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. More... | |
int | reconfigure (WT_SESSION *session, const char *config) |
Reconfigure a session handle. More... | |
const char * | strerror (WT_SESSION *session, int error) |
Return information about an error as a string. More... | |
Cursor handles | |
int | open_cursor (WT_SESSION *session, const char *uri, WT_CURSOR *to_dup, const char *config, WT_CURSOR **cursorp) |
Open a new cursor on a data source or duplicate an existing cursor. More... | |
Table operations | |
int | 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) a table. 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. More... | |
int | truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, 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. More... | |
int | verify (WT_SESSION *session, const char *name, const char *config) |
Verify a table. More... | |
Transactions | |
int | begin_transaction (WT_SESSION *session, const char *config) |
Start a transaction in this session. More... | |
int | commit_transaction (WT_SESSION *session, const char *config) |
Commit the current transaction. More... | |
int | prepare_transaction (WT_SESSION *session, const char *config) |
Prepare the current transaction. More... | |
int | rollback_transaction (WT_SESSION *session, const char *config) |
Roll back the current transaction. More... | |
Transaction timestamps | |
int | query_timestamp (WT_SESSION *session, char *hex_timestamp, const char *config) |
Query the session's transaction timestamp state. 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... | |
Transaction support | |
int | checkpoint (WT_SESSION *session, const char *config) |
Write a transactionally consistent snapshot of a database or set of individual objects. More... | |
int | reset_snapshot (WT_SESSION *session) |
Reset the snapshot used for database visibility. More... | |
int | transaction_pinned_range (WT_SESSION *session, uint64_t *range) |
Return the transaction ID range pinned by the session handle. 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
. See Error handling for details.
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-level 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_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, and all cursors associated with the session 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::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 Transactional applications 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) a table.
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
. See Error handling for details.
This method is not transactional, and will not guarantee ACID properties; see Transactional applications 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_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 associated with the session.
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: | backup cursor | key=string , see Backups for details |
backup:export | export cursor that generates a text file WiredTiger.export. The file contains metadata for all objects in the database. It can be used in the import process as the value for metadata_file configuration option | key=string , see Export tables using backup cursor for details |
backup:query_id | backup cursor that only returns block incremental ids | 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:
|
A timestamp of 0 is returned if the timestamp is not available or has not been set.
int WT_SESSION::reconfigure | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Reconfigure a session handle.
Only configurations listed in the method arguments are modified, other configurations remain in their current state. This method additionally resets the cursors associated with the session. WT_SESSION::reconfigure will fail if a transaction is in progress in the session.
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 Transactional applications 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
. See Error handling for details.
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 the cursors associated with the session, clears session statistics and discards cached resources. No session configurations are modified (or reset to their default values). WT_SESSION::reset will fail if a transaction is in progress in the session.
session | the session handle |
int WT_SESSION::reset_snapshot | ( | WT_SESSION * | session | ) |
Reset the snapshot used for database visibility.
For transactions running with snapshot isolation, this method releases the existing snapshot of the database and gets a new one. This makes newer commits visible. The call can be used to avoid pinning old and no-longer-needed content in the database. Applications not using read timestamps for search may see different results after the snapshot is updated.
It is an error to call this method when using an isolation level other than snapshot isolation, or if the current transaction has already written any data.
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 associated with the session 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.
Salvage rebuilds the file or files which comprise a table, discarding any corrupted file blocks.
When salvage is done, previously deleted records may re-appear, and inserted records may disappear, 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
. See Error handling for details.
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 call |
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 method over WT_SESSION::timestamp_transaction if the hexadecimal 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 being set (see WT_TS_TXN_TYPE for available options, and WT_SESSION::timestamp_transaction for constraints on the timestamps). |
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 an approximate count of transactions 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_CURSOR * | start, | ||
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. The start and stop points are both inclusive; that is, the key set in the start cursor is the first record to be deleted and the key set in the stop cursor is the last.
Range truncate is implemented as a "scan and write" operation, specifically without range locks. Inserts or other operations in the range, as well as operations before or after the range when no explicit starting or ending key is set, are not well defined: conflicts may be detected or both transactions may commit. If both commit, there's a failure 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.
Example: 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.
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
. See Error handling for details.
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.
Verify reports if a file, or the files that comprise a table, 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
. See Error handling for details.
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:
|