Materia KV

Materia is a new serverless databases offering by Clever Cloud. A whole range of services meeting the needs expressed by our customers in recent years, with an open and resilient approach. It includes deployment across multiple availability zones, compatibility with existing protocols, clients, and pay-as-you-go billing. It’s built on the FoundationDB open source transactional engine. A distributed and robust solution, notably thanks to its high simulation capacity.

Materia KV is the first publicly available product of this family. It’s a key-value database which comes with simplicity in mind. You have no instance size to choose, no storage capacity to worry about. We simply provide you with a host address, a port and a token: you’re ready to go! Once our servers send a reply message, your data is durable: it’s synchronously replicated over 3 data centers in Paris.

You don’t have to configure leaders, followers: high availability is included, by design.

Compatibility layers

We didn’t want this Materia KV to come at the cost of complex configuration, requiring the use of special clients and ORMs. That’s why we’ve developed its compatibility layers: each one lets you talk to Materia KV through an existing protocol, with the clients, CLIs and ORMs you already use — no Clever Cloud-specific SDK required.

Two layers are available:

• Redis API (and variants such as Redict and Valkey) — full read/write access, the primary way to interact with Materia KV.
• GraphQL — a typed, read-oriented view of the same keyspace, served from a standard GraphQL endpoint.

Both layers operate on the same underlying data, so any key written through the Redis API is immediately visible through GraphQL. For the Redis API layer specifically, you can use redis-cli, valkey-cli or alternatives such as iredis, as well as graphical clients we’ve tested successfully:

• Another Redis Desktop Client
• PX3 Redis UI
• Qredis
• Redis Commander
• Redis Insight

Create a Materia KV add-on

You can create a Materia KV add-on as simply as any other Clever Cloud service in the Console, following this link. Select the plan (free during Beta testing phase), an application to link to (or none), give it a name, and you’ll get access to its dashboard giving you connection details. Environment variables shared with a linked application are listed in the Service dependencies section.

We included them with the REDIS_ format. Thus, you can just try to replace a Redis or Valkey instance by Materia KV. It’s as simple as linking the new add-on, unlinking the old one and restarting your application! (Check commands you’ll need first).

You can also use clever tools to create a Materia KV add-on and set environment variables to test it with a PING command:

clever addon create kv ADDON_NAME
source <(clever addon env addon ADDON_ID -F shell)
redis-cli -h $KV_HOST -p $KV_PORT --tls PING

Here is an example of what you can expect:

$ clever addon create kv testKV

Add-on created successfully!
ID: addon_4997cfe3-f104-4d05-9fe4-xxxxxxxxx
Real ID: kv_01HV6NCSRDxxxxxxxxxxxxxxxx
Name: testKV

/!\ The Materia KV provider is in Beta testing phase, don't store sensitive or production grade data
You can easily use Materia KV with 'redis-cli', with such commands:
source <(clever addon env addon_4997cfe3-f104-xxxx-xxxx-xxxxxxxxx -F shell)
redis-cli -h $KV_HOST -p $KV_PORT --tls

You can also deploy Materia KV add-ons with Terraform provider (OpenTofu compatible).

Clever Cloud KV Explorer

Access and edit your Key-Value databases with the KV Explorer tool, it’s part of Clever Cloud’s all included experience.

Supported data types

Hash, list, set and string types are supported. For Materia KV, only string type is currently available, with other types coming soon.

An intuitive, useful interface

The interface lets you filter keys by type and perform wildcard searches (for example: *value_to_search*). Value fields are multi-line for convenience, and you can copy/paste values directly from the interface. Special attention has been paid to accessibility and keyboard navigation with shortcuts to optimize your experience.

KV Explorer Terminal

At the bottom of the page, you’ll find an integrated terminal that works like a traditional CLI client. Type your commands and press Enter to execute them. All commands are supported, including FLUSHDB and FLUSHALL. Be careful with these as they erase data!

KV Explorer is in Beta testing phase and we’ll improve it over the coming months, thanks to your feedback and suggestions.

• Share your feedback on KV Explorer

Using the Redis API compatible layer

Environment variables and CLI usage

To connect to a Materia KV add-on, you need 3 parameters: the host, the port and a token. You can set these parameters as environment variables by doing source <(clever addon env addon ADDON_ID -F shell). The variables set are:

• $KV_HOST and its alias $REDIS_HOST
• $KV_PORT and its alias $REDIS_PORT
• $KV_TOKEN and its alias $REDIS_PASSWORD
• $REDIS_CLI_URL
• $REDISCLI_AUTH

You can directly use these environment variables to connect to a Materia KV add-on using redis-cli if REDISCLI_AUTH is set:

redis-cli -h $KV_HOST -p $KV_PORT --tls

Materia KV is also compatible with alternatives such as iredis.

Fish shell users

If you use the Fish shell, you can use the following command to set the environment variables:

clever addon env ADDON_ID -F shell | source

Clever KV

We’re exploring how Clever Tools can natively support Materia KV and helps you to manage such add-ons without any additional software or configuration. The clever kv command is available since version 3.11.

• Learn more about Clever KV

Supported types and commands

Supported value types are:

• Hash
• Set
• String

Find below the list of currently supported commands:

JSON commands

Materia KV provides preliminary support for JSON data type operations, compatible with Redis API JSON commands and clients. Unlike Redis JSON which uses a dedicated data type, our implementation works directly with classic string data types while maintaining API compatibility.

Path Syntax and Behavior

• $: Root element (required for setting values, optional for GET/DEL)
• $.field: Access field in object
• $..field: Recursively search for all matching fields
• $.array[index]: Access array element by index
• .field: Shorthand notation (without $) returns a direct value instead of an array wrapper

Examples

# Setting and getting JSON
> JSON.SET myJsonKey $ '{"a":"23"}'
OK
> JSON.GET myJsonKey
"{\"a\":\"23\"}"
> JSON.GET myJsonKey $
"[{\"a\":\"23\"}]"
> JSON.GET myJsonKey $.a
"[\"23\"]"

# Multiple paths with different notations
> JSON.SET myJsonKey $ '{"f1":{"k1":["foo",42],"k2":["bar",53]},"f2":{"k1":["Hello",61]}}'
OK
> JSON.GET myJsonKey $.f1 $.f2
"{\"$.f1\":[{\"k1\":[\"foo\",42],\"k2\":[\"bar\",53]}],\"$.f2\":[{\"k1\":[\"Hello\",61]}]}"
> JSON.GET myJsonKey .f1 .f2
"{\".f1\":{\"k1\":[\"foo\",42],\"k2\":[\"bar\",53]},\".f2\":{\"k1\":[\"Hello\",61]}}"

# Recursive search
> JSON.GET myJsonKey $..k1
"[[\"foo\",42],[\"Hello\",61]]"

# Array manipulation
> JSON.SET myJsonKey $ '{"a":[1,2,3,4]}'
OK
> JSON.DEL myJsonKey $.a[1]
(integer) 1
> JSON.GET myJsonKey
"{\"a\":[1,3,4]}"

Current Limitations

• JSON.SET can only create new documents at root path ($)
• JSON.SET can’t create new fields in existing documents
• Nested path creation is not supported (e.g., $.new.child.field)
• Keys in your JSON must not contains characters like .., *, [?(

Using the GraphQL compatibility layer

In addition to the Redis API, Materia KV exposes a GraphQL endpoint. It reads from the same keyspace as the Redis API layer — every key you write through the Redis API is immediately queryable through GraphQL, with no synchronization layer in between. Both interfaces authenticate with the same token, and that token scopes each request to your add-on’s data on the shared cluster.

The GraphQL layer is read-only today — mutations aren’t supported yet. Use the Redis API for writes.

Endpoint and authentication

Materia KV is a distributed cluster: the GraphQL endpoint is a single URL shared by every add-on in a given region, over HTTPS on the standard port. For the Paris region, it is:

https://materiakv-graphql.eu-fr-1.services.clever-cloud.com/graphql

Authentication uses the same token as the Redis API ($KV_TOKEN / $REDIS_PASSWORD), passed as a bearer token:

curl -X POST "https://materiakv-graphql.eu-fr-1.services.clever-cloud.com/graphql" \
  -H "Authorization: Bearer $KV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

Missing or invalid credentials return HTTP 401 with the error in the GraphQL errors array. This endpoint returns HTTP 200 for all other errors (wrong-type reads, unknown fields, mutation requests, validation errors), with the details in errors.

GraphiQL playground

Opening the GraphQL URL in a browser (plain GET) serves an embedded GraphiQL playground: an in-browser IDE with autocompletion, query history and a documentation explorer. Every request — including the schema introspection that powers autocomplete and the docs explorer — needs your token, otherwise GraphiQL displays Error fetching schema.

Initial setup, once per browser session:

1. At the bottom of the query panel, click the Headers tab (next to Variables).

2. Paste your token as a JSON object:

   {
     "Authorization": "Bearer <your-token>"
   }

3. Click the Re-fetch GraphQL schema icon at the bottom of the left sidebar (the circular-arrow icon, keyboard shortcut Ctrl + Shift + R). Introspection runs with your header, and the full schema becomes browsable.

Once the header is set, the Docs Explorer (book icon, also in the left sidebar) shows the full type tree: every query, every argument, every return type, with the descriptions baked into the schema.

Fetching the schema

Introspection is enabled, so you can pull the schema directly from the endpoint in three common ways.

1. Browse it in GraphiQL — follow the setup above (headers + re-fetch), then click the Docs Explorer icon in the left sidebar.

2. Raw JSON introspection via curl — useful for scripts and CI:

   curl -X POST "https://materiakv-graphql.eu-fr-1.services.clever-cloud.com/graphql" \
     -H "Authorization: Bearer $KV_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query":"{ __schema { queryType { name fields { name } } types { name kind } } }"}'

3. Download as SDL (the classic .graphql schema file) using any introspection tool, such as get-graphql-schema:

   npx -y get-graphql-schema \
     -h "Authorization=Bearer $KV_TOKEN" \
     "https://materiakv-graphql.eu-fr-1.services.clever-cloud.com/graphql" > schema.graphql

The resulting file plugs straight into code generators, IDE plugins, and schema-aware editors.

Queries

The schema exposes a single root type, MateriaKvQuery, with queries for strings, hashes and sets — including single-key lookups, batched reads, pattern matching and server-side set algebra (setIntersection, setDifference, setUnion). Fetch the full list of queries and their signatures through introspection (see Fetching the schema above) or browse them in the GraphiQL Docs Explorer.

Single-key queries (string, hash, hashField, getSetMembers) return a nullable object — null when the key doesn’t exist. Pattern and batch queries return non-null lists (possibly empty).

Query examples

Fetch a single string, including its expiration:

query ReadSession($key: String!) {
  string(key: $key) {
    key
    value
    expireAt
  }
}

Read a structured record in one round-trip:

query GetUser($key: String!) {
  hash(key: $key) {
    key
    fields { name value }
  }
}

Combine several reads into one request using aliases:

query Dashboard {
  admins: getSetMembers(key: "group:admins") { members }
  active: getSetMembers(key: "group:active") { members }
  overlap: setIntersection(keys: ["group:admins", "group:active"])
}

Always pass user input through GraphQL variables rather than string interpolation: the server type-checks every variable, which reduces injection risk and avoids query string interpolation issues:

curl -X POST "https://materiakv-graphql.eu-fr-1.services.clever-cloud.com/graphql" \
  -H "Authorization: Bearer $KV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($k:String!){ string(key:$k){ key value } }",
    "variables": { "k": "session:xyz" }
  }'

JSON values read through GraphQL

JSON documents written via JSON.SET are stored on top of strings. The schema has no dedicated GraphQL type for JSON: read the document back through string(key) as the serialized payload and parse it client-side. Partial JSON paths (JSON.GET key $.field) are only available through the Redis API.

Current behaviors and limitations

• Queries on a key of the wrong type (e.g. hash(key) on a string key) return a GraphQL error — Database operation failed: Operation against a key holding the wrong kind of value — rather than null. Make sure your query type matches the Redis type at the same key.
• stringsByPattern(pattern) rejects a call where the pattern matches more than 100 keys with an error (Database operation failed: Max batch size exceeded: N > 100) — results are not silently truncated. Narrow the pattern (or walk the keyspace through several tighter prefixes) when the match count is larger.
• strings(keys: [...]) has the same hard limit: at most 100 keys per call. Chunk larger batches on the client side.
• Pattern-based queries (hashesByPattern, setsByPattern, hashFieldsByPattern) are not paginated: each call returns its full result set in one response. Keep patterns focused to avoid oversized payloads.
• Glob patterns follow the Redis KEYS/SCAN syntax (*, ?, [abc]).
• The expireAt field is an absolute instant (ISO 8601), not a remaining TTL — parse it as an ISO 8601 timestamp in your client, then subtract the current time to compute a countdown.
• Authentication errors return HTTP 401 with the message in the errors array. Every other GraphQL error (wrong-type reads, mutation requests, validation errors) returns HTTP 200 with errors populated.

Demos and examples

We’ve prepared a few examples to help you get started with Materia KV:

• Materia KV Go client
• Materia KV raw TCP V demo
• Materia KV raw TCP Ruby demo
• Materia KV PHP sessions with TTL demo
• Materia KV write via Redis API, read via GraphQL