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.

What it is for

The main use is a handoff between processing modes. A streaming scenario computes state from events - a sliding window, an aggregate, the last value seen for a key - and writes it under that key with a TTL. A request-response scenario reads it by key and answers in milliseconds, without touching the event stream. The namespace's value schema is the contract between the two: the writer and the reader are typed against the same definition.

Exposed as an MCP tool, such a request-response scenario gives an AI agent real-time context: the agent asks for a key and gets fresh, pre-computed, typed state instead of raw events. The blog post Real-time Kafka data for AI agents with MCP walks through this pipeline end to end: purchases on a Kafka topic, a sliding window in a streaming scenario, the aggregate in a namespace with a TTL, a request-response scenario classifying it with a decision table, and the scenario published as an MCP tool the agent calls.

Beyond that handoff, the store serves the usual per-key state: counters, user profiles, feature flags, idempotency keys and lookups cached by key.

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 Nussknacker's own PostgreSQL database, the one the Designer keeps scenarios in (databaseKind: nussknacker-db). No additional setup is required, which makes it the right choice for a first installation and for development, but it is not a production configuration: every get and set is a query against the Designer's database, and expired entries are only filtered out on read and cleaned up periodically. For production, configure Redis.
• 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.