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) 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 | rebalance (WT_SESSION *session, const char *uri, const char *config) |
Rebalance a table or file, see Rebalance. 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_CURSOR *start, WT_CURSOR *stop, const char *config) |
Truncate a file, table or cursor range. 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 | 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 | 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 objects. More... | |
int | snapshot (WT_SESSION *session, const char *config) |
Manage named snapshot transactions. More... | |
int | transaction_pinned_range (WT_SESSION *session, uint64_t *range) |
Return the transaction ID range pinned by the session handle. More... | |
int | transaction_sync (WT_SESSION *session, const char *config) |
Wait for a transaction to become synchronized. More... | |
Public Attributes | |
WT_CONNECTION * | connection |
The connection for this session. More... | |
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 objects.
In the absence of transaction timestamps, the checkpoint includes all transactions committed before the checkpoint starts.
When timestamps are in use and a stable_timestamp
has been set via WT_CONNECTION::set_timestamp and the checkpoint runs with use_timestamp=true
(the default), updates committed with a timestamp larger than the stable_timestamp
will not be included in the checkpoint for tables configured with log=
(enabled=false). For tables with logging enabled, all committed changes will be included in the checkpoint (since recovery would roll them forward anyway).
Additionally, 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.
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.
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.
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 | ||
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.
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::rebalance | ( | WT_SESSION * | session, |
const char * | uri, | ||
const char * | config | ||
) |
Rebalance a table or file, see Rebalance.
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:mytable" |
config | configuration string, see Configuration Strings. No values currently permitted. |
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 and discards cached resources. 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::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. No values currently permitted. |
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:
|
int WT_SESSION::snapshot | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Manage named snapshot transactions.
Use this API to create and drop named snapshots. Named snapshot transactions can be accessed via WT_CURSOR::open. See Named Snapshots.
session | the session handle | |||||||||||||||||||||||||||
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.
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::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::transaction_sync | ( | WT_SESSION * | session, |
const char * | config | ||
) |
Wait for a transaction to become synchronized.
This method is only useful when wiredtiger_open is configured with the transaction_sync
setting disabled.
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::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 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.
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.
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.
session | the session handle |
name | the URI of the table or file 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. |
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 | |||||||||||||||||||||
config | configuration string, see Configuration Strings. Permitted values:
|
WT_CONNECTION* WT_SESSION::connection |
The connection for this session.