Nuxeo key-value stores: providers, TTL and Java examples

What's a Key Value Store?

Nuxeo's KeyValueStore API stores values under keys and provides operations for strings, bytes and long values. It also supports an optional time to live (TTL). Use it for application state that does not need a document's content model and user-facing lifecycle.

Choose a provider for the deployed release

Provider availability and persistence depend on the Nuxeo release and deployment. The LTS 2025 API documents SQL and MongoDB providers. Inspect the configured provider before relying on shared state or restart durability; an in-memory store is unsuitable for data that must survive the process. SQL provider

Real-World Use Cases

I looked at ~30 recent Nuxeo projects I worked on, and KVS popped up in many ways:

• Temporarily storing values while publishing to external systems
• Holding intermediate data during import
• Tracking failed login attempts
• Counting blocked users
• Saving custom config settings
• Storing tokens/codes used in auth flows
• Tracking export stats (e.g., # of docs zipped)
• Holding user or system notifications
• etc..

Basically, whenever you need to persist data that doesn't belong in a document or vocabulary-this is your tool.

How to Use KVS in Nuxeo

The following contribution and Java calls illustrate a named MongoDB-backed store. Confirm the provider configuration against your installed Nuxeo release before using them.

Step 1 - Declare your store in your XML contribution:

<extension target="org.nuxeo.runtime.kv.KeyValueService" point="configuration">
  <store name="transcodingFailureNotification" class="org.nuxeo.ecm.core.mongodb.kv.MongoDBKeyValueStore">
    <property name="collection">transcodingFailureNotification</property>
  </store>
</extension>

Step 2 - Store a value (with or without a TTL):

KeyValueStore kvStore = Framework.getService(KeyValueService.class)
    .getKeyValueStore("transcodingFailureNotification");
kvStore.put(doc.getId(), failureMessage, 3600); // TTL in seconds: one hour

Step 3 - Retrieve the value later:

KeyValueStore kvStore = Framework.getService(KeyValueService.class)
    .getKeyValueStore("transcodingFailureNotification");
String failureMessage = kvStore.getString(doc.getId());

Make expiry and concurrent updates explicit

The API defines TTL in seconds, with zero meaning no expiry. A missing key returns null. Handle that case as part of normal control flow. For counters or competing writers, review the atomic operations such as compareAndSet rather than building a read-then-write sequence. LTS 2025 KeyValueStore API

A store is not an authentication policy. If you use it for codes or temporary access state, define expiration, attempt limits and single-use behavior separately. See the external-share passcode design.

Verify the behavior your workflow depends on

Test a missing key, an expired value, a replacement process and two concurrent writers. Record which provider and Nuxeo release were used. For a clustered workflow, verify that different nodes see the expected value; an example that works in one process does not establish that result.

For processing workloads, pair this with media conversion planning or discuss an integration review.