FdbTransactionOption

Namespace: FoundationDB.Client · enum

Implements: IComparable, ISpanFormattable, IFormattable, IConvertible

Defines a set of options for a transaction

Fields

AccessSystemKeys

AccessSystemKeys = 301

Allows this transaction to read and modify system keys (those that start with the byte 0xFF)

Parameter: Option takes no parameter

AuthorizationToken

AuthorizationToken = 2000

Attach given authorization token to the transaction such that subsequent tenant-aware requests are authorized.

Parameter: (String) A JSON Web Token authorized to access data belonging to one or more tenants, indicated by 'tenants' claim of the token's payload.

Attach given authorization token to the transaction such that subsequent tenant-aware requests are authorized

AutoThrottleTag

AutoThrottleTag = 801

Adds a tag to the transaction that can be used to apply manual or automatic targeted throttling.

Parameter: (String) String identifier used to associate this transaction with a throttling group. Must not exceed 16 characters.

At most 5 tags can be set on a transaction.

AutomaticIdempotency

AutomaticIdempotency = 505

Automatically assign a random 16 byte idempotency id for this transaction.

Prevents commits from failing with CommitUnknownResult.

WARNING: If you are also using the multiversion client or transaction timeouts, if either cluster_version_changed or transaction_timed_out was thrown during a commit, then that commit may have already succeeded or may succeed in the future.

This feature is in development and not ready for general use.

BypassStorageQuota

BypassStorageQuota = 304

Allows this transaction to bypass storage quota enforcement.

Should only be used for transactions that directly or indirectly decrease the size of the tenant group's data.

BypassUnreadable

BypassUnreadable = 1100

Allows get operations to read from sections of keyspace that have become unreadable because of VersionStamp operations.

These reads will view VersionStamp operations as if they were set operations that did not fill in the VersionStamp.

CausalReadDisable

CausalReadDisable = 21

Parameter: Option takes no parameter

CausalReadRisky

CausalReadRisky = 20

The read version will be committed, and usually will be the latest committed, but might not be the latest committed in the event of a fault or partition

Parameter: Option takes no parameter

CausalWriteRisky

CausalWriteRisky = 10

The transaction, if not self-conflicting, may be committed a second time after commit succeeds, in the event of a fault

Parameter: Option takes no parameter

CheckWritesEnable

CheckWritesEnable = 50

For internal use only.

CommitOnFirstProxy

CommitOnFirstProxy = 40

Committing this transaction will bypass the normal load balancing across proxies and go directly to the specifically nominated 'first proxy'.

ConsistencyCheckRequiredReplicas

ConsistencyCheckRequiredReplicas = 4001

Specifies the number of storage server replica results that the load balancer needs to compare when the EnableReplicaConsistencyCheck option is set.

Parameter: (int) Number of storage replicas over which the load balancer consistency check is done.

DebugDump

DebugDump = 400

Enables dumping the set of mutations generated by a transaction, at commit time.

DebugRetryLogging

DebugRetryLogging = 401

Sets a client provided identifier for the transaction that will be used for logging during retries.

Parameter: (String) Optional transaction name

DebugTransactionIdentifier

DebugTransactionIdentifier = 403

Sets a client provided identifier for the transaction that will be used in scenarios like tracing or profiling. Client trace logging or transaction profiling must be separately enabled.

Parameter: (String) String identifier to be used when tracing or profiling this transaction. The identifier must not exceed 100 characters.

DevNullIsWebScale

DevNullIsWebScale = 130

Deprecated

DurabilityDataCenter

DurabilityDataCenter = 110

Parameter: Option takes no parameter

DurabilityRisky

DurabilityRisky = 120

Parameter: Option takes no parameter

EnableReplicaConsistencyCheck

EnableReplicaConsistencyCheck = 4000

Enables replica consistency check

Compares the results returned by storage server replicas (as many as specified by ConsistencyCheckRequiredReplicas option) for a given read request, in client-side load balancer.

ExpensiveClearCostEstimationEnable

ExpensiveClearCostEstimationEnable = 1000

Asks storage servers for how many bytes a clear key range contains. Otherwise, uses the location cache to roughly estimate this.

FirstInBatch

FirstInBatch = 710

No other transactions will be applied before this transaction within the same commit version.

IdempotencyId

IdempotencyId = 504

Associate this transaction with this ID for the purpose of checking whether this transaction has already committed.

Parameter: (String) Unique ID. Must be at least 16 bytes and less than 256 bytes

This feature is in development and not ready for general use.

Unless the AutomaticIdempotency option is set after this option, the client will not automatically attempt to remove this id from the cluster after a successful commit.

IncludePortInAddress

IncludePortInAddress = 23

Addresses returned by GetAddressesForKeyAsync include the port when enabled. This will be enabled by default in api version 700, and this option will be deprecated.

InitializeNewDatabase

InitializeNewDatabase = 300

This is a write-only transaction which sets the initial configuration. This option is designed for use by database system tools only.

Parameter: Option takes no parameter

LockAware

LockAware = 700

The transaction can read and write to locked databases, and is responsible for checking that it took the lock.

LogTransaction

LogTransaction = 404

Enables tracing for this transaction and logs results to the client trace logs. The DebugTransactionIdentifier option must be set before using this option, and client trace logging must be enabled and to get log output.

MaxRetryDelay

MaxRetryDelay = 502

Set the maximum amount of backoff delay incurred in the call to onError if the error is retryable. Defaults to 1000 ms. Valid parameter values are [0, int.MaxValue]. Like all transaction options, the maximum retry delay must be reset after a call to onError. If the maximum retry delay is less than the current retry delay of the transaction, then the current retry delay will be clamped to the maximum retry delay. Parameter: (Int32) value in milliseconds of maximum delay

NextWriteNoWriteConflictRange

NextWriteNoWriteConflictRange = 30

The next write performed on this transaction will not generate a write conflict range. As a result, other transactions which read the key(s) being modified by the next write will not conflict with this transaction. Care needs to be taken when using this option on a transaction that is shared between multiple threads. When setting this option, write conflict ranges will be disabled on the next write operation, regardless of what thread it is on.

Parameter: Option takes no parameter

None

None = 0

None

PriorityBatch

PriorityBatch = 201

Specifies that this transaction should be treated as low priority and that default priority transactions should be processed first. Useful for doing batch work simultaneously with latency-sensitive work

Parameter: Option takes no parameter

PrioritySystemImmediate

PrioritySystemImmediate = 200

Specifies that this transaction should be treated as highest priority and that lower priority transactions should block behind this one. Use is discouraged outside low-level tools

Parameter: Option takes no parameter

RawAccess

RawAccess = 303

Allows this transaction to access the raw key-space when tenant mode is on.

ReadAheadDisable

ReadAheadDisable = 52

Deprecated

ReadLockAware

ReadLockAware = 702

The transaction can read from locked databases.

ReadPriorityHigh

ReadPriorityHigh = 511

Use high read priority for subsequent read requests in this transaction.

ReadPriorityLow

ReadPriorityLow = 510

Use low read priority for subsequent read requests in this transaction.

ReadPriorityNormal

ReadPriorityNormal = 509

Use normal read priority for subsequent read requests in this transaction.

This is the default behavior.

ReadServerSizeCacheDisable

ReadServerSizeCacheDisable = 508

Storage server should not cache disk blocks needed for subsequent read requests in this transaction.

This can be used to avoid cache pollution for reads not expected to be repeated.

ReadServerSizeCacheEnable

ReadServerSizeCacheEnable = 507

Storage server should cache disk blocks needed for subsequent read requests in this transaction.

This is the default behavior.

ReadSystemKeys

ReadSystemKeys = 302

Allows this transaction to read system keys (those that start with the byte 0xFF)

Parameter: Option takes no parameter

ReadYourWritesDisable

ReadYourWritesDisable = 51

Reads performed by a transaction will not see any prior mutations that occurred in that transaction, instead seeing the value which was in the database at the transaction's read version. This option may provide a small performance benefit for the client, but also disables a number of client-side optimizations which are beneficial for transactions which tend to read and write the same keys within a single transaction. Also note that with this option invoked any outstanding reads will return errors when transaction commit is called (rather than the normal behavior of commit waiting for outstanding reads to complete).

Parameter: Option takes no parameter

ReportConflictingKeys

ReportConflictingKeys = 712

The transaction can retrieve keys that are conflicting with other transactions.

RetryLimit

RetryLimit = 501

Set a maximum number of retries after which additional calls to onError will throw the most recently seen error code. Valid parameter values are [-1, int.MaxValue]. If set to -1, will disable the retry limit. Parameter: (Int32) number of times to retry

ServerRequestTracing

ServerRequestTracing = 406

Sets an identifier for server tracing of this transaction.

When committed, this identifier triggers logging when each part of the transaction authority encounters it, which is helpful in diagnosing slowness in misbehaving clusters.

The identifier is randomly generated.

When there is also a DebugTransactionIdentifier, both IDs are logged together.

SizeLimit

SizeLimit = 503

Set the transaction size limit in bytes. The size is calculated by combining the sizes of all keys and values written or mutated, all key ranges cleared, and all read and write conflict ranges. (In other words, it includes the total size of all data included in the request to the cluster to commit the transaction.) Large transactions can cause performance problems on FoundationDB clusters, so setting this limit to a smaller value than the default can help prevent the client from accidentally degrading the cluster's performance. This value must be at least 32 and cannot be set to higher than 10,000,000, the default transaction size limit.

Parameter: (Int32) value in bytes

SkipGrvCache

SkipGrvCache = 1102

Specifically instruct this transaction to NOT use cached GRV.

Primarily used for the read version cache's background updater to avoid attempting to read a cached entry in specific situations.

SnapshotReadYourWritesDisable

SnapshotReadYourWritesDisable = 601

Snapshot read operations will not see the results of writes done in the same transaction.

SnapshotReadYourWritesEnable

SnapshotReadYourWritesEnable = 600

Snapshot read operations will see the results of writes done in the same transaction.

SpanParent

SpanParent = 900

Adds a parent to the Span of this transaction. Used for transaction tracing. A span can be identified with any 16 bytes.

SpecialKeySpaceEnableWrites

SpecialKeySpaceEnableWrites = 714

By default, users are not allowed to write to special keys.

Enabling this option will implicitly enable all options required to achieve the configuration change.

SpecialKeySpaceRelaxed

SpecialKeySpaceRelaxed = 713

Allow reading from zero or more modules.

By default, the special key space will only allow users to read from exactly one module (a subspace in the special key space). Use this option to allow reading from zero or more modules.

Users who set this option should be prepared for new modules, which may have different behaviors than the modules they're currently reading. For example, a new module might block or return an error.

Tag

Tag = 800

Adds a tag to the transaction that can be used to apply manual targeted throttling.

Parameter: (String) String identifier used to associate this transaction with a throttling group. Must not exceed 16 characters.

At most 5 tags can be set on a transaction.

Timeout

Timeout = 500

Set a timeout in milliseconds which, when elapsed, will cause the transaction automatically to be cancelled. Valid parameter values are [0, int.MaxValue]. If set to 0, will disable all timeouts. All pending and any future uses of the transaction will throw an exception. The transaction can be used again after it is reset. Like all transaction options, a timeout must be reset after a call to onError. This behavior allows the user to make the timeout dynamic.

Parameter: (Int32) value in milliseconds of timeout

TransactionLoggingEnable

TransactionLoggingEnable = 402

Enables tracing for this transaction and logs results to the client traces logs.

Parameter: (String) Optional transaction name

TransactionLoggingMaxFieldLength

TransactionLoggingMaxFieldLength = 405

Sets the maximum escaped length of key and value fields to be logged to the trace file via the LogTransaction option, after which the field will be truncated. A negative value disables truncation.

Parameter: (Int32) Maximum length of escaped key and value fields.

UseGrvCache

UseGrvCache = 1101

Allows this transaction to use cached GRV from the database context.

Defaults to off.

Upon first usage, starts a background updater to periodically update the cache to avoid stale read versions.

The DisableClientBypass option must also be set.

UseProvisionalProxies

UseProvisionalProxies = 711

This option should only be used by tools which change the database configuration.

UsedDuringCommitProtectionDisable

UsedDuringCommitProtectionDisable = 701

By default, operations that are performed on a transaction while it is being committed will not only fail themselves, but they will attempt to fail other in-flight operations (such as the commit) as well. This behavior is intended to help developers discover situations where operations could be unintentionally executed after the transaction has been reset. Setting this option removes that protection, causing only the offending operation to fail.