-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathcustom_collators.html
100 lines (100 loc) · 7.04 KB
/
custom_collators.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
<!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: Custom Collators</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('custom_collators.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Custom Collators </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="custom_collators_intro"></a>
Introduction to Custom Collators</h1>
<p>WiredTiger tables order records based on their keys. Cursors traverse records in key order using <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 in reverse order using <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a43d6664d2f68902aa63f933864242e76" title="Return the previous record. ">WT_CURSOR::prev</a>. By default, WiredTiger uses lexicographic ordering, by comparing the raw bytes of each key to determine their order.</p>
<p>The built-in encoding of types (including integers and strings) is designed to make lexicographic ordering match the natural ordering, including when the key consists of multiple columns, each of which can be a different type.</p>
<p>Applications that need custom ordering of keys can either change the serialized representation so that the lexicographic order matches the required order, or implement the <a class="el" href="struct_w_t___c_o_l_l_a_t_o_r.html" title="The interface implemented by applications to provide custom ordering of records. ">WT_COLLATOR</a> interface to change the comparison routine that WiredTiger uses.</p>
<p>Applications must register their <a class="el" href="struct_w_t___c_o_l_l_a_t_o_r.html" title="The interface implemented by applications to provide custom ordering of records. ">WT_COLLATOR</a> implementations using <a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#a89290382c55f20e5a4e1bc9216c7a8c8" title="Add a custom collation function. ">WT_CONNECTION::add_collator</a>. They are then configured by passing <code>"collator=..."</code> 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> when creating a table or index.</p>
<p>See <a class="el" href="ex_extending_8c-example.html">ex_extending.c</a> for more details about how to implement custom collators.</p>
<h1><a class="anchor" id="custom_collators_recovery"></a>
Custom Collators and Recovery</h1>
<p>If logging is enabled, WiredTiger will run recovery as required in <a class="el" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed" title="Open a connection to a database. ">wiredtiger_open</a>. Any custom collators in use must be registered before recovery runs. This is described in more detail in <a class="el" href="extensions.html#extensions_recovery">Extensions and recovery</a>.</p>
<h1><a class="anchor" id="custom_collators_indices"></a>
Custom Collators for Indices</h1>
<p>Custom collators can be used with indices, but they must take into account how WiredTiger indices are implemented. The primary key columns are implicitly appended to the logical index key columns in order to create the key that is stored in the index. This is done so that the key stored in the index is unique even when multiple records have the same values for the index key columns.</p>
<p>A collator must give an unambiguous ordering to records in the index, so it must use the primary key columns as well as the index columns when comparing two index records.</p>
<p>What this means in practice is that if the table has <code>key_format=r</code> and the index is on a string column, then the index cursor will have <code>key_format=S</code>, but the actual keys stored in the index will have <code>key_format=Sr</code> (with the primary key appended).</p>
<p>Collators usually call <a class="el" href="group__wt.html#ga1db8298185374dbb61b398a4e9a3d1c8" title="Unpack a structure from a buffer. ">wiredtiger_struct_unpack</a> with the appropriate format to split the index key into fields that are used for the comparison. </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-2016 MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>