1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
/*! @page 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 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 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 do not survive transaction boundaries. When a
transaction is started with the WT_SESSION:begin_transaction or ended
with either WT_SESSION::commit_transaction or
WT_SESSION::rollback_transaction, all open cursors are reset, as if the
WT_CURSOR::reset method was called. The cursor reset discards any
cursor position as well as the key and value.
Applications that need to continue an operation across a transaction
boundary must make a copy of the cursor's key, and re-position the cursor
with WT_CURSOR::search to continue the operation, dealing with cases
where the record may no longer be available due to a WT_CURSOR::remove
or WT_SESSION::rollback_transaction.
See @ref transactions for more information.
@section cursor_types Cursor types
The following are some of common builtin cursor types:
<table>
@hrow{URI, Type}
@row{<tt>colgroup:\<tablename\>.\<columnset\></tt>,
column group cursor}
@row{<tt>table:\<tablename\></tt>,
table cursor (key=table key\, value=table value)}
@row{<tt>file:\<filename\></tt>,
file cursor (key=file key\, value=file value)}
@row{<tt>index:\<tablename\>.\<indexname\></tt>,
index cursor (key=index key\, value=table value)}
@row{<tt>statistics:[file</tt><tt>:\<filename\>]</tt>,
database or file statistics (key=(int)\,
value=(string)description\, (string)value\, (uint64_t)value)}
</table>
See @subpage data_sources for the full list.
@section cursor_projections 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
<code>uri</code> 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.
@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 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 \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 ::wiredtiger_struct_pack for the
cursor's \c key_format or \c value_format, respectively.
*/
|
