IFdbReadOnlyTransaction

Namespace: FoundationDB.Client · interface

Implements: IDisposable

Transaction that allows read operations

Properties

Cancellation

CancellationToken Cancellation { get; }

Cancellation Token linked to the lifetime of the transaction

Will be triggered if the transaction is aborted or disposed

Context

FdbOperationContext Context { get; }

Context of this transaction.

Database

IFdbDatabase Database { get; }

Database of this transaction

Id

int Id { get; }

Local id of the transaction

This id is only guaranteed unique inside the current AppDomain or process and is reset on every restart. It should only be used for diagnostics and/or logging.

IsSnapshot

bool IsSnapshot { get; }

If true, the transaction is operating in Snapshot mode

Log

FdbTransactionLog Log { get; }

Log of all operations performed on this transaction (if logging was enabled on the database or transaction)

Options

IFdbTransactionOptions Options { get; }

Helper that can set options for this transaction

Snapshot

IFdbReadOnlyTransaction Snapshot { get; }

Return a Snapshot version of this transaction, or the transaction itself it is already operating in Snapshot mode.

Tenant

IFdbTenant Tenant { get; }

Tenant of this transaction

If , the transaction can interact with the complete keyspace

Methods

Annotate

void Annotate(string comment)

Add a comment to the transaction log

comment — Line of text that will be added to the log

This method does nothing if logging is disabled. To prevent unnecessary allocations, you may check first

tr.Annotate("Reticulating splines...");

void Annotate(ref InvariantInterpolatedStringHandler comment)

Add a comment to the transaction log

comment — Line of text that will be added to the log

This method does nothing if logging is disabled. To prevent unnecessary allocations, you may check first

tr.Annotate($"Reticulated {splines.Count} splines");

Cancel

void Cancel()

Cancels the transaction. All pending or future uses of the transaction will return a TransactionCancelled error code. The transaction can be used again after it is reset.

CheckValueAsync

Task<(FdbValueCheckResult, Slice)> CheckValueAsync(ReadOnlySpan<byte> key, Slice expected)

Check if the value from the database snapshot represented by the current transaction is equal to some expected value.

key — Key to be looked up in the database
expected — Expected value for this key

Returns: Task that will return the value of the key if it is found, Slice.Nil if the key does not exist, or an exception

EnsureCanRead

void EnsureCanRead()

Ensure that the transaction is in a valid state for issuing read operations.

GetAddressesForKeyAsync

Task<string[]> GetAddressesForKeyAsync(ReadOnlySpan<byte> key)

Returns a list of public network addresses as strings, one for each of the storage servers responsible for storing key and its associated value

key — Name of the key whose location is to be queried.

Returns: Task that will return an array of strings, or an exception

Depending on the API level or whether database option is set, the returned string may or may not include the port numbers

GetAsync

Task<Slice> GetAsync(ReadOnlySpan<byte> key)

Reads a value from the database snapshot represented by the current transaction.

key — Key to be looked up in the database

Returns: Task that will return the value of the key if it is found, Slice.Nil if the key does not exist, or an exception

Task<TResult> GetAsync<TResult>(ReadOnlySpan<byte> key, FdbValueDecoder<TResult> valueDecoder)

Reads a value from the database snapshot represented by the current transaction.

key — Key to be looked up in the database
valueDecoder — Decoder that will extract the result from the value found in the database

Returns: Task that will return the value of the key if it is found, Slice.Nil if the key does not exist, or an exception

Task<TResult> GetAsync<TValueState, TResult>(ReadOnlySpan<byte> key, TValueState valueState, FdbValueDecoder<TValueState, TResult> valueDecoder)

Reads a value from the database snapshot represented by the current transaction.

key — Key to be looked up in the database
valueState — State that will be forwarded to the valueDecoder
valueDecoder — Decoder that will extract the result from the value found in the database

Returns: Task that will return the value of the key if it is found, Slice.Nil if the key does not exist, or an exception

GetEstimatedRangeSizeBytesAsync

Task<long> GetEstimatedRangeSizeBytesAsync(ReadOnlySpan<byte> beginKey, ReadOnlySpan<byte> endKey)

Returns an estimated byte size of the key range.

beginKey — Name of the key of the start of the range
endKey — Name of the key of the end of the range

Returns: Task that will return an estimated byte size of the key range, or an exception

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.

GetKeyAsync

Task<Slice> GetKeyAsync(KeySelector selector)

Resolves a key selector against the keys in the database snapshot represented by the current transaction.

selector — Key selector to resolve

Returns: Task that will return the key matching the selector, or an exception

Task<Slice> GetKeyAsync(KeySpanSelector selector)

Resolves a key selector against the keys in the database snapshot represented by the current transaction.

selector — Key selector to resolve

Returns: Task that will return the key matching the selector, or an exception

GetKeysAsync

Task<Slice[]> GetKeysAsync(ReadOnlySpan<KeySelector> selectors)

Resolves several key selectors against the keys in the database snapshot represented by the current transaction.

selectors — Key selectors to resolve

Returns: Task that will return an array of keys matching the selectors, or an exception

GetMetadataVersionKeyAsync

Task<VersionStamp?> GetMetadataVersionKeyAsync(Slice key = null)

Safely read a key containing a VersionStamp representing the version of some metadata or schema information stored in the database.

key — Key to read. If Nil, read the global \xff/metadataVersion key

Either the current value of the key, or if the key has already changed in this transaction

GetRange

IFdbKeyValueRangeQuery GetRange(KeySelector beginInclusive, KeySelector endExclusive, FdbRangeOptions options = null)

Creates a new range query that will read all key-value pairs in the database snapshot represented by the transaction

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)

Returns: Range query that, once executed, will return all the key-value pairs matching the providing selector pair

IFdbRangeQuery<TResult> GetRange<TResult>(KeySelector beginInclusive, KeySelector endExclusive, Func<KeyValuePair<Slice, Slice>, TResult> selector, FdbRangeOptions options = null)

Creates a new range query that will read all key-value pairs in the database snapshot represented by the transaction, and transform them into a result of type TResult

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
selector — Selector used to convert each key-value pair into an element of type TResult
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)

Returns: Range query that, once executed, will return all the key-value pairs matching the providing selector pair

IFdbRangeQuery<TResult> GetRange<TState, TResult>(KeySelector beginInclusive, KeySelector endExclusive, TState state, FdbKeyValueDecoder<TState, TResult> selector, FdbRangeOptions options = null)

Creates a new range query that will read all key-value pairs in the database snapshot represented by the transaction, and transform them into a result of type TResult

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
state — State that will be forwarded to the selector
selector — Selector used to convert each key-value pair into an element of type TResult
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)

Returns: Range query that, once executed, will return all the key-value pairs matching the providing selector pair

GetRangeAsync

Task<FdbRangeChunk> GetRangeAsync(KeySelector beginInclusive, KeySelector endExclusive, FdbRangeOptions options = null, int iteration = 0)

Reads all key-value pairs in the database snapshot represented by transaction (potentially limited by Limit, TargetBytes, or Mode) which have a key lexicographically greater than or equal to the key resolved by the beginning key selector and lexicographically less than the key resolved by the end key selector.

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)
iteration — If streaming mode is Iterator, this parameter should start at 1 and be incremented by 1 for each successive call while reading this range. In all other cases it is ignored.

Returns: Chunk of results

Task<FdbRangeChunk> GetRangeAsync(KeySpanSelector beginInclusive, KeySpanSelector endExclusive, FdbRangeOptions options = null, int iteration = 0)

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)
iteration — If streaming mode is Iterator, this parameter should start at 1 and be incremented by 1 for each successive call while reading this range. In all other cases it is ignored.

Returns: Chunk of results

Task<FdbRangeChunk<TResult>> GetRangeAsync<TState, TResult>(KeySelector beginInclusive, KeySelector endExclusive, TState state, FdbKeyValueDecoder<TState, TResult> decoder, FdbRangeOptions options = null, int iteration = 0)

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
state — State that will be forwarded to the decoder
decoder — Decoder that will extract the result from the value found in the database
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)
iteration — If streaming mode is Iterator, this parameter should start at 1 and be incremented by 1 for each successive call while reading this range. In all other cases it is ignored.

Returns: Chunk of results

Task<FdbRangeChunk<TResult>> GetRangeAsync<TState, TResult>(KeySpanSelector beginInclusive, KeySpanSelector endExclusive, TState state, FdbKeyValueDecoder<TState, TResult> decoder, FdbRangeOptions options = null, int iteration = 0)

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
state — State that will be forwarded to the decoder
decoder — Decoder that will extract the result from the value found in the database
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)
iteration — If streaming mode is Iterator, this parameter should start at 1 and be incremented by 1 for each successive call while reading this range. In all other cases it is ignored.

Returns: Chunk of results

GetRangeSplitPointsAsync

Task<Slice[]> GetRangeSplitPointsAsync(ReadOnlySpan<byte> beginKey, ReadOnlySpan<byte> endKey, long chunkSize)

Returns a list of keys that can split the given range into (roughly) equally sized chunks based on chunkSize.

beginKey — Name of the key of the start of the range
endKey — Name of the key of the end of the range
chunkSize — Size of chunks that will be used to split the range

Returns: Task that will return an array of keys that split the range in equally sized chunks, or an exception

The returned split points contain the start key and end key of the given range

GetReadStatistics

(int, long) GetReadStatistics()

Returns the number of keys read byte this transaction, as well as their total size

GetReadVersionAsync

Task<long> GetReadVersionAsync()

Returns this transaction snapshot read version.

GetValuesAsync

Task<Slice[]> GetValuesAsync(ReadOnlySpan<Slice> keys)

Reads several values from the database snapshot represented by the current transaction

keys — Keys to be looked up in the database

Returns: Task that will return an array of values, or an exception. Each item in the array will contain the value of the key at the same index in keys, or Slice.Nil if that key does not exist.

Task GetValuesAsync<TResult>(ReadOnlySpan<Slice> keys, Memory<TResult> results, FdbValueDecoder<TResult> valueDecoder)

Reads several values from the database snapshot represented by the current transaction

keys — Keys to be looked up in the database
results — Buffer where the results will be written to (must be at least as large as keys). Each entry will contain the decoded value of the key at the same index in keys.
valueDecoder — Decoder that will extract the result from the value found in the database.

Returns: Task that will complete once all the keys have been read and values decoded.

Task GetValuesAsync<TValueState, TResult>(ReadOnlySpan<Slice> keys, Memory<TResult> results, TValueState valueState, FdbValueDecoder<TValueState, TResult> valueDecoder)

Reads several values from the database snapshot represented by the current transaction

keys — Keys to be looked up in the database
results — Buffer where the results will be written to (must be at least as large as keys). Each entry will contain the decoded value of the key at the same index in keys.
valueState — State that will be forwarded to the valueDecoder
valueDecoder — Decoder that will extract the result from the value found in the database.

Returns: Task that will complete once all the keys have been read and values decoded.

IsLogged

bool IsLogged()

Return true if logging is enabled on this transaction

If logging is enabled, the transaction will track all the operations performed by this transaction until it completes. The log can be accessed via the property. Comments can be added via the method.

OnErrorAsync

Task OnErrorAsync(FdbError code)

Implements the recommended retry and back-off behavior for a transaction. This function knows which of the error codes generated by other query functions represent temporary error conditions and which represent application errors that should be handled by the application. It also implements an exponential back-off strategy to avoid swamping the database cluster with excessive retries when there is a high level of conflict between transactions.

code — FdbError code thrown by the previous command

Returns: Returns a task that completes if the operation can be safely retried, or that rethrows the original exception if the operation is not retry-able.

Reset

void Reset()

Reset transaction to its initial state.

This is similar to disposing the transaction and recreating a new one. The only state that persists through a transaction reset is that which is related to the back-off logic used by OnErrorAsync()

SetReadVersion

void SetReadVersion(long version)

Sets the snapshot read version used by a transaction. This is not needed in simple cases.

version — Read version to use in this transaction

If the given version is too old, subsequent reads will fail with error_code_past_version; if it is too new, subsequent reads may be delayed indefinitely and/or fail with error_code_future_version. If any of Get*() methods have been called on this transaction already, the result is undefined.

StopLogging

void StopLogging()

If logging was previously enabled on this transaction, clear the log and stop logging any new operations

Any log handler attached to this transaction will not be called

VisitRangeAsync

Task<long> VisitRangeAsync<TState>(KeySelector beginInclusive, KeySelector endExclusive, TState state, FdbKeyValueAction<TState> visitor, FdbRangeOptions options = null)

Visits all key-value pairs in the database snapshot represent by the transaction

beginInclusive — key selector defining the beginning of the range
endExclusive — key selector defining the end of the range
state — State that will be forwarded to the visitor
visitor — Lambda called for each key-value pair, in order.
options — Optional query options (Limit, TargetBytes, Mode, Reverse, ...)

Returns: Number of key/value pairs visited