IFdbTransactionHandler

Namespace: FoundationDB.Client.Core · interface

Implements: IDisposable

Basic API for FoundationDB transactions

Properties

IsClosed

bool IsClosed { get; }

Checks if this transaction handler is closed

Size

long Size { get; }

Returns the estimated payload size of the transaction (including keys and values)

Methods

AddConflictRange

void AddConflictRange(ReadOnlySpan<byte> beginKeyInclusive, ReadOnlySpan<byte> endKeyExclusive, FdbConflictRangeType type)

Adds a conflict range to a transaction without performing the associated read or write.

• beginKeyInclusive — Key specifying the beginning of the conflict range. The key is included
• endKeyExclusive — Key specifying the end of the conflict range. The key is excluded
• type — One of the FDBConflictRangeType values indicating what type of conflict range is being set.

Atomic

void Atomic(ReadOnlySpan<byte> key, ReadOnlySpan<byte> param, FdbMutationType mutation)

Modify the database snapshot represented by this transaction to perform the operation indicated by mutation with operand param to the value stored by the given key.

• key — Name of the key whose value is to be mutated.
• param — Parameter with which the atomic operation will mutate the value associated with key_name.
• mutation — Type of mutation that should be performed on the key

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

ValueTask<(FdbValueCheckResult, Slice)> CheckValueAsync(ReadOnlySpan<byte> key, Slice expected, bool snapshot, CancellationToken ct)

Checks the value of a key in the database snapshot is equal to the expected value.

• key — Key to check
• expected — Expected value of the key
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

Returns: Task that will return a pair of FdbValueCheckResult and the actual value of the key in the database.

Clear

void Clear(ReadOnlySpan<byte> key)

Modify the database snapshot represented by this transaction to remove the given key from the database. If the key was not previously present in the database, there is no effect.

• key — Name of the key to be removed from the database.

ClearRange

void ClearRange(ReadOnlySpan<byte> beginKeyInclusive, ReadOnlySpan<byte> endKeyExclusive)

Modify the database snapshot represented by this transaction to remove all keys (if any) which are lexicographically greater than or equal to the given begin key and lexicographically less than the given end_key. Sets and clears affect the actual database only if transaction is later committed with CommitAsync().

• beginKeyInclusive — Name of the key specifying the beginning of the range to clear.
• endKeyExclusive — Name of the key specifying the end of the range to clear.

CommitAsync

Task CommitAsync(CancellationToken ct)

Attempts to commit the sets and clears previously applied to the database snapshot represented by this transaction to the actual database. The commit may or may not succeed – in particular, if a conflicting transaction previously committed, then the commit must fail in order to preserve transactional isolation. If the commit does succeed, the transaction is durably committed to the database and all subsequently started transactions will observe its effects.

• ct — Token used to cancel the operation from the outside

Returns: Task that succeeds if the transaction was committed successfully, or fails if the transaction failed to commit.

As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, CommitAsync() will throw CommitUnknownResult error. The OnErrorAsync() function treats this error as retry-able, so retry loops that don't check for CommitUnknownResult could execute the transaction twice. In these cases, you must consider the idempotence of the transaction.

GetAddressesForKeyAsync

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

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.
• ct — Token used to cancel the operation from the outside

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

GetApproximateSizeAsync

Task<long> GetApproximateSizeAsync(CancellationToken ct)

Returns the approximate size of the transaction's mutations

GetAsync

Task<Slice> GetAsync(ReadOnlySpan<byte> key, bool snapshot, CancellationToken ct)

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

• key — Key to be looked up in the database
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation

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, bool snapshot, FdbValueDecoder<TResult> decoder, CancellationToken ct)

Reads a value from the database snapshot represented by the current transaction, and return the converted value.

• key — Key to be looked up in the database
• snapshot — Set to true for snapshot reads
• decoder — Handler that will convert the result of the read, into a TResult instance.
• ct — Token used to cancel the operation

Returns: Task that will return the converted value of the key, or an exception

Task<TResult> GetAsync<TState, TResult>(ReadOnlySpan<byte> key, bool snapshot, TState state, FdbValueDecoder<TState, TResult> decoder, CancellationToken ct)

Reads a value from the database snapshot represented by the current transaction, and return the converted value.

• key — Key to be looked up in the database
• snapshot — Set to true for snapshot reads
• state — Opaque state provided by the caller, and passed to the decoder
• decoder — Handler that will convert the result of the read operation, into a TResult instance.
• ct — Token used to cancel the operation

Returns: Task that will return the converted value of the key, or an exception

GetCommittedVersion

long GetCommittedVersion()

Retrieves the database version number at which a given transaction was committed.

CommitAsync() must have been called on this transaction and the resulting task must have completed successfully before this function is called, or the behavior is undefined. Read-only transactions do not modify the database when committed and will have a committed version of -1. Keep in mind that a transaction which reads keys and then sets them to their current values may be optimized to a read-only transaction.

GetEstimatedRangeSizeBytesAsync

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

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
• ct — Token used to cancel the operation from the outside

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(KeySpanSelector selector, bool snapshot, CancellationToken ct)

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

• selector — Key selector to resolve
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

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

GetKeysAsync

Task<Slice[]> GetKeysAsync(ReadOnlySpan<KeySelector> selectors, bool snapshot, CancellationToken ct)

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

• selectors — Key selectors to resolve
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

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

GetRangeAsync

Task<FdbRangeChunk> GetRangeAsync(KeySpanSelector beginInclusive, KeySpanSelector endExclusive, FdbRangeOptions options, int iteration, bool snapshot, CancellationToken ct)

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 Begin 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 — Range read options
• iteration — If the streaming mode is set to Iterator (default), 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.
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

Task<FdbRangeChunk<TResult>> GetRangeAsync<TState, TResult>(KeySpanSelector beginInclusive, KeySpanSelector endExclusive, bool snapshot, TState state, FdbKeyValueDecoder<TState, TResult> decoder, FdbRangeOptions options, int iteration, CancellationToken ct)

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 Begin 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
• snapshot — Set to true for snapshot reads
• state — Opaque state provided by the caller, and passed to the decoder
• decoder — Handler that will convert the result of the read, into a TResult instance.
• options — Range read options
• iteration — If the streaming mode is set to Iterator (default), 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.
• ct — Token used to cancel the operation from the outside

GetRangeSplitPointsAsync

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

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
• ct — Token used to cancel the operation from the outside

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, as well as their total size

GetReadVersionAsync

Task<long> GetReadVersionAsync(CancellationToken ct)

Returns this transaction snapshot read version.

GetValuesAsync

Task<Slice[]> GetValuesAsync(ReadOnlySpan<Slice> keys, bool snapshot, CancellationToken ct)

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

• keys — Keys to be looked up in the database
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

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 Nil if that key does not exist.

Task<long> GetValuesAsync<TResult>(ReadOnlySpan<Slice> keys, Memory<TResult> values, FdbValueDecoder<TResult> decoder, bool snapshot, CancellationToken ct)

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

• keys — Keys to be looked up in the database
• values — Buffer, provided by the caller, that will receive the decoded values
• decoder — Handler that will convert the result of the read operation, into a TResult instance.
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

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 Nil if that key does not exist.

Task<long> GetValuesAsync<TState, TResult>(ReadOnlySpan<Slice> keys, Memory<TResult> values, TState state, FdbValueDecoder<TState, TResult> decoder, bool snapshot, CancellationToken ct)

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

• keys — Keys to be looked up in the database
• values — Buffer, provided by the caller, that will receive the decoded values
• state — Opaque state provided by the caller, and passed to the decoder
• decoder — Handler that will convert the result of the read operation, into a TResult instance.
• snapshot — Set to true for snapshot reads
• ct — Token used to cancel the operation from the outside

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 Nil if that key does not exist.

GetVersionStampAsync

Task<VersionStamp> GetVersionStampAsync(CancellationToken ct)

Returns the VersionStamp which was used by VersionStamps operations in this transaction.

GetWriteStatistics

(int, long) GetWriteStatistics()

Returns the number of keys changed, as well as the estimated payload size

OnErrorAsync

Task OnErrorAsync(FdbError code, CancellationToken ct)

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
• ct — Token used to cancel the operation from the outside

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()

Set

void Set(ReadOnlySpan<byte> key, ReadOnlySpan<byte> value)

Modify the database snapshot represented by transaction to change the given key to have the given value. If the given key was not previously present in the database it is inserted. The modification affects the actual database only if transaction is later committed with CommitAsync().

• key — Name of the key to be inserted into the database.
• value — Value to be inserted into the database.

SetOption

void SetOption(FdbTransactionOption option, ReadOnlySpan<byte> data)

Set an option on this transaction

• option — Option to set
• data — Parameter value (empty for parameter-less options)

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.

VisitRangeAsync

Task<FdbRangeResult> VisitRangeAsync<TState>(KeySpanSelector beginInclusive, KeySpanSelector endExclusive, bool snapshot, TState state, FdbKeyValueAction<TState> visitor, FdbRangeOptions options, int iteration, CancellationToken ct)

Visit 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 Begin 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
• snapshot — Set to true for snapshot reads
• state — Opaque state provided by the caller, and passed to the visitor
• visitor — Handler that will observe the result of the read.
• options — Range read options
• iteration — If the streaming mode is set to Iterator (default), 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.
• ct — Token used to cancel the operation from the outside

Returns: true if the range

Watch

FdbWatch Watch(Slice key, CancellationToken ct)

Watch a key for any change in the database.

• key — Key to watch
• ct — CancellationToken used to abort the watch if the caller doesn't want to wait anymore. Note that you can manually cancel the watch by calling Cancel() on the returned FdbWatch instance

Returns: FdbWatch that can be awaited and will complete when the key has changed in the database, or cancellation occurs. You can call Cancel() at any time if you are not interested in watching the key anymore. You MUST always call Dispose() if the watch completes or is cancelled, to ensure that resources are released properly.

You can directly await an FdbWatch, or obtain a Task by reading the property.