Extension API

The 486-entry canonical catalog is not the entire ffkv command registry. This page covers the additional callable APIs implemented by the native queues, storage administration, filter/sketch and JSON handlers. These commands use the same RESP connection and native CLI; no Redis module installation is required for the built-in datatypes.

Canonical command explorer · CLI and binary input · Compatibility boundaries

All syntax below is checked against current source registrations. Arguments are byte strings unless a numeric/keyword form is specified. The common 8 MiB/1,024-argument ingress and origin-specific reply budgets still apply. Normal documentation generation never runs a server, native binary or network request.

Native leased jobs

FQ.* owns a separate ffkv-queue key datatype, not a Redis list. Delivery is at least once: make external side effects idempotent. Higher priority wins; ties use enqueue order. CLAIM is nonblocking. Queue TTL/DEL removes the queue and its policy. Empty queues retain policy and counters until deletion/expiry. Reading missing-queue policy does not create a key.

Limits and caveats: Default visibility is 30 seconds; visibility/extension cap at 24 hours. Claims/pages cap at 1,000 rows, queue jobs and idempotency records at one million each, and one claim at 32 MiB of logical bodies (the reply origin can impose a smaller limit). Default max attempts is 25; concurrency 0 is unlimited. Idempotency defaults to five minutes and caps at 30 days. Receipt generations/epochs prevent reuse after retries/restarts; the exact deadline is already expired.

Implementation source: src/engine/queues.rs; src/queue.rs; src/engine/native.rs. Workflow and datatype guide

Coverage scope: No FQ.* JSON command vectors occur in the BDD feature corpus. Dedicated executable coverage is in tests/native_queues_smoke.py (enqueue, claim, acknowledgements, expiry/retry, paging, idempotency and persistence). This reference does not label those tests as Gherkin scenarios.

FQ.ENQUEUE

FQ.ENQUEUE queue payload [IDEMPOTENCY bytes] [DELAY ms | AT epoch_ms] [PRIORITY i32] [MAXATTEMPTS n]

Returns job_id and created. A retained idempotency duplicate returns the original ID with created: 0 without replacing its body. DELAY and AT are mutually exclusive.

FQ.CLAIM

FQ.CLAIM queue [COUNT n] [VISIBILITY ms]

Returns eligible job records with payload, job_id, receipt and lease deadline; increments attempts. An empty result means no eligible job. Requires the returned receipt for lease operations.

FQ.ACK

FQ.ACK queue receipt

Completes and removes the leased job. Expired, forged or stale receipts cannot acknowledge a current lease. Retained idempotency records outlive completion.

FQ.NACK

FQ.NACK queue receipt [DELAY ms] [ERROR bytes]

Releases a live lease into retry scheduling or dead state when attempts are exhausted. Optional ERROR bytes retain failure information.

FQ.EXTEND

FQ.EXTEND queue receipt visibility_ms

Extends a valid current lease; returns the new absolute deadline, not OK. Extend before expiry.

FQ.RETRY

FQ.RETRY queue job_id [DELAY ms]

Explicitly redrives a dead job and resets attempts while preserving receipt non-reuse.

FQ.CANCEL

FQ.CANCEL queue job_id

Removes a ready, scheduled, running or dead job. Does not undo an external side effect already performed by a worker.

FQ.CONFIG

FQ.CONFIG queue [CONCURRENCY n] [MAXATTEMPTS n] [BACKOFF ms] [MAXBACKOFF ms] [IDEMPOTENCY ms]

Reads or updates queue policy. Max-attempt changes apply to future jobs, not existing ones. Expiry/NACK retries use bounded exponential backoff.

FQ.STATS

FQ.STATS queue

Returns real state counts and observed wait/run sums; these are not estimated latency percentiles.

FQ.JOBS

FQ.JOBS queue cursor [COUNT n] [STATE ready | scheduled | running | dead]

Cursor-pages job metadata. Bodies are fetched explicitly with GET or CLAIM. Treat the returned cursor as queue traversal state.

FQ.GET

FQ.GET queue job_id

Returns job information and body, or null when absent. Inspection is not a lease claim.

Storage administration

FFKV.* administration is an ffkv API. These commands are admin/noscript operations; storage maintenance coordinates execution and can require substantial disk headroom. Maps use RESP3 maps or the corresponding RESP2 representation. A lost reply has an unknown operation outcome: inspect state before retrying.

Limits and caveats: CHECKPOINT and BACKUP require —data-dir. COMPACT requires —storage hybrid. Backup names must be 1–64 ASCII alphanumeric, hyphen or underscore bytes; arbitrary paths and existing destinations are refused. Backups contain plaintext logical data; protect access and restore only from trusted storage.

Implementation source: src/engine.rs:828–855; src/admin.rs; src/blocking.rs. Workflow and datatype guide

Coverage scope: Storage and native queue smoke suites complement the BDD corpus; coverage below is reported only when an actual feature command vector is present. Read src/admin.rs for the current response fields and coordinated checkpoint implementation.

FFKV.STATS

FFKV.STATS

Returns server identity/version/baseline, shard count, storage mode, durability, role, instance/revision/readiness, storage statistics (null in memory mode), WAL bytes/policy/dirty/last-sync and key_count. This is introspection, not a health or HA certificate.

FFKV.COMPACT

FFKV.COMPACT

Reclaims unreferenced derived payload segments in hybrid storage. It is distinct from WAL checkpointing and needs space for old and rebuilt segments. Does not offload all datatypes.

FFKV.CHECKPOINT

FFKV.CHECKPOINT

Streams and synchronizes a coherent logical image and atomically replaces the WAL while retaining the lock. Returns old_bytes, new_bytes and data_frames. File-local WAL sequences reset, not replication offsets.

FFKV.BACKUP

FFKV.BACKUP name

Exports a coherent immutable backup under data-dir/backups/name. Response includes name/path, instance/revision, wal_bytes, data_frames and sha256. Restore is an offline ffkv restore command into a new directory, not a RESP command. Never copy a changing WAL as a backup.

Bloom filters

Scalable bit filters provide probabilistic membership: a positive may be a false positive. ADD/MADD/INSERT can create a missing filter; NOCREATE forbids creation. Reserve before ingest when capacity and error policy matter. Information fields describe ffkv’s actual representation.

Limits and caveats: Backing arrays cap at 64 MiB per key, capacity at 2^30, with bounded growth. Error rates must be finite and strictly between 0 and 1; the handler clamps rates above 0.25. NONSCALING conflicts with nonzero explicit EXPANSION; NOCREATE conflicts with CAPACITY/ERROR. SCANDUMP/LOADCHUNK use checksummed FFKF effects, not RedisBloom packed-memory dumps. Freeze writes during export; only ffkv-to-ffkv interchange is covered.

Implementation source: src/engine/filters.rs:1172–1519; src/engine/filters.rs (handlers and regressions). Workflow and datatype guide

Coverage scope: No BF.* command vectors are present in tests/bdd/features. Source regressions in src/engine/filters.rs cover hashing, growth, bounds, snapshots and FFKF round-trips; this is not an upstream binary-compatibility claim.

BF.RESERVE

BF.RESERVE key error_rate capacity [EXPANSION expansion] [NONSCALING]

Creates a filter with explicit policy; fails when the key exists.

BDD coverage and source examples

These are source observations, not a test run performed by this documentation build. A tag identifies scenario intent; an extracted vector identifies a command invocation, which may intentionally produce an error. Scenarios may require setup, multiple connections, persistence, cluster nodes or native-module fixtures.

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.

Extracted command vectors

The following JSON arrays are the test harness’s argument vectors, not shell commands. Numeric arguments are converted by the harness; objects of the form {"base64":"…"} represent decoded binary bytes, not a literal JSON command argument. Preserve scenario setup and connection ordering. See the CLI guide for shell quoting and binary stdin. No reply is invented or inferred.

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:7 (the following commands succeed:)

[
  "BF.RESERVE",
  "bf",
  0.01,
  10
]

BF.ADD

BF.ADD key item

Adds one item and reports whether the filter changed.

BF.MADD

BF.MADD key item [item ...]

Adds multiple items; returns one result per item.

BF.INSERT

BF.INSERT key [CAPACITY capacity] [ERROR error_rate] [EXPANSION expansion] [NONSCALING] [NOCREATE] ITEMS item [item ...]

Adds a batch with optional creation policy. ITEMS is required.

BDD coverage and source examples

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.

Extracted command vectors

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:11 (client “v3” executes:)

[
  "BF.INSERT",
  "bf",
  "CAPACITY",
  1073741824,
  "ITEMS",
  "x"
]

Next source assertion: the reply equals:

[true]

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:43 (client “v3” executes:)

[
  "BF.INSERT",
  "missing-bf",
  "CAPACITY",
  1073741824,
  "ITEMS",
  "x"
]

Next source assertion: the reply is an error with code “ERR”

BF.EXISTS

BF.EXISTS key item

Returns approximate membership for one item.

BDD coverage and source examples

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.

Extracted command vectors

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:19 (client “v3” executes:)

[
  "BF.EXISTS",
  "bf",
  "x"
]

Next source assertion: the reply equals:

true

BF.MEXISTS

BF.MEXISTS key item [item ...]

Returns approximate membership per item.

BF.CARD

BF.CARD key

Returns the filter’s tracked inserted cardinality, not an exact set membership proof.

BF.INFO

BF.INFO key [CAPACITY | SIZE | FILTERS | ITEMS | EXPANSION]

Returns all information fields or a selected field.

BF.DEBUG

BF.DEBUG key

Returns implementation-specific filter diagnostics.

BF.SCANDUMP

BF.SCANDUMP key iterator

Exports one FFKF chunk and continuation iterator; begin at iterator 0 and follow returned cursors. The chunk is binary.

BF.LOADCHUNK

BF.LOADCHUNK key iterator data

Imports the corresponding binary FFKF page with checked continuity and checksum. Do not paste base64 text as if it were the binary data.

Cuckoo filters

Byte fingerprints, bounded relocation and counting support approximate membership and deletion. ADD permits duplicates; ADDNX/INSERTNX avoid adding a fingerprint already considered present. Delete only items you inserted: false-positive membership can otherwise remove another item’s fingerprint.

Limits and caveats: Backing arrays cap at 64 MiB per key. BUCKETSIZE is 1–255 and MAXITERATIONS 1–65,535. Expansion is bounded; exhaustion returns an error rather than unlimited allocation. FFKF exports are intentionally not RedisBloom native dump files; freeze the source while exporting.

Implementation source: src/engine/filters.rs:1250–1519; src/engine/filters.rs (handlers and regressions). Workflow and datatype guide

Coverage scope: No CF.* command vectors are present in tests/bdd/features. Cuckoo algorithm, relocation, deletion, snapshot and binary round-trip regressions live in src/engine/filters.rs.

CF.RESERVE

CF.RESERVE key capacity [BUCKETSIZE size] [MAXITERATIONS iterations] [EXPANSION expansion]

Creates a filter with explicit capacity and relocation policy.

BDD coverage and source examples

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.
Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:80; command tag and invocation observed.

Extracted command vectors

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:7 (the following commands succeed:)

[
  "CF.RESERVE",
  "cf",
  10
]

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:83 (the following commands succeed:)

[
  "CF.RESERVE",
  "cf",
  4,
  "BUCKETSIZE",
  1,
  "EXPANSION",
  1
]

CF.ADD

CF.ADD key item

Adds one fingerprint, including duplicates.

CF.ADDNX

CF.ADDNX key item

Adds only when approximate membership is absent.

CF.INSERT

CF.INSERT key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...]

Batch insertion; may create a missing filter unless NOCREATE.

BDD coverage and source examples

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.
Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:80; command tag and invocation observed.

Extracted command vectors

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:87 (client “v3” executes:)

[
  "CF.INSERT",
  "cf",
  "ITEMS",
  "hello",
  "hello"
]

Next source assertion: the reply equals:

[true,true]

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:27 (client “v3” executes:)

[
  "CF.INSERT",
  "cf",
  "CAPACITY",
  1073741824,
  "ITEMS",
  "x"
]

Next source assertion: the reply equals:

[true]

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:83 (the following commands succeed:)

[
  "CF.INSERT",
  "cf",
  "ITEMS",
  "",
  "",
  "",
  ""
]

CF.INSERTNX

CF.INSERTNX key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...]

Batch insertion with approximate duplicate avoidance.

CF.EXISTS

CF.EXISTS key item

Returns approximate membership.

BDD coverage and source examples

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:4; command tag and invocation observed.

Extracted command vectors

Insert ignores creation allocation budgets for existing filters — tests/bdd/features/probabilistic.feature:35 (client “v3” executes:)

[
  "CF.EXISTS",
  "cf",
  "x"
]

Next source assertion: the reply equals:

true

CF.MEXISTS

CF.MEXISTS key item [item ...]

Returns membership per item.

CF.COUNT

CF.COUNT key item

Returns the number of matching fingerprints, an approximate count.

BDD coverage and source examples

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:80; command tag and invocation observed.

Extracted command vectors

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:103 (client “v3” executes:)

[
  "CF.COUNT",
  "cf",
  ""
]

Next source assertion: the reply equals:

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:111 (client “v3” executes:)

[
  "CF.COUNT",
  "cf",
  "hello"
]

Next source assertion: the reply equals:

CF.DEL

CF.DEL key item

Deletes a matching fingerprint if present.

BDD coverage and source examples

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:80; command tag and invocation observed.

Extracted command vectors

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:144 (client “v3” executes:)

[
  "CF.DEL",
  "cf",
  "hello"
]

Next source assertion: the reply equals:

true

CF.INFO

CF.INFO key

Returns implementation-specific filter information.

BDD coverage and source examples

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:80; command tag and invocation observed.

Extracted command vectors

Cuckoo insertion reuses earlier parts and preserves duplicate counts after replay — tests/bdd/features/probabilistic.feature:95 (client “v3” executes:)

[
  "CF.INFO",
  "cf"
]

Next source assertion: the reply contains:

{"Size":8,"Number of filters":2,"Number of items inserted":6}

CF.DEBUG

CF.DEBUG key

Returns implementation-specific diagnostics.

CF.SCANDUMP

CF.SCANDUMP key iterator

Exports binary FFKF pages and continuation cursors, starting at iterator 0.

CF.LOADCHUNK

CF.LOADCHUNK key iterator data

Imports checked binary FFKF pages in order.

CF.COMPACT

CF.COMPACT key

Compacts the filter’s representation without converting it into an exact set.

Count-Min Sketch

Bounded counter rows provide approximate frequencies. Initializers require a missing key. Merge requires an existing destination and compatible source width/depth/cell-size. Signed updates and signed merge weights are validated without partial application of a failed batch.

Limits and caveats: At most 8,388,608 cells. CELL_SIZE accepts 1, 2, 4 or 8 bytes (default 4). Probability initialization uses ceil(2/error) width and ceil(log(probability)/log(0.5)) depth. Error and probability must be finite and strictly between 0 and 1. Sketches remain RAM-resident in hybrid mode.

Implementation source: src/engine/sketches.rs:21–51, 1435–1630. Workflow and datatype guide

Coverage scope: No CMS.* command vectors occur in the BDD features. src/engine/sketches.rs contains probability/dimension, signed-update, collision, merge, binary and replay regression tests.

CMS.INITBYDIM

CMS.INITBYDIM key width depth [CELL_SIZE bytes]

Creates explicitly sized counter rows.

CMS.INITBYPROB

CMS.INITBYPROB key error probability [CELL_SIZE bytes]

Derives dimensions from the specified error/probability budget.

CMS.INCRBY

CMS.INCRBY key item increment [item increment ...]

Updates item frequency estimates and returns the resulting estimates.

CMS.QUERY

CMS.QUERY key item [item ...]

Reads approximate frequency per item.

CMS.MERGE

CMS.MERGE destination numkeys source [source ...] [WEIGHTS weight [weight ...]]

Weighted merge into an existing compatible destination; number of weights must equal numkeys.

CMS.INFO

CMS.INFO key

Reports dimensions and accumulated count.

Top-K

HeavyKeeper counter rows plus a retained-member min-heap estimate the most frequent items. This is not an exact ranking over all previously observed members. Results depend on bounded probabilistic state.

Limits and caveats: At most 8,388,608 cells. RESERVE accepts either k alone or all width/depth/decay options; defaults are width 8, depth 7, decay 0.9. Decay is finite and in (0,1]. Typed structures remain RAM-resident.

Implementation source: src/engine/sketches.rs:52–88, 1631–1761. Workflow and datatype guide

Coverage scope: No TOPK.* vectors occur in the BDD feature corpus. Command validation, collisions, membership, counts, binary members and replay have regressions in src/engine/sketches.rs.

TOPK.RESERVE

TOPK.RESERVE key k [width depth decay]

Creates a missing Top-K sketch.

TOPK.ADD

TOPK.ADD key item [item ...]

Adds observations and returns displaced retained members (or null entries).

TOPK.INCRBY

TOPK.INCRBY key item increment [item increment ...]

Adds weighted observations and returns displaced members.

TOPK.QUERY

TOPK.QUERY key item [item ...]

Reports whether each item is retained in the Top-K heap.

TOPK.COUNT

TOPK.COUNT key item [item ...]

Returns frequency estimates.

TOPK.LIST

TOPK.LIST key [WITHCOUNT]

Lists retained heavy hitters, optionally with counts.

TOPK.INFO

TOPK.INFO key

Reports configured k, width, depth and decay.

t-digest

Weighted centroids approximate distributions, quantiles, CDFs and ranks. Observations must be finite. Empty-digest and edge-rank results must be interpreted as distribution query results, not fabricated zero measurements.

Limits and caveats: Compression caps at 1,000,000 (default 100); allocation and reply budgets still apply. MERGE includes the old destination unless OVERRIDE; explicit COMPRESSION wins, otherwise existing destination or source compression determines the result. Structures remain in RAM.

Implementation source: src/engine/sketches.rs:89–174, 1762–1943. Workflow and datatype guide

Coverage scope: No TDIGEST.* vectors occur in the BDD features. Distribution, weighted centroid, rank, merge and persistence regressions live in src/engine/sketches.rs.

TDIGEST.CREATE

TDIGEST.CREATE key [COMPRESSION compression]

Creates a missing digest.

TDIGEST.RESET

TDIGEST.RESET key

Clears observations while retaining digest policy.

TDIGEST.ADD

TDIGEST.ADD key value [value ...]

Adds finite numeric observations.

TDIGEST.MERGE

TDIGEST.MERGE destination numkeys source [source ...] [COMPRESSION compression] [OVERRIDE]

Merges source distributions, optionally replacing existing destination observations.

TDIGEST.MIN

TDIGEST.MIN key

Returns the observed minimum.

TDIGEST.MAX

TDIGEST.MAX key

Returns the observed maximum.

TDIGEST.QUANTILE

TDIGEST.QUANTILE key quantile [quantile ...]

Estimates values at quantiles in [0,1].

TDIGEST.CDF

TDIGEST.CDF key value [value ...]

Estimates cumulative probabilities at values.

TDIGEST.TRIMMED_MEAN

TDIGEST.TRIMMED_MEAN key low_cut_quantile high_cut_quantile

Estimates the mean between quantile cuts.

TDIGEST.RANK

TDIGEST.RANK key value [value ...]

Estimates ranks from the lower end.

TDIGEST.REVRANK

TDIGEST.REVRANK key value [value ...]

Estimates ranks from the upper end.

TDIGEST.BYRANK

TDIGEST.BYRANK key rank [rank ...]

Estimates values at lower-end ranks.

TDIGEST.BYREVRANK

TDIGEST.BYREVRANK key rank [rank ...]

Estimates values at upper-end ranks.

TDIGEST.INFO

TDIGEST.INFO key

Reports compression, capacity and centroid/observation statistics.

Additional JSON arithmetic

JSON.NUMPOWBY is registered by ffkv but absent from the pinned canonical catalog. It shares atomic JSON numeric update and path semantics with the other JSON arithmetic operations.

Limits and caveats: The JSON document/path/node/match limits apply. Invalid numeric operations or non-finite results fail instead of writing invalid JSON numbers.

Implementation source: src/engine/json.rs:590–596, 2729–2743. Workflow and datatype guide

Coverage scope: There are no JSON.NUMPOWBY command vectors in the BDD corpus. Direct engine regressions in src/engine/json.rs cover exponentiation and invalid input.

JSON.NUMPOWBY

JSON.NUMPOWBY key path value

Raises each matching numeric value to the supplied power and returns the JSON arithmetic result.

Containers and discovery

Registry roots such as ACL, CLIENT, CLUSTER, CONFIG, FUNCTION, MODULE, SCRIPT, PUBSUB, XGROUP, XINFO, FT.CONFIG and FT.CURSOR dispatch their named subcommands. They are not separate implementations of every upstream command. Find each canonical subcommand in the explorer; inspect COMMAND LIST and COMMAND INFO on the running build for dynamically loaded native-module commands. The hash-import API is already represented in the canonical catalog: HIMPORT.