Version 1.3.0
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.
 
int reconfigure (WT_SESSION *session, const char *config)
 Reconfigure a session handle.
 
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.
 
Table operations
int create (WT_SESSION *session, const char *name, const char *config)
 Create a table, column group, index or file.
 
int drop (WT_SESSION *session, const char *name, const char *config)
 Drop (delete) an object.
 
int rename (WT_SESSION *session, const char *oldname, const char *newname, const char *config)
 Rename an object.
 
int salvage (WT_SESSION *session, const char *name, const char *config)
 Salvage a file or table.
 
int truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config)
 Truncate a file, table or cursor range.
 
int upgrade (WT_SESSION *session, const char *name, const char *config)
 Upgrade a file or table.
 
int verify (WT_SESSION *session, const char *name, const char *config)
 Verify a file or table.
 
Transactions
int begin_transaction (WT_SESSION *session, const char *config)
 Start a transaction in this session.
 
int commit_transaction (WT_SESSION *session, const char *config)
 Commit the current transaction.
 
int rollback_transaction (WT_SESSION *session, const char *config)
 Roll back the current transaction.
 
int checkpoint (WT_SESSION *session, const char *config)
 Write a transactionally consistent snapshot of a database or set of objects.
 
Debugging
int dumpfile (WT_SESSION *session, const char *name, const char *config)
 Dump a physical file in debugging mode.
 
int msg_printf (WT_SESSION *session, const char *fmt,...)
 Send a string to the message handler for debugging.
 

Public Attributes

WT_CONNECTIONconnection
 The connection for this session.
 

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_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.

Member Function Documentation

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.

All open cursors are reset.

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

ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* The begin_transaction call resets all open cursors.
*/
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);
/*
* The commit_transaction call resets all open cursors.
* If commit_transaction fails, the transaction was rolled-back.
*/
break;
case WT_DEADLOCK: /* Update conflict */
default: /* Other error */
ret = session->rollback_transaction(session, NULL);
/* The rollback_transaction call resets all open 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.
synchow to sync log records when the transaction commits.a string, chosen from the following options: "full", "flush", "write", "none"; default full.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_config.c.
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.
nameif non-empty, specify a name for the checkpoint.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.
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_thread.c.
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.

All open cursors are reset.

If WT_SESSION::commit_transaction returns an error, the transaction was rolled-back, not committed.

ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* The begin_transaction call resets all open cursors.
*/
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);
/*
* The commit_transaction call resets all open cursors.
* If commit_transaction fails, the transaction was rolled-back.
*/
break;
case WT_DEADLOCK: /* Update conflict */
default: /* Other error */
ret = session->rollback_transaction(session, NULL);
/* The rollback_transaction call resets all open 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.
Examples:
ex_config.c.
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"
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
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 512B is a good choice absent requirements from the operating system or storage device.an integer between 512B and 128MB; default 512B.
block_compressorconfigure a compressor for file blocks. Permitted values are empty (off) or "bzip2", "snappy" or custom compression engine "name" created with WT_CONNECTION::add_compressor. See Compressors for more information.a string; default empty.
cache_residentdo not ever evict the object's pages; see Cache resident objects for more information.a boolean flag; default false.
checksumconfigure file block checksums; if false, the block manager is free to not write or check block checksums. This can increase performance in applications where compression provides checksum functionality or read-only applications where blocks require no verification.a boolean flag; default true.
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. Value must be a collator name created with WT_CONNECTION::add_collator.a string; default empty.
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 number of entries maintained 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.
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.
filenameoverride the default filename derived from the object name.a string; default empty.
huffman_keyconfigure Huffman encoding for keys. Permitted values are empty (off), "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information.a string; default empty.
huffman_valueconfigure Huffman encoding for values. Permitted values are empty (off), "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information.a string; default empty.
internal_item_maxthe maximum key size stored on internal nodes, in bytes. If zero, a maximum is calculated to permit at least 8 keys per 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.an integer between 512B and 512MB; default 2KB.
key_formatthe format of the data packed into key items. See Format types for details. By default, the key_format is 'u' and applications use WT_ITEM structures to manipulate raw byte arrays. By default, records are stored in row-store files: keys of type 'r' are record numbers and records referenced by record number are stored in column-store files.a format string; default u.
key_gapthe maximum gap between instantiated keys in a Btree leaf page, constraining the number of keys processed to instantiate a random Btree leaf page key.an integer greater than or equal to 0; default 10.
leaf_item_maxthe maximum key or value size stored on leaf nodes, in bytes. If zero, a size is calculated to permit at least 8 items (values or row store keys) per 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.an integer between 512B and 512MB; default 1MB.
lsm_bloom_bit_countthe number of bits used per item for LSM bloom filters..an integer between 2 and 1000; default 8.
lsm_bloom_hash_countthe number of hash values per item used for LSM bloom filters..an integer between 2 and 100; default 4.
lsm_chunk_sizethe maximum size of the in-memory chunk of an LSM tree.an integer between 512K and 500MB; default 2MB.
prefix_compressionconfigure row-store format key prefix compression.a boolean flag; default true.
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 25 and 100; default 75.
typethe file type.a string, chosen from the following options: "btree"; default btree.
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_call_center.c, ex_config.c, ex_cursor.c, ex_file.c, ex_schema.c, ex_stat.c, and ex_thread.c.
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.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
int WT_SESSION::dumpfile ( WT_SESSION session,
const char *  name,
const char *  config 
)

Dump a physical file in debugging mode.

The specified file is displayed in a non-portable debugging mode to the application's standard output.

ret = session->dumpfile(session, "file:myfile", NULL);
Parameters
sessionthe session handle
namethe URI of the file to dump
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.
int WT_SESSION::msg_printf ( WT_SESSION session,
const char *  fmt,
  ... 
)

Send a string to the message handler for debugging.

ret = session->msg_printf(
session, "process ID %" PRIuMAX, (uintmax_t)getpid());
Parameters
sessionthe session handle
fmta printf-like format specification
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.
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.

To reconfigure a cursor, duplicate it with a new configuration value:

ret = session->open_cursor(
session, "table:mytable", NULL, NULL, &cursor);
cursor->set_key(cursor, key);
/* Reconfigure the cursor to overwrite the record. */
ret = session->open_cursor(
session, NULL, cursor, "overwrite=true", &overwrite_cursor);
ret = cursor->close(cursor);
overwrite_cursor->set_value(overwrite_cursor, value);
ret = overwrite_cursor->insert(cursor);

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. Ending a transaction implicitly resets all open 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 cursor types:
URITypeKey/Value types
backup:hot backup cursorkey=string, see Hot backup for details
colgroup:<tablename>.<columnset>column group cursortable key, column group value(s)
table:<tablename>table cursortable key, table value(s)
file:<filename>file cursorfile key, file value(s)
index:<tablename>.<indexname>index cursorkey=index key, value=table value(s)
statistics:[file:<filename>]database or file statistics cursorkey=int id, value=(string description, string value, uint64_t value), see Statistics Data for details
to_dupa cursor to duplicate
sessionthe session handle
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 loads; bulk-load is a fast load path for empty objects and only empty objects may be bulk-loaded. Cursors configured for bulk load only support the WT_CURSOR::insert and WT_CURSOR::close methods.a boolean flag; default false.
checkpointthe name of a checkpoint to open; the reserved checkpoint name "WiredTigerCheckpoint" opens a cursor on the most recent internal checkpoint taken for the object.a string; default empty.
dumpconfigure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "print" selects a format where only non-printing characters are hexadecimal encoded. The cursor dump format is compatible with the wt dump and wt load commands.a string, chosen from the following options: "hex", "print"; default empty.
next_randomconfigure the cursor to return a pseudo-random record from the object; valid only for row-store cursors. Cursors configured with next_random only support the WT_CURSOR::next and WT_CURSOR::close methods. See Cursor random for details.a boolean flag; default false.
overwritechange the behavior of the cursor's insert method to overwrite previously existing values.a boolean flag; default false.
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.
statisticsconfigure the cursor for statistics.a boolean flag; default false.
statistics_clearreset statistics counters when the cursor is closed; valid only for statistics cursors.a boolean flag; default false.
targetif non-empty, backup the list of objects; valid only for a backup data source.a list of strings; default empty.
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_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.
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 open cursors are reset.

Parameters
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
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.
int WT_SESSION::rename ( WT_SESSION session,
const char *  oldname,
const char *  newname,
const char *  config 
)

Rename an object.

ret = session->rename(session, "table:old", "table:new", NULL);
Parameters
sessionthe session handle
oldnamethe current URI of the object, such as "table:old"
newnamethe new name of the object, such as "table:new"
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.
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 open cursors are reset.

ret =
session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
ret = session->begin_transaction(session, NULL);
/*
* Cursors may be opened before or after the transaction begins, and in
* either case, subsequent operations are included in the transaction.
* The begin_transaction call resets all open cursors.
*/
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);
/*
* The commit_transaction call resets all open cursors.
* If commit_transaction fails, the transaction was rolled-back.
*/
break;
case WT_DEADLOCK: /* Update conflict */
default: /* Other error */
ret = session->rollback_transaction(session, NULL);
/* The rollback_transaction call resets all open 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.
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 and a non-zero error code on failure. See Error Returns for details.
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);
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.
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 and a non-zero error code on failure. See Error Returns for details.
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. No values currently permitted.
Returns
zero on success and a non-zero error code on failure. See Error Returns for details.

Member Data Documentation

WT_CONNECTION* WT_SESSION::connection

The connection for this session.