Version 11.3.0
Cursors

Common operations in WiredTiger are performed using WT_CURSOR handles. A cursor includes:

  • a position within a data source
  • getter/setters for key and value fields
  • encoding of fields to store in the data source
  • methods to navigate within and iterate through the data

See Cursor operations for a description of how to use cursors.

Cursor types

The following are the builtin basic cursor types:

URITypeNotes
table:<table name>[<projection>]table cursortable key, table value(s) with optional projection of columns
colgroup:<table name>:<column group name>column group cursortable key, column group value(s)
index:<table name>:<index name>[<projection>]index cursorkey=index key, value=table value(s) with optional projection of columns
join:table:<table name>[<projection>]join cursorkey=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:

URITypeNotes
backup:backup cursorkey=string, see Backups for details
backup:exportexport 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 optionkey=string, see Export tables using backup cursor for details
backup:query_idbackup cursor that only returns block incremental idskey=string, see Backups for details
log:log cursorkey=(long fileID, long offset, int seqno),
value=(uint64_t txnid, uint32_t rectype,
uint32_t optype, uint32_t fileid,
WT_ITEM key, WT_ITEM value)
,
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 cursorkey=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:

URITypeNotes
file:<file name>file cursorfile key, file value(s)
lsm:<name>LSM cursor (key=LSM key, value=LSM value)LSM key, LSM value,
see Log-Structured Merge Trees

See the following for more details:

Projections

Cursors on tables and indices can return a subset of columns. This is done by listing the column names in parenthesis in the uri parameter to WT_SESSION::open_cursor. Only the fields from the listed columns are returned by WT_CURSOR::get_value.

The ex_schema.c example creates a table where the value format is "5sHq", where the initial string is the country, the short is a year, and the long is a population. The following example lists just the country and year columns from the table record values:

/*
* Use a projection to return just the table's country and year columns.
*/
error_check(session->open_cursor(session, "table:poptable(country,year)", NULL, NULL, &cursor));
while ((ret = cursor->next(cursor)) == 0) {
error_check(cursor->get_value(cursor, &country, &year));
printf("country %s, year %" PRIu16 "\n", country, year);
}

This is particularly useful with index cursors, because if all columns in the projection are available in the index (including primary key columns, which are the values of the index), the data can be read from the index without accessing any column groups. See Index cursor projections for more information.

Cursors and Eviction

Cursor positions hold resources that can inhibit the eviction of memory pages. If a cursor is active on a page being considered for eviction, the eviction will defer until the cursor is moved or reset. To avoid this and to keep resources freed in general, an application should call WT_CURSOR::reset during times it does not need to keep the cursor positioned. A cursor that has been reset is not active and will not inhibit eviction.

Raw mode

Cursors can be configured for raw mode by specifying the "raw" config keyword to WT_SESSION::open_cursor. In this mode, the methods WT_CURSOR::get_key, WT_CURSOR::get_value, WT_CURSOR::set_key and WT_CURSOR::set_value all take a single WT_ITEM in the variable-length argument list instead of a separate argument for each column.

WT_ITEM structures do not need to be cleared before use.

For WT_CURSOR::get_key and WT_CURSOR::get_value in raw mode, the WT_ITEM can be split into columns by calling WT_EXTENSION_API::struct_unpack with the cursor's key_format or value_format, respectively. For WT_CURSOR::set_key and WT_CURSOR::set_value in raw mode, the WT_ITEM should be equivalent to calling WT_EXTENSION_API::struct_pack for the cursor's key_format or value_format, respectively.

WT_CURSOR::get_raw_key_value can be used to obtain both the key and value in raw format in a single function call.

The ex_schema.c example creates a table where the value format is "5sHq", where the initial string is the country, the short is a year, and the long is a population. The following example lists the table record values, using raw mode:

/* List the records in the table using raw mode. */
error_check(session->open_cursor(session, "table:poptable", NULL, "raw", &cursor));
while ((ret = cursor->next(cursor)) == 0) {
WT_ITEM key, value;
error_check(cursor->get_key(cursor, &key));
error_check(wiredtiger_struct_unpack(session, key.data, key.size, "r", &recno));
printf("ID %" PRIu64, recno);
error_check(cursor->get_value(cursor, &value));
session, value.data, value.size, "5sHQ", &country, &year, &population));
printf(
": country %s, year %" PRIu16 ", population %" PRIu64 "\n", country, year, population);
}
scan_end_check(ret == WT_NOTFOUND);

Raw mode can be used in combination with projections. The following example lists just the country and year columns from the table record values, using raw mode:

/*
* Use a projection to return just the table's country and year columns, using raw mode.
*/
error_check(
session->open_cursor(session, "table:poptable(country,year)", NULL, "raw", &cursor));
while ((ret = cursor->next(cursor)) == 0) {
WT_ITEM value;
error_check(cursor->get_value(cursor, &value));
error_check(
wiredtiger_struct_unpack(session, value.data, value.size, "5sH", &country, &year));
printf("country %s, year %" PRIu16 "\n", country, year);
}
scan_end_check(ret == WT_NOTFOUND);

Reading WiredTiger Metadata

WiredTiger cursors provide access to data from a variety of sources. One of these sources is the list of objects in the database.

To retrieve the list of database objects, open a cursor on the uri metadata:. Each returned key will be a database object and each returned value will be the information stored in the metadata for object named by the key.

For example:

error_check(session->open_cursor(session, "metadata:", NULL, NULL, &cursor));

To retrieve value strings that are valid arguments for calls to WT_SESSION::create, open a cursor on metadata:create.

The metadata cursor is read-only, and the metadata cannot be modified.

WT_SESSION::open_cursor
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.
WT_ITEM::data
const void * data
The memory reference of the data item.
Definition: wiredtiger.in:99
WT_CURSOR::get_key
int get_key(WT_CURSOR *cursor,...)
Get the key for the current record.
WT_ITEM::size
size_t size
The number of bytes in the data item.
Definition: wiredtiger.in:108
wiredtiger_struct_unpack
int wiredtiger_struct_unpack(WT_SESSION *session, const void *buffer, size_t len, const char *format,...)
Unpack a structure from a buffer.
WT_CURSOR::next
int next(WT_CURSOR *cursor)
Return the next record.
WT_ITEM
A raw item of data to be managed, including a pointer to the data and a length.
Definition: wiredtiger.in:91
WT_CURSOR::get_value
int get_value(WT_CURSOR *cursor,...)
Get the value for the current record.
WT_NOTFOUND
#define WT_NOTFOUND
Item not found.
Definition: wiredtiger.in:4105