Next: , Previous: BTree Indexing, Up: User Guide


4.9 Index Cursors

Index cursors are just like BTree cursors except you can get the main BTree value instead of the index value. There are also a parallel set of operations such as cursor-pnext instead of cursor-next which returns exists, key, primary-btree-value and index-value = primary-btree-key.

Operations that have the same behavior, but return primary btree values and keys are:

BTree Cursor Function Index Cursor Function


cursor-first => cursor-pfirst


cursor-last => cursor-plast


cursor-current => cursor-pcurrent


cursor-next => cursor-pnext


cursor-prev => cursor-pprev


cursor-set => cursor-pset


cursor-set-range => cursor-set-prange

The big difference between btree cursors and index cursors is that indices can have duplicate key values. This means we have to choose between incrementing over elements, unique key-values or only within a duplicate segment. There are cursor operations for each:

After incrementing through a set of duplicate items using a xxx-dup function, the last next operation returns nil indicating there are no more duplicates. The consequence of this is that the cursor is now uninitialized (cursor-initialized-p) and needs to be reset by a set or set both call.

See Index Cursor API for further details.