Store Functions

Updated: All opened stores are now kept in main memory. As a result, a newly opened store will not overwrite the default store anymore. The functions have been enriched with a parameter to supply the name of a store.

This module provides functions to organize values in a persistent main-memory key-value store.

Stores are useful if data (a system configuration, maps serving as indexes) needs to be repeatedly accessed. A store is persistent: Contents will be written to disk at shutdown time (unless WRITESTORE is disabled), and the serialized store will be retrieved from disk as soon as the store is used for the first time. The default store will be stored in a binary store.basex file in the database directory.

In addition, custom stores can be read and written, and can be addressed via an additional $name parameter. Custom stores have filenames with the pattern store-NAME.basex.

The Cache provides similar functionality, but its entries have a limited lifetime and are transient, i.e., will never be persisted.

Functions of this module are nondeterministic and side-effecting: Updates will immediately be visible, and a repeated call of the same function may yield different results if the contents of the store have changed.

Single operations are atomic, but a sequence of them is not. If a store is accessed by several clients at the same time, a value that depends on entries that were read before may be based on outdated data.

Conventions

All functions and errors are in the http://basex.org/modules/store namespace, to which the store prefix is statically bound.

Key-value Operations

store:get

store:get(  $key   as xs:string,  $name  as xs:string?  := '') as item()*create

store:put

store:put(  $key    as xs:string,  $value  as item()*,  $name   as xs:string?  := '') as empty-sequence()create

store:get-or-put

store:get-or-put(  $key   as xs:string,  $put   as fn() as item()*,  $name  as xs:string?  := '') as item()*create

store:remove

store:remove(  $key   as xs:string,  $name  as xs:string?  := '') as empty-sequence()create

store:keys

store:keys(  $name  as xs:string?  := '') as xs:string*create

Organize Stores

store:list

store:list() as xs:string*create

store:info

Added: New function.

store:info(  $name  as xs:string?  := '') as map(*)create

store:info('sessions')?entries

store:read

store:read(  $name  as xs:string?  := '') as empty-sequence()create

store:write

store:write(  $name  as xs:string?  := '') as empty-sequence()create

store:delete

store:delete(  $name  as xs:string?  := '') as empty-sequence()create

store:close

Added: New function.

store:close(  $name  as xs:string?  := '') as empty-sequence()create

store:clear

store:clear() as empty-sequence()create

Examples

(: store an integer :)
store:put('version', 1),
(: retrieve existing or new value, store an element :)
let $license := store:get-or-put('license', fn() { 'free' })
let $type := if ($license = 'free') then 'Free' else 'Professional' 
return store:put('info', <info>{ $type } License</info>),
(: store a map :)
store:put('data', { 'year': 2022 }),
(: serialize configuration to disk :)
store:write()

The configuration can be requested by further operations, e.g. a client request:

store:get('version')

The store remains available across restarts of BaseX until it is cleared.

let $map := map:merge(
  for $country in db:get('factbook')//country
  for $religion in $country//religions
  group by $religion
  return map:entry($religion, data($country/@name))
)
return store:put('religions', $map)

A subsequent query can be used to access its contents:

store:get('religions')?Buddhism

Note that the store will eventually be written to disk unless it is deleted or cleared before closing the GUI.

Errors

Changelog

• Added: store:info, store:close
• Updated: All opened stores are now kept in main memory.

• Added: New WRITESTORE option.
• Updated: Values are compactified before being stored.

• Added: New module added.