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) an object. 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 or file. 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 or file. More...
int	verify (WT_SESSION *session, const char *name, const char *config)
	Verify a table or file. 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	reset_snapshot (WT_SESSION *session)
	Reset the snapshot. More...
int	rollback_transaction (WT_SESSION *session, const char *config)
	Roll back the current transaction. More...
int	timestamp_transaction (WT_SESSION *session, const char *config)
	Set a timestamp on a transaction. More...
int	query_timestamp (WT_SESSION *session, char *hex_timestamp, const char *config)
	Query the session's transaction timestamp state. More...
int	checkpoint (WT_SESSION *session, const char *config)
	Write a transactionally consistent snapshot of a database or set of objects. More...
int	transaction_pinned_range (WT_SESSION *session, uint64_t *range)
	Return the transaction ID range pinned by the session handle. More...
int	transaction_sync (WT_SESSION *session, const char *config)
	Wait for a transaction to become synchronized. More...

Public Attributes
WT_CONNECTION *	connection
	The connection for this session. More...
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, and rotn_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.

        error_check(session->alter(session, "table:mytable", "access_pattern_hint=random"));

Parameters

session	the session handle
name	the URI of the object to alter, such as "table:stock"
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values access_pattern_hint It 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 specify sequential and other workloads specify none. The option leads to an advisory call to an appropriate operating system API where available. a string, chosen from the following options: "none", "random", "sequential"; default none. app_metadata application-owned metadata for this object. a string; default empty. cache_resident do 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 below.     enabled if false, this object has checkpoint-level durability. a boolean flag; default true. ) os_cache_dirty_max maximum 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_max maximum 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. readonly the file is read-only. All methods that may modify a file are disabled. See Database read-only mode for more information. a boolean flag; default false. verbose enable messages for various events. Options are given as a list, such as "verbose=[write_timestamp]". a list, with values chosen from the following options: "write_timestamp"; default []. write_timestamp_usage describe how timestamps are expected to be used on modifications to the table. This option should be used in conjunction with the corresponding write_timestamp configuration under the assert and verbose options to provide logging and assertions for incorrect timestamp usage. The choices are always which ensures a timestamp is used for every operation on a table, key_consistent to ensure that once timestamps are used for a key, they are always used, ordered is like key_consistent except it also enforces that subsequent updates to each key must use increasing timestamps, mixed_mode is like ordered except that updates with no timestamp are allowed and have the effect of resetting the chain of updates once the transaction ID based snapshot is no longer relevant, never enforces that timestamps are never used for a table and none does not enforce any expectation on timestamp usage meaning that no log message or assertions will be produced regardless of the corresponding assert and verbose settings. 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.

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

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values ignore_prepare whether to ignore the updates by other prepared transactions as part of read operations of this transaction. When true, forces the transaction to be read-only. Use force to ignore prepared updates and permit writes (which can cause lost updates unless the application knows something about the relationship between prepared transactions and the updates that are ignoring them). a string, chosen from the following options: "false", "force", "true"; default false. isolation the 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. name name of the transaction for tracing and debugging. a string; default empty. operation_timeout_ms when 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. priority priority of the transaction for resolving conflicts. Transactions with higher values are less likely to abort. an integer between -100 and 100; default 0. read_before_oldest allows the caller to specify a read timestamp less than the oldest timestamp but newer than or equal to the pinned timestamp. Cannot be set to true while also rounding up the read timestamp. See Application-specified Transaction Timestamps. a boolean flag; default false. read_timestamp read using the specified timestamp. The supplied value must not be older than the current oldest timestamp. See Application-specified Transaction Timestamps. a string; default empty. roundup_timestamps = ( round up timestamps of the transaction. This setting alters the visibility expected in a transaction. See Application-specified Transaction Timestamps. a set of related configuration options defined below.      prepared applicable only for prepared transactions. Indicates if the prepare timestamp and the commit timestamp of this transaction can be rounded up. If the prepare timestamp is less than the oldest timestamp, the prepare timestamp will be rounded to the oldest timestamp. If the commit timestamp is less than the prepare timestamp, the commit timestamp will be rounded up to the prepare timestamp. a boolean flag; default false.     read if the read timestamp is less than the oldest timestamp, the read timestamp will be rounded up to the oldest timestamp. a boolean flag; default false. ) sync whether 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 objects.

In the absence of transaction timestamps, the checkpoint includes all transactions committed before the checkpoint starts.

When timestamps are in use and a stable_timestamp has been set via WT_CONNECTION::set_timestamp and the checkpoint runs with use_timestamp=true (the default), updates committed with a timestamp larger than the stable_timestamp will not be included in the checkpoint for tables configured with log=(enabled=false). For tables with logging enabled, all committed changes will be included in the checkpoint (since recovery would roll them forward anyway).

Additionally, 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

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values drop specify 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. force if 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. name if set, specify a name for the checkpoint (note that checkpoints including LSM trees may not be named). a string; default empty. target if non-empty, checkpoint the list of objects. a list of strings; default empty. use_timestamp if true (the default), create the checkpoint as of the last stable timestamp if timestamps are in use, or all current updates if there is no stable timestamp set. If false, this option generates a checkpoint with all updates including those later than the 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

session	the session handle
config	configuration 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.

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

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values commit_timestamp set the commit timestamp for the current transaction. The supplied value must not be older than the first commit timestamp set for the current transaction. The value must also not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps. a string; default empty. durable_timestamp set the durable timestamp for the current transaction. The supplied value must not be older than the commit timestamp set for the current transaction. The value must also not be older than the current stable timestamp. See Application-specified Transaction Timestamps. a string; default empty. operation_timeout_ms when 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. sync override whether to sync log records when the transaction commits, inherited from wiredtiger_open transaction_sync. The background setting initiates a background synchronization intended to be used with a later call to WT_SESSION::transaction_sync. The off setting does not wait for record 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: "background", "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

session	the session handle
name	the URI of the object to compact, such as "table:stock"
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values timeout maximum 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 Transactions for more details.

    error_check(session->create(session, "table:mytable", "key_format=S,value_format=S"));

Parameters

session	the session handle
name	the URI of the object to create, such as "table:stock". For a description of URI formats see Data Sources.
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values access_pattern_hint It 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 specify sequential and other workloads specify none. The option leads to an advisory call to an appropriate operating system API where available. a string, chosen from the following options: "none", "random", "sequential"; default none. allocation_size the file unit allocation size, in bytes, must 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_metadata application-owned metadata for this object. a string; default empty. block_allocation configure 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, the "log-structure" configuration allocates a new file for each checkpoint. a string, chosen from the following options: "best", "first", "log-structured"; default best. block_compressor configure a compressor for file blocks. Permitted values are "none" or 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_resident do 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. checksum configure block checksums; permitted values are on (checksum all blocks), off (checksum no blocks) and uncompresssed (checksum only blocks which are not compressed for any reason). The uncompressed setting is for applications which can rely on decompression to fail if a block has been corrupted. a string, chosen from the following options: "on", "off", "uncompressed"; default uncompressed. colgroups comma-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. a list of strings; default empty. collator configure custom collation for keys. Permitted values are "none" or a custom collator name created with WT_CONNECTION::add_collator. a string; default none. columns list 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. dictionary the 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 below.      keyid An 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.     name Permitted values are "none" or custom encryption engine name created with WT_CONNECTION::add_encryptor. See Encryptors for more information. a string; default none. ) exclusive fail 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. extractor configure custom extractor for indices. Permitted values are "none" or an extractor name created with WT_CONNECTION::add_extractor. a string; default none. format the file format. a string, chosen from the following options: "btree"; default btree. huffman_key This option is no longer supported. Retained for backward compatibility. See Huffman Encoding for more information. a string; default none. huffman_value configure 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_size allow 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. immutable configure the index to be immutable - that is an 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 below.     enabled whether to import the input URI from disk. a boolean flag; default false.     file_metadata the file configuration extracted from the metadata of the export database. a string; default empty.     repair whether to reconstruct the metadata from the raw file content. a boolean flag; default false. ) internal_key_max the largest key stored in an internal 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 and the maximum allowed value are both one-tenth the size of a newly split internal page. an integer greater than or equal to 0; default 0. internal_key_truncate configure internal key truncation, discarding unnecessary trailing bytes on internal keys (ignored for custom collators). a boolean flag; default true. internal_page_max the 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_format the 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. leaf_key_max the 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_max the 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. an integer between 512B and 512MB; default 32KB. leaf_value_max the 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 below.     enabled if 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 below.     auto_throttle Throttle inserts into LSM trees if flushing to disk isn't keeping up. a boolean flag; default true.     bloom create bloom filters on LSM tree chunks as they are merged. a boolean flag; default true.     bloom_bit_count the number of bits used per item for LSM bloom filters. an integer between 2 and 1000; default 16.     bloom_config config string used when creating Bloom filter files, passed to WT_SESSION::create. a string; default empty.     bloom_hash_count the number of hash values per item used for LSM bloom filters. an integer between 2 and 100; default 8.     bloom_oldest create a bloom filter on the oldest LSM tree chunk. Only supported if bloom filters are enabled. a boolean flag; default false.     chunk_count_limit the 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_max the 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_size the 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 below.         prefix custom data source prefix instead of "file". a string; default empty.         start_generation merge generation at which the custom data source is used (zero indicates no custom data source). an integer between 0 and 10; default 0.         suffix custom data source suffix instead of ".lsm". a string; default empty. )     merge_max the maximum number of chunks to include in a merge operation. an integer between 2 and 100; default 15.     merge_min the 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_max the 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_max the 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_max maximum 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_max maximum 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_compression configure prefix compression on row-store leaf pages. a boolean flag; default false. prefix_compression_min minimum gain before prefix compression will be used on row-store leaf pages. an integer greater than or equal to 0; default 4. readonly the file is read-only. All methods that may modify a file are disabled. See Database read-only mode for more information. a boolean flag; default false. split_pct the 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 = ( options only relevant for tiered data sources. a set of related configuration options defined below.     chunk_size the maximum size of the hot chunk of tiered tree. This limit is soft - it is possible for chunks to be temporarily larger than this value. an integer greater than or equal to 1M; default 1GB.     tiers list of data sources to combine into a tiered storage structure. a list of strings; default empty. ) tiered_storage = ( configure a storage source for this table. a set of related configuration options defined below.     auth_token authentication string identifier. a string; default empty.     bucket The bucket indicating the location for this table. a string; default empty.     local_retention time in seconds to retain data on tiered storage on the local tier for faster read access. an integer between 0 and 10000; default 300.     name Permitted values are "none" or custom storage source name created with WT_CONNECTION::add_storage_source. See Custom Tiered Storage sources for more information. a string; default none.      object_target_size the approximate size of objects before creating them on the tiered storage tier. an integer between 100K and 10TB; default 10M. ) type set 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_format the 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. verbose enable messages for various events. Options are given as a list, such as "verbose=[write_timestamp]". a list, with values chosen from the following options: "write_timestamp"; default []. write_timestamp_usage describe how timestamps are expected to be used on modifications to the table. This option should be used in conjunction with the corresponding write_timestamp configuration under the assert and verbose options to provide logging and assertions for incorrect timestamp usage. The choices are always which ensures a timestamp is used for every operation on a table, key_consistent to ensure that once timestamps are used for a key, they are always used, ordered is like key_consistent except it also enforces that subsequent updates to each key must use increasing timestamps, mixed_mode is like ordered except that updates with no timestamp are allowed and have the effect of resetting the chain of updates once the transaction ID based snapshot is no longer relevant, never enforces that timestamps are never used for a table and none does not enforce any expectation on timestamp usage meaning that no log message or assertions will be produced regardless of the corresponding assert and verbose settings. 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) an object.

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.

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

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

Parameters

session	the session handle
name	the URI of the object to drop, such as "table:stock"
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values force return success if the object does not exist. a boolean flag; default false. remove_files if 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

session	the session handle
join_cursor	a cursor that was opened using a "join:" URI. It may not have been used for any operations other than other join calls.
ref_cursor	an 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

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values bloom_bit_count the number of bits used per item for the bloom filter. an integer between 2 and 1000; default 16. bloom_false_positives return all values that pass the bloom filter, without eliminating any false positives. a boolean flag; default false. bloom_hash_count the number of hash values per item for the bloom filter. an integer between 2 and 100; default 8. compare modifies 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". count set 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 . operation the 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". strategy when 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

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values sync forcibly flush the log and wait for it to achieve the synchronization level specified. The background setting initiates a background synchronization intended to be used with a later call to WT_SESSION::transaction_sync. 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: "background", "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

session	the session handle
format	a 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.

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

session	the session handle
uri	the 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:

URI	Type	Notes
table:<table name>[<projection>]	table cursor	table key, table value(s) with optional projection of columns
colgroup:<table name>:<column group name>	column group cursor	table key, column group value(s)
index:<table name>:<index name>[<projection>]	index cursor	key=index key, value=table value(s) with optional projection of columns
join:table:<table name>[<projection>]	join cursor	key=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:

URI	Type	Notes
backup:[query_id]	backup cursor (optionally only returning block incremental ids if query_id is appended)	key=string, see Backups for details
log:	log cursor	key=(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 cursor	key=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:

URI	Type	Notes
file:<file name>	file cursor	file 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_dup	a cursor to duplicate or gather statistics on
	config	configuration string, see Configuration Strings. Permitted values: Name Effect Values append append the value as a new record, creating a new record number key; valid only for cursors with record number keys. a boolean flag; default false. bulk configure 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. checkpoint the name of a checkpoint to open (the reserved name "WiredTigerCheckpoint" opens the most recent internal 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 below.     release_evict Configure the cursor to evict the page positioned on when the reset API is used. a boolean flag; default false. ) dump configure 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") 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", "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 below.      consolidate causes 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.     enabled whether to configure this backup as the starting point for a subsequent incremental backup. a boolean flag; default false.     file the 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_stop causes 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.     granularity this 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_id a 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_id a 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. a string; default empty. ) next_random configure 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_size cursors 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. overwrite configures whether the cursor's insert, update and remove methods check the existing state of the record. If overwrite is false, WT_CURSOR::insert fails with WT_DUPLICATE_KEY if the record exists, WT_CURSOR::update fails with WT_NOTFOUND if the record does not exist. a boolean flag; default true. raw ignore 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_once results that are brought into cache from disk by this cursor will be given less priority in the cache. a boolean flag; default false. readonly only 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. a boolean flag; default false. statistics Specify 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. target if non-empty, backup the list of objects; valid only for a backup data source. a list of strings; default empty.
[out]	cursorp	a 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

session	the session handle
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values prepare_timestamp set the prepare timestamp for the updates of the current transaction. The supplied value must not be older than any active read timestamps. See Application-specified Transaction 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.

Parameters

	session	the session handle
[out]	hex_timestamp	a 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).
	config	configuration string, see Configuration Strings. Permitted values: Name Effect Values get specify 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 at. See Application-specified Transaction Timestamps. a string, chosen from the following options: "commit", "first_commit", "prepare", "read"; default read.

Returns

zero on success and a non-zero error code on failure. See Error handling for details. If the session is not in a transaction WT_NOTFOUND will be returned.

reconfigure()

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

Reconfigure a session handle.

    error_check(session->reconfigure(session, "isolation=snapshot"));

WT_SESSION::reconfigure will fail if a transaction is in progress in the session.

All cursors are reset.

Parameters

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values cache_cursors enable 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. ignore_cache_size when 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. isolation the 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 Transactions 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.

Parameters

session	the session handle
uri	the current URI of the object, such as "table:old"
newuri	the new URI of the object, such as "table:new"
config	configuration 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 all cursors associated with this session, discards cached resources and resets session statistics. The session can be re-used immediately after this call returns. If a transaction is running on this session, then this call takes no action and return an error.

        error_check(session->reset(session));

Parameters

session

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

This method resets snapshots for snapshot isolation transactions to update their existing snapshot. It raises an error when this API is used for isolation other than snapshot isolation mode or when the session has performed any write operations. This API internally releases the current snapshot and gets the new running transactions snapshot to avoid pinning the content in the database that is no longer needed. Applications that don't use read_timestamp for the search may see different results compared to earlier with the updated snapshot.

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

        /*
         * Resets snapshots for snapshot isolation transactions to update their existing snapshot.
         * It raises an error when this API is used for isolation other than snapshot isolation
         * mode.
         */
        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(session->reset_snapshot(session));
        error_check(session->commit_transaction(session, NULL));

Parameters

session

the 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 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

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values operation_timeout_ms when 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 or file.

Salvage rebuilds the file, or files of which a table is comprised, discarding any corrupted file blocks.

Previously deleted records may re-appear, and inserted records may disappear, when salvage is done, 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.

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

Parameters

session	the session handle
name	the URI of the table or file to salvage
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values force force 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));
            return (ret);
        }

Parameters

session	the session handle
error	a return value from a WiredTiger, ISO C, or POSIX standard API

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.

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

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

Parameters

session

the session handle

config

configuration string, see Configuration Strings. Permitted values: Name Effect Values commit_timestamp set the commit timestamp for the current transaction. The supplied value must not be older than the first commit timestamp set for the current transaction. The value must also not be older than the current oldest and stable timestamps. See Application-specified Transaction Timestamps. a string; default empty. durable_timestamp set the durable timestamp for the current transaction. The supplied value must not be older than the commit timestamp set for the current transaction. The value must also not be older than the current stable timestamp. See Application-specified Transaction Timestamps. a string; default empty. prepare_timestamp set the prepare timestamp for the updates of the current transaction. The supplied value must not be older than any active read timestamps. See Application-specified Transaction Timestamps. a string; default empty. read_timestamp read using the specified timestamp. The supplied value must not be older than the current oldest timestamp. This can only be set once for a transaction. See Application-specified Transaction Timestamps. a string; default empty.

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 approximate 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

	session	the session handle
[out]	range	the 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.

transaction_sync()

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

Wait for a transaction to become synchronized.

This method is only useful when wiredtiger_open is configured with the transaction_sync setting disabled.

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

        error_check(session->transaction_sync(session, NULL));

Parameters

session	the session handle
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values timeout_ms maximum amount of time to wait for background sync to complete in milliseconds. A value of zero disables the timeout and returns immediately. an integer; default 1200000.

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.

                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));

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.

When a range truncate is in progress, and another transaction inserts a key into that range, the behavior is not well defined - a conflict may be detected or both transactions may be permitted to commit. If they do commit, and if there is a crash and recovery runs, the result may be different than what was in cache before the crash.

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

session	the session handle
name	the URI of the table or file to truncate, or "log:" for a backup cursor
start	optional 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
stop	optional cursor marking the last record discarded; if NULL, the truncate continues to the end of the object; ignored when truncating a backup cursor
config	configuration 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 or file.

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.

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

Parameters

session	the session handle
name	the URI of the table or file to upgrade
config	configuration 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 or file.

Verify reports if a file, or the files of which a table is comprised, 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.

Parameters

session	the session handle
name	the URI of the table or file to verify, optional if verifying the history store
config	configuration string, see Configuration Strings. Permitted values: Name Effect Values dump_address Display 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_blocks Display 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_layout Display 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_offsets Display the contents of specific on-disk blocks, using the application's message handler, intended for debugging. a list of strings; default empty. dump_pages Display the contents of in-memory pages as they are verified, using the application's message handler, intended for debugging. a boolean flag; default false. stable_timestamp Ensure that no data has a start timestamp after the stable timestamp, to be run after rollback_to_stable. a boolean flag; default false. strict Treat 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.

Member Data Documentation

connection

WT_CONNECTION* WT_SESSION::connection

The connection for this session.

Examples:

ex_encrypt.c.