Store Module
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.
Contents
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:
|
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.