Concepts

Explore the illustrated introduction to Layer →

Wire protocol matching

Layer accepts the Turbopuffer HTTP wire protocol: the methods and paths a client calls, the JSON request fields it sends, and the response shapes and status codes it reads. For supported operations, an application can point its Turbopuffer client at Layer’s base URL and keep the same request body. See the API reference for authentication and client setup.

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. A valid but unsupported feature should return 422 UnsupportedByStore, naming the store, route, and feature, rather than silently dropping part of the request.

Matching the wire does not promise identical index internals, latency, scores, or ranking across stores. In particular, full-text ranking is backend-specific. Layer’s additional request fields, routes, and response metadata are documented as gateway enhancements.

How we validate it

• API and client contracts. The SDK harness compares the gateway OpenAPI operations and generated Python client with the upstream API, and checks captured HTTP requests against documented examples using a mock server. These checks catch route, field, and serialization drift; they do not prove that a real backend returns the right results.
• Backend acceptance. Store-specific suites send requests through a real gateway and backend using generated clients. They check supported operations and explicit rejection of unsupported requests.
• Documented examples. A committed selection of upstream examples runs against a real gateway and store. Each request is classified as ok, unsupported, fail, or blocked by a prerequisite. A baseline change fails the check for review; matching a baseline can still preserve known failures. This is a selected test corpus, not proof that every upstream request or combination works.

The capability matrix is generated from backend declarations and checked for source drift. It states the contract; acceptance results are evidence of behavior. Both are needed to assess compatibility.

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 fronts your existing Turbopuffer account. See configuration.

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

Turbopuffer namespaces can use _hevlayer_shard hash buckets. Initialization stamps rows and backfills existing rows. Scatter/gather starts after layer.shard_lag_rows reaches zero; the single-namespace path serves queries while backfill runs. See CLI initialization.

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.