Overview

Concepts

Wire protocol matching

Layer accepts the Turbopuffer HTTP wire protocol, so an application can point its Turbopuffer client at Layer’s base URL and keep the same request bodies. With Turbopuffer as the store, Layer forwards native requests after gateway validation. With another store, Layer translates supported operations into that store’s native calls, and a valid request the store cannot serve returns 422 UnsupportedByStore instead of silently dropping part of it. The capability matrix lists what each store supports and how we validate it. See the API reference for authentication and client setup.

Gateway enhancements

Layer adds retrieval operations around the store while keeping one client endpoint. Hybrid text fusion combines retrieval legs, query routing selects a strategy, scans select or count matching rows, and federated queries combine named namespaces. The API reference calls out each backend’s limits at the relevant feature.

The Layer clients expose these additions; plain HTTP can call the same API. Native requests and enhanced requests can share the gateway endpoint. Where Layer needs bookkeeping attributes, it reserves the _hevlayer_* prefix. Treat these fields as read-only; the document model defines the contract.

Gateway and store

The gateway receives writes and queries over HTTP and executes them against the selected store. Local Compose supplies Postgres with pgvector and pg_search; an existing Turbopuffer account is another supported backend. See configuration and store support.

Namespaces and rows

A namespace groups rows addressed by ID. A row contains attributes and can include vectors. The first write creates a namespace.

Retrieval

Query routing chooses a ranking strategy. Scans select rows or aggregate matching values, while federation merges results across explicit namespaces. Support depends on the backing store and request shape.

Scatter/gather

Layer stamps every row it writes to Turbopuffer with a _hevlayer_shard hash bucket. For an existing namespace, initialization backfills rows that were written without one. Scatter/gather starts after layer.shard_lag_rows reaches zero; the single-namespace path serves queries while backfill runs. See CLI initialization.

Layer shards are not Turbopuffer shards

	Layer shards	Turbopuffer shards
What	Hash buckets inside one Turbopuffer namespace	Partitions of a namespace inside Turbopuffer
Set by	The gateway, on every row it writes: `xxh64(id) % shard_count`	You, with `sharding.num_shards` on the first write
Where you see it	`_hevlayer_shard` in rows and the schema	`sharding.num_shards` in namespace metadata
Used for	Layer's scatter/gather across parallel requests	Scaling one namespace inside Turbopuffer

Every Layer namespace on Turbopuffer has Layer shards. Turbopuffer shards are optional and independent of them.

Glossary

Concept	Meaning
Wire protocol	The HTTP methods, paths, request fields, response shapes, and status codes exchanged by client and server.
Wire feature	An individual operation or option whose backend support is declared in the capability matrix.
Gateway	The Layer service that receives client requests, validates them, and executes them against the configured stores.
VectorStore	A serving connection to the backend that stores and queries rows.
Warehouse	An upstream source connection, separate from the store serving retrieval requests.
Namespace	A named collection of rows addressed through `/v2/namespaces/{namespace}`.
Document / row	An ID and application attributes, optionally including vectors.
Scan	Row selection that returns matching IDs, field values, or a count; supported selectors depend on the backend.
Shard	A hash bucket within a namespace, identified by the reserved `_hevlayer_shard` attribute.
Scatter/gather	Running subqueries across shards or namespaces and combining their results into one response.
Leg	One subquery contributing to a hybrid or federated result.
RRF	Reciprocal rank fusion: combining ranked lists using each result’s position in its input lists.
Tokenizer policy	The rules that turn input text into retrieval tokens, including word boundaries, case normalization, and token limits.
Route	A retrieval strategy, such as `hybrid_text`, `semantic`, or `fused`, selected by the query router where supported.
Routing policy	The deterministic, versioned rules used to select an `Auto` route.
Deferral	An `Auto` response with `executed: false`: the application must supply an embedding before the selected route can execute.