Key-Value Store

ekoDB includes a built-in key-value (KV) store optimized for fast lookups, caching, and metadata storage. Use KV operations for simple key-value pairs when you don't need the full document structure.

When to Use KV Store

Caching - Store frequently accessed data
Session Management - User sessions and temporary data
Configuration - Application settings and flags
Counters - Track metrics and statistics
Metadata - Additional data linked to documents

First, generate an access token using your API key:

curl -X POST https://{EKODB_API_URL}/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Get Value

Retrieve a value by key.

GET https://{EKODB_API_URL}/api/kv/get/{key}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "user_id": "user_456",
  "login_time": "2024-01-15T10:30:00Z"
}

Working Examples

Prefer a client library? See examples in Rust, Python, TypeScript, Go, or Kotlin

Want to use the REST API directly? See examples in JavaScript, Python, Go, or Rust

Response Format

The get operation returns the value directly without wrapping it in an object. The key is part of the URL path.

Set Value

Store or update a key-value pair.

POST https://{EKODB_API_URL}/api/kv/set/{key}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "user_id": "user_456",
  "login_time": "2024-01-15T10:30:00Z"
}

# Response
{
  "user_id": "user_456",
  "login_time": "2024-01-15T10:30:00Z"
}

Response Format

The set operation returns the stored value directly, confirming what was saved.

Value Types:

KV store accepts any JSON value:

// String
"simple value"

// Number
42

// Boolean
true

// Object
{"nested": "data", "count": 10}

// Array
["item1", "item2", "item3"]

Delete Value

Delete a key-value pair.

DELETE https://{EKODB_API_URL}/api/kv/delete/{key}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
{
  "message": "deleted"
}

Batch Get

Retrieve multiple values in a single request.

POST https://{EKODB_API_URL}/api/kv/batch/get
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "keys": ["session_1", "session_2", "session_3"]
}

# Response
[
  {"user_id": "user_1"},
  {"user_id": "user_2"},
  {}
]

Response Format

Returns an array of values in the same order as the requested keys. Missing keys return an empty object {}.

Batch Set

Store multiple key-value pairs in a single request.

POST https://{EKODB_API_URL}/api/kv/batch/set
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "operations": [
    {
      "key": "counter_views",
      "value": 1000
    },
    {
      "key": "counter_clicks",
      "value": 250
    },
    {
      "key": "feature_flags",
      "value": {
        "new_ui": true,
        "beta_features": false
      }
    }
  ]
}

# Response
[
  ["counter_views", true],
  ["counter_clicks", true],
  ["feature_flags", true]
]

Response Format

Returns an array of [key, success] tuples indicating which keys were successfully set.

Batch Delete

Delete multiple keys in a single request.

DELETE https://{EKODB_API_URL}/api/kv/batch/delete
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "keys": ["session_1", "session_2", "temp_data"]
}

# Response
[
  ["session_1", true],
  ["session_2", true],
  ["temp_data", true]
]

Response Format

Returns an array of [key, success] tuples indicating which keys were successfully deleted.

Clear All

Delete all key-value pairs.

Admin Permission Required

This operation requires admin permissions and cannot be undone.

DELETE https://{EKODB_API_URL}/api/kv/clear
Authorization: Bearer {ADMIN_TOKEN}

# Response
{
  "message": "success"
}

Find Keys

Query keys with filters and patterns.

POST https://{EKODB_API_URL}/api/kv/find
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "prefix": "user_session_",
  "limit": 10,
  "offset": 0
}

# Response
[
  {"key": "user_session_123", ...},
  {"key": "user_session_456", ...},
  {"key": "user_session_789", ...}
]

Response Format

Returns an array of key-value records directly, not wrapped in an object. Each record contains the key and its associated value.

Filter Options:

{
  "prefix": "cache_",       // Keys starting with prefix
  "suffix": "_temp",        // Keys ending with suffix
  "contains": "session",    // Keys containing string
  "limit": 100,             // Max results
  "offset": 0               // Pagination offset
}

Linking KV to Documents

Link key-value pairs to document records for additional metadata.

Create Link

Link a KV pair to a document.

POST https://{EKODB_API_URL}/api/kv/{key}/links/{collection}/{record_id}
Content-Type: application/json
Authorization: Bearer {YOUR_API_TOKEN}

{
  "metadata": {
    "created_by": "user_123",
    "purpose": "analytics",
    "expires": "2024-12-31"
  }
}

# Response
null

Response Format

Returns null on success. Check HTTP status code (200) to confirm the link was created.

Get Links

Retrieve all document links for a key.

GET https://{EKODB_API_URL}/api/kv/{key}/links
Authorization: Bearer {YOUR_API_TOKEN}

# Response
[
  {
    "collection": "reports",
    "record_id": "report_456",
    "metadata": {
      "created_by": "user_123",
      "purpose": "analytics"
    }
  },
  {
    "collection": "dashboards",
    "record_id": "dashboard_789",
    "metadata": {
      "created_by": "user_456"
    }
  }
]

Response Format

Returns an array of link objects directly, not wrapped in an object.

Remove Link

Remove a link between a KV pair and a document.

DELETE https://{EKODB_API_URL}/api/kv/{key}/links/{collection}/{record_id}
Authorization: Bearer {YOUR_API_TOKEN}

# Response
null

Response Format

Returns null on success. Check HTTP status code (200) to confirm the link was removed.

Complete Example

Here's a complete workflow using KV store for session management:

#!/bin/bash

# 1. Create session on login
session_id=$(uuidgen)
curl -X POST https://{EKODB_API_URL}/api/kv/set/session_$session_id \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "user_id": "user_123",
    "login_time": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
    "ip_address": "192.168.1.1"
  }'

# 2. Link session to user document
curl -X POST https://{EKODB_API_URL}/api/kv/session_$session_id/links/users/user_123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "metadata": {
      "session_type": "web",
      "device": "desktop"
    }
  }'

# 3. Get session data
curl -X GET https://{EKODB_API_URL}/api/kv/get/session_$session_id \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

# 4. Get all sessions for user (using find)
curl -X POST https://{EKODB_API_URL}/api/kv/find \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {YOUR_API_TOKEN}" \
  -d '{
    "prefix": "session_",
    "limit": 100
  }'

# 5. Cleanup session on logout
curl -X DELETE https://{EKODB_API_URL}/api/kv/delete/session_$session_id \
  -H "Authorization: Bearer {YOUR_API_TOKEN}"

Best Practices

Choose KV vs Documents

Use Case	Recommendation	Why
Simple key-value lookup	KV Store	Faster, simpler
Complex queries/filtering	Documents	Full query capabilities
Temporary data/cache	KV Store	Fast writes, auto-cleanup
Structured records	Documents	Schema validation, relationships
Session management	KV Store	Quick lookups, TTL support
User profiles	Documents	Complex queries, joins

Use Prefixes for Organization

# Group related keys with prefixes
POST /api/kv/set/cache:users:123
POST /api/kv/set/cache:posts:456
POST /api/kv/set/session:abc123
POST /api/kv/set/session:def456
POST /api/kv/set/config:feature_flags

Batch Operations for Efficiency

# Good: Batch get for multiple keys
POST /api/kv/batch/get
{"keys": ["session_1", "session_2", "session_3"]}

# Avoid: Multiple individual requests
GET /api/kv/get/session_1
GET /api/kv/get/session_2
GET /api/kv/get/session_3

Link KV to Documents

# Store analytics in KV, link to report document
POST /api/kv/set/analytics_2024_01
{"views": 1000, "clicks": 250}

POST /api/kv/analytics_2024_01/links/reports/report_123
{"metadata": {"period": "monthly"}}

# Query report to get linked analytics
GET /api/find/reports/report_123
# Then fetch linked KV data
GET /api/kv/analytics_2024_01/links

Use Cases

Caching API Responses

# Cache expensive query results
POST /api/kv/set/cache:trending_posts
{
  "posts": [...],
  "generated_at": "2024-01-15T10:30:00Z",
  "ttl": 300
}

# Retrieve cached data
GET /api/kv/get/cache:trending_posts

Feature Flags

# Store feature flags
POST /api/kv/set/feature_flags
{
  "new_dashboard": true,
  "beta_search": false,
  "experimental_ai": true
}

# Quick lookup
GET /api/kv/get/feature_flags

Rate Limiting Counters

# Increment API call counter
GET /api/kv/get/rate_limit:user_123
# {"count": 95, "reset_at": "2024-01-15T11:00:00Z"}

# Update counter
POST /api/kv/set/rate_limit:user_123
{"count": 96, "reset_at": "2024-01-15T11:00:00Z"}

Session Storage

# Store user session
POST /api/kv/set/session:abc123
{
  "user_id": "user_456",
  "roles": ["user", "premium"],
}

# Validate session
GET /api/kv/get/session:abc123

Basic Operations - Document CRUD operations
Batch Operations - Bulk document operations
Authentication - API key and JWT authentication

Example Code

Direct HTTP/REST API Examples

Raw HTTP examples demonstrating the REST API directly:

JavaScript - kv_operations.js
Python - kv_operations.py
Go - kv_operations.go
Rust - kv_operations.rs

Client Library Examples

Production-ready examples using official client libraries:

Rust - client_kv_operations.rs
Python - client_kv_operations.py
TypeScript - client_kv_operations.ts
Go - client_kv_operations.go
Kotlin - ClientKvOperations.kt
JavaScript - client_kv_operations.js

Get Value​

Set Value​

Delete Value​

Batch Get​

Batch Set​

Batch Delete​

Clear All​

Find Keys​

Linking KV to Documents​

Create Link​

Get Links​

Remove Link​

Complete Example​

Best Practices​

Choose KV vs Documents​

Use Prefixes for Organization​

Batch Operations for Efficiency​

Link KV to Documents​

Use Cases​

Caching API Responses​

Feature Flags​

Rate Limiting Counters​

Session Storage​

Related Documentation​

Example Code​

Direct HTTP/REST API Examples​

Client Library Examples​

Get Value

Set Value

Delete Value

Batch Get

Batch Set

Batch Delete

Clear All

Find Keys

Linking KV to Documents

Create Link

Get Links

Remove Link

Complete Example

Best Practices

Choose KV vs Documents

Use Prefixes for Organization

Batch Operations for Efficiency

Link KV to Documents

Use Cases

Caching API Responses

Feature Flags

Rate Limiting Counters

Session Storage

Related Documentation

Example Code

Direct HTTP/REST API Examples

Client Library Examples