Next: , Previous: Persistent Set API, Up: User API Reference


5.5 BTrees

Persistent collections inherit from Class elephant:persistent-collection and consist of the Class elephant:btree, Class elephant:indexed-btree and Class elephant:btree-index classes. The following operations are defined on most of these classes. More information can be found in Persistent BTrees and BTree Indexing.

— Function: elephant:make-btree

Constructs a new BTree instance for use by the user. Each backend returns its own internal type as appropriate and ensures that the btree is associated with the store-controller that created it.

— Generic Function: elephant:get-value key bt

Get a value from a Btree.

Values are written to a btree using the setf method on get-value.

— Generic Function: elephant:remove-kv key bt

Remove a key / value pair from a BTree.

— Method: elephant:remove-kv key (bt btree-index)

Remove a key / value from the primary by a secondary lookup, updating all other secondary indices.

— Generic Function: elephant:existsp key bt

Test existence of a key / value pair in a BTree

— Generic Function: elephant:drop-btree bt

Delete all key-value pairs from the btree and render it an invalid object in the data store

— Generic Function: elephant:map-btree fn btree &rest args &key start end value from-end collect value &allow-other-keys

Map btree maps over a btree from the value start to the value of end. If values are not provided, then it maps over all values. BTrees do not have duplicates, but map-btree can also be used with indices in the case where you don't want access to the primary key so we require a value argument as well for mapping duplicate value sets. The collect keyword will accumulate the results from each call of fn in a fresh list and return that list in the same order the calls were made (first to last).

These functions are only defined on indexed btrees.

— Function: elephant:make-indexed-btree

Constructs a new indexed BTree instance for use by the user. Each backend returns its own internal type as appropriate and ensures that the btree is associated with the store-controller that created it.

— Generic Function: elephant:add-index bt &key index-name key-form populate

Add a secondary index. The indices are stored in an eq hash-table, so the index-name should be a symbol. key-form should be a symbol naming a function, a function call form eg '(create-index 3) or a lambda expression -- actual functions aren't supported. Lambda expresssions are converted to functions through compile and function call forms are transformed applying the first element of the list to the rest of the list. The function should take 3 arguments: the secondary db, primary key and value, and return two values: a boolean indicating whether to index this key / value, and the secondary key if so. If populate = t it will fill in secondary keys for existing primary entries (may be expensive!)

— Generic Function: elephant:get-index bt index-name

Get a named index.

— Generic Function: elephant:get-primary-key key bt

Get the primary key from a secondary key.

— Generic Function: elephant:remove-index bt index-name

Remove a named index.

This function is only valid for indexes.

— Generic Function: elephant:map-index fn index &rest args &key start end value from-end collect value &allow-other-keys

Map-index is like map-btree but for secondary indices, it takes a function of three arguments: key, value and primary key. As with map-btree the keyword arguments start and end determine the starting element and ending element, inclusive. Also, start = nil implies the first element, end = nil implies the last element in the index. If you want to traverse only a set of identical key values, for example all nil values, then use the value keyword which will override any values of start and end. The collect keyword will accumulate the results from each call of fn in a fresh list and return that list in the same order the calls were made (first to last)