Server cache
Keep values in memory, shared by all sessions and users of the server, in named caches with a lifetime and atomic counters. Nothing is written to disk. Typical uses: keep the result of a costly SQL report or slow web service for a few minutes.
cache setcache setcache addcache addcache getcache getcache entrycache hascache deletecache incrcache incrcache incrcache decrcache decrcache decrcache keyscache keyscache keyscache clearcache clear_allcache global_configcache global_configcache statscache statscache configcache configcache lockcache lockcache unlockcache lock_renewcache lock_info

cache set <cache> <key> <value>


Description

    Store a value with the default lifetime of the cache (default_ttl, 3600 seconds unless cache config changed it). A value already there is replaced. Returns 1

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    value:   The value, a text (a JSON document is a text): 4 MB at most by default (max_value_bytes, counted as 2 bytes per character) - String - required
admin
cache set "doc.reports" "sales:2026-11" "{\"total\": 18250.5}"
mentdb
1

cache set <cache> <key> <value> <ttl_seconds>


Description

    Store a value with its own lifetime. Returns 1

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    value:   The value, a text (a JSON document is a text): 4 MB at most by default (max_value_bytes, counted as 2 bytes per character) - String - required
    ttl_seconds:   The lifetime in seconds, from 0 to 31536000 (one year). 0 means no expiry (the entry still leaves by the LRU rule when the cache is full) - Integer - required
admin
cache set "doc.api" "rates:EUR" "{\"USD\": 1.08}" "300"
mentdb
1
without expiry
admin
cache set "doc.api" "country:FR" "France" "0"
mentdb
1
Used in use cases (1 recipe)

    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache clear  ·  cache delete  ·  cache get  ·  cache has  ·  cache stats

cache add <cache> <key> <value>


Description

    Store a value only if the key is absent, atomically: returns 1 if it was stored, 0 if the key was already there (its value stays, and the entry counts as used). Useful for an idempotency key: the first request wins, the repeated ones are refused. In a cache that evicts, a key can leave under memory pressure and a repeated request then wins again: use a cache with evict false (cache config) for idempotency

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    value:   The value, a text (a JSON document is a text): 4 MB at most by default (max_value_bytes, counted as 2 bytes per character) - String - required
admin
cache add "doc.idem" "order-7781" "taken"; cache add "doc.idem" "order-7781" "taken"
mentdb
0

cache add <cache> <key> <value> <ttl_seconds>


Description

    Store a value only if the key is absent, with its own lifetime. Returns 1 or 0

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    value:   The value, a text (a JSON document is a text): 4 MB at most by default (max_value_bytes, counted as 2 bytes per character) - String - required
    ttl_seconds:   The lifetime in seconds, from 0 to 31536000 (one year). 0 means no expiry (the entry still leaves by the LRU rule when the cache is full) - Integer - required
admin
cache add "doc.idem" "payment-55" "1" "86400"
mentdb
1
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache clear  ·  cache config  ·  cache get  ·  cache incr  ·  cache keys  ·  cache lock  ·  cache lock_info  ·  cache unlock

cache get <cache> <key>


Description

    Read a value. Returns an empty text when the key is absent or expired (use cache entry to tell an empty value from a missing one, or the form with a default)

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache set "doc.get" "k" "hello"; cache get "doc.get" "k"
mentdb
hello
an absent key
admin
cache get "doc.get" "nothing"
mentdb

cache get <cache> <key> <default>


Description

    Read a value, or the default when the key is absent or expired

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    default:   The text returned when the key is absent - String - required
admin
cache get "doc.get" "nothing" "MISSING"
mentdb
MISSING
Used in use cases (2 recipes)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache clear  ·  cache add  ·  cache config  ·  cache delete  ·  cache has  ·  cache incr  ·  cache keys  ·  cache lock

cache entry <cache> <key>


Description

    Read an entry with its state. Returns {found, value, expires_in_ms}: expires_in_ms is null without expiry, value is null when found is false

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache set "doc.entry" "empty" "" "0"; cache entry "doc.entry" "empty"
mentdb
{"found": true, "value": "", "expires_in_ms": null}
an absent key
admin
cache entry "doc.entry" "nothing"
mentdb
{"found": false, "value": null, "expires_in_ms": null}

cache has <cache> <key>


Description

    Returns 1 if the key is there and not expired, else 0. Does not count as a hit or a miss and does not change the LRU order

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache set "doc.has" "k" "1"; cache has "doc.has" "k"
mentdb
1
Used in use cases (1 recipe)

    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache clear  ·  cache delete  ·  cache get  ·  cache set  ·  cache stats

cache delete <cache> <key>


Description

    Remove a key. Returns 1 if it was there, else 0

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache set "doc.del" "customer:12" "x"; cache delete "doc.del" "customer:12"
mentdb
1
Used in use cases (1 recipe)

    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache clear  ·  cache get  ·  cache has  ·  cache set  ·  cache stats

cache incr <cache> <key>


Description

    Add 1 to a counter, atomically, and return the new value. An absent counter starts at 0 with the default lifetime of the cache. The value must be an integer (64 bits); an overflow is an error

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache incr "doc.counters" "views:home"
mentdb
1

cache incr <cache> <key> <by>


Description

    Add an integer (from -10^15 to 10^15) to a counter

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    by:   The integer to add - Integer - required
admin
cache incr "doc.counters" "points" "10"; cache incr "doc.counters" "points" "5"
mentdb
15

cache incr <cache> <key> <by> <ttl_seconds>


Description

    Add to a counter with a lifetime given when the counter is created. Later calls keep the date of expiry: the counter counts in a fixed window

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    by:   The integer to add - Integer - required
    ttl_seconds:   The lifetime in seconds, from 0 to 31536000 (one year). 0 means no expiry (the entry still leaves by the LRU rule when the cache is full) - Integer - required
admin
cache incr "doc.counters" "req:minute" "1" "60"
mentdb
1
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache config  ·  cache get  ·  cache keys  ·  cache lock  ·  cache lock_info  ·  cache unlock

cache decr <cache> <key>


Description

    Subtract 1 from a counter, atomically, and return the new value (it may go below 0)

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
admin
cache set "doc.stock" "tickets" "3" "0"; cache decr "doc.stock" "tickets"
mentdb
2

cache decr <cache> <key> <by>


Description

    Subtract an integer from a counter

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    by:   The integer to subtract - Integer - required
admin
cache set "doc.stock" "seats" "10" "0"; cache decr "doc.stock" "seats" "2"
mentdb
8

cache decr <cache> <key> <by> <ttl_seconds>


Description

    Subtract from a counter with a lifetime given when the counter is created

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    key:   The key: 1 to 1024 characters - String - required
    by:   The integer to subtract - Integer - required
    ttl_seconds:   The lifetime in seconds, from 0 to 31536000 (one year). 0 means no expiry (the entry still leaves by the LRU rule when the cache is full) - Integer - required
admin
cache decr "doc.stock" "quota:user7" "1" "3600"
mentdb
-1

cache keys <cache>


Description

    The keys of a cache that are not expired, sorted, 1000 at most. Returns a JSON array. The keys are copied, then matched outside the lock of the cache, so a long call never blocks the other sessions

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
admin
cache set "doc.keys" "user:1" "a"; cache set "doc.keys" "user:2" "b"; cache set "doc.keys" "order:9" "c"; cache keys "doc.keys"
mentdb
["order:9", "user:1", "user:2"]

cache keys <cache> <pattern>


Description

    The keys that match a pattern: * is any text, ? is one character, every other character is itself. The work is bounded (key length times pattern length per key, 50 million steps per call): beyond, the call fails and asks for a simpler pattern

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    pattern:   The pattern, ex: user:* - String - required
admin
cache set "doc.keys2" "user:1" "a"; cache set "doc.keys2" "order:9" "c"; cache keys "doc.keys2" "user:*"
mentdb
["user:1"]

cache keys <cache> <pattern> <limit>


Description

    The keys that match a pattern, at most limit (from 1 to 100000) after sorting

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    pattern:   The pattern - String - required
    limit:   The maximum number of keys - Integer - required
admin
cache set "doc.keys3" "user:1" "a"; cache set "doc.keys3" "user:2" "b"; cache keys "doc.keys3" "*" "1"
mentdb
["user:1"]
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache config  ·  cache get  ·  cache incr  ·  cache lock  ·  cache lock_info  ·  cache unlock

cache clear <cache>


Description

    Remove all the entries of a cache. Returns the number removed. A cache without cache config disappears with its statistics; a configured one keeps its settings and statistics

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
admin
cache set "doc.clear" "a" "1"; cache set "doc.clear" "b" "2"; cache clear "doc.clear"
mentdb
2
Used in use cases (2 recipes)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache get  ·  cache add  ·  cache config  ·  cache delete  ·  cache has  ·  cache incr  ·  cache keys  ·  cache lock

cache clear_all


Description

    Remove all the caches of the server, their settings and the statistics. Needs the group sys. Returns the number of entries removed

admin
cache clear_all
mentdb
21

cache global_config <json_params>


Description

    Change the limits of all the caches together, until the next restart (put the call in a startup script to keep it). Needs the group sys. Parameters: max_bytes (from 1 MB to half of the Java maximum memory) or max_memory_percent (0.1 to 50, of the Java maximum memory; 5 by default), max_caches (1 to 10000; 256 by default). A smaller limit removes the least recently used entries at once. A change that leaves less than twice the bytes reserved by the caches with evict false is refused. Returns {max_bytes, max_memory_percent, max_caches, bytes, entries, caches, reserved_bytes}

Parameters

    json_params:   The parameters - String - required
admin
cache global_config "{\"max_bytes\": 134217728}"
mentdb
{"max_bytes": 134217728, "max_memory_percent": null, "max_caches": 256, "bytes": 0, "entries": 0, "caches": 0, "reserved_bytes": 0}

cache global_config


Description

    The global limits and the current use. Any session can read them

admin
cache global_config
mentdb
{"max_bytes": 134217728, "max_memory_percent": null, "max_caches": 256, "bytes": 0, "entries": 0, "caches": 0, "reserved_bytes": 0}

cache stats <cache>


Description

    The statistics of a cache: {cache, exists, entries, bytes, hits, misses, hit_ratio, sets, deletes, evictions, expirations}. A read that finds nothing (cache get, cache entry) counts as a miss, also on a cache that does not exist yet: the cache is then created empty, to keep its statistics. Such an empty cache without settings gives its place when the limit of max_caches is reached; cache has never counts

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
admin
cache set "doc.stats" "a" "1"; cache get "doc.stats" "a"; cache get "doc.stats" "b"; cache stats "doc.stats"
mentdb
{"cache": "doc.stats", "exists": true, "entries": 1, "bytes": 116, "hits": 1, "misses": 1, "hit_ratio": 0.5, "sets": 1, "deletes": 0, "evictions": 0, "expirations": 0}
the first read of a new cache is a miss
admin
cache get "doc.stats.new" "a" ""; cache stats "doc.stats.new"
mentdb
{"cache": "doc.stats.new", "exists": true, "entries": 0, "bytes": 0, "hits": 0, "misses": 1, "hit_ratio": 0, "sets": 0, "deletes": 0, "evictions": 0, "expirations": 0}

cache stats


Description

    The statistics of the whole server: {caches, entries, bytes, max_bytes, hits, misses, hit_ratio, sets, evictions, expirations, names}

admin
cache stats
mentdb
{"caches": 2, "entries": 1, "bytes": 116, "max_bytes": 134217728, "hits": 1, "misses": 2, "hit_ratio": 0.3333, "sets": 1, "evictions": 0, "expirations": 0, "names": ["doc.stats", "doc.stats.new"]}
Used in use cases (1 recipe)

    Web & API developer › Compute a costly report once and serve it from the server cache to every caller of an API
Often used with

    cache clear  ·  cache delete  ·  cache get  ·  cache has  ·  cache set

cache config <cache>


Description

    The settings of a cache: {cache, max_entries, max_bytes, default_ttl, max_value_bytes}. max_bytes is the one in force (never more than the global one). An unknown cache gives the default settings and is not created

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
admin
cache config "doc.unknown"
mentdb
{"cache": "doc.unknown", "max_entries": 100000, "max_bytes": 134217728, "default_ttl": 3600, "max_value_bytes": 4194304, "evict": true}

cache config <cache> <json_params>


Description

    Change the settings of a cache (it is created if needed): max_entries (1 to 10000000; 100000 by default), max_bytes (from 1024; the global max_bytes by default), default_ttl (0 to 31536000 seconds; 3600 by default; 0 = no expiry), max_value_bytes (16 to 67108864; 4194304 by default), evict (true by default; false: no LRU eviction, a write over the limits is an error, and max_bytes is required and reserved, see the top of the page). A smaller limit removes the least recently used entries at once. Returns the settings

Parameters

    cache:   The name of the cache: 1 to 64 characters among A-Z a-z 0-9 _ . : -. A cache is created by its first write - String - required
    json_params:   The parameters - String - required
admin
cache config "doc.small" "{\"max_entries\": 2, \"default_ttl\": 600}"; cache set "doc.small" "a" "1"; cache set "doc.small" "b" "2"; cache get "doc.small" "a"; cache set "doc.small" "c" "3"; cache keys "doc.small"
mentdb
["a", "c"]
the settings
admin
cache config "doc.small2" "{\"max_bytes\": 1048576, \"max_value_bytes\": 65536}"
mentdb
{"cache": "doc.small2", "max_entries": 100000, "max_bytes": 1048576, "default_ttl": 3600, "max_value_bytes": 65536, "evict": true}
idempotency keys that are never evicted: the repeated request is refused
admin
cache config "doc.idem2" "{\"evict\": false, \"max_bytes\": 65536}"; cache add "doc.idem2" "op-1" "1" "86400"; cache add "doc.idem2" "op-1" "1" "86400"
mentdb
0
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache get  ·  cache incr  ·  cache keys  ·  cache lock  ·  cache lock_info  ·  cache unlock

cache lock <name> <ttl_seconds>


Description

    Take a named lock without waiting. Returns a token (32 hexadecimal characters) to give to cache unlock, or an empty text if the lock is held by someone else. The lock is not reentrant: the same session gets an empty text too. It ends with cache unlock, at the end of the lease, or when the session that took it is closed (see the top of the page: a web call keeps it until its HTTP session ends)

Parameters

    name:   The name of the lock: 1 to 256 characters - String - required
    ttl_seconds:   The lease in seconds, from 1 to 86400: the lock is released at the end of it, even if the holder is still running - Integer - required
admin
cache lock "doc.job.nightly" "600"
mentdb
539b7da0a9c7669e22963a50bcc8f55e

cache lock <name> <ttl_seconds> <json_params>


Description

    Take a named lock, waiting for it at most wait_ms (from 0 to 60000 milliseconds; 0 by default). Returns the token, or an empty text at the end of the wait

Parameters

    name:   The name of the lock: 1 to 256 characters - String - required
    ttl_seconds:   The lease in seconds, from 1 to 86400: the lock is released at the end of it, even if the holder is still running - Integer - required
    json_params:   The parameters - String - required
admin
cache lock "doc.job.export" "60" "{\"wait_ms\": 100}"; cache lock_info "doc.job.export"
mentdb
{"name": "doc.job.export", "locked": true, "expires_in_ms": 60000, "user": ""}
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache config  ·  cache get  ·  cache incr  ·  cache keys  ·  cache lock_info  ·  cache unlock

cache unlock <name> <token>


Description

    Release a lock with its token. Returns 1, or 0 if the token is not the one of the current holder (the lease may be over and another session may hold the lock)

Parameters

    name:   The name of the lock: 1 to 256 characters - String - required
    token:   The token returned by cache lock - String - required
admin
cache unlock "doc.job.nightly" "0123456789abcdef0123456789abcdef"
mentdb
0
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache config  ·  cache get  ·  cache incr  ·  cache keys  ·  cache lock  ·  cache lock_info

cache lock_renew <name> <token> <ttl_seconds>


Description

    Give a new lease to a lock you hold, for a long job. Returns 1, or 0 if the token is not the one of the current holder

Parameters

    name:   The name of the lock: 1 to 256 characters - String - required
    token:   The token returned by cache lock - String - required
    ttl_seconds:   The lease in seconds, from 1 to 86400: the lock is released at the end of it, even if the holder is still running - Integer - required
admin
cache lock_renew "doc.job.nightly" "0123456789abcdef0123456789abcdef" "600"
mentdb
0

cache lock_info <name>


Description

    The state of a lock: {name, locked, expires_in_ms, user}. The token is never shown

Parameters

    name:   The name of the lock: 1 to 256 characters - String - required
admin
cache lock_info "doc.job.free"
mentdb
{"name": "doc.job.free", "locked": false, "expires_in_ms": null, "user": null}
Used in use cases (1 recipe)

    Integrator & ETL developer › Run an import job once at a time and process each message only once
Often used with

    cache add  ·  cache clear  ·  cache config  ·  cache get  ·  cache incr  ·  cache keys  ·  cache lock  ·  cache unlock