Value Type Reference — StrataDB Docs

Docs menu · Reference

Interim page. Maintained by hand until it is generated from the resolved command index (IDL). Where this page and strata agents commands --json disagree, the command index wins.

Strata has five capabilities — kv, json, event, vector, and graph — over one branch-aware versioned store. This page shows what each one accepts and returns, verified by writing and reading each value. For the conceptual model see Primitives and Value Types.

Every write returns a commit receipt (version, timestamp, put/delete counts, durable, and an effect); reads return the value plus its version and timestamp. The version/timestamp pair is a logical commit clock, distinct from any wall-clock time stored inside a value.

KV — opaque bytes

KV values are opaque byte strings. Text from the CLI is stored as its UTF-8 bytes; arbitrary bytes come from a file (--file or @path).

$ strata --db ./db kv put greeting "hello world"
created greeting applied=true

$ strata --db ./db kv get greeting          # plain: UTF-8 decoded
hello world

$ strata --db ./db --json kv get greeting   # --json: value is base64
{"data":{"timestamp":3,"value":"aGVsbG8gd29ybGQ=","version":3},"type":"kv_versioned_value"}

Binary values round-trip byte-for-byte:

$ strata --db ./db kv put blob --file ./payload.bin
created blob applied=true

$ strata --db ./db --json kv get blob
{"data":{"timestamp":4,"value":"AAEC/2Jpbg==","version":4},"type":"kv_versioned_value"}

Rules of thumb:

Under --json, both the key and the value are base64 (they are bytes on the wire).
Plain and --raw output decode UTF-8 for display; non-text bytes are best read via --json and decoded by the caller.
A read of a missing key returns {"data":null,...} with exit 0 — absence is not an error.

JSON — documents addressed by path

JSON values are real JSON documents. Paths use $ for the whole document and $.field for a member. Writing $ replaces the document; a subpath read returns just that value.

$ strata --db ./db json set user:1 '$' '{"name":"Ada","age":36,"tags":["a","b"]}'
created user:1 applied=true

$ strata --db ./db json get user:1 '$'
{"age":36,"name":"Ada","tags":["a","b"]}

$ strata --db ./db --json json get user:1 '$.name'
{"data":{"found":true,"value":{"document_version":1,"timestamp":3,"value":"Ada","version":3}},"type":"json_versioned_value"}

Documents carry a document_version (per-document revision) alongside the commit version/timestamp. Values may be any JSON type: object, array, string, number, boolean, or null. Non-JSON text passed to json set is stored as a JSON string.

Event — immutable, hash-chained log

Events are append-only. Each event has a string event_type, a JSON payload, a dense sequence starting at 0, a microsecond wall-clock timestamp, and a SHA-256 hash chained to the previous_hash of the prior event.

$ strata --db ./db event append user.created '{"id":1,"email":"a@b.co"}'
created applied=true

$ strata --db ./db --json event list

{"data":{"items":[
  {"event":{"event_type":"user.created","sequence":0,
    "payload":{"email":"a@b.co","id":1},
    "hash":"1d2616c3…","previous_hash":"0000000000…",
    "timestamp":1783735353572894},
   "version":3,"timestamp":3},
  {"event":{"event_type":"user.updated","sequence":1,
    "payload":{"id":1},
    "hash":"f331b047…","previous_hash":"1d2616c3…",
    "timestamp":1783735353581986},
   "version":4,"timestamp":4}
],"has_more":false,"cursor":null},"type":"event_records"}

The genesis previous_hash is all zeros. Sequences are contiguous; strata event verify-chain checks density and hash linkage. Note the two clocks: the event’s own timestamp is microsecond wall-clock; the outer version/timestamp is the logical commit clock.

Vector — embeddings with a metric

A collection fixes a dimension and a distance metric. Metrics accepted at create time:

Metric	Value
Cosine similarity (default)	`cosine`
Euclidean	`euclidean`
Dot product	`dot-product`

Vector components are 32-bit floats — values are stored and returned at f32 precision (note the rounding below). Each vector may carry a metadata object.

$ strata --db ./db vector collection create docs 4
{"count":0,"dimension":4,"metric":"cosine","name":"docs"}

$ strata --db ./db vector upsert docs a '[0.1,0.2,0.3,0.4]' --metadata '{"kind":"note"}'
created a applied=true

$ strata --db ./db --json vector get docs a
{"data":{"data":{"embedding":[0.10000000149011612,0.20000000298023224,0.30000001192092896,0.4000000059604645],
  "metadata":{"kind":"note"}},"key":"a","vector_revision":1,"timestamp":5,"version":5},"type":"vector_data"}

$ strata --db ./db --json vector query docs '[0.1,0.2,0.3,0.4]' --k 3
{"data":[{"key":"a","metadata":{"kind":"note"},"score":1.0}],"type":"vector_matches"}

Components can be a JSON array, comma-separated floats, or @path. A dimension mismatch is rejected:

$ strata --db ./db --json vector upsert docs b '[1,2]'
{"error":{"class":"invalid_argument","code":"invalid_argument.engine.vector_dimension",
  "message":"vector dimension mismatch: expected 4, got 2", …}}

The collection create surface exposes dimension and metric only; there is no per-collection storage-dtype selection on the CLI in this release.

Search filters are explicit and AND-composed, and only equality is supported. Each condition names a field, the op eq, and an adjacently-tagged scalar value (tag string, number, or bool):

$ strata --db ./db --json vector query docs '[0.1,0.9]' \
    --filter '{"conditions":[{"field":"lang","op":"eq","value":{"type":"string","value":"en"}}]}'
{"data":[{"key":"a","metadata":{"lang":"en"},"score":1.0}],"type":"vector_matches"}

A bare {"lang":"en"} is rejected (missing field conditions), and any op other than eq is rejected (unknown variant …, expected eq).

Graph — nodes and typed edges

A graph holds nodes (an id plus an optional properties object) and edges (a source, an edge_type, a destination, an optional weight, and optional properties).

$ strata --db ./db graph create deps
$ strata --db ./db graph add-node deps core --properties '{"lang":"rust"}'
$ strata --db ./db graph add-node deps cli
$ strata --db ./db graph add-edge deps cli depends_on core --weight 2.5

$ strata --db ./db --json graph get-node deps core
{"data":{"graph":"deps","node_id":"core","properties":{"lang":"rust"},"version":4,"timestamp":4},"type":"graph_node_result"}

$ strata --db ./db --json graph get-edge deps cli depends_on core
{"data":{"graph":"deps","src":"cli","edge_type":"depends_on","dst":"core","weight":2.5,"version":6,"timestamp":6},"type":"graph_edge_result"}

graph neighbors walks a node’s edges with direction outgoing (default), incoming, or both, and returns each neighbor’s edge and node together. Edge weight is optional; omit it for an unweighted edge.

Write receipts

Every mutating command returns the same receipt shape. A representative write under --json:

{"data":{
  "commit":{"version":3,"timestamp":3,"put_count":1,"delete_count":0,"durable":false},
  "effect":{"applied":true,"kind":"created","matched":false,"affected_count":1},
  "key":"Z3JlZXRpbmc="
},"type":"write_result"}

durable reflects whether the commit reached disk (false in cache mode). effect.kind reports created, updated, or deleted; applied says whether the write changed anything.