Main Page » XQuery » Functions » Store Functions

Store Functions

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

The store is useful if data (a system configuration, maps serving as indexes) needs to be repeatedly accessed. The 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 store will be stored in a binary store.basex file in the database directory.

In addition, custom stores can be read and written. Custom stores have filenames with the pattern store-NAME.basex. The implicit write of the standard store at shutdown time will be disabled if a custom store is used.

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.

Conventions

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

Key-value operations

store:get

Signature
store:get(
  $key  as xs:string
) as item()*
SummaryRetrieves an entry from the store with the given $key. If the addressed entry does not exist, an empty sequence is returned.

store:put

Signature
store:put(
  $key    as xs:string,
  $value  as item()*
) as empty-sequence()
SummaryStores an entry with the given $key and $value in the store:
  • If the value is an empty sequence, the entry is removed.
  • If a value refers to an opened database or is a lazy item, its contents are materialized in main memory.
  • Values with function items are rejected.

store:get-or-put

Signature
store:get-or-put(
  $key  as xs:string,
  $put  as fn(*)
) as item()*
SummaryRetrieves an entry from the store with the given $key. The $put function will only be invoked if the entry does not exist, and its result will be stored and returned instead.

store:remove

Signature
store:remove(
  $key  as xs:string
) as empty-sequence()
SummaryRemoves an entry with the given $key from the store. No error will be raised if an addressed entry does not exist.

store:keys

Signature
store:keys() as xs:string*
SummaryLists the names of all keys.

store:clear

Signature
store:clear() as empty-sequence()
SummaryResets the store by removing all its entries.

Store Operations

store:read

Signature
store:read(
  $name  as xs:string?  := ()
) as empty-sequence()
SummaryRetrieves the standard store from disk, or a custom store if a $name is supplied.
Errors
ioThe store could not be read or written.
nameThe specified name is invalid.
not-foundA store with the specified name does not exist.

store:write

Signature
store:write(
  $name  as xs:string?  := ()
) as empty-sequence()
SummaryWrites the standard store to disk, or to a custom store file if a $name is supplied. If the standard store is empty, the store file will be deleted.
Errors
ioThe store could not be read or written.
nameThe specified name is invalid.

store:list

Signature
store:list() as xs:string*
SummaryLists the names of all custom stores.

store:delete

Signature
store:delete(
  $name  as xs:string
) as empty-sequence()
SummaryDeletes a custom store from disk.
Errors
nameThe specified name is invalid.
not-foundA store with the specified name does not exist.

Examples

Use Case 1: Create/update a system configuration in a running BaseX server instance
(: 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.

Use Case 2: Create index for fast lookup operations in the GUI
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.

Errors

CodeDescription
ioThe store could not be read or written.
nameThe specified name is invalid.
not-foundA store with the specified name does not exist.

Changelog

Version 11
  • Added: New WRITESTORE option.
  • Updated: Values are compactified before being stored.
Version 10
  • Added: New module added.

⚡Generated with XQuery