All data operations are performed in the context of a WT_SESSION. More...
Public Member Functions | |
int | close (WT_HANDLE_CLOSED(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... | |
int | query_timestamp (WT_SESSION *session, char *hex_timestamp, const char *config) |
Query the session's transaction timestamp state. More... | |
int | checkpoint (WT_SESSION *session, const char *config) |
Write a transactionally consistent snapshot of a database or set of individual objects. More... | |
int | transaction_pinned_range (WT_SESSION *session, uint64_t *range) |
Return the transaction ID range pinned by the session handle. More... | |
Cursor handles | |
int | open_cursor (WT_SESSION *session, const char *uri, WT_HANDLE_NULLABLE(WT_CURSOR) *to_dup, const char *config, WT_CURSOR **cursorp) |
Open a new cursor on a data source or duplicate an existing cursor. More... | |
Table operations | |
int | alter (WT_SESSION *session, const char *name, const char *config) |
Alter a table. More... | |
int | create (WT_SESSION *session, const char *name, const char *config) |
Create a table, column group, index or file. More... | |
int | compact (WT_SESSION *session, const char *name, const char *config) |
Compact a live row- or column-store btree or LSM tree. More... | |
int | drop (WT_SESSION *session, const char *name, const char *config) |
Drop (delete) an object. More... | |
int | join (WT_SESSION *session, WT_CURSOR *join_cursor, WT_CURSOR *ref_cursor, const char *config) |
Join a join cursor with a reference cursor. More... | |
int | log_flush (WT_SESSION *session, const char *config) |
Flush the log. More... | |
int | log_printf (WT_SESSION *session, const char *format,...) |
Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called). More... | |
int | rename (WT_SESSION *session, const char *uri, const char *newuri, const char *config) |
Rename an object. More... | |
int | reset (WT_SESSION *session) |
Reset the session handle. More... | |
int | salvage (WT_SESSION *session, const char *name, const char *config) |
Salvage a table or file. More... | |
int | truncate (WT_SESSION *session, const char *name, WT_HANDLE_NULLABLE(WT_CURSOR) *start, WT_HANDLE_NULLABLE(WT_CURSOR) *stop, const char *config) |
Truncate a file, table, cursor range, or backup cursor. More... | |
int | upgrade (WT_SESSION *session, const char *name, const char *config) |
Upgrade a table or file. More... | |
int | verify (WT_SESSION *session, const char *name, const char *config) |
Verify a table or file. More... | |
Transactions | |
int | begin_transaction (WT_SESSION *session, const char *config) |
Start a transaction in this session. More... | |
int | commit_transaction (WT_SESSION *session, const char *config) |
Commit the current transaction. More... | |
int | prepare_transaction (WT_SESSION *session, const char *config) |
Prepare the current transaction. More... | |
int | reset_snapshot (WT_SESSION *session) |
Reset the snapshot. More... | |
int | rollback_transaction (WT_SESSION *session, const char *config) |
Roll back the current transaction. More... | |
int | timestamp_transaction (WT_SESSION *session, const char *config) |
Set a timestamp on a transaction. More... | |
int | timestamp_transaction_uint (WT_SESSION *session, WT_TS_TXN_TYPE which, uint64_t ts) |
Set a timestamp on a transaction numerically. More... | |
Public Attributes | |
WT_CONNECTION * | connection |
The connection for this session. | |
void * | app_private |
A location for applications to store information that will be available in callbacks taking a WT_SESSION handle. | |
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.
int WT_SESSION::alter | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Alter a table.
This will allow modification of some table settings after creation.
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
session | the session handle | ||||||||||||||||||||||||||||||||||||
name | the URI of the object to alter, such as "table:stock" | ||||||||||||||||||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::begin_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Start a transaction in this session.
The transaction remains active until ended by WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction. Operations performed on cursors capable of supporting transactional operations that are already open in this session, or which are opened before the transaction ends, will operate in the context of the transaction.
This method must not be called on a session with an active transaction.
session | the session handle | |||||||||||||||||||||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::checkpoint | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Write a transactionally consistent snapshot of a database or set of individual objects.
When timestamps are not in use, the checkpoint includes all transactions committed before the checkpoint starts. When timestamps are in use and the checkpoint runs with use_timestamp=true
(the default), updates committed with a timestamp after the stable
timestamp, in tables configured for checkpoint-level durability, are not included in the checkpoint. Updates committed in tables configured for commit-level durability are always included in the checkpoint. See Checkpoint durability and Commit-level durability for more information.
Calling the checkpoint method multiple times serializes the checkpoints, new checkpoint calls wait for running checkpoint calls to complete.
Existing named checkpoints may optionally be discarded.
This method must not be called on a session with an active transaction.
session | the session handle | ||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::close | ( | WT_HANDLE_CLOSED(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.
session | the session handle |
config | configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::commit_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Commit the current transaction.
A transaction must be in progress when this method is called.
If WT_SESSION::commit_transaction returns an error, the transaction was rolled back, not committed.
This method must be called on a session with an active transaction.
session | the session handle | |||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::compact | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Compact a live row- or column-store btree or LSM tree.
session | the session handle | ||||||
name | the URI of the object to compact, such as "table:stock" | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::create | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Create a table, column group, index or file.
This method is not transactional, and will not guarantee ACID properties, see Transactions for more details.
session | the session handle | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
name | the URI of the object to create, such as "table:stock" . For a description of URI formats see Data Sources. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::drop | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Drop (delete) an object.
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
This method is not transactional, and will not guarantee ACID properties, see Transactions for more details.
session | the session handle | |||||||||
name | the URI of the object to drop, such as "table:stock" | |||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
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.
session | the session handle |
join_cursor | a cursor that was opened using a "join:" URI. It may not have been used for any operations other than other join calls. |
ref_cursor | an index cursor having the same base table as the join_cursor, or a table cursor open on the same base table, or another join cursor. Unless the ref_cursor is another join cursor, it must be positioned. |
The ref_cursor limits the results seen by iterating the join_cursor to table items referred to by the key in this index. The set of keys referred to is modified by the compare config option.
Multiple join calls builds up a set of ref_cursors, and by default, the results seen by iteration are the intersection of the cursor ranges participating in the join. When configured with "operation=or"
, the results seen are the union of the participating cursor ranges.
After the join call completes, the ref_cursor cursor may not be used for any purpose other than get_key and get_value. Any other cursor method (e.g. next, prev,close) will fail. When the join_cursor is closed, the ref_cursor is made available for general use again. The application should close ref_cursor when finished with it, although not before the join_cursor is closed.
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::log_flush | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Flush the log.
WT_SESSION::log_flush will fail if logging is not enabled.
session | the session handle | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::log_printf | ( | WT_SESSION * | session, |
const char * | format, | ||
... | |||
) |
Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called).
session | the session handle |
format | a printf format specifier |
int WT_SESSION::open_cursor | ( | WT_SESSION * | session, |
const char * | uri, | ||
WT_HANDLE_NULLABLE(WT_CURSOR) * | to_dup, | ||
const char * | config, | ||
WT_CURSOR ** | cursorp | ||
) |
Open a new cursor on a data source or duplicate an existing cursor.
An existing cursor can be duplicated by passing it as the to_dup
parameter and setting the uri
parameter to NULL:
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.
session | the session handle |
uri | the data source on which the cursor operates; cursors are usually opened on tables, however, cursors can be opened on any data source, regardless of whether it is ultimately stored in a table. Some cursor types may have limited functionality (for example, they may be read-only or not support transactional updates). See Data Sources for more information. |
The following are the builtin basic cursor types:
URI | Type | Notes |
---|---|---|
table:<table name>[<projection>] | table cursor | table key, table value(s) with optional projection of columns |
colgroup:<table name>:<column group name> | column group cursor | table key, column group value(s) |
index:<table name>:<index name>[<projection>] | index cursor | key=index key, value=table value(s) with optional projection of columns |
join:table:<table name>[<projection>] | join cursor | key=table key, value=table value(s) with optional projection of columns |
Some administrative tasks can be accomplished using the following special cursor types that give access to data managed by WiredTiger:
URI | Type | Notes |
---|---|---|
backup:[query_id] | backup cursor (optionally only returning block incremental ids if query_id is appended) | key=string , see Backups for details |
log: | log cursor | key=(long fileID, long offset, int seqno) ,value= (uint64_t txnid, uint32_t rectype, ,see Log cursors for details |
metadata:[create] | metadata cursor (optionally only returning configuration strings for WT_SESSION::create if create is appended) | key=string , value=string ,see Reading WiredTiger Metadata for details |
statistics:[<data source URI>] | database, data source, join or session statistics cursor | key=int id ,value= (string description, string value, uint64_t value) ,see Statistics Data for details |
Advanced applications may also open the following low-level cursor types:
URI | Type | Notes |
---|---|---|
file:<file name> | file cursor | file key, file value(s) |
lsm:<name> | LSM cursor (key=LSM key, value=LSM value) | LSM key, LSM value, see Log-Structured Merge Trees |
to_dup | a cursor to duplicate or gather statistics on | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[out] | cursorp | a pointer to the newly opened cursor |
int WT_SESSION::prepare_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Prepare the current transaction.
A transaction must be in progress when this method is called.
Preparing a transaction will guarantee a subsequent commit will succeed. Only commit and rollback are allowed on a transaction after it has been prepared. The transaction prepare API is designed to support MongoDB exclusively, and guarantees update conflicts have been resolved, but does not guarantee durability.
This method must be called on a session with an active transaction.
session | the session handle | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::query_timestamp | ( | WT_SESSION * | session, |
char * | hex_timestamp, | ||
const char * | config | ||
) |
Query the session's transaction timestamp state.
The WT_SESSION.query_timestamp method can only be used at snapshot isolation.
session | the session handle | |||||||
[out] | hex_timestamp | a buffer that will be set to the hexadecimal encoding of the timestamp being queried. Must be large enough to hold a NUL terminated, hex-encoded 8B timestamp (17 bytes). | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::reconfigure | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Reconfigure a session handle.
WT_SESSION::reconfigure will fail if a transaction is in progress in the session.
All cursors are reset.
session | the session handle | |||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::rename | ( | WT_SESSION * | session, |
const char * | uri, | ||
const char * | newuri, | ||
const char * | config | ||
) |
Rename an object.
This method is not transactional, and will not guarantee ACID properties, see Transactions for more details.
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
session | the session handle |
uri | the current URI of the object, such as "table:old" |
newuri | the new URI of the object, such as "table:new" |
config | configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::reset | ( | WT_SESSION * | session | ) |
Reset the session handle.
This method resets all cursors associated with this session, discards cached resources and resets session statistics. The session can be re-used immediately after this call returns. If a transaction is running on this session, then this call takes no action and return an error.
session | the session handle |
int WT_SESSION::reset_snapshot | ( | WT_SESSION * | session | ) |
Reset the snapshot.
This method resets snapshots for snapshot isolation transactions to update their existing snapshot. It raises an error when this API is used for isolation other than snapshot isolation mode or when the session has performed any write operations. This API internally releases the current snapshot and gets the new running transactions snapshot to avoid pinning the content in the database that is no longer needed. Applications that don't use read_timestamp for the search may see different results compared to earlier with the updated snapshot.
This method must be called on a session with an active transaction.
session | the session handle |
int WT_SESSION::rollback_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Roll back the current transaction.
A transaction must be in progress when this method is called.
All cursors are reset.
This method must be called on a session with an active transaction.
session | the session handle | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::salvage | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Salvage a table or file.
Salvage rebuilds the file, or files of which a table is comprised, discarding any corrupted file blocks.
Previously deleted records may re-appear, and inserted records may disappear, when salvage is done, so salvage should not be run unless it is known to be necessary. Normally, salvage should be called after a table or file has been corrupted, as reported by the WT_SESSION::verify method.
Files are rebuilt in place, the salvage method overwrites the existing files.
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
session | the session handle | ||||||
name | the URI of the table or file to salvage | ||||||
config | configuration string, see Configuration Strings. Permitted values:
|
const char* WT_SESSION::strerror | ( | WT_SESSION * | session, |
int | error | ||
) |
Return information about an error as a string.
session | the session handle |
error | a return value from a WiredTiger, ISO C, or POSIX standard API |
int WT_SESSION::timestamp_transaction | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Set a timestamp on a transaction.
The WT_SESSION.timestamp_transaction method can only be used at snapshot isolation.
This method must be called on a session with an active transaction.
session | the session handle | |||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
int WT_SESSION::timestamp_transaction_uint | ( | WT_SESSION * | session, |
WT_TS_TXN_TYPE | which, | ||
uint64_t | ts | ||
) |
Set a timestamp on a transaction numerically.
Prefer this over timestamp_transaction when the string parsing done in that method becomes a bottleneck.
The WT_SESSION.timestamp_transaction_uint method can only be used at snapshot isolation.
This method must be called on a session with an active transaction.
session | the session handle |
which | the timestamp you wish to set. See WT_TS_TXN_TYPE for available options, and timestamp_transaction for constraints on when timestamps can be set. |
ts | the timestamp. |
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.
session | the session handle | |
[out] | range | the range of IDs pinned by this session. Zero if there is no active transaction. |
int WT_SESSION::truncate | ( | WT_SESSION * | session, |
const char * | name, | ||
WT_HANDLE_NULLABLE(WT_CURSOR) * | start, | ||
WT_HANDLE_NULLABLE(WT_CURSOR) * | stop, | ||
const char * | config | ||
) |
Truncate a file, table, cursor range, or backup cursor.
Truncate a table or file.
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.
When a range truncate is in progress, and another transaction inserts a key into that range, the behavior is not well defined - a conflict may be detected or both transactions may be permitted to commit. If they do commit, and if there is a crash and recovery runs, the result may be different than what was in cache before the crash.
The WT_CURSOR::truncate range truncate operation can only be used at snapshot isolation.
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.
Truncate a backup cursor. This operation removes all log files that have been returned by the backup cursor. It can be used to remove log files after copying them during Log-based Incremental backup.
session | the session handle |
name | the URI of the table or file to truncate, or "log:" for a backup cursor |
start | optional cursor marking the first record discarded; if NULL , the truncate starts from the beginning of the object; must be provided when truncating a backup cursor |
stop | optional cursor marking the last record discarded; if NULL , the truncate continues to the end of the object; ignored when truncating a backup cursor |
config | configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::upgrade | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Upgrade a table or file.
Upgrade upgrades a table or file, if upgrade is required.
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
session | the session handle |
name | the URI of the table or file to upgrade |
config | configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::verify | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Verify a table or file.
Verify reports if a file, or the files of which a table is comprised, have been corrupted. The WT_SESSION::salvage method can be used to repair a corrupted file,
This method requires exclusive access to the specified data source(s). If any cursors are open with the specified name(s) or a data source is otherwise in use, the call will fail and return EBUSY
.
session | the session handle | |||||||||||||||||||||||||||
name | the URI of the table or file to verify, optional if verifying the history store | |||||||||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|