Key-Value Store

Description

The Key-Value Store component stores and retrieves values shared across events, scenarios and processing modes. Use it to keep state that outlives a single event — for example counters, user profiles, feature flags or data handed over from one scenario to another.

Entries are grouped into namespaces. A namespace defines:

• the key name — a label describing what the key represents (e.g. userId),
• the value schema — a JSON schema all values stored in the namespace must conform to. The Designer derives the value type from this schema, so values you read and write are fully typed in scenario expressions.

Every entry has a time-to-live (TTL) and is automatically removed after that duration.

The component supports two operations:

• get — reads the value stored under a key; returns null when the key is absent or expired,
• set — writes a value under a key with the given TTL, overwriting the previous value if present.

Parameters and configuration

Name	Description
Operation	get or set.
Namespace	Namespace that groups keys and defines the value schema. Namespaces are created and deleted in the Key-Value Store tab.
Key (shown under the namespace's key name)	Unique identifier of the entry within the namespace.
Value	set operation only — the value to store. Its type is derived from the namespace schema and validated in the Designer.
TTL	set operation only — time-to-live of the entry; the entry is automatically removed after this duration. Defaults to 1 hour.
Output variable name	Variable name under which the node result will be available in subsequent nodes.

Returned value

Operation	Returned value
get	The stored value, typed according to the namespace schema, or null when the key is absent or its TTL has expired.
set	A record with a single field keyExisted (Boolean) — true when the write overwrote an existing entry.

Namespaces

A default namespace is created automatically, using Key as the key name and String as the value type. Admins create and delete namespaces in the Key-Value Store tab. For each namespace, you specify its name, key name, and the schema of its stored values.

A namespace name may contain letters, digits, spaces, hyphens and underscores. Deleting a namespace removes all entries stored in it. You cannot change the key name or the schema of an existing namespace: delete the namespace and create it again, which removes its entries.

The value schema is defined with the JSON schema builder: a table of fields, or JSON Schema text. Only flat schemas (no nested objects) can be defined there. The Value of a set operation can be built with the Data Mapper.

Key-Value Store management

Admins open the tab from the Key-Value Store entry in the left menu. It lists every Key-Value Store configured in any scenario type; when there is more than one, pick it in the Store field at the top of the namespace list. Stores with the same component ID but different backend configurations remain separate; use the scenario type to choose the right one. Identical backend configurations are grouped across scenario types. Search the list, open a namespace to see its key name and value schema or to delete it, or use Create namespace to add one.

Administration API

The administration API is rooted at /api/custom/kv-store-management/stores. The store list returns storeId, componentId, label, backendType, and processingTypes. Use the returned storeId in /{storeId}/namespaces to list or create namespaces, and /{storeId}/namespaces/{namespace} to read one. URL-encode both identifiers. Creating uses POST with {namespace, keyName, jsonSchema}; jsonSchema is an object. Reads return {name, keyName, jsonSchema}. All these endpoints require administrator access. Creation provisions empty metadata; it does not import stored entries.

Storage backends

The Key-Value Store keeps data in one of the following backends:

• Database (default) — entries are stored in a Nussknacker database. No additional setup is required. Expired entries are filtered out on read and cleaned up periodically.
• Redis — entries are stored in a Redis instance configured via the Redis integration. Each Redis integration adds a separate, dedicated Key-Value Store component to the palette. Expired entries are removed natively by Redis.

Regardless of the backend, the component behaves the same in scenarios — operations, typing and namespaces work identically.

Additional considerations

• The store can be configured with limits: maximum TTL, maximum key size, maximum value size and maximum number of entries. Exceeding a limit causes a runtime error for the processed record.
• The entry count limit may temporarily include entries that have already expired but have not been cleaned up yet.
• set operations are also performed when testing scenarios — test runs write to the same store.