Cursor operations

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

Opening a cursor

Cursors are created using the WT_SESSION::open_cursor method. The following are examples from the example program ex_cursor.c:

        ret = session->open_cursor(session, "table:world", NULL, NULL, &cursor);

        ret = session->open_cursor(session,
            "table:world(country,population)", NULL, NULL, &cursor);

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:

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

See Cursors for more information on available cursor types.

Closing a cursor

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.

Positioning a cursor

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:

int
cursor_reset(WT_CURSOR *cursor)
{
        return (cursor->reset(cursor));
}

To move a cursor forward or backward in the data source, use the cursor WT_CURSOR::next and WT_CURSOR::prev methods:

int
cursor_forward_scan(WT_CURSOR *cursor)
{
        const char *key, *value;
        int ret;

        while ((ret = cursor->next(cursor)) == 0) {
                ret = cursor->get_key(cursor, &key);
                ret = cursor->get_value(cursor, &value);
        }
        return (ret);
}

int
cursor_reverse_scan(WT_CURSOR *cursor)
{
        const char *key, *value;
        int ret;

        while ((ret = cursor->prev(cursor)) == 0) {
                ret = cursor->get_key(cursor, &key);
                ret = cursor->get_value(cursor, &value);
        }
        return (ret);
}

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:

int
cursor_search(WT_CURSOR *cursor)
{
        const char *value;
        int ret;

        cursor->set_key(cursor, "foo");

        if ((ret = cursor->search(cursor)) != 0)
                ret = cursor->get_value(cursor, &value);

        return (ret);
}

To position a cursor at or near a location in the data source, use the WT_CURSOR::search_near method:

int
cursor_search_near(WT_CURSOR *cursor)
{
        const char *key, *value;
        int exact, ret;

        cursor->set_key(cursor, "foo");

        if ((ret = cursor->search_near(cursor, &exact)) == 0) {
                switch (exact) {
                case -1:        /* Returned key smaller than search key */
                        ret = cursor->get_key(cursor, &key);
                        break;
                case 0:         /* Exact match found */
                        break;
                case 1:         /* Returned key larger than search key */
                        ret = cursor->get_key(cursor, &key);
                        break;
                }

                ret = cursor->get_value(cursor, &value);
        }

        return (ret);
}

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.

Inserting and updating

To insert new data, and optionally update existing data, using a cursor, use the WT_CURSOR::insert method:

int
cursor_insert(WT_CURSOR *cursor)
{
        cursor->set_key(cursor, "foo");
        cursor->set_value(cursor, "bar");

        return (cursor->insert(cursor));
}

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:

int
cursor_update(WT_CURSOR *cursor)
{
        cursor->set_key(cursor, "foo");
        cursor->set_value(cursor, "newbar");

        return (cursor->update(cursor));
}

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:

int
cursor_remove(WT_CURSOR *cursor)
{
        cursor->set_key(cursor, "foo");
        return (cursor->remove(cursor));
}

Cursor position after error

After any cursor handle method failure, the cursor's position is undetermined. Applications that cannot re-position the cursor after failure must duplicate the cursor before calling a cursor method that will attempt to re-position the cursor.