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_CONNECTION *	connection
	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

session

the session handle

config

Configuration string, see Configuration Strings. Permitted values: Name Effect Values 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. 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. sync how 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

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 while a hot backup is in progress or if open in a cursor. a list of strings; default empty. name if non-empty, specify a name for the checkpoint. a string; default empty. target if 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

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

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

session	the session handle
name	the URI of the object to create, such as "table:stock"
config	Configuration string, see Configuration Strings. Permitted values: Name Effect Values 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 512B is a good choice absent requirements from the operating system or storage device. an integer between 512B and 128MB; default 512B. block_compressor configure 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_resident do not ever evict the object's pages; see Cache resident objects for more information. a boolean flag; default false. checksum configure 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. 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. Value must be a collator name created with WT_CONNECTION::add_collator. a string; default empty. 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 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. 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. filename override the default filename derived from the object name. a string; default empty. huffman_key configure 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_value configure 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_max the 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_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. an integer between 512B and 512MB; default 2KB. 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. key_gap the 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_max the 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_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. an integer between 512B and 512MB; default 1MB. lsm_bloom_bit_count the number of bits used per item for LSM bloom filters.. an integer between 2 and 1000; default 8. lsm_bloom_hash_count the number of hash values per item used for LSM bloom filters.. an integer between 2 and 100; default 4. lsm_chunk_size the maximum size of the in-memory chunk of an LSM tree. an integer between 512K and 500MB; default 2MB. prefix_compression configure row-store format key prefix compression. a boolean flag; default true. 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 25 and 100; default 75. type the file type. a string, chosen from the following options: "btree"; default btree. 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.

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

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.

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

session	the session handle
name	the URI of the file to dump
config	Configuration 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

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

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 cursor types: URI Type Key/Value types backup: hot backup cursor key=string, see Hot backup for details colgroup:<tablename>.<columnset> column group cursor table key, column group value(s) table:<tablename> table cursor table key, table value(s) file:<filename> file cursor file key, file value(s) index:<tablename>.<indexname> index cursor key=index key, value=table value(s) statistics:[file:<filename>] database or file statistics cursor key=int id, value=(string description, string value, uint64_t value), see Statistics Data for details
to_dup	a cursor to duplicate
session	the session handle
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 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. checkpoint the 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. dump configure 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_random configure 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. overwrite change the behavior of the cursor's insert method to overwrite previously existing values. a boolean flag; default false. 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. statistics configure the cursor for statistics. a boolean flag; default false. statistics_clear reset statistics counters when the cursor is closed; valid only for statistics cursors. a boolean flag; default false. target if non-empty, backup the list of objects; valid only for a backup data source. a list of strings; default empty.
cursorp	a 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

session	the session handle
config	Configuration string, see Configuration Strings. Permitted values: Name Effect Values isolation the 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

session	the session handle
oldname	the current URI of the object, such as "table:old"
newname	the new name of the object, such as "table:new"
config	Configuration 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

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

session	the session handle
name	the URI of the file or table 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 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

session	the session handle
name	the URI of the file or table to truncate
start	optional cursor marking the first record discarded; if NULL, the truncate starts from the beginning of the object
stop	optional cursor marking the last record discarded; if NULL, the truncate continues to the end of the object
config	Configuration 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

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

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