Version 2.8.0
Join cursors

Join cursors provide a way to iterate over a subset of a table, where the subset is specified by relationships with reference cursors.

A join cursor is created with WT_SESSION::open_cursor using a "join:table:<name>" URI prefix. Then reference cursors are positioned to keys on indices and joined to the join cursor using WT_SESSION::join calls. The result is a join cursor that can be iterated to satisfy the join equation.

Here is an example using join cursors:

/* Open cursors needed by the join. */
ret = session->open_cursor(session,
"join:table:poptable", NULL, NULL, &join_cursor);
ret = session->open_cursor(session,
"index:poptable:country", NULL, NULL, &cursor);
ret = session->open_cursor(session,
"index:poptable:immutable_year", NULL, NULL, &cursor2);
/* select values WHERE country == "AU" AND year > 1900 */
cursor->set_key(cursor, "AU\0\0\0");
ret = cursor->search(cursor);
ret = session->join(session, join_cursor, cursor,
"compare=eq,count=10");
cursor2->set_key(cursor2, (uint16_t)1900);
ret = cursor2->search(cursor2);
ret = session->join(session, join_cursor, cursor2,
"compare=gt,count=10,strategy=bloom");
/* List the values that are joined */
while ((ret = join_cursor->next(join_cursor)) == 0) {
ret = join_cursor->get_key(join_cursor, &recno);
ret = join_cursor->get_value(join_cursor, &country, &year,
&population);
printf("ID %" PRIu64, recno);
printf(
": country %s, year %" PRIu16 ", population %" PRIu64 "\n",
country, year, population);
}

Joins support various comparison operators: "eq", "gt", "ge", "lt", "le". Ranges with lower and upper bounds can also be specified, by joining two cursors on the same index, for example, one with "compare=ge" and another "compare=lt". In addition to joining indices, the main table can be joined so that a range of primary keys can be specified.

All the joins should be done on the join cursor before WT_CURSOR::next is called. Calling WT_CURSOR::next on a join cursor for the first time populates any bloom filters and performs other initialization. The join cursor's key is the primary key (the key for the main table), and its value is the entire set of values of the main table. A join cursor can be created with a projection by appending "(col1,col2,...)" to the URI if a different set of values is needed.