Skip to main content

Key Value Store

Overview​

The Key-Value Store in RelayX provides a simple way to persist and retrieve small pieces of state that need to be shared across parts of your system.

It is designed for configuration, flags, counters, metadata, and other lightweight state that must be available quickly and consistently. It is not a database and does not provide querying, indexing, or transactions.

Before performing any key-value operations, the Key-Value Store must be explicitly initialized. All reads and writes happen through the initialized store handle.

How This Works​

The Key-Value Store is scoped to your RelayX account.

When you initialize the store, the SDK establishes access permissions and prepares a client-side handle. All operations are executed directly against the RelayX backend.

Writes overwrite existing values. Reads return the most recent value. Deletes permanently remove keys.

There is no versioning, no history, and no conflict resolution beyond last-write-wins.

Success for an operation means the backend has accepted the request and applied it.

Initializing the Key-Value Store​

Before using the Key-Value Store, you must initialize it from a connected client.

import kotlinx.coroutines.runBlocking

runBlocking {
    val kvStore = realtime.initKVStore()
}

This returns a KVStorage object that exposes all KV operations.

Note: initKVStore() is a suspend function and must be called from a coroutine scope.

Initialization may fail if the client is not connected or does not have KV permissions.

Creating or Updating a Key​

API Usage​

runBlocking {
    kvStore.put(key, value)
}

Note: put() is a suspend function and must be called from a coroutine scope.

Key Rules​

  • Must be a String
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Value Rules​

Values may be:

  • String
  • Number (Int, Long, Double, Float, etc.)
  • Boolean
  • JsonObject (com.google.gson.JsonObject)
  • JsonArray (com.google.gson.JsonArray)

The Kotlin SDK has overloaded put() methods for each supported type.

If the key does not exist, it is created.

If the key already exists, the previous value is overwritten.

The method does not return anything.

Errors​

put() throws an error if:

  • The key is invalid
  • The value type is unsupported
  • The client does not have write permission

Example​

import com.google.gson.JsonObject
import kotlinx.coroutines.runBlocking

runBlocking {
    // Number
    kvStore.put("config.maxRetries", 5)

    // Boolean
    kvStore.put("featureFlags.newUI", true)

    // JsonObject
    val metadata = JsonObject().apply {
        addProperty("region", "ap-south-1")
    }
    kvStore.put("service.metadata", metadata)

    // String
    kvStore.put("service.name", "my-service")
}

Getting a Value​

API Usage​

runBlocking {
    val data = kvStore.get(key)
}

Note: get() is a suspend function and must be called from a coroutine scope.

The method returns a KeyValueData? object (nullable) for the given key.

Return Value​

data class KeyValueData(
    var key: String,
    var value: Any?
)
  • Returns KeyValueData if the key exists
  • Returns null if the key does not exist
  • The value property contains the actual stored value

Key Rules​

  • Must be a String
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Errors​

get() throws an error if:

  • The key is invalid
  • The client does not have read permission

Example​

import kotlinx.coroutines.runBlocking

runBlocking {
    val data = kvStore.get("config.maxRetries")

    if (data != null) {
        println("Key: ${data.key}")
        println("Value: ${data.value}")
    } else {
        println("Key not found")
    }
}

Deleting a Key​

API Usage​

runBlocking {
    kvStore.delete(key)
}

Note: delete() is a suspend function and must be called from a coroutine scope.

Deletes the key permanently from the Key-Value Store.

The method does not return anything.

Key Rules​

  • Must be a String
  • Must not be null
  • Must not be empty
  • Names can only contain: a-z, A-Z, 0-9, _, -, ., = and /

Errors​

delete() throws an error if:

  • The key is invalid
  • The client does not have write permission

Example​

import kotlinx.coroutines.runBlocking

runBlocking {
    kvStore.delete("featureFlags.newUI")
}

Listing All Keys​

API Usage​

runBlocking {
    val keys = kvStore.keys()
}

Note: keys() is a suspend function and must be called from a coroutine scope.

Returns a List<String> representing all keys currently stored.

Errors​

keys() throws an error if:

  • The client does not have read permission

Example​

import kotlinx.coroutines.runBlocking

runBlocking {
    val allKeys = kvStore.keys()
    println("All keys: $allKeys")

    // Iterate through keys
    for (key in allKeys) {
        val data = kvStore.get(key)
        println("$key = ${data?.value}")
    }
}

Common Mistakes​

  • Assuming values are versioned or transactional
  • Using the KV Store as a database
  • Writing large payloads
  • Ignoring permission errors

Notes & Limitations​

  • Last-write-wins behavior
  • No TTL or expiry
  • No atomic operations
  • No partial updates
  • Intended for small, shared state only


Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️