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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<!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="navtreedata.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 3.2.1</span>
</div>
<div id="projectbrief"><!-- 3.2.1 --></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.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></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. 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="cursor_types"></a>
Cursor types</h1>
<p>The following are the builtin basic cursor types: </p><table class="doxtable">
<tr>
<th>URI</th><th>Type</th><th>Notes </th></tr>
<tr>
<td><code>table:<table name>[<projection>]</code></td><td>table cursor</td><td>table key, table value(s) with optional projection of columns </td></tr>
<tr>
<td><code>colgroup:<table name>:<column group name></code></td><td>column group cursor</td><td>table key, column group value(s) </td></tr>
<tr>
<td><code>index:<table name>:<index name>[<projection>]</code></td><td>index cursor</td><td>key=index key, value=table value(s) with optional projection of columns </td></tr>
<tr>
<td><code>join:table:<table name>[<projection>]</code></td><td>join cursor</td><td>key=table key, value=table value(s) with optional projection of columns </td></tr>
</table>
<p>Some administrative tasks can be accomplished using the following special cursor types that give access to data managed by WiredTiger: </p><table class="doxtable">
<tr>
<th>URI</th><th>Type</th><th>Notes </th></tr>
<tr>
<td><code>backup:</code></td><td>backup cursor</td><td>key=<code>string</code>, see <a class="el" href="backup.html">Backups</a> for details </td></tr>
<tr>
<td><code>log:</code></td><td>log cursor</td><td>key=<code>(long fileID, long offset, int seqno)</code>,<br />
value=<code>(uint64_t txnid, uint32_t rectype,<br />
uint32_t optype, uint32_t fileid,<br />
<a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed, including a pointer to the data and a length. ">WT_ITEM</a> key, <a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed, including a pointer to the data and a length. ">WT_ITEM</a> value)</code>,<br />
see <a class="el" href="cursor_log.html">Log cursors</a> for details </td></tr>
<tr>
<td><code>metadata:[create]</code></td><td>metadata cursor (optionally only returning configuration strings for <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a358ca4141d59c345f401c58501276bbb" title="Create a table, column group, index or file. ">WT_SESSION::create</a> if <code>create</code> is appended</td><td>key=<code>string</code>, value=<code>string</code>,<br />
see <a class="el" href="cursors.html#metadata">Reading WiredTiger Metadata</a> for details </td></tr>
<tr>
<td><code>statistics:[<data source URI>]</code></td><td>database</td><td>data source</td><td>join or session statistics cursor</td><td>key=<code>int id</code>,<br />
value=<code>(string description, string value, uint64_t value)</code>,<br />
see <a class="el" href="data_sources.html#data_statistics">Statistics Data</a> for details </td></tr>
</table>
<p>Advanced applications may also open the following low-level cursor types: </p><table class="doxtable">
<tr>
<th>URI</th><th>Type</th><th>Notes </th></tr>
<tr>
<td><code>file:<file name></code></td><td>file cursor</td><td>file key, file value(s) </td></tr>
<tr>
<td><code>lsm:<name></code></td><td>LSM cursor (key=LSM key, value=LSM value)</td><td>LSM key, LSM value,<br />
see <a class="el" href="lsm.html">Log-Structured Merge Trees</a> </td></tr>
</table>
<p>See the following for more details:</p>
<ul>
<li><a class="el" href="data_sources.html">Data Sources</a></li>
<li><a class="el" href="cursors.html#metadata">Reading WiredTiger Metadata</a></li>
<li><a class="el" href="cursor_log.html">Log cursors</a></li>
<li><a class="el" href="cursor_join.html">Join cursors</a></li>
</ul>
<h1><a class="anchor" id="cursor_projections"></a>
Projections</h1>
<p>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 <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>The <a class="el" href="ex_schema_8c-example.html">ex_schema.c</a> example creates a table where the value format is <code>"5sHq"</code>, 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:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Use a projection to return just the table's country and year columns.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> error_check(session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"table:poptable(country,year)"</span>, NULL, NULL, &cursor));</div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b">next</a>(cursor)) == 0) {</div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01">get_value</a>(cursor, &country, &year));</div><div class="line"> printf(<span class="stringliteral">"country %s, year %"</span> PRIu16 <span class="stringliteral">"\n"</span>, country, year);</div><div class="line"> }</div></div><!-- fragment --><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_index_projections">Index cursor projections</a> for more information.</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#adad5965cd4a60f65b5ac01f7ca6d1fc0" 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. A call to <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b" title="Return the next record. ">WT_CURSOR::next</a> or <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a43d6664d2f68902aa63f933864242e76" title="Return the previous record. ">WT_CURSOR::prev</a> on a positioned cursor will not update the snapshot.</p>
<p>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 <a class="el" href="struct_w_t___c_u_r_s_o_r.html#afc1b42c22c9c85e1ba08ce3b34437565" title="Reset the cursor. ">WT_CURSOR::reset</a> method was called, discarding any cursor position as well as any key and value.</p>
<p>See <a class="el" href="transactions.html">Transactions</a> for more information.</p>
<h1><a class="anchor" id="cursors_eviction"></a>
Cursors and Eviction</h1>
<p>Cursor positions hold resources that can inhibit the eviction of memory pages. If a cursor is active on a page being considered for eviction, the eviction will defer until the cursor is moved or reset. To avoid this and to keep resources freed in general, an application should call <a class="el" href="struct_w_t___c_u_r_s_o_r.html#afc1b42c22c9c85e1ba08ce3b34437565" title="Reset the cursor. ">WT_CURSOR::reset</a> during times it does not need to keep the cursor positioned. A cursor that has been reset is not active and will not inhibit eviction.</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, including a pointer to the data and a length. ">WT_ITEM</a> in the variable-length argument list instead of a separate argument for each column.</p>
<p><a class="el" href="group__wt.html#struct_w_t___i_t_e_m" title="A raw item of data to be managed, including a pointer to the data and a length. ">WT_ITEM</a> structures do not need to be cleared before use.</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, including a pointer to the data and a length. ">WT_ITEM</a> can be split into columns by calling <a class="el" href="struct_w_t___e_x_t_e_n_s_i_o_n___a_p_i.html#a4bff77f867b83e76a65426eabd9e6da3" title="Unpack a structure from a buffer. ">WT_EXTENSION_API::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, including a pointer to the data and a length. ">WT_ITEM</a> should be equivalent to calling <a class="el" href="struct_w_t___e_x_t_e_n_s_i_o_n___a_p_i.html#a353dd240d0f7b32910d1bb97c0762ee8" title="Pack a structure into a buffer. ">WT_EXTENSION_API::struct_pack</a> for the cursor's <code>key_format</code> or <code>value_format</code>, respectively.</p>
<p>The <a class="el" href="ex_schema_8c-example.html">ex_schema.c</a> example creates a table where the value format is <code>"5sHq"</code>, where the initial string is the country, the short is a year, and the long is a population. The following example lists the table record values, using raw mode:</p>
<div class="fragment"><div class="line"> <span class="comment">/* List the records in the table using raw mode. */</span></div><div class="line"> error_check(session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"table:poptable"</span>, NULL, <span class="stringliteral">"raw"</span>, &cursor));</div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b">next</a>(cursor)) == 0) {</div><div class="line"> <a class="code" href="group__wt.html#struct_w_t___i_t_e_m">WT_ITEM</a> key, value;</div><div class="line"></div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af19f6f9d9c7fc248ab38879032620b2f">get_key</a>(cursor, &key));</div><div class="line"> error_check(<a class="code" href="group__wt.html#ga7cdc8c688f2c15303188ed6999dcc1b4">wiredtiger_struct_unpack</a>(session, key.<a class="code" href="group__wt.html#a57f5e62aa968275d7e398cfa70e49450">data</a>, key.<a class="code" href="group__wt.html#abd8b1299dfb5c54dc049fa42a4680b55">size</a>, <span class="stringliteral">"r"</span>, &recno));</div><div class="line"> printf(<span class="stringliteral">"ID %"</span> PRIu64, recno);</div><div class="line"></div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01">get_value</a>(cursor, &value));</div><div class="line"> error_check(<a class="code" href="group__wt.html#ga7cdc8c688f2c15303188ed6999dcc1b4">wiredtiger_struct_unpack</a>(</div><div class="line"> session, value.<a class="code" href="group__wt.html#a57f5e62aa968275d7e398cfa70e49450">data</a>, value.<a class="code" href="group__wt.html#abd8b1299dfb5c54dc049fa42a4680b55">size</a>, <span class="stringliteral">"5sHQ"</span>, &country, &year, &population));</div><div class="line"> printf(</div><div class="line"> <span class="stringliteral">": country %s, year %"</span> PRIu16 <span class="stringliteral">", population %"</span> PRIu64 <span class="stringliteral">"\n"</span>, country, year, population);</div><div class="line"> }</div><div class="line"> scan_end_check(ret == <a class="code" href="group__wt.html#ga3c9e1b494d95cf34404ab7a974af6bf8">WT_NOTFOUND</a>);</div></div><!-- fragment --><p> 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:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Use a projection to return just the table's country and year columns, using raw mode.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> error_check(</div><div class="line"> session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"table:poptable(country,year)"</span>, NULL, <span class="stringliteral">"raw"</span>, &cursor));</div><div class="line"> <span class="keywordflow">while</span> ((ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#a0503f16bd8f3d05aa3552f229b3a8e1b">next</a>(cursor)) == 0) {</div><div class="line"> <a class="code" href="group__wt.html#struct_w_t___i_t_e_m">WT_ITEM</a> value;</div><div class="line"></div><div class="line"> error_check(cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#af85364a5af50b95bbc46c82e72f75c01">get_value</a>(cursor, &value));</div><div class="line"> error_check(</div><div class="line"> <a class="code" href="group__wt.html#ga7cdc8c688f2c15303188ed6999dcc1b4">wiredtiger_struct_unpack</a>(session, value.<a class="code" href="group__wt.html#a57f5e62aa968275d7e398cfa70e49450">data</a>, value.<a class="code" href="group__wt.html#abd8b1299dfb5c54dc049fa42a4680b55">size</a>, <span class="stringliteral">"5sH"</span>, &country, &year));</div><div class="line"> printf(<span class="stringliteral">"country %s, year %"</span> PRIu16 <span class="stringliteral">"\n"</span>, country, year);</div><div class="line"> }</div><div class="line"> scan_end_check(ret == <a class="code" href="group__wt.html#ga3c9e1b494d95cf34404ab7a974af6bf8">WT_NOTFOUND</a>);</div></div><!-- fragment --> <h1><a class="anchor" id="metadata"></a>
Reading WiredTiger Metadata</h1>
<p>WiredTiger cursors provide access to data from a variety of sources. One of these sources is the list of objects in the database.</p>
<p>To retrieve the list of database objects, open a cursor on the uri <code>metadata:</code>. 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.</p>
<p>For example:</p>
<div class="fragment"><div class="line"> error_check(session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session, <span class="stringliteral">"metadata:"</span>, NULL, NULL, &cursor));</div></div><!-- fragment --><p> To retrieve value strings that are valid arguments for calls to <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a358ca4141d59c345f401c58501276bbb" title="Create a table, column group, index or file. ">WT_SESSION::create</a>, open a cursor on <code>metadata:create</code>.</p>
<p>The metadata cursor is read-only, and the metadata cannot be modified. </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-2019 MongoDB, Inc. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</li>
</ul>
</div>
</body>
</html>
|
