Skip to main content

Configuration

Configure your ekoDB instance at runtime using the REST API. All configuration changes take effect immediately without requiring a restart.

Admin Access Required

Configuration endpoints require admin permissions.

API Endpoints​

Get Configuration​

Retrieve the current configuration:

GET /api/config
Authorization: Bearer {ADMIN_TOKEN}

Update Configuration​

Update one or more configuration options. Only the fields you include in the request body will be changed — all other settings remain unchanged.

PUT /api/config
Content-Type: application/json
Authorization: Bearer {ADMIN_TOKEN}

{
  "use_typed_values": false,
  "storage_mode": "balanced",
  "durable_operations": true
}

Response:

{
  "status": "success",
  "message": "Configuration updated successfully"
}

Core Settings​

OptionTypeDefaultRangeDescription
use_typed_valuesBooleantrue—When true, responses include type metadata (e.g., {"type": "String", "value": "Alice"}). When false, returns plain values.
default_ttlInteger36000–604800Default time-to-live for new records in seconds. 0 disables expiration. Max 7 days (604,800 seconds).
token_expiry_hoursInteger11–168JWT token lifetime in hours. Max 7 days (168 hours).
encrypt_idsBooleantrue—Encrypt record IDs with AES-GCM. Disable only for testing/benchmarks.
access_modeString"read_write""read", "write", "read_write"Node access permissions. Use "read" for read replicas, "write" for write-only nodes.

Example — Configure a read-only replica:

{
  "access_mode": "read",
  "token_expiry_hours": 24
}

Storage & Durability​

Storage Mode​

OptionTypeDefaultValuesDescription
storage_modeString"fast""fast", "balanced", "cold"Record persistence strategy.
ModeDescriptionBest For
fastIn-memory primary with WAL-only persistenceLow-latency reads (default)
balancedLRU cache with periodic checkpoint batching to diskGeneral-purpose workloads
coldIndex-only memory with chunked append storageWrite-heavy ingestion, logging

Durability & WAL​

OptionTypeDefaultRangeDescription
durable_operationsBooleantrue—When true, writes are fsynced to disk before responding. When false, writes are buffered and fsynced in the background for higher throughput.
group_commitsBooleantrue—Batch concurrent writes together with a single fsync. Dramatically improves throughput under concurrent load while maintaining durability.
group_commit_delay_msInteger20–100Batching window in milliseconds for group commits. Lower = lower latency, higher = more batching throughput.
group_commit_modeString"channel""leader_election", "channel"Group commit strategy. "leader_election" provides highest throughput. "channel" provides simpler error handling.
wal_shardsInteger41–16Number of parallel WAL shards for concurrent fsync. More shards = higher write throughput under concurrent load.

Example — Maximum write throughput:

{
  "durable_operations": true,
  "group_commits": true,
  "group_commit_delay_ms": 5,
  "group_commit_mode": "leader_election",
  "wal_shards": 8
}

Example — Low-latency single-writer:

{
  "durable_operations": true,
  "group_commits": false
}
Disabling Durability

Setting durable_operations to false means data written within the last flush window (typically 0–1 second) may be lost on crash. Only disable for non-critical data like analytics or bulk ingestion.

Resource Allocation​

OptionTypeDefaultRangeDescription
memory_allocation_percentInteger501–80Percentage of system RAM to use for database caching.
cpu_utilization_percentInteger10010–100Percentage of CPU cores to use for concurrent operations.

Guidelines:

ScenarioMemoryCPU
Dedicated database server50–70%100%
Shared server with other services25–40%50%
Background/minimal service10–20%25%

Example — Shared server configuration:

{
  "memory_allocation_percent": 30,
  "cpu_utilization_percent": 50
}

LLM Providers​

Configure LLM providers for Chat/RAG functionality. You can configure multiple providers and select which to use per chat session.

OpenAI​

OptionTypeDefaultDescription
openai_api_keyString—API key for OpenAI. Required to use OpenAI models.
openai_api_urlString"https://api.openai.com"Custom API URL for OpenAI-compatible APIs (e.g., LM Studio, Ollama).
openai_default_modelString—Default model for OpenAI chat sessions (e.g., "gpt-4", "gpt-4o").

Anthropic​

OptionTypeDefaultDescription
anthropic_api_keyString—API key for Anthropic. Required to use Anthropic models.
anthropic_api_urlString—Custom API URL for Anthropic.
anthropic_default_modelString—Default model (e.g., "claude-sonnet-4-5-20250929").
anthropic_default_versionString—Anthropic API version string.

Perplexity​

OptionTypeDefaultDescription
perplexity_api_keyString—API key for Perplexity. Required to use Perplexity models.
perplexity_api_urlString—Custom API URL for Perplexity.
perplexity_default_modelString—Default model for Perplexity chat sessions.

Example — Configure OpenAI with a local LM Studio endpoint:

{
  "openai_api_key": "lm-studio",
  "openai_api_url": "http://localhost:1234",
  "openai_default_model": "llama-3.1-8b"
}

Example — Configure multiple providers:

{
  "openai_api_key": "sk-...",
  "openai_default_model": "gpt-4o",
  "anthropic_api_key": "sk-ant-...",
  "anthropic_default_model": "claude-sonnet-4-5-20250929"
}

Chat Settings​

Fine-tune chat/RAG behavior for each LLM provider. See Chat & RAG for usage.

General Chat Settings​

OptionTypeDefaultDescription
chat_max_context_snippetsInteger5Maximum number of context snippets returned from search results for each chat query.
chat_max_tokensInteger4096Maximum number of tokens for LLM responses.
chat_max_merged_messagesInteger10000Maximum messages to merge when loading chat history.

Provider Temperature & Sampling​

Control the creativity and determinism of LLM responses per provider.

OptionTypeDefaultRangeDescription
chat_openai_temperatureFloat0.70.0–2.0OpenAI response temperature. Lower = more focused.
chat_openai_top_pFloat1.00.0–1.0OpenAI nucleus sampling.
chat_anthropic_temperatureFloat1.00.0–1.0Anthropic response temperature.
chat_anthropic_top_pFloat0.990.0–1.0Anthropic nucleus sampling.
chat_perplexity_temperatureFloat0.20.0–2.0Perplexity response temperature.
chat_perplexity_top_pFloat0.90.0–1.0Perplexity nucleus sampling.

These settings control how chat queries use collection schemas to improve search results.

OptionTypeDefaultDescription
chat_schema_search_min_resultsInteger3Minimum text search results before triggering schema-based field matching.
chat_schema_search_min_word_lengthInteger3Minimum word length for query terms to be used in schema field matching.
chat_schema_field_match_scoreFloat0.5Score added when a query term matches a schema field name.
chat_field_name_boost_multiplierFloat0.3Score boost multiplier for results with matching field names.
chat_schema_sample_recordsInteger1Number of sample records to fetch when schema field names match the query.

Custom Collection Names​

Override the default collection names used by the chat system.

OptionTypeDefaultDescription
chat_configurations_collectionString"chat_configurations_{db_name}"Collection for storing chat session configurations.
chat_messages_collectionString"chat_messages_{db_name}"Collection for storing chat messages.

Write Performance Tuning​

Control which features run inline (synchronous) versus in the background during insert and update operations. Setting features to false defers them to background tasks for maximum write throughput.

Insert Features​

OptionTypeDefaultDescription
insert_features.search_indexBooleantrueUpdate text/vector search indexes inline during insert. When false, search indexes update asynchronously.
insert_features.query_indexBooleantrueUpdate query indexes inline during insert. When false, query indexes update asynchronously.
insert_features.constraintsBooleantrueRun schema constraint validation (unique, required, enum, min, max, regex) during insert. When false, constraints are skipped entirely.
insert_features.disk_cacheBooleantrueWrite to disk cache inline during insert. When false, disk cache writes are deferred (WAL still provides durability).

Update Features​

OptionTypeDefaultDescription
update_features.search_indexBooleantrueUpdate text/vector search indexes inline during update.
update_features.query_indexBooleantrueUpdate query indexes inline during update.
update_features.constraintsBooleantrueRun schema constraint validation during update.
update_features.disk_cacheBooleantrueWrite to disk cache inline during update.

Example — Maximum insert throughput (defer everything):

{
  "insert_features": {
    "search_index": false,
    "query_index": false,
    "constraints": false,
    "disk_cache": false
  }
}

Example — Fast inserts with constraints still enforced:

{
  "insert_features": {
    "search_index": false,
    "query_index": false,
    "constraints": true,
    "disk_cache": false
  }
}
When to Defer Features
  • Bulk ingestion: Defer all features for maximum throughput, then rebuild indexes after
  • No constraints needed: Skip constraints if the collection has no unique/required fields
  • Search not critical: Defer search indexing if real-time search isn't required

Rate Limiting​

Configure rate limiting for public (unauthenticated) endpoints.

OptionTypeDefaultRangeDescription
public_endpoint_rate_limit_enabledBooleantrue—Enable rate limiting on public endpoints (/api/health, /api/auth/register, /api/auth/token).
public_endpoint_rate_limit_per_minuteInteger6010–300Maximum requests per IP per minute for public endpoints.
Authenticated Rate Limits

Rate limits for authenticated API endpoints are determined by your deployment tier. See Security - Rate Limiting for tier details.

Functions​

OptionTypeDefaultDescription
functions_collectionString"functions_{db_name}"Collection name for storing scheduled functions.
environment_varsObject{}Key-value pairs accessible in functions via {{env.VAR_NAME}} syntax.

Example — Set function environment variables:

{
  "environment_vars": {
    "WEBHOOK_URL": "https://api.example.com/webhook",
    "AUTH_TOKEN": "token123"
  }
}

Maintenance​

OptionTypeDefaultDescription
disable_maintenanceBooleanfalseDisable periodic background maintenance tasks (cache cleanup, compaction). Only disable for benchmarking.

Full Configuration Example​

Here's an example configuring a production instance with multiple LLM providers, tuned durability, and resource limits:

curl -X PUT https://{EKODB_API_URL}/api/config \
  -H "Authorization: Bearer {ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "use_typed_values": true,
    "token_expiry_hours": 1,
    "default_ttl": 3600,
    "storage_mode": "fast",
    "durable_operations": true,
    "group_commits": true,
    "group_commit_delay_ms": 2,
    "wal_shards": 4,
    "memory_allocation_percent": 50,
    "cpu_utilization_percent": 100,
    "openai_api_key": "sk-...",
    "openai_default_model": "gpt-4o",
    "chat_max_context_snippets": 5,
    "chat_max_tokens": 4096,
    "public_endpoint_rate_limit_enabled": true,
    "public_endpoint_rate_limit_per_minute": 60,
    "insert_features": {
      "search_index": true,
      "query_index": true,
      "constraints": true,
      "disk_cache": true
    }
  }'