com.apple.foundationdb

Interface ReadTransaction

All Superinterfaces:

ReadTransactionContext

All Known Subinterfaces:

Transaction

public interface ReadTransaction
extends ReadTransactionContext

A read-only subset of a FoundationDB Transaction. This is the interface that Transaction's snapshot presents.

Note: Client must call Transaction.commit() and wait on the result on all transactions, even ones that only read. This is done automatically when using the retry loops from Database.run(java.util.function.Function). This is explained more in the intro to Transaction.

See Also:

Transaction

Field Summary

Fields

Modifier and Type	Field and Description
static int	ROW_LIMIT_UNLIMITED When passed to a getRange() call that takes a limit parameter, indicates that the query should return unlimited rows.

Method Summary

Modifier and Type	Method and Description
boolean	addReadConflictKeyIfNotSnapshot(byte[] key) Adds the read conflict range that this ReadTransaction would have added as if it had read the given key.
boolean	addReadConflictRangeIfNotSnapshot(byte[] keyBegin, byte[] keyEnd) Adds the read conflict range that this ReadTransaction 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 specified KeySelector.
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<java.lang.Long>	getReadVersion() Gets the version at which the reads for this Transaction 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 a Transaction
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 a getRange() call that takes a limit 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 this ReadTransaction.
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 this Transaction 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 this ReadTransaction 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 and false otherwise

See Also:

Transaction.addReadConflictRange(byte[], byte[])

addReadConflictKeyIfNotSnapshot

boolean addReadConflictKeyIfNotSnapshot(byte[] key)

Adds the read conflict range that this ReadTransaction 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 and false otherwise

See Also:

Transaction.addReadConflictKey(byte[])

get

java.util.concurrent.CompletableFuture<byte[]> get(byte[] key)

Gets a value from the database. The call will return null 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 specified KeySelector. 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. Invoking setReadYourWritesDisable 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 by KeySelectors, with the begin KeySelector inclusive and the end KeySelector 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 by KeySelectors, with the begin KeySelector inclusive and the end KeySelector 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. Pass ROW_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 by KeySelectors, with the begin KeySelector inclusive and the end KeySelector 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. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 by KeySelectors, with the begin KeySelector inclusive and the end KeySelector 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. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 the ITERATOR streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that the AsyncIterable.asList() function will fetch all results in the range. If a limit is specified, the EXACT streaming mode will be used, and otherwise it will use WANT_ALL. To achieve comparable performance when iterating over an entire range without using AsyncIterable.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 by byte[] 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 by byte[] 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. Pass ROW_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 by byte[] 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. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 by byte[] 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. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 the ITERATOR streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that the AsyncIterable.asList() function will fetch all results in the range. If a limit is specified, the EXACT streaming mode will be used, and otherwise it will use WANT_ALL. To achieve comparable performance when iterating over an entire range without using AsyncIterable.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 by byte[] arrays, with the begin key inclusive and the end key exclusive. Ranges are returned from calls to Tuple.range() and Range.startsWith(byte[]).

Note: users of older version of the API should replace old calls to getRangeStartsWith( k ) with getRange(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 by byte[] arrays, with the begin key inclusive and the end key exclusive. Ranges are returned from calls to Tuple.range() and Range.startsWith(byte[]).

Note: users of older version of the API should replace old calls to getRangeStartsWith( k ) with getRange(Range.startsWith( k ))

Parameters:

range - the range of keys to return

limit - the maximum number of results to return. Limits results to the first keys in the range. Pass ROW_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 by byte[] arrays, with the begin key inclusive and the end key exclusive. Ranges are returned from calls to Tuple.range() and Range.startsWith(byte[]).

Note: users of older version of the API should replace old calls to getRangeStartsWith( k ) with getRange(Range.startsWith( k ))

Parameters:

range - the range of keys to return

limit - the maximum number of results to return. Limits results to the first keys in the range. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 by byte[] arrays, with the begin key inclusive and the end key exclusive. Ranges are returned from calls to Tuple.range() and Range.startsWith(byte[]).

Note: users of older version of the API should replace old calls to getRangeStartsWith( k ) with getRange(Range.startsWith( k ))

Parameters:

range - the range of keys to return

limit - the maximum number of results to return. Limits results to the first keys in the range. Pass ROW_LIMIT_UNLIMITED if this query should not limit the number of results. If reverse is true 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 the ITERATOR streaming mode, the query is automatically modified to fetch results in larger batches. This is done because it is known in advance that the AsyncIterable.asList() function will fetch all results in the range. If a limit is specified, the EXACT streaming mode will be used, and otherwise it will use WANT_ALL. To achieve comparable performance when iterating over an entire range without using AsyncIterable.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.

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.

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 a Transaction

Returns:

a set of transaction-specific options affecting this Transaction