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
|
/*! @page cursor_ops 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
@section cursor_opening Opening a cursor
Cursors are created using the WT_SESSION::open_cursor method. The
following are examples from the example program @ex_ref{ex_cursor.c}:
@snippet ex_cursor.c open cursor #1
@snippet ex_cursor.c open cursor #2
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:
@snippet ex_cursor.c open cursor #3
See @ref cursors for more information on available cursor types.
@section cursor_position 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:
@snippet ex_cursor.c cursor reset
To move a cursor forward or backward in the data source, use the cursor
WT_CURSOR::next and WT_CURSOR::prev methods:
@snippet ex_cursor.c cursor next
@snippet ex_cursor.c cursor prev
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:
@snippet ex_cursor.c cursor search
To position a cursor at or near a location in the data source, use the
WT_CURSOR::search_near method:
@snippet ex_cursor.c cursor search near
@section cursor_writes Inserting and updating
To insert new data, and optionally update existing data, using a cursor,
use the WT_CURSOR::insert method:
@snippet ex_cursor.c cursor insert
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 <code>overwrite</code> 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 <code>overwrite</code> 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:
@snippet ex_cursor.c cursor update
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:
@snippet ex_cursor.c cursor remove
@section cursor_error 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. @notyet{cursor duplication}
*/
|
