Version 2.9.2
WT_SESSION Struct Reference

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

Public Member Functions

int alter (WT_SESSION *session, const char *name, const char *config)
 Alter a table. More...
 
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 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 *fmt,...)
 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 rebalance (WT_SESSION *session, const char *uri, const char *config)
 Rebalance a table, see Rebalance. 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 file or table. More...
 
int truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config)
 Truncate a file, table or cursor range. More...
 
int upgrade (WT_SESSION *session, const char *name, const char *config)
 Upgrade a file or table. More...
 
int verify (WT_SESSION *session, const char *name, const char *config)
 Verify a file or 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 rollback_transaction (WT_SESSION *session, const char *config)
 Roll back the current transaction. More...
 
int checkpoint (WT_SESSION *session, const char *config)
 Write a transactionally consistent snapshot of a database or set of objects. More...
 
int snapshot (WT_SESSION *session, const char *config)
 Manage named snapshot transactions. 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_CONNECTIONconnection
 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_async.c, ex_call_center.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.

ret = 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 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.
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.
Returns
zero on success and a non-zero error code on failure. See Error Returns 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.

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

/*
* 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.
*/
ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (ret = cursor->update(cursor)) {
case 0: /* Update success */
ret = session->commit_transaction(session, NULL);
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
ret = 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
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.
prioritypriority of the transaction for resolving conflicts. Transactions with higher values are less likely to abort.an integer between -100 and 100; default 0.
snapshotuse a named, in-memory snapshot, see Named Snapshots.a string; default empty.
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 Returns 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.

The checkpoint includes all transactions committed before the checkpoint starts. Additionally, checkpoints may optionally be discarded.

/* Checkpoint the database. */
ret = session->checkpoint(session, NULL);
/* Checkpoint of the database, creating a named snapshot. */
ret = session->checkpoint(session, "name=June01");
/*
* Checkpoint a list of objects.
* JSON parsing requires quoting the list of target URIs.
*/
ret = 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.
*/
ret = session->
checkpoint(session, "target=(\"table:mytable\"),name=midnight");
/* Checkpoint the database, discarding all previous snapshots. */
ret = session->checkpoint(session, "drop=(from=all)");
/* Checkpoint the database, discarding the "midnight" snapshot. */
ret = session->checkpoint(session, "drop=(midnight)");
/*
* Checkpoint the database, discarding all snapshots after and
* including "noon".
*/
ret = session->checkpoint(session, "drop=(from=noon)");
/*
* Checkpoint the database, discarding all snapshots before and
* including "midnight".
*/
ret = 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.
*/
ret = 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 while a hot backup is in progress or if open in a cursor.a list of strings; default empty.
forceby default, checkpoints may be skipped if the underlying object has not been modified, 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.a list of strings; default empty.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
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.

ret = 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 Returns 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.

/*
* 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.
*/
ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (ret = cursor->update(cursor)) {
case 0: /* Update success */
ret = session->commit_transaction(session, NULL);
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
ret = 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
syncoverride 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 Returns 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.

ret = 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 Returns for details.

◆ create()

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

Create a table, column group, index or file.

ret = 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 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_sizethe 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_metadataapplication-owned metadata for this object.a string; default empty.
block_allocationconfigure block allocation. Permitted values are "first" or "best"; the "first" configuration uses a first-available algorithm during block allocation, the "best" configuration uses a best-fit algorithm.a string, chosen from the following options: "first", "best"; default best.
block_compressorconfigure 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_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; 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.
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.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 below.
    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 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 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_keyconfigure Huffman encoding for keys. Permitted values are "none", "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information.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 an index is not changed by any update to a record in the table.a boolean flag; default false.
internal_key_maxthe 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_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.
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.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 below.
    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 below.
    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_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_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.
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.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_access.c, ex_async.c, ex_call_center.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.

ret = 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_filesshould the underlying files be removed?.a boolean flag; default true.
Returns
zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns 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. */
ret = session->open_cursor(session,
"join:table:poptable", NULL, NULL, &join_cursor);
ret = session->open_cursor(session,
"index:poptable:country", NULL, NULL, &country_cursor);
ret = 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");
ret = country_cursor->search(country_cursor);
ret = session->join(session, join_cursor, country_cursor,
"compare=eq,count=10");
year_cursor->set_key(year_cursor, (uint16_t)1900);
ret = year_cursor->search(year_cursor);
ret = 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) {
ret = join_cursor->get_key(join_cursor, &recno);
ret = join_cursor->get_value(join_cursor, &country, &year,
&population);
printf("ID %" PRIu64, recno);
printf(
": country %s, year %" PRIu16 ", population %" PRIu64 "\n",
country, year, population);
}
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 .
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 Returns for details.
Examples:
ex_schema.c, and ex_stat.c.

◆ log_flush()

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

Flush the log.

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 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 Returns for details.

◆ log_printf()

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

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
fmta printf format specifier
Returns
zero on success and a non-zero error code on failure. See Error Returns 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.

ret = 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:

ret = session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor);
cursor->set_key(cursor, key);
ret = cursor->search(cursor);
/* Duplicate the cursor. */
ret = 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
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
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 appendedkey=string, value=string,
see Reading WiredTiger Metadata for details
statistics:[<data source URI>]databasedata source or join 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 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.
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 internal checkpoint taken for the object). The cursor does not support data modification.a string; default empty.
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, 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", "print"; 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, 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 and WT_CURSOR::remove fail 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.
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 log and metadata 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, backup the 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 Returns for details.
Examples:
ex_access.c, ex_call_center.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.

◆ rebalance()

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

Rebalance a table, see Rebalance.

ret = session->rebalance(session, "table:mytable", NULL);
Parameters
sessionthe session handle
urithe current URI of the object, such as "table:mytable"
configConfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

◆ reconfigure()

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

Reconfigure a session handle.

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

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

All cursors are reset.

Parameters
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
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 read-committed.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.

◆ rename()

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

Rename an object.

ret = session->rename(session, "table:old", "table:new", NULL);
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 there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

◆ reset()

int WT_SESSION::reset ( WT_SESSION session)

Reset the session handle.

This will reset all cursors associated with this session and clear any buffers that each cursor held. After this the buffers associated with the session will be discarded. The session can be re-used immediately after this call returns. If a transaction is running on this session, then this call will take no action and return a busy error.

ret = session->reset(session);
Parameters
sessionthe session handle
Returns
zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns 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.

/*
* 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.
*/
ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
cursor->set_key(cursor, "key");
cursor->set_value(cursor, "value");
switch (ret = cursor->update(cursor)) {
case 0: /* Update success */
ret = session->commit_transaction(session, NULL);
/*
* If commit_transaction succeeds, cursors remain positioned; if
* commit_transaction fails, the transaction was rolled-back and
* and all cursors are reset.
*/
break;
case WT_ROLLBACK: /* Update conflict */
default: /* Other error */
ret = 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. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.

◆ salvage()

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

Salvage a file or table.

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 file or table has been corrupted, as reported by the WT_SESSION::verify method.

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

ret = session->salvage(session, "table:mytable", NULL);
Parameters
sessionthe session handle
namethe URI of the file or table 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 there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

◆ snapshot()

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

Manage named snapshot transactions.

Use this API to create and drop named snapshots. Named snapshot transactions can be accessed via WT_CURSOR::open. See Named Snapshots.

/* Create a named snapshot */
ret = session->snapshot(session, "name=June01");
/* Open a transaction at a given snapshot */
ret = session->begin_transaction(session, "snapshot=June01");
/* Drop all named snapshots */
ret = session->snapshot(session, "drop=(all)");
Parameters
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
drop = (if non-empty, specifies which snapshots to drop. Where a group of snapshots are being dropped, the order is based on snapshot creation order not alphanumeric name order.a set of related configuration options defined below.
    alldrop all named snapshots.a boolean flag; default false.
    beforedrop all snapshots up to but not including the specified name.a string; default empty.
    namesdrop specific named snapshots.a list of strings; default empty.
    todrop all snapshots up to and including the specified name.a string; default empty.
)
include_updatesmake updates from the current transaction visible to users of the named snapshot. Transactions started with such a named snapshot are restricted to being read-only.a boolean flag; default false.
namespecify a name for the snapshot.a string; default empty.
Returns
zero on success and a non-zero error code on failure. See Error Returns 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
sessionthe session handle
errora return value from a WiredTiger, ISO C, or POSIX standard API
Returns
a string representation of the error
Examples:
ex_log.c, and ex_thread.c.

◆ 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;
ret = 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 Returns 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 be called when no transactions are active in the session.

ret = session->transaction_sync(session, NULL);
Parameters
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
timeout_msmaximum 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 Returns 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 or cursor range.

Truncate a file or table.

ret = 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;
ret = session->open_cursor(
session, "table:mytable", NULL, NULL, &start);
start->set_key(start, "June01");
ret = start->search(start);
ret = session->open_cursor(
session, "table:mytable", NULL, NULL, &stop);
stop->set_key(stop, "June30");
ret = stop->search(stop);
ret = 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.

Parameters
sessionthe session handle
namethe URI of the file or table to truncate
startoptional cursor marking the first record discarded; if NULL, the truncate starts from the beginning of the object
stopoptional cursor marking the last record discarded; if NULL, the truncate continues to the end of the object
configConfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.

◆ upgrade()

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

Upgrade a file or table.

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

ret = session->upgrade(session, "table:mytable", NULL);
Parameters
sessionthe session handle
namethe URI of the file or table to upgrade
configConfiguration string, see Configuration Strings. No values currently permitted.
Returns
zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

◆ verify()

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

Verify a file or table.

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,

ret = session->verify(session, "table:mytable", NULL);
Parameters
sessionthe session handle
namethe URI of the file or table to verify
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
dump_addressDisplay addresses 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.
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 there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

Member Data Documentation

◆ connection

WT_CONNECTION* WT_SESSION::connection

The connection for this session.

Examples:
ex_encrypt.c.