View Source FDB.Transaction (fdb v6.3.23-0)

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.

Returns the approximate transaction size so far in the returned future, which is the summation of the estimated size of mutations, read conflict ranges, and write conflict ranges.

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

Returns the estimated size of the key range given.

Async version of get_estimated_range_size_bytes/1

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

Get metadata version.

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 FDB.Versionstamp.t/0 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 default options 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.

Same as set, but replaces the placeholder versionstamp in the key

Same as set, but replaces the placeholder versionstamp in the value

Update metadata version.

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

Specs

t() :: %FDB.Transaction{
  coder: FDB.Transaction.Coder.t(),
  resource: identifier(),
  snapshot: integer()
}

Link to this section Functions

Link to this function

add_conflict_key(transaction, key, type, options \\ %{})

View Source
Link to this function

add_conflict_range(transaction, key_range, type, options \\ %{})

View Source

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, options \\ %{})

View Source

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

Specs

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, options \\ %{})

View Source

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, options \\ %{})

View Source

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.

Specs

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.

Specs

commit_q(t()) :: FDB.Future.t()

Async version of commit/1

Link to this function

create(database, defaults \\ %{})

View Source

Specs

create(FDB.Database.t(), map()) :: t()

Creates a new transaction.

Link to this function

get(transaction, key, options \\ %{})

View Source

Specs

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

Specs

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, options \\ %{})

View Source

Async version of get_addresses_for_key/2

Link to this function

get_approximate_size(transaction)

View Source

Specs

get_approximate_size(t()) :: integer()

Returns the approximate transaction size so far in the returned future, which is the summation of the estimated size of mutations, read conflict ranges, and write conflict ranges.

This can be called multiple times before the transaction is committed.

Link to this function

get_approximate_size_q(transaction)

View Source

Specs

get_approximate_size_q(t()) :: FDB.Future.t()

Async version of get_approximate_size/1

Link to this function

get_committed_version(transaction)

View Source

Specs

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_estimated_range_size_bytes(transaction, key_range, options \\ %{})

View Source

Specs

get_estimated_range_size_bytes(t(), FDB.KeyRange.t(), map()) :: integer()

Returns the estimated size of the key range given.

Link to this function

get_estimated_range_size_bytes_q(transaction, key_range, options \\ %{})

View Source

Specs

get_estimated_range_size_bytes_q(t(), FDB.KeyRange.t(), map()) :: FDB.Future.t()

Async version of get_estimated_range_size_bytes/1

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

View Source

Specs

get_metadata_version(t()) :: FDB.Versionstamp.t() | nil

Get metadata version.

Note: This might return nil if the metadata version was never set earlier.

Link to this function

get_q(transaction, key, options \\ %{})

View Source

Specs

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

Specs

get_range(t(), FDB.KeySelectorRange.t(), map()) :: FDB.RangeResult.t()

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.

Makes a single call to fetch data. The returned struct FDB.RangeResult.t/0 contains key_values, has_more and next function. If has_more is true, then next function can be called to fetch the next batch of FDB.RangeResult.t/0.

The next function expects transaction as the first argument and returns FDB.RangeResult.t/0

The amount of data returned on each call is determined by the options like target_bytes and mode.

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_range_stream(transaction, key_selector_range, options \\ %{})

View Source

Specs

get_range_stream(t() | FDB.Database.t(), FDB.KeySelectorRange.t(), map()) ::
  Enumerable.t()

See get_range/3 for options

A Stream is returned which fetches all the key value pairs lazily using get_range/3 function. This is suitable for iterating over large list of key value pair.

Link to this function

get_read_version(transaction)

View Source

Specs

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

Specs

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

Specs

get_versionstamp_q(t()) :: FDB.Future.t()

Returns an FDB.Future.t/0 which will be set to the FDB.Versionstamp.t/0 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

Specs

on_error(t(), integer()) :: :ok
Link to this function

on_error_q(transaction, code)

View Source

Specs

on_error_q(t(), integer()) :: FDB.Future.t()

Async version of on_error/2

Link to this function

set(transaction, key, value, options \\ %{})

View Source

Specs

set(t(), any(), any(), map()) :: :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_defaults(transaction, defaults)

View Source

Specs

set_defaults(t(), map()) :: t()

Changes the default options associated with the transaction.

Link to this function

set_option(transaction, option)

View Source

Specs

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

Specs

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

Specs

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

set_versionstamped_key(transaction, key, value, options \\ %{})

View Source

Specs

set_versionstamped_key(t(), any(), any(), map()) :: :ok

Same as set, but replaces the placeholder versionstamp in the key

The semantics are same as set/4 except the key should have one incomplete FDB.Versionstamp.t/0. The versionstamp will get replaced on commit of the transaction.

A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an error.

This operation is not compatible with the READ_YOUR_WRITES_DISABLE transaction option and will generate an error if used with it.

The database version should be atleast 5.2.

Example

coder =
  FDB.Transaction.Coder.new(
    Coder.Tuple.new({Coder.ByteString.new(), Coder.Versionstamp.new()})
  )

future =
  Database.transact(db, fn t ->
    :ok =
      Transaction.set_versionstamped_key(
        t,
        {"stamped", FDB.Versionstamp.incomplete()},
        random_value()
      )

    Transaction.get_versionstamp_q(t)
  end)

stamp = Future.await(future)

[{{"stamped", key_stamp}, _}] =
  Database.get_range_stream(db, KeySelectorRange.starts_with({"stamped"}))
  |> Enum.to_list()

assert stamp == key_stamp
Link to this function

set_versionstamped_value(transaction, key, value, options \\ %{})

View Source

Specs

set_versionstamped_value(t(), any(), any(), map()) :: :ok

Same as set, but replaces the placeholder versionstamp in the value

The semantics are same as set/4 except the value should have one incomplete FDB.Versionstamp.t/0. The versionstamp will get replaced on commit of the transaction.

A transaction is not permitted to read any transformed key or value previously set within that transaction, and an attempt to do so will result in an error.

This operation is not compatible with the READ_YOUR_WRITES_DISABLE transaction option and will generate an error if used with it.

The database version should be atleast 5.2.

Example

coder =
  FDB.Transaction.Coder.new(
    Coder.ByteString.new(),
    Coder.Tuple.new({Coder.ByteString.new(), Coder.Versionstamp.new()})
  )

future =
  Database.transact(db, fn t ->
    :ok =
      Transaction.set_versionstamped_value(
        t,
        key,
        {"stamped", FDB.Versionstamp.incomplete()}
      )

    Transaction.get_versionstamp_q(t)
  end)

stamp = Future.await(future)

value =
  Database.transact(db, fn t ->
    Transaction.get(t, key)
  end)

assert {"stamped", stamp} == value
Link to this function

update_metadata_version(transaction)

View Source

Specs

update_metadata_version(t()) :: :ok

Update metadata version.

Link to this function

watch_q(transaction, key, options \\ %{})

View Source

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.