Interface ReadTransaction
-
- All Superinterfaces:
ReadTransactionContext
- All Known Subinterfaces:
Transaction
public interface ReadTransaction extends ReadTransactionContext
A read-only subset of a FoundationDBTransaction
. This is the interface thatTransaction
'ssnapshot
presents.
Note: Client must callTransaction.commit()
and wait on the result on all transactions, even ones that only read. This is done automatically when using the retry loops fromDatabase.run(java.util.function.Function)
. This is explained more in the intro toTransaction
.- See Also:
Transaction
-
-
Field Summary
Fields Modifier and Type Field Description static int
ROW_LIMIT_UNLIMITED
When passed to agetRange()
call that takes alimit
parameter, indicates that the query should return unlimited rows.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
addReadConflictKeyIfNotSnapshot(byte[] key)
Adds the read conflict range that thisReadTransaction
would have added as if it had read the given key.boolean
addReadConflictRangeIfNotSnapshot(byte[] keyBegin, byte[] keyEnd)
Adds the read conflict range that thisReadTransaction
would have added as if it had read the given key range.java.util.concurrent.CompletableFuture<byte[]>
get(byte[] key)
Gets a value from the database.java.util.concurrent.CompletableFuture<java.lang.Long>
getEstimatedRangeSizeBytes(byte[] begin, byte[] end)
Gets an estimate for the number of bytes stored in the given range.java.util.concurrent.CompletableFuture<java.lang.Long>
getEstimatedRangeSizeBytes(Range range)
Gets an estimate for the number of bytes stored in the given range.java.util.concurrent.CompletableFuture<byte[]>
getKey(KeySelector selector)
Returns the key referenced by the specifiedKeySelector
.AsyncIterable<MappedKeyValue>
getMappedRange(KeySelector begin, KeySelector end, byte[] mapper, int limit, boolean reverse, StreamingMode mode)
WARNING: This feature is considered experimental at this time.AsyncIterable<KeyValue>
getRange(byte[] begin, byte[] end)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(byte[] begin, byte[] end, int limit)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(byte[] begin, byte[] end, int limit, boolean reverse)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(byte[] begin, byte[] end, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(KeySelector begin, KeySelector end)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(KeySelector begin, KeySelector end, int limit)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(KeySelector begin, KeySelector end, int limit, boolean reverse)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(KeySelector begin, KeySelector end, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(Range range)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(Range range, int limit)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(Range range, int limit, boolean reverse)
Gets an ordered range of keys and values from the database.AsyncIterable<KeyValue>
getRange(Range range, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database.java.util.concurrent.CompletableFuture<KeyArrayResult>
getRangeSplitPoints(byte[] begin, byte[] end, long chunkSize)
Gets a list of keys that can split the given range into (roughly) equally sized chunks based onchunkSize
.java.util.concurrent.CompletableFuture<KeyArrayResult>
getRangeSplitPoints(Range range, long chunkSize)
Gets a list of keys that can split the given range into (roughly) equally sized chunks based onchunkSize
Note: the returned split points contain the start key and end key of the given range.java.util.concurrent.CompletableFuture<java.lang.Long>
getReadVersion()
Gets the version at which the reads for thisTransaction
will access the database.boolean
isSnapshot()
Gets whether this transaction is a snapshot view of the database.TransactionOptions
options()
Returns a set of options that can be set on aTransaction
void
setReadVersion(long version)
Directly sets the version of the database at which to execute reads.ReadTransaction
snapshot()
Return a special-purpose, read-only view of the database.-
Methods inherited from interface com.apple.foundationdb.ReadTransactionContext
getExecutor, read, readAsync
-
-
-
-
Field Detail
-
ROW_LIMIT_UNLIMITED
static final int ROW_LIMIT_UNLIMITED
When passed to agetRange()
call that takes alimit
parameter, indicates that the query should return unlimited rows.- See Also:
- Constant Field Values
-
-
Method Detail
-
isSnapshot
boolean isSnapshot()
Gets whether this transaction is a snapshot view of the database. In other words, this returns whether read conflict ranges are omitted for any reads done through thisReadTransaction
.
For more information about how to use snapshot reads correctly, see Using snapshot reads.- Returns:
- whether this is a snapshot view of the database with relaxed isolation properties
- See Also:
snapshot()
-
snapshot
ReadTransaction snapshot()
Return a special-purpose, read-only view of the database. Reads done through this interface are known as "snapshot reads". Snapshot reads selectively relax FoundationDB's isolation property, reducing Transaction conflicts but making reasoning about concurrency harder.
For more information about how to use snapshot reads correctly, see Using snapshot reads.- Returns:
- a read-only view of this
ReadTransaction
with relaxed isolation properties
-
getReadVersion
java.util.concurrent.CompletableFuture<java.lang.Long> getReadVersion()
Gets the version at which the reads for thisTransaction
will access the database.- Returns:
- the version for database reads
-
setReadVersion
void setReadVersion(long version)
Directly sets the version of the database at which to execute reads. The normal operation of a transaction is to determine an appropriately recent version; this call overrides that behavior. If the version is set too far in the past,transaction_too_old
errors will be thrown from read operations. Infrequently used.- Parameters:
version
- the version at which to read from the database
-
addReadConflictRangeIfNotSnapshot
boolean addReadConflictRangeIfNotSnapshot(byte[] keyBegin, byte[] keyEnd)
Adds the read conflict range that thisReadTransaction
would have added as if it had read the given key range. If this is a snapshot view of the database, this will not add the conflict range. This mirrors how reading a range through a snapshot view of the database does not add a conflict range for the read keys.- Parameters:
keyBegin
- the first key in the range (inclusive)keyEnd
- the last key in the range (exclusive)- Returns:
true
if the read conflict range was added andfalse
otherwise- See Also:
Transaction.addReadConflictRange(byte[], byte[])
-
addReadConflictKeyIfNotSnapshot
boolean addReadConflictKeyIfNotSnapshot(byte[] key)
Adds the read conflict range that thisReadTransaction
would have added as if it had read the given key. If this is a snapshot view of the database, this will not add the conflict range. This mirrors how reading a key through a snapshot view of the database does not add a conflict range for the read key.- Parameters:
key
- the key to add to the read conflict range set (it this is not a snapshot view of the database)- Returns:
true
if the read conflict key was added andfalse
otherwise- See Also:
Transaction.addReadConflictKey(byte[])
-
get
java.util.concurrent.CompletableFuture<byte[]> get(byte[] key)
Gets a value from the database. The call will returnnull
if the key is not present in the database.- Parameters:
key
- the key whose value to fetch from the database- Returns:
- a
CompletableFuture
which will be set to the value corresponding to the key or to null if the key does not exist.
-
getKey
java.util.concurrent.CompletableFuture<byte[]> getKey(KeySelector selector)
Returns the key referenced by the specifiedKeySelector
. By default, the key is cached for the duration of the transaction, providing a potential performance benefit. However, the value of the key is also retrieved, using network bandwidth. InvokingsetReadYourWritesDisable
will avoid both the caching and the increased network bandwidth.- Parameters:
selector
- the relative key location to resolve- Returns:
- a
CompletableFuture
which will be set to an absolute database key - See Also:
KeySelector
-
getRange
AsyncIterable<KeyValue> getRange(KeySelector begin, KeySelector end)
Gets an ordered range of keys and values from the database. The begin and end keys are specified byKeySelector
s, with the beginKeySelector
inclusive and the endKeySelector
exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(KeySelector begin, KeySelector end, int limit)
Gets an ordered range of keys and values from the database. The begin and end keys are specified byKeySelector
s, with the beginKeySelector
inclusive and the endKeySelector
exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(KeySelector begin, KeySelector end, int limit, boolean reverse)
Gets an ordered range of keys and values from the database. The begin and end keys are specified byKeySelector
s, with the beginKeySelector
inclusive and the endKeySelector
exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(KeySelector begin, KeySelector end, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database. The begin and end keys are specified byKeySelector
s, with the beginKeySelector
inclusive and the endKeySelector
exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.mode
- provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.When converting the result of this query to a list using
AsyncIterable.asList()
with theITERATOR
streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that theAsyncIterable.asList()
function will fetch all results in the range. If a limit is specified, theEXACT
streaming mode will be used, and otherwise it will useWANT_ALL
. To achieve comparable performance when iterating over an entire range without usingAsyncIterable.asList()
, the same streaming mode would need to be used.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(byte[] begin, byte[] end)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(byte[] begin, byte[] end, int limit)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(byte[] begin, byte[] end, int limit, boolean reverse)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(byte[] begin, byte[] end, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)limit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.mode
- provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.When converting the result of this query to a list using
AsyncIterable.asList()
with theITERATOR
streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that theAsyncIterable.asList()
function will fetch all results in the range. If a limit is specified, theEXACT
streaming mode will be used, and otherwise it will useWANT_ALL
. To achieve comparable performance when iterating over an entire range without usingAsyncIterable.asList()
, the same streaming mode would need to be used.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(Range range)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.Range
s are returned from calls toTuple.range()
andRange.startsWith(byte[])
.
Note: users of older version of the API should replace old calls togetRangeStartsWith( k )
withgetRange(Range.startsWith( k ))
- Parameters:
range
- the range of keys to return- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(Range range, int limit)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.Range
s are returned from calls toTuple.range()
andRange.startsWith(byte[])
.
Note: users of older version of the API should replace old calls togetRangeStartsWith( k )
withgetRange(Range.startsWith( k ))
- Parameters:
range
- the range of keys to returnlimit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(Range range, int limit, boolean reverse)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.Range
s are returned from calls toTuple.range()
andRange.startsWith(byte[])
.
Note: users of older version of the API should replace old calls togetRangeStartsWith( k )
withgetRange(Range.startsWith( k ))
- Parameters:
range
- the range of keys to returnlimit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getRange
AsyncIterable<KeyValue> getRange(Range range, int limit, boolean reverse, StreamingMode mode)
Gets an ordered range of keys and values from the database. The begin and end keys are specified bybyte[]
arrays, with the begin key inclusive and the end key exclusive.Range
s are returned from calls toTuple.range()
andRange.startsWith(byte[])
.
Note: users of older version of the API should replace old calls togetRangeStartsWith( k )
withgetRange(Range.startsWith( k ))
- Parameters:
range
- the range of keys to returnlimit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.mode
- provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.When converting the result of this query to a list using
AsyncIterable.asList()
with theITERATOR
streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that theAsyncIterable.asList()
function will fetch all results in the range. If a limit is specified, theEXACT
streaming mode will be used, and otherwise it will useWANT_ALL
. To achieve comparable performance when iterating over an entire range without usingAsyncIterable.asList()
, the same streaming mode would need to be used.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getMappedRange
AsyncIterable<MappedKeyValue> getMappedRange(KeySelector begin, KeySelector end, byte[] mapper, int limit, boolean reverse, StreamingMode mode)
WARNING: This feature is considered experimental at this time. It is only allowed when using snapshot isolation AND disabling read-your-writes.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)mapper
- TODOlimit
- the maximum number of results to return. Limits results to the first keys in the range. PassROW_LIMIT_UNLIMITED
if this query should not limit the number of results. Ifreverse
istrue
rows will be limited starting at the end of the range.reverse
- return results starting at the end of the range in reverse order. Reading ranges in reverse is supported natively by the database and should have minimal extra cost.mode
- provide a hint about how the results are to be used. This can provide speed improvements or efficiency gains based on the caller's knowledge of the upcoming access pattern.When converting the result of this query to a list using
AsyncIterable.asList()
with theITERATOR
streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that theAsyncIterable.asList()
function will fetch all results in the range. If a limit is specified, theEXACT
streaming mode will be used, and otherwise it will useWANT_ALL
. To achieve comparable performance when iterating over an entire range without usingAsyncIterable.asList()
, the same streaming mode would need to be used.- Returns:
- a handle to access the results of the asynchronous call
- See Also:
KeySelector
,AsyncIterator
-
getEstimatedRangeSizeBytes
java.util.concurrent.CompletableFuture<java.lang.Long> getEstimatedRangeSizeBytes(byte[] begin, byte[] end)
Gets an estimate for the number of bytes stored in the given range. Note: the estimated size is calculated based on the sampling done by FDB server. The sampling algorithm works roughly in this way: the larger the key-value pair is, the more likely it would be sampled and the more accurate its sampled size would be. And due to that reason it is recommended to use this API to query against large ranges for accuracy considerations. For a rough reference, if the returned size is larger than 3MB, one can consider the size to be accurate.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)- Returns:
- a handle to access the results of the asynchronous call
-
getEstimatedRangeSizeBytes
java.util.concurrent.CompletableFuture<java.lang.Long> getEstimatedRangeSizeBytes(Range range)
Gets an estimate for the number of bytes stored in the given range. Note: the estimated size is calculated based on the sampling done by FDB server. The sampling algorithm works roughly in this way: the larger the key-value pair is, the more likely it would be sampled and the more accurate its sampled size would be. And due to that reason it is recommended to use this API to query against large ranges for accuracy considerations. For a rough reference, if the returned size is larger than 3MB, one can consider the size to be accurate.- Parameters:
range
- the range of the keys- Returns:
- a handle to access the results of the asynchronous call
-
getRangeSplitPoints
java.util.concurrent.CompletableFuture<KeyArrayResult> getRangeSplitPoints(byte[] begin, byte[] end, long chunkSize)
Gets a list of keys that can split the given range into (roughly) equally sized chunks based onchunkSize
. Note: the returned split points contain the start key and end key of the given range.- Parameters:
begin
- the beginning of the range (inclusive)end
- the end of the range (exclusive)- Returns:
- a handle to access the results of the asynchronous call
-
getRangeSplitPoints
java.util.concurrent.CompletableFuture<KeyArrayResult> getRangeSplitPoints(Range range, long chunkSize)
Gets a list of keys that can split the given range into (roughly) equally sized chunks based onchunkSize
Note: the returned split points contain the start key and end key of the given range.- Parameters:
range
- the range of the keys- Returns:
- a handle to access the results of the asynchronous call
-
options
TransactionOptions options()
Returns a set of options that can be set on aTransaction
- Returns:
- a set of transaction-specific options affecting this
Transaction
-
-