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 | 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 *fmt,...) |
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 file or table. 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 file or table. More... | |
int | verify (WT_SESSION *session, const char *name, const char *config) |
Verify a file or 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 | rollback_transaction (WT_SESSION *session, const char *config) |
Roll back the current transaction. 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::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.
WT_SESSION::begin_transaction will fail if a transaction is already in progress in the session.
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.
The checkpoint includes all transactions committed before the checkpoint starts. Additionally, checkpoints may optionally be discarded.
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.
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.
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.
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 | either an index cursor having the same base table as the join_cursor, or a table cursor open on the same base table. The ref_cursor 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 the results seen by iteration are the intersection of the cursor ranges participating in the join.
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 * | fmt, | ||
... | |||
) |
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 |
fmt | 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 or data source 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 | ||||||||||||||||||||||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
| ||||||||||||||||||||||||||||||||||
[out] | cursorp | a pointer to the newly opened cursor |
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.
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 will reset all cursors associated with this session and clear any buffers that each cursor held. After this the buffers associated with the session will be discarded. The session can be re-used immediately after this call returns. If a transaction is running on this session, then this call will take no action and return a busy 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.
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 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.
session | the session handle | ||||||
name | the URI of the file or table 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 function |
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 be called when no transactions are active in the session.
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 file or table.
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.
session | the session handle |
name | the URI of the file or table to truncate |
start | optional cursor marking the first record discarded; if NULL , the truncate starts from the beginning of the object |
stop | optional cursor marking the last record discarded; if NULL , the truncate continues to the end of the object |
config | Configuration string, see Configuration Strings. No values currently permitted. |
int WT_SESSION::upgrade | ( | WT_SESSION * | session, |
const char * | name, | ||
const char * | config | ||
) |
Upgrade a file or table.
Upgrade upgrades a file or table, if upgrade is required.
session | the session handle |
name | the URI of the file or table 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 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,
session | the session handle | |||||||||||||||||||||
name | the URI of the file or table to verify | |||||||||||||||||||||
config | Configuration string, see Configuration Strings. Permitted values:
|
WT_CONNECTION* WT_SESSION::connection |
The connection for this session.