-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathconfig_strings.html
160 lines (160 loc) · 12.3 KB
/
config_strings.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
156
157
158
159
160
<!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: Configuration Strings</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);
$(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.0.1</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.3.1 -->
<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('config_strings.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Configuration Strings </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="config_intro"></a>
Introduction</h1>
<p>Methods in WiredTiger take a configuration string to provide optional arguments and configure non-standard behaviors. These strings are simple comma-separated lists of <code>"<key>=<value>"</code> pairs, and all have the same format:</p>
<pre>
[key['='value]][','[key['='value]]]*
</pre><p>Keys and values and values that consist of alphanumeric characters can be specified directly. More precisely, keys or values that match this regular expression do not require quotes:</p>
<pre>
[-_0-9A-Za-z/][^\t\r\n :=,\])}]*
</pre><p>More complex keys and values can be specified by quoting them with double quotes.</p>
<p>For example, a configuration string is used when opening a connection to a database to specify if the database should be created and to set the cache size:</p>
<div class="fragment"><div class="line"> ret = <a class="code" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed" title="Open a connection to a database.">wiredtiger_open</a>(home, NULL, <span class="stringliteral">"create,cache_size=500M"</span>, &conn);</div>
</div><!-- fragment --><p> Configuration strings are also used to configure the table schema. For example, to create a table that uses C language strings for keys and values:</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" title="Create a table, column group, index or file.">create</a>(session,</div>
<div class="line"> <span class="stringliteral">"table:mytable"</span>, <span class="stringliteral">"key_format=S,value_format=S"</span>);</div>
</div><!-- fragment --><p> To handle more complex schema configuration, such as specifying multiple columns in a table, values are nested using parentheses. For example:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Create a table with columns: keys are record numbers, values are</span></div>
<div class="line"><span class="comment"> * (string, signed 32-bit integer, unsigned 16-bit integer).</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> ret = session-><a class="code" href="struct_w_t___s_e_s_s_i_o_n.html#a358ca4141d59c345f401c58501276bbb" title="Create a table, column group, index or file.">create</a>(session, <span class="stringliteral">"table:mytable"</span>,</div>
<div class="line"> <span class="stringliteral">"key_format=r,value_format=SiH,"</span></div>
<div class="line"> <span class="stringliteral">"columns=(id,department,salary,year-started)"</span>);</div>
</div><!-- fragment --><p> All types of parentheses are treated equivalently by the parser.</p>
<p>When an integer values is expected, the value may have multiplier characters appended, as follows:</p>
<table class="doxtable">
<tr>
<th>Character</th><th>Meaning</th><th>Change to value </th></tr>
<tr>
<td><code>B</code> or <code>b</code> </td><td>byte</td><td>no change </td></tr>
<tr>
<td><code>K</code> or <code>k</code> </td><td>kilobyte</td><td>multiply by 2^10 </td></tr>
<tr>
<td><code>M</code> or <code>m</code> </td><td>megabyte</td><td>multiply by 2^20 </td></tr>
<tr>
<td><code>G</code> or <code>g</code> </td><td>gigabyte</td><td>multiply by 2^30 </td></tr>
<tr>
<td><code>T</code> or <code>t</code> </td><td>terabyte</td><td>multiply by 2^40 </td></tr>
<tr>
<td><code>P</code> or <code>p</code> </td><td>petabyte</td><td>multiply by 2^50 </td></tr>
</table>
<p>For example, the value <code>500B</code> is the same as entering the number <code>500</code>, the value <code>500K</code> is the same as <code>512000</code> and the string <code>500GB</code> is the same as <code>536870912000</code>.</p>
<p>Values of type of "boolean" can be set to any of <code>false</code>, <code>true</code>, <code>0</code> or <code>1</code>. If no value is specified for a key, the value <code>1</code> is implied. For example, all of the following forms of the <code>overwrite</code> configuration string are identical:</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" title="Open a new cursor on a data source or duplicate an existing cursor.">open_cursor</a>(session, <span class="stringliteral">"table:mytable"</span>, NULL,</div>
<div class="line"> <span class="stringliteral">"overwrite"</span>, &cursor);</div>
<div class="line"> ret = session-><a class="code" 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.">open_cursor</a>(session, <span class="stringliteral">"table:mytable"</span>, NULL,</div>
<div class="line"> <span class="stringliteral">"overwrite=true"</span>, &cursor);</div>
<div class="line"> ret = session-><a class="code" 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.">open_cursor</a>(session, <span class="stringliteral">"table:mytable"</span>, NULL,</div>
<div class="line"> <span class="stringliteral">"overwrite=1"</span>, &cursor);</div>
</div><!-- fragment --><p> Configuration strings are processed in order from left to right, with later settings overriding earlier ones (unless multiple settings for a key are supported by the method).</p>
<p>Superfluous commas and whitespace in the configuration string are ignored (including at the beginning and end of the string), so it is always safe to combine two configuration strings by concatenating them with a comma in between.</p>
<p>Empty configuration strings may be represented in C or C++ by passing <code>NULL</code>.</p>
<h1><a class="anchor" id="config_json"></a>
JavaScript Object Notation (JSON) compatibility</h1>
<p>WiredTiger configuration strings are compatible with <a href="http://www.json.org/">JavaScript Object Notation (JSON)</a>, and will accept additional formatting as follows:</p>
<ul>
<li>parentheses may be round or square brackets or curly braces: <code>'()'</code>, <code>'[]'</code> or <code>'{}'</code></li>
<li>the whole configuration string may optionally be wrapped in parentheses</li>
<li>the key/value separator can be a colon: <code>':'</code></li>
<li>keys and values may be in double quotes: <code>"key" = "value"</code></li>
<li>quoted strings are interpreted as UTF-8 values</li>
</ul>
<p>The result of this relaxed parsing is that applications may pass strings representing valid <a href="http://json.org/">JSON objects</a> wherever configuration strings are required.</p>
<p>For example, in Python, code might look as follows:</p>
<div class="fragment"><div class="line"><span class="keyword">import</span> json</div>
<div class="line">config = json.dumps({</div>
<div class="line"> <span class="stringliteral">"key_format"</span> : <span class="stringliteral">"r"</span>,</div>
<div class="line"> <span class="stringliteral">"value_format"</span> : <span class="stringliteral">"5sHQ"</span>,</div>
<div class="line"> <span class="stringliteral">"columns"</span> : (<span class="stringliteral">"id"</span>, <span class="stringliteral">"country"</span>, <span class="stringliteral">"year"</span>, <span class="stringliteral">"population"</span>),</div>
<div class="line"> <span class="stringliteral">"colgroup.population"</span> : [<span class="stringliteral">"population"</span>],</div>
<div class="line"> <span class="stringliteral">"index.country_year"</span> : [<span class="stringliteral">"country"</span>, <span class="stringliteral">"year"</span>]</div>
<div class="line">})</div>
</div><!-- fragment --><p>Because JSON compatibility allows colons to be used as key/value separators, WiredTiger URIs may require quoting. For example, the following <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#a6550c9079198955c5071583941c85bbf" title="Write a transactionally consistent snapshot of a database or set of objects.">WT_SESSION::checkpoint</a> call specifies a set of URIs as checkpoint targets, using double-quote characters to keep the parser from treating the colon characters as JSON name/value separators:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Checkpoint a list of objects.</span></div>
<div class="line"><span class="comment"> * JSON parsing requires quoting the list of target URIs.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"> ret = session-></div>
<div class="line"> checkpoint(session, <span class="stringliteral">"target=(\"table:table1\",\"table:table2\")"</span>);</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-2013 WiredTiger, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>