Store Module

From BaseX Documentation
Revision as of 15:16, 6 May 2022 by CG (talk | contribs)
Jump to navigation Jump to search

This XQuery Module provides functions to organize values in a main-memory key value store.

Caching is advisable if data (a system configuration, maps serving as indexes) needs to be repeatedly accessed. The cache is persistent: Contents will be written to disk at shutdown time, and the serialized cache will be retrieved from disk as soon as the cache is used for the first time. The cache will be stored in a binary cache.basex file in the database directory.

In addition, custom caches can be read and written. Custom cache files use the filename pattern cache-NAME.basex. The implicit write of the standard cache at shutdown time will be disabled if a custom cache is used.

Functions of this module are non-deterministic 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 cache have changed.

Conventions

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

Cache Entries

cache:get

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

cache:put

Signatures cache:put($key as xs:string, $value as item()*) as empty-sequence()
Summary Stores an entry with the given $key and $value in the cache:
  • 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.

cache:get-or-put

Signatures cache:get-or-put($key as xs:string, $put as function() as item()*) as item()*
Summary Retrieves an entry from the cache 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.

cache:remove

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

cache:keys

Signatures cache:keys() as xs:string*
Summary Lists the names of all keys.

cache:clear

Signatures cache:clear() as empty-sequence()
Summary Resets the cache by removing all its entries.

Cache Operations

cache:read

Signatures cache:read() as empty-sequence()
cache:read($name as xs:string) as empty-sequence()
Summary Retrieves the standard cache from disk, or a custom cache if a $name is supplied.
Errors io: The cache could not be read.
name: The specified name is invalid.
not-found: A cache with the specified name does not exist.

cache:write

Signatures cache:write() as empty-sequence()
cache:write($name as xs:string) as empty-sequence()
Summary Writes the standard cache to disk, or to a custom cache file if a $name is supplied. If the standard cache is empty, the cache file will be deleted.
Errors io: The cache could not be written.
name: The specified name is invalid.

cache:list

Signatures cache:list() as xs:string*
Summary Lists the names of all custom caches.

cache:delete

Signatures cache:delete($name as xs:string) as empty-sequence()
Summary Deletes a custom cache from disk.
Errors name: The specified name is invalid.
not-found: A cache with the specified name does not exist.

Examples

Use Case 1: Create/update a system configuration in a running BaseX server instance:

<syntaxhighlight lang="xquery"> (: store an integer :) cache:put('version', 1), (: retrieve existing or new value, store an element :) let $license := cache:get-or-put('license', function() { 'free' }) return cache:put('info', <info>{ $license = 'free' ?? 'Free' !! 'Professional' } License</info>), (: store a map :) cache:put('data', map { 'year': 2022 }), (: serialize configuration to disk :) cache:write() </syntaxhighlight>

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

<syntaxhighlight lang="xquery"> cache:get('version') </syntaxhighlight>

The cache will still be available if BaseX is restarted until it is cleared.

Use Case 2: Create index for fast lookup operations in the GUI:

<syntaxhighlight lang="xquery"> let $map := map:merge(

 for $country in db:open('factbook')//country
 for $religion in $country//religions
 group by $religion
 return map:entry($religion, data($country/@name))

) return cache:put('religions', $map) </syntaxhighlight>

A subsequent query can be used to access its contents:

<syntaxhighlight lang="xquery"> cache:get('religions')?Buddhism </syntaxhighlight>

Note that the cache will eventually be written to disk unless it is invalidated before closing the GUI.

Errors

Code Description
io The cache could not be read or written.
name The specified name is invalid.
not-found A cache with the specified name does not exist.

Changelog

The module was introduced with Version 10.