Version 11.1.0
All Classes Functions Variables Typedefs Enumerations Enumerator Modules Pages
WT_SESSION Struct Reference

All data operations are performed in the context of a WT_SESSION. More...

Public Member Functions

int close (WT_SESSION *session, const char *config)
 Close the session handle. More...
 
int reconfigure (WT_SESSION *session, const char *config)
 Reconfigure a session handle. More...
 
const char * strerror (WT_SESSION *session, int error)
 Return information about an error as a string. More...
 
Cursor handles
int open_cursor (WT_SESSION *session, const char *uri, WT_CURSOR *to_dup, const char *config, WT_CURSOR **cursorp)
 Open a new cursor on a data source or duplicate an existing cursor. More...
 
Table operations
int alter (WT_SESSION *session, const char *name, const char *config)
 Alter a table. More...
 
int create (WT_SESSION *session, const char *name, const char *config)
 Create a table, column group, index or file. More...
 
int compact (WT_SESSION *session, const char *name, const char *config)
 Compact a live row- or column-store btree or LSM tree. More...
 
int drop (WT_SESSION *session, const char *name, const char *config)
 Drop (delete) a table. More...
 
int join (WT_SESSION *session, WT_CURSOR *join_cursor, WT_CURSOR *ref_cursor, const char *config)
 Join a join cursor with a reference cursor. More...
 
int log_flush (WT_SESSION *session, const char *config)
 Flush the log. More...
 
int log_printf (WT_SESSION *session, const char *format,...)
 Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called). More...
 
int rename (WT_SESSION *session, const char *uri, const char *newuri, const char *config)
 Rename an object. More...
 
int reset (WT_SESSION *session)
 Reset the session handle. More...
 
int salvage (WT_SESSION *session, const char *name, const char *config)
 Salvage a table. More...
 
int truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config)
 Truncate a file, table, cursor range, or backup cursor. More...
 
int upgrade (WT_SESSION *session, const char *name, const char *config)
 Upgrade a table. More...
 
int verify (WT_SESSION *session, const char *name, const char *config)
 Verify a table. More...
 
Transactions
int begin_transaction (WT_SESSION *session, const char *config)
 Start a transaction in this session. More...
 
int commit_transaction (WT_SESSION *session, const char *config)
 Commit the current transaction. More...
 
int prepare_transaction (WT_SESSION *session, const char *config)
 Prepare the current transaction. More...
 
int rollback_transaction (WT_SESSION *session, const char *config)
 Roll back the current transaction. More...
 
Transaction timestamps
int query_timestamp (WT_SESSION *session, char *hex_timestamp, const char *config)
 Query the session's transaction timestamp state. More...
 
int timestamp_transaction (WT_SESSION *session, const char *config)
 Set a timestamp on a transaction. More...
 
int timestamp_transaction_uint (WT_SESSION *session, WT_TS_TXN_TYPE which, uint64_t ts)
 Set a timestamp on a transaction numerically. More...
 
Transaction support
int checkpoint (WT_SESSION *session, const char *config)
 Write a transactionally consistent snapshot of a database or set of individual objects. More...
 
int reset_snapshot (WT_SESSION *session)
 Reset the snapshot used for database visibility. More...
 
int transaction_pinned_range (WT_SESSION *session, uint64_t *range)
 Return the transaction ID range pinned by the session handle. More...
 

Public Attributes

WT_CONNECTIONconnection
 The connection for this session.
 
void * app_private
 A location for applications to store information that will be available in callbacks taking a WT_SESSION handle.
 

Detailed Description

All data operations are performed in the context of a WT_SESSION.

This encapsulates the thread and transactional context of the operation.

Thread safety: A WT_SESSION handle is not usually shared between threads, see Multithreading for more information.

Examples
ex_access.c, ex_backup.c, ex_backup_block.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extending.c, ex_extractor.c, ex_file_system.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, nop_encrypt.c, rotn_encrypt.c, and sodium_encrypt.c.

Member Function Documentation

◆ alter()

int WT_SESSION::alter ( WT_SESSION session,
const char *  name,
const char *  config 
)

Alter a table.

This will allow modification of some table settings after creation.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

error_check(session->alter(session, "table:mytable", "access_pattern_hint=random"));
Parameters
sessionthe session handle
namethe URI of the object to alter, such as "table:stock"
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
access_pattern_hintIt is recommended that workloads that consist primarily of updates and/or point queries specify random. Workloads that do many cursor scans through large ranges of data should specify sequential and other workloads should specify none. The option leads to an appropriate operating system advisory call where available.a string, chosen from the following options: "none", "random", "sequential"; default none.
app_metadataapplication-owned metadata for this object.a string; default empty.
assert = (declare timestamp usage.a set of related configuration options defined as follows.
    read_timestampif set, check that timestamps are always or never used on reads with this table, writing an error message if the policy is violated. If the library was built in diagnostic mode, drop core at the failing check.a string, chosen from the following options: "always", "never", "none"; default none.
)
cache_residentdo not ever evict the object's pages from cache. Not compatible with LSM tables; see Cache resident objects for more information.a boolean flag; default false.
log = (the transaction log configuration for this object. Only valid if log is enabled in wiredtiger_open.a set of related configuration options defined as follows.
    enabledif false, this object has checkpoint-level durability.a boolean flag; default true.
)
os_cache_dirty_maxmaximum dirty system buffer cache usage, in bytes. If non-zero, schedule writes for dirty blocks belonging to this object in the system buffer cache after that many bytes from this object are written into the buffer cache.an integer greater than or equal to 0; default 0.
os_cache_maxmaximum system buffer cache usage, in bytes. If non-zero, evict object blocks from the system buffer cache after that many bytes from this object are read or written into the buffer cache.an integer greater than or equal to 0; default 0.
write_timestamp_usagedescribe how timestamps are expected to be used on table modifications. The choices are the default, which ensures that once timestamps are used for a key, they are always used, and also that multiple updates to a key never use decreasing timestamps and never which enforces that timestamps are never used for a table. (The always, key_consistent, mixed_mode and ordered choices should not be used, and are retained for backward compatibility.).a string, chosen from the following options: "always", "key_consistent", "mixed_mode", "never", "none", "ordered"; default none.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

◆ begin_transaction()

int WT_SESSION::begin_transaction ( WT_SESSION session,
const char *  config 
)

Start a transaction in this session.

The transaction remains active until ended by WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction. Operations performed on cursors capable of supporting transactional operations that are already open in this session, or which are opened before the transaction ends, will operate in the context of the transaction.

This method must not be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in either case, subsequent
* operations are included in the transaction. Opening cursors before the transaction begins
* allows applications to cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if commit_transaction fails,
* the transaction was rolled-back and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all cursors. */
break;
}
/*
* Cursors remain open and may be used for multiple transactions.
*/
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
ignore_preparewhether to ignore updates by other prepared transactions when doing of read operations of this transaction. When true, forces the transaction to be read-only. Use force to ignore prepared updates and permit writes (see Configuring ignore_prepare for more information).a string, chosen from the following options: "false", "force", "true"; default false.
isolationthe isolation level for this transaction; defaults to the session's isolation level.a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default empty.
namename of the transaction for tracing and debugging.a string; default empty.
no_timestampallow a commit without a timestamp, creating values that have "always existed" and are visible regardless of timestamp. See Managing the transaction timestamp state.a boolean flag; default false.
operation_timeout_mswhen non-zero, a requested limit on the time taken to complete operations in this transaction. Time is measured in real time milliseconds from the start of each WiredTiger API call. There is no guarantee any operation will not take longer than this amount of time. If WiredTiger notices the limit has been exceeded, an operation may return a WT_ROLLBACK error. Default is to have no limit.an integer greater than or equal to 1; default 0.
prioritypriority of the transaction for resolving conflicts. Transactions with higher values are less likely to abort.an integer between -100 and 100; default 0.
read_timestampread using the specified timestamp. The value must not be older than the current oldest timestamp. See Managing the transaction timestamp state.a string; default empty.
roundup_timestamps = (round up timestamps of the transaction.a set of related configuration options defined as follows.
    preparedapplicable only for prepared transactions, and intended only for special-purpose use. See Automatic prepare timestamp rounding. Allows the prepare timestamp and the commit timestamp of this transaction to be rounded up to be no older than the oldest timestamp, and allows violating the usual restriction that the prepare timestamp must be newer than the stable timestamp. Specifically: at transaction prepare, if the prepare timestamp is less than or equal to the oldest timestamp, the prepare timestamp will be rounded to the oldest timestamp. Subsequently, at commit time, if the commit timestamp is less than the (now rounded) prepare timestamp, the commit timestamp will be rounded up to it and thus to at least oldest. Neither timestamp will be checked against the stable timestamp.a boolean flag; default false.
    readif the read timestamp is less than the oldest timestamp, the read timestamp will be rounded up to the oldest timestamp. See Rounding up the read timestamp.a boolean flag; default false.
)
syncwhether to sync log records when the transaction commits, inherited from wiredtiger_open transaction_sync.a boolean flag; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_log.c.

◆ checkpoint()

int WT_SESSION::checkpoint ( WT_SESSION session,
const char *  config 
)

Write a transactionally consistent snapshot of a database or set of individual objects.

When timestamps are not in use, the checkpoint includes all transactions committed before the checkpoint starts. When timestamps are in use and the checkpoint runs with use_timestamp=true (the default), updates committed with a timestamp after the stable timestamp, in tables configured for checkpoint-level durability, are not included in the checkpoint. Updates committed in tables configured for commit-level durability are always included in the checkpoint. See Checkpoint-level durability and Commit-level durability for more information.

Calling the checkpoint method multiple times serializes the checkpoints; new checkpoint calls wait for running checkpoint calls to complete.

Existing named checkpoints may optionally be discarded.

This method must not be called on a session with an active transaction.

/* Checkpoint the database. */
error_check(session->checkpoint(session, NULL));
/* Checkpoint of the database, creating a named snapshot. */
error_check(session->checkpoint(session, "name=June01"));
/*
* Checkpoint a list of objects. JSON parsing requires quoting the list of target URIs.
*/
error_check(session->checkpoint(session, "target=(\"table:table1\",\"table:table2\")"));
/*
* Checkpoint a list of objects, creating a named snapshot. JSON parsing requires quoting the
* list of target URIs.
*/
error_check(session->checkpoint(session, "target=(\"table:mytable\"),name=midnight"));
/* Checkpoint the database, discarding all previous snapshots. */
error_check(session->checkpoint(session, "drop=(from=all)"));
/* Checkpoint the database, discarding the "midnight" snapshot. */
error_check(session->checkpoint(session, "drop=(midnight)"));
/*
* Checkpoint the database, discarding all snapshots after and including "noon".
*/
error_check(session->checkpoint(session, "drop=(from=noon)"));
/*
* Checkpoint the database, discarding all snapshots before and including "midnight".
*/
error_check(session->checkpoint(session, "drop=(to=midnight)"));
/*
* Create a checkpoint of a table, creating the "July01" snapshot and discarding the "May01" and
* "June01" snapshots. JSON parsing requires quoting the list of target URIs.
*/
error_check(
session->checkpoint(session, "target=(\"table:mytable\"),name=July01,drop=(May01,June01)"));
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
dropspecify a list of checkpoints to drop. The list may additionally contain one of the following keys: "from=all" to drop all checkpoints, "from=<checkpoint>" to drop all checkpoints after and including the named checkpoint, or "to=<checkpoint>" to drop all checkpoints before and including the named checkpoint. Checkpoints cannot be dropped if open in a cursor. While a hot backup is in progress, checkpoints created prior to the start of the backup cannot be dropped.a list of strings; default empty.
flush_tier = (configure flushing objects to tiered storage after checkpoint.a set of related configuration options defined as follows.
    enabledif true, perform one iteration of object switching and flushing objects to tiered storage.a boolean flag; default false.
    forceif false (the default), flush_tier of any individual object may be skipped if the underlying object has not been modified since the previous flush_tier. If true, this option forces the flush_tier.a boolean flag; default false.
    syncwait for all objects to be flushed to the shared storage to the level specified. When false, do not wait for any objects to be written to the tiered storage system but return immediately after generating the objects and work units for an internal thread. When true, the caller waits until all work queued for this call to be completely processed before returning.a boolean flag; default true.
    timeoutamount of time, in seconds, to wait for flushing of objects to complete. WiredTiger returns EBUSY if the timeout is reached. A value of zero disables the timeout.an integer; default 0.
)
forceif false (the default), checkpoints may be skipped if the underlying object has not been modified. If true, this option forces the checkpoint.a boolean flag; default false.
nameif set, specify a name for the checkpoint (note that checkpoints including LSM trees may not be named).a string; default empty.
targetif non-empty, checkpoint the list of objects. Checkpointing a list of objects separately from a database-wide checkpoint can lead to data inconsistencies; see Checkpointing specific objects for more information.a list of strings; default empty.
use_timestampif true (the default), create the checkpoint as of the last stable timestamp if timestamps are in use, or with all committed updates if there is no stable timestamp set. If false, always generate a checkpoint with all committed updates, ignoring any stable timestamp.a boolean flag; default true.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_backup.c, ex_backup_block.c, and ex_stat.c.

◆ close()

int WT_SESSION::close ( WT_SESSION session,
const char *  config 
)

Close the session handle.

This will release the resources associated with the session handle, including rolling back any active transactions and closing any cursors that remain open in the session.

error_check(session->close(session, NULL));
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_log.c, and ex_thread.c.

◆ commit_transaction()

int WT_SESSION::commit_transaction ( WT_SESSION session,
const char *  config 
)

Commit the current transaction.

A transaction must be in progress when this method is called.

If WT_SESSION::commit_transaction returns an error, the transaction was rolled back, not committed, and all cursors associated with the session are reset.

This method must be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in either case, subsequent
* operations are included in the transaction. Opening cursors before the transaction begins
* allows applications to cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if commit_transaction fails,
* the transaction was rolled-back and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all cursors. */
break;
}
/*
* Cursors remain open and may be used for multiple transactions.
*/
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
commit_timestampset the commit timestamp for the current transaction. For non-prepared transactions, the value must not be older than the first commit timestamp already set for the current transaction (if any), must not be older than the current oldest timestamp, and must be after the current stable timestamp. For prepared transactions, a commit timestamp is required, must not be older than the prepare timestamp, and can be set only once. See Managing the transaction timestamp state and Using transaction prepare with timestamps.a string; default empty.
durable_timestampset the durable timestamp for the current transaction. Required for the commit of a prepared transaction, and otherwise not permitted. The value must also be after the current oldest and stable timestamps and must not be older than the commit timestamp. See Using transaction prepare with timestamps.a string; default empty.
operation_timeout_mswhen non-zero, a requested limit on the time taken to complete operations in this transaction. Time is measured in real time milliseconds from the start of each WiredTiger API call. There is no guarantee any operation will not take longer than this amount of time. If WiredTiger notices the limit has been exceeded, an operation may return a WT_ROLLBACK error. Default is to have no limit.an integer greater than or equal to 1; default 0.
syncoverride whether to sync log records when the transaction commits. The default is inherited from wiredtiger_open transaction_sync. The off setting does not wait for records to be written or synchronized. The on setting forces log records to be written to the storage device.a string, chosen from the following options: "off", "on"; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_log.c.

◆ compact()

int WT_SESSION::compact ( WT_SESSION session,
const char *  name,
const char *  config 
)

Compact a live row- or column-store btree or LSM tree.

error_check(session->compact(session, "table:mytable", NULL));
Parameters
sessionthe session handle
namethe URI of the object to compact, such as "table:stock"
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
timeoutmaximum amount of time to allow for compact in seconds. The actual amount of time spent in compact may exceed the configured value. A value of zero disables the timeout.an integer; default 1200.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ create()

int WT_SESSION::create ( WT_SESSION session,
const char *  name,
const char *  config 
)

Create a table, column group, index or file.

This method is not transactional, and will not guarantee ACID properties; see Transactional applications for more details.

error_check(session->create(session, "table:mytable", "key_format=S,value_format=S"));
Parameters
sessionthe session handle
namethe URI of the object to create, such as "table:stock". For a description of URI formats see Data Sources.
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
access_pattern_hintIt is recommended that workloads that consist primarily of updates and/or point queries specify random. Workloads that do many cursor scans through large ranges of data should specify sequential and other workloads should specify none. The option leads to an appropriate operating system advisory call where available.a string, chosen from the following options: "none", "random", "sequential"; default none.
allocation_sizethe file unit allocation size, in bytes, must be a power of two; smaller values decrease the file space required by overflow items, and the default value of 4KB is a good choice absent requirements from the operating system or storage device.an integer between 512B and 128MB; default 4KB.
app_metadataapplication-owned metadata for this object.a string; default empty.
assert = (declare timestamp usage.a set of related configuration options defined as follows.
    read_timestampif set, check that timestamps are always or never used on reads with this table, writing an error message if the policy is violated. If the library was built in diagnostic mode, drop core at the failing check.a string, chosen from the following options: "always", "never", "none"; default none.
)
block_allocationconfigure block allocation. Permitted values are "best" or "first"; the "best" configuration uses a best-fit algorithm, the "first" configuration uses a first-available algorithm during block allocation.a string, chosen from the following options: "best", "first"; default best.
block_compressorconfigure a compressor for file blocks. Permitted values are "none" or a custom compression engine name created with WT_CONNECTION::add_compressor. If WiredTiger has builtin support for "lz4", "snappy", "zlib" or "zstd" compression, these names are also available. See Compressors for more information.a string; default none.
cache_residentdo not ever evict the object's pages from cache. Not compatible with LSM tables; see Cache resident objects for more information.a boolean flag; default false.
checksumconfigure block checksums; the permitted values are on, off, uncompressed and unencrypted. The default is on, in which case all block writes include a checksum subsequently verified when the block is read. The off setting does no checksums, the uncompressed setting only checksums blocks that are not compressed, and the unencrypted setting only checksums blocks that are not encrypted. See Checksums for more information.a string, chosen from the following options: "on", "off", "uncompressed", "unencrypted"; default on.
colgroupscomma-separated list of names of column groups. Each column group is stored separately, keyed by the primary key of the table. If no column groups are specified, all columns are stored together in a single file. All value columns in the table must appear in at least one column group. Each column group must be created with a separate call to WT_SESSION::create using a colgroup: URI.a list of strings; default empty.
collatorconfigure custom collation for keys. Permitted values are "none" or a custom collator name created with WT_CONNECTION::add_collator.a string; default none.
columnslist of the column names. Comma-separated list of the form (column[,...]). For tables, the number of entries must match the total number of values in key_format and value_format. For colgroups and indices, all column names must appear in the list of columns for the table.a list of strings; default empty.
dictionarythe maximum number of unique values remembered in the Btree row-store leaf page value dictionary; see File formats and compression for more information.an integer greater than or equal to 0; default 0.
encryption = (configure an encryptor for file blocks. When a table is created, its encryptor is not implicitly used for any related indices or column groups.a set of related configuration options defined as follows.
    keyidAn identifier that identifies a unique instance of the encryptor. It is stored in clear text, and thus is available when the WiredTiger database is reopened. On the first use of a (name, keyid) combination, the WT_ENCRYPTOR::customize function is called with the keyid as an argument.a string; default empty.
    namePermitted values are "none" or a custom encryption engine name created with WT_CONNECTION::add_encryptor. See Encryptors for more information.a string; default none.
)
exclusivefail if the object exists. When false (the default), if the object exists, check that its settings match the specified configuration.a boolean flag; default false.
extractorconfigure a custom extractor for indices. Permitted values are "none" or an extractor name created with WT_CONNECTION::add_extractor.a string; default none.
formatthe file format.a string, chosen from the following options: "btree"; default btree.
huffman_keyThis option is no longer supported, retained for backward compatibility.a string; default none.
huffman_valueconfigure Huffman encoding for values. Permitted values are "none", "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information.a string; default none.
ignore_in_memory_cache_sizeallow update and insert operations to proceed even if the cache is already at capacity. Only valid in conjunction with in-memory databases. Should be used with caution - this configuration allows WiredTiger to consume memory over the configured cache limit.a boolean flag; default false.
immutableconfigure the index to be immutable – that is, the index is not changed by any update to a record in the table.a boolean flag; default false.
import = (configure import of an existing object into the currently running database.a set of related configuration options defined as follows.
    compare_timestampallow importing files with timestamps smaller or equal to the configured global timestamps. Note the history of the files are not imported together and thus snapshot read of historical data will not work with the option "stable_timestamp". (The oldest and stable arguments are deprecated short-hand for oldest_timestamp and stable_timestamp, respectively).a string, chosen from the following options: "oldest", "oldest_timestamp", "stable", "stable_timestamp"; default oldest_timestamp.
     enabledwhether to import the input URI from disk.a boolean flag; default false.
    file_metadatathe file configuration extracted from the metadata of the export database.a string; default empty.
    metadata_filea text file that contains all the relevant metadata information for the URI to import. The file is generated by backup:export cursor.a string; default empty.
    repairwhether to reconstruct the metadata from the raw file content.a boolean flag; default false.
)
internal_key_maxThis option is no longer supported, retained for backward compatibility.an integer greater than or equal to 0; default 0.
internal_key_truncateconfigure internal key truncation, discarding unnecessary trailing bytes on internal keys (ignored for custom collators).a boolean flag; default true.
internal_page_maxthe maximum page size for internal nodes, in bytes; the size must be a multiple of the allocation size and is significant for applications wanting to avoid excessive L2 cache misses while searching the tree. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done.an integer between 512B and 512MB; default 4KB.
key_formatthe format of the data packed into key items. See Format types for details. By default, the key_format is 'u' and applications use WT_ITEM structures to manipulate raw byte arrays. By default, records are stored in row-store files: keys of type 'r' are record numbers and records referenced by record number are stored in column-store files.a format string; default u.
key_gapThis option is no longer supported, retained for backward compatibility.an integer greater than or equal to 0; default 10.
leaf_key_maxthe largest key stored in a leaf node, in bytes. If set, keys larger than the specified size are stored as overflow items (which may require additional I/O to access). The default value is one-tenth the size of a newly split leaf page.an integer greater than or equal to 0; default 0.
leaf_page_maxthe maximum page size for leaf nodes, in bytes; the size must be a multiple of the allocation size, and is significant for applications wanting to maximize sequential data transfer from a storage device. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done. For fixed-length column store, the size includes only the bitmap data; pages containing timestamp information can be larger, and the size is limited to 128KB rather than 512MB.an integer between 512B and 512MB; default 32KB.
leaf_value_maxthe largest value stored in a leaf node, in bytes. If set, values larger than the specified size are stored as overflow items (which may require additional I/O to access). If the size is larger than the maximum leaf page size, the page size is temporarily ignored when large values are written. The default is one-half the size of a newly split leaf page.an integer greater than or equal to 0; default 0.
log = (the transaction log configuration for this object. Only valid if log is enabled in wiredtiger_open.a set of related configuration options defined as follows.
    enabledif false, this object has checkpoint-level durability.a boolean flag; default true.
)
lsm = (options only relevant for LSM data sources.a set of related configuration options defined as follows.
    auto_throttleThrottle inserts into LSM trees if flushing to disk isn't keeping up.a boolean flag; default true.
    bloomcreate Bloom filters on LSM tree chunks as they are merged.a boolean flag; default true.
    bloom_bit_countthe number of bits used per item for LSM Bloom filters.an integer between 2 and 1000; default 16.
    bloom_configconfig string used when creating Bloom filter files, passed to WT_SESSION::create.a string; default empty.
    bloom_hash_countthe number of hash values per item used for LSM Bloom filters.an integer between 2 and 100; default 8.
    bloom_oldestcreate a Bloom filter on the oldest LSM tree chunk. Only supported if Bloom filters are enabled.a boolean flag; default false.
    chunk_count_limitthe maximum number of chunks to allow in an LSM tree. This option automatically times out old data. As new chunks are added old chunks will be removed. Enabling this option disables LSM background merges.an integer; default 0.
    chunk_maxthe maximum size a single chunk can be. Chunks larger than this size are not considered for further merges. This is a soft limit, and chunks larger than this value can be created. Must be larger than chunk_size.an integer between 100MB and 10TB; default 5GB.
    chunk_sizethe maximum size of the in-memory chunk of an LSM tree. This limit is soft, it is possible for chunks to be temporarily larger than this value. This overrides the memory_page_max setting.an integer between 512K and 500MB; default 10MB.
    merge_custom = (configure the tree to merge into a custom data source.a set of related configuration options defined as follows.
         prefixcustom data source prefix instead of "file".a string; default empty.
        start_generationmerge generation at which the custom data source is used (zero indicates no custom data source).an integer between 0 and 10; default 0.
        suffixcustom data source suffix instead of ".lsm".a string; default empty.
     )
    merge_maxthe maximum number of chunks to include in a merge operation.an integer between 2 and 100; default 15.
    merge_minthe minimum number of chunks to include in a merge operation. If set to 0 or 1 half the value of merge_max is used.an integer no more than 100; default 0.
)
memory_page_image_maxthe maximum in-memory page image represented by a single storage block. Depending on compression efficiency, compression can create storage blocks which require significant resources to re-instantiate in the cache, penalizing the performance of future point updates. The value limits the maximum in-memory page image a storage block will need. If set to 0, a default of 4 times leaf_page_max is used.an integer greater than or equal to 0; default 0.
memory_page_maxthe maximum size a page can grow to in memory before being reconciled to disk. The specified size will be adjusted to a lower bound of leaf_page_max, and an upper bound of cache_size / 10. This limit is soft - it is possible for pages to be temporarily larger than this value. This setting is ignored for LSM trees, see chunk_size.an integer between 512B and 10TB; default 5MB.
os_cache_dirty_maxmaximum dirty system buffer cache usage, in bytes. If non-zero, schedule writes for dirty blocks belonging to this object in the system buffer cache after that many bytes from this object are written into the buffer cache.an integer greater than or equal to 0; default 0.
os_cache_maxmaximum system buffer cache usage, in bytes. If non-zero, evict object blocks from the system buffer cache after that many bytes from this object are read or written into the buffer cache.an integer greater than or equal to 0; default 0.
prefix_compressionconfigure prefix compression on row-store leaf pages.a boolean flag; default false.
prefix_compression_minminimum gain before prefix compression will be used on row-store leaf pages.an integer greater than or equal to 0; default 4.
split_pctthe Btree page split size as a percentage of the maximum Btree page size, that is, when a Btree page is split, it will be split into smaller pages, where each page is the specified percentage of the maximum Btree page size.an integer between 50 and 100; default 90.
tiered_storage = (configure a storage source for this table.a set of related configuration options defined as follows.
    auth_tokenauthentication string identifier.a string; default empty.
    bucketthe bucket indicating the location for this table.a string; default empty.
    bucket_prefixthe unique bucket prefix for this table.a string; default empty.
    cache_directorya directory to store locally cached versions of files in the storage source. By default, it is named with "-cache" appended to the bucket name. A relative directory name is relative to the home directory.a string; default empty.
    local_retentiontime in seconds to retain data on tiered storage on the local tier for faster read access.an integer between 0 and 10000; default 300.
    namepermitted values are "none" or a custom storage source name created with WT_CONNECTION::add_storage_source. See Custom Tiered Storage sources for more information.a string; default none.
)
typeset the type of data source used to store a column group, index or simple table. By default, a "file:" URI is derived from the object name. The type configuration can be used to switch to a different data source, such as LSM or an extension configured by the application.a string; default file.
value_formatthe format of the data packed into value items. See Format types for details. By default, the value_format is 'u' and applications use a WT_ITEM structure to manipulate raw byte arrays. Value items of type 't' are bitfields, and when configured with record number type keys, will be stored using a fixed-length store.a format string; default u.
write_timestamp_usagedescribe how timestamps are expected to be used on table modifications. The choices are the default, which ensures that once timestamps are used for a key, they are always used, and also that multiple updates to a key never use decreasing timestamps and never which enforces that timestamps are never used for a table. (The always, key_consistent, mixed_mode and ordered choices should not be used, and are retained for backward compatibility.).a string, chosen from the following options: "always", "key_consistent", "mixed_mode", "never", "none", "ordered"; default none.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_access.c, ex_backup.c, ex_backup_block.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extractor.c, ex_file_system.c, ex_log.c, ex_schema.c, ex_stat.c, and ex_thread.c.

◆ drop()

int WT_SESSION::drop ( WT_SESSION session,
const char *  name,
const char *  config 
)

Drop (delete) a table.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

This method is not transactional, and will not guarantee ACID properties; see Transactional applications for more details.

error_check(session->drop(session, "table:mytable", NULL));
Parameters
sessionthe session handle
namethe URI of the object to drop, such as "table:stock"
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
forcereturn success if the object does not exist.a boolean flag; default false.
remove_filesif the underlying files should be removed.a boolean flag; default true.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

◆ join()

int WT_SESSION::join ( WT_SESSION session,
WT_CURSOR join_cursor,
WT_CURSOR ref_cursor,
const char *  config 
)

Join a join cursor with a reference cursor.

/* Open cursors needed by the join. */
error_check(session->open_cursor(session, "join:table:poptable", NULL, NULL, &join_cursor));
error_check(
session->open_cursor(session, "index:poptable:country", NULL, NULL, &country_cursor));
error_check(
session->open_cursor(session, "index:poptable:immutable_year", NULL, NULL, &year_cursor));
/* select values WHERE country == "AU" AND year > 1900 */
country_cursor->set_key(country_cursor, "AU\0\0\0");
error_check(country_cursor->search(country_cursor));
error_check(session->join(session, join_cursor, country_cursor, "compare=eq,count=10"));
year_cursor->set_key(year_cursor, (uint16_t)1900);
error_check(year_cursor->search(year_cursor));
error_check(
session->join(session, join_cursor, year_cursor, "compare=gt,count=10,strategy=bloom"));
/* List the values that are joined */
while ((ret = join_cursor->next(join_cursor)) == 0) {
error_check(join_cursor->get_key(join_cursor, &recno));
error_check(join_cursor->get_value(join_cursor, &country, &year, &population));
printf("ID %" PRIu64, recno);
printf(
": country %s, year %" PRIu16 ", population %" PRIu64 "\n", country, year, population);
}
scan_end_check(ret == WT_NOTFOUND);
Parameters
sessionthe session handle
join_cursora cursor that was opened using a "join:" URI. It may not have been used for any operations other than other join calls.
ref_cursoran index cursor having the same base table as the join_cursor, or a table cursor open on the same base table, or another join cursor. Unless the ref_cursor is another join cursor, it must be positioned.

The ref_cursor limits the results seen by iterating the join_cursor to table items referred to by the key in this index. The set of keys referred to is modified by the compare config option.

Multiple join calls builds up a set of ref_cursors, and by default, the results seen by iteration are the intersection of the cursor ranges participating in the join. When configured with "operation=or", the results seen are the union of the participating cursor ranges.

After the join call completes, the ref_cursor cursor may not be used for any purpose other than get_key and get_value. Any other cursor method (e.g. next, prev,close) will fail. When the join_cursor is closed, the ref_cursor is made available for general use again. The application should close ref_cursor when finished with it, although not before the join_cursor is closed.

Parameters
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
bloom_bit_countthe number of bits used per item for the Bloom filter.an integer between 2 and 1000; default 16.
bloom_false_positivesreturn all values that pass the Bloom filter, without eliminating any false positives.a boolean flag; default false.
bloom_hash_countthe number of hash values per item for the Bloom filter.an integer between 2 and 100; default 8.
comparemodifies the set of items to be returned so that the index key satisfies the given comparison relative to the key set in this cursor.a string, chosen from the following options: "eq", "ge", "gt", "le", "lt"; default "eq".
countset an approximate count of the elements that would be included in the join. This is used in sizing the Bloom filter, and also influences evaluation order for cursors in the join. When the count is equal for multiple Bloom filters in a composition of joins, the Bloom filter may be shared.an integer; default 0.
operationthe operation applied between this and other joined cursors. When "operation=and" is specified, all the conditions implied by joins must be satisfied for an entry to be returned by the join cursor; when "operation=or" is specified, only one must be satisfied. All cursors joined to a join cursor must have matching operations.a string, chosen from the following options: "and", "or"; default "and".
strategywhen set to bloom, a Bloom filter is created and populated for this index. This has an up front cost but may reduce the number of accesses to the main table when iterating the joined cursor. The bloom setting requires that count be set.a string, chosen from the following options: "bloom", "default"; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_col_store.c, ex_schema.c, and ex_stat.c.

◆ log_flush()

int WT_SESSION::log_flush ( WT_SESSION session,
const char *  config 
)

Flush the log.

WT_SESSION::log_flush will fail if logging is not enabled.

Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
syncforcibly flush the log and wait for it to achieve the synchronization level specified. The off setting forces any buffered log records to be written to the file system. The on setting forces log records to be written to the storage device.a string, chosen from the following options: "off", "on"; default on.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ log_printf()

int WT_SESSION::log_printf ( WT_SESSION session,
const char *  format,
  ... 
)

Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called).

Parameters
sessionthe session handle
formata printf format specifier
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_encrypt.c, and ex_log.c.

◆ open_cursor()

int WT_SESSION::open_cursor ( WT_SESSION session,
const char *  uri,
WT_CURSOR to_dup,
const char *  config,
WT_CURSOR **  cursorp 
)

Open a new cursor on a data source or duplicate an existing cursor.

error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));

An existing cursor can be duplicated by passing it as the to_dup parameter and setting the uri parameter to NULL:

error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
cursor->set_key(cursor, key);
error_check(cursor->search(cursor));
/* Duplicate the cursor. */
error_check(session->open_cursor(session, NULL, cursor, NULL, &duplicate));

Cursors being duplicated must have a key set, and successfully duplicated cursors are positioned at the same place in the data source as the original.

Cursor handles should be discarded by calling WT_CURSOR::close.

Cursors capable of supporting transactional operations operate in the context of the current transaction, if any.

WT_SESSION::rollback_transaction implicitly resets all cursors associated with the session.

Cursors are relatively light-weight objects but may hold references to heavier-weight objects; applications should re-use cursors when possible, but instantiating new cursors is not so expensive that applications need to cache cursors at all cost.

Parameters
sessionthe session handle
urithe data source on which the cursor operates; cursors are usually opened on tables, however, cursors can be opened on any data source, regardless of whether it is ultimately stored in a table. Some cursor types may have limited functionality (for example, they may be read-only or not support transactional updates). See Data Sources for more information.

The following are the builtin basic cursor types:

URITypeNotes
table:<table name>[<projection>]table cursortable key, table value(s) with optional projection of columns
colgroup:<table name>:<column group name>column group cursortable key, column group value(s)
index:<table name>:<index name>[<projection>]index cursorkey=index key, value=table value(s) with optional projection of columns
join:table:<table name>[<projection>]join cursorkey=table key, value=table value(s) with optional projection of columns

Some administrative tasks can be accomplished using the following special cursor types that give access to data managed by WiredTiger:

URITypeNotes
backup:backup cursorkey=string, see Backups for details
backup:exportexport cursor that generates a text file WiredTiger.export. The file contains metadata for all objects in the database. It can be used in the import process as the value for metadata_file configuration optionkey=string, see Export tables using backup cursor for details
backup:query_idbackup cursor that only returns block incremental idskey=string, see Backups for details
log:log cursorkey=(long fileID, long offset, int seqno),
value=(uint64_t txnid, uint32_t rectype,
uint32_t optype, uint32_t fileid,
WT_ITEM key, WT_ITEM value)
,
see Log cursors for details
metadata:[create]metadata cursor (optionally only returning configuration strings for WT_SESSION::create if create is appended)key=string, value=string,
see Reading WiredTiger Metadata for details
statistics:[<data source URI>]database, data source, join or session statistics cursorkey=int id,
value=(string description, string value, uint64_t value),
see Statistics Data for details

Advanced applications may also open the following low-level cursor types:

URITypeNotes
file:<file name>file cursorfile key, file value(s)
lsm:<name>LSM cursor (key=LSM key, value=LSM value)LSM key, LSM value,
see Log-Structured Merge Trees
Parameters
to_dupa cursor to duplicate or gather statistics on
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
appendappend written values as new records, giving each a new record number key; valid only for cursors with record number keys.a boolean flag; default false.
bulkconfigure the cursor for bulk-loading, a fast, initial load path (see Bulk-load for more information). Bulk-load may only be used for newly created objects and applications should use the WT_CURSOR::insert method to insert rows. When bulk-loading, rows must be loaded in sorted order. The value is usually a true/false flag; when bulk-loading fixed-length column store objects, the special value bitmap allows chunks of a memory resident bitmap to be loaded directly into a file by passing a WT_ITEM to WT_CURSOR::set_value where the size field indicates the number of records in the bitmap (as specified by the object's value_format configuration). Bulk-loaded bitmap values must end on a byte boundary relative to the bit count (except for the last set of values loaded).a string; default false.
checkpointthe name of a checkpoint to open. (The reserved name "WiredTigerCheckpoint" opens the most recent checkpoint taken for the object.) The cursor does not support data modification.a string; default empty.
debug = (configure debug specific behavior on a cursor. Generally only used for internal testing purposes.a set of related configuration options defined as follows.
    dump_versionopen a version cursor, which is a debug cursor on a table that enables iteration through the history of values for a given key.a boolean flag; default false.
     release_evictConfigure the cursor to evict the page positioned on when the reset API call is used.a boolean flag; default false.
)
dumpconfigure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "json" selects a JSON format with each record formatted as fields named by column names if available, "pretty" selects a human-readable format (making it incompatible with the "load"), "pretty_hex" is similar to "pretty" (also incompatible with "load") except raw byte data elements will be printed like "hex" format, and "print" selects a format where only non-printing characters are hexadecimal encoded. These formats are compatible with the wt dump and wt load commands.a string, chosen from the following options: "hex", "json", "pretty", "pretty_hex", "print"; default empty.
incremental = (configure the cursor for block incremental backup usage. These formats are only compatible with the backup data source; see Backups.a set of related configuration options defined as follows.
     consolidatecauses block incremental backup information to be consolidated if adjacent granularity blocks are modified. If false, information will be returned in granularity sized blocks only. This must be set on the primary backup cursor and it applies to all files for this backup.a boolean flag; default false.
    enabledwhether to configure this backup as the starting point for a subsequent incremental backup.a boolean flag; default false.
    filethe file name when opening a duplicate incremental backup cursor. That duplicate cursor will return the block modifications relevant to the given file name.a string; default empty.
    force_stopcauses all block incremental backup information to be released. This is on an open_cursor call and the resources will be released when this cursor is closed. No other operations should be done on this open cursor.a boolean flag; default false.
    granularitythis setting manages the granularity of how WiredTiger maintains modification maps internally. The larger the granularity, the smaller amount of information WiredTiger need to maintain.an integer between 4KB and 2GB; default 16MB.
    src_ida string that identifies a previous checkpoint backup source as the source of this incremental backup. This identifier must have already been created by use of the 'this_id' configuration in an earlier backup. A source id is required to begin an incremental backup.a string; default empty.
    this_ida string that identifies the current system state as a future backup source for an incremental backup via src_id. This identifier is required when opening an incremental backup cursor and an error will be returned if one is not provided. The identifiers can be any text string, but should be unique.a string; default empty.
)
next_randomconfigure the cursor to return a pseudo-random record from the object when the WT_CURSOR::next method is called; valid only for row-store cursors. See Cursor random for details.a boolean flag; default false.
next_random_sample_sizecursors configured by next_random to return pseudo-random records from the object randomly select from the entire object, by default. Setting next_random_sample_size to a non-zero value sets the number of samples the application expects to take using the next_random cursor. A cursor configured with both next_random and next_random_sample_size attempts to divide the object into next_random_sample_size equal-sized pieces, and each retrieval returns a record from one of those pieces. See Cursor random for details.a string; default 0.
overwriteconfigures whether the cursor's insert and update methods check the existing state of the record. If overwrite is false, WT_CURSOR::insert fails with WT_DUPLICATE_KEY if the record exists, and WT_CURSOR::update fails with WT_NOTFOUND if the record does not exist.a boolean flag; default true.
rawignore the encodings for the key and value, manage data as if the formats were "u". See Raw mode for details.a boolean flag; default false.
read_onceresults that are brought into cache from disk by this cursor will be given less priority in the cache.a boolean flag; default false.
readonlyonly query operations are supported by this cursor. An error is returned if a modification is attempted using the cursor. The default is false for all cursor types except for metadata cursors and checkpoint cursors.a boolean flag; default false.
statisticsSpecify the statistics to be gathered. Choosing "all" gathers statistics regardless of cost and may include traversing on-disk files; "fast" gathers a subset of relatively inexpensive statistics. The selection must agree with the database statistics configuration specified to wiredtiger_open or WT_CONNECTION::reconfigure. For example, "all" or "fast" can be configured when the database is configured with "all", but the cursor open will fail if "all" is specified when the database is configured with "fast", and the cursor open will fail in all cases when the database is configured with "none". If "size" is configured, only the underlying size of the object on disk is filled in and the object is not opened. If statistics is not configured, the default configuration is the database configuration. The "clear" configuration resets statistics after gathering them, where appropriate (for example, a cache size statistic is not cleared, while the count of cursor insert operations will be cleared). See Statistics for more information.a list, with values chosen from the following options: "all", "cache_walk", "fast", "clear", "size", "tree_walk"; default empty.
targetif non-empty, back up the given list of objects; valid only for a backup data source.a list of strings; default empty.
[out]cursorpa pointer to the newly opened cursor
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_access.c, ex_backup.c, ex_backup_block.c, ex_call_center.c, ex_col_store.c, ex_cursor.c, ex_encrypt.c, ex_extractor.c, ex_file_system.c, ex_log.c, ex_schema.c, ex_stat.c, and ex_thread.c.

◆ prepare_transaction()

int WT_SESSION::prepare_transaction ( WT_SESSION session,
const char *  config 
)

Prepare the current transaction.

A transaction must be in progress when this method is called.

Preparing a transaction will guarantee a subsequent commit will succeed. Only commit and rollback are allowed on a transaction after it has been prepared. The transaction prepare API is designed to support MongoDB exclusively, and guarantees update conflicts have been resolved, but does not guarantee durability.

This method must be called on a session with an active transaction.

/*
* Prepare a transaction which guarantees a subsequent commit will succeed. Only commit and
* rollback are allowed on a transaction after it has been prepared.
*/
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
error_check(session->prepare_transaction(session, "prepare_timestamp=2a"));
error_check(
session->commit_transaction(session, "commit_timestamp=2b,durable_timestamp=2b"));
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
prepare_timestampset the prepare timestamp for the updates of the current transaction. The value must not be older than any active read timestamps, and must be newer than the current stable timestamp. See Using transaction prepare with timestamps.a string; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ query_timestamp()

int WT_SESSION::query_timestamp ( WT_SESSION session,
char *  hex_timestamp,
const char *  config 
)

Query the session's transaction timestamp state.

The WT_SESSION.query_timestamp method can only be used at snapshot isolation.

Parameters
sessionthe session handle
[out]hex_timestampa buffer that will be set to the hexadecimal encoding of the timestamp being queried. Must be large enough to hold a NUL terminated, hex-encoded 8B timestamp (17 bytes).
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
getspecify which timestamp to query: commit returns the most recently set commit_timestamp; first_commit returns the first set commit_timestamp; prepare returns the timestamp used in preparing a transaction; read returns the timestamp at which the transaction is reading. See Managing the transaction timestamp state.a string, chosen from the following options: "commit", "first_commit", "prepare", "read"; default read.

A timestamp of 0 is returned if the timestamp is not available or has not been set.

Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ reconfigure()

int WT_SESSION::reconfigure ( WT_SESSION session,
const char *  config 
)

Reconfigure a session handle.

Only configurations listed in the method arguments are modified, other configurations remain in their current state. This method additionally resets the cursors associated with the session. WT_SESSION::reconfigure will fail if a transaction is in progress in the session.

error_check(session->reconfigure(session, "isolation=snapshot"));
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
cache_cursorsenable caching of cursors for reuse. Any calls to WT_CURSOR::close for a cursor created in this session will mark the cursor as cached and keep it available to be reused for later calls to WT_SESSION::open_cursor. Cached cursors may be eventually closed. This value is inherited from wiredtiger_open cache_cursors.a boolean flag; default true.
cache_max_wait_msthe maximum number of milliseconds an application thread will wait for space to be available in cache before giving up. Default value will be the global setting of the connection config.an integer greater than or equal to 0; default 0.
debug = (configure debug specific behavior on a session. Generally only used for internal testing purposes.a set of related configuration options defined as follows.
    release_evict_pageConfigure the session to evict the page when it is released and no longer needed.a boolean flag; default false.
)
ignore_cache_sizewhen set, operations performed by this session ignore the cache size and are not blocked when the cache is full. Note that use of this option for operations that create cache pressure can starve ordinary sessions that obey the cache size.a boolean flag; default false.
isolationthe default isolation level for operations in this session.a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default snapshot.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ rename()

int WT_SESSION::rename ( WT_SESSION session,
const char *  uri,
const char *  newuri,
const char *  config 
)

Rename an object.

This method is not transactional, and will not guarantee ACID properties; see Transactional applications for more details.

error_check(session->rename(session, "table:old", "table:new", NULL));

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

Parameters
sessionthe session handle
urithe current URI of the object, such as "table:old"
newurithe new URI of the object, such as "table:new"
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

◆ reset()

int WT_SESSION::reset ( WT_SESSION session)

Reset the session handle.

This method resets the cursors associated with the session, clears session statistics and discards cached resources. No session configurations are modified (or reset to their default values). WT_SESSION::reset will fail if a transaction is in progress in the session.

error_check(session->reset(session));
Parameters
sessionthe session handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ reset_snapshot()

int WT_SESSION::reset_snapshot ( WT_SESSION session)

Reset the snapshot used for database visibility.

For transactions running with snapshot isolation, this method releases the existing snapshot of the database and gets a new one. This makes newer commits visible. The call can be used to avoid pinning old and no-longer-needed content in the database. Applications not using read timestamps for search may see different results after the snapshot is updated.

It is an error to call this method when using an isolation level other than snapshot isolation, or if the current transaction has already written any data.

This method must be called on a session with an active transaction.

/*
* Get a new read snapshot for the current transaction. This is only permitted for
* transactions running with snapshot isolation.
*/
const char *value1, *value2; /* For the cursor's string value. */
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, "isolation=snapshot"));
cursor->set_key(cursor, "some-key");
error_check(cursor->search(cursor));
error_check(cursor->get_value(cursor, &value1));
error_check(session->reset_snapshot(session));
error_check(cursor->get_value(cursor, &value2)); /* May be different. */
error_check(session->commit_transaction(session, NULL));
Parameters
sessionthe session handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ rollback_transaction()

int WT_SESSION::rollback_transaction ( WT_SESSION session,
const char *  config 
)

Roll back the current transaction.

A transaction must be in progress when this method is called.

All cursors associated with the session are reset.

This method must be called on a session with an active transaction.

/*
* Cursors may be opened before or after the transaction begins, and in either case, subsequent
* operations are included in the transaction. Opening cursors before the transaction begins
* allows applications to cache cursors and use them for multiple operations.
*/
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &cursor));
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (cursor->update(cursor)) {
case 0: /* Update success */
error_check(session->commit_transaction(session, NULL));
/*
* If commit_transaction succeeds, cursors remain positioned; if commit_transaction fails,
* the transaction was rolled-back and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
error_check(session->rollback_transaction(session, NULL));
/* The rollback_transaction call resets all cursors. */
break;
}
/*
* Cursors remain open and may be used for multiple transactions.
*/
Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
operation_timeout_mswhen non-zero, a requested limit on the time taken to complete operations in this transaction. Time is measured in real time milliseconds from the start of each WiredTiger API call. There is no guarantee any operation will not take longer than this amount of time. If WiredTiger notices the limit has been exceeded, an operation may return a WT_ROLLBACK error. Default is to have no limit.an integer greater than or equal to 1; default 0.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ salvage()

int WT_SESSION::salvage ( WT_SESSION session,
const char *  name,
const char *  config 
)

Salvage a table.

Salvage rebuilds the file or files which comprise a table, discarding any corrupted file blocks.

When salvage is done, previously deleted records may re-appear, and inserted records may disappear, so salvage should not be run unless it is known to be necessary. Normally, salvage should be called after a table or file has been corrupted, as reported by the WT_SESSION::verify method.

Files are rebuilt in place. The salvage method overwrites the existing files.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

error_check(session->salvage(session, "table:mytable", NULL));
Parameters
sessionthe session handle
namethe URI of the table or file to salvage
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
forceforce salvage even of files that do not appear to be WiredTiger files.a boolean flag; default false.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

◆ strerror()

const char* WT_SESSION::strerror ( WT_SESSION session,
int  error 
)

Return information about an error as a string.

const char *key = "non-existent key";
cursor->set_key(cursor, key);
if ((ret = cursor->remove(cursor)) != 0)
fprintf(stderr, "cursor.remove: %s\n", cursor->session->strerror(cursor->session, ret));
Parameters
sessionthe session handle
errora return value from a WiredTiger, ISO C, or POSIX standard API call
Returns
a string representation of the error
Examples
ex_thread.c.

◆ timestamp_transaction()

int WT_SESSION::timestamp_transaction ( WT_SESSION session,
const char *  config 
)

Set a timestamp on a transaction.

The WT_SESSION.timestamp_transaction method can only be used at snapshot isolation.

error_check(session->timestamp_transaction(session, "commit_timestamp=2a"));

This method must be called on a session with an active transaction.

Parameters
sessionthe session handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
commit_timestampset the commit timestamp for the current transaction. For non-prepared transactions, the value must not be older than the first commit timestamp already set for the current transaction, if any, must not be older than the current oldest timestamp and must be after the current stable timestamp. For prepared transactions, a commit timestamp is required, must not be older than the prepare timestamp, can be set only once, and must not be set until after the transaction has successfully prepared. See Managing the transaction timestamp state and Using transaction prepare with timestamps.a string; default empty.
durable_timestampset the durable timestamp for the current transaction. Required for the commit of a prepared transaction, and otherwise not permitted. Can only be set after the transaction has been prepared and a commit timestamp has been set. The value must be after the current oldest and stable timestamps and must not be older than the commit timestamp. See Using transaction prepare with timestamps.a string; default empty.
prepare_timestampset the prepare timestamp for the updates of the current transaction. The value must not be older than any active read timestamps, and must be newer than the current stable timestamp. Can be set only once per transaction. Setting the prepare timestamp does not by itself prepare the transaction, but does oblige the application to eventually prepare the transaction before committing it. See Using transaction prepare with timestamps.a string; default empty.
read_timestampread using the specified timestamp. The value must not be older than the current oldest timestamp. This can only be set once for a transaction. See Managing the transaction timestamp state.a string; default empty.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ timestamp_transaction_uint()

int WT_SESSION::timestamp_transaction_uint ( WT_SESSION session,
WT_TS_TXN_TYPE  which,
uint64_t  ts 
)

Set a timestamp on a transaction numerically.

Prefer this method over WT_SESSION::timestamp_transaction if the hexadecimal string parsing done in that method becomes a bottleneck.

The WT_SESSION.timestamp_transaction_uint method can only be used at snapshot isolation.

error_check(session->timestamp_transaction_uint(session, WT_TS_TXN_TYPE_COMMIT, 42));

This method must be called on a session with an active transaction.

Parameters
sessionthe session handle
whichthe timestamp being set (see WT_TS_TXN_TYPE for available options, and WT_SESSION::timestamp_transaction for constraints on the timestamps).
tsthe timestamp.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ transaction_pinned_range()

int WT_SESSION::transaction_pinned_range ( WT_SESSION session,
uint64_t *  range 
)

Return the transaction ID range pinned by the session handle.

The ID range is an approximate count of transactions and is calculated based on the oldest ID needed for the active transaction in this session, compared to the newest transaction in the system.

/* Check the transaction ID range pinned by the session handle. */
uint64_t range;
error_check(session->transaction_pinned_range(session, &range));
Parameters
sessionthe session handle
[out]rangethe range of IDs pinned by this session. Zero if there is no active transaction.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ truncate()

int WT_SESSION::truncate ( WT_SESSION session,
const char *  name,
WT_CURSOR start,
WT_CURSOR stop,
const char *  config 
)

Truncate a file, table, cursor range, or backup cursor.

Truncate a table or file.

error_check(session->truncate(session, "table:mytable", NULL, NULL, NULL));

Truncate a cursor range. When truncating based on a cursor position, it is not required the cursor reference a record in the object, only that the key be set. This allows applications to discard portions of the object name space without knowing exactly what records the object contains. The start and stop points are both inclusive; that is, the key set in the start cursor is the first record to be deleted and the key set in the stop cursor is the last.

WT_CURSOR *start, *stop;
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &start));
start->set_key(start, "June01");
error_check(start->search(start));
error_check(session->open_cursor(session, "table:mytable", NULL, NULL, &stop));
stop->set_key(stop, "June30");
error_check(stop->search(stop));
error_check(session->truncate(session, NULL, start, stop, NULL));

Range truncate is implemented as a "scan and write" operation, specifically without range locks. Inserts or other operations in the range, as well as operations before or after the range when no explicit starting or ending key is set, are not well defined: conflicts may be detected or both transactions may commit. If both commit, there's a failure and recovery runs, the result may be different than what was in cache before the crash.

The WT_CURSOR::truncate range truncate operation can only be used at snapshot isolation.

Any specified cursors end with no position, and subsequent calls to the WT_CURSOR::next (WT_CURSOR::prev) method will iterate from the beginning (end) of the table.

Example: truncate a backup cursor. This operation removes all log files that have been returned by the backup cursor. It can be used to remove log files after copying them during Log-based Incremental backup.

error_check(session->truncate(session, "log:", cursor, NULL, NULL));
Parameters
sessionthe session handle
namethe URI of the table or file to truncate, or "log:" for a backup cursor
startoptional cursor marking the first record discarded; if NULL, the truncate starts from the beginning of the object; must be provided when truncating a backup cursor
stopoptional cursor marking the last record discarded; if NULL, the truncate continues to the end of the object; ignored when truncating a backup cursor
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.
Examples
ex_backup.c.

◆ upgrade()

int WT_SESSION::upgrade ( WT_SESSION session,
const char *  name,
const char *  config 
)

Upgrade a table.

Upgrade upgrades a table or file, if upgrade is required.

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

error_check(session->upgrade(session, "table:mytable", NULL));
Parameters
sessionthe session handle
namethe URI of the table or file to upgrade
configconfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.

◆ verify()

int WT_SESSION::verify ( WT_SESSION session,
const char *  name,
const char *  config 
)

Verify a table.

Verify reports if a file, or the files that comprise a table, have been corrupted. The WT_SESSION::salvage method can be used to repair a corrupted file.

error_check(session->verify(session, "table:mytable", NULL));

This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY. See Error handling for details.

Parameters
sessionthe session handle
namethe URI of the table or file to verify, optional if verifying the history store
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
do_not_clear_txn_idTurn off transaction id clearing, intended for debugging and better diagnosis of crashes or failures.a boolean flag; default false.
dump_addressDisplay page addresses, time windows, and page types as pages are verified, using the application's message handler, intended for debugging.a boolean flag; default false.
dump_blocksDisplay the contents of on-disk blocks as they are verified, using the application's message handler, intended for debugging.a boolean flag; default false.
dump_layoutDisplay the layout of the files as they are verified, using the application's message handler, intended for debugging; requires optional support from the block manager.a boolean flag; default false.
dump_offsetsDisplay the contents of specific on-disk blocks, using the application's message handler, intended for debugging.a list of strings; default empty.
dump_pagesDisplay the contents of in-memory pages as they are verified, using the application's message handler, intended for debugging.a boolean flag; default false.
read_corruptA mode that allows verify to continue reading after encountering a checksum error. It will skip past the corrupt block and continue with the verification process.a boolean flag; default false.
stable_timestampEnsure that no data has a start timestamp after the stable timestamp, to be run after rollback_to_stable.a boolean flag; default false.
strictTreat any verification problem as an error; by default, verify will warn, but not fail, in the case of errors that won't affect future behavior (for example, a leaked block).a boolean flag; default false.
Returns
zero on success, EBUSY if the object is not available for exclusive access, and a non-zero error code on failure. See Error handling for details.
WT_SESSION::rollback_transaction
int rollback_transaction(WT_SESSION *session, const char *config)
Roll back the current transaction.
WT_SESSION::upgrade
int upgrade(WT_SESSION *session, const char *name, const char *config)
Upgrade a table.
WT_SESSION::close
int close(WT_SESSION *session, const char *config)
Close the session handle.
WT_SESSION::create
int create(WT_SESSION *session, const char *name, const char *config)
Create a table, column group, index or file.
WT_SESSION::timestamp_transaction
int timestamp_transaction(WT_SESSION *session, const char *config)
Set a timestamp on a transaction.
WT_ROLLBACK
#define WT_ROLLBACK
Conflict between concurrent operations.
Definition: wiredtiger.in:3905
WT_SESSION::open_cursor
int open_cursor(WT_SESSION *session, const char *uri, WT_CURSOR *to_dup, const char *config, WT_CURSOR **cursorp)
Open a new cursor on a data source or duplicate an existing cursor.
WT_SESSION::compact
int compact(WT_SESSION *session, const char *name, const char *config)
Compact a live row- or column-store btree or LSM tree.
WT_CURSOR
A WT_CURSOR handle is the interface to a cursor.
Definition: wiredtiger.in:199
WT_CURSOR::search
int search(WT_CURSOR *cursor)
Return the record matching the key.
WT_SESSION::commit_transaction
int commit_transaction(WT_SESSION *session, const char *config)
Commit the current transaction.
WT_SESSION::join
int join(WT_SESSION *session, WT_CURSOR *join_cursor, WT_CURSOR *ref_cursor, const char *config)
Join a join cursor with a reference cursor.
WT_SESSION::rename
int rename(WT_SESSION *session, const char *uri, const char *newuri, const char *config)
Rename an object.
WT_SESSION::alter
int alter(WT_SESSION *session, const char *name, const char *config)
Alter a table.
WT_SESSION::reset
int reset(WT_SESSION *session)
Reset the session handle.
WT_TS_TXN_TYPE_COMMIT
@ WT_TS_TXN_TYPE_COMMIT
Commit timestamp.
Definition: wiredtiger.in:788
WT_SESSION::salvage
int salvage(WT_SESSION *session, const char *name, const char *config)
Salvage a table.
WT_SESSION::verify
int verify(WT_SESSION *session, const char *name, const char *config)
Verify a table.
WT_SESSION::truncate
int truncate(WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config)
Truncate a file, table, cursor range, or backup cursor.
WT_SESSION::begin_transaction
int begin_transaction(WT_SESSION *session, const char *config)
Start a transaction in this session.
WT_SESSION::reconfigure
int reconfigure(WT_SESSION *session, const char *config)
Reconfigure a session handle.
WT_SESSION::checkpoint
int checkpoint(WT_SESSION *session, const char *config)
Write a transactionally consistent snapshot of a database or set of individual objects.
WT_SESSION::drop
int drop(WT_SESSION *session, const char *name, const char *config)
Drop (delete) a table.
WT_SESSION::timestamp_transaction_uint
int timestamp_transaction_uint(WT_SESSION *session, WT_TS_TXN_TYPE which, uint64_t ts)
Set a timestamp on a transaction numerically.
WT_SESSION::prepare_transaction
int prepare_transaction(WT_SESSION *session, const char *config)
Prepare the current transaction.
WT_CURSOR::set_key
void set_key(WT_CURSOR *cursor,...)
Set the key for the next operation.
WT_NOTFOUND
#define WT_NOTFOUND
Item not found.
Definition: wiredtiger.in:3926
WT_SESSION::transaction_pinned_range
int transaction_pinned_range(WT_SESSION *session, uint64_t *range)
Return the transaction ID range pinned by the session handle.
WT_SESSION::reset_snapshot
int reset_snapshot(WT_SESSION *session)
Reset the snapshot used for database visibility.