Difference between revisions of "Store Module"
m (Text replacement - "db:pre(" to "db:get(") |
|||
Line 16: | Line 16: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:get|$key as xs:string|item()*}}<br/ > | |{{Func|store:get|$key as xs:string|item()*}}<br/ > | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Retrieves an entry from the store with the given {{Code|$key}}. If the addressed entry does not exist, an empty sequence is returned. | |Retrieves an entry from the store with the given {{Code|$key}}. If the addressed entry does not exist, an empty sequence is returned. | ||
Line 27: | Line 27: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:put|$key as xs:string, $value as item()*|empty-sequence()}}<br/ > | |{{Func|store:put|$key as xs:string, $value as item()*|empty-sequence()}}<br/ > | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Stores an entry with the given {{Code|$key}} and {{Code|$value}} in the store: | |Stores an entry with the given {{Code|$key}} and {{Code|$value}} in the store: | ||
Line 41: | Line 41: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:get-or-put|$key as xs:string, $put as function() as item()*|item()*}}<br/ > | |{{Func|store:get-or-put|$key as xs:string, $put as function() as item()*|item()*}}<br/ > | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Retrieves an entry from the store with the given {{Code|$key}}. The {{Code|$put}} function will only be invoked if the entry does not exist, and its result will be stored and returned instead. | |Retrieves an entry from the store with the given {{Code|$key}}. The {{Code|$put}} function will only be invoked if the entry does not exist, and its result will be stored and returned instead. | ||
Line 52: | Line 52: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:remove|$key as xs:string|empty-sequence()}}<br/ > | |{{Func|store:remove|$key as xs:string|empty-sequence()}}<br/ > | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Removes an entry with the given {{Code|$key}} from the store. No error will be raised if an addressed entry does not exist. | |Removes an entry with the given {{Code|$key}} from the store. No error will be raised if an addressed entry does not exist. | ||
Line 63: | Line 63: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:keys||xs:string*}} | |{{Func|store:keys||xs:string*}} | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Lists the names of all keys. | |Lists the names of all keys. | ||
Line 74: | Line 74: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:clear||empty-sequence()}}<br/ > | |{{Func|store:clear||empty-sequence()}}<br/ > | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Resets the store by removing all its entries. | |Resets the store by removing all its entries. | ||
Line 87: | Line 87: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:read||empty-sequence()}}<br/ >{{Func|store:read|$name as xs:string|empty-sequence()}} | |{{Func|store:read||empty-sequence()}}<br/ >{{Func|store:read|$name as xs:string|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Retrieves the standard store from disk, or a custom store if a {{Code|$name}} is supplied. | |Retrieves the standard store from disk, or a custom store if a {{Code|$name}} is supplied. | ||
− | |- | + | |- valign="top" |
|'''Errors''' | |'''Errors''' | ||
|{{Error|io|#Errors}} The store could not be read.<br/>{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A store with the specified name does not exist. | |{{Error|io|#Errors}} The store could not be read.<br/>{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A store with the specified name does not exist. | ||
Line 101: | Line 101: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:write||empty-sequence()}}<br/ >{{Func|store:write|$name as xs:string|empty-sequence()}} | |{{Func|store:write||empty-sequence()}}<br/ >{{Func|store:write|$name as xs:string|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Writes the standard store to disk, or to a custom store file if a {{Code|$name}} is supplied. If the standard store is empty, the store file will be deleted. | |Writes the standard store to disk, or to a custom store file if a {{Code|$name}} is supplied. If the standard store is empty, the store file will be deleted. | ||
− | |- | + | |- valign="top" |
|'''Errors''' | |'''Errors''' | ||
|{{Error|io|#Errors}} The store could not be written.<br/>{{Error|name|#Errors}} The specified name is invalid. | |{{Error|io|#Errors}} The store could not be written.<br/>{{Error|name|#Errors}} The specified name is invalid. | ||
Line 115: | Line 115: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:list||xs:string*}} | |{{Func|store:list||xs:string*}} | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Lists the names of all custom stores. | |Lists the names of all custom stores. | ||
Line 126: | Line 126: | ||
{| width='100%' | {| width='100%' | ||
− | |- | + | |- valign="top" |
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
|{{Func|store:delete|$name as xs:string|empty-sequence()}} | |{{Func|store:delete|$name as xs:string|empty-sequence()}} | ||
− | |- | + | |- valign="top" |
|'''Summary''' | |'''Summary''' | ||
|Deletes a custom store from disk. | |Deletes a custom store from disk. | ||
− | |- | + | |- valign="top" |
|'''Errors''' | |'''Errors''' | ||
|{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A store with the specified name does not exist. | |{{Error|name|#Errors}} The specified name is invalid.<br/>{{Error|not-found|#Errors}} A store with the specified name does not exist. | ||
Line 186: | Line 186: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|io}} | |{{Code|io}} | ||
| The store could not be read or written. | | The store could not be read or written. | ||
− | |- | + | |- valign="top" |
|{{Code|name}} | |{{Code|name}} | ||
| The specified name is invalid. | | The specified name is invalid. | ||
− | |- | + | |- valign="top" |
|{{Code|not-found}} | |{{Code|not-found}} | ||
| A store with the specified name does not exist. | | A store with the specified name does not exist. |
Revision as of 14:19, 20 July 2022
This XQuery 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, 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 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 store have changed.
Contents
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
Signatures | store:get($key as xs:string) as item()* |
Summary | Retrieves an entry from the store with the given $key . If the addressed entry does not exist, an empty sequence is returned.
|
store:put
Signatures | store:put($key as xs:string, $value as item()*) as empty-sequence() |
Summary | Stores an entry with the given $key and $value in the store:
|
store:get-or-put
Signatures | store:get-or-put($key as xs:string, $put as function() as item()*) as item()* |
Summary | Retrieves 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
Signatures | store:remove($key as xs:string) as empty-sequence() |
Summary | Removes an entry with the given $key from the store. No error will be raised if an addressed entry does not exist.
|
store:keys
Signatures | store:keys() as xs:string*
|
Summary | Lists the names of all keys. |
store:clear
Signatures | store:clear() as empty-sequence() |
Summary | Resets the store by removing all its entries. |
Store Operations
store:read
Signatures | store:read() as empty-sequence() store:read($name as xs:string) as empty-sequence()
|
Summary | Retrieves the standard store from disk, or a custom store if a $name is supplied.
|
Errors | io : The store could not be read.name : The specified name is invalid.not-found : A store with the specified name does not exist.
|
store:write
Signatures | store:write() as empty-sequence() store:write($name as xs:string) as empty-sequence()
|
Summary | Writes 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 | io : The store could not be written.name : The specified name is invalid.
|
store:list
Signatures | store:list() as xs:string*
|
Summary | Lists the names of all custom stores. |
store:delete
Signatures | store:delete($name as xs:string) as empty-sequence()
|
Summary | Deletes a custom store from disk. |
Errors | name : The specified name is invalid.not-found : A store 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 :) store:put('version', 1), (: retrieve existing or new value, store an element :) let $license := store:get-or-put('license', function() { 'free' }) return store:put('info', <info>{ $license = 'free' ?? 'Free' !! 'Professional' } License</info>), (: store a map :) store:put('data', map { 'year': 2022 }), (: serialize configuration to disk :) store:write() </syntaxhighlight>
The configuration can be requested by further operations, e.g. a client request:
<syntaxhighlight lang="xquery"> store:get('version') </syntaxhighlight>
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:
<syntaxhighlight lang="xquery"> 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) </syntaxhighlight>
A subsequent query can be used to access its contents:
<syntaxhighlight lang="xquery"> store:get('religions')?Buddhism </syntaxhighlight>
Note that the store will eventually be written to disk unless it is invalidated before closing the GUI.
Errors
Code | Description |
---|---|
io
|
The store could not be read or written. |
name
|
The specified name is invalid. |
not-found
|
A store with the specified name does not exist. |
Changelog
The module was introduced with Version 10.