Version 1.1.5
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 cursor types:

URIType
colgroup:<tablename>.<columnset>column group cursor
config:[<uri>]object configuration cursor (key=config string, value=config value
table:<tablename>table cursor (key=table key, value=table value)
file:<filename>file cursor (key=file key, value=file value)
index:<tablename>.<indexname>index cursor (key=index key, value=table value)
join:<cursor1>&<cursor2>[&<cursor3>...]

join cursor Not yet supported in WiredTiger.

statistics:[file:<filename>]database or file statistics (key=(int), value=(string)description, (string)value, (uint64_t)value)

Index cursors

When an index is created for a table, records are inserted into the index whenever the table is updated. These records use a different key to the primary table, as specified when the index is created with the WT_SESSION::create method.

A cursor opened on an index has the specified index columns as its key, accessed by WT_CURSOR::set_key and WT_CURSOR::get_key. The value columns default to returning the value columns from the table, but this can be overridden by configuring a projection cursor (see Projections), which can access the table key columns or a subset of the value columns.

File cursors

WiredTiger's schema layer can be bypassed by opening cursors with a "file:" URI, using the name of the underlying file. This can be useful for seeing the contents of a column group or index without reading all of the columns from the table.

For example, if an index becomes inconsistent with its primary, a file cursor can read from the index without errors (even though some of the keys that are returned may not exist in the primary).

Statistics cursors

Cursors can return run-time statistics about the WiredTiger engine as well as statistics for the underlying row- and column-store files. Each cursor iteration sets three separate values: a printable description of the entry, a printable version of the entry's value, and the entry's unsigned 64-bit integral value.

The statistic key is an integer from the list of keys in Statistics Keys.

The following is an example of printing run-time statistics about the WiredTiger engine:

        if ((ret = session->open_cursor(session,
            "statistics:", NULL, NULL, &cursor)) != 0)
                return (ret);

        return (print_cursor(cursor));

The following is an example of printing statistics about an underlying file:

        if ((ret = session->open_cursor(session,
            "statistics:file:access.wt", NULL, NULL, &cursor)) != 0)
                return (ret);

        return (print_cursor(cursor));

Both examples can use a common display routine that iterates through the statistics until the cursor returns the end of the list.

int
print_cursor(WT_CURSOR *cursor)
{
        const char *desc, *pvalue;
        uint64_t value;
        int ret;

        while (
            (ret = cursor->next(cursor)) == 0 &&
            (ret = cursor->get_value(cursor, &desc, &pvalue, &value)) == 0)
                printf("%s=%s\n", desc, pvalue);

        return (ret == WT_NOTFOUND ? 0 : ret);
}

Projections

Cursors on tables, column groups 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.

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), there is no need to access any column groups.

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.

For WT_CURSOR::get_key and WT_CURSOR::get_value in raw mode, the WT_ITEM can be split into columns by calling wiredtiger_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 wiredtiger_struct_pack for the cursor's key_format or value_format, respectively.