# hev layer

> Retrieval gateway and transform runtime around turbopuffer.

hev layer is a transparent proxy in front of turbopuffer that adds operational semantics — document cache, namespace snapshots, search history, pipeline state — plus a Kubernetes-native UDF transform runtime for embedding, classification, tagging, and attribute migration.

These docs are queryable from the command line — better than reading this file: install `ask` (`go install github.com/hev/ask/cmd/ask@latest`), then `ask --endpoint https://hevlayer.com/api/ask search "<question>"` for ranked sections with deep links, `section get "<id>"` for detail, `overview` for the full map. Setup and verbs: https://hevlayer.com/docs/agents

The full concatenated docs are at https://hevlayer.com/llms-full.txt.

## Overview
- [Introduction](https://hevlayer.com/docs): Layer is a gateway and function runtime for modern retrieval systems. It scales compute for multi-stage indexing pipelines and runs functions across every row of your index, with all durable state in object storage.
- [Concepts](https://hevlayer.com/docs/concepts): How the gateway composes turbopuffer, the document cache, PostgreSQL, S3, and metrics — and the core nouns you'll work with.
- [Document model](https://hevlayer.com/docs/document-model): A Layer document and the reserved attributes the gateway manages on every row.
- [No Guarantees](https://hevlayer.com/docs/guarantees): Layer can't offer guarantees — here's what we commit to instead.
- [Tradeoffs](https://hevlayer.com/docs/tradeoffs): The current product posture and the cases it is not trying to cover.
- [Limits](https://hevlayer.com/docs/limits): Current ceilings inherited from the components we ship with, and what we don't cap.
- [Agents](https://hevlayer.com/docs/agents): Use the Layer docs and layer CLI from your coding agent with one-file skills that work across agent harnesses.
- [Demos](https://hevlayer.com/docs/demos): Live applications built on Layer — query routing, hybrid text fusion, semantic image search, and a full storefront workload — each composing shipped gateway features over a different corpus.
- [Changelog](https://hevlayer.com/docs/roadmap): What has shipped in hev layer, and what is coming next.
- [FAQ](https://hevlayer.com/docs/faq): Licensing, pricing, trials, and how to get started.

## Operations
- [Quickstart](https://hevlayer.com/docs/quickstart): Run the community gateway with Docker, initialize a namespace, and run a query — three steps, no license key.
- [Install](https://hevlayer.com/docs/install): How to bring up a hev layer environment: AWS resources via Terraform, runtime via Helm.
- [Operator Overview](https://hevlayer.com/docs/kubernetes/operator): What layer-operator reconciles and how it relates to the gateway.
- [VectorStore CRD](https://hevlayer.com/docs/kubernetes/vectorstore-crd): Backend connection and gateway inbound auth policy for a Layer install.
- [ApiKey CRD](https://hevlayer.com/docs/kubernetes/apikey-crd): Minted API keys as Kubernetes resources: lifecycle, entitlements, and opaque claims.
- [Warehouse CRD](https://hevlayer.com/docs/kubernetes/warehouse-crd): Declared upstream data source: identity, credential, and verified reachability.
- [Index CRD](https://hevlayer.com/docs/kubernetes/index-crd): Declarative representation of a namespace managed by Layer.
- [InfraRules CRD](https://hevlayer.com/docs/kubernetes/scaling-crd): Cluster-wide compute pools, document cache rules, and workload scaling.
- [Pipeline CRD](https://hevlayer.com/docs/kubernetes/pipeline-crd): Staged row-changing work declared as a Kubernetes resource.
- [Function CRD](https://hevlayer.com/docs/kubernetes/function-crd): Stateless user-defined functions declared as Kubernetes resources.
- [Agent CRD](https://hevlayer.com/docs/kubernetes/agent-crd): Agentic search as a Kubernetes resource: a governed reasoning loop over your indices, bound to a model, a budget, and an entitlement.
- [Failure Modes](https://hevlayer.com/docs/failure-modes): How reads and writes degrade when the gateway, cache, or pipeline runs into trouble.
- [Layer CLI](https://hevlayer.com/docs/cli): The layer CLI manages environments, initializes namespace sharding, observes data-supply resources, indexes, pipelines, and UDFs, mints API keys, and runs Function manifests.
- [Dashboard](https://hevlayer.com/docs/dashboard): Running the in-cluster operations dashboard: the access it needs, networking, auth, and turning it off.

## API
- [Introduction](https://hevlayer.com/docs/api/introduction): What Layer adds on top of the turbopuffer-compatible client wire, and how to point a client at the gateway.
- [Write & Stage](https://hevlayer.com/docs/api/write): Write rows to a namespace and stage documents in the cache.
- [Blobs](https://hevlayer.com/docs/api/blobs): Durable content-addressed bytes served through the gateway.
- [Query & Fetch](https://hevlayer.com/docs/api/query): Vector similarity search with stable reads, query by id, and cached document fetch.
- [Federated query](https://hevlayer.com/docs/api/federated-query): Federate one query across a set of namespaces and merge the results into a single ranked list, scoped by the key's entitlements.
- [Agentic search](https://hevlayer.com/docs/api/agents): Run a configured reasoning loop over your indices: plan, fan out for recall, score for relevance, and return the standard row shape.
- [Scan](https://hevlayer.com/docs/api/scans): On-demand row selection by filter, full-text, hybrid-text, or radius — IDs, count, or values.
- [Pipelines](https://hevlayer.com/docs/api/pipelines): Organize a two-stage indexing pipeline: extract + chunk on CPU, embed on GPU, trigger runs and wait for completion.
- [Namespace metadata](https://hevlayer.com/docs/api/namespace-metadata): Read namespace metadata enriched with Layer freshness signals.
- [VectorStores And Warehouses](https://hevlayer.com/docs/api/data-supply): Read declared vector stores and upstream warehouses through the gateway.
- [Warm cache](https://hevlayer.com/docs/api/warm-cache): Warm a namespace's document cache and snapshot mirror.
- [Snapshot History](https://hevlayer.com/docs/api/snapshots): Facet snapshot jobs, history, bodies, and activity streams.
- [Checkpoints](https://hevlayer.com/docs/api/checkpoints): Immutable labels over namespace snapshot watermarks.
- [Query History](https://hevlayer.com/docs/api/search-history): Per-namespace query and clickstream history backed by JSONL in S3.

## Search knowledge graph

Version: 2
Generated: 2026-07-15T00:41:01.536Z
Content hash: 875b3273a38d3da8036bee0922c5ec44edcafbb765d2fc37051ea5e486a1f1f9

Context:
hev layer is a gateway and operator surface around Turbopuffer-shaped vector stores. It preserves familiar read and write contracts while adding cache-backed fetches, stable reads, scans, snapshots, history, federated retrieval, and operational controls. Kubernetes resources declare stores, indexes, warehouses, credentials, compute pools, pipelines, and Functions; the operator reconciles those resources while the gateway continues serving traffic. Pipelines bring external data into Layer and may change row count, while Functions derive attributes on rows already in Layer. Durable product state lives in object storage, the document cache is ephemeral acceleration, and indexing queues hold only pipeline and embedding state. The docs serve operators, application developers, and coding agents with deep links and a committed local search digest.

Glossary:
- stable watermark: The latest time boundary at which a namespace is known to present a caught-up index view. Aliases: stable cut, freshness watermark.
- document cache: The pull-through acceleration layer for documents, pipeline chunks, and recent snapshot data. Aliases: hot cache, cache.
- snapshot: A durable, content-addressed namespace view containing row counts and configured facet histograms. Aliases: snapshot body, facet snapshot.
- checkpoint: An immutable namespace-local label pointing to a durable snapshot watermark. Aliases: named cut, snapshot label.
- federated query: One search executed across multiple namespaces and merged into a single ranked result list. Aliases: cross-namespace search, fan-out query.
- agentic search: A configured retrieval loop that plans variants, gathers candidates, scores relevance, and returns search rows. Aliases: reasoning search, agent query.
- pipeline: A staged workflow that extracts, chunks, embeds, and writes newly ingested data. Aliases: indexing pipeline, ingestion pipeline, staged work.
- scan: On-demand selection that returns matching identifiers, counts, or distinct field values. Aliases: namespace scan.
- VectorStore: A declared serving-side connection that maps namespaces to a search backend and credential policy. Aliases: vector store, serving store, serving backend.
- Warehouse: A declared source-side connection consumed by ingestion pipelines. Aliases: source warehouse, data source, source system, upstream source.
- Agent: A saved, governed search plan that reformulates and reranks federated retrieval without generating an answer. Aliases: agentic search resource, reasoning loop.
- ApiKey: A managed credential whose entitlements describe the Layer surfaces or external claims available to its holder. Aliases: minted key, credential resource.
- Function: A stateless computation over rows already stored in Layer, with queueing, retries, and completion tracking. Aliases: UDF, user-defined function.
- Index: The declarative policy and backend binding for one namespace served through Layer. Aliases: managed namespace, namespace resource.
- Compute pool: A centrally defined placement, resource, and replica envelope selected by managed workloads. Aliases: worker pool, resource pool.
- Warm window: A post-work cooldown that retains workers and nodes to reduce repeated cold starts. Aliases: cooldown window, warm retention.
- License floor: The reduced product state used when no valid license or grace period remains. Aliases: floor state, community behavior.