-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathcursors.html
130 lines (130 loc) · 11.8 KB
/
cursors.html
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>WiredTiger: Cursors</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 1.4.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li><a href="license.html"><span>License</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('cursors.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Cursors </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Common operations in WiredTiger are performed using <a class="el" href="struct_w_t___c_u_r_s_o_r.html" title="A WT_CURSOR handle is the interface to a cursor.">WT_CURSOR</a> handles.</p>
<p>A cursor includes:</p>
<ul>
<li>a position within a data source</li>
<li>getter/setters for key and value fields</li>
<li>encoding of fields to store in the data source</li>
<li>methods to navigate within and iterate through the data</li>
</ul>
<p>See <a class="el" href="cursor_ops.html">Cursor operations</a> for a description of how to use cursors.</p>
<h1><a class="anchor" id="cursors_transactions"></a>
Cursors and Transactions</h1>
<p>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 <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a712226eca5ade5bd123026c624468fa2" title="Commit the current transaction.">WT_SESSION::commit_transaction</a>, or discarded by calling <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#ab45f521464ad9e54d9b15efc2ffe20a1" title="Roll back the current transaction.">WT_SESSION::rollback_transaction</a>.</p>
<p>If no transaction is active, cursor reads are performed at the isolation level of the session, set with the <code>isolation</code> configuration key to <a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#afc75c44ff4497627c59d9b6aaa64c9d8" title="Open a session.">WT_CONNECTION::open_session</a> and successful updates are automatically committed before the update operation completes.</p>
<p>Any operation that consists of multiple related updates should be enclosed in an explicit transaction to ensure that the updates are applied atomically.</p>
<p>At <code>read-committed</code> (the default) or <code>snapshot</code> 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.</p>
<p>Cursor positions do not survive transaction boundaries. When a transaction is started with the <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a7e26b16b26b5870498752322fad790bf" title="Start a transaction in this session.">WT_SESSION::begin_transaction</a> or ended with either <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a712226eca5ade5bd123026c624468fa2" title="Commit the current transaction.">WT_SESSION::commit_transaction</a> or <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#ab45f521464ad9e54d9b15efc2ffe20a1" title="Roll back the current transaction.">WT_SESSION::rollback_transaction</a>, all open cursors are reset, as if the <a class="el" href="struct_w_t___c_u_r_s_o_r.html#afc1b42c22c9c85e1ba08ce3b34437565" title="Reset the position of the cursor.">WT_CURSOR::reset</a> method was called. The cursor reset discards any cursor position as well as the key and value.</p>
<p>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 <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a7e25b2ced2cf3ec68bd5429bf921c79f" title="Move to the record matching the key.">WT_CURSOR::search</a> to continue the operation, dealing with cases where the record may no longer be available due to a <a class="el" href="struct_w_t___c_u_r_s_o_r.html#abbba24fe607fee519c4c9c4669cd4455" title="Remove a record.">WT_CURSOR::remove</a> or <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#ab45f521464ad9e54d9b15efc2ffe20a1" title="Roll back the current transaction.">WT_SESSION::rollback_transaction</a>.</p>
<p>See <a class="el" href="transactions.html">Transactions</a> for more information.</p>
<h1><a class="anchor" id="cursor_types"></a>
Cursor types</h1>
<p>The following are some of the common builtin cursor types:</p>
<table class="doxtable">
<tr>
<th>URI</th><th>Type</th><th>Notes </th></tr>
<tr>
<td><code>backup:</code></td><td>hot backup cursor</td><td>See also: <a class="el" href="hot_backup.html">Hot backup</a> </td></tr>
<tr>
<td><code>colgroup:<tablename>.<columnset></code></td><td>column group cursor</td><td></td></tr>
<tr>
<td><code>config:[<uri>]</code></td><td>object configuration cursor</td><td>(key=config string, value=config value) </td></tr>
<tr>
<td><code>file:<filename></code></td><td>file cursor (key=file key, value=file value)</td><td></td></tr>
<tr>
<td><code>index:<tablename>.<indexname></code></td><td>index cursor (key=index key, value=table value)</td><td></td></tr>
<tr>
<td><code>lsm:<name></code></td><td>LSM cursor (key=LSM key, value=LSM value)</td><td>See also: <a class="el" href="lsm.html">Log-Structured Merge Trees</a> </td></tr>
<tr>
<td><code>statistics:[file</code><code>:<filename>]</code></td><td>database or file statistics (key=(int), value=(string)description, (string)value, (uint64_t)value)</td><td></td></tr>
<tr>
<td><code>table:<tablename></code></td><td>table cursor (key=table key, value=table value)</td><td></td></tr>
</table>
<p>See <a class="el" href="data_sources.html">Data Sources</a> for the full list.</p>
<h1><a class="anchor" id="cursor_projections"></a>
Projections</h1>
<p>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 <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d" title="Open a new cursor on a data source or duplicate an existing cursor.">WT_SESSION::open_cursor</a>. Only the fields from the listed columns are returned by <a class="el" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01" title="Get the value for the current record.">WT_CURSOR::get_value</a>.</p>
<p>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 <a class="el" href="schema.html#schema_indices">Indices</a> for more details.</p>
<h1><a class="anchor" id="cursor_raw"></a>
Raw mode</h1>
<p>Cursors can be configured for raw mode by specifying the <code>"raw"</code> config keyword to <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d" title="Open a new cursor on a data source or duplicate an existing cursor.">WT_SESSION::open_cursor</a>. In this mode, the methods <a class="el" href="struct_w_t___c_u_r_s_o_r.html#af19f6f9d9c7fc248ab38879032620b2f" title="Get the key for the current record.">WT_CURSOR::get_key</a>, <a class="el" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01" title="Get the value for the current record.">WT_CURSOR::get_value</a>, <a class="el" href="struct_w_t___c_u_r_s_o_r.html#ad1088d719df40babc1f57d086691ebdc" title="Set the key for the next operation.">WT_CURSOR::set_key</a> and <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a27f7cbd0cd3e561f6a145704813ad64c" title="Set the value for the next operation.">WT_CURSOR::set_value</a> all take a single <a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed.">WT_ITEM</a> in the variable-length argument list instead of a separate argument for each column.</p>
<p>For <a class="el" href="struct_w_t___c_u_r_s_o_r.html#af19f6f9d9c7fc248ab38879032620b2f" title="Get the key for the current record.">WT_CURSOR::get_key</a> and <a class="el" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01" title="Get the value for the current record.">WT_CURSOR::get_value</a> in raw mode, the <a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed.">WT_ITEM</a> can be split into columns by calling <a class="el" href="group__wt.html#ga1db8298185374dbb61b398a4e9a3d1c8" title="Unpack a structure from a buffer.">wiredtiger_struct_unpack</a> with the cursor's <code>key_format</code> or <code>value_format</code>, respectively. For <a class="el" href="struct_w_t___c_u_r_s_o_r.html#ad1088d719df40babc1f57d086691ebdc" title="Set the key for the next operation.">WT_CURSOR::set_key</a> and <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a27f7cbd0cd3e561f6a145704813ad64c" title="Set the value for the next operation.">WT_CURSOR::set_value</a> in raw mode, the <a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed.">WT_ITEM</a> should be equivalent to calling <a class="el" href="group__wt.html#ga58d055cb4d054715bebd58a2cb713b2d" title="Pack a structure into a buffer.">wiredtiger_struct_pack</a> for the cursor's <code>key_format</code> or <code>value_format</code>, respectively. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming.html">Writing WiredTiger applications</a></li>
<li class="footer">Copyright (c) 2008-2013 WiredTiger, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>