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 |
|---|---|---|
|
|
Where storage and seed state live. Mount a volume here to persist across restarts. |
|
(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 |
|---|---|---|
|
|
How often a vector index writes its graph in the background. |
|
|
How often a vector index is optimized. |
|
|
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. |
|
|
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. |
|
|
Whether closing an index optimizes it first. Off by default because it lengthens a shutdown that is already racing the stop grace period. |
|
|
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 |
|
|
How many changes must accumulate before a background optimization runs. |
|
|
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. |
|
|
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 |
|
|
Gemini |
|
|
Ollama |
|
(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 |
|
OpenAI |
|
Gemini |
|
Ollama |
|
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_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 |
|---|---|---|
|
|
The one directory |
|
|
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 |
|---|---|
|
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.