-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathbasic_api.html
155 lines (155 loc) · 15.4 KB
/
basic_api.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
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
<!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: Getting Started with the API</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);
$(window).load(resizeHeight);
</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 2.9.2</span>
</div>
<div id="projectbrief"><!-- 2.9.2 --></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.10 -->
<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="community.html"><span>Community</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('basic_api.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Getting Started with the API </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger applications will generally use the following classes to access and manage data:</p>
<ul>
<li>a <a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database. ">WT_CONNECTION</a> represents a connection to a database. Most applications will only open one connection to a database for each process. All methods in <a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html" title="A connection to a WiredTiger database. ">WT_CONNECTION</a> are thread safe.</li>
<li>a <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html" title="All data operations are performed in the context of a WT_SESSION. ">WT_SESSION</a> represents a context in which database operations are performed. Sessions are opened on a specified connection, and applications must open a single session for each thread accessing the database.</li>
<li>a <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> represents a cursor over a collection of data. Cursors are opened in the context of a session (which may have an associated transaction), and can query and update records. In the common case, a cursor is used to access records in a table. However, cursors can be used on subsets of tables (such as a single column or a projection of multiple columns), as an interface to statistics, configuration data or application-specific data sources.</li>
</ul>
<p>Handles and operations are <a class="el" href="config_strings.html">configured using strings</a>, which keeps the set of methods in the API relatively small and makes the interface very similar regardless of the programming language used in the application. WiredTiger supports the C, C++, Java and Python programming languages (among others).</p>
<p>By default, WiredTiger works as a traditional key/value store, where the keys and values are raw byte arrays accessed using a <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> structure. Keys and values may be up to (4GB - 512B) bytes in size, but depending on how <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> "maximum item sizes" are configured, large key and value items will be stored on overflow pages.</p>
<p>WiredTiger also supports a <a class="el" href="schema.html">schema layer</a> so that keys and values types can be chosen from a list, or composite keys or values made up of columns with any combination of types. The size (4GB - 512B) byte limit on keys and values still applies.</p>
<p>All applications that use WiredTiger will be structured roughly as follows. The code below is taken from the complete example program <a class="el" href="ex_access_8c-example.html">ex_access.c</a>.</p>
<h1><a class="anchor" id="basic_connection"></a>
Connecting to a database</h1>
<p>To access a database, first open a connection and create a session handle for the single thread accessing the database:</p>
<div class="fragment"><div class="line"> <a class="code" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html">WT_CONNECTION</a> *conn;</div>
<div class="line"> <a class="code" href="struct_w_t___c_u_r_s_o_r.html">WT_CURSOR</a> *cursor;</div>
<div class="line"> <a class="code" href="struct_w_t___s_e_s_s_i_o_n.html">WT_SESSION</a> *session;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *key, *value;</div>
<div class="line"> <span class="keywordtype">int</span> ret;</div>
<div class="line"></div>
<div class="line"> <span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Create a clean test directory for this run of the test program if the</span></div>
<div class="line"><span class="comment"> * environment variable isn't already set (as is done by make check).</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> <span class="keywordflow">if</span> (getenv(<span class="stringliteral">"WIREDTIGER_HOME"</span>) == NULL) {</div>
<div class="line"> home = <span class="stringliteral">"WT_HOME"</span>;</div>
<div class="line"> ret = system(<span class="stringliteral">"rm -rf WT_HOME && mkdir WT_HOME"</span>);</div>
<div class="line"> } <span class="keywordflow">else</span></div>
<div class="line"> home = NULL;</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Open a connection to the database, creating it if necessary. */</span></div>
<div class="line"> <span class="keywordflow">if</span> ((ret = <a class="code" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed">wiredtiger_open</a>(home, NULL, <span class="stringliteral">"create"</span>, &conn)) != 0 ||</div>
<div class="line"> (ret = conn-><a class="code" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#afc75c44ff4497627c59d9b6aaa64c9d8">open_session</a>(conn, NULL, NULL, &session)) != 0) {</div>
<div class="line"> fprintf(stderr, <span class="stringliteral">"Error connecting to %s: %s\n"</span>,</div>
<div class="line"> home == NULL ? <span class="stringliteral">"."</span> : home, <a class="code" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd">wiredtiger_strerror</a>(ret));</div>
<div class="line"> <span class="keywordflow">return</span> (EXIT_FAILURE);</div>
<div class="line"> }</div>
</div><!-- fragment --><p> The configuration string <code>"create"</code> is passed to <a class="el" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed" title="Open a connection to a database. ">wiredtiger_open</a> to indicate the database should be created if it does not already exist.</p>
<p>The code block above also shows simple error handling with <a class="el" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd" title="Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...">wiredtiger_strerror</a> (a function that returns a string describing an error code passed as its argument). More complex error handling can be configured by passing an implementation of <a class="el" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html" title="The interface implemented by applications to handle error, informational and progress messages...">WT_EVENT_HANDLER</a> to <a class="el" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed" title="Open a connection to a database. ">wiredtiger_open</a> or <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>.</p>
<h1><a class="anchor" id="basic_create_table"></a>
Creating a table</h1>
<p>Create a table we can use to store data:</p>
<div class="fragment"><div class="line"> ret = session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#a358ca4141d59c345f401c58501276bbb">create</a>(session,</div>
<div class="line"> <span class="stringliteral">"table:access"</span>, <span class="stringliteral">"key_format=S,value_format=S"</span>);</div>
</div><!-- fragment --><p> This call creates a table called <code>"access"</code>, configured to use strings for its key and value columns. (See <a class="el" href="schema.html">Schema, Columns, Column Groups, Indices and Projections</a> for more information on tables with other types of key and value columns.)</p>
<h1><a class="anchor" id="basic_cursors"></a>
Accessing data with cursors</h1>
<p>Now that we have a table, we open a cursor to perform some operations on it:</p>
<div class="fragment"><div class="line"> ret = session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d">open_cursor</a>(session,</div>
<div class="line"> <span class="stringliteral">"table:access"</span>, NULL, NULL, &cursor);</div>
</div><!-- fragment --><p> Here, the string <code>"table:access"</code> specifies that we are opening the cursor on the table named <code>"access"</code>.</p>
<p>Then we insert a new row into the table. The <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> calls put the application's key and value into the cursor, respectively. The <a class="el" href="struct_w_t___c_u_r_s_o_r.html#aac90d9fbcc031570f924db55f8a1cee3" title="Insert a record and optionally update an existing record. ">WT_CURSOR::insert</a> call creates a record containing that value and inserts it into the table.</p>
<div class="fragment"><div class="line"> cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#ad1088d719df40babc1f57d086691ebdc">set_key</a>(cursor, <span class="stringliteral">"key1"</span>); <span class="comment">/* Insert a record. */</span></div>
<div class="line"> cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#a27f7cbd0cd3e561f6a145704813ad64c">set_value</a>(cursor, <span class="stringliteral">"value1"</span>);</div>
<div class="line"> ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#aac90d9fbcc031570f924db55f8a1cee3">insert</a>(cursor);</div>
</div><!-- fragment --><p> Now we iterate through all of the records in the table, printing them out as we go:</p>
<div class="fragment"><div class="line"> ret = cursor-><a class="code" href="struct_w_t___c_u_r_s_o_r.html#afc1b42c22c9c85e1ba08ce3b34437565">reset</a>(cursor); <span class="comment">/* Restart the scan. */</span></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"> ret = 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"> ret = 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"></div>
<div class="line"> printf(<span class="stringliteral">"Got record: %s : %s\n"</span>, key, value);</div>
<div class="line"> }</div>
</div><!-- fragment --><p> Note that the key and value parts of the records are returned as C strings because the table was created that way (even if it was created by a previous run of the example). No data extraction or conversion is required in the application.</p>
<p>Because the cursor was positioned in the table after the <a class="el" href="struct_w_t___c_u_r_s_o_r.html#aac90d9fbcc031570f924db55f8a1cee3" title="Insert a record and optionally update an existing record. ">WT_CURSOR::insert</a> call, we had to re-position it using the WT_CURSOR::first call; if we weren't using the cursor for the call to <a class="el" href="struct_w_t___c_u_r_s_o_r.html#aac90d9fbcc031570f924db55f8a1cee3" title="Insert a record and optionally update an existing record. ">WT_CURSOR::insert</a> above, this loop would simplify to:</p>
<div class="fragment"><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"> ...</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="basic_close"></a>
Closing handles</h1>
<p>Lastly, we close the connection, which implicitly closes the cursor and session handles:</p>
<div class="fragment"><div class="line"> ret = conn-><a class="code" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#af535c517df851eeac8ebf3594d40b545">close</a>(conn, NULL);</div>
</div><!-- fragment --></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-2016 MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>