Version 1.1.5
WT_SESSION Struct Reference

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

List of all members.

Public Member Functions

int close (WT_SESSION *session, const char *config)
 Close the 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 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 sync (WT_SESSION *session, const char *name, const char *config)
 Sync 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 a 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)
 Flush the cache and/or the log and optionally archive log files.
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 cannot be shared between threads: it may only be used within a single thread. Each thread accessing a database should open a separate WT_SESSION handle.

Examples:
ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, and ex_transaction.c.

Member Function Documentation

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

Start a transaction in this session.

Not yet supported in WiredTiger.

All cursors opened in this session that support transactional semantics will operate in the context of the transaction. The transaction remains active until ended with WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction.

Ignored if a transaction is in progress.

        ret = session->begin_transaction(session, NULL);
Parameters:
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
isolationthe isolation level for this transaction.a string, chosen from the following options: "serializable", "snapshot", "read-committed", "read-uncommitted"; default read-committed.
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_all.c, ex_config.c, and ex_transaction.c.
int WT_SESSION::checkpoint ( WT_SESSION session,
const char *  config 
)

Flush the cache and/or the log and optionally archive log files.

Not yet supported in WiredTiger.

        ret = session->checkpoint(session, NULL);
Parameters:
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
archiveremove log files no longer required for transactional durability.a boolean flag; default false.
flush_cacheflush the cache.a boolean flag; default true.
flush_logflush the log to disk.a boolean flag; default true.
forcewrite a new checkpoint even if nothing has changed since the last one.a boolean flag; default false.
log_sizeonly proceed if more than the specified number of bytes of log records have been written since the last checkpoint.an integer greater than or equal to 0; default 0.
timeoutonly proceed if more than the specified number of milliseconds have elapsed since the last checkpoint.an integer greater than or equal to 0; default 0.
Returns:
zero on success and a non-zero error code on failure. See Error Returns for details.
Examples:
ex_all.c.
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 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_all.c, and ex_thread.c.
int WT_SESSION::commit_transaction ( WT_SESSION session,
const char *  config 
)

Commit the current transaction.

Not yet supported in WiredTiger.

Any cursors opened during the transaction will be closed before the commit is processed.

Ignored if no transaction is in progress.

        ret = session->commit_transaction(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_all.c, ex_config.c, and ex_transaction.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.
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.
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.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.
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_all.c, ex_call_center.c, ex_config.c, ex_cursor.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.
Examples:
ex_all.c.
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.
Examples:
ex_all.c.
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 pid %lu", mypid);
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.
Examples:
ex_all.c.
int WT_SESSION::open_cursor ( WT_SESSION session,
const char *  uri,
WT_CURSOR to_dup,
const char *  config,
WT_CURSOR **  cursorp 
)

Open a cursor.

Open a new cursor on the specified data source. Cursor handles should be discarded by calling WT_CURSOR::close.

Cursors are light-weight objects but may hold references to heavier-weight objects. Applications should usually not cache cursors as a performance optimization, instead, a new cursor should be opened for new groups of operations.

Cursors are opened in the context of the current transaction. The cursor must be closed before the transaction can end. If WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction are called with cursors open in the transaction, the cursor handles will be closed implicitly and must not be accessed again.

An existing cursor can be duplicated by passing it as the to_dup parameter and setting the uri parameter to NULL, otherwise the to_dup parameter should be NULL.

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);
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, be read-only or not support transactional updates). See Cursor types for more information.
The following are the builtin cursor types:
URITypeKey/Value types
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 cursors for details
to_dupa cursor to duplicate
sessionthe session handle
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
appendonly supported by cursors with record number keys: append the value as a new record, creating a new record number key.a boolean flag; default false.
bulkconfigure the cursor for bulk loads; bulk-load is a fast load path for empty objects, only empty objects may be bulk-loaded.a boolean flag; default false.
clear_on_closefor statistics cursors, reset statistics counters when the cursor is closed.a boolean flag; default false.
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.
isolationthe isolation level for this cursor, ignored for transactional cursors.a string, chosen from the following options: "snapshot", "read-committed", "read-uncommitted"; default read-committed.
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.
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_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.
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.
Examples:
ex_all.c.
int WT_SESSION::rollback_transaction ( WT_SESSION session,
const char *  config 
)

Roll back the current transaction.

Not yet supported in WiredTiger.

Any cursors opened during the transaction will be closed before the rollback is processed.

Ignored if no transaction is in progress.

        ret = session->rollback_transaction(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_all.c.
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.
Examples:
ex_all.c.
int WT_SESSION::sync ( WT_SESSION session,
const char *  name,
const char *  config 
)

Sync a file or table.

Flush dirty pages from a table to stable storage. Note that not all pages are necessarily flushed (pages pinned in memory, or in use by other threads of control may not be written until all open session handles for the table are closed).

        ret = session->sync(session, "table:mytable", NULL);
Parameters:
sessionthe session handle
namethe URI of the file or table to sync
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_all.c.
int WT_SESSION::truncate ( WT_SESSION session,
const char *  name,
WT_CURSOR start,
WT_CURSOR stop,
const char *  config 
)

Truncate a file, table or a cursor range.

        ret = session->truncate(session, "table:mytable", NULL, NULL, NULL);
        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 table
stopoptional cursor marking the last record discarded; if NULL, the truncate continues to the end of the table
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_all.c.
int WT_SESSION::upgrade ( WT_SESSION session,
const char *  name,
const char *  config 
)

Upgrade a file or table.

Upgrade upgrades a file, or the files of which a table is comprised.

        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.
Examples:
ex_all.c.
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.
Examples:
ex_all.c.

Member Data Documentation

The connection for this session.