IFdbTransaction

Namespace: FoundationDB.Client · interface

Implements: IFdbReadOnlyTransaction, IDisposable

Transaction that allows read and write operations

Properties

IsReadOnly

bool IsReadOnly { get; }

Returns true if this transaction instance only allows read operations

Attempting to call a write method on a read-only transaction will immediately throw an exception

Size

long Size { get; }

Estimated payload size of the transaction (in bytes)

This is not guaranteed to be accurate, and should only be used as a hint.

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)

Performs an atomic operation that will mutate a key in the database

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

Modifies 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.

Clear

void Clear(ReadOnlySpan<byte> key)

Removes a key from the database.

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

Modifies 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.

ClearRange

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

Removes a range of keys from the database.

• 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.

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

CommitAsync

Task CommitAsync()

Commits any changes performed by this transaction to the database.

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

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.

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 retryable, 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.

CreateUniqueVersionStamp

VersionStamp CreateUniqueVersionStamp()

Returns a place-holder 96-bit VersionStamp with a unique user version per transaction.

Use this method, instead of if you intend to add multiple stamped keys to the same subspace, inside the same transaction!

CreateVersionStamp

VersionStamp CreateVersionStamp()

Returns a place-holder 80-bit VersionStamp, whose value is not yet known, but will be filled by the database at commit time.

Returns: This value can be used to generate temporary keys or value, for use with the VersionStampedKey or VersionStampedValue mutations

The generate placeholder will use a random value that is unique per transaction (and changes at each retry).

If you need to generate multiple different stamps per transaction (ex: adding multiple items to the same subspace), either call CreateVersionStamp or CreateUniqueVersionStamp!

If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.

If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.

VersionStamp CreateVersionStamp(int userVersion)

Returns a place-holder 96-bit VersionStamp with an attached user version, whose value is not yet known, but will be filled by the database at commit time.

Returns: This value can be used to generate temporary keys or value, for use with the VersionStampedKey or VersionStampedValue mutations

The generate placeholder will use a random value that is unique per transaction (and changes at reach retry).

If the key contains the exact 80-bit byte signature of this token, the corresponding location will be tagged and replaced with the actual VersionStamp at commit time.

If another part of the key contains (by random chance) the same exact byte sequence, then an error will be triggered, and hopefully the transaction will retry with another byte sequence.

EnsureCanWrite

void EnsureCanWrite()

Ensures that the transaction is in a valid state for issuing write operations.

GetApproximateSizeAsync

Task<long> GetApproximateSizeAsync()

Returns the approximate size of the mutation list that this transaction will send to the server.

GetCommittedVersion

long GetCommittedVersion()

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

Returns: Version of the database after a successful commit, or -1 if no commit has been performed yet, or if it was unsuccessful.

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.

GetVersionStampAsync

Task<VersionStamp> GetVersionStampAsync()

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

The Task will be ready only after the successful completion of a call to CommitAsync on this transaction.

Read-only transactions do not modify the database when committed and will result in the Task completing with an error.

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.

GetWriteStatistics

(int, long) GetWriteStatistics()

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

The counters are reset everytime the transaction is recycled (either via on )

Set

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

Sets the value of a key in the database.

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

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

TouchMetadataVersionKey

void TouchMetadataVersionKey(Slice key = null)

Bumps the value of a metadata key of the database snapshot represented by the current transaction.

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

The value of the key will be updated to a value higher than any previous value, once the transaction commits.

Until this happens, any additional call to GetMetadataVersionKeyAsync will return null.

If the value of the key is read via a regular GetAsync or GetRange call, the transaction will fail to commit!

This method requires API version 610 or greater.

Watch

FdbWatch Watch(ReadOnlySpan<byte> key, CancellationToken ct)

Watches a key for any future change in the database.

• key — Name of the key that will be watched
• ct — Token used to abort the watch if the caller doesn't want to wait anymore.

Returns: FdbWatch instance that can be awaited and will complete when the key has changed in the database, or cancellation occurs.

The watch will only become active if the transaction successfully commits, and should NOT be awaited from within the same or another transaction.

You can directly await an FdbWatch, or use the Task property.

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.

It is possible (though rare) that a Watch fires even if the key did not change.