Configuration

Everything is configured with environment variables passed to docker run. The defaults are chosen so the container works with no configuration at all; this chapter covers what is worth changing.

Storage and memory

Variable Default Purpose

CYROCK_DB_BOOTSTRAP_STORAGE_PATH

/data

Where storage and seed state live. Mount a volume here to persist across restarts.

JAVA_OPTS

(unset)

JVM options, most usefully the heap ceiling.

Three servers and the vector indices share one JVM in this image, so the heap matters more than it would for a single service:

docker run --rm --name cyrock-db -p 7280:7280 -v cyrock-db-data:/data \
  -e JAVA_OPTS="-Xmx6g" \
  cyrockai/db:1.0.0

Guidance: 3 GB is fine for exploring with sample data. Give it 6-8 GB before loading hundreds of thousands of vectors. HNSW indices are held in memory for search, so vector count and dimension drive the requirement more than document count does. Also raise Docker’s own memory limit - a -Xmx above what Docker will grant just moves the failure.

The peak is at startup, not under query load: an index whose graph is not on disk has to be rebuilt in memory from the stored vectors, and every collection does that at once. Stopping the container with a grace period long enough to finish - docker stop -t 90, see the operations chapter - is what keeps the graphs on disk and the next start cheap.

Vector index persistence

Defaults that a normal deployment should not need to change. They exist for the two cases that do: an ingest-heavy instance that wants the periodic consolidation out of the way, and a container whose stop grace period is too short for the default shutdown budget.

Variable Default Purpose

CYROCK_DB_DATA_VECTOR_INDEX_PERSISTENCE_INTERVAL_MS

600000

How often a vector index writes its graph in the background. 0 turns the background task off; the index is still written when the store opens and when it closes. Writing consolidates the whole graph, so a shorter interval is not free.

CYROCK_DB_DATA_VECTOR_INDEX_OPTIMIZATION_INTERVAL_MS

1800000

How often a vector index is optimized. 0 turns it off.

CYROCK_DB_DATA_VECTOR_INDEX_MIN_CHANGES_BETWEEN_PERSISTS

1

How many changes must accumulate before a background write runs. Raising it means a collection written once and then left alone never gets its index onto disk.

CYROCK_DB_DATA_VECTOR_INDEX_PERSIST_ON_SHUTDOWN

true

Whether closing an index writes its graph. Turning it off shortens a shutdown at the cost of losing that session’s index changes; the index is still written when a store opens, so a start does not rebuild from nothing.

CYROCK_DB_DATA_VECTOR_INDEX_OPTIMIZE_ON_SHUTDOWN

false

Whether closing an index optimizes it first. Off by default because it lengthens a shutdown that is already racing the stop grace period.

CYROCK_DB_DATA_VECTOR_INDEX_SHUTDOWN_PERSIST_TIMEOUT_MS

30000

How long closing a vector index may spend writing it before the write is stopped, so a slow write does not consume the whole shutdown. Counted per index, and a soft limit: the write stops at its next stage and commits nothing. Three writes are not limited at all: an index with every background task turned off, a quantized index whose quantizer is not trained yet, which a close persists explicitly so the quantizer gets trained once the index holds enough vectors and the data does not stay at full precision, and an index created while PERSIST_ON_SHUTDOWN was off, which keeps that setting and is written by the store instead. Stopping costs the next start a rebuild of that index, nothing more. Raising this only helps if the container waits too.

CYROCK_DB_DATA_VECTOR_INDEX_MIN_CHANGES_BETWEEN_OPTIMIZATIONS

1000

How many changes must accumulate before a background optimization runs.

CYROCK_DB_DATA_VECTOR_INDEX_PARALLEL_ON_DISK_WRITE

false

Whether writing a graph uses more than one thread. Off by default because for the vectors stored today the parallel writer measures marginally slower than the sequential one; it is worth turning on only once per-vector work grows.

CYROCK_DB_DATA_VECTOR_INDEX_FLUSH_THRESHOLD

100000

How many vectors an index collects in memory before writing them out as a new segment on disk. Lowering it saves little memory, since the stored vectors take most of it either way, and makes searches slower, since each search visits every segment. Raise it for a single very large collection to keep the segment count down.

The VECTOR_INDEX settings above apply to indices created while the setting is in force. A vector index remembers how it was configured, the write and optimize schedule included, and applying a new schedule to an existing one would mean rebuilding it, which is not worth it. Set them before you load data you intend to keep; changing one later takes effect for vector fields created after the change. One exception: turning PERSIST_ON_SHUTDOWN on also covers existing indices created while it was off - the store then writes them on close itself, outside the shutdown budget.

Embedding providers

Vector search needs embeddings. Either supply vectors yourself, or configure a provider and let the engine compute them on write.

In-process ONNX - no account, no network

The image enables this one by default, so vector search works out of the box: the embedding model runs inside the container, needing no API key, no provider account and no outbound network access at all. There is nothing to set to get it.

It takes precedence over every other embedding provider. That is what makes the default safe - but it also means configuring a provider of your own is not enough on its own. To be served by another provider, turn ONNX off in the same command:

docker run --rm --name cyrock-db -p 7280:7280 -v cyrock-db-data:/data \
  -e CYROCK_DB_EMBEDDING_ONNX_ENABLED=false \
  -e CYROCK_DB_EMBEDDING_OPENAI_API_KEY=sk-... \
  cyrockai/db:1.0.0

Leave ONNX on and set an OpenAI key, and ONNX still wins while the key is ignored - worth knowing before you spend an afternoon wondering which one produced a vector.

Hosted and self-hosted providers

Provider Enabled by Default model

OpenAI

CYROCK_DB_EMBEDDING_OPENAI_API_KEY

text-embedding-3-small

Gemini

CYROCK_DB_EMBEDDING_GEMINI_API_KEY

text-embedding-004

Ollama

CYROCK_DB_EMBEDDING_OLLAMA_MODEL

(no default - the model name is required)

Each also accepts …​_MODEL and …​_TIMEOUT. Providing the key - or, for Ollama, the model name - is what activates the provider; there is no separate enable flag.

For Ollama, set CYROCK_DB_EMBEDDING_OLLAMA_BASE_URL to your Ollama host. Inside a container localhost means the container itself, so reach an Ollama on your own machine as http://host.docker.internal:11434.

Embedding dimensions must match the vector field’s declared dimensions. The in-process ONNX model is fixed at 384. Changing provider or model usually changes the dimension, which means re-embedding rather than just reconfiguring.

Language model providers

Natural-language search and the console’s schema wizards use a language model. All are optional; the engine works without one, you simply write CyQL yourself.

Provider Variables

Anthropic

CYROCK_DB_INFERENCE_LLM_ANTHROPIC_API_KEY, …​_MODEL, …​_TEMPERATURE, …​_TIMEOUT

OpenAI

CYROCK_DB_INFERENCE_LLM_OPENAI_API_KEY, …​_MODEL, …​_TEMPERATURE, …​_TIMEOUT

Gemini

CYROCK_DB_INFERENCE_LLM_GEMINI_API_KEY, …​_MODEL, …​_TEMPERATURE, …​_TIMEOUT

Ollama

CYROCK_DB_INFERENCE_LLM_OLLAMA_MODEL, …​_BASE_URL, …​_TEMPERATURE, …​_TIMEOUT

TEMPERATURE takes 0 to 1 and defaults to 0.7; TIMEOUT is in seconds and defaults to 60. For query translation, a low temperature is the better choice - you want the same question to produce the same query.

Reranking

A reranker re-scores an initial result set with a model that reads query and document together. It is more accurate than vector similarity alone and slower, so it suits a final pass over a shortlist.

Provider Enabled by Default model

Cohere

CYROCK_DB_RERANK_COHERE_API_KEY

rerank-v3.5

CYROCK_DB_RERANK_COHERE_MODEL and CYROCK_DB_RERANK_COHERE_TIMEOUT are also accepted.

Loading CSV

LOAD CSV reads only from one configured import directory, and filenames in a query are resolved relative to it. Absolute paths, .. and symlinks that escape the directory are all rejected, so a query cannot be used to read arbitrary files from the host.

Variable Default Purpose

CYROCK_DB_DATA_IMPORT_PATH

./storage/import

The one directory LOAD CSV reads from. Must not be blank.

CYROCK_DB_DATA_IMPORT_BATCH_SIZE

5000

Rows an import reads and keeps in memory at a time, and commits per transaction.

docker run --rm --name cyrock-db -p 7280:7280 \
  -v cyrock-db-data:/data \
  -v "$PWD/imports:/imports:ro" \
  -e CYROCK_DB_DATA_IMPORT_PATH=/imports \
  cyrockai/db:1.0.0

A file at imports/movies.csv on your machine is then referred to as just movies.csv:

LOAD CSV WITH HEADERS FROM 'movies.csv' AS row
MERGE (m:Movie {title: row.title})

Mounting the directory read-only is a good habit - the engine only ever needs to read it.

Telemetry

Variable Purpose

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP collector endpoint for distributed traces.

Prometheus metrics need no configuration - see Operations.

Authentication

The evaluation image seeds three in-memory logins, which is why it is not a production topology. A general-availability deployment authenticates against your identity provider over OIDC instead. Those variables are documented with the deployment topology they belong to, which arrives at general availability.

Putting it together

A configuration worth keeping for real evaluation work - offline embeddings, a sensible heap, a persistent volume and an import directory:

docker run -d --name cyrock-db \
  -p 7280:7280 -p 7281:7281 -p 7282:7282 -p 7285:7285 -p 7290:7290 \
  -v cyrock-db-data:/data \
  -v "$PWD/imports:/imports:ro" \
  -e JAVA_OPTS="-Xmx6g" \
  -e CYROCK_DB_DATA_IMPORT_PATH=/imports \
  cyrockai/db:1.0.0

That needs no external service and no provider account - embeddings are in-process by default, so there is no provider line to add.