Transactions, durability, and snapshots
ShrikeDB coordinates graph, vector, key-value, and geospatial writes through transaction RPCs and publishes durable database snapshots for readers. Use a transaction when several modality writes represent one application change.
Transaction workflow
A client begins a transaction, sends supported transaction-scoped writes, and then commits or rolls back. Keep the transaction ID returned by the begin call and pass it to each subsequent request.
| Step | Application responsibility |
|---|---|
Begin |
Select the intended database and retain the transaction identifier. |
Write |
Send |
Commit |
Treat the change as accepted only after a successful commit response. |
Rollback |
Discard the transaction when application validation or a write fails. |
Do not expose an application success response before the database acknowledges commit. A network timeout leaves the outcome uncertain; resolve it using the request or transaction identity exposed by the deployment rather than blindly issuing a second logical change.
Publication and query visibility
Commit makes a new database version eligible for publication. Readers pin a published snapshot for the duration of a query. A request that begins before a later publication continues with its pinned view; a new request can observe the new version.
Named indexes and structural summaries carry their own version or readiness state. The query planner binds the facts required by the selected plan to the database and snapshot. A learned estimate or stale statistic never substitutes for a required semantic fact.
Cross-modal writes
Use the same entity UID when one logical record has graph, vector, KV, and geospatial representations. A typical create workflow is:
-
allocate or derive the stable UID;
-
insert the graph node and relationships;
-
insert the embedding into the named vector index;
-
store the document or application payload under the corresponding KV key;
-
append timestamped positions to a named geospatial index when the entity has observations;
-
commit the supported writes together.
If a loader intentionally uses separate commits, record which modalities are ready and prevent queries from assuming the entire entity is present until the workflow finishes.
Geospatial observations remain explicit writes: graph properties do not automatically create index entries, and observations do not automatically mutate graph nodes. TransactionInsertSpaceKey lets the application place both writes under one commit. Queries acquire their multimodal snapshot while commit publication is gated, so they cannot observe only one side of a graph-plus-geospatial commit.
Durable storage
The data directory contains the WAL, segments, indexes, manifests, catalogs, and recovery metadata. Place the complete directory on persistent storage. Copying selected index files does not form a database backup.
Use the normal shutdown path so background vector and index work can quiesce and persist its current state. Backup and restore procedures are documented in Back up and restore a standalone database.
Shared WAL synchronization
The WAL can make several independent transaction records durable with one storage flush. Each transaction keeps its own identity and recovery receipt. Applications continue to use the normal begin, write, and commit workflow; a shared flush does not create a shared rollback boundary between their transactions.
Bounded grouping is available in the native storage replay path. Public HA request batching requires separate integration. Size application batches around the changes that must succeed together, rather than assuming a particular number of client requests will share a flush.
Once grouped storage commit starts its owned durability work, a disconnected caller does not cancel that work. Graceful shutdown waits for it to finish. After an unexpected interruption, recovery uses individual durable records and receipts to determine what completed. See HA durability and recovery for replication and retry behavior.
Read consistency in applications
One Cypher or SPARQL request receives a coherent query view. A workflow made from several direct RPCs can cross publication boundaries unless it carries a supported snapshot version or uses a higher-level query that composes the operations.
Prefer a single Cypher query for vector-to-graph-to-KV retrieval when coherent composition matters. Use explicit snapshot fields for low-level APIs that expose them, and record snapshot identifiers in reproducibility-sensitive jobs.
Failure handling
| Failure | Response |
|---|---|
Write rejected before commit |
Correct the request or roll back; no successful commit was reported. |
Client loses connection during commit |
Resolve the transaction outcome before retrying the logical operation. |
Server restarts |
Wait for readiness and recovery health before resuming traffic. |
Recovered vector namespace is empty |
Verify the data directory, database/schema scope, index name, and vector namespace report. |
A query cannot use an index immediately |
Inspect readiness and fallback diagnostics; durable presence and a particular optimized index state are distinct conditions. |
For HA deployments, commit acknowledgement depends on the configured replication and quorum mode for the covered write path. Follow HA deployment status and configuration for supported operations, recovery, and deployment checks.