Common operations in WiredTiger are performed using WT_CURSOR handles.
A cursor includes:
Cursors are created using the WT_SESSION::open_cursor method. The following are examples from the example program ex_cursor.c:
In addition to traditional data sources, cursors in WiredTiger are used to access projections and even created data sources such as the run-time statistics:
See Cursors for more information on available cursor types.
Cursors remain open until either WT_CURSOR::close is called or the cursor's session is closed, which may either be in WT_SESSION::close or WT_CONNECTION::close.
Cursors may be positioned at the beginning of the data source, the end of the data source, at an exact key within the data source, and near a key within the data source.
To invalidate the position of a cursor so that subsequent iterations start from the beginning or end of the data source, use the WT_CURSOR::reset method:
To move a cursor forward or backward in the data source, use the cursor WT_CURSOR::next and WT_CURSOR::prev methods:
If the WT_CURSOR::next and WT_CURSOR::prev methods are called on cursors without a position in the data source, they are positioned at the beginning or end of the data source, respectively.
To position a cursor at a specific location in the data source, use the WT_CURSOR::search method:
To position a cursor at or near a location in the data source, use the WT_CURSOR::search_near method:
Cursor positions do not survive transactions: cursors that are open during WT_SESSION::begin_transaction, WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction will lose their position as if WT_CURSOR::reset was called.
Cursors can be configured to move to a random position with WT_CURSOR::next is called, see Cursor random for details.
To insert new data, and optionally update existing data, using a cursor, use the WT_CURSOR::insert method:
By default, when inserting into a row-store, the WT_CURSOR::insert method returns an error if the key already exists in the store, otherwise it inserts a new key/value pair. If the overwrite
configuration string is specified to the WT_SESSION::open_cursor method, any previously existing key/value pair is updated to the new value rather than returning an error.
By default, when updating an underlying column-store, the WT_CURSOR::insert method ignores the application's key value, instead, it allocates an unused record number in the store and returns that record number in the application's key. If the overwrite
configuration string is specified to the WT_SESSION::open_cursor method, the application's key value will be used to specify the record number being inserted or updated.
To update existing data using a cursor, use the WT_CURSOR::update method:
In all cases, calling WT_CURSOR::update where the key does not already exist in the store will return an error.
To remove existing data using a cursor, use the WT_CURSOR::remove method:
After any cursor handle method failure, the cursor's position is undetermined. For cursor operations that expect a key to be set before the operation begins (including WT_CURSOR::search, WT_CURSOR::insert, WT_CURSOR::update and WT_CURSOR::remove), the application's key and value will not be cleared by an error.
Applications that cannot re-position the cursor after failure must duplicate the cursor by calling WT_SESSION::open_cursor and passing the cursor as the to_dup
parameter before calling a cursor method that will attempt to re-position the cursor. Cursor duplication is not supported for the backup, config and statistics cursor types.