Common operations in WiredTiger are performed using Cursor handles. A cursor includes:
Cursors are created using the Session.open_cursor method. For example, from the program ex_cursor.java:
Another example from the same program:
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 in Java for more information on available cursor types.
Cursors remain open until either Cursor.close is called or the cursor's session is closed, which may either be in Session.close or 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 Cursor.reset method:
To move a cursor forward in the data source, use the cursor Cursor.next method:
If the Cursor.next method is called on a cursor without a position in the data source, it is positioned at the beginning of the data source.
To move a cursor backward in the data source, use the cursor Cursor.prev method:
If the Cursor.prev method is called on a cursor without a position in the data source, it is positioned at the end of the data source.
To position a cursor at a specific location in the data source, use the Cursor.search method:
To position a cursor at or near a location in the data source, use the Cursor.search_near method:
Cursor positions do not survive transactions: cursors that are open during Session.begin_transaction, Session.commit_transaction or Session.rollback_transaction will lose their position as if Cursor.reset was called.
Cursors can be configured to move to a random position with Cursor.next is called, see Cursor random in Java for details.
To insert new data, and optionally update existing data, using a cursor, use the Cursor.insert method:
To update existing data using a cursor, use the Cursor.update method:
To remove existing data using a cursor, use the Cursor.remove method:
The Session.open_cursor overwrite
configuration is true
by default, causing Cursor.insert, Cursor.remove and Cursor.update to ignore the current state of the record, and these methods will succeed regardless of whether or not the record previously exists.
When an application configures overwrite
to false
, Cursor.insert will fail with WT_DUPLICATE_KEY if the record previously exists, and Cursor.update and Cursor.remove will fail with WT_NOTFOUND if the record does not previously exist.
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 Cursor.search, Cursor.insert, Cursor.update and 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 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.
When applications pass pointers to Cursor.set_key or Cursor.set_value, which can be a WT_ITEM or a string, the application is required to keep the memory valid until the next operation that successfully positions the cursor. These operations are Cursor.remove, Cursor.search, Cursor.search_near and Cursor.update, but do not include Cursor.insert, as it does not position the cursor.
If such an operation fails (for example, due to a WT_ROLLBACK error), it may be retried without calling Cursor.set_key or Cursor.set_value again. That is, the cursor may still reference the application-supplied memory until it is successfully positioned.