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, and if a value depends on entries that were read before, use store:update to turn the reads and writes into a single atomic operation.

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()*

store:put

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

store:get-or-put

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

store:remove

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

store:update

Added: New function.

store:update(
  $update  as fn(map(xs:string, item()*)) as map(xs:string, item()*),
  $name    as xs:string?  := ''
) as xs:boolean

store:update(fn { map:put(., 'hits', (?hits otherwise 0) + 1) })

store:update(fn($entries) {
  let $now := current-dateTime()
  return map:filter($entries, fn($key, $value) { $value?expires > $now })
}, 'sessions')

store:keys

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

Organize Stores

store:list

store:list() as xs:string*

store:read

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

store:write

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

store:delete

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

store:close

Added: New function.

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

store:clear

store:clear() as empty-sequence()

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 will still be available if BaseX is restarted 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 invalidated before closing the GUI.

A check that is followed by a write is only reliable if no other request can interfere in between. store:update evaluates both steps in a single atomic operation. As the returned map is left unchanged if a conflicting lock is found, the result of the function indicates whether the lock was granted:

let $granted := store:update(fn($locks) {
  if (map:keys($locks)[starts-with($path, .)]) {
    $locks
  } else {
    map:put($locks, $path, $owner)
  }
}, 'locks')
return if ($granted) { 'locked ' || $path } else { 'denied' }

Errors

Changelog

• Added: store:update, 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.