1<!--$Id: dup.so,v 10.28 2003/10/18 19:15:54 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Duplicate data items</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 14<td align=right><a href="/am_conf/byteorder.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am_conf/malloc.html"><img src="/images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Duplicate data items</b></p> 17<p>The Btree and Hash access methods support the creation of multiple data 18items for a single key item. By default, multiple data items are not 19permitted, and each database store operation will overwrite any previous 20data item for that key. To configure Berkeley DB for duplicate data items, 21call the <a href="/api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="/api_c/db_set_flags.html#DB_DUP">DB_DUP</a> flag. Only one 22copy of the key will be stored for each set of duplicate data items. 23If the Btree access method comparison routine returns that two keys 24compare equally, it is undefined which of the two keys will be stored 25and returned from future database operations.</p> 26<p>By default, Berkeley DB stores duplicates in the order in which they were added, 27that is, each new duplicate data item will be stored after any already 28existing data items. This default behavior can be overridden by using 29the <a href="/api_c/dbc_put.html">DBcursor->put</a> method and one of the <a href="/api_c/dbc_put.html#DB_AFTER">DB_AFTER</a>, <a href="/api_c/dbc_put.html#DB_BEFORE">DB_BEFORE</a> 30<a href="/api_c/dbc_put.html#DB_KEYFIRST">DB_KEYFIRST</a> or <a href="/api_c/dbc_put.html#DB_KEYLAST">DB_KEYLAST</a> flags. Alternatively, Berkeley DB 31may be configured to sort duplicate data items.</p> 32<p>When stepping through the database sequentially, duplicate data items will 33be returned individually, as a key/data pair, where the key item only 34changes after the last duplicate data item has been returned. For this 35reason, duplicate data items cannot be accessed using the 36<a href="/api_c/db_get.html">DB->get</a> method, as it always returns the first of the duplicate data 37items. Duplicate data items should be retrieved using a Berkeley DB cursor 38interface such as the <a href="/api_c/dbc_get.html">DBcursor->get</a> method.</p> 39<p>There is a flag that permits applications to request the following data 40item only if it <b>is</b> a duplicate data item of the current entry, 41see <a href="/api_c/dbc_get.html#DB_NEXT_DUP">DB_NEXT_DUP</a> for more information. There is a flag that 42permits applications to request the following data item only if it 43<b>is not</b> a duplicate data item of the current entry, see 44<a href="/api_c/dbc_get.html#DB_NEXT_NODUP">DB_NEXT_NODUP</a> and <a href="/api_c/dbc_get.html#DB_PREV_NODUP">DB_PREV_NODUP</a> for more information.</p> 45<p>It is also possible to maintain duplicate records in sorted order. Sorting 46duplicates will significantly increase performance when searching them 47and performing equality joins, common operations when using secondary 48indices. To configure Berkeley DB to sort duplicate data items, the application 49must call the <a href="/api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="/api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag (in 50addition to the <a href="/api_c/db_set_flags.html#DB_DUP">DB_DUP</a> flag). In addition, a custom comparison 51function may be specified using the <a href="/api_c/db_set_dup_compare.html">DB->set_dup_compare</a> method. If the 52<a href="/api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag is given, but no comparison routine is specified, 53then Berkeley DB defaults to the same lexicographical sorting used for Btree 54keys, with shorter items collating before longer items.</p> 55<p>If the duplicate data items are unsorted, applications may store identical 56duplicate data items, or, for those that just like the way it sounds, 57<i>duplicate duplicates</i>.</p> 58<p><b>In this release it is an error to attempt to store identical 59duplicate data items when duplicates are being stored in a sorted order.</b> 60This restriction is expected to be lifted in a future release. There 61is a flag that permits applications to disallow storing duplicate data 62items when the database has been configured for sorted duplicates, see 63<a href="/api_c/db_put.html#DB_NODUPDATA">DB_NODUPDATA</a> for more information. Applications not wanting to 64permit duplicate duplicates in databases configured for sorted 65duplicates should begin using the <a href="/api_c/db_put.html#DB_NODUPDATA">DB_NODUPDATA</a> flag immediately.</p> 66<p>For further information on how searching and insertion behaves in the 67presence of duplicates (sorted or not), see the <a href="/api_c/db_get.html">DB->get</a>, 68<a href="/api_c/db_put.html">DB->put</a>, <a href="/api_c/dbc_get.html">DBcursor->get</a> and <a href="/api_c/dbc_put.html">DBcursor->put</a> documentation.</p> 69<table width="100%"><tr><td><br></td><td align=right><a href="/am_conf/byteorder.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/am_conf/malloc.html"><img src="/images/next.gif" alt="Next"></a> 70</td></tr></table> 71<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 72</body> 73</html> 74