diff options
Diffstat (limited to 'src/third_party/wiredtiger/src/docs/cursors.dox')
-rw-r--r-- | src/third_party/wiredtiger/src/docs/cursors.dox | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/src/third_party/wiredtiger/src/docs/cursors.dox b/src/third_party/wiredtiger/src/docs/cursors.dox new file mode 100644 index 00000000000..06f4321ad02 --- /dev/null +++ b/src/third_party/wiredtiger/src/docs/cursors.dox @@ -0,0 +1,130 @@ +/*! @m_page{{c,java},cursors,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 @subpage cursor_ops for a description of how to use cursors. + +@section cursor_types Cursor types + +@copydoc doc_cursor_types + +See the following for more details: + +- @subpage data_sources +- @ref metadata +- @ref cursor_log + +@section cursor_projections Projections + +Cursors on tables and indices can return a subset of columns. This is done by +listing the column names in parenthesis in the <code>uri</code> parameter to +WT_SESSION::open_cursor. Only the fields from the listed columns are returned +by WT_CURSOR::get_value. + +The @ex_ref{ex_schema.c} example creates a table where the value format is +\c "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: + +@snippet ex_schema.c Return a subset of values from the table + +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 @ref schema_index_projections for +more information. + +@section cursors_transactions Cursors and Transactions + +If there is a transaction active in a session, cursors operate in the +context of that transaction. Reads performed while a transaction is +active inherit the isolation level of the transaction, and updates +performed within a transaction are made durable by calling +WT_SESSION::commit_transaction, or discarded by calling +WT_SESSION::rollback_transaction. + +If no transaction is active, cursor reads are performed at the isolation +level of the session, set with the \c isolation configuration key to +WT_CONNECTION::open_session and successful updates are automatically +committed before the update operation completes. + +Any operation that consists of multiple related updates should be +enclosed in an explicit transaction to ensure that the updates are +applied atomically. + +At \c read-committed (the default) or \c snapshot isolation levels, +committed changes from concurrent transactions become visible when no +cursor is positioned. In other words, at these isolation levels, all +cursors in a session read from a stable snapshot while any cursor in the +session remains positioned. + +Cursor positions survive transaction boundaries, unless a transaction +is rolled back. When a transaction is rolled-back either implicitly +or explicitly, all cursors in the session are reset as if the +WT_CURSOR::reset method was called, discarding any cursor position as +well as any key and value. + +See @ref transactions for more information. + +@section cursor_raw Raw mode + +Cursors can be configured for raw mode by specifying the \c "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 +@m_if{c} +WT_ITEM +@m_else +byte array +@m_endif +in the variable-length +argument list instead of a separate argument for each column. + +@m_if{c} +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 \c key_format or \c 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 \c key_format or \c value_format, respectively. + +The @ex_ref{ex_schema.c} example creates a table where the value format is +\c "5sHq", where the initial string is the country, the short is a year, +and the long is a population. +@m_endif +The following example lists the table record +values, using raw mode: + +@snippet ex_schema.c List the records in the table using raw mode. + +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: + +@snippet ex_schema.c Return a subset of values from the table using raw mode + +@section metadata 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 +\c 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: + +@snippet ex_all.c Open a cursor on the metadata + +The metadata cursor is read-only, and the metadata cannot be modified. + +*/ |