fdb v5.1.7-2 FDB.Transaction View Source

Link to this section Summary

Functions

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

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

Cancels the transaction. All pending or future uses of the transaction will return a transaction_cancelled error

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

Modify the database snapshot represented by 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

Attempts to commit the sets and clears previously applied to the database snapshot represented by 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

Async version of commit/1

Creates a new transaction

Reads a value from the database snapshot represented by transaction

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

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

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

Reads all key-value pairs in the database snapshot represented by transaction 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

Returns the transaction snapshot read version

Returns an FDB.Future.t/0 which will be set to the versionstamp which was used by any versionstamp operations in this transaction

Modify the database snapshot represented by transaction to change the given key to have the given value

Changes the FDB.Transaction.Coder.t/0 associated with the transaction

Refer FDB.Option for the list of options. Any option that starts with transaction_option_ is allowed

Refer FDB.Option for the list of options. Any option that starts with transaction_option_ is allowed

Sets the snapshot read version used by a transaction

watch’s behavior is relative to the transaction that created it. A watch will report a change in relation to the key’s value as readable by that transaction. The initial value used for comparison is either that of the transaction’s read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change

Link to this section Types

Link to this type t() View Source
t() :: %FDB.Transaction{
  coder: FDB.Transaction.Coder.t() | nil,
  resource: identifier()
}

Link to this section Functions

Link to this function add_conflict_range(transaction, key_range, type) View Source
add_conflict_range(t(), FDB.KeyRange.t(), FDB.Option.key()) :: :ok

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

Most applications will use the serializable isolation that transactions provide by default and will not need to manipulate conflict ranges.

Link to this function atomic_op(transaction, key, operation_type, param) View Source
atomic_op(t(), any(), FDB.Option.key(), FDB.Option.value()) :: :ok

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

An atomic operation is a single database command that carries out several logical steps: reading the value of a key, performing a transformation on that value, and writing the result. Different atomic operations perform different transformations. Like other database operations, an atomic operation is used within a transaction; however, its use within a transaction will not cause the transaction to conflict.

Atomic operations do not expose the current value of the key to the client but simply send the database the transformation to apply. In regard to conflict checking, an atomic operation is equivalent to a write without a read. It can only cause other transactions performing reads of the key to conflict.

By combining these logical steps into a single, read-free operation, FoundationDB can guarantee that the transaction will not conflict due to the operation. This makes atomic operations ideal for operating on keys that are frequently modified. A common example is the use of a key-value pair as a counter.

If a transaction uses both an atomic operation and a serializable read on the same key, the benefits of using the atomic operation (for both conflict checking and performance) are lost.

The modification affects the actual database only if transaction is later committed with commit/1.

Refer FDB.Option for the list of operationtype. Any option that starts with `mutation_type` is allowed

Link to this function cancel(transaction) View Source
cancel(t()) :: :ok

Cancels the transaction. All pending or future uses of the transaction will return a transaction_cancelled error.

If your program attempts to cancel a transaction after commit/1 has been called but before it returns, unpredictable behavior will result. While it is guaranteed that the transaction will eventually end up in a cancelled state, the commit may or may not occur. Moreover, even if the call to commit/1 appears to return a transaction_cancelled error, the commit may have occurred or may occur in the future. This can make it more difficult to reason about the order in which transactions occur.

Link to this function clear(transaction, key) View Source
clear(t(), any()) :: :ok

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

The modification affects the actual database only if transaction is later committed with commit/1.

Link to this function clear_range(transaction, key_range) View Source
clear_range(t(), FDB.KeyRange.t()) :: :ok

Modify the database snapshot represented by 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.

The modification affects the actual database only if transaction is later committed with commit/1.

Link to this function commit(transaction) View Source
commit(t()) :: :ok

Attempts to commit the sets and clears previously applied to the database snapshot represented by 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.

It is not necessary to commit a read-only transaction.

As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, commit/1 will return a commit_unknown_result error. The FDB.Database.transact/2 function treats this error as retryable, so this could execute the transaction twice. In these cases, you must consider the idempotence of the transaction.

Normally, commit will wait for outstanding reads to return. However, if those reads were snapshot reads or the transaction option for FDB.Option.transaction_option_read_your_writes_disable/0 has been invoked, any outstanding reads will immediately return errors.

Link to this function commit_q(transaction) View Source
commit_q(t()) :: FDB.Future.t()

Async version of commit/1

Link to this function create(database, coder \\ nil) View Source
create(FDB.Database.t(), FDB.Transaction.Coder.t() | nil) :: t()

Creates a new transaction.

if coder is not set then database’s coder is used.

Link to this function get(transaction, key, options \\ %{}) View Source
get(t(), any(), map()) :: any()

Reads a value from the database snapshot represented by transaction.

If key is not present in the database, nil is returned as the result.

Options

  • :snapshot - (boolean) Defaults to false.
Link to this function get_addresses_for_key(transaction, key) View Source
get_addresses_for_key(t(), any()) :: [String.t()]

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

Link to this function get_addresses_for_key_q(transaction, key) View Source
get_addresses_for_key_q(t(), any()) :: FDB.Future.t()

Async version of get_addresses_for_key/2

Link to this function get_committed_version(transaction) View Source
get_committed_version(t()) :: integer()

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

commit/1 must have been called on transaction and not an error 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.

Note that database versions are not necessarily unique to a given transaction and so cannot be used to determine in what order two transactions completed. The only use for this function is to manually enforce causal consistency when calling set_read_version/2 on another subsequent transaction.

Most applications will not call this function.

Link to this function get_key(transaction, key_selector, options \\ %{}) View Source

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

Returns the key in the database matching the key selector.

Link to this function get_key_q(transaction, key_selector, options \\ %{}) View Source

Async version of get_key/2

Link to this function get_q(transaction, key, options \\ %{}) View Source
get_q(t(), any(), map()) :: FDB.Future.t()

Async version of get/3

Link to this function get_range(transaction, key_selector_range, options \\ %{}) View Source

Reads all key-value pairs in the database snapshot represented by transaction 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.

Multiple calls may be made to server to fetch the data. The amount of data returned on each call is determined by the options like target_bytes and mode.

A Stream is returned which fetches the data lazily. This is suitable for iterating over large list of key value pair.

Options

  • :snapshot - (boolean) Defaults to false.
  • :reverse - (boolean) Defaults to false.
  • :target_bytes - (boolean) If non-zero, indicates a (soft) cap on the combined number of bytes of keys and values to return per call. Defaults to 0.
  • :mode - (FDB.Option.key/0) Refer FDB.Option for the list of options. Any option that starts with streaming_mode_ is allowed. Defaults to FDB.Option.streaming_mode_iterator/0.
  • :limit - (number) If non-zero, indicates the maximum number of key-value pairs to return. Defaults to 0.
Link to this function get_read_version(transaction) View Source
get_read_version(t()) :: integer()

Returns the transaction snapshot read version.

The transaction obtains a snapshot read version automatically at the time of the first call to get_* (including this one) and (unless causal consistency has been deliberately compromised by transaction options) is guaranteed to represent all transactions which were reported committed before that call.

Link to this function get_read_version_q(transaction) View Source
get_read_version_q(t()) :: FDB.Future.t()

Async version of get_read_version/1

Link to this function get_versionstamp_q(transaction) View Source
get_versionstamp_q(t()) :: FDB.Future.t()

Returns an FDB.Future.t/0 which will be set to the versionstamp which was used by any versionstamp operations in this transaction.

The future will be ready only after the successful completion of a call to commit/1 on this transaction. Read-only transactions do not modify the database when committed and will result in the future 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.

Link to this function on_error(transaction, code) View Source
on_error(t(), integer()) :: :ok
Link to this function on_error_q(transaction, code) View Source
on_error_q(t(), integer()) :: FDB.Future.t()

Async version of on_error/2

Link to this function set(transaction, key, value) View Source
set(t(), any(), any()) :: :ok

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 commit/1.

Link to this function set_coder(transaction, coder) View Source
set_coder(t(), FDB.Transaction.Coder.t()) :: t()

Changes the FDB.Transaction.Coder.t/0 associated with the transaction.

Link to this function set_option(transaction, option) View Source
set_option(t(), FDB.Option.key()) :: :ok

Refer FDB.Option for the list of options. Any option that starts with transaction_option_ is allowed.

Link to this function set_option(transaction, option, value) View Source
set_option(t(), FDB.Option.key(), FDB.Option.value()) :: :ok

Refer FDB.Option for the list of options. Any option that starts with transaction_option_ is allowed.

Link to this function set_read_version(transaction, version) View Source
set_read_version(t(), integer()) :: :ok

Sets the snapshot read version used by a transaction.

This is not needed in simple cases. 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* have been called on this transaction already, the result is undefined.

Link to this function watch_q(transaction, key) View Source
watch_q(t(), any()) :: FDB.Future.t()

watch’s behavior is relative to the transaction that created it. A watch will report a change in relation to the key’s value as readable by that transaction. The initial value used for comparison is either that of the transaction’s read version or the value as modified by the transaction itself prior to the creation of the watch. If the value changes and then changes back to its initial value, the watch might not report the change.

Until the transaction that created it has been committed, a watch will not report changes made by other transactions. In contrast, a watch will immediately report changes made by the transaction itself. Watches cannot be created if the transaction has set the FDB.Option.transaction_option_read_your_writes_disable/0 transaction option, and an attempt to do so will return an watches_disabled error.

If the transaction used to create a watch encounters an error during commit, then the watch will be set with that error. A transaction whose commit result is unknown will set all of its watches with the commit_unknown_result error. If an uncommitted transaction is reset or destroyed, then any watches it created will be set with the transaction_cancelled error.

Returns an FDB.Future.t/0 representing an empty value that will be set once the watch has detected a change to the value at the specified key.

By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will return a too_many_watches error. This limit can be changed using the FDB.Option.database_option_max_watches/0 database option.