Operations

Index CRD

An Index represents one namespace exposed through the gateway. It declares which upstream namespace to use, snapshot policy, cache posture, and consistency mode. The backend connection itself lives in a VectorStore.

apiVersion: hevlayer.com/v1
kind: Index
metadata:
  name: products
  namespace: layer
spec:
  backend:
    storeRef: turbopuffer-default
    namespace: products
    distanceMetric: cosine_distance
  embedding:
    model: voyage-3-large@v1
    outputDim: 1024
    normalization: l2
  metadata:
    labels:
      app: shop
    tags:
      - catalog
  snapshot:
    interval: 5m
    retention: never
    facetFields:
      - category
      - brand
  search:
    fullText: true
  scan:
    threads: 8
  cache:
    ttl: 24h
    capGiB: 64
    mode: standard
  consistency: strong

Backend

Field	Purpose
`backend.storeRef`	Optional `VectorStore` name in the same namespace. The gateway routes requests for this upstream namespace to that store. Defaults to the namespace’s default store.
`backend.namespace`	Optional upstream namespace override. Defaults to the Index name.
`backend.distanceMetric`	Vector metric, default `cosine_distance`.

For kind: search stores, the operator accepts only the metrics the backend serves directly today: L2-style metrics for single-vector namespaces and cosine_distance for multivector namespaces. Unsupported values put the Index in Ready=False with reason MetricMismatch.

Embedding

spec.embedding declares the embedding identity of this namespace’s vectors. It is optional for a single-namespace query, where distances are only ever compared within the namespace. It is required to include a namespace in a federated vector query: the gateway merges those by distance, which is only meaningful when every namespace in the set shares one embedding space.

Field	Purpose
`embedding.model`	Model identity and version, e.g. `voyage-3-large@v1`. Treated as an opaque token compared for equality across a namespace set.
`embedding.outputDim`	Vector dimensionality. Part of the identity because a model truncated to a smaller dimension (Matryoshka) is not comparable to its full-width output. Cross-checked against the namespace schema.
`embedding.normalization`	Vector normalization, e.g. `l2` or `none`.

Together with backend.distanceMetric, these form the embedding profile the gateway compares across a fan-out. Two namespaces are distance-comparable only when all four match; otherwise a fused vector query over them falls back to rank-interleave (or is rejected under strict).

Snapshot policy

Field	Default	Purpose
`snapshot.facetFields`	`[]`	Fields the gateway materializes into durable facet snapshots. Empty disables the automatic writer.
`snapshot.interval`	`5m`	Minimum spacing between automatic snapshot writes after upstream-stable advances.
`snapshot.retention`	`never`	`never` keeps all snapshot bodies; a duration such as `30d` prunes older bodies while keeping the latest.

Search backend policy

spec.search applies when the Index targets a kind: search VectorStore. The operator uses it to drive the backend’s explicit index lifecycle.

Field	Default	Purpose
`search.fullText`	`false`	Build the backend’s BM25 index for the namespace’s `text` column. Enable this for lexical, FTS, or hybrid-text namespaces.

Scan policy

scan.threads sets the per-namespace default for origin scan fan-out: the maximum concurrent upstream requests one scan may issue during scatter/gather. It defaults to 8 and is clamped by the gateway’s server cap and the active shard count. Request-level threads overrides this default for one scan.

Cache policy

Aerospike remains an ephemeral cache; durable snapshot history stays in S3. Cache warming uses the same scan fan-out policy as other origin scans.

Status

The operator reports observed generation, metadata sync state, and conditions. status.snapshot.lastRun and lastSuccess are reserved for the gateway history bridge.