Records and multi-vector

A record is one vector plus named extra representations. The one vector (the primary, a plain dense embedding) is what is indexed and searched, exactly like any vector written with POST /v1/namespaces/{ns}/vectors. The extras sit beside it and are stored, replicated, backed up and deleted with it: per-token vectors for late interaction (a token multivector), per-patch vectors for a page image (a patch multivector), or another dense vector. Use records when you compute multi-vector embeddings yourself and want Dakera to keep them with the document. Memories written by the server under late interaction, and image pages indexed through the multimodal lane, are records of the same shape.

The routes are off by default (DAKERA_RECORDS): with the switch off both answer 501 FEATURE_DISABLED before touching any state, and no other route changes.

Configuration

One structural limit is compiled in and has no variable: at most 8 extra representations per record (the primary is not counted). GET /v1/capabilities reports records.enabled, records.representation_kinds, records.dtypes, records.max_representations, records.max_vectors and records.max_bytes; with the routes off it still reports what they would accept once enabled.

Write records

POST /v1/namespaces/{ns}/records (write scope). The namespace is created if it does not exist.

curl -s -X POST localhost:3000/v1/namespaces/docs/records \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"records": [{
        "id": "r1",
        "values": [0.5, 0.25, 0.25, 0.5],
        "representations": [{
          "name": "tokens",
          "kind": "token_multivector",
          "vectors": [[0.5, -0.25], [0.125, 1.0]],
          "store_as": "f16"
        }],
        "metadata": {"source": "demo"}
      }]}'
# 200 {"upserted_count": 1}

Request body: {"records": [ … ]}, between 1 and 10,000 records.

Response: {"upserted_count": N}. A record is one vector with extras, so the count is of records and of vectors alike. An upsert replaces the whole record: rewriting a record without representations removes the extras it had.

Representation kinds

Storage types (store_as)

The wire format is always plain nested float arrays; store_as only chooses how the server packs the block.

The payload of a representation is dim x count x bytes per value; it is what bytes reports and what counts against DAKERA_RECORD_MAX_BYTES. For example 128-wide token vectors stored as f16 take 256 bytes each, so 4,096 of them (the vector limit) are 1 MiB; 1024-wide vectors as f32 take 4 KiB each, so the 8 MiB byte limit is reached at 2,048 of them.

Late-interaction slots

Two slot names have a meaning to the engine. They are the slots a memory written by the server carries, so a record written through this route is searched exactly like one:

Under DAKERA_SCORING_STRATEGY=late-interaction the server derives the .fde slot from your colbert (kind token_multivector) or patch (kind patch_multivector) slot when it stores the record, from rows normalized to unit length for the encoding only (your stored rows are not changed). Sending an .fde slot yourself is 400 in every configuration, because only the server's encoder produces one the first stage can search. A record written while the strategy was single-vector has no .fde slot and is reached through its primary vector until it is written again. See Search and ranking for the scoring strategy.

Read a record

GET /v1/namespaces/{ns}/records/{id} (read scope).

curl -s localhost:3000/v1/namespaces/docs/records/r1 -H "Authorization: Bearer $KEY"
# {"id": "r1",
#  "dimension": 4,
#  "representations": [{"name": "tokens", "kind": "token_multivector",
#                       "dim": 2, "count": 2, "dtype": "f16", "bytes": 8}],
#  "metadata": {"source": "demo"}}

curl -s "localhost:3000/v1/namespaces/docs/records/r1?include_vectors=true" -H "Authorization: Bearer $KEY"
# {"id": "r1", "values": [0.5, 0.25, 0.25, 0.5], "dimension": 4,
#  "representations": [{"name": "tokens", "kind": "token_multivector", "dim": 2, "count": 2,
#                       "dtype": "f16", "bytes": 8, "vectors": [[0.5, -0.25], [0.125, 1.0]]}],
#  "metadata": {"source": "demo"}}

By default a read returns a manifest: the primary's dimension and, per extra representation, its name, kind, model (omitted when empty), dim, count, dtype and packed bytes. A token block is 20 to 100 times the size of the dense vector beside it and most reads only want to know what a record has, so the payloads (values and each representation's vectors, decoded back to floats) come only with include_vectors=true. Fields that are empty are omitted: a plain dense record has no representations, and ttl_seconds and expires_at appear only on a record that expires. unsupported_representations (a count) appears when the record holds slots written by a newer Dakera with a kind or dtype this binary cannot read; they are skipped, never served and never deleted.

A sidecar that no longer matches its primary (the memory's content was updated, the vector was re-embedded, or the id was rewritten through the plain vector route) is stale and is not served: the record reads back as the dense record it also is. The next TTL sweep removes it.

An unknown record is 404 (VECTOR_NOT_FOUND, the v0.11 code kept).

Delete a record

There is deliberately no record delete route. Delete the id through the vector routes, which are document level: the extras go with the primary.

curl -s -X POST localhost:3000/v1/namespaces/docs/vectors/delete \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"ids": ["r1"]}'
# {"deleted_count": 1}

Atomicity and storage

The extras are kept as a sidecar value next to the primary on every backend. RocksDB writes both in one batch (atomic); the object store writes the sidecar first and the primary second, with the primary as the commit point, so a reader never sees extras without their primary. The sidecar is bound to the exact primary vector it was written with, which is why a rewrite of the primary orphans it rather than serving mismatched vectors. Snapshots, export/import (JSONL carries the representations; CSV is dense only), backups and cluster replication carry records whole, so a peer never keeps only the dense half of a record. Records go through the same write path as vectors, so namespace quotas (max_storage_bytes counts the extras' bytes; an overwrite releases the old extras), ANN invalidation and the cluster broadcast apply unchanged. WAL, caches and tiered storage forward records, and the tiered flush carries the sidecar.

v0.11.108 does not know the extras: after dakera downgrade it serves a record as its dense vector and the sidecars are left in place for a later upgrade.

Errors

The message names the record and slot: records[0] (id 'r1'): representation 'tokens': rows differ in length: expected 2, found 1. A well-formed record that is too large is 413; anything malformed is 400.

Verify it works

1. curl -s localhost:3000/v1/capabilities -H "Authorization: Bearer $KEY" | jq .records shows "enabled": true and the limits in force.
2. Write the example record above and read it back: the manifest shows dtype: "f16" and bytes: 8.
3. Read it with include_vectors=true and compare the rows (exactly representable values come back unchanged; others come back rounded to the chosen type).
4. Write it again without representations and read it: the extras are gone.
5. Delete it with POST …/vectors/delete and read it: 404.