# hev layer — full docs > Concatenated docs surface. Index at https://hevlayer.com/llms.txt. --- ## 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. Raw JSON: ```json { "version": 2, "generatedAt": "2026-07-15T00:41:01.536Z", "contentHash": "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": [ { "term": "stable watermark", "aliases": [ "stable cut", "freshness watermark" ], "definition": "The latest time boundary at which a namespace is known to present a caught-up index view." }, { "term": "document cache", "aliases": [ "hot cache", "cache" ], "definition": "The pull-through acceleration layer for documents, pipeline chunks, and recent snapshot data." }, { "term": "snapshot", "aliases": [ "snapshot body", "facet snapshot" ], "definition": "A durable, content-addressed namespace view containing row counts and configured facet histograms." }, { "term": "checkpoint", "aliases": [ "named cut", "snapshot label" ], "definition": "An immutable namespace-local label pointing to a durable snapshot watermark." }, { "term": "federated query", "aliases": [ "cross-namespace search", "fan-out query" ], "definition": "One search executed across multiple namespaces and merged into a single ranked result list." }, { "term": "agentic search", "aliases": [ "reasoning search", "agent query" ], "definition": "A configured retrieval loop that plans variants, gathers candidates, scores relevance, and returns search rows." }, { "term": "pipeline", "aliases": [ "indexing pipeline", "ingestion pipeline", "staged work" ], "definition": "A staged workflow that extracts, chunks, embeds, and writes newly ingested data." }, { "term": "scan", "aliases": [ "namespace scan" ], "definition": "On-demand selection that returns matching identifiers, counts, or distinct field values." }, { "term": "VectorStore", "aliases": [ "vector store", "serving store", "serving backend" ], "definition": "A declared serving-side connection that maps namespaces to a search backend and credential policy." }, { "term": "Warehouse", "aliases": [ "source warehouse", "data source", "source system", "upstream source" ], "definition": "A declared source-side connection consumed by ingestion pipelines." }, { "term": "Agent", "aliases": [ "agentic search resource", "reasoning loop" ], "definition": "A saved, governed search plan that reformulates and reranks federated retrieval without generating an answer." }, { "term": "ApiKey", "aliases": [ "minted key", "credential resource" ], "definition": "A managed credential whose entitlements describe the Layer surfaces or external claims available to its holder." }, { "term": "Function", "aliases": [ "UDF", "user-defined function" ], "definition": "A stateless computation over rows already stored in Layer, with queueing, retries, and completion tracking." }, { "term": "Index", "aliases": [ "managed namespace", "namespace resource" ], "definition": "The declarative policy and backend binding for one namespace served through Layer." }, { "term": "Compute pool", "aliases": [ "worker pool", "resource pool" ], "definition": "A centrally defined placement, resource, and replica envelope selected by managed workloads." }, { "term": "Warm window", "aliases": [ "cooldown window", "warm retention" ], "definition": "A post-work cooldown that retains workers and nodes to reduce repeated cold starts." }, { "term": "License floor", "aliases": [ "floor state", "community behavior" ], "definition": "The reduced product state used when no valid license or grace period remains." } ], "overview": "## API\n- Agentic search — `api/agents`\n- Auth — `api/agents#auth`\n- Bring your own embedding — `api/agents#bring-your-own-embedding`\n- Configuration — `api/agents#configuration`\n- Provenance and trace — `api/agents#provenance-and-trace`\n- Request — `api/agents#request`\n- Response — `api/agents#response`\n- Validation — `api/agents#validation`\n- Blobs — `api/blobs`\n- Fetch — `api/blobs#fetch`\n- Routes — `api/blobs#routes`\n- Store — `api/blobs#store`\n- Warm Policy — `api/blobs#warm-policy`\n- Checkpoints — `api/checkpoints`\n- Create — `api/checkpoints#create`\n- List — `api/checkpoints#list`\n- Resolve — `api/checkpoints#resolve`\n- Routes — `api/checkpoints#routes`\n- VectorStores And Warehouses — `api/data-supply`\n- VectorStores — `api/data-supply#vectorstores`\n- Warehouses — `api/data-supply#warehouses`\n- Federated query — `api/federated-query`\n- Consistency — `api/federated-query#consistency`\n- Entitlements — `api/federated-query#entitlements`\n- Fan-out and fuse — `api/federated-query#fan-out-and-fuse`\n- Filters — `api/federated-query#filters`\n- Fusion options — `api/federated-query#fusion-options`\n- Limits — `api/federated-query#limits`\n- Merge — `api/federated-query#merge`\n- Partial failure — `api/federated-query#partial-failure`\n- Response — `api/federated-query#response`\n- Validation — `api/federated-query#validation`\n- Vector merge requires a matching embedding space — `api/federated-query#vector-merge-requires-a-matching-embedding-space`\n- Introduction — `api/introduction`\n- Authentication — `api/introduction#authentication`\n- Cache warm hint — GET /v1/namespaces/{ns}/hint_cache_warm — `api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm`\n- Compatibility posture — `api/introduction#compatibility-posture`\n- Cross-cutting conventions — `api/introduction#cross-cutting-conventions`\n- Enhancements to upstream routes — `api/introduction#enhancements-to-upstream-routes`\n- Gateway failures — `api/introduction#gateway-failures`\n- Install — `api/introduction#install`\n- Metadata — GET /v2/namespaces/{ns}/metadata — `api/introduction#metadata--get-v2namespacesnsmetadata`\n- Query — POST /v2/namespaces/{ns}/query — `api/introduction#query--post-v2namespacesnsquery`\n- Write — POST /v2/namespaces/{ns} — `api/introduction#write--post-v2namespacesns`\n- API keys — `api/keys`\n- Authenticate — `api/keys#authenticate`\n- CLI — `api/keys#cli`\n- Key model — `api/keys#key-model`\n- kubectl — `api/keys#kubectl`\n- List and get — `api/keys#list-and-get`\n- Mint — `api/keys#mint`\n- Revoke by default — `api/keys#revoke-by-default`\n- Routes — `api/keys#routes`\n- Using a minted key — `api/keys#using-a-minted-key`\n- License — `api/license`\n- Client Call — `api/license#client-call`\n- Fields — `api/license#fields`\n- Response — `api/license#response`\n- State Effects — `api/license#state-effects`\n- Namespace metadata — `api/namespace-metadata`\n- List namespaces — `api/namespace-metadata#list-namespaces`\n- Request — `api/namespace-metadata#request`\n- The layer block — `api/namespace-metadata#the-layer-block`\n- Pipelines — `api/pipelines`\n- Deploy — `api/pipelines#deploy`\n- Document lifecycle — `api/pipelines#document-lifecycle`\n- Embed — `api/pipelines#embed`\n- Extract and chunk — `api/pipelines#extract-and-chunk`\n- Failure model — `api/pipelines#failure-model`\n- File tree — `api/pipelines#file-tree`\n- Trigger a run — `api/pipelines#trigger-a-run`\n- Wait for completion — `api/pipelines#wait-for-completion`\n- Query & Fetch — `api/query`\n- Batch fetch — `api/query#batch-fetch`\n- Batch query — `api/query#batch-query`\n- Behavior matrix — `api/query#behavior-matrix`\n- Counting matches — `api/query#counting-matches`\n- Fetch — `api/query#fetch`\n- Hybrid text fusion — `api/query#hybrid-text-fusion`\n- Options — `api/query#options`\n- Query by id — `api/query#query-by-id`\n- Query routing — `api/query#query-routing`\n- Rank expressions — `api/query#rank-expressions`\n- Response — `api/query#response`\n- Response — `api/query#response-1`\n- Routing policy — `api/query#routing-policy`\n- Semantics — `api/query#semantics`\n- Single fetch — `api/query#single-fetch`\n- Stable reads — `api/query#stable-reads`\n- Surfacing fallback — `api/query#surfacing-fallback`\n- Tokenization — `api/query#tokenization`\n- Validation — `api/query#validation`\n- Validation — `api/query#validation-1`\n- Response Headers — `api/response-headers`\n- Scan — `api/scans`\n- Auto-Mode Policy — `api/scans#auto-mode-policy`\n- Bounding ranked scans — `api/scans#bounding-ranked-scans`\n- Count Mode — `api/scans#count-mode`\n- Fan-out width — `api/scans#fan-out-width`\n- Filters — `api/scans#filters`\n- Full-text count — `api/scans#full-text-count`\n- High cardinality — `api/scans#high-cardinality`\n- Hybrid text count — `api/scans#hybrid-text-count`\n- ID Mode — `api/scans#id-mode`\n- Operational notes — `api/scans#operational-notes`\n- Precomputed serving — `api/scans#precomputed-serving`\n- Radius count — `api/scans#radius-count`\n- Routes — `api/scans#routes`\n- Sources — `api/scans#sources`\n- Values Mode — `api/scans#values-mode`\n- Query History — `api/search-history`\n- Clickstream entry — `api/search-history#clickstream-entry`\n- Query parameters — `api/search-history#query-parameters`\n- Routes — `api/search-history#routes`\n- Search history entry — `api/search-history#search-history-entry`\n- Storage — `api/search-history#storage`\n- Tag contract — `api/search-history#tag-contract`\n- Writing metadata — `api/search-history#writing-metadata`\n- Snapshot History — `api/snapshots`\n- Activity — `api/snapshots#activity`\n- History — `api/snapshots#history`\n- Manual snapshot — `api/snapshots#manual-snapshot`\n- Routes — `api/snapshots#routes`\n- Snapshot body — `api/snapshots#snapshot-body`\n- Snapshot policy — `api/snapshots#snapshot-policy`\n- Warm cache — `api/warm-cache`\n- Cache-cold behavior — `api/warm-cache#cache-cold-behavior`\n- Hint-cache warm — `api/warm-cache#hint-cache-warm`\n- Layer warm — `api/warm-cache#layer-warm`\n- Write & Stage — `api/write`\n- Stage — `api/write#stage`\n- Status — `api/write#status`\n## Operations\n- Layer CLI — `cli`\n- Ask The Docs — `cli#ask-the-docs`\n- Configuration — `cli#configuration`\n- Delete An Index — `cli#delete-an-index`\n- Environments — `cli#environments`\n- Initialize a Namespace — `cli#initialize-a-namespace`\n- Inspect An Index — `cli#inspect-an-index`\n- Install — `cli#install`\n- Keys — `cli#keys`\n- Manage Snapshots — `cli#manage-snapshots`\n- Pipelines — `cli#pipelines`\n- Run A Function — `cli#run-a-function`\n- TUI — `cli#tui`\n- Vector Store And Warehouse — `cli#vector-store-and-warehouse`\n- Dashboard — `dashboard`\n- Access it needs — `dashboard#access-it-needs`\n- Basic auth — `dashboard#basic-auth`\n- Disabling the dashboard — `dashboard#disabling-the-dashboard`\n- Networking — `dashboard#networking`\n- Operational notes — `dashboard#operational-notes`\n- Pipeline queue states — `dashboard#pipeline-queue-states`\n- Failure Modes — `failure-modes`\n- Client failures — `failure-modes#client-failures`\n- Pipeline stop-writes — `failure-modes#pipeline-stop-writes`\n- Read — `failure-modes#read`\n- Write — `failure-modes#write`\n- Install — `install`\n- Cluster: recommended — `install#cluster-recommended`\n- Cost notes — `install#cost-notes`\n- Default InfraRules — `install#default-infrarules`\n- Gateway auth modes — `install#gateway-auth-modes`\n- Helm — `install#helm`\n- Image Coordinates — `install#image-coordinates`\n- Install shape — `install#install-shape`\n- Layer-Operated Search — `install#layer-operated-search`\n- Local gateway development — `install#local-gateway-development`\n- One-script install — `install#one-script-install`\n- Outputs — `install#outputs`\n- Required values — `install#required-values`\n- Run the install — `install#run-the-install`\n- Terraform — `install#terraform`\n- What gets installed — `install#what-gets-installed`\n- What it sets up — `install#what-it-sets-up`\n- Agent CRD — `kubernetes/agent-crd`\n- Auth — `kubernetes/agent-crd#auth`\n- Budget — `kubernetes/agent-crd#budget`\n- Indices — `kubernetes/agent-crd#indices`\n- Model — `kubernetes/agent-crd#model`\n- Naming — `kubernetes/agent-crd#naming`\n- Observability — `kubernetes/agent-crd#observability`\n- Output — `kubernetes/agent-crd#output`\n- Retrieval — `kubernetes/agent-crd#retrieval`\n- Status — `kubernetes/agent-crd#status`\n- ApiKey CRD — `kubernetes/apikey-crd`\n- Backup and migration — `kubernetes/apikey-crd#backup-and-migration`\n- Bootstrapping — `kubernetes/apikey-crd#bootstrapping`\n- Entitlements — `kubernetes/apikey-crd#entitlements`\n- Kubernetes RBAC — `kubernetes/apikey-crd#kubernetes-rbac`\n- Minting — `kubernetes/apikey-crd#minting`\n- Spec — `kubernetes/apikey-crd#spec`\n- Verification — `kubernetes/apikey-crd#verification`\n- Function CRD — `kubernetes/function-crd`\n- GPU classifier — `kubernetes/function-crd#gpu-classifier`\n- Lifecycle — `kubernetes/function-crd#lifecycle`\n- Scaling — `kubernetes/function-crd#scaling`\n- Selection — `kubernetes/function-crd#selection`\n- Simple classifier — `kubernetes/function-crd#simple-classifier`\n- Tuning knobs — `kubernetes/function-crd#tuning-knobs`\n- Version markers — `kubernetes/function-crd#version-markers`\n- Worker — `kubernetes/function-crd#worker`\n- Writeback — `kubernetes/function-crd#writeback`\n- Index CRD — `kubernetes/index-crd`\n- Backend — `kubernetes/index-crd#backend`\n- Cache policy — `kubernetes/index-crd#cache-policy`\n- Embedding — `kubernetes/index-crd#embedding`\n- Scan policy — `kubernetes/index-crd#scan-policy`\n- Search backend policy — `kubernetes/index-crd#search-backend-policy`\n- Snapshot policy — `kubernetes/index-crd#snapshot-policy`\n- Status — `kubernetes/index-crd#status`\n- Operator Overview — `kubernetes/operator`\n- CRDs — `kubernetes/operator#crds`\n- Relationship to the gateway — `kubernetes/operator#relationship-to-the-gateway`\n- Scheduling and node pools — `kubernetes/operator#scheduling-and-node-pools`\n- Pipeline CRD — `kubernetes/pipeline-crd`\n- Chunking — `kubernetes/pipeline-crd#chunking`\n- Pipeline id — `kubernetes/pipeline-crd#pipeline-id`\n- Scaling — `kubernetes/pipeline-crd#scaling`\n- Schedule — `kubernetes/pipeline-crd#schedule`\n- Source — `kubernetes/pipeline-crd#source`\n- Status — `kubernetes/pipeline-crd#status`\n- Target — `kubernetes/pipeline-crd#target`\n- Typed sources — `kubernetes/pipeline-crd#typed-sources`\n- Worker — `kubernetes/pipeline-crd#worker`\n- InfraRules CRD — `kubernetes/scaling-crd`\n- Compute pools — `kubernetes/scaling-crd#compute-pools`\n- Document cache rules — `kubernetes/scaling-crd#document-cache-rules`\n- InfraRules — `kubernetes/scaling-crd#infrarules`\n- Warm window — `kubernetes/scaling-crd#warm-window`\n- Workload scaling — `kubernetes/scaling-crd#workload-scaling`\n- VectorStore CRD — `kubernetes/vectorstore-crd`\n- Connection — `kubernetes/vectorstore-crd#connection`\n- Inbound auth — `kubernetes/vectorstore-crd#inbound-auth`\n- Routing — `kubernetes/vectorstore-crd#routing`\n- Standalone config — `kubernetes/vectorstore-crd#standalone-config`\n- Status — `kubernetes/vectorstore-crd#status`\n- Warehouse CRD — `kubernetes/warehouse-crd`\n- Connection — `kubernetes/warehouse-crd#connection`\n- Deletion — `kubernetes/warehouse-crd#deletion`\n- Hugging Face — `kubernetes/warehouse-crd#hugging-face`\n- Keys — `kubernetes/warehouse-crd#keys`\n- Pipeline source — `kubernetes/warehouse-crd#pipeline-source`\n- REST — `kubernetes/warehouse-crd#rest`\n- REST / HTTP JSON API — `kubernetes/warehouse-crd#rest--http-json-api`\n- Rotation — `kubernetes/warehouse-crd#rotation`\n- Snowflake — `kubernetes/warehouse-crd#snowflake`\n- Snowflake — `kubernetes/warehouse-crd#snowflake-1`\n- Status — `kubernetes/warehouse-crd#status`\n- Supported Warehouses — `kubernetes/warehouse-crd#supported-warehouses`\n- Verification — `kubernetes/warehouse-crd#verification`\n- Quickstart — `quickstart`\n- 1. Start the Gateway — `quickstart#1-start-the-gateway`\n- 2. Initialize the Namespace — `quickstart#2-initialize-the-namespace`\n- 3. Run a Query — `quickstart#3-run-a-query`\n## Overview\n- Agents — `agents`\n- 1. Install the CLIs — `agents#1-install-the-clis`\n- 2. Add the docs skill — `agents#2-add-the-docs-skill`\n- 3. Add the layer CLI skill — `agents#3-add-the-layer-cli-skill`\n- 4. Ask — `agents#4-ask`\n- The verbs — `agents#the-verbs`\n- Why answers stay grounded — `agents#why-answers-stay-grounded`\n- Concepts — `concepts`\n- Control loops — `concepts#control-loops`\n- Document cache — `concepts#document-cache`\n- Gateway enhancements — `concepts#gateway-enhancements`\n- Glossary — `concepts#glossary`\n- Kubernetes autoscaling — `concepts#kubernetes-autoscaling`\n- Scatter/gather — `concepts#scattergather`\n- Demos — `demos`\n- chart — clinical patient-notes search that shows its routing — `demos#chart--clinical-patient-notes-search-that-shows-its-routing`\n- hybrid-text — hybrid text fusion over SciFact — `demos#hybrid-text--hybrid-text-fusion-over-scifact`\n- shelf — book search that shows its routing — `demos#shelf--book-search-that-shows-its-routing`\n- shop — semantic shopping, everything together — `demos#shop--semantic-shopping-everything-together`\n- Document model — `document-model`\n- FAQ — `faq`\n- How do I know whether my license is healthy? — `faq#how-do-i-know-whether-my-license-is-healthy`\n- How do I start a trial? — `faq#how-do-i-start-a-trial`\n- How much will it cost? — `faq#how-much-will-it-cost`\n- What is the licensing for hev layer? — `faq#what-is-the-licensing-for-hev-layer`\n- Who built hev layer? — `faq#who-built-hev-layer`\n- No Guarantees — `guarantees`\n- Commitments — `guarantees#commitments`\n- Introduction — `index`\n- Licensing — `licensing`\n- Client SDKs — `licensing#client-sdks`\n- End-to-End Runbook — `licensing#end-to-end-runbook`\n- Governing Terms — `licensing#governing-terms`\n- Install the Key — `licensing#install-the-key`\n- License Claims — `licensing#license-claims`\n- License States — `licensing#license-states`\n- Metrics — `licensing#metrics`\n- Renewals — `licensing#renewals`\n- Start a Trial — `licensing#start-a-trial`\n- Limits — `limits`\n- No limits — `limits#no-limits`\n- Changelog — `roadmap`\n- 0.4 — `roadmap#04`\n- API hardening — `roadmap#api-hardening`\n- Lifecycle and operability — `roadmap#lifecycle-and-operability`\n- Polish — `roadmap#polish`\n- Search — `roadmap#search`\n- Surfaces — `roadmap#surfaces`\n- Up Next — `roadmap#up-next`\n- Tradeoffs — `tradeoffs`", "suggestions": [ "How do I choose between a Pipeline and a Function?", "What happens when the document cache is unavailable?", "How do stable reads behave while an index is updating?", "Which write operations does each vector store support?", "How do I install Layer on Kubernetes?" ], "nodes": [ { "id": "agents", "kind": "section", "title": "Agents", "heading": null, "group": "Overview", "url": "/docs/agents", "summary": "Layer supplies portable one-file skills that let coding agents search the documentation and operate environments and workloads from a shell. The docs search path is local and keyless, while operational access uses the Layer command-line client.", "facts": [ { "kind": "code", "literal": "⌘K", "chunkId": "agents" }, { "kind": "code", "literal": "layer", "chunkId": "agents" }, { "kind": "code", "literal": "SKILL.md", "chunkId": "agents" }, { "kind": "code", "literal": "AGENTS.md", "chunkId": "agents" }, { "kind": "value", "literal": "Callout.astro", "chunkId": "agents" } ], "sources": [ { "chunkId": "agents", "url": "/docs/agents", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "supplies", "portable", "file", "skills", "coding", "agents", "search", "documentation", "operate", "environments", "workloads", "shell", "docs", "path", "local", "keyless", "while", "operational", "access", "uses", "command", "line", "client", "skill", "callout", "astro", "agent", "work", "across", "harnesses", "these", "queryable", "same", "engine", "behind", "site", "ships", "read", "cite" ] }, { "id": "agents#1-install-the-clis", "kind": "section", "title": "Agents", "heading": "1. Install the CLIs", "group": "Overview", "url": "/docs/agents#1-install-the-clis", "summary": "Install the self-contained documentation search tool for any shell-capable agent, and build the Layer command-line client when the agent also needs operational access.", "facts": [ { "kind": "code", "literal": "go install github.com/hev/ask/cmd/ask@latest", "chunkId": "agents#1-install-the-clis" }, { "kind": "code", "literal": "go build -o layer ./apps/layer-cli", "chunkId": "agents#1-install-the-clis" }, { "kind": "code", "literal": "ask", "chunkId": "agents#1-install-the-clis" }, { "kind": "code", "literal": "layer", "chunkId": "agents#1-install-the-clis" } ], "sources": [ { "chunkId": "agents#1-install-the-clis", "url": "/docs/agents#1-install-the-clis", "anchor": "1-install-the-clis" } ], "mode": "agent-primary", "terms": [ "install", "clis", "self", "contained", "documentation", "search", "tool", "shell", "capable", "agent", "build", "layer", "command", "line", "client", "also", "needs", "operational", "access", "github", "latest", "apps", "binary", "harness", "checkout", "should", "operate", "environments", "instead", "only", "searching", "docs" ] }, { "id": "agents#2-add-the-docs-skill", "kind": "section", "title": "Agents", "heading": "2. Add the docs skill", "group": "Overview", "url": "/docs/agents#2-add-the-docs-skill", "summary": "Place a documentation skill in the agent harness's native skill directory. It should answer from retrieved documentation, begin with ranked search, fetch detailed sections as needed, and cite returned page links.", "facts": [ { "kind": "code", "literal": "AGENT_SKILL_HOME", "chunkId": "agents#2-add-the-docs-skill" }, { "kind": "code", "literal": "~/.codex/skills", "chunkId": "agents#2-add-the-docs-skill" }, { "kind": "code", "literal": "~/.claude/skills", "chunkId": "agents#2-add-the-docs-skill" } ], "sources": [ { "chunkId": "agents#2-add-the-docs-skill", "url": "/docs/agents#2-add-the-docs-skill", "anchor": "2-add-the-docs-skill" } ], "mode": "agent-primary", "terms": [ "docs", "skill", "place", "documentation", "agent", "harness", "native", "directory", "should", "answer", "retrieved", "begin", "ranked", "search", "fetch", "detailed", "sections", "needed", "cite", "returned", "page", "links", "home", "codex", "skills", "claude", "agentskillhome", "such", "code", "codexhome", "mkdir", "hevlayer", "name", "description", "query", "layer", "user", "asks", "about", "turbopuffer" ] }, { "id": "agents#3-add-the-layer-cli-skill", "kind": "section", "title": "Agents", "heading": "3. Add the layer CLI skill", "group": "Overview", "url": "/docs/agents#3-add-the-layer-cli-skill", "summary": "Add a separate operational skill that favors structured output, keeps documentation lookup and read-only inspection distinct from mutations, and confirms the environment and cluster target before making changes.", "facts": [ { "kind": "code", "literal": "layer", "chunkId": "agents#3-add-the-layer-cli-skill" } ], "sources": [ { "chunkId": "agents#3-add-the-layer-cli-skill", "url": "/docs/agents#3-add-the-layer-cli-skill", "anchor": "3-add-the-layer-cli-skill" } ], "mode": "agent-primary", "terms": [ "layer", "skill", "separate", "operational", "favors", "structured", "output", "keeps", "documentation", "lookup", "read", "only", "inspection", "distinct", "mutations", "confirms", "environment", "cluster", "target", "before", "making", "changes", "agent", "should", "inspect", "operate", "through", "docs", "mutating", "operations", "agentskillhome", "codexhome", "home", "codex", "skills", "mkdir", "hevlayer", "name", "description", "user" ] }, { "id": "agents#4-ask", "kind": "section", "title": "Agents", "heading": "4. Ask", "group": "Overview", "url": "/docs/agents#4-ask", "summary": "The usual documentation workflow is to search a natural-language problem, open the best matching section, and answer with that section's citation.", "facts": [ { "kind": "code", "literal": "ask --endpoint https://hevlayer.com/api/ask search \"cache is down\"", "chunkId": "agents#4-ask" }, { "kind": "code", "literal": "{\n \"results\": [\n {\n \"title\": \"Concepts\",\n \"heading\": \"Document cache\",\n \"url\": \"/docs/concepts#document-cache\",\n \"group\": \"Overview\",\n \"snippet\": \"The document cache does two jobs: pull-through document reads...\"\n }\n ]\n}", "chunkId": "agents#4-ask" }, { "kind": "code", "literal": "section get", "chunkId": "agents#4-ask" } ], "sources": [ { "chunkId": "agents#4-ask", "url": "/docs/agents#4-ask", "anchor": "4-ask" } ], "mode": "agent-primary", "terms": [ "usual", "documentation", "workflow", "search", "natural", "language", "problem", "open", "best", "matching", "section", "answer", "citation", "endpoint", "https", "hevlayer", "cache", "down", "results", "title", "concepts", "heading", "document", "docs", "group", "overview", "snippet", "does", "jobs", "pull", "through", "reads", "here", "agent", "typically", "runs", "winning", "answers" ] }, { "id": "agents#the-verbs", "kind": "section", "title": "Agents", "heading": "The verbs", "group": "Overview", "url": "/docs/agents#the-verbs", "summary": "The documentation tool provides orientation, ranked search, detailed section retrieval, and glossary resolution so an agent can move from broad discovery to exact context.", "facts": [ { "kind": "code", "literal": "overview", "chunkId": "agents#the-verbs" }, { "kind": "code", "literal": "search \"\"", "chunkId": "agents#the-verbs" }, { "kind": "code", "literal": "section get \"\"", "chunkId": "agents#the-verbs" }, { "kind": "code", "literal": "glossary get \"\"", "chunkId": "agents#the-verbs" }, { "kind": "code", "literal": "watermark", "chunkId": "agents#the-verbs" } ], "sources": [ { "chunkId": "agents#the-verbs", "url": "/docs/agents#the-verbs", "anchor": "the-verbs" } ], "mode": "agent-primary", "terms": [ "verbs", "documentation", "tool", "provides", "orientation", "ranked", "search", "detailed", "section", "retrieval", "glossary", "resolution", "agent", "move", "broad", "discovery", "exact", "context", "overview", "query", "term", "watermark", "verb", "returns", "plus", "full", "stable", "sections", "snippets", "deep", "links", "summary", "identifiers", "source", "product", "resolved", "through", "aliases" ] }, { "id": "agents#why-answers-stay-grounded", "kind": "section", "title": "Agents", "heading": "Why answers stay grounded", "group": "Overview", "url": "/docs/agents#why-answers-stay-grounded", "summary": "Answers are grounded in a committed digest built from the same reviewed headings as the site, with links checked during continuous integration. Plain-text corpora also exist, but the command-line search saves tokens by ranking sections and resolving aliases.", "facts": [ { "kind": "value", "literal": "llms.txt", "chunkId": "agents#why-answers-stay-grounded" }, { "kind": "value", "literal": "llms-full.txt", "chunkId": "agents#why-answers-stay-grounded" } ], "sources": [ { "chunkId": "agents#why-answers-stay-grounded", "url": "/docs/agents#why-answers-stay-grounded", "anchor": "why-answers-stay-grounded" } ], "mode": "agent-primary", "terms": [ "answers", "stay", "grounded", "committed", "digest", "built", "same", "reviewed", "headings", "site", "links", "checked", "during", "continuous", "integration", "plain", "text", "corpora", "also", "exist", "command", "line", "search", "saves", "tokens", "ranking", "sections", "resolving", "aliases", "llms", "full", "runs", "reviewable", "these", "docs", "corpus", "heading", "renders", "every", "anchor" ] }, { "id": "api/agents", "kind": "section", "title": "Agentic search", "heading": null, "group": "API", "url": "/docs/api/agents", "summary": "Agentic search runs a configured reasoning loop across one or more namespaces, broadens recall with planned query variants, grades candidates for relevance, and returns ordinary federated search rows rather than generated prose.", "facts": [ { "kind": "code", "literal": "POST /v2/agents/{name}/query", "chunkId": "api/agents" }, { "kind": "code", "literal": "/v2/query", "chunkId": "api/agents" }, { "kind": "code", "literal": "Agent", "chunkId": "api/agents" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/agents" } ], "sources": [ { "chunkId": "api/agents", "url": "/docs/api/agents", "anchor": null } ], "mode": "source-primary", "terms": [ "agentic", "search", "runs", "configured", "reasoning", "loop", "across", "more", "namespaces", "broadens", "recall", "planned", "query", "variants", "grades", "candidates", "relevance", "returns", "ordinary", "federated", "rows", "rather", "generated", "prose", "post", "agents", "name", "agent", "codetabs", "astro", "indices", "plan", "score", "return", "standard", "shape", "same", "every", "other", "endpoint" ] }, { "id": "api/agents#auth", "kind": "section", "title": "Agentic search", "heading": "Auth", "group": "API", "url": "/docs/api/agents#auth", "summary": "Agentic search follows normal gateway and federated authorization. Scoped credentials must also be entitled to invoke the configured agent.", "facts": [ { "kind": "code", "literal": "agent.", "chunkId": "api/agents#auth" } ], "sources": [ { "chunkId": "api/agents#auth", "url": "/docs/api/agents#auth", "anchor": "auth" } ], "mode": "source-primary", "terms": [ "auth", "agentic", "search", "follows", "normal", "gateway", "federated", "authorization", "scoped", "credentials", "must", "also", "entitled", "invoke", "configured", "agent", "name", "same", "model", "other", "endpoints", "multi", "namespace", "queries", "follow", "query", "behavior", "minted", "additionally", "needs", "entitlement", "apikey" ] }, { "id": "api/agents#bring-your-own-embedding", "kind": "section", "title": "Agentic search", "heading": "Bring your own embedding", "group": "API", "url": "/docs/api/agents#bring-your-own-embedding", "summary": "The client supplies the semantic query vector, created with the same embedding model and dimensions as the target indexes. Without one, planned semantic legs fall back to lexical retrieval over the reformulated text.", "facts": [ { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/agents/support-search/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"auth errors after the june upgrade\",\n \"vector\": [0.0123, -0.0456, 0.0789],\n \"top_k\": 20\n }'", "chunkId": "api/agents#bring-your-own-embedding" }, { "kind": "code", "literal": "/v2/query", "chunkId": "api/agents#bring-your-own-embedding" }, { "kind": "code", "literal": "vector", "chunkId": "api/agents#bring-your-own-embedding" }, { "kind": "code", "literal": "query", "chunkId": "api/agents#bring-your-own-embedding" } ], "sources": [ { "chunkId": "api/agents#bring-your-own-embedding", "url": "/docs/api/agents#bring-your-own-embedding", "anchor": "bring-your-own-embedding" } ], "mode": "source-primary", "terms": [ "bring", "embedding", "client", "supplies", "semantic", "query", "vector", "created", "same", "model", "dimensions", "target", "indexes", "without", "planned", "legs", "fall", "back", "lexical", "retrieval", "reformulated", "text", "curl", "post", "layer", "gateway", "agents", "support", "search", "authorization", "bearer", "content", "type", "application", "json", "auth", "errors", "after", "june", "upgrade" ] }, { "id": "api/agents#configuration", "kind": "section", "title": "Agentic search", "heading": "Configuration", "group": "API", "url": "/docs/api/agents#configuration", "summary": "The Agent resource fixes the model, credentials, time budget, target indexes, fan-out, fusion weights, and output behavior, keeping each request focused on query data.", "facts": [ { "kind": "code", "literal": "Agent", "chunkId": "api/agents#configuration" }, { "kind": "code", "literal": "kubectl get agent -o yaml", "chunkId": "api/agents#configuration" }, { "kind": "code", "literal": "client.agent(\"support-search\").apply()", "chunkId": "api/agents#configuration" } ], "sources": [ { "chunkId": "api/agents#configuration", "url": "/docs/api/agents#configuration", "anchor": "configuration" } ], "mode": "source-primary", "terms": [ "configuration", "agent", "resource", "fixes", "model", "credentials", "time", "budget", "target", "indexes", "fusion", "weights", "output", "behavior", "keeping", "request", "focused", "query", "data", "kubectl", "yaml", "client", "support", "search", "apply", "everything", "omits", "bound", "credential", "deadline", "indices", "weighting", "shaping", "spellings", "same", "object" ] }, { "id": "api/agents#provenance-and-trace", "kind": "section", "title": "Agentic search", "heading": "Provenance and trace", "group": "API", "url": "/docs/api/agents#provenance-and-trace", "summary": "Optional provenance explains which planned variant first found each row and separates its retrieval position from the model's relevance grade. The response can also report planning, deadline, and full-trace details, while search history retains the trace for evaluation.", "facts": [ { "kind": "code", "literal": "agent", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "$agent", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "$agent.retrievalScore", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "fanout", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "$agent.relevanceScore", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "$agent.query", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "$agent.queryIndex", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "agent.queries", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "agent.turns", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "agent.deadlineHit", "chunkId": "api/agents#provenance-and-trace" }, { "kind": "code", "literal": "output.trace", "chunkId": "api/agents#provenance-and-trace" } ], "sources": [ { "chunkId": "api/agents#provenance-and-trace", "url": "/docs/api/agents#provenance-and-trace", "anchor": "provenance-and-trace" } ], "mode": "source-primary", "terms": [ "provenance", "trace", "optional", "explains", "planned", "variant", "first", "found", "separates", "retrieval", "position", "model", "relevance", "grade", "response", "also", "report", "planning", "deadline", "full", "details", "while", "search", "history", "retains", "evaluation", "agent", "retrievalscore", "fanout", "relevancescore", "query", "queryindex", "queries", "turns", "deadlinehit", "output", "gains", "echo", "carries", "field" ] }, { "id": "api/agents#request", "kind": "section", "title": "Agentic search", "heading": "Request", "group": "API", "url": "/docs/api/agents#request", "summary": "An agent query contains natural-language input, an optional client-generated embedding, and a desired result count. Operational choices remain on the Agent resource and cannot be overridden per request.", "facts": [ { "kind": "code", "literal": "response = await client.agent(\"support-search\").query({\n \"query\": \"auth errors after the june upgrade\",\n \"top_k\": 20,\n})", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "response, err := client.Agent(\"support-search\").Query(ctx, &hevlayer.AgentQueryRequest{\n Query: \"auth errors after the june upgrade\",\n TopK: 20,\n})", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "const response = await client.agent(\"support-search\").query({\n query: \"auth errors after the june upgrade\",\n top_k: 20,\n});", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/agents/support-search/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"auth errors after the june upgrade\",\n \"top_k\": 20\n }'", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "query", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "vector", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "top_k", "chunkId": "api/agents#request" }, { "kind": "code", "literal": "Agent", "chunkId": "api/agents#request" } ], "sources": [ { "chunkId": "api/agents#request", "url": "/docs/api/agents#request", "anchor": "request" } ], "mode": "source-primary", "terms": [ "request", "agent", "query", "contains", "natural", "language", "input", "optional", "client", "generated", "embedding", "desired", "result", "count", "operational", "choices", "remain", "resource", "cannot", "overridden", "response", "await", "support", "search", "auth", "errors", "after", "june", "upgrade", "hevlayer", "agentqueryrequest", "topk", "const", "curl", "post", "layer", "gateway", "agents", "authorization", "bearer" ] }, { "id": "api/agents#response", "kind": "section", "title": "Agentic search", "heading": "Response", "group": "API", "url": "/docs/api/agents#response", "summary": "The default response matches the normal federated-query shape, including rows, merge information, and per-namespace freshness. Provenance can be enabled on the Agent when callers need the underlying scoring details.", "facts": [ { "kind": "code", "literal": "{\n \"rows\": [\n { \"id\": \"T-4821\", \"$namespace\": \"tickets\", \"$rank\": 1, \"$score\": 9.7, \"subject\": \"SSO login fails after upgrade\" }\n ],\n \"merge\": { \"method\": \"weighted-rrf\", \"route\": \"dual-score\" },\n \"namespaces\": [\n { \"namespace\": \"tickets\", \"stable_as_of\": 1747300000123, \"matched\": 20 }\n ]\n}", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "rows", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "$namespace", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "$rank", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "$score", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "$dist", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "merge", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "namespaces", "chunkId": "api/agents#response" }, { "kind": "code", "literal": "output.provenance", "chunkId": "api/agents#response" } ], "sources": [ { "chunkId": "api/agents#response", "url": "/docs/api/agents#response", "anchor": "response" } ], "mode": "source-primary", "terms": [ "response", "default", "matches", "normal", "federated", "query", "shape", "including", "rows", "merge", "information", "namespace", "freshness", "provenance", "enabled", "agent", "callers", "need", "underlying", "scoring", "details", "4821", "tickets", "rank", "score", "subject", "login", "fails", "after", "upgrade", "method", "weighted", "route", "dual", "namespaces", "stable", "1747300000123", "matched", "dist", "output" ] }, { "id": "api/agents#validation", "kind": "section", "title": "Agentic search", "heading": "Validation", "group": "API", "url": "/docs/api/agents#validation", "summary": "Requests fail when the Agent is unavailable, the caller lacks access, input is empty, or an embedding does not fit the bound indexes. Deadline and model-provider failures follow the Agent's configured fallback and partial-result policy.", "facts": [ { "kind": "code", "literal": "{name}", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "Ready", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "agent.", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "query", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "vector", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "onDeadline: bestEffort", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "agent.deadlineHit: true", "chunkId": "api/agents#validation" }, { "kind": "code", "literal": "onDeadline: error", "chunkId": "api/agents#validation" } ], "sources": [ { "chunkId": "api/agents#validation", "url": "/docs/api/agents#validation", "anchor": "validation" } ], "mode": "source-primary", "terms": [ "validation", "requests", "fail", "agent", "unavailable", "caller", "lacks", "access", "input", "empty", "embedding", "does", "bound", "indexes", "deadline", "model", "provider", "failures", "follow", "configured", "fallback", "partial", "result", "policy", "name", "ready", "query", "vector", "ondeadline", "besteffort", "deadlinehit", "true", "error", "condition", "status", "known", "minted", "entitlement", "index", "outside" ] }, { "id": "api/blobs", "kind": "section", "title": "Blobs", "heading": null, "group": "API", "url": "/docs/api/blobs", "summary": "Blobs keep opaque binary content durably in object storage and serve it through the gateway's pull-through cache. Rows hold ordinary content-addressed references rather than embedding the bytes themselves.", "facts": [ { "kind": "code", "literal": "image_blob: \"blob://products/\"", "chunkId": "api/blobs" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/blobs" } ], "sources": [ { "chunkId": "api/blobs", "url": "/docs/api/blobs", "anchor": null } ], "mode": "source-primary", "terms": [ "blobs", "keep", "opaque", "binary", "content", "durably", "object", "storage", "serve", "through", "gateway", "pull", "cache", "rows", "hold", "ordinary", "addressed", "references", "rather", "embedding", "bytes", "themselves", "image", "blob", "products", "sha256", "codetabs", "astro", "durable", "served", "store", "layer", "bucket", "aerospike", "never", "stores", "string", "attribute", "such", "imageblob" ] }, { "id": "api/blobs#fetch", "kind": "section", "title": "Blobs", "heading": "Fetch", "group": "API", "url": "/docs/api/blobs#fetch", "summary": "Fetching a blob returns immutable, content-addressed bytes with long-lived caching metadata. Common image formats receive a specific media type and other content is served as generic binary data.", "facts": [ { "kind": "code", "literal": "image = await client.get_blob(\"products\", stored.sha256)", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "image, err := client.GetBlob(ctx, \"products\", stored.Sha256)", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "const image = await client.getBlob(\"products\", stored.sha256);", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v1/namespaces/products/blobs/$SHA256\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -o image.jpg", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "Cache-Control: public, max-age=31536000, immutable\nETag: \"\"", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "jpeg", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "png", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "gif", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "webp", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "Content-Type", "chunkId": "api/blobs#fetch" }, { "kind": "code", "literal": "application/octet-stream", "chunkId": "api/blobs#fetch" } ], "sources": [ { "chunkId": "api/blobs#fetch", "url": "/docs/api/blobs#fetch", "anchor": "fetch" } ], "mode": "source-primary", "terms": [ "fetch", "fetching", "blob", "returns", "immutable", "content", "addressed", "bytes", "long", "lived", "caching", "metadata", "common", "image", "formats", "receive", "specific", "media", "type", "other", "served", "generic", "binary", "data", "await", "client", "products", "stored", "sha256", "getblob", "const", "curl", "layer", "gateway", "namespaces", "blobs", "authorization", "bearer", "cache", "control" ] }, { "id": "api/blobs#routes", "kind": "section", "title": "Blobs", "heading": "Routes", "group": "API", "url": "/docs/api/blobs#routes", "summary": "The blob surface stores raw bytes under a namespace and retrieves them by content hash, reading the hot cache first and falling back to durable object storage.", "facts": [ { "kind": "code", "literal": "PUT /v1/namespaces/{ns}/blobs", "chunkId": "api/blobs#routes" }, { "kind": "code", "literal": "blob://", "chunkId": "api/blobs#routes" }, { "kind": "code", "literal": "GET /v1/namespaces/{ns}/blobs/{sha256}", "chunkId": "api/blobs#routes" } ], "sources": [ { "chunkId": "api/blobs#routes", "url": "/docs/api/blobs#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "blob", "surface", "stores", "bytes", "under", "namespace", "retrieves", "content", "hash", "reading", "cache", "first", "falling", "back", "durable", "object", "storage", "namespaces", "blobs", "sha256", "route", "method", "behavior", "store", "return", "reference", "serve", "aerospike", "backfilling" ] }, { "id": "api/blobs#store", "kind": "section", "title": "Blobs", "heading": "Store", "group": "API", "url": "/docs/api/blobs#store", "summary": "Storing non-empty bytes below the configured size limit returns a deterministic reference, digest, and size. That reference can be written as a normal row attribute, while binary payloads are rejected from ordinary namespace writes.", "facts": [ { "kind": "code", "literal": "with open(\"image.jpg\", \"rb\") as f:\n stored = await client.put_blob(\"products\", f.read())\n\nprint(stored.ref)", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "body, _ := os.ReadFile(\"image.jpg\")\nstored, err := client.PutBlob(ctx, \"products\", body, nil)", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "import fs from \"node:fs/promises\";\n\nconst bytes = await fs.readFile(\"image.jpg\");\nconst stored = await client.putBlob(\"products\", bytes);", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "curl -X PUT \"$LAYER_GATEWAY_URL/v1/namespaces/products/blobs\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary @image.jpg", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "{\n \"ref\": \"blob://products/9f86d081884c7d659a2feaa0c55ad015...\",\n \"sha256\": \"9f86d081884c7d659a2feaa0c55ad015...\",\n \"size\": 48213\n}", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "{\n \"id\": \"B0123\",\n \"vector\": [0.1, 0.2],\n \"image_blob\": \"blob://products/9f86d081884c7d659a2feaa0c55ad015...\"\n}", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "ref", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "blobs", "chunkId": "api/blobs#store" }, { "kind": "code", "literal": "/v2/namespaces/{ns}", "chunkId": "api/blobs#store" } ], "sources": [ { "chunkId": "api/blobs#store", "url": "/docs/api/blobs#store", "anchor": "store" } ], "mode": "source-primary", "terms": [ "store", "storing", "empty", "bytes", "below", "configured", "size", "limit", "returns", "deterministic", "reference", "digest", "written", "normal", "attribute", "while", "binary", "payloads", "rejected", "ordinary", "namespace", "writes", "open", "image", "stored", "await", "client", "blob", "products", "read", "print", "body", "readfile", "putblob", "import", "node", "promises", "const", "curl", "layer" ] }, { "id": "api/blobs#warm-policy", "kind": "section", "title": "Blobs", "heading": "Warm Policy", "group": "API", "url": "/docs/api/blobs#warm-policy", "summary": "Blob reads currently warm the cache on demand, with an optional write-through hint for a single object. Bulk warming is deferred until namespaces can declare blob-reference fields and enforce an explicit cache budget.", "facts": [ { "kind": "code", "literal": "PUT ...?warm=true", "chunkId": "api/blobs#warm-policy" }, { "kind": "code", "literal": "hint_cache_warm?blobs=true", "chunkId": "api/blobs#warm-policy" } ], "sources": [ { "chunkId": "api/blobs#warm-policy", "url": "/docs/api/blobs#warm-policy", "anchor": "warm-policy" } ], "mode": "source-primary", "terms": [ "warm", "policy", "blob", "reads", "currently", "cache", "demand", "optional", "write", "through", "hint", "single", "object", "bulk", "warming", "deferred", "until", "namespaces", "declare", "reference", "fields", "enforce", "explicit", "budget", "true", "blobs", "pull", "today", "miss", "backfills", "aerospike", "best", "effort", "hintcachewarm", "intentionally", "part", "first", "slice", "needs", "namespace" ] }, { "id": "api/checkpoints", "kind": "section", "title": "Checkpoints", "heading": null, "group": "API", "url": "/docs/api/checkpoints", "summary": "A checkpoint gives a stable name to the newest durable snapshot of a namespace without scanning or rewriting rows. It records the snapshot watermark, content digest, and growth since the prior checkpoint.", "facts": [ { "kind": "code", "literal": "catalog_run_id", "chunkId": "api/checkpoints" }, { "kind": "code", "literal": "watermark_ms", "chunkId": "api/checkpoints" }, { "kind": "code", "literal": "sha", "chunkId": "api/checkpoints" }, { "kind": "code", "literal": "row_count", "chunkId": "api/checkpoints" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/checkpoints" } ], "sources": [ { "chunkId": "api/checkpoints", "url": "/docs/api/checkpoints", "anchor": null } ], "mode": "source-primary", "terms": [ "checkpoint", "gives", "stable", "name", "newest", "durable", "snapshot", "namespace", "without", "scanning", "rewriting", "rows", "records", "watermark", "content", "digest", "growth", "since", "prior", "catalog", "count", "codetabs", "astro", "immutable", "labels", "watermarks", "checkpoints", "give", "application", "known", "good", "creating", "body", "stores", "small", "label", "record", "does", "scan", "write" ] }, { "id": "api/checkpoints#create", "kind": "section", "title": "Checkpoints", "heading": "Create", "group": "API", "url": "/docs/api/checkpoints#create", "summary": "Creating a namespace-local checkpoint binds its label permanently to the newest existing snapshot and is idempotent for repeated labels. Creation requires at least one durable snapshot.", "facts": [ { "kind": "code", "literal": "checkpoint = await client.create_checkpoint(\"products\", {\n \"label\": \"catalog-2026-06-15\",\n})", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "checkpoint, err := client.CreateCheckpoint(ctx, \"products\",\n &hevlayer.CreateCheckpointRequest{Label: \"catalog-2026-06-15\"})", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "const checkpoint = await client.createCheckpoint(\"products\", {\n label: \"catalog-2026-06-15\",\n});", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\": \"catalog-2026-06-15\"}'", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "{\n \"namespace\": \"products\",\n \"label\": \"catalog-2026-06-15\",\n \"watermark_ms\": 1749513600000,\n \"sha\": \"3f9e8b21...\",\n \"row_count\": 10000\n}", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "label", "chunkId": "api/checkpoints#create" }, { "kind": "code", "literal": "412 precondition_failed", "chunkId": "api/checkpoints#create" } ], "sources": [ { "chunkId": "api/checkpoints#create", "url": "/docs/api/checkpoints#create", "anchor": "create" } ], "mode": "source-primary", "terms": [ "create", "creating", "namespace", "local", "checkpoint", "binds", "label", "permanently", "newest", "existing", "snapshot", "idempotent", "repeated", "labels", "creation", "requires", "least", "durable", "await", "client", "products", "catalog", "2026", "createcheckpoint", "hevlayer", "createcheckpointrequest", "const", "curl", "post", "layer", "gateway", "namespaces", "checkpoints", "authorization", "bearer", "content", "type", "application", "json", "watermark" ] }, { "id": "api/checkpoints#list", "kind": "section", "title": "Checkpoints", "heading": "List", "group": "API", "url": "/docs/api/checkpoints#list", "summary": "Checkpoint listings are returned newest first with bounded page sizes and opaque continuation cursors.", "facts": [ { "kind": "code", "literal": "page = await client.list_checkpoints(\"products\", limit=20)", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "page, err := client.ListCheckpoints(ctx, \"products\",\n &hevlayer.ListCheckpointsParams{Limit: 20})", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "const page = await client.listCheckpoints(\"products\", { limit: 20 });", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints?limit=20\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "{\n \"checkpoints\": [\n {\n \"namespace\": \"products\",\n \"label\": \"catalog-2026-06-15\",\n \"watermark_ms\": 1749513600000,\n \"sha\": \"3f9e8b21...\",\n \"row_count\": 10000\n }\n ],\n \"next_cursor\": null\n}", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "limit", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "before", "chunkId": "api/checkpoints#list" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/checkpoints#list" } ], "sources": [ { "chunkId": "api/checkpoints#list", "url": "/docs/api/checkpoints#list", "anchor": "list" } ], "mode": "source-primary", "terms": [ "list", "checkpoint", "listings", "returned", "newest", "first", "bounded", "page", "sizes", "opaque", "continuation", "cursors", "await", "client", "checkpoints", "products", "limit", "listcheckpoints", "hevlayer", "listcheckpointsparams", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "namespace", "label", "catalog", "2026", "watermark", "1749513600000", "3f9e8b21", "count", "10000", "next", "cursor", "null", "before" ] }, { "id": "api/checkpoints#resolve", "kind": "section", "title": "Checkpoints", "heading": "Resolve", "group": "API", "url": "/docs/api/checkpoints#resolve", "summary": "Resolving a checkpoint returns the immutable snapshot label record for that namespace, or a not-found response when the label is absent.", "facts": [ { "kind": "code", "literal": "checkpoint = await client.get_checkpoint(\"products\", \"catalog-2026-06-15\")", "chunkId": "api/checkpoints#resolve" }, { "kind": "code", "literal": "checkpoint, err := client.GetCheckpoint(ctx, \"products\", \"catalog-2026-06-15\")", "chunkId": "api/checkpoints#resolve" }, { "kind": "code", "literal": "const checkpoint = await client.getCheckpoint(\"products\", \"catalog-2026-06-15\");", "chunkId": "api/checkpoints#resolve" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints/catalog-2026-06-15\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/checkpoints#resolve" }, { "kind": "code", "literal": "404 not_found", "chunkId": "api/checkpoints#resolve" } ], "sources": [ { "chunkId": "api/checkpoints#resolve", "url": "/docs/api/checkpoints#resolve", "anchor": "resolve" } ], "mode": "source-primary", "terms": [ "resolve", "resolving", "checkpoint", "returns", "immutable", "snapshot", "label", "record", "namespace", "found", "response", "absent", "await", "client", "products", "catalog", "2026", "getcheckpoint", "const", "curl", "layer", "gateway", "namespaces", "checkpoints", "authorization", "bearer", "layergatewayurl", "layergatewayapikey", "notfound", "does", "exist" ] }, { "id": "api/checkpoints#routes", "kind": "section", "title": "Checkpoints", "heading": "Routes", "group": "API", "url": "/docs/api/checkpoints#routes", "summary": "Checkpoint operations create immutable labels, list a namespace's labels, and resolve one label to its snapshot cut.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}/checkpoints", "chunkId": "api/checkpoints#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/checkpoints", "chunkId": "api/checkpoints#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/checkpoints/{label}", "chunkId": "api/checkpoints#routes" } ], "sources": [ { "chunkId": "api/checkpoints#routes", "url": "/docs/api/checkpoints#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "checkpoint", "operations", "create", "immutable", "labels", "list", "namespace", "resolve", "label", "snapshot", "post", "namespaces", "checkpoints", "route", "method", "behavior", "return", "newest", "first" ] }, { "id": "api/data-supply", "kind": "section", "title": "VectorStores And Warehouses", "heading": null, "group": "API", "url": "/docs/api/data-supply", "summary": "The gateway exposes credential-safe, read-only views of serving stores and source warehouses. Operators create or edit the underlying Kubernetes resources, while API consumers see secret references but never secret contents.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "api/data-supply" }, { "kind": "code", "literal": "Warehouse", "chunkId": "api/data-supply" }, { "kind": "code", "literal": "read", "chunkId": "api/data-supply" } ], "sources": [ { "chunkId": "api/data-supply", "url": "/docs/api/data-supply", "anchor": null } ], "mode": "source-primary", "terms": [ "gateway", "exposes", "credential", "safe", "read", "only", "views", "serving", "stores", "source", "warehouses", "operators", "create", "edit", "underlying", "kubernetes", "resources", "while", "consumers", "secret", "references", "never", "contents", "vectorstore", "warehouse", "declared", "vector", "upstream", "through", "layer", "data", "supply", "routes", "side", "connection", "pipelines", "responses", "show", "operator", "tools" ] }, { "id": "api/data-supply#vectorstores", "kind": "section", "title": "VectorStores And Warehouses", "heading": "VectorStores", "group": "API", "url": "/docs/api/data-supply#vectorstores", "summary": "Vector store views include backend kind, endpoint, default selection, authentication policy, safe credential references, reachability, and optional links to the upstream organization.", "facts": [ { "kind": "code", "literal": "curl -H \"Authorization: Bearer $LAYER_API_KEY\" \\\n \"$LAYER_BASE_URL/v2/vectorstores\"", "chunkId": "api/data-supply#vectorstores" }, { "kind": "code", "literal": "GET /v2/vectorstores/{name}", "chunkId": "api/data-supply#vectorstores" }, { "kind": "code", "literal": "turbopufferUrl", "chunkId": "api/data-supply#vectorstores" }, { "kind": "code", "literal": "spec.turbopuffer.orgId", "chunkId": "api/data-supply#vectorstores" } ], "sources": [ { "chunkId": "api/data-supply#vectorstores", "url": "/docs/api/data-supply#vectorstores", "anchor": "vectorstores" } ], "mode": "source-primary", "terms": [ "vectorstores", "vector", "store", "views", "include", "backend", "kind", "endpoint", "default", "selection", "authentication", "policy", "safe", "credential", "references", "reachability", "optional", "links", "upstream", "organization", "curl", "authorization", "bearer", "layer", "base", "name", "turbopufferurl", "spec", "turbopuffer", "orgid", "layerapikey", "layerbaseurl", "prod", "true", "https", "east", "region", "org123", "secretref", "inboundauth" ] }, { "id": "api/data-supply#warehouses", "kind": "section", "title": "VectorStores And Warehouses", "heading": "Warehouses", "group": "API", "url": "/docs/api/data-supply#warehouses", "summary": "Warehouse views expose source identity, connection-pool settings, verification state, failure context, and counts of pipelines or keys that still depend on the resource.", "facts": [ { "kind": "code", "literal": "curl -H \"Authorization: Bearer $LAYER_API_KEY\" \\\n \"$LAYER_BASE_URL/v2/warehouses\"", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "GET /v2/warehouses/{name}", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "phase", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "Pending", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "Verified", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "Failed", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "status.failureReason", "chunkId": "api/data-supply#warehouses" }, { "kind": "code", "literal": "status.consumers", "chunkId": "api/data-supply#warehouses" } ], "sources": [ { "chunkId": "api/data-supply#warehouses", "url": "/docs/api/data-supply#warehouses", "anchor": "warehouses" } ], "mode": "source-primary", "terms": [ "warehouses", "warehouse", "views", "expose", "source", "identity", "connection", "pool", "settings", "verification", "state", "failure", "context", "counts", "pipelines", "keys", "still", "depend", "resource", "curl", "authorization", "bearer", "layer", "base", "name", "phase", "pending", "verified", "failed", "status", "failurereason", "consumers", "layerapikey", "layerbaseurl", "prod", "snowflake", "kind", "account", "acme", "xy12345" ] }, { "id": "api/federated-query", "kind": "section", "title": "Federated query", "heading": null, "group": "API", "url": "/docs/api/federated-query", "summary": "A federated query fans one ranking across a chosen namespace set and merges the results into one list. It is intended for searching a whole feed or library, not for returning several independent rankings.", "facts": [ { "kind": "code", "literal": "POST /v2/query", "chunkId": "api/federated-query" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/federated-query" } ], "sources": [ { "chunkId": "api/federated-query", "url": "/docs/api/federated-query", "anchor": null } ], "mode": "source-primary", "terms": [ "federated", "query", "fans", "ranking", "across", "chosen", "namespace", "merges", "results", "list", "intended", "searching", "whole", "feed", "library", "returning", "several", "independent", "rankings", "post", "codetabs", "astro", "federate", "namespaces", "merge", "single", "ranked", "scoped", "entitlements", "runs", "less", "endpoint", "names", "path", "while", "takes", "body", "longer", "parameter", "upstream" ] }, { "id": "api/federated-query#consistency", "kind": "section", "title": "Federated query", "heading": "Consistency", "group": "API", "url": "/docs/api/federated-query#consistency", "summary": "Each namespace retains its own stable cut; Layer does not invent a global one. The response reports per-namespace freshness and uses the oldest reached cut as the conservative overall freshness signal.", "facts": [ { "kind": "code", "literal": "namespaces", "chunkId": "api/federated-query#consistency" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/federated-query#consistency" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/federated-query#consistency" } ], "sources": [ { "chunkId": "api/federated-query#consistency", "url": "/docs/api/federated-query#consistency", "anchor": "consistency" } ], "mode": "source-primary", "terms": [ "consistency", "namespace", "retains", "stable", "layer", "does", "invent", "global", "response", "reports", "freshness", "uses", "oldest", "reached", "conservative", "overall", "signal", "namespaces", "read", "watermark", "there", "single", "consistent", "across", "independent", "block", "stableasof", "header", "carries", "minimum", "most", "answer", "manufacture" ] }, { "id": "api/federated-query#entitlements", "kind": "section", "title": "Federated query", "heading": "Entitlements", "group": "API", "url": "/docs/api/federated-query#entitlements", "summary": "Every named namespace must be readable by the caller, and scoped credentials reject explicitly unauthorized names. An implicit namespace set can expand from the caller's allowed namespace patterns.", "facts": [ { "kind": "code", "literal": "namespaces", "chunkId": "api/federated-query#entitlements" }, { "kind": "code", "literal": "strict", "chunkId": "api/federated-query#entitlements" }, { "kind": "code", "literal": "vectorstore.", "chunkId": "api/federated-query#entitlements" }, { "kind": "code", "literal": "403", "chunkId": "api/federated-query#entitlements" }, { "kind": "code", "literal": "namespaces: [\"*\"]", "chunkId": "api/federated-query#entitlements" } ], "sources": [ { "chunkId": "api/federated-query#entitlements", "url": "/docs/api/federated-query#entitlements", "anchor": "entitlements" } ], "mode": "source-primary", "terms": [ "entitlements", "every", "named", "namespace", "must", "readable", "caller", "scoped", "credentials", "reject", "explicitly", "unauthorized", "names", "implicit", "expand", "allowed", "patterns", "namespaces", "strict", "vectorstore", "name", "uses", "same", "store", "derived", "authentication", "path", "individual", "queries", "upstream", "able", "read", "listed", "failure", "reported", "under", "partial", "unless", "enabled", "minted" ] }, { "id": "api/federated-query#fan-out-and-fuse", "kind": "section", "title": "Federated query", "heading": "Fan-out and fuse", "group": "API", "url": "/docs/api/federated-query#fan-out-and-fuse", "summary": "The gateway applies one ranking, shared filters, and one routing decision across the namespace set, tags each row with its origin, and returns a single fused list. The namespace set may be explicit or expanded from the authenticated allowlist.", "facts": [ { "kind": "code", "literal": "response = await client.query({\n \"namespaces\": [\"moment-pod-changelog\", \"moment-pod-latent-space\", \"moment-pod-no-priors\"],\n \"rank_by\": [\"text\", \"Auto\", \"evaluating RAG systems\"],\n \"top_k\": 12,\n \"filters\": [\"published_at\", \"Gte\", 1740000000],\n \"include_attributes\": [\"text\", \"show\", \"source_url\", \"start_sec\"],\n})", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "const response = await client.query({\n namespaces: [\"moment-pod-changelog\", \"moment-pod-latent-space\", \"moment-pod-no-priors\"],\n rank_by: [\"text\", \"Auto\", \"evaluating RAG systems\"],\n top_k: 12,\n filters: [\"published_at\", \"Gte\", 1740000000],\n include_attributes: [\"text\", \"show\", \"source_url\", \"start_sec\"],\n});", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "namespaces", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "rows", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "Auto", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "routing", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "filters", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "namespaces: [\"*\"]", "chunkId": "api/federated-query#fan-out-and-fuse" }, { "kind": "code", "literal": "[\"*\"]", "chunkId": "api/federated-query#fan-out-and-fuse" } ], "sources": [ { "chunkId": "api/federated-query#fan-out-and-fuse", "url": "/docs/api/federated-query#fan-out-and-fuse", "anchor": "fan-out-and-fuse" } ], "mode": "source-primary", "terms": [ "fuse", "gateway", "applies", "ranking", "shared", "filters", "routing", "decision", "across", "namespace", "tags", "origin", "returns", "single", "fused", "list", "explicit", "expanded", "authenticated", "allowlist", "response", "await", "client", "query", "namespaces", "moment", "changelog", "latent", "space", "priors", "rank", "text", "auto", "evaluating", "systems", "published", "1740000000", "include", "attributes", "show" ] }, { "id": "api/federated-query#filters", "kind": "section", "title": "Federated query", "heading": "Filters", "group": "API", "url": "/docs/api/federated-query#filters", "summary": "One filter is evaluated independently against every namespace, so all participants need compatible field types and filterability. In best-effort mode incompatible namespaces become partial errors; strict mode rejects the whole request.", "facts": [ { "kind": "code", "literal": "filters", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "filter_schema_mismatch", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "matched: 0", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "rows", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "errors", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "x-layer-partial: true", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "strict: true", "chunkId": "api/federated-query#filters" }, { "kind": "code", "literal": "422", "chunkId": "api/federated-query#filters" } ], "sources": [ { "chunkId": "api/federated-query#filters", "url": "/docs/api/federated-query#filters", "anchor": "filters" } ], "mode": "source-primary", "terms": [ "filters", "filter", "evaluated", "independently", "against", "every", "namespace", "participants", "need", "compatible", "field", "types", "filterability", "best", "effort", "mode", "incompatible", "namespaces", "become", "partial", "errors", "strict", "rejects", "whole", "request", "schema", "mismatch", "matched", "rows", "layer", "true", "expression", "applied", "evaluates", "only", "behaves", "uniformly", "attributes", "references", "part" ] }, { "id": "api/federated-query#fusion-options", "kind": "section", "title": "Federated query", "heading": "Fusion options", "group": "API", "url": "/docs/api/federated-query#fusion-options", "summary": "Fusion can limit how deeply each namespace contributes before merging, avoiding wasted retrieval across wide fan-outs. A reserved tuning value is accepted for future compatibility but currently has no effect.", "facts": [ { "kind": "code", "literal": "fusion.per_namespace_limit", "chunkId": "api/federated-query#fusion-options" }, { "kind": "code", "literal": "clamp(2 × top_k, 10, 100)", "chunkId": "api/federated-query#fusion-options" }, { "kind": "code", "literal": "per_leg_limit", "chunkId": "api/federated-query#fusion-options" }, { "kind": "code", "literal": "top_k", "chunkId": "api/federated-query#fusion-options" }, { "kind": "code", "literal": "fusion.rank_constant", "chunkId": "api/federated-query#fusion-options" }, { "kind": "code", "literal": "60", "chunkId": "api/federated-query#fusion-options" } ], "sources": [ { "chunkId": "api/federated-query#fusion-options", "url": "/docs/api/federated-query#fusion-options", "anchor": "fusion-options" } ], "mode": "source-primary", "terms": [ "fusion", "options", "limit", "deeply", "namespace", "contributes", "before", "merging", "avoiding", "wasted", "retrieval", "across", "wide", "outs", "reserved", "tuning", "value", "accepted", "future", "compatibility", "currently", "effect", "clamp", "rank", "constant", "option", "default", "meaning", "pernamespacelimit", "topk", "many", "rows", "returns", "merge", "shallower", "single", "perleglimit", "most", "namespaces", "contribute" ] }, { "id": "api/federated-query#limits", "kind": "section", "title": "Federated query", "heading": "Limits", "group": "API", "url": "/docs/api/federated-query#limits", "summary": "Federated search caps the number of namespaces in one request and does not support pagination because independent namespace rankings cannot form a reliable global cursor.", "facts": [ { "kind": "code", "literal": "422", "chunkId": "api/federated-query#limits" }, { "kind": "code", "literal": "cursor", "chunkId": "api/federated-query#limits" } ], "sources": [ { "chunkId": "api/federated-query#limits", "url": "/docs/api/federated-query#limits", "anchor": "limits" } ], "mode": "source-primary", "terms": [ "limits", "federated", "search", "caps", "number", "namespaces", "request", "does", "support", "pagination", "because", "independent", "namespace", "rankings", "cannot", "form", "reliable", "global", "cursor", "limit", "value", "naming", "excess", "supported", "rejected", "fused", "across", "monotone", "bands", "relies" ] }, { "id": "api/federated-query#merge", "kind": "section", "title": "Federated query", "heading": "Merge", "group": "API", "url": "/docs/api/federated-query#merge", "summary": "Vector results can merge by distance only when namespaces share one embedding geometry. Text scores are corpus-specific, so text search interleaves per-namespace ranks and retains native scores only as provenance.", "facts": [ { "kind": "code", "literal": "ANN", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "$dist", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "merge.method", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "\"distance\"", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "BM25", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "fused", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "$score", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "$rank", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "id", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "\"rank-interleave\"", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "top_k", "chunkId": "api/federated-query#merge" }, { "kind": "code", "literal": "fusion.per_namespace_limit", "chunkId": "api/federated-query#merge" } ], "sources": [ { "chunkId": "api/federated-query#merge", "url": "/docs/api/federated-query#merge", "anchor": "merge" } ], "mode": "source-primary", "terms": [ "merge", "vector", "results", "distance", "only", "namespaces", "share", "embedding", "geometry", "text", "scores", "corpus", "specific", "search", "interleaves", "namespace", "ranks", "retains", "native", "provenance", "dist", "method", "bm25", "hybridtext", "fused", "hybrid", "score", "rank", "interleave", "fusion", "limit", "federated", "query", "merges", "quantity", "route", "makes", "comparable", "across", "distances" ] }, { "id": "api/federated-query#partial-failure", "kind": "section", "title": "Federated query", "heading": "Partial failure", "group": "API", "url": "/docs/api/federated-query#partial-failure", "summary": "Best-effort fan-out returns successful namespaces and records unavailable or incompatible ones without blanking the full search. Strict mode instead fails the whole request when any participant cannot contribute.", "facts": [ { "kind": "code", "literal": "{\n \"rows\": [ \"...\" ],\n \"errors\": [\n { \"namespace\": \"moment-pod-no-priors\", \"error\": \"Upstream error: namespace not found\" }\n ]\n}", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "{\n \"rows\": [\n { \"id\": \"ep123#7\", \"$namespace\": \"moment-pod-latent-space\", \"$rank\": 1 }\n ],\n \"errors\": [\n {\n \"namespace\": \"moment-pod-no-priors\",\n \"code\": \"filter_schema_mismatch\",\n \"error\": \"filter schema mismatch\",\n \"detail\": \"filter attribute published_at is absent, not filterable, or has an incompatible type\"\n }\n ]\n}", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "errors", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "x-layer-partial: true", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "error", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "namespace", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "code: \"filter_schema_mismatch\"", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "detail", "chunkId": "api/federated-query#partial-failure" }, { "kind": "code", "literal": "\"strict\": true", "chunkId": "api/federated-query#partial-failure" } ], "sources": [ { "chunkId": "api/federated-query#partial-failure", "url": "/docs/api/federated-query#partial-failure", "anchor": "partial-failure" } ], "mode": "source-primary", "terms": [ "partial", "failure", "best", "effort", "returns", "successful", "namespaces", "records", "unavailable", "incompatible", "ones", "without", "blanking", "full", "search", "strict", "mode", "instead", "fails", "whole", "request", "participant", "cannot", "contribute", "rows", "errors", "namespace", "moment", "priors", "error", "upstream", "found", "ep123", "latent", "space", "rank", "code", "filter", "schema", "mismatch" ] }, { "id": "api/federated-query#response", "kind": "section", "title": "Federated query", "heading": "Response", "group": "API", "url": "/docs/api/federated-query#response", "summary": "The response contains one list with row origins and local ranks, a description of the merge strategy, and freshness and contribution counts for every reached namespace. Native scores are generally local provenance unless a vector distance merge is valid.", "facts": [ { "kind": "code", "literal": "$namespace", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "$rank", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "merge", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "namespaces", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "$score", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "$dist", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "method", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "\"distance\"", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "\"rank-interleave\"", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "route", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "\"fused\"", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "matched", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "per_namespace_limit", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "top_k", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "matched: 0", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "routing", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "hybrid", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "Auto", "chunkId": "api/federated-query#response" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/federated-query#response" } ], "sources": [ { "chunkId": "api/federated-query#response", "url": "/docs/api/federated-query#response", "anchor": "response" } ], "mode": "source-primary", "terms": [ "response", "contains", "list", "origins", "local", "ranks", "description", "merge", "strategy", "freshness", "contribution", "counts", "every", "reached", "namespace", "native", "scores", "generally", "provenance", "unless", "vector", "distance", "valid", "rank", "namespaces", "score", "dist", "method", "interleave", "route", "fused", "stable", "matched", "limit", "routing", "hybrid", "auto", "hybridtext", "carries", "origin" ] }, { "id": "api/federated-query#validation", "kind": "section", "title": "Federated query", "heading": "Validation", "group": "API", "url": "/docs/api/federated-query#validation", "summary": "Validation distinguishes authorization failures, best-effort namespace errors, strict failures, filter incompatibility, invalid namespace sets, incompatible embedding profiles, unsupported pagination, and malformed rankings.", "facts": [ { "kind": "code", "literal": "errors", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "strict: true", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "filters", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "errors[].code: \"filter_schema_mismatch\"", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "x-layer-partial: true", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "namespaces", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "namespaces: [\"*\"]", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "cursor", "chunkId": "api/federated-query#validation" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/federated-query#validation" } ], "sources": [ { "chunkId": "api/federated-query#validation", "url": "/docs/api/federated-query#validation", "anchor": "validation" } ], "mode": "source-primary", "terms": [ "validation", "distinguishes", "authorization", "failures", "best", "effort", "namespace", "errors", "strict", "filter", "incompatibility", "invalid", "sets", "incompatible", "embedding", "profiles", "unsupported", "pagination", "malformed", "rankings", "true", "filters", "code", "schema", "mismatch", "layer", "partial", "namespaces", "cursor", "rank", "condition", "status", "named", "outside", "minted", "grant", "read", "fails", "upstream", "cannot" ] }, { "id": "api/federated-query#vector-merge-requires-a-matching-embedding-space", "kind": "section", "title": "Federated query", "heading": "Vector merge requires a matching embedding space", "group": "API", "url": "/docs/api/federated-query#vector-merge-requires-a-matching-embedding-space", "summary": "Distance merging requires every participating index to declare the same embedding model, dimension, normalization, and distance geometry. Best-effort queries downgrade to rank interleaving when profiles are missing or differ, while strict queries fail.", "facts": [ { "kind": "code", "literal": "spec.embedding", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "Index", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "spec.backend.distanceMetric", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "merge.method: \"distance\"", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "merge.method: \"rank-interleave\"", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "merge.downgraded_reason", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "\"missing_embedding_profile\"", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "\"embedding_profile_mismatch\"", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "strict: true", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" }, { "kind": "code", "literal": "422", "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space" } ], "sources": [ { "chunkId": "api/federated-query#vector-merge-requires-a-matching-embedding-space", "url": "/docs/api/federated-query#vector-merge-requires-a-matching-embedding-space", "anchor": "vector-merge-requires-a-matching-embedding-space" } ], "mode": "source-primary", "terms": [ "vector", "merge", "requires", "matching", "embedding", "space", "distance", "merging", "every", "participating", "index", "declare", "same", "model", "dimension", "normalization", "geometry", "best", "effort", "queries", "downgrade", "rank", "interleaving", "profiles", "missing", "differ", "while", "strict", "fail", "spec", "backend", "distancemetric", "method", "interleave", "downgraded", "reason", "profile", "mismatch", "true", "only" ] }, { "id": "api/introduction", "kind": "section", "title": "Introduction", "heading": null, "group": "API", "url": "/docs/api/introduction", "summary": "Layer accepts the backing store's native client protocol and overlays freshness, caching, and enhanced retrieval metadata, allowing existing clients to adopt the gateway with minimal request changes.", "facts": [ { "kind": "code", "literal": "x-layer-*", "chunkId": "api/introduction" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/introduction" }, { "kind": "value", "literal": "StoreSwitch.astro", "chunkId": "api/introduction" }, { "kind": "value", "literal": "StoreNote.astro", "chunkId": "api/introduction" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/introduction" }, { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "api/introduction" } ], "sources": [ { "chunkId": "api/introduction", "url": "/docs/api/introduction", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "accepts", "backing", "store", "native", "client", "protocol", "overlays", "freshness", "caching", "enhanced", "retrieval", "metadata", "allowing", "existing", "clients", "adopt", "gateway", "minimal", "request", "changes", "codetabs", "astro", "storeswitch", "storenote", "upstream", "featuregate", "adds", "turbopuffer", "compatible", "wire", "point", "speaks", "adding", "fields", "needs", "through", "headers", "pointing", "just" ] }, { "id": "api/introduction#authentication", "kind": "section", "title": "Introduction", "heading": "Authentication", "group": "API", "url": "/docs/api/introduction#authentication", "summary": "Requests use either the default store credential with administrative access or a gateway-minted credential scoped by resource, namespace, and operation. Connection settings identify the gateway and bearer, while generated clients remain aligned through the shared specification.", "facts": [ { "kind": "code", "literal": "Authorization: Bearer ", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "VectorStore", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "read", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "write", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "admin", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "LAYER_GATEWAY_URL", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "keys", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "TURBOPUFFER_API_KEY", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "TURBOPUFFER_API_URL", "chunkId": "api/introduction#authentication" }, { "kind": "code", "literal": "https://aws-us-east-1.turbopuffer.com", "chunkId": "api/introduction#authentication" } ], "sources": [ { "chunkId": "api/introduction#authentication", "url": "/docs/api/introduction#authentication", "anchor": "authentication" } ], "mode": "source-primary", "terms": [ "authentication", "requests", "either", "default", "store", "credential", "administrative", "access", "gateway", "minted", "scoped", "resource", "namespace", "operation", "connection", "settings", "identify", "bearer", "while", "generated", "clients", "remain", "aligned", "through", "shared", "specification", "authorization", "vectorstore", "read", "write", "admin", "layer", "derivefromstore", "keys", "turbopuffer", "https", "east", "every", "request", "carries" ] }, { "id": "api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm", "kind": "section", "title": "Introduction", "heading": "Cache warm hint — GET /v1/namespaces/{ns}/hint_cache_warm", "group": "API", "url": "/docs/api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm", "summary": "A bare cache-warm hint passes through unchanged. Supplying warm options also lets Layer backfill the document cache and mirror the newest snapshot, with each step independently selectable.", "facts": [ { "kind": "code", "literal": "GET /v1/namespaces/{ns}/hint_cache_warm", "chunkId": "api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm" } ], "sources": [ { "chunkId": "api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm", "url": "/docs/api/introduction#cache-warm-hint--get-v1namespacesnshint_cache_warm", "anchor": "cache-warm-hint--get-v1namespacesnshint_cache_warm" } ], "mode": "source-primary", "terms": [ "cache", "warm", "hint", "namespaces", "bare", "passes", "through", "unchanged", "supplying", "options", "also", "lets", "layer", "backfill", "document", "mirror", "newest", "snapshot", "step", "independently", "selectable", "turbopuffer", "hintcachewarm", "upstream", "contract", "query", "parameters", "passthrough", "response", "returned", "verbatim", "option", "supplied", "forwards", "runs", "side", "steps", "aerospike", "origin", "plus" ] }, { "id": "api/introduction#compatibility-posture", "kind": "section", "title": "Introduction", "heading": "Compatibility posture", "group": "API", "url": "/docs/api/introduction#compatibility-posture", "summary": "Layer preserves upstream client compatibility and places gateway-only behavior in a distinct API space. Unknown routes return not found instead of being silently redirected upstream.", "facts": [ { "kind": "code", "literal": "/v2/", "chunkId": "api/introduction#compatibility-posture" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/introduction#compatibility-posture" } ], "sources": [ { "chunkId": "api/introduction#compatibility-posture", "url": "/docs/api/introduction#compatibility-posture", "anchor": "compatibility-posture" } ], "mode": "source-primary", "terms": [ "compatibility", "posture", "layer", "preserves", "upstream", "client", "places", "gateway", "only", "behavior", "distinct", "space", "unknown", "routes", "return", "found", "instead", "being", "silently", "redirected", "turbopuffer", "drop", "existing", "clients", "does", "implement", "namespaced", "under", "shadow", "request", "route", "doesn", "proxy", "returns", "rather", "routed", "might", "handle", "differently" ] }, { "id": "api/introduction#cross-cutting-conventions", "kind": "section", "title": "Introduction", "heading": "Cross-cutting conventions", "group": "API", "url": "/docs/api/introduction#cross-cutting-conventions", "summary": "Layer reserves its own document attributes, stamps write watermarks server-side, treats backing-store failures as hard, and treats document-cache failures as soft. Response metadata distinguishes cache outcomes and carries pagination separately from compatible bodies.", "facts": [ { "kind": "code", "literal": "_hevlayer_*", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "_hevlayer_", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "_hevlayer_upserted_at", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "x-layer-cache", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "hit", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "miss", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "miss-on-error", "chunkId": "api/introduction#cross-cutting-conventions" }, { "kind": "code", "literal": "x-layer-next-cursor", "chunkId": "api/introduction#cross-cutting-conventions" } ], "sources": [ { "chunkId": "api/introduction#cross-cutting-conventions", "url": "/docs/api/introduction#cross-cutting-conventions", "anchor": "cross-cutting-conventions" } ], "mode": "source-primary", "terms": [ "cross", "cutting", "conventions", "layer", "reserves", "document", "attributes", "stamps", "write", "watermarks", "server", "side", "treats", "backing", "store", "failures", "hard", "cache", "soft", "response", "metadata", "distinguishes", "outcomes", "carries", "pagination", "separately", "compatible", "bodies", "hevlayer", "upserted", "miss", "error", "next", "cursor", "these", "apply", "every", "endpoint", "proxies", "whether" ] }, { "id": "api/introduction#enhancements-to-upstream-routes", "kind": "section", "title": "Introduction", "heading": "Enhancements to upstream routes", "group": "API", "url": "/docs/api/introduction#enhancements-to-upstream-routes", "summary": "Enhanced upstream routes keep their native wire contract, and the documentation describes only Layer's additional behavior.", "facts": [], "sources": [ { "chunkId": "api/introduction#enhancements-to-upstream-routes", "url": "/docs/api/introduction#enhancements-to-upstream-routes", "anchor": "enhancements-to-upstream-routes" } ], "mode": "source-primary", "terms": [ "enhancements", "upstream", "routes", "enhanced", "keep", "their", "native", "wire", "contract", "documentation", "describes", "only", "layer", "additional", "behavior", "below", "compatible", "turbopuffer", "body", "section", "overlays" ] }, { "id": "api/introduction#gateway-failures", "kind": "section", "title": "Introduction", "heading": "Gateway failures", "group": "API", "url": "/docs/api/introduction#gateway-failures", "summary": "Generated clients return the original connection failure when the gateway is unreachable and do not choose a backing store themselves, preserving a backend-neutral client surface.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "api/introduction#gateway-failures" } ], "sources": [ { "chunkId": "api/introduction#gateway-failures", "url": "/docs/api/introduction#gateway-failures", "anchor": "gateway-failures" } ], "mode": "source-primary", "terms": [ "gateway", "failures", "generated", "clients", "return", "original", "connection", "failure", "unreachable", "choose", "backing", "store", "themselves", "preserving", "backend", "neutral", "client", "surface", "vectorstore", "python", "typescript", "sdks", "talk", "layer", "error", "returned", "retry", "directly", "against", "because", "server", "chooses", "namespace", "stays" ] }, { "id": "api/introduction#install", "kind": "section", "title": "Introduction", "heading": "Install", "group": "API", "url": "/docs/api/introduction#install", "summary": "Layer can be called from generated Python, Go, or TypeScript clients or directly over HTTP. All surfaces derive from one API specification and expose the same operations.", "facts": [ { "kind": "code", "literal": "pip install hevlayer # Python 3.11+\ngo get github.com/hev/layer-go # Go 1.22+\nnpm install hevlayer # Node 18+", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "import os\n\nfrom hevlayer import AsyncHevlayer\n\nclient = AsyncHevlayer(\n base_url=os.environ[\"LAYER_GATEWAY_URL\"],\n api_key=os.environ[\"LAYER_GATEWAY_API_KEY\"],\n)", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "import (\n \"os\"\n\n hevlayer \"github.com/hev/layer-go\"\n)\n\nclient := hevlayer.NewClient(\n hevlayer.WithBaseURL(os.Getenv(\"LAYER_GATEWAY_URL\")),\n hevlayer.WithAPIKey(os.Getenv(\"LAYER_GATEWAY_API_KEY\")),\n)", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "import { Hevlayer } from \"hevlayer\";\n\nconst client = new Hevlayer({\n baseUrl: process.env.LAYER_GATEWAY_URL,\n apiKey: process.env.LAYER_GATEWAY_API_KEY,\n});", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "apps/layer-gateway/openapi.yaml", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "client", "chunkId": "api/introduction#install" }, { "kind": "code", "literal": "ctx context.Context", "chunkId": "api/introduction#install" } ], "sources": [ { "chunkId": "api/introduction#install", "url": "/docs/api/introduction#install", "anchor": "install" } ], "mode": "source-primary", "terms": [ "install", "layer", "called", "generated", "python", "typescript", "clients", "directly", "http", "surfaces", "derive", "specification", "expose", "same", "operations", "hevlayer", "github", "node", "import", "asynchevlayer", "client", "base", "environ", "gateway", "newclient", "withbaseurl", "getenv", "withapikey", "const", "baseurl", "process", "apikey", "curl", "namespaces", "authorization", "bearer", "apps", "openapi", "yaml", "context" ] }, { "id": "api/introduction#metadata--get-v2namespacesnsmetadata", "kind": "section", "title": "Introduction", "heading": "Metadata — GET /v2/namespaces/{ns}/metadata", "group": "API", "url": "/docs/api/introduction#metadata--get-v2namespacesnsmetadata", "summary": "Namespace metadata passes through the upstream schema, counts, status, and timestamps, then adds Layer's current stability and stable-cut signals.", "facts": [ { "kind": "code", "literal": "GET /v2/namespaces/{ns}/metadata", "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata" }, { "kind": "code", "literal": "layer", "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata" }, { "kind": "code", "literal": "is_stable", "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata" } ], "sources": [ { "chunkId": "api/introduction#metadata--get-v2namespacesnsmetadata", "url": "/docs/api/introduction#metadata--get-v2namespacesnsmetadata", "anchor": "metadata--get-v2namespacesnsmetadata" } ], "mode": "source-primary", "terms": [ "metadata", "namespaces", "namespace", "passes", "through", "upstream", "schema", "counts", "status", "timestamps", "adds", "layer", "current", "stability", "stable", "signals", "turbopuffer", "contract", "count", "index", "proxied", "verbatim", "enriched", "block", "containing", "stableasof", "isstable", "page" ] }, { "id": "api/introduction#query--post-v2namespacesnsquery", "kind": "section", "title": "Introduction", "heading": "Query — POST /v2/namespaces/{ns}/query", "group": "API", "url": "/docs/api/introduction#query--post-v2namespacesnsquery", "summary": "Query keeps the native vector and text contract while protecting reads from partially indexed writes with a stable-cut predicate when needed. It can retry once under write pressure and reports the freshness cut used.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}/query", "chunkId": "api/introduction#query--post-v2namespacesnsquery" }, { "kind": "code", "literal": "_hevlayer_upserted_at <= watermark", "chunkId": "api/introduction#query--post-v2namespacesnsquery" }, { "kind": "code", "literal": "updating", "chunkId": "api/introduction#query--post-v2namespacesnsquery" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/introduction#query--post-v2namespacesnsquery" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/introduction#query--post-v2namespacesnsquery" } ], "sources": [ { "chunkId": "api/introduction#query--post-v2namespacesnsquery", "url": "/docs/api/introduction#query--post-v2namespacesnsquery", "anchor": "query--post-v2namespacesnsquery" } ], "mode": "source-primary", "terms": [ "query", "post", "namespaces", "keeps", "native", "vector", "text", "contract", "while", "protecting", "reads", "partially", "indexed", "writes", "stable", "predicate", "needed", "retry", "once", "under", "write", "pressure", "reports", "freshness", "hevlayer", "upserted", "watermark", "updating", "layer", "turbopuffer", "upstream", "queries", "request", "shape", "ranking", "filters", "attribute", "selection", "injected", "hevlayerupsertedat" ] }, { "id": "api/introduction#write--post-v2namespacesns", "kind": "section", "title": "Introduction", "heading": "Write — POST /v2/namespaces/{ns}", "group": "API", "url": "/docs/api/introduction#write--post-v2namespacesns", "summary": "Writes preserve upstream upsert, delete, and patch semantics while adding best-effort cache mirroring and a server-owned timestamp used by stable reads. Caller attempts to write reserved fields are rejected.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}", "chunkId": "api/introduction#write--post-v2namespacesns" }, { "kind": "code", "literal": "patch_rows", "chunkId": "api/introduction#write--post-v2namespacesns" }, { "kind": "code", "literal": "_hevlayer_upserted_at", "chunkId": "api/introduction#write--post-v2namespacesns" }, { "kind": "code", "literal": "_hevlayer_*", "chunkId": "api/introduction#write--post-v2namespacesns" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/introduction#write--post-v2namespacesns" } ], "sources": [ { "chunkId": "api/introduction#write--post-v2namespacesns", "url": "/docs/api/introduction#write--post-v2namespacesns", "anchor": "write--post-v2namespacesns" } ], "mode": "source-primary", "terms": [ "write", "post", "namespaces", "writes", "preserve", "upstream", "upsert", "delete", "patch", "semantics", "while", "adding", "best", "effort", "cache", "mirroring", "server", "owned", "timestamp", "stable", "reads", "caller", "attempts", "reserved", "fields", "rejected", "rows", "hevlayer", "upserted", "turbopuffer", "contract", "patchrows", "aerospike", "document", "mirror", "before", "explicit", "stamped", "hevlayerupsertedat", "every" ] }, { "id": "api/keys", "kind": "section", "title": "API keys", "heading": null, "group": "API", "url": "/docs/api/keys", "summary": "Layer can mint, verify, and revoke credentials whose entitlements target serving stores, warehouses, or Layer itself. The default store credential remains the bootstrap administrative bearer.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "api/keys" }, { "kind": "code", "literal": "Warehouse", "chunkId": "api/keys" }, { "kind": "code", "literal": "ApiKey", "chunkId": "api/keys" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/keys" } ], "sources": [ { "chunkId": "api/keys", "url": "/docs/api/keys", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "mint", "verify", "revoke", "credentials", "whose", "entitlements", "target", "serving", "stores", "warehouses", "itself", "default", "store", "credential", "remains", "bootstrap", "administrative", "bearer", "vectorstore", "warehouse", "apikey", "codetabs", "astro", "keys", "rest", "open", "mints", "opens", "declared", "resource", "entitlement", "names", "carries", "scopes", "claims", "page", "covers", "model", "surface" ] }, { "id": "api/keys#authenticate", "kind": "section", "title": "API keys", "heading": "Authenticate", "group": "API", "url": "/docs/api/keys#authenticate", "summary": "External applications can exchange a presented token for a stable actor identity and entitlement map, then interpret opaque claims themselves. Invalid, expired, and revoked tokens are deliberately indistinguishable and the operation is rate-limited.", "facts": [ { "kind": "code", "literal": "identity = await client.authenticate_key({\"token\": presented})\nclaims = identity.entitlements[\"warehouse.prod-snowflake\"].claims", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "identity, err := client.AuthenticateKey(ctx, &hevlayer.AuthenticateKeyRequest{\n\tToken: presented,\n})\nclaims := identity.Entitlements[\"warehouse.prod-snowflake\"].Claims", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "const identity = await client.authenticateKey({ token: presented });\nconst claims = identity.entitlements[\"warehouse.prod-snowflake\"].claims;", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/keys/authenticate\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"token\": \"hvl_iqGFsDD2PNkyhCqr59jjvKuKL47vqXMz\"}'", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "keyId", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "200", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "{keyId, name, owner, entitlements, expiresAt}", "chunkId": "api/keys#authenticate" }, { "kind": "code", "literal": "401", "chunkId": "api/keys#authenticate" } ], "sources": [ { "chunkId": "api/keys#authenticate", "url": "/docs/api/keys#authenticate", "anchor": "authenticate" } ], "mode": "source-primary", "terms": [ "authenticate", "external", "applications", "exchange", "presented", "token", "stable", "actor", "identity", "entitlement", "interpret", "opaque", "claims", "themselves", "invalid", "expired", "revoked", "tokens", "deliberately", "indistinguishable", "operation", "rate", "limited", "await", "client", "entitlements", "warehouse", "prod", "snowflake", "authenticatekey", "hevlayer", "authenticatekeyrequest", "const", "curl", "post", "layer", "gateway", "keys", "content", "type" ] }, { "id": "api/keys#cli", "kind": "section", "title": "API keys", "heading": "CLI", "group": "API", "url": "/docs/api/keys#cli", "summary": "The command-line client supports minting, listing, revoking, and rare permanent removal. Newly minted token material is printed once in a pipe-friendly form while metadata is separated.", "facts": [ { "kind": "code", "literal": "layer keys mint cohort-reader --owner acme \\\n --entitle vectorstore.prod-turbopuffer=read \\\n --namespaces \"cohort-*\" \\\n --claim warehouse.prod-snowflake=\"notes:cohort:*:read\"\nlayer keys ls\nlayer keys revoke cohort-reader\n# Rare cleanup after the retention period:\nlayer keys rm cohort-reader", "chunkId": "api/keys#cli" }, { "kind": "code", "literal": "layer keys mint", "chunkId": "api/keys#cli" } ], "sources": [ { "chunkId": "api/keys#cli", "url": "/docs/api/keys#cli", "anchor": "cli" } ], "mode": "source-primary", "terms": [ "command", "line", "client", "supports", "minting", "listing", "revoking", "rare", "permanent", "removal", "newly", "minted", "token", "material", "printed", "once", "pipe", "friendly", "form", "while", "metadata", "separated", "layer", "keys", "mint", "cohort", "reader", "owner", "acme", "entitle", "vectorstore", "prod", "turbopuffer", "read", "namespaces", "claim", "warehouse", "snowflake", "notes", "revoke" ] }, { "id": "api/keys#key-model", "kind": "section", "title": "API keys", "heading": "Key model", "group": "API", "url": "/docs/api/keys#key-model", "summary": "Raw token material is revealed once and only a one-way hash is retained. Revocation is the normal lifecycle end because it preserves the audit record; permanent deletion requires prior revocation and removes that history.", "facts": [ { "kind": "code", "literal": "hvl_iqGFsDD2PNkyhCqr59jjvKuKL47vqXMz", "chunkId": "api/keys#key-model" }, { "kind": "code", "literal": "ApiKey", "chunkId": "api/keys#key-model" }, { "kind": "code", "literal": "is the audit trail, and", "chunkId": "api/keys#key-model" }, { "kind": "code", "literal": "Revoked", "chunkId": "api/keys#key-model" } ], "sources": [ { "chunkId": "api/keys#key-model", "url": "/docs/api/keys#key-model", "anchor": "key-model" } ], "mode": "source-primary", "terms": [ "model", "token", "material", "revealed", "once", "only", "hash", "retained", "revocation", "normal", "lifecycle", "because", "preserves", "audit", "record", "permanent", "deletion", "requires", "prior", "removes", "history", "iqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "apikey", "trail", "revoked", "tokens", "look", "like", "hvliqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "returned", "mint", "response", "layer", "stores", "hashes", "lost", "minted", "never", "recovered", "every" ] }, { "id": "api/keys#kubectl", "kind": "section", "title": "API keys", "heading": "kubectl", "group": "API", "url": "/docs/api/keys#kubectl", "summary": "Credentials can also be authored as Kubernetes resources, with the operator creating token material in a referenced Secret. Kubernetes and REST representations round-trip through the same schema.", "facts": [ { "kind": "code", "literal": "kubectl apply -f key.yaml\nkubectl get apikeys -n layer\nkubectl get secret apikey-cohort-reader -n layer -o jsonpath='{.data.token}' | base64 -d", "chunkId": "api/keys#kubectl" }, { "kind": "code", "literal": "ApiKey", "chunkId": "api/keys#kubectl" }, { "kind": "code", "literal": "status.secretRef", "chunkId": "api/keys#kubectl" }, { "kind": "code", "literal": "and", "chunkId": "api/keys#kubectl" }, { "kind": "flag", "literal": "-o", "chunkId": "api/keys#kubectl" } ], "sources": [ { "chunkId": "api/keys#kubectl", "url": "/docs/api/keys#kubectl", "anchor": "kubectl" } ], "mode": "source-primary", "terms": [ "kubectl", "credentials", "also", "authored", "kubernetes", "resources", "operator", "creating", "token", "material", "referenced", "secret", "rest", "representations", "round", "trip", "through", "same", "schema", "apply", "yaml", "apikeys", "layer", "apikey", "cohort", "reader", "jsonpath", "data", "base64", "status", "secretref", "other", "authoring", "surface", "credential", "mints", "named", "both", "surfaces", "keys" ] }, { "id": "api/keys#list-and-get", "kind": "section", "title": "API keys", "heading": "List and get", "group": "API", "url": "/docs/api/keys#list-and-get", "summary": "Key listings and detail views expose identity, ownership, entitlements, lifecycle, expiry, and rate-limited last-use metadata, but never token material or recoverable hashes.", "facts": [ { "kind": "code", "literal": "keys = await client.list_keys()\nkey = await client.get_key(\"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\")", "chunkId": "api/keys#list-and-get" }, { "kind": "code", "literal": "keys, err := client.ListKeys(ctx, nil)\nkey, err := client.GetKey(ctx, \"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\")", "chunkId": "api/keys#list-and-get" }, { "kind": "code", "literal": "const keys = await client.listKeys();\nconst key = await client.getKey(\"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\");", "chunkId": "api/keys#list-and-get" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/keys\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/keys#list-and-get" }, { "kind": "code", "literal": "lastSeenAt", "chunkId": "api/keys#list-and-get" } ], "sources": [ { "chunkId": "api/keys#list-and-get", "url": "/docs/api/keys#list-and-get", "anchor": "list-and-get" } ], "mode": "source-primary", "terms": [ "list", "listings", "detail", "views", "expose", "identity", "ownership", "entitlements", "lifecycle", "expiry", "rate", "limited", "last", "metadata", "never", "token", "material", "recoverable", "hashes", "keys", "await", "client", "0a1b2c3d", "4e5f", "6071", "8293", "a4b5c6d7e8f9", "listkeys", "getkey", "const", "curl", "layer", "gateway", "authorization", "bearer", "lastseenat", "layergatewayurl", "layergatewayapikey", "keyid", "name" ] }, { "id": "api/keys#mint", "kind": "section", "title": "API keys", "heading": "Mint", "group": "API", "url": "/docs/api/keys#mint", "summary": "Minting creates a uniquely named credential with optional ownership, description, resource entitlements, claims, and expiry. The token appears only in the successful creation response, missing targets grant nothing, and administrative credentials may mint more keys.", "facts": [ { "kind": "code", "literal": "const key = await client.mintKey({\n name: \"cohort-reader\",\n owner: \"acme\",\n entitlements: {\n \"vectorstore.prod-turbopuffer\": {\n scopes: [\"read\"],\n namespaces: [\"cohort-*\"],\n },\n \"warehouse.prod-snowflake\": {\n claims: [\"notes:cohort:*:read\"],\n },\n },\n expiresAfter: \"365d\",\n});\nconsole.log(key.token); // shown once, never again", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "201 Created", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "name", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "ApiKey", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "owner", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "description", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "entitlements", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "vectorstore.", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "warehouse.", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "layer", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "expiresAfter", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "never", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "365d", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "expiresAt", "chunkId": "api/keys#mint" }, { "kind": "code", "literal": "EntitlementTargetMissing", "chunkId": "api/keys#mint" } ], "sources": [ { "chunkId": "api/keys#mint", "url": "/docs/api/keys#mint", "anchor": "mint" } ], "mode": "source-primary", "terms": [ "mint", "minting", "creates", "uniquely", "named", "credential", "optional", "ownership", "description", "resource", "entitlements", "claims", "expiry", "token", "appears", "only", "successful", "creation", "response", "missing", "targets", "grant", "nothing", "administrative", "credentials", "more", "keys", "const", "await", "client", "mintkey", "name", "cohort", "reader", "owner", "acme", "vectorstore", "prod", "turbopuffer", "scopes" ] }, { "id": "api/keys#revoke-by-default", "kind": "section", "title": "API keys", "heading": "Revoke by default", "group": "API", "url": "/docs/api/keys#revoke-by-default", "summary": "Rotate credentials by minting and deploying a replacement before revoking the old one. Revoked records remain for audit until an external retention policy permits deliberate permanent deletion.", "facts": [ { "kind": "code", "literal": "await client.revoke_key(\"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\")", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "_, err := client.RevokeKey(ctx, \"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\")", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "await client.revokeKey(\"0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9\");", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/keys/$KEY_ID/revoke\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "curl -X DELETE \"$LAYER_GATEWAY_URL/v2/keys/$KEY_ID\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "?includeRevoked", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "Revoked", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "Active", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "Pending", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "Expired", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "409 Conflict", "chunkId": "api/keys#revoke-by-default" }, { "kind": "code", "literal": "ApiKey", "chunkId": "api/keys#revoke-by-default" } ], "sources": [ { "chunkId": "api/keys#revoke-by-default", "url": "/docs/api/keys#revoke-by-default", "anchor": "revoke-by-default" } ], "mode": "source-primary", "terms": [ "revoke", "default", "rotate", "credentials", "minting", "deploying", "replacement", "before", "revoking", "revoked", "records", "remain", "audit", "until", "external", "retention", "policy", "permits", "deliberate", "permanent", "deletion", "await", "client", "0a1b2c3d", "4e5f", "6071", "8293", "a4b5c6d7e8f9", "revokekey", "curl", "post", "layer", "gateway", "keys", "authorization", "bearer", "delete", "includerevoked", "active", "pending" ] }, { "id": "api/keys#routes", "kind": "section", "title": "API keys", "heading": "Routes", "group": "API", "url": "/docs/api/keys#routes", "summary": "Administrative key operations create, list, inspect, revoke, and permanently remove eligible records, while public authentication exchanges presented token material for identity and entitlements.", "facts": [ { "kind": "code", "literal": "/v2/keys", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "?includeRevoked", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "/v2/keys/{keyId}", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "/v2/keys/{keyId}/revoke", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "Revoked", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "/v2/keys/authenticate", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "layer", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "admin", "chunkId": "api/keys#routes" }, { "kind": "code", "literal": "authenticate", "chunkId": "api/keys#routes" } ], "sources": [ { "chunkId": "api/keys#routes", "url": "/docs/api/keys#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "administrative", "operations", "create", "list", "inspect", "revoke", "permanently", "remove", "eligible", "records", "while", "public", "authentication", "exchanges", "presented", "token", "material", "identity", "entitlements", "keys", "includerevoked", "keyid", "revoked", "authenticate", "layer", "admin", "route", "method", "auth", "behavior", "post", "mint", "only", "response", "contains", "metadata", "never", "adds", "expired" ] }, { "id": "api/keys#using-a-minted-key", "kind": "section", "title": "API keys", "heading": "Using a minted key", "group": "API", "url": "/docs/api/keys#using-a-minted-key", "summary": "A minted credential can access only the routes, stores, namespaces, and scopes granted by its entitlements. Claim-only credentials authenticate external applications without opening Layer routes, and minted credentials cannot be used directly against the backing store.", "facts": [ { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/cohort-7/query\" \\\n -X POST \\\n -H \"Authorization: Bearer hvl_iqGFsDD2PNkyhCqr59jjvKuKL47vqXMz\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"rank_by\": [\"text\", \"BM25\", \"acme\"], \"top_k\": 10}'", "chunkId": "api/keys#using-a-minted-key" }, { "kind": "code", "literal": "{\"error\": \"namespace not in key grant\", \"namespace\": \"orders\"}", "chunkId": "api/keys#using-a-minted-key" }, { "kind": "code", "literal": "{\"error\": \"insufficient API key scope\", \"required_scope\": \"admin\"}", "chunkId": "api/keys#using-a-minted-key" }, { "kind": "code", "literal": "vectorstore.", "chunkId": "api/keys#using-a-minted-key" } ], "sources": [ { "chunkId": "api/keys#using-a-minted-key", "url": "/docs/api/keys#using-a-minted-key", "anchor": "using-a-minted-key" } ], "mode": "source-primary", "terms": [ "minted", "credential", "access", "only", "routes", "stores", "namespaces", "scopes", "granted", "entitlements", "claim", "credentials", "authenticate", "external", "applications", "without", "opening", "layer", "cannot", "directly", "against", "backing", "store", "curl", "gateway", "cohort", "query", "post", "authorization", "bearer", "iqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "content", "type", "application", "json", "rank", "text", "bm25", "acme", "error" ] }, { "id": "api/license", "kind": "section", "title": "License", "heading": null, "group": "API", "url": "/docs/api/license", "summary": "The gateway exposes a purely local projection of its configured license and grace policy for operator and dashboard health checks; it does not contact a remote service.", "facts": [ { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/license\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/license" }, { "kind": "code", "literal": "GET /v2/license", "chunkId": "api/license" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/license" } ], "sources": [ { "chunkId": "api/license", "url": "/docs/api/license", "anchor": null } ], "mode": "source-primary", "terms": [ "gateway", "exposes", "purely", "local", "projection", "configured", "license", "grace", "policy", "operator", "dashboard", "health", "checks", "does", "contact", "remote", "service", "curl", "layer", "authorization", "bearer", "codetabs", "astro", "read", "state", "returns", "oracle", "never", "phones", "home", "derives", "plus", "codified", "cushion", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/license#client-call", "kind": "section", "title": "License", "heading": "Client Call", "group": "API", "url": "/docs/api/license#client-call", "summary": "Clients can retrieve the local license projection and inspect the gateway's current enforcement state.", "facts": [ { "kind": "code", "literal": "state = await client.get_license()\nprint(state.gateway.state)", "chunkId": "api/license#client-call" }, { "kind": "code", "literal": "state, err := client.GetLicense(ctx)\nif err != nil {\n return err\n}\nfmt.Println(state.Gateway.State)", "chunkId": "api/license#client-call" }, { "kind": "code", "literal": "const state = await client.getLicense();\nconsole.log(state.gateway.state);", "chunkId": "api/license#client-call" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/license\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/license#client-call" } ], "sources": [ { "chunkId": "api/license#client-call", "url": "/docs/api/license#client-call", "anchor": "client-call" } ], "mode": "source-primary", "terms": [ "client", "call", "clients", "retrieve", "local", "license", "projection", "inspect", "gateway", "current", "enforcement", "state", "await", "print", "getlicense", "return", "println", "const", "console", "curl", "layer", "authorization", "bearer", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/license#fields", "kind": "section", "title": "License", "heading": "Fields", "group": "API", "url": "/docs/api/license#fields", "summary": "License health reports validity, verifier state, subject, tier, enabled features, numeric limits, expiry, and gateway-specific deadline and grace timing. The gateway always resolves to licensed, grace, or floor behavior.", "facts": [ { "kind": "code", "literal": "valid", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "state", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "reason", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "missing", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "sub", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "tier", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "trial", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "design-partner", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "features", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "limits", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "exp", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "gateway.state", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "licensed", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "grace", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "floor", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "gateway.seconds_to_deadline", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "exp + grace", "chunkId": "api/license#fields" }, { "kind": "code", "literal": "gateway.grace_seconds_remaining", "chunkId": "api/license#fields" } ], "sources": [ { "chunkId": "api/license#fields", "url": "/docs/api/license#fields", "anchor": "fields" } ], "mode": "source-primary", "terms": [ "fields", "license", "health", "reports", "validity", "verifier", "state", "subject", "tier", "enabled", "features", "numeric", "limits", "expiry", "gateway", "specific", "deadline", "grace", "timing", "always", "resolves", "licensed", "floor", "behavior", "valid", "reason", "missing", "trial", "design", "partner", "seconds", "remaining", "field", "present", "meaning", "whether", "currently", "treats", "deployment", "invalid" ] }, { "id": "api/license#response", "kind": "section", "title": "License", "heading": "Response", "group": "API", "url": "/docs/api/license#response", "summary": "A valid or grace-period key returns its claims and remaining timing, while missing, invalid, or fully expired keys return a floor state with a reason and no remaining grace.", "facts": [ { "kind": "code", "literal": "{\n \"valid\": true,\n \"sub\": \"acme-corp\",\n \"tier\": \"design-partner\",\n \"features\": [\"transform-runtime\", \"agents\", \"rbac\", \"warehouses\", \"doc-cache\", \"history\", \"cost\"],\n \"limits\": {\"namespaces\": 50, \"udf_workers\": 20},\n \"exp\": \"2026-12-14T00:00:00Z\",\n \"gateway\": {\n \"state\": \"licensed\",\n \"seconds_to_deadline\": 1209600,\n \"grace_seconds_remaining\": 0\n }\n}", "chunkId": "api/license#response" }, { "kind": "code", "literal": "{\n \"valid\": false,\n \"state\": \"floor\",\n \"reason\": \"missing\",\n \"gateway\": {\n \"state\": \"floor\",\n \"seconds_to_deadline\": 0,\n \"grace_seconds_remaining\": 0\n }\n}", "chunkId": "api/license#response" }, { "kind": "code", "literal": "valid: true", "chunkId": "api/license#response" }, { "kind": "code", "literal": "gateway.state", "chunkId": "api/license#response" }, { "kind": "code", "literal": "grace", "chunkId": "api/license#response" }, { "kind": "code", "literal": "valid", "chunkId": "api/license#response" }, { "kind": "code", "literal": "true", "chunkId": "api/license#response" }, { "kind": "code", "literal": "grace_seconds_remaining", "chunkId": "api/license#response" }, { "kind": "code", "literal": "valid: false", "chunkId": "api/license#response" }, { "kind": "code", "literal": "reason", "chunkId": "api/license#response" }, { "kind": "code", "literal": "reason: \"missing\"", "chunkId": "api/license#response" } ], "sources": [ { "chunkId": "api/license#response", "url": "/docs/api/license#response", "anchor": "response" } ], "mode": "source-primary", "terms": [ "response", "valid", "grace", "period", "returns", "claims", "remaining", "timing", "while", "missing", "invalid", "fully", "expired", "keys", "return", "floor", "state", "reason", "true", "acme", "corp", "tier", "design", "partner", "features", "transform", "runtime", "agents", "rbac", "warehouses", "cache", "history", "cost", "limits", "namespaces", "workers", "2026", "14t00", "gateway", "licensed" ] }, { "id": "api/license#state-effects", "kind": "section", "title": "License", "heading": "State Effects", "group": "API", "url": "/docs/api/license#state-effects", "summary": "Feature-gated routes work when licensed, continue with a grace warning during the cushion, and are denied at the floor. The community gateway routes remain available in every state.", "facts": [ { "kind": "code", "literal": "licensed", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "features", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "grace", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "x-hevlayer-license-grace: true", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "floor", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "402", "chunkId": "api/license#state-effects" }, { "kind": "code", "literal": "error: \"license_required\"", "chunkId": "api/license#state-effects" } ], "sources": [ { "chunkId": "api/license#state-effects", "url": "/docs/api/license#state-effects", "anchor": "state-effects" } ], "mode": "source-primary", "terms": [ "state", "effects", "feature", "gated", "routes", "work", "licensed", "continue", "grace", "warning", "during", "cushion", "denied", "floor", "community", "gateway", "remain", "available", "every", "features", "hevlayer", "license", "true", "error", "required", "route", "behavior", "includes", "always", "works", "responses", "include", "return", "licenserequired", "query", "point", "read", "write", "scan", "namespace" ] }, { "id": "api/namespace-metadata", "kind": "section", "title": "Namespace metadata", "heading": null, "group": "API", "url": "/docs/api/namespace-metadata", "summary": "Layer preserves upstream namespace metadata and adds a compact freshness sub-object describing stability and indexing completeness.", "facts": [ { "kind": "code", "literal": "/v2/namespaces/{ns}/metadata", "chunkId": "api/namespace-metadata" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/namespace-metadata" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/namespace-metadata" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/namespace-metadata" } ], "sources": [ { "chunkId": "api/namespace-metadata", "url": "/docs/api/namespace-metadata", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "preserves", "upstream", "namespace", "metadata", "adds", "compact", "freshness", "object", "describing", "stability", "indexing", "completeness", "namespaces", "astro", "codetabs", "turbopuffer", "read", "enriched", "signals", "payload", "proxied", "verbatim", "endpoint", "schema", "counts", "index", "status", "timestamps", "follow", "contract", "single" ] }, { "id": "api/namespace-metadata#list-namespaces", "kind": "section", "title": "Namespace metadata", "heading": "List namespaces", "group": "API", "url": "/docs/api/namespace-metadata#list-namespaces", "summary": "The augmented namespace inventory combines upstream listings with stability, cache, write, and indexing signals for dashboard use. Per-row metadata errors degrade individual rows instead of making the listing incomplete, and a short cache limits polling fan-out.", "facts": [ { "kind": "code", "literal": "namespaces = await client.list_namespaces(prefix=\"prod\", page_size=100)", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "namespaces, err := client.ListNamespaces(ctx, &hevlayer.ListNamespacesParams{\n Prefix: \"prod\",\n PageSize: 100,\n})", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "const namespaces = await client.listNamespaces({\n prefix: \"prod\",\n pageSize: 100,\n});", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces?prefix=prod&page_size=100\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "{\n \"namespaces\": [\n {\n \"name\": \"products\",\n \"row_count\": 12500,\n \"size_bytes\": 48800000,\n \"stable_as_of_ms\": 1715600400000,\n \"is_stable\": true,\n \"index\": { \"status\": \"up-to-date\" },\n \"cache_state\": {\"state\": \"warm\", \"warm_inflight\": false},\n \"last_write_ms\": 1715600399000,\n \"shadow\": false,\n \"labels\": {}\n }\n ],\n \"next_cursor\": \"...\"\n}", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "GET /v2/namespaces", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "is_stable", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "index.status", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "\"up-to-date\"", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "\"updating\"", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "stable_as_of_ms", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "indexed", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "index_lag_rows", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "GET /v2/namespaces/{namespace}/metadata", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "index", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "index.unindexed_bytes", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "updating", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "prefix", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "cursor", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "page_size", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "metadata_error", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "NAMESPACE_LIST_CACHE_TTL_MS", "chunkId": "api/namespace-metadata#list-namespaces" }, { "kind": "code", "literal": "10000", "chunkId": "api/namespace-metadata#list-namespaces" } ], "sources": [ { "chunkId": "api/namespace-metadata#list-namespaces", "url": "/docs/api/namespace-metadata#list-namespaces", "anchor": "list-namespaces" } ], "mode": "source-primary", "terms": [ "list", "namespaces", "augmented", "namespace", "inventory", "combines", "upstream", "listings", "stability", "cache", "write", "indexing", "signals", "dashboard", "metadata", "errors", "degrade", "individual", "rows", "instead", "making", "listing", "incomplete", "short", "limits", "polling", "await", "client", "prefix", "prod", "page", "size", "listnamespaces", "hevlayer", "listnamespacesparams", "pagesize", "const", "curl", "layer", "gateway" ] }, { "id": "api/namespace-metadata#request", "kind": "section", "title": "Namespace metadata", "heading": "Request", "group": "API", "url": "/docs/api/namespace-metadata#request", "summary": "A namespace metadata read returns the upstream schema, approximate size and row counts, timestamps, and index status together with Layer's freshness and indexing-completeness view.", "facts": [ { "kind": "code", "literal": "metadata = await client.get_namespace_metadata(\"products\")", "chunkId": "api/namespace-metadata#request" }, { "kind": "code", "literal": "metadata, err := client.GetNamespaceMetadata(ctx, \"products\")", "chunkId": "api/namespace-metadata#request" }, { "kind": "code", "literal": "const metadata = await client.getNamespaceMetadata(\"products\");", "chunkId": "api/namespace-metadata#request" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/metadata\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/namespace-metadata#request" } ], "sources": [ { "chunkId": "api/namespace-metadata#request", "url": "/docs/api/namespace-metadata#request", "anchor": "request" } ], "mode": "source-primary", "terms": [ "request", "namespace", "metadata", "read", "returns", "upstream", "schema", "approximate", "size", "counts", "timestamps", "index", "status", "together", "layer", "freshness", "indexing", "completeness", "view", "await", "client", "products", "getnamespacemetadata", "const", "curl", "gateway", "namespaces", "authorization", "bearer", "layergatewayurl", "layergatewayapikey", "proxied", "turbopuffer", "verbatim", "approxrowcount", "12500", "approxlogicalbytes", "48800000", "createdat", "2026" ] }, { "id": "api/namespace-metadata#the-layer-block", "kind": "section", "title": "Namespace metadata", "heading": "The layer block", "group": "API", "url": "/docs/api/namespace-metadata#the-layer-block", "summary": "Current stability says whether the upstream index is caught up, while the stable watermark records the historical read cut. Indexed readiness separately compares snapshot vector coverage with namespace row count, so a namespace can be stable yet still incomplete during bulk indexing.", "facts": [ { "kind": "code", "literal": "layer", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "is_stable", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "index.status == \"up-to-date\"", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "indexed", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "index_lag_rows", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "CONSISTENCY_STABLE_POLL_INTERVAL_MS", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "CONSISTENCY_POLL_INTERVAL_MS", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "is_stable: true", "chunkId": "api/namespace-metadata#the-layer-block" }, { "kind": "code", "literal": "indexed: false", "chunkId": "api/namespace-metadata#the-layer-block" } ], "sources": [ { "chunkId": "api/namespace-metadata#the-layer-block", "url": "/docs/api/namespace-metadata#the-layer-block", "anchor": "the-layer-block" } ], "mode": "source-primary", "terms": [ "layer", "block", "current", "stability", "says", "whether", "upstream", "index", "caught", "while", "stable", "watermark", "records", "historical", "read", "indexed", "readiness", "separately", "compares", "snapshot", "vector", "coverage", "namespace", "count", "still", "incomplete", "during", "bulk", "indexing", "status", "date", "rows", "consistency", "poll", "interval", "true", "false", "field", "meaning", "stableasof" ] }, { "id": "api/pipelines", "kind": "section", "title": "Pipelines", "heading": null, "group": "API", "url": "/docs/api/pipelines", "summary": "A typical indexing pipeline separates CPU extraction and chunking from GPU embedding, with the gateway coordinating state across both stages and supporting longer staged workflows.", "facts": [ { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/pipelines" } ], "sources": [ { "chunkId": "api/pipelines", "url": "/docs/api/pipelines", "anchor": null } ], "mode": "source-primary", "terms": [ "typical", "indexing", "pipeline", "separates", "extraction", "chunking", "embedding", "gateway", "coordinating", "state", "across", "both", "stages", "supporting", "longer", "staged", "workflows", "codetabs", "astro", "organize", "stage", "extract", "chunk", "embed", "trigger", "runs", "wait", "completion", "keeps", "code", "need", "index", "data", "simple", "organized", "followed", "guide", "walks", "through", "best" ] }, { "id": "api/pipelines#deploy", "kind": "section", "title": "Pipelines", "heading": "Deploy", "group": "API", "url": "/docs/api/pipelines#deploy", "summary": "Users build and publish worker images, then apply Pipeline resources that the operator turns into deployments and autoscaling objects. The application creates gateway pipeline state before enqueueing work, preventing workers from targeting a missing queue.", "facts": [ { "kind": "code", "literal": "kubectl apply -f pipelines/", "chunkId": "api/pipelines#deploy" } ], "sources": [ { "chunkId": "api/pipelines#deploy", "url": "/docs/api/pipelines#deploy", "anchor": "deploy" } ], "mode": "source-primary", "terms": [ "deploy", "users", "build", "publish", "worker", "images", "apply", "pipeline", "resources", "operator", "turns", "deployments", "autoscaling", "objects", "application", "creates", "gateway", "state", "before", "enqueueing", "work", "preventing", "workers", "targeting", "missing", "queue", "kubectl", "pipelines", "yaml", "references", "push", "registry", "cluster", "pull", "layer", "does", "deployment", "resource", "embed", "pool" ] }, { "id": "api/pipelines#document-lifecycle", "kind": "section", "title": "Pipelines", "heading": "Document lifecycle", "group": "API", "url": "/docs/api/pipelines#document-lifecycle", "summary": "Staged chunks enter a pending state, are leased temporarily for embedding, and become indexed after vectors are written. Re-staging replaces the chunks and returns the document to pending, while expired leases recover automatically.", "facts": [ { "kind": "code", "literal": "put chunks put vectors\n (new doc) ──────────► pending ──────────────► indexed\n ▲\n │ re-stage (idempotent)", "chunkId": "api/pipelines#document-lifecycle" }, { "kind": "code", "literal": "embedding", "chunkId": "api/pipelines#document-lifecycle" }, { "kind": "code", "literal": "pending", "chunkId": "api/pipelines#document-lifecycle" } ], "sources": [ { "chunkId": "api/pipelines#document-lifecycle", "url": "/docs/api/pipelines#document-lifecycle", "anchor": "document-lifecycle" } ], "mode": "source-primary", "terms": [ "document", "lifecycle", "staged", "chunks", "enter", "pending", "state", "leased", "temporarily", "embedding", "become", "indexed", "after", "vectors", "written", "staging", "replaces", "returns", "while", "expired", "leases", "recover", "automatically", "stage", "idempotent", "stored", "waiting", "namespace", "configured", "vectorstore", "claim", "documents", "only", "worker", "lease", "expires", "resets", "reprocess", "source", "data" ] }, { "id": "api/pipelines#embed", "kind": "section", "title": "Pipelines", "heading": "Embed", "group": "API", "url": "/docs/api/pipelines#embed", "summary": "Embedding workers lease pending documents, read durable chunks, compute vectors, and write them to the configured serving store. Successful writes mark the document indexed, and crashed workers lose only their lease rather than the work.", "facts": [ { "kind": "code", "literal": "indexed", "chunkId": "api/pipelines#embed" }, { "kind": "code", "literal": "kind: search", "chunkId": "api/pipelines#embed" }, { "kind": "code", "literal": "vectors: [[...], [...]]", "chunkId": "api/pipelines#embed" }, { "kind": "code", "literal": "vector: [...]", "chunkId": "api/pipelines#embed" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "api/pipelines#embed" } ], "sources": [ { "chunkId": "api/pipelines#embed", "url": "/docs/api/pipelines#embed", "anchor": "embed" } ], "mode": "source-primary", "terms": [ "embed", "embedding", "workers", "lease", "pending", "documents", "read", "durable", "chunks", "compute", "vectors", "write", "configured", "serving", "store", "successful", "writes", "mark", "document", "indexed", "crashed", "lose", "only", "their", "rather", "work", "kind", "search", "vector", "nearest", "worker", "claims", "reads", "back", "writing", "upserts", "namespace", "vectorstore", "marks", "leased" ] }, { "id": "api/pipelines#extract-and-chunk", "kind": "section", "title": "Pipelines", "heading": "Extract and chunk", "group": "API", "url": "/docs/api/pipelines#extract-and-chunk", "summary": "CPU workers consume an external source, split documents, and stage durable chunks, which marks documents ready for embedding. The operator injects pipeline and source configuration so worker code stays reusable.", "facts": [ { "kind": "code", "literal": "pending", "chunkId": "api/pipelines#extract-and-chunk" }, { "kind": "code", "literal": "spec.sourceRef", "chunkId": "api/pipelines#extract-and-chunk" }, { "kind": "code", "literal": "sourceRef", "chunkId": "api/pipelines#extract-and-chunk" }, { "kind": "code", "literal": "pipelines/extract-chunk.yaml", "chunkId": "api/pipelines#extract-and-chunk" } ], "sources": [ { "chunkId": "api/pipelines#extract-and-chunk", "url": "/docs/api/pipelines#extract-and-chunk", "anchor": "extract-and-chunk" } ], "mode": "source-primary", "terms": [ "extract", "chunk", "workers", "consume", "external", "source", "split", "documents", "stage", "durable", "chunks", "marks", "ready", "embedding", "operator", "injects", "pipeline", "configuration", "worker", "code", "stays", "reusable", "pending", "spec", "sourceref", "pipelines", "yaml", "reads", "splits", "text", "stages", "staging", "stores", "durably", "cached", "document", "cache", "hardcodes", "nothing", "gateway" ] }, { "id": "api/pipelines#failure-model", "kind": "section", "title": "Pipelines", "heading": "Failure model", "group": "API", "url": "/docs/api/pipelines#failure-model", "summary": "Serving-store write failures keep documents recoverable for another claim, cache failures fall back to durable chunk storage, and indexing-state database failures should be retried. Lease expiry recovers work from crashed embedding workers.", "facts": [ { "kind": "code", "literal": "embedding", "chunkId": "api/pipelines#failure-model" } ], "sources": [ { "chunkId": "api/pipelines#failure-model", "url": "/docs/api/pipelines#failure-model", "anchor": "failure-model" } ], "mode": "source-primary", "terms": [ "failure", "model", "serving", "store", "write", "failures", "keep", "documents", "recoverable", "another", "claim", "cache", "fall", "back", "durable", "chunk", "storage", "indexing", "state", "database", "should", "retried", "lease", "expiry", "recovers", "work", "crashed", "embedding", "workers", "vectorstore", "hard", "vectors", "route", "returns", "document", "stays", "aerospike", "block", "reads", "backing" ] }, { "id": "api/pipelines#file-tree", "kind": "section", "title": "Pipelines", "heading": "File tree", "group": "API", "url": "/docs/api/pipelines#file-tree", "summary": "A recommended project separates resource manifests for CPU and GPU stages from worker implementations and an application entry point. Both worker resources share one pipeline identifier and queue.", "facts": [ { "kind": "code", "literal": "indexer/\n├── pipelines/\n│ ├── extract-chunk.yaml # CPU stage — Pipeline resource\n│ └── embed.yaml # GPU stage — Pipeline resource\n├── extract_chunk.py # read the source, stage chunks\n├── embed.py # claim pending docs, write vectors\n└── app.py # REST API: trigger a run, wait for completion", "chunkId": "api/pipelines#file-tree" }, { "kind": "code", "literal": "pipelineId: products", "chunkId": "api/pipelines#file-tree" } ], "sources": [ { "chunkId": "api/pipelines#file-tree", "url": "/docs/api/pipelines#file-tree", "anchor": "file-tree" } ], "mode": "source-primary", "terms": [ "file", "tree", "recommended", "project", "separates", "resource", "manifests", "stages", "worker", "implementations", "application", "entry", "point", "both", "resources", "share", "pipeline", "identifier", "queue", "indexer", "pipelines", "extract", "chunk", "yaml", "stage", "embed", "read", "source", "chunks", "claim", "pending", "docs", "write", "vectors", "rest", "trigger", "wait", "completion", "pipelineid", "products" ] }, { "id": "api/pipelines#trigger-a-run", "kind": "section", "title": "Pipelines", "heading": "Trigger a run", "group": "API", "url": "/docs/api/pipelines#trigger-a-run", "summary": "An application-facing indexing run ensures pipeline state exists, sends source documents to the external queue, waits for processing to drain, and returns the durable snapshot produced after the run.", "facts": [ { "kind": "code", "literal": "POST /index-runs", "chunkId": "api/pipelines#trigger-a-run" } ], "sources": [ { "chunkId": "api/pipelines#trigger-a-run", "url": "/docs/api/pipelines#trigger-a-run", "anchor": "trigger-a-run" } ], "mode": "source-primary", "terms": [ "trigger", "application", "facing", "indexing", "ensures", "pipeline", "state", "exists", "sends", "source", "documents", "external", "queue", "waits", "processing", "drain", "returns", "durable", "snapshot", "produced", "after", "post", "index", "runs", "exposes", "rest", "system", "endpoint", "batch", "complete", "created", "first", "target", "namespace", "code", "fastapi", "import", "hevlayer", "asynchevlayer", "hevlayererror" ] }, { "id": "api/pipelines#wait-for-completion", "kind": "section", "title": "Pipelines", "heading": "Wait for completion", "group": "API", "url": "/docs/api/pipelines#wait-for-completion", "summary": "Completion requires both an empty work queue and a later stable snapshot. Queue depth drives autoscaling, upstream waits and dead-letter reasons explain stalls, and the resulting snapshot becomes the exact application cut.", "facts": [ { "kind": "code", "literal": "pending_count", "chunkId": "api/pipelines#wait-for-completion" }, { "kind": "code", "literal": "status", "chunkId": "api/pipelines#wait-for-completion" }, { "kind": "code", "literal": "waiting_on_upstream", "chunkId": "api/pipelines#wait-for-completion" }, { "kind": "code", "literal": "failed", "chunkId": "api/pipelines#wait-for-completion" }, { "kind": "code", "literal": "failed_reasons", "chunkId": "api/pipelines#wait-for-completion" }, { "kind": "code", "literal": "{\"chunks_unavailable\": 2}", "chunkId": "api/pipelines#wait-for-completion" } ], "sources": [ { "chunkId": "api/pipelines#wait-for-completion", "url": "/docs/api/pipelines#wait-for-completion", "anchor": "wait-for-completion" } ], "mode": "source-primary", "terms": [ "wait", "completion", "requires", "both", "empty", "work", "queue", "later", "stable", "snapshot", "depth", "drives", "autoscaling", "upstream", "waits", "dead", "letter", "reasons", "explain", "stalls", "resulting", "becomes", "exact", "application", "pending", "count", "status", "waiting", "failed", "chunks", "unavailable", "complete", "steps", "drains", "consistency", "watcher", "observes", "namespace", "writes", "past" ] }, { "id": "api/query", "kind": "section", "title": "Query & Fetch", "heading": null, "group": "API", "url": "/docs/api/query", "summary": "Layer's query surface adds stable reads, cached document fetch, history, and response metadata around the backing store's native vector, text, filter, and multi-query behavior.", "facts": [ { "kind": "code", "literal": "x-layer-*", "chunkId": "api/query" }, { "kind": "code", "literal": "vector", "chunkId": "api/query" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/query" }, { "kind": "code", "literal": "filters", "chunkId": "api/query" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/query" }, { "kind": "value", "literal": "StoreSwitch.astro", "chunkId": "api/query" }, { "kind": "value", "literal": "StoreNote.astro", "chunkId": "api/query" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/query" }, { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "api/query" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/query" } ], "sources": [ { "chunkId": "api/query", "url": "/docs/api/query", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "query", "surface", "adds", "stable", "reads", "cached", "document", "fetch", "history", "response", "metadata", "around", "backing", "store", "native", "vector", "text", "filter", "multi", "behavior", "rank", "filters", "codetabs", "astro", "storeswitch", "storenote", "upstream", "featuregate", "turbopuffer", "similarity", "search", "reports", "headers", "backed", "runs", "namespace", "adding", "cache", "body" ] }, { "id": "api/query#batch-fetch", "kind": "section", "title": "Query & Fetch", "heading": "Batch fetch", "group": "API", "url": "/docs/api/query#batch-fetch", "summary": "Batch fetch returns found documents in request order and reports missing identifiers inline. Ordered results also make it useful for reconstructing a source document from sequential pipeline chunks.", "facts": [ { "kind": "code", "literal": "batch = await client.fetch_documents(\"products\", {\n \"ids\": [\"asin-1\", \"asin-2\", \"asin-3\"],\n \"include_attributes\": [\"title\"],\n})", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "batch, err := client.FetchDocuments(ctx, \"products\", &hevlayer.FetchDocumentsRequest{\n Ids: []string{\"asin-1\", \"asin-2\", \"asin-3\"},\n IncludeAttributes: []string{\"title\"},\n})", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "const batch = await client.fetchDocuments(\"products\", {\n ids: [\"asin-1\", \"asin-2\", \"asin-3\"],\n include_attributes: [\"title\"],\n});", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/documents\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\"asin-1\", \"asin-2\", \"asin-3\"],\n \"include_attributes\": [\"title\"]\n }'", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "{\n \"documents\": [\n {\"id\": \"asin-1\", \"attributes\": {\"title\": \"...\"}},\n {\"id\": \"asin-3\", \"attributes\": {\"title\": \"...\"}}\n ],\n \"missing\": [\"asin-2\"]\n}", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "documents", "chunkId": "api/query#batch-fetch" }, { "kind": "code", "literal": "missing", "chunkId": "api/query#batch-fetch" } ], "sources": [ { "chunkId": "api/query#batch-fetch", "url": "/docs/api/query#batch-fetch", "anchor": "batch-fetch" } ], "mode": "source-primary", "terms": [ "batch", "fetch", "returns", "found", "documents", "request", "order", "reports", "missing", "identifiers", "inline", "ordered", "results", "also", "make", "useful", "reconstructing", "source", "document", "sequential", "pipeline", "chunks", "await", "client", "products", "asin", "include", "attributes", "title", "fetchdocuments", "hevlayer", "fetchdocumentsrequest", "string", "includeattributes", "const", "curl", "post", "layer", "gateway", "namespaces" ] }, { "id": "api/query#batch-query", "kind": "section", "title": "Query & Fetch", "heading": "Batch query", "group": "API", "url": "/docs/api/query#batch-query", "summary": "Batch query runs several independent rankings against one namespace in a single round trip, preserving request order and one consistency cut. It differs from seed fusion, upstream reranking, and federated search across namespaces.", "facts": [ { "kind": "code", "literal": "batch = await client.batch_query_namespace(\"products\", {\n \"queries\": [\n {\"rank_by\": [\"vector\", \"ANN\", [0.1, 0.2, 0.3]], \"top_k\": 10},\n {\"rank_by\": [\"title\", \"BM25\", \"wireless earbuds\"], \"top_k\": 10},\n ],\n})\n# batch.results[0].rows ranked by vector; batch.results[1].rows by text", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "batch, err := client.BatchQueryNamespace(ctx, \"products\",\n &hevlayer.BatchQueryRequest{\n Queries: []hevlayer.TurbopufferQueryRequest{\n {\"rank_by\": []any{\"vector\", \"ANN\", []float64{0.1, 0.2, 0.3}}, \"top_k\": 10},\n {\"rank_by\": []any{\"title\", \"BM25\", \"wireless earbuds\"}, \"top_k\": 10},\n },\n })", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "const batch = await client.batchQueryNamespace(\"products\", {\n queries: [\n { rank_by: [\"vector\", \"ANN\", [0.1, 0.2, 0.3]], top_k: 10 },\n { rank_by: [\"title\", \"BM25\", \"wireless earbuds\"], top_k: 10 },\n ],\n});\n// batch.results[0].rows ranked by vector; batch.results[1].rows by text", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"queries\": [\n {\"rank_by\": [\"vector\", \"ANN\", [0.1, 0.2, 0.3]], \"top_k\": 10},\n {\"rank_by\": [\"title\", \"BM25\", \"wireless earbuds\"], \"top_k\": 10}\n ]\n }'", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "queries", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "results", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "{ \"results\": [{ \"rows\": ... }] }", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "batch_query_namespace", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "rerank_by", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#batch-query" }, { "kind": "code", "literal": "cursor", "chunkId": "api/query#batch-query" } ], "sources": [ { "chunkId": "api/query#batch-query", "url": "/docs/api/query#batch-query", "anchor": "batch-query" } ], "mode": "source-primary", "terms": [ "batch", "query", "runs", "several", "independent", "rankings", "against", "namespace", "single", "round", "trip", "preserving", "request", "order", "consistency", "differs", "seed", "fusion", "upstream", "reranking", "federated", "search", "across", "namespaces", "await", "client", "products", "queries", "rank", "vector", "title", "bm25", "wireless", "earbuds", "results", "rows", "ranked", "text", "batchquerynamespace", "hevlayer" ] }, { "id": "api/query#behavior-matrix", "kind": "section", "title": "Query & Fetch", "heading": "Behavior matrix", "group": "API", "url": "/docs/api/query#behavior-matrix", "summary": "Fetches use the cache on a hit, otherwise read and backfill from origin; missing single documents return not found while batches list missing identifiers. Cache outages fall through to origin and are surfaced distinctly.", "facts": [ { "kind": "code", "literal": "missing", "chunkId": "api/query#behavior-matrix" }, { "kind": "code", "literal": "miss-on-error", "chunkId": "api/query#behavior-matrix" } ], "sources": [ { "chunkId": "api/query#behavior-matrix", "url": "/docs/api/query#behavior-matrix", "anchor": "behavior-matrix" } ], "mode": "source-primary", "terms": [ "behavior", "matrix", "fetches", "cache", "otherwise", "read", "backfill", "origin", "missing", "single", "documents", "return", "found", "while", "batches", "list", "identifiers", "outages", "fall", "through", "surfaced", "distinctly", "miss", "error", "state", "fetch", "batch", "upstream", "present", "absent", "inline", "unavailable" ] }, { "id": "api/query#counting-matches", "kind": "section", "title": "Query & Fetch", "heading": "Counting matches", "group": "API", "url": "/docs/api/query#counting-matches", "summary": "Use scan count mode for ranked match counts: full-text counts are exact, while vector-radius counts are approximate and both honor depth and deadline controls.", "facts": [ { "kind": "code", "literal": "fts", "chunkId": "api/query#counting-matches" }, { "kind": "code", "literal": "ann", "chunkId": "api/query#counting-matches" }, { "kind": "code", "literal": "/scans", "chunkId": "api/query#counting-matches" }, { "kind": "code", "literal": "approximate", "chunkId": "api/query#counting-matches" }, { "kind": "code", "literal": "exhaustive", "chunkId": "api/query#counting-matches" } ], "sources": [ { "chunkId": "api/query#counting-matches", "url": "/docs/api/query#counting-matches", "anchor": "counting-matches" } ], "mode": "source-primary", "terms": [ "counting", "matches", "scan", "count", "mode", "ranked", "match", "counts", "full", "text", "exact", "while", "vector", "radius", "approximate", "both", "honor", "depth", "deadline", "controls", "scans", "exhaustive", "many", "rows", "query", "selector", "share", "single", "endpoint", "filter", "flagged", "flag" ] }, { "id": "api/query#fetch", "kind": "section", "title": "Query & Fetch", "heading": "Fetch", "group": "API", "url": "/docs/api/query#fetch", "summary": "Document fetch is gateway-specific and reads the cache first, then falls through to the backing store on a miss or cache error and backfills best-effort.", "facts": [], "sources": [ { "chunkId": "api/query#fetch", "url": "/docs/api/query#fetch", "anchor": "fetch" } ], "mode": "source-primary", "terms": [ "fetch", "document", "gateway", "specific", "reads", "cache", "first", "falls", "through", "backing", "store", "miss", "error", "backfills", "best", "effort", "layer", "only", "endpoint", "upstream", "equivalent", "checked" ] }, { "id": "api/query#hybrid-text-fusion", "kind": "section", "title": "Query & Fetch", "heading": "Hybrid text fusion", "group": "API", "url": "/docs/api/query#hybrid-text-fusion", "summary": "Hybrid text search combines full-input lexical ranking with token-level fuzzy legs and fuses them into one typo-tolerant ranking. The field must support both full-text and fuzzy indexing, and optional tuning controls edit tolerance, fusion depth, and fan-out.", "facts": [ { "kind": "code", "literal": "response = await client.query_namespace(\"support-tickets\", {\n \"rank_by\": [\"content\", \"HybridText\", \"conection timout kubernets\"],\n \"top_k\": 10,\n \"filters\": [\"tenant\", \"Eq\", \"t-42\"],\n \"include_attributes\": [\"content\", \"title\"],\n})", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "response, err := client.QueryNamespace(ctx, \"support-tickets\", &hevlayer.QueryRequest{\n RankBy: []any{\"content\", \"HybridText\", \"conection timout kubernets\"},\n TopK: 10,\n Filters: []any{\"tenant\", \"Eq\", \"t-42\"},\n IncludeAttributes: []string{\"content\", \"title\"},\n})", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "const response = await client.queryNamespace(\"support-tickets\", {\n rank_by: [\"content\", \"HybridText\", \"conection timout kubernets\"],\n top_k: 10,\n filters: [\"tenant\", \"Eq\", \"t-42\"],\n include_attributes: [\"content\", \"title\"],\n});", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/support-tickets/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"rank_by\": [\"content\", \"HybridText\", \"conection timout kubernets\"],\n \"top_k\": 10,\n \"filters\": [\"tenant\", \"Eq\", \"t-42\"],\n \"include_attributes\": [\"content\", \"title\"]\n }'", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "[\"content\", \"HybridText\", \"conection timout kubernets\", {\n \"fuzziness\": \"auto\",\n \"rank_constant\": 60,\n \"per_leg_limit\": null\n}]", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "alyze", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "{\"type\": \"string\", \"full_text_search\": true, \"fuzzy\": true}", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "fuzziness", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "\"auto\"", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "rank_constant", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "60", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "per_leg_limit", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "clamp(5 × top_k, 50, 200)", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "threads", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "Index.spec.scan.threads", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "include_leg_breakdown: true", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "$fused.legs", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "rank", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "score", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "null", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "bm25", "chunkId": "api/query#hybrid-text-fusion" }, { "kind": "code", "literal": "fuzzy:", "chunkId": "api/query#hybrid-text-fusion" } ], "sources": [ { "chunkId": "api/query#hybrid-text-fusion", "url": "/docs/api/query#hybrid-text-fusion", "anchor": "hybrid-text-fusion" } ], "mode": "source-primary", "terms": [ "hybrid", "text", "fusion", "search", "combines", "full", "input", "lexical", "ranking", "token", "level", "fuzzy", "legs", "fuses", "typo", "tolerant", "field", "must", "support", "both", "indexing", "optional", "tuning", "controls", "edit", "tolerance", "depth", "response", "await", "client", "query", "namespace", "tickets", "rank", "content", "hybridtext", "conection", "timout", "kubernets", "filters" ] }, { "id": "api/query#options", "kind": "section", "title": "Query & Fetch", "heading": "Options", "group": "API", "url": "/docs/api/query#options", "summary": "Routing options can leave strategy selection automatic or force lexical, semantic, or fused retrieval for replay and comparison. Semantic routes require a client-supplied vector, while lexical expansion retains fuzzy-search tuning.", "facts": [ { "kind": "code", "literal": "route", "chunkId": "api/query#options" }, { "kind": "code", "literal": "\"auto\"", "chunkId": "api/query#options" }, { "kind": "code", "literal": "\"hybrid_text\"", "chunkId": "api/query#options" }, { "kind": "code", "literal": "\"semantic\"", "chunkId": "api/query#options" }, { "kind": "code", "literal": "\"fused\"", "chunkId": "api/query#options" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#options" }, { "kind": "code", "literal": "fuzziness", "chunkId": "api/query#options" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#options" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "api/query#options" }, { "kind": "code", "literal": "fused", "chunkId": "api/query#options" }, { "kind": "code", "literal": "semantic", "chunkId": "api/query#options" }, { "kind": "code", "literal": "hybrid", "chunkId": "api/query#options" }, { "kind": "code", "literal": "routing", "chunkId": "api/query#options" }, { "kind": "code", "literal": "include_leg_breakdown: true", "chunkId": "api/query#options" }, { "kind": "code", "literal": "$fused.legs", "chunkId": "api/query#options" } ], "sources": [ { "chunkId": "api/query#options", "url": "/docs/api/query#options", "anchor": "options" } ], "mode": "source-primary", "terms": [ "options", "routing", "leave", "strategy", "selection", "automatic", "force", "lexical", "semantic", "fused", "retrieval", "replay", "comparison", "routes", "require", "client", "supplied", "vector", "while", "expansion", "retains", "fuzzy", "search", "tuning", "route", "auto", "hybrid", "text", "fuzziness", "hybridtext", "include", "breakdown", "true", "legs", "optional", "fourth", "tuple", "element", "option", "default" ] }, { "id": "api/query#query-by-id", "kind": "section", "title": "Query & Fetch", "heading": "Query by id", "group": "API", "url": "/docs/api/query#query-by-id", "summary": "Similarity can start from one or more stored document vectors instead of a supplied query vector. The gateway resolves every seed, averages them equally into one centroid, and returns a single neighbor ranking, failing if any seed lacks a vector.", "facts": [ { "kind": "code", "literal": "response = await client.query_namespace(\"products\", {\n \"nearest_to_id\": [\"asin-B08N5WRWNW\", \"asin-B07PXGQC1Q\"],\n \"top_k\": 10,\n \"include_attributes\": [\"title\", \"category\"],\n})", "chunkId": "api/query#query-by-id" }, { "kind": "code", "literal": "response, err := client.QueryNamespace(ctx, \"products\", &hevlayer.QueryRequest{\n NearestToID: []string{\"asin-B08N5WRWNW\", \"asin-B07PXGQC1Q\"},\n TopK: 10,\n IncludeAttributes: []string{\"title\", \"category\"},\n})", "chunkId": "api/query#query-by-id" }, { "kind": "code", "literal": "const response = await client.queryNamespace(\"products\", {\n nearest_to_id: [\"asin-B08N5WRWNW\", \"asin-B07PXGQC1Q\"],\n top_k: 10,\n include_attributes: [\"title\", \"category\"],\n});", "chunkId": "api/query#query-by-id" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"nearest_to_id\": [\"asin-B08N5WRWNW\", \"asin-B07PXGQC1Q\"],\n \"top_k\": 10,\n \"include_attributes\": [\"title\", \"category\"]\n }'", "chunkId": "api/query#query-by-id" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "api/query#query-by-id" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#query-by-id" } ], "sources": [ { "chunkId": "api/query#query-by-id", "url": "/docs/api/query#query-by-id", "anchor": "query-by-id" } ], "mode": "source-primary", "terms": [ "query", "similarity", "start", "more", "stored", "document", "vectors", "instead", "supplied", "vector", "gateway", "resolves", "every", "seed", "averages", "equally", "centroid", "returns", "single", "neighbor", "ranking", "failing", "lacks", "response", "await", "client", "namespace", "products", "nearest", "asin", "b08n5wrwnw", "b07pxgqc1q", "include", "attributes", "title", "category", "querynamespace", "hevlayer", "queryrequest", "nearesttoid" ] }, { "id": "api/query#query-routing", "kind": "section", "title": "Query & Fetch", "heading": "Query routing", "group": "API", "url": "/docs/api/query#query-routing", "summary": "Automatic routing chooses lexical, semantic, or fused retrieval from the shape of the input text. Layer never creates embeddings, so a vectorless request that needs semantic retrieval returns a routing decision for the client to embed and reissue.", "facts": [ { "kind": "code", "literal": "\"timout\"", "chunkId": "api/query#query-routing" }, { "kind": "code", "literal": "Auto", "chunkId": "api/query#query-routing" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/query#query-routing" } ], "sources": [ { "chunkId": "api/query#query-routing", "url": "/docs/api/query#query-routing", "anchor": "query-routing" } ], "mode": "source-primary", "terms": [ "query", "routing", "automatic", "chooses", "lexical", "semantic", "fused", "retrieval", "shape", "input", "text", "layer", "never", "creates", "embeddings", "vectorless", "request", "needs", "returns", "decision", "client", "embed", "reissue", "timout", "auto", "rank", "real", "search", "boxes", "receive", "both", "pods", "lose", "their", "connection", "during", "deploys", "first", "wants", "hybrid" ] }, { "id": "api/query#rank-expressions", "kind": "section", "title": "Query & Fetch", "heading": "Rank expressions", "group": "API", "url": "/docs/api/query#rank-expressions", "summary": "Explicit ranking expressions are available when callers need a named ranking operator, while native bodies without the Layer ranking shape continue to pass through. Explicit ranking cannot be combined with top-level vector or seed-based ranking.", "facts": [ { "kind": "code", "literal": "rank_by", "chunkId": "api/query#rank-expressions" }, { "kind": "code", "literal": "top_k", "chunkId": "api/query#rank-expressions" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#rank-expressions" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "api/query#rank-expressions" } ], "sources": [ { "chunkId": "api/query#rank-expressions", "url": "/docs/api/query#rank-expressions", "anchor": "rank-expressions" } ], "mode": "source-primary", "terms": [ "rank", "expressions", "explicit", "ranking", "available", "callers", "need", "named", "operator", "while", "native", "bodies", "without", "layer", "shape", "continue", "pass", "through", "cannot", "combined", "level", "vector", "seed", "based", "nearest", "rankby", "topk", "instead", "nearesttoid", "handles", "portable", "subset", "same", "cache", "history", "stable", "read", "behavior", "queries", "upstream" ] }, { "id": "api/query#response", "kind": "section", "title": "Query & Fetch", "heading": "Response", "group": "API", "url": "/docs/api/query#response", "summary": "Hybrid results include the fused rows plus an echo of tokenization, fuzzy behavior, leg count, retrieval depth, and pagination. Optional per-leg attribution explains each row, while fused scores are meaningful only within one response.", "facts": [ { "kind": "code", "literal": "{\n \"rows\": [\n {\n \"id\": \"ticket-4117\",\n \"$score\": 0.0639,\n \"content\": \"...\",\n \"title\": \"Connection timeout on Kubernetes ingress\"\n }\n ],\n \"hybrid\": {\n \"tokens\": [\"conection\", \"timout\", \"kubernets\"],\n \"tokens_dropped\": 0,\n \"fuzziness\": \"auto\",\n \"rank_constant\": 60,\n \"legs\": 4,\n \"per_leg_limit\": 50\n },\n \"next_cursor\": null\n}", "chunkId": "api/query#response" }, { "kind": "code", "literal": "hybrid", "chunkId": "api/query#response" }, { "kind": "code", "literal": "$score", "chunkId": "api/query#response" }, { "kind": "code", "literal": "$fused.legs", "chunkId": "api/query#response" }, { "kind": "code", "literal": "include_leg_breakdown: true", "chunkId": "api/query#response" }, { "kind": "code", "literal": "leg", "chunkId": "api/query#response" }, { "kind": "code", "literal": "rank", "chunkId": "api/query#response" }, { "kind": "code", "literal": "score", "chunkId": "api/query#response" }, { "kind": "code", "literal": "tokens", "chunkId": "api/query#response" }, { "kind": "code", "literal": "tokens_dropped", "chunkId": "api/query#response" }, { "kind": "code", "literal": "legs", "chunkId": "api/query#response" }, { "kind": "code", "literal": "surfaced", "chunkId": "api/query#response" }, { "kind": "code", "literal": "true", "chunkId": "api/query#response" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/query#response" }, { "kind": "code", "literal": "null", "chunkId": "api/query#response" }, { "kind": "code", "literal": "x-layer-next-cursor", "chunkId": "api/query#response" }, { "kind": "code", "literal": "cursor", "chunkId": "api/query#response" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#response" }, { "kind": "code", "literal": "threads", "chunkId": "api/query#response" }, { "kind": "code", "literal": "rerank_by", "chunkId": "api/query#response" } ], "sources": [ { "chunkId": "api/query#response", "url": "/docs/api/query#response", "anchor": "response" } ], "mode": "source-primary", "terms": [ "response", "hybrid", "results", "include", "fused", "rows", "plus", "echo", "tokenization", "fuzzy", "behavior", "count", "retrieval", "depth", "pagination", "optional", "attribution", "explains", "while", "scores", "meaningful", "only", "within", "ticket", "4117", "score", "0639", "content", "title", "connection", "timeout", "kubernetes", "ingress", "tokens", "conection", "timout", "kubernets", "dropped", "fuzziness", "auto" ] }, { "id": "api/query#response-1", "kind": "section", "title": "Query & Fetch", "heading": "Response", "group": "API", "url": "/docs/api/query#response-1", "summary": "Every automatically routed response identifies the selected strategy, policy version, token count, and whether execution occurred. Deferred responses contain no rows and tell the caller to supply an embedding and force the chosen route.", "facts": [ { "kind": "code", "literal": "{\n \"rows\": [{\"id\": \"ticket-4117\", \"$score\": 0.0639, \"title\": \"...\"}],\n \"routing\": {\n \"route\": \"hybrid_text\",\n \"policy\": \"v1\",\n \"tokens\": 1,\n \"executed\": true\n },\n \"hybrid\": {\"tokens\": [\"timout\"], \"tokens_dropped\": 0, \"fuzziness\": \"auto\", \"rank_constant\": 60, \"legs\": 2, \"per_leg_limit\": 50}\n}", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "Auto", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "routing", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "route", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "policy", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "\"forced\"", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "tokens", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "executed", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "false", "chunkId": "api/query#response-1" }, { "kind": "code", "literal": "rows", "chunkId": "api/query#response-1" } ], "sources": [ { "chunkId": "api/query#response-1", "url": "/docs/api/query#response-1", "anchor": "response-1" } ], "mode": "source-primary", "terms": [ "response", "every", "automatically", "routed", "identifies", "selected", "strategy", "policy", "version", "token", "count", "whether", "execution", "occurred", "deferred", "responses", "contain", "rows", "tell", "caller", "supply", "embedding", "force", "chosen", "route", "ticket", "4117", "score", "0639", "title", "routing", "hybrid", "text", "tokens", "executed", "true", "timout", "dropped", "fuzziness", "auto" ] }, { "id": "api/query#routing-policy", "kind": "section", "title": "Query & Fetch", "heading": "Routing policy", "group": "API", "url": "/docs/api/query#routing-policy", "summary": "The first routing policy sends very short input to lexical fusion, long input to semantic retrieval, and middle-length input to a fused strategy. Vector presence controls whether semantic work can execute, not which route is selected.", "facts": [ { "kind": "code", "literal": "hybrid_text", "chunkId": "api/query#routing-policy" }, { "kind": "code", "literal": "semantic", "chunkId": "api/query#routing-policy" }, { "kind": "code", "literal": "fused", "chunkId": "api/query#routing-policy" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#routing-policy" }, { "kind": "code", "literal": "\"policy\": \"v1\"", "chunkId": "api/query#routing-policy" } ], "sources": [ { "chunkId": "api/query#routing-policy", "url": "/docs/api/query#routing-policy", "anchor": "routing-policy" } ], "mode": "source-primary", "terms": [ "routing", "policy", "first", "sends", "very", "short", "input", "lexical", "fusion", "long", "semantic", "retrieval", "middle", "length", "fused", "strategy", "vector", "presence", "controls", "whether", "work", "execute", "route", "selected", "hybrid", "text", "reads", "token", "count", "under", "same", "tokenizer", "tokens", "runs", "hybridtext", "expansion", "supplied", "query", "both", "merged" ] }, { "id": "api/query#semantics", "kind": "section", "title": "Query & Fetch", "heading": "Semantics", "group": "API", "url": "/docs/api/query#semantics", "summary": "All fusion legs share filters and one stable read cut, and any leg failure fails the entire request. Search history records the original expression as one replayable unit rather than separate expanded legs.", "facts": [ { "kind": "code", "literal": "include_leg_breakdown: true", "chunkId": "api/query#semantics" }, { "kind": "code", "literal": "filters", "chunkId": "api/query#semantics" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/query#semantics" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#semantics" } ], "sources": [ { "chunkId": "api/query#semantics", "url": "/docs/api/query#semantics", "anchor": "semantics" } ], "mode": "source-primary", "terms": [ "semantics", "fusion", "legs", "share", "filters", "stable", "read", "failure", "fails", "entire", "request", "search", "history", "records", "original", "expression", "replayable", "unit", "rather", "separate", "expanded", "include", "breakdown", "true", "layer", "hybridtext", "uses", "effective", "order", "bm25", "first", "fuzzy", "token", "semantic", "routed", "fused", "queries", "includelegbreakdown", "require", "upstream" ] }, { "id": "api/query#single-fetch", "kind": "section", "title": "Query & Fetch", "heading": "Single fetch", "group": "API", "url": "/docs/api/query#single-fetch", "summary": "Single-document fetch reports whether the response came from cache, origin after a miss, or origin during a cache error, and returns not found only when neither layer has the document.", "facts": [ { "kind": "code", "literal": "doc = await client.fetch_document(\n \"products\",\n \"asin-B08N5WRWNW\",\n include_attributes=[\"title\", \"category\"],\n)", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "doc, err := client.FetchDocument(ctx, \"products\", \"asin-B08N5WRWNW\",\n &hevlayer.FetchDocumentParams{\n IncludeAttributes: []string{\"title\", \"category\"},\n })", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "const doc = await client.fetchDocument(\"products\", \"asin-B08N5WRWNW\", {\n includeAttributes: [\"title\", \"category\"],\n});", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/documents/asin-B08N5WRWNW?include_attributes=title,category\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "x-layer-cache: hit", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "x-layer-cache: miss", "chunkId": "api/query#single-fetch" }, { "kind": "code", "literal": "x-layer-cache: miss-on-error", "chunkId": "api/query#single-fetch" } ], "sources": [ { "chunkId": "api/query#single-fetch", "url": "/docs/api/query#single-fetch", "anchor": "single-fetch" } ], "mode": "source-primary", "terms": [ "single", "fetch", "document", "reports", "whether", "response", "came", "cache", "origin", "after", "miss", "during", "error", "returns", "found", "only", "neither", "layer", "await", "client", "products", "asin", "b08n5wrwnw", "include", "attributes", "title", "category", "fetchdocument", "hevlayer", "fetchdocumentparams", "includeattributes", "string", "const", "curl", "gateway", "namespaces", "documents", "authorization", "bearer", "layergatewayurl" ] }, { "id": "api/query#stable-reads", "kind": "section", "title": "Query & Fetch", "heading": "Stable reads", "group": "API", "url": "/docs/api/query#stable-reads", "summary": "Queries default to an index cut known to be stable, filtering out newer partially indexed writes only while needed and retrying once under write pressure. Responses expose freshness and pagination, and callers may request explicit point-in-time or interval cuts.", "facts": [ { "kind": "code", "literal": "HTTP/1.1 200 OK\nx-layer-stable-as-of: 1715600400000\n\n{\"rows\":[{\"id\":\"asin-B08N5WRWNW\",\"$dist\":0.42,\"title\":\"...\"}]}", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "consistency=eventual", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "index.status", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "poll_start - safety_margin", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "Updating", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "_hevlayer_upserted_at <= watermark", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "Stable", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "Unknown", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "null", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "x-layer-next-cursor", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "cursor", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "Auto", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "as_of", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "between", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "as_of: 1747300000123", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "_hevlayer_upserted_at <= 1747300000123", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "between: [lo, hi]", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "lo < _hevlayer_upserted_at <= hi", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "filters", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "api/query#stable-reads" }, { "kind": "code", "literal": "consistency", "chunkId": "api/query#stable-reads" } ], "sources": [ { "chunkId": "api/query#stable-reads", "url": "/docs/api/query#stable-reads", "anchor": "stable-reads" } ], "mode": "source-primary", "terms": [ "stable", "reads", "queries", "default", "index", "known", "filtering", "newer", "partially", "indexed", "writes", "only", "while", "needed", "retrying", "once", "under", "write", "pressure", "responses", "expose", "freshness", "pagination", "callers", "request", "explicit", "point", "time", "interval", "cuts", "http", "layer", "1715600400000", "rows", "asin", "b08n5wrwnw", "dist", "title", "consistency", "eventual" ] }, { "id": "api/query#surfacing-fallback", "kind": "section", "title": "Query & Fetch", "heading": "Surfacing fallback", "group": "API", "url": "/docs/api/query#surfacing-fallback", "summary": "When the normal lexical and fuzzy expansion yields no rows, Layer retries token-level fuzzy legs ordered by edit distance and fuses them. A response marker identifies this additive typo-recovery path.", "facts": [ { "kind": "code", "literal": "\"surfaced\": true", "chunkId": "api/query#surfacing-fallback" }, { "kind": "code", "literal": "hybrid", "chunkId": "api/query#surfacing-fallback" }, { "kind": "code", "literal": "legs", "chunkId": "api/query#surfacing-fallback" }, { "kind": "code", "literal": "surfaced", "chunkId": "api/query#surfacing-fallback" } ], "sources": [ { "chunkId": "api/query#surfacing-fallback", "url": "/docs/api/query#surfacing-fallback", "anchor": "surfacing-fallback" } ], "mode": "source-primary", "terms": [ "surfacing", "fallback", "normal", "lexical", "fuzzy", "expansion", "yields", "rows", "layer", "retries", "token", "level", "legs", "ordered", "edit", "distance", "fuses", "response", "marker", "identifies", "additive", "typo", "recovery", "path", "surfaced", "true", "hybrid", "every", "primary", "ranks", "bm25", "full", "input", "upstream", "scores", "zero", "drops", "matches", "stored", "term" ] }, { "id": "api/query#tokenization", "kind": "section", "title": "Query & Fetch", "heading": "Tokenization", "group": "API", "url": "/docs/api/query#tokenization", "summary": "Hybrid text uses Unicode word boundaries, lowercases, drops very short tokens, removes duplicates, and caps the expansion. It intentionally performs no stemming, stopword removal, or language detection.", "facts": [ { "kind": "code", "literal": "alyze", "chunkId": "api/query#tokenization" }, { "kind": "code", "literal": "word_v4", "chunkId": "api/query#tokenization" }, { "kind": "code", "literal": "tokens_dropped", "chunkId": "api/query#tokenization" } ], "sources": [ { "chunkId": "api/query#tokenization", "url": "/docs/api/query#tokenization", "anchor": "tokenization" } ], "mode": "source-primary", "terms": [ "tokenization", "hybrid", "text", "uses", "unicode", "word", "boundaries", "lowercases", "drops", "very", "short", "tokens", "removes", "duplicates", "caps", "expansion", "intentionally", "performs", "stemming", "stopword", "removal", "language", "detection", "alyze", "dropped", "input", "string", "becomes", "under", "fixed", "documented", "policy", "split", "lowercase", "code", "behind", "turbopuffer", "production", "wordv4", "tokenizer" ] }, { "id": "api/query#validation", "kind": "section", "title": "Query & Fetch", "heading": "Validation", "group": "API", "url": "/docs/api/query#validation", "summary": "Hybrid text rejects input that produces no usable tokens, nested use inside a batch, and tuning values outside the supported ranges.", "facts": [ { "kind": "code", "literal": "422", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "queries", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "fuzziness", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "\"auto\" \\| 0 \\| 1 \\| 2", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "rank_constant", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "per_leg_limit", "chunkId": "api/query#validation" }, { "kind": "code", "literal": "threads", "chunkId": "api/query#validation" } ], "sources": [ { "chunkId": "api/query#validation", "url": "/docs/api/query#validation", "anchor": "validation" } ], "mode": "source-primary", "terms": [ "validation", "hybrid", "text", "rejects", "input", "produces", "usable", "tokens", "nested", "inside", "batch", "tuning", "values", "outside", "supported", "ranges", "hybridtext", "queries", "fuzziness", "auto", "rank", "constant", "limit", "threads", "return", "condition", "yields", "zero", "under", "policy", "nothing", "expand", "array", "expansion", "already", "deep", "construction", "rankconstant", "perleglimit", "range" ] }, { "id": "api/query#validation-1", "kind": "section", "title": "Query & Fetch", "heading": "Validation", "group": "API", "url": "/docs/api/query#validation-1", "summary": "Automatic routing rejects empty tokenization, incompatible vector dimensions, nested batch use, and forced vector-dependent strategies that omit the vector.", "facts": [ { "kind": "code", "literal": "422", "chunkId": "api/query#validation-1" }, { "kind": "code", "literal": "\"semantic\"", "chunkId": "api/query#validation-1" }, { "kind": "code", "literal": "\"fused\"", "chunkId": "api/query#validation-1" }, { "kind": "code", "literal": "vector", "chunkId": "api/query#validation-1" }, { "kind": "code", "literal": "Auto", "chunkId": "api/query#validation-1" }, { "kind": "code", "literal": "queries", "chunkId": "api/query#validation-1" } ], "sources": [ { "chunkId": "api/query#validation-1", "url": "/docs/api/query#validation-1", "anchor": "validation-1" } ], "mode": "source-primary", "terms": [ "validation", "automatic", "routing", "rejects", "empty", "tokenization", "incompatible", "vector", "dimensions", "nested", "batch", "forced", "dependent", "strategies", "omit", "semantic", "fused", "auto", "queries", "return", "condition", "without", "forcing", "asserts", "only", "defers", "input", "yields", "zero", "tokens", "under", "policy", "nothing", "route", "dimensionality", "mismatch", "same", "check", "plain", "query" ] }, { "id": "api/response-headers", "kind": "section", "title": "Response Headers", "heading": null, "group": "API", "url": "/docs/api/response-headers", "summary": "Layer keeps compatible response bodies and carries gateway metadata in headers, including freshness, pagination, cache outcome, warnings, license grace, and distributed trace context. Generated clients project useful header values into response objects.", "facts": [ { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "x-layer-next-cursor", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "x-layer-cache", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "hit", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "miss", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "miss-on-error", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "x-layer-warning", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "vector_attribute_dropped", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "x-hevlayer-license-grace", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "true", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "traceparent", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "query_namespace", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "rows", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/response-headers" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/response-headers" } ], "sources": [ { "chunkId": "api/response-headers", "url": "/docs/api/response-headers", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "keeps", "compatible", "response", "bodies", "carries", "gateway", "metadata", "headers", "including", "freshness", "pagination", "cache", "outcome", "warnings", "license", "grace", "distributed", "trace", "context", "generated", "clients", "project", "useful", "header", "values", "objects", "stable", "next", "cursor", "miss", "error", "warning", "vector", "attribute", "dropped", "hevlayer", "true", "traceparent", "query" ] }, { "id": "api/scans", "kind": "section", "title": "Scan", "heading": null, "group": "API", "url": "/docs/api/scans", "summary": "Scans select rows by filters, full-text, hybrid text, or vector radius and return identifiers asynchronously, counts synchronously, or distinct field values asynchronously. Ranked selectors use origin fan-out, while filters can further constrain any selector.", "facts": [ { "kind": "code", "literal": "mode: ids", "chunkId": "api/scans" }, { "kind": "code", "literal": "mode: count", "chunkId": "api/scans" }, { "kind": "code", "literal": "mode: values", "chunkId": "api/scans" }, { "kind": "code", "literal": "filters", "chunkId": "api/scans" }, { "kind": "code", "literal": "fts", "chunkId": "api/scans" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "api/scans" }, { "kind": "code", "literal": "ann", "chunkId": "api/scans" }, { "kind": "code", "literal": "radius", "chunkId": "api/scans" }, { "kind": "code", "literal": "threads", "chunkId": "api/scans" }, { "kind": "code", "literal": "Index.spec.scan.threads", "chunkId": "api/scans" }, { "kind": "code", "literal": "POST /v2/namespaces/{ns}/init", "chunkId": "api/scans" }, { "kind": "code", "literal": "layer.shard_lag_rows", "chunkId": "api/scans" }, { "kind": "code", "literal": "_hevlayer_shard", "chunkId": "api/scans" }, { "kind": "code", "literal": "422", "chunkId": "api/scans" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/scans" } ], "sources": [ { "chunkId": "api/scans", "url": "/docs/api/scans", "anchor": null } ], "mode": "source-primary", "terms": [ "scans", "select", "rows", "filters", "full", "text", "hybrid", "vector", "radius", "return", "identifiers", "asynchronously", "counts", "synchronously", "distinct", "field", "values", "ranked", "selectors", "origin", "while", "further", "constrain", "selector", "mode", "count", "threads", "index", "spec", "scan", "post", "namespaces", "init", "layer", "shard", "hevlayer", "codetabs", "astro", "demand", "selection" ] }, { "id": "api/scans#auto-mode-policy", "kind": "section", "title": "Scan", "heading": "Auto-Mode Policy", "group": "API", "url": "/docs/api/scans#auto-mode-policy", "summary": "Automatic source selection relates cache freshness to the namespace's stable watermark. A populated stale cache can serve its last warmed cut while a background origin refresh advances it.", "facts": [ { "kind": "code", "literal": "cache_warmed_through", "chunkId": "api/scans#auto-mode-policy" }, { "kind": "code", "literal": "cache_warmed_through >= watermark", "chunkId": "api/scans#auto-mode-policy" }, { "kind": "code", "literal": "cache_warmed_through < watermark", "chunkId": "api/scans#auto-mode-policy" }, { "kind": "code", "literal": "_hevlayer_upserted_at <= cache_warmed_through", "chunkId": "api/scans#auto-mode-policy" } ], "sources": [ { "chunkId": "api/scans#auto-mode-policy", "url": "/docs/api/scans#auto-mode-policy", "anchor": "auto-mode-policy" } ], "mode": "source-primary", "terms": [ "auto", "mode", "policy", "automatic", "source", "selection", "relates", "cache", "freshness", "namespace", "stable", "watermark", "populated", "stale", "serve", "last", "warmed", "while", "background", "origin", "refresh", "advances", "through", "hevlayer", "upserted", "ties", "same", "consistency", "reads", "gateway", "tracks", "cachewarmedthrough", "observed", "successful", "warm", "state", "action", "empty", "stamp", "start" ] }, { "id": "api/scans#bounding-ranked-scans", "kind": "section", "title": "Scan", "heading": "Bounding ranked scans", "group": "API", "url": "/docs/api/scans#bounding-ranked-scans", "summary": "Ranked scans cap each shard contribution and use concurrency, exhaustive traversal, and deadlines to control cost. Saturation yields a lower-bound marker, while vector-radius approximation is a separate property of nearest-neighbor recall.", "facts": [ { "kind": "code", "literal": "top_k = 10_000", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "threads", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "exhaustive", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "timeout_seconds", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "exhaustive: false", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "bounded: true", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "shards_saturated > 0", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "exhaustive: true", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "$score < last", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "id", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "$dist", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "$dist <= radius", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "bounded", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "approximate", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": ">=", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "ann", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "bounded: false", "chunkId": "api/scans#bounding-ranked-scans" }, { "kind": "code", "literal": "approximate: true", "chunkId": "api/scans#bounding-ranked-scans" } ], "sources": [ { "chunkId": "api/scans#bounding-ranked-scans", "url": "/docs/api/scans#bounding-ranked-scans", "anchor": "bounding-ranked-scans" } ], "mode": "source-primary", "terms": [ "bounding", "ranked", "scans", "shard", "contribution", "concurrency", "exhaustive", "traversal", "deadlines", "control", "cost", "saturation", "yields", "lower", "bound", "marker", "while", "vector", "radius", "approximation", "separate", "property", "nearest", "neighbor", "recall", "threads", "timeout", "seconds", "false", "bounded", "true", "shards", "saturated", "score", "last", "dist", "approximate", "selectors", "turbopuffer", "query" ] }, { "id": "api/scans#count-mode", "kind": "section", "title": "Scan", "heading": "Count Mode", "group": "API", "url": "/docs/api/scans#count-mode", "summary": "Count scans choose among precomputed snapshots, cache, and origin based on selector complexity and freshness. Temporal windows require live data, while origin responses report boundedness, timeout, shard, concurrency, and elapsed-time details.", "facts": [ { "kind": "code", "literal": "count = await client.create_scan(\"products\", {\n \"mode\": \"count\",\n \"source\": \"auto\",\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"threads\": 8,\n \"timeout_seconds\": 30,\n})", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "count, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Mode: \"count\",\n Source: \"auto\",\n Filters: []interface{}{\"category\", \"Eq\", \"Electronics\"},\n Threads: 8,\n TimeoutSeconds: 30,\n})", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "const count = await client.createScan(\"products\", {\n mode: \"count\",\n source: \"auto\",\n filters: [\"category\", \"Eq\", \"Electronics\"],\n threads: 8,\n timeout_seconds: 30,\n});", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"count\",\n \"source\": \"auto\",\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"threads\": 8,\n \"timeout_seconds\": 30\n }'", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "{\n \"count\": 4210,\n \"served_by\": \"snapshot\",\n \"snapshot_sha\": \"3f9e8b21\",\n \"watermark_ms\": 1747300000123,\n \"elapsed_ms\": 3\n}", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "{\n \"count\": 4210,\n \"served_by\": \"origin\",\n \"bounded\": false,\n \"timed_out\": false,\n \"shards_saturated\": 0,\n \"shards_total\": 1,\n \"threads\": 1,\n \"elapsed_ms\": 42\n}", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "watermark_ms", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "x-layer-stable-as-of", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "snapshot", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "cache", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "origin", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "Eq", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "In", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "fields[]", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "And", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "Or", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "Not", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "412 precondition_failed", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "source: snapshot", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "as_of", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "_hevlayer_upserted_at <= as_of", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "between: [lo, hi]", "chunkId": "api/scans#count-mode" }, { "kind": "code", "literal": "lo < _hevlayer_upserted_at <= hi", "chunkId": "api/scans#count-mode" } ], "sources": [ { "chunkId": "api/scans#count-mode", "url": "/docs/api/scans#count-mode", "anchor": "count-mode" } ], "mode": "source-primary", "terms": [ "count", "mode", "scans", "choose", "among", "precomputed", "snapshots", "cache", "origin", "based", "selector", "complexity", "freshness", "temporal", "windows", "require", "live", "data", "while", "responses", "report", "boundedness", "timeout", "shard", "concurrency", "elapsed", "time", "details", "await", "client", "create", "scan", "products", "source", "auto", "filters", "category", "electronics", "threads", "seconds" ] }, { "id": "api/scans#fan-out-width", "kind": "section", "title": "Scan", "heading": "Fan-out width", "group": "API", "url": "/docs/api/scans#fan-out-width", "summary": "Origin scans limit the number of shard requests in flight using request, index, and gateway defaults, then clamp that width to active shards and a server ceiling. Snapshot and cache scans do not fan out.", "facts": [ { "kind": "code", "literal": "threads", "chunkId": "api/scans#fan-out-width" }, { "kind": "code", "literal": "spec.scan.threads", "chunkId": "api/scans#fan-out-width" }, { "kind": "code", "literal": "Index", "chunkId": "api/scans#fan-out-width" }, { "kind": "code", "literal": "32", "chunkId": "api/scans#fan-out-width" } ], "sources": [ { "chunkId": "api/scans#fan-out-width", "url": "/docs/api/scans#fan-out-width", "anchor": "fan-out-width" } ], "mode": "source-primary", "terms": [ "width", "origin", "scans", "limit", "number", "shard", "requests", "flight", "request", "index", "gateway", "defaults", "clamp", "active", "shards", "server", "ceiling", "snapshot", "cache", "threads", "spec", "scan", "upstream", "sets", "maximum", "those", "single", "once", "means", "concurrent", "operating", "system", "async", "resolution", "order", "namespace", "resource", "default", "effective", "value" ] }, { "id": "api/scans#filters", "kind": "section", "title": "Scan", "heading": "Filters", "group": "API", "url": "/docs/api/scans#filters", "summary": "Origin scans pass the native filter expression to the backing store, while cache scans evaluate a documented operator subset locally. Automatic mode falls back to origin for unsupported cache predicates; explicit cache mode fails.", "facts": [ { "kind": "code", "literal": "Eq", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "NotEq", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Gt", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Gte", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Lt", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Lte", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "In", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "NotIn", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "And", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Or", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "Not", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#filters" }, { "kind": "code", "literal": "source: cache", "chunkId": "api/scans#filters" } ], "sources": [ { "chunkId": "api/scans#filters", "url": "/docs/api/scans#filters", "anchor": "filters" } ], "mode": "source-primary", "terms": [ "filters", "origin", "scans", "pass", "native", "filter", "expression", "backing", "store", "while", "cache", "evaluate", "documented", "operator", "subset", "locally", "automatic", "mode", "falls", "back", "unsupported", "predicates", "explicit", "fails", "noteq", "notin", "auto", "source", "accept", "same", "turbopuffer", "array", "query", "pushed", "gateway", "evaluates", "against", "cached", "document", "attributes" ] }, { "id": "api/scans#full-text-count", "kind": "section", "title": "Scan", "heading": "Full-text count", "group": "API", "url": "/docs/api/scans#full-text-count", "summary": "Full-text count scans run exact lexical matching against origin shards and may combine the text predicate with an additional filter constraint.", "facts": [ { "kind": "code", "literal": "count = await client.create_scan(\"products\", {\n \"mode\": \"count\",\n \"fts\": {\"field\": \"title\", \"query\": \"wireless headphones\"},\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"exhaustive\": True,\n})", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "count, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Mode: \"count\",\n Fts: &hevlayer.FtsScan{Field: \"title\", Query: \"wireless headphones\"},\n Filters: []interface{}{\"category\", \"Eq\", \"Electronics\"},\n Exhaustive: true,\n})", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "const count = await client.createScan(\"products\", {\n mode: \"count\",\n fts: { field: \"title\", query: \"wireless headphones\" },\n filters: [\"category\", \"Eq\", \"Electronics\"],\n exhaustive: true,\n});", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"count\",\n \"fts\": {\"field\": \"title\", \"query\": \"wireless headphones\"},\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"exhaustive\": true\n }'", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "fts", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "source", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "origin", "chunkId": "api/scans#full-text-count" }, { "kind": "code", "literal": "filters", "chunkId": "api/scans#full-text-count" } ], "sources": [ { "chunkId": "api/scans#full-text-count", "url": "/docs/api/scans#full-text-count", "anchor": "full-text-count" } ], "mode": "source-primary", "terms": [ "full", "text", "count", "scans", "exact", "lexical", "matching", "against", "origin", "shards", "combine", "predicate", "additional", "filter", "constraint", "await", "client", "create", "scan", "products", "mode", "field", "title", "query", "wireless", "headphones", "filters", "category", "electronics", "exhaustive", "true", "createscan", "hevlayer", "createscanrequest", "ftsscan", "interface", "const", "curl", "post", "layer" ] }, { "id": "api/scans#high-cardinality", "kind": "section", "title": "Scan", "heading": "High cardinality", "group": "API", "url": "/docs/api/scans#high-cardinality", "summary": "Values scans cover fields too diverse for snapshot facets and retain exact counts for the highest-frequency values up to a much larger cap. Truncation, upstream saturation, and vector approximation are reported independently.", "facts": [ { "kind": "code", "literal": "truncated: true", "chunkId": "api/scans#high-cardinality" }, { "kind": "code", "literal": "truncated", "chunkId": "api/scans#high-cardinality" }, { "kind": "code", "literal": "bounded", "chunkId": "api/scans#high-cardinality" }, { "kind": "code", "literal": "approximate", "chunkId": "api/scans#high-cardinality" }, { "kind": "code", "literal": "top_k", "chunkId": "api/scans#high-cardinality" } ], "sources": [ { "chunkId": "api/scans#high-cardinality", "url": "/docs/api/scans#high-cardinality", "anchor": "high-cardinality" } ], "mode": "source-primary", "terms": [ "high", "cardinality", "values", "scans", "cover", "fields", "diverse", "snapshot", "facets", "retain", "exact", "counts", "highest", "frequency", "much", "larger", "truncation", "upstream", "saturation", "vector", "approximation", "reported", "independently", "truncated", "true", "bounded", "approximate", "facet", "histograms", "field", "distinct", "skip", "beyond", "enumeration", "path", "exactly", "those", "accumulates", "histogram", "gateway" ] }, { "id": "api/scans#hybrid-text-count", "kind": "section", "title": "Scan", "heading": "Hybrid text count", "group": "API", "url": "/docs/api/scans#hybrid-text-count", "summary": "Hybrid-text counting unions lexical, fuzzy, and typo-surfacing legs, so it may be broader than the normal hybrid query route. It is intended as a generous live count beside typo-tolerant search results.", "facts": [ { "kind": "code", "literal": "count = await client.create_scan(\"products\", {\n \"mode\": \"count\",\n \"hybrid_text\": {\"field\": \"title\", \"query\": \"wireles headphones\"},\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n})", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "count, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Mode: \"count\",\n HybridText: &hevlayer.HybridTextScan{Field: \"title\", Query: \"wireles headphones\"},\n Filters: []interface{}{\"category\", \"Eq\", \"Electronics\"},\n})", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "const count = await client.createScan(\"products\", {\n mode: \"count\",\n hybrid_text: { field: \"title\", query: \"wireles headphones\" },\n filters: [\"category\", \"Eq\", \"Electronics\"],\n});", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"count\",\n \"hybrid_text\": {\"field\": \"title\", \"query\": \"wireles headphones\"},\n \"filters\": [\"category\", \"Eq\", \"Electronics\"]\n }'", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "query", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#hybrid-text-count" }, { "kind": "code", "literal": "fts", "chunkId": "api/scans#hybrid-text-count" } ], "sources": [ { "chunkId": "api/scans#hybrid-text-count", "url": "/docs/api/scans#hybrid-text-count", "anchor": "hybrid-text-count" } ], "mode": "source-primary", "terms": [ "hybrid", "text", "count", "counting", "unions", "lexical", "fuzzy", "typo", "surfacing", "legs", "broader", "normal", "query", "route", "intended", "generous", "live", "beside", "tolerant", "search", "results", "await", "client", "create", "scan", "products", "mode", "field", "title", "wireles", "headphones", "filters", "category", "electronics", "createscan", "hevlayer", "createscanrequest", "hybridtext", "hybridtextscan", "interface" ] }, { "id": "api/scans#id-mode", "kind": "section", "title": "Scan", "heading": "ID Mode", "group": "API", "url": "/docs/api/scans#id-mode", "summary": "Identifier scans create an asynchronous job over cache or origin and expose progress until completion, after which callers page through matching identifiers. Client helpers can create and poll the job automatically.", "facts": [ { "kind": "code", "literal": "job = await client.create_scan(\"products\", {\n \"source\": \"auto\",\n \"mode\": \"ids\",\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"threads\": 8,\n \"page_size\": 1000,\n})", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "job, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Source: \"auto\",\n Mode: \"ids\",\n Filters: []interface{}{\"category\", \"Eq\", \"Electronics\"},\n Threads: 8,\n PageSize: 1000,\n})", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "const job = await client.createScan(\"products\", {\n source: \"auto\",\n mode: \"ids\",\n filters: [\"category\", \"Eq\", \"Electronics\"],\n threads: 8,\n page_size: 1000,\n});", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"source\": \"auto\",\n \"mode\": \"ids\",\n \"filters\": [\"category\", \"Eq\", \"Electronics\"],\n \"threads\": 8,\n \"page_size\": 1000\n }'", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "{\n \"id\": \"scan-uuid\",\n \"namespace\": \"products\",\n \"source\": \"auto\",\n \"effective_source\": \"origin\",\n \"status\": \"running\",\n \"progress\": 0,\n \"documents_scanned\": 0,\n \"threads\": 8,\n \"created_at\": \"2026-05-26T10:00:00Z\"\n}", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "results = await client.get_scan_results(\"products\", job.id, limit=1000, offset=0)", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "results, err := client.GetScanResults(ctx, \"products\", scanID,\n &hevlayer.GetScanResultsParams{Limit: 1000, Offset: 0})", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "const results = await client.getScanResults(\"products\", job.id, {\n limit: 1000,\n offset: 0,\n});", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans/scan-uuid/results?limit=1000&offset=0\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "{\n \"ids\": [\"doc-1\", \"doc-2\"],\n \"total\": 2\n}", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "mode", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "ids", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "cache", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "origin", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "scan(...)", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "GetScan", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "status", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "completed", "chunkId": "api/scans#id-mode" }, { "kind": "code", "literal": "202 Accepted", "chunkId": "api/scans#id-mode" } ], "sources": [ { "chunkId": "api/scans#id-mode", "url": "/docs/api/scans#id-mode", "anchor": "id-mode" } ], "mode": "source-primary", "terms": [ "mode", "identifier", "scans", "create", "asynchronous", "cache", "origin", "expose", "progress", "until", "completion", "after", "callers", "page", "through", "matching", "identifiers", "client", "helpers", "poll", "automatically", "await", "scan", "products", "source", "auto", "filters", "category", "electronics", "threads", "size", "1000", "createscan", "hevlayer", "createscanrequest", "interface", "pagesize", "const", "curl", "post" ] }, { "id": "api/scans#operational-notes", "kind": "section", "title": "Scan", "heading": "Operational notes", "group": "API", "url": "/docs/api/scans#operational-notes", "summary": "Identifier and values jobs are ephemeral across gateway restarts, count scans have bounded deadlines, high-cardinality values may truncate, and origin fan-out has a configurable concurrency default. Snapshot counts remain exact at their stored watermark.", "facts": [ { "kind": "code", "literal": "truncated: true", "chunkId": "api/scans#operational-notes" }, { "kind": "code", "literal": "Index.spec.scan.threads", "chunkId": "api/scans#operational-notes" }, { "kind": "code", "literal": "watermark_ms", "chunkId": "api/scans#operational-notes" } ], "sources": [ { "chunkId": "api/scans#operational-notes", "url": "/docs/api/scans#operational-notes", "anchor": "operational-notes" } ], "mode": "source-primary", "terms": [ "operational", "notes", "identifier", "values", "jobs", "ephemeral", "across", "gateway", "restarts", "count", "scans", "bounded", "deadlines", "high", "cardinality", "truncate", "origin", "configurable", "concurrency", "default", "snapshot", "counts", "remain", "exact", "their", "stored", "watermark", "truncated", "true", "index", "spec", "scan", "threads", "state", "memory", "resets", "restart", "deadline", "maximum", "300s" ] }, { "id": "api/scans#precomputed-serving", "kind": "section", "title": "Scan", "heading": "Precomputed serving", "group": "API", "url": "/docs/api/scans#precomputed-serving", "summary": "An unfiltered values request for a facet already present in the latest snapshot can finish immediately from its histogram. Missing, skipped, or selector-constrained fields fall through under automatic source selection or fail when snapshot use is forced.", "facts": [ { "kind": "code", "literal": "filters", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "fields[]", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "202", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "status: completed", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "effective_source: snapshot", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "snapshot_sha", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "watermark_ms", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "fields_skipped[]", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "auto", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "412 precondition_failed", "chunkId": "api/scans#precomputed-serving" }, { "kind": "code", "literal": "source: snapshot", "chunkId": "api/scans#precomputed-serving" } ], "sources": [ { "chunkId": "api/scans#precomputed-serving", "url": "/docs/api/scans#precomputed-serving", "anchor": "precomputed-serving" } ], "mode": "source-primary", "terms": [ "precomputed", "serving", "unfiltered", "values", "request", "facet", "already", "present", "latest", "snapshot", "finish", "immediately", "histogram", "missing", "skipped", "selector", "constrained", "fields", "fall", "through", "under", "automatic", "source", "selection", "fail", "forced", "filters", "status", "completed", "effective", "watermark", "auto", "precondition", "failed", "scan", "ranked", "field", "answered", "straight", "completes" ] }, { "id": "api/scans#radius-count", "kind": "section", "title": "Scan", "heading": "Radius count", "group": "API", "url": "/docs/api/scans#radius-count", "summary": "Vector-radius scans count neighbors inside a finite distance bound using origin nearest-neighbor retrieval. Membership is approximate because of vector-index recall, independent of whether any shard hit its retrieval cap.", "facts": [ { "kind": "code", "literal": "count = await client.create_scan(\"products\", {\n \"mode\": \"count\",\n \"ann\": {\"field\": \"vector\", \"vector\": [0.12, -0.3, 0.88], \"radius\": 0.25},\n})", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "count, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Mode: \"count\",\n Ann: &hevlayer.AnnScan{Field: \"vector\", Vector: []float64{0.12, -0.3, 0.88}, Radius: 0.25},\n})", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "const count = await client.createScan(\"products\", {\n mode: \"count\",\n ann: { field: \"vector\", vector: [0.12, -0.3, 0.88], radius: 0.25 },\n});", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"count\",\n \"ann\": {\"field\": \"vector\", \"vector\": [0.12, -0.3, 0.88], \"radius\": 0.25}\n }'", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "{\n \"count\": 980,\n \"served_by\": \"origin\",\n \"approximate\": true,\n \"bounded\": false,\n \"timed_out\": false,\n \"shards_saturated\": 0,\n \"shards_total\": 1,\n \"threads\": 1,\n \"elapsed_ms\": 51\n}", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "radius", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "ann", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "field", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "vector", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "fts", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "approximate: true", "chunkId": "api/scans#radius-count" }, { "kind": "code", "literal": "$dist", "chunkId": "api/scans#radius-count" } ], "sources": [ { "chunkId": "api/scans#radius-count", "url": "/docs/api/scans#radius-count", "anchor": "radius-count" } ], "mode": "source-primary", "terms": [ "radius", "count", "vector", "scans", "neighbors", "inside", "finite", "distance", "bound", "origin", "nearest", "neighbor", "retrieval", "membership", "approximate", "because", "index", "recall", "independent", "whether", "shard", "await", "client", "create", "scan", "products", "mode", "field", "createscan", "hevlayer", "createscanrequest", "annscan", "float64", "const", "curl", "post", "layer", "gateway", "namespaces", "authorization" ] }, { "id": "api/scans#routes", "kind": "section", "title": "Scan", "heading": "Routes", "group": "API", "url": "/docs/api/scans#routes", "summary": "The scan surface creates jobs or immediate counts, lists and inspects jobs, reads completed identifier or value results, and removes ephemeral job state.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}/scans", "chunkId": "api/scans#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/scans", "chunkId": "api/scans#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/scans/{id}", "chunkId": "api/scans#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/scans/{id}/results", "chunkId": "api/scans#routes" }, { "kind": "code", "literal": "DELETE /v2/namespaces/{ns}/scans/{id}", "chunkId": "api/scans#routes" } ], "sources": [ { "chunkId": "api/scans#routes", "url": "/docs/api/scans#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "scan", "surface", "creates", "jobs", "immediate", "counts", "lists", "inspects", "reads", "completed", "identifier", "value", "results", "removes", "ephemeral", "state", "post", "namespaces", "scans", "delete", "route", "method", "behavior", "create", "values", "return", "count", "list", "namespace", "read", "drop", "memory" ] }, { "id": "api/scans#sources", "kind": "section", "title": "Scan", "heading": "Sources", "group": "API", "url": "/docs/api/scans#sources", "summary": "Filter scans can choose snapshots, cache, or origin according to mode and eligibility. Ranked text and vector selectors always use origin because snapshots and cache do not evaluate those rankings.", "facts": [ { "kind": "code", "literal": "auto", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "snapshot", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "Eq", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "In", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "fields[]", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "cache", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "origin", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "fts", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "ann", "chunkId": "api/scans#sources" }, { "kind": "code", "literal": "422", "chunkId": "api/scans#sources" } ], "sources": [ { "chunkId": "api/scans#sources", "url": "/docs/api/scans#sources", "anchor": "sources" } ], "mode": "source-primary", "terms": [ "sources", "filter", "scans", "choose", "snapshots", "cache", "origin", "according", "mode", "eligibility", "ranked", "text", "vector", "selectors", "always", "because", "evaluate", "those", "rankings", "auto", "snapshot", "fields", "hybrid", "source", "count", "values", "fresh", "enough", "otherwise", "first", "eligible", "supported", "latest", "only", "requires", "facet", "listing", "unfiltered", "scan", "field" ] }, { "id": "api/scans#values-mode", "kind": "section", "title": "Scan", "heading": "Values Mode", "group": "API", "url": "/docs/api/scans#values-mode", "summary": "Values scans asynchronously enumerate distinct scalar or string-array field values with per-document counts and deterministic ordering. They reject vector fields and expose truncation, saturation, or approximation when applicable.", "facts": [ { "kind": "code", "literal": "job = await client.create_scan(\"products\", {\n \"mode\": \"values\",\n \"field\": \"category\",\n \"source\": \"auto\",\n \"filters\": [\"in_stock\", \"Eq\", True],\n})", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "job, err := client.CreateScan(ctx, \"products\", &hevlayer.CreateScanRequest{\n Mode: \"values\",\n Field: \"category\",\n Source: \"auto\",\n Filters: []interface{}{\"in_stock\", \"Eq\", true},\n})", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "const job = await client.createScan(\"products\", {\n mode: \"values\",\n field: \"category\",\n source: \"auto\",\n filters: [\"in_stock\", \"Eq\", true],\n});", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/scans\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"values\",\n \"field\": \"category\",\n \"source\": \"auto\",\n \"filters\": [\"in_stock\", \"Eq\", true]\n }'", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "{\n \"id\": \"scan-uuid\",\n \"namespace\": \"products\",\n \"mode\": \"values\",\n \"field\": \"category\",\n \"source\": \"auto\",\n \"effective_source\": \"origin\",\n \"status\": \"running\",\n \"progress\": 0,\n \"documents_scanned\": 0,\n \"threads\": 8,\n \"created_at\": \"2026-05-26T10:00:00Z\"\n}", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "{\n \"values\": [\n {\"v\": \"electronics\", \"n\": 4210},\n {\"v\": \"books\", \"n\": 1240}\n ],\n \"total\": 2,\n \"truncated\": false\n}", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "field", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "mode: values", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "422", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "202 Accepted", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "scan(...)", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "status", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "completed", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "limit", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "offset", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": "bounded: true", "chunkId": "api/scans#values-mode" }, { "kind": "code", "literal": ">=", "chunkId": "api/scans#values-mode" } ], "sources": [ { "chunkId": "api/scans#values-mode", "url": "/docs/api/scans#values-mode", "anchor": "values-mode" } ], "mode": "source-primary", "terms": [ "values", "mode", "scans", "asynchronously", "enumerate", "distinct", "scalar", "string", "array", "field", "document", "counts", "deterministic", "ordering", "reject", "vector", "fields", "expose", "truncation", "saturation", "approximation", "applicable", "await", "client", "create", "scan", "products", "category", "source", "auto", "filters", "stock", "true", "createscan", "hevlayer", "createscanrequest", "interface", "const", "curl", "post" ] }, { "id": "api/search-history", "kind": "section", "title": "Query History", "heading": null, "group": "API", "url": "/docs/api/search-history", "summary": "Every served query can be recorded in a durable per-namespace object-storage log with a hot recent cache, while correlated fetch events form a companion clickstream. Together they support relevance analysis, experiments, and incident reconstruction.", "facts": [ { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/search-history" } ], "sources": [ { "chunkId": "api/search-history", "url": "/docs/api/search-history", "anchor": null } ], "mode": "source-primary", "terms": [ "every", "served", "query", "recorded", "durable", "namespace", "object", "storage", "recent", "cache", "while", "correlated", "fetch", "events", "form", "companion", "clickstream", "together", "support", "relevance", "analysis", "experiments", "incident", "reconstruction", "codetabs", "astro", "history", "backed", "jsonl", "layer", "logs", "gateway", "serves", "trail", "mirrored", "fast", "reads", "downstream", "consumers", "back" ] }, { "id": "api/search-history#clickstream-entry", "kind": "section", "title": "Query History", "heading": "Clickstream entry", "group": "API", "url": "/docs/api/search-history#clickstream-entry", "summary": "Clickstream events record the fetched document, search trace, source, and cache outcome. The shared trace identity links result consumption back to the query that produced it.", "facts": [ { "kind": "code", "literal": "{\n \"events\": [\n {\n \"timestamp\": \"2026-05-22T08:00:02.143Z\",\n \"timestamp_nanos\": 1747900802143000000,\n \"trace_id\": \"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\",\n \"namespace\": \"products\",\n \"doc_id\": \"asin-B08N5WRWNW\",\n \"tags\": [\"session:abc123\"],\n \"source\": \"fetch\",\n \"served_from\": \"cache\"\n }\n ],\n \"next_cursor\": \"1747900802142000000\"\n}", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "events = await client.list_clickstream(\n \"products\",\n trace_id=\"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\",\n)", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "events, err := client.ListClickstream(ctx, \"products\",\n &hevlayer.ListClickstreamParams{\n TraceID: \"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\",\n })", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "const events = await client.listClickstream(\"products\", {\n traceId: \"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\",\n});", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/clickstream?trace_id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "trace_id", "chunkId": "api/search-history#clickstream-entry" }, { "kind": "code", "literal": "served_from", "chunkId": "api/search-history#clickstream-entry" } ], "sources": [ { "chunkId": "api/search-history#clickstream-entry", "url": "/docs/api/search-history#clickstream-entry", "anchor": "clickstream-entry" } ], "mode": "source-primary", "terms": [ "clickstream", "entry", "events", "record", "fetched", "document", "search", "trace", "source", "cache", "outcome", "shared", "identity", "links", "result", "consumption", "back", "query", "produced", "timestamp", "2026", "22t08", "143z", "nanos", "1747900802143000000", "f81d4fae", "7dec", "11d0", "a765", "00a0c91e6bf6", "namespace", "products", "asin", "b08n5wrwnw", "tags", "session", "abc123", "fetch", "served", "next" ] }, { "id": "api/search-history#query-parameters", "kind": "section", "title": "Query History", "heading": "Query parameters", "group": "API", "url": "/docs/api/search-history#query-parameters", "summary": "History and clickstream reads support conjunctive tag filtering, bounded time ranges, newest-first cursor pagination, and capped page sizes.", "facts": [ { "kind": "code", "literal": "tag", "chunkId": "api/search-history#query-parameters" }, { "kind": "code", "literal": "from", "chunkId": "api/search-history#query-parameters" }, { "kind": "code", "literal": "to", "chunkId": "api/search-history#query-parameters" }, { "kind": "code", "literal": "before", "chunkId": "api/search-history#query-parameters" }, { "kind": "code", "literal": "timestamp_nanos", "chunkId": "api/search-history#query-parameters" }, { "kind": "code", "literal": "limit", "chunkId": "api/search-history#query-parameters" } ], "sources": [ { "chunkId": "api/search-history#query-parameters", "url": "/docs/api/search-history#query-parameters", "anchor": "query-parameters" } ], "mode": "source-primary", "terms": [ "query", "parameters", "history", "clickstream", "reads", "support", "conjunctive", "filtering", "bounded", "time", "ranges", "newest", "first", "cursor", "pagination", "capped", "page", "sizes", "before", "timestamp", "nanos", "limit", "param", "purpose", "comma", "separated", "filter", "semantics", "every", "must", "match", "rfc3339", "bounds", "return", "entries", "strictly", "older", "given", "timestampnanos", "default" ] }, { "id": "api/search-history#routes", "kind": "section", "title": "Query History", "heading": "Routes", "group": "API", "url": "/docs/api/search-history#routes", "summary": "Separate namespace feeds return query history and correlated fetch events, with legacy aliases retained for client compatibility.", "facts": [ { "kind": "code", "literal": "GET /v2/namespaces/{ns}/search-history", "chunkId": "api/search-history#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/clickstream", "chunkId": "api/search-history#routes" }, { "kind": "code", "literal": "/v1/", "chunkId": "api/search-history#routes" } ], "sources": [ { "chunkId": "api/search-history#routes", "url": "/docs/api/search-history#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "separate", "namespace", "feeds", "return", "query", "history", "correlated", "fetch", "events", "legacy", "aliases", "retained", "client", "compatibility", "namespaces", "search", "clickstream", "route", "behavior", "newest", "first", "versions", "both", "identical", "held" ] }, { "id": "api/search-history#search-history-entry", "kind": "section", "title": "Query History", "heading": "Search history entry", "group": "API", "url": "/docs/api/search-history#search-history-entry", "summary": "A history entry captures time, trace identity, optional human query text, stable cut, a structured query summary, ranked result identifiers, and segmentation tags. Hybrid and routed queries remain replayable as one expression with their routing decision.", "facts": [ { "kind": "code", "literal": "timestamp", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "timestamp_nanos", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "trace_id", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "raw_query", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "x-hevlayer-search-query", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "stable_as_of", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "query", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "top_result_ids", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "tags", "chunkId": "api/search-history#search-history-entry" }, { "kind": "code", "literal": "HybridText", "chunkId": "api/search-history#search-history-entry" }, { "kind": "value", "literal": "e.g", "chunkId": "api/search-history#search-history-entry" } ], "sources": [ { "chunkId": "api/search-history#search-history-entry", "url": "/docs/api/search-history#search-history-entry", "anchor": "search-history-entry" } ], "mode": "source-primary", "terms": [ "search", "history", "entry", "captures", "time", "trace", "identity", "optional", "human", "query", "text", "stable", "structured", "summary", "ranked", "result", "identifiers", "segmentation", "tags", "hybrid", "routed", "queries", "remain", "replayable", "expression", "their", "routing", "decision", "timestamp", "nanos", "hevlayer", "hybridtext", "entries", "2026", "22t08", "000z", "timestampnanos", "1747900800000000000", "namespace", "products" ] }, { "id": "api/search-history#storage", "kind": "section", "title": "Query History", "heading": "Storage", "group": "API", "url": "/docs/api/search-history#storage", "summary": "History writes are best-effort and never delay query responses. Object storage is durable, while the cache accelerates recent reads and can be bypassed during an outage.", "facts": [ { "kind": "code", "literal": "search-history/{namespace}/{YYYY-MM-DD}/{timestamp_nanos}.jsonl", "chunkId": "api/search-history#storage" } ], "sources": [ { "chunkId": "api/search-history#storage", "url": "/docs/api/search-history#storage", "anchor": "storage" } ], "mode": "source-primary", "terms": [ "storage", "history", "writes", "best", "effort", "never", "delay", "query", "responses", "object", "durable", "while", "cache", "accelerates", "recent", "reads", "bypassed", "during", "outage", "search", "namespace", "yyyy", "timestamp", "nanos", "jsonl", "timestampnanos", "block", "response", "aerospike", "holds", "window", "fast", "store", "degrades", "read", "latency", "durability", "list", "calls", "walk" ] }, { "id": "api/search-history#tag-contract", "kind": "section", "title": "Query History", "heading": "Tag contract", "group": "API", "url": "/docs/api/search-history#tag-contract", "summary": "Tags are comma-separated, normalized, sorted, deduplicated, character-limited labels with bounded count and length. Listing filters require every requested tag to be present.", "facts": [ { "kind": "code", "literal": "x-hevlayer-tags", "chunkId": "api/search-history#tag-contract" }, { "kind": "code", "literal": "?tag=", "chunkId": "api/search-history#tag-contract" }, { "kind": "code", "literal": "?tag=a,b", "chunkId": "api/search-history#tag-contract" } ], "sources": [ { "chunkId": "api/search-history#tag-contract", "url": "/docs/api/search-history#tag-contract", "anchor": "tag-contract" } ], "mode": "source-primary", "terms": [ "contract", "tags", "comma", "separated", "normalized", "sorted", "deduplicated", "character", "limited", "labels", "bounded", "count", "length", "listing", "filters", "require", "every", "requested", "present", "hevlayer", "layer", "splits", "commas", "trims", "whitespace", "drops", "empty", "values", "sorts", "dedupes", "before", "storing", "matching", "separators", "cannot", "escaped", "limits", "limit", "value", "unique" ] }, { "id": "api/search-history#writing-metadata", "kind": "section", "title": "Query History", "heading": "Writing metadata", "group": "API", "url": "/docs/api/search-history#writing-metadata", "summary": "Callers may attach the original human query and segmentation labels to search requests, then filter history by those labels. Query text belongs in its dedicated metadata field rather than being duplicated as a tag.", "facts": [ { "kind": "code", "literal": "query = await client.query_namespace(\n \"products\",\n {\"vector\": embedding, \"top_k\": 10, \"include_attributes\": [\"title\"]},\n raw_query=\"wireless headphones\",\n tags=[\"app:hev-shop\", \"surface:storefront\", \"route:search\", \"page:first\"],\n)\n\nhistory = await client.list_search_history(\n \"products\",\n tags=[\"app:hev-shop\", \"route:search\", \"page:first\"],\n limit=20,\n)", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "const query = await client.queryNamespace(\n \"products\",\n { vector: embedding, top_k: 10, include_attributes: [\"title\"] },\n {\n searchQuery: \"wireless headphones\",\n tags: [\"app:hev-shop\", \"surface:storefront\", \"route:search\", \"page:first\"],\n },\n);\n\nconst history = await client.listSearchHistory(\"products\", {\n tags: [\"app:hev-shop\", \"route:search\", \"page:first\"],\n limit: 20,\n});", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "x-hevlayer-search-query", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "x-hevlayer-tags", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "raw_query", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "tags", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "WithSearchQuery", "chunkId": "api/search-history#writing-metadata" }, { "kind": "code", "literal": "WithSearchTags", "chunkId": "api/search-history#writing-metadata" } ], "sources": [ { "chunkId": "api/search-history#writing-metadata", "url": "/docs/api/search-history#writing-metadata", "anchor": "writing-metadata" } ], "mode": "source-primary", "terms": [ "writing", "metadata", "callers", "attach", "original", "human", "query", "segmentation", "labels", "search", "requests", "filter", "history", "those", "text", "belongs", "dedicated", "field", "rather", "being", "duplicated", "await", "client", "namespace", "products", "vector", "embedding", "include", "attributes", "title", "wireless", "headphones", "tags", "shop", "surface", "storefront", "route", "page", "first", "list" ] }, { "id": "api/snapshots", "kind": "section", "title": "Snapshot History", "heading": null, "group": "API", "url": "/docs/api/snapshots", "summary": "Snapshots are durable, content-addressed namespace facet histograms with value listings and counts, mirrored into the hot cache for recent reads. They can be materialized on demand or written from stable namespace observations.", "facts": [ { "kind": "code", "literal": "values[].v", "chunkId": "api/snapshots" }, { "kind": "code", "literal": "values[].n", "chunkId": "api/snapshots" }, { "kind": "code", "literal": "POST /snapshots", "chunkId": "api/snapshots" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/snapshots" } ], "sources": [ { "chunkId": "api/snapshots", "url": "/docs/api/snapshots", "anchor": null } ], "mode": "source-primary", "terms": [ "snapshots", "durable", "content", "addressed", "namespace", "facet", "histograms", "value", "listings", "counts", "mirrored", "cache", "recent", "reads", "materialized", "demand", "written", "stable", "observations", "values", "post", "codetabs", "astro", "snapshot", "jobs", "history", "bodies", "activity", "streams", "carry", "stored", "durably", "aerospike", "latest", "body", "materialize", "field", "routes", "read", "chronology" ] }, { "id": "api/snapshots#activity", "kind": "section", "title": "Snapshot History", "heading": "Activity", "group": "API", "url": "/docs/api/snapshots#activity", "summary": "A cross-namespace activity feed lists snapshot lifecycle events after a required time bound, with optional namespace filtering and cursor pagination. Query and click activity remain separate feeds.", "facts": [ { "kind": "code", "literal": "activity = await client.list_snapshot_activity(since=1747200000000, limit=50)", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "activity, err := client.ListSnapshotActivity(ctx,\n &hevlayer.ListSnapshotActivityParams{Since: 1747200000000, Limit: 50})", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "const activity = await client.listSnapshotActivity({\n since: 1747200000000,\n limit: 50,\n});", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/activity/snapshots?since=1747200000000&limit=50\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "since", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "ts_ms", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "limit", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "namespace", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "cursor", "chunkId": "api/snapshots#activity" }, { "kind": "code", "literal": "next_cursor", "chunkId": "api/snapshots#activity" } ], "sources": [ { "chunkId": "api/snapshots#activity", "url": "/docs/api/snapshots#activity", "anchor": "activity" } ], "mode": "source-primary", "terms": [ "activity", "cross", "namespace", "feed", "lists", "snapshot", "lifecycle", "events", "after", "required", "time", "bound", "optional", "filtering", "cursor", "pagination", "query", "click", "remain", "separate", "feeds", "await", "client", "list", "since", "1747200000000", "limit", "listsnapshotactivity", "hevlayer", "listsnapshotactivityparams", "const", "curl", "layer", "gateway", "snapshots", "authorization", "bearer", "next", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/snapshots#history", "kind": "section", "title": "Snapshot History", "heading": "History", "group": "API", "url": "/docs/api/snapshots#history", "summary": "Snapshot history lists durable object keys newest first without loading every body. It supports digest-based pagination, while operator tags remain metadata outside the content hash.", "facts": [ { "kind": "code", "literal": "history = await client.list_namespace_history(\"products\", limit=20)", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "history, err := client.ListNamespaceHistory(ctx, \"products\",\n &hevlayer.ListNamespaceHistoryParams{Limit: 20})", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "const history = await client.listNamespaceHistory(\"products\", { limit: 20 });", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/history?limit=20\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "[\n {\"watermark_ms\": 1747300000123, \"sha\": \"3f9e8b21...\", \"tags\": [\"pre-migration\"]},\n {\"watermark_ms\": 1747299600045, \"sha\": \"a1c5b09f...\", \"tags\": []}\n]", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "limit", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "before", "chunkId": "api/snapshots#history" }, { "kind": "code", "literal": "tags", "chunkId": "api/snapshots#history" } ], "sources": [ { "chunkId": "api/snapshots#history", "url": "/docs/api/snapshots#history", "anchor": "history" } ], "mode": "source-primary", "terms": [ "history", "snapshot", "lists", "durable", "object", "keys", "newest", "first", "without", "loading", "every", "body", "supports", "digest", "based", "pagination", "while", "operator", "tags", "remain", "metadata", "outside", "content", "hash", "await", "client", "list", "namespace", "products", "limit", "listnamespacehistory", "hevlayer", "listnamespacehistoryparams", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer" ] }, { "id": "api/snapshots#manual-snapshot", "kind": "section", "title": "Snapshot History", "heading": "Manual snapshot", "group": "API", "url": "/docs/api/snapshots#manual-snapshot", "summary": "An on-demand snapshot job chooses stored, cache, or origin data based on the requested source and filter eligibility. Origin computation persists a new durable body, and completed jobs expose the resulting content digest and stable cut.", "facts": [ { "kind": "code", "literal": "job = await client.create_snapshot(\"products\", {\n \"field\": \"category\",\n \"source\": \"auto\",\n \"filters\": [\"brand\", \"Eq\", \"Acme\"],\n \"page_size\": 1000,\n})", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "job, err := client.CreateSnapshot(ctx, \"products\", &hevlayer.CreateSnapshotRequest{\n Field: \"category\",\n Source: \"auto\",\n Filters: []interface{}{\"brand\", \"Eq\", \"Acme\"},\n PageSize: 1000,\n})", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "const job = await client.createSnapshot(\"products\", {\n field: \"category\",\n source: \"auto\",\n filters: [\"brand\", \"Eq\", \"Acme\"],\n page_size: 1000,\n});", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/snapshots\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"field\": \"category\",\n \"source\": \"auto\",\n \"filters\": [\"brand\", \"Eq\", \"Acme\"],\n \"page_size\": 1000\n }'", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "{\n \"id\": \"snapshot-job-uuid\",\n \"namespace\": \"products\",\n \"field\": \"category\",\n \"source\": \"auto\",\n \"status\": \"running\",\n \"progress\": 0,\n \"documents_scanned\": 0,\n \"created_at\": \"2026-05-26T10:00:00Z\"\n}", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "job = await client.get_snapshot_job(\"products\", job.id)", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "job, err := client.GetSnapshotJob(ctx, \"products\", jobID)", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "const job = await client.getSnapshotJob(\"products\", jobId);", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/snapshot-jobs/snapshot-job-uuid\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "{\n \"id\": \"snapshot-job-uuid\",\n \"namespace\": \"products\",\n \"field\": \"category\",\n \"source\": \"origin\",\n \"status\": \"completed\",\n \"documents_scanned\": 12844,\n \"sha\": \"3f9e8b21\",\n \"stable_as_of\": 1747300000123\n}", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "auto", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "stored", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "cache", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "origin", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "202 Accepted", "chunkId": "api/snapshots#manual-snapshot" }, { "kind": "code", "literal": "sha", "chunkId": "api/snapshots#manual-snapshot" } ], "sources": [ { "chunkId": "api/snapshots#manual-snapshot", "url": "/docs/api/snapshots#manual-snapshot", "anchor": "manual-snapshot" } ], "mode": "source-primary", "terms": [ "manual", "snapshot", "demand", "chooses", "stored", "cache", "origin", "data", "based", "requested", "source", "filter", "eligibility", "computation", "persists", "durable", "body", "completed", "jobs", "expose", "resulting", "content", "digest", "stable", "await", "client", "create", "products", "field", "category", "auto", "filters", "brand", "acme", "page", "size", "1000", "createsnapshot", "hevlayer", "createsnapshotrequest" ] }, { "id": "api/snapshots#routes", "kind": "section", "title": "Snapshot History", "heading": "Routes", "group": "API", "url": "/docs/api/snapshots#routes", "summary": "Snapshot operations create and inspect jobs, manage automatic policy, list durable history, fetch bodies and lifecycle activity, and direct callers to checkpoints when they need a named cut rather than a new scan.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}/snapshots", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/snapshot-policy", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "PUT /v2/namespaces/{ns}/snapshot-policy", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "facetFields", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "interval", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "retention", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "Index.spec.snapshot", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/snapshot-jobs", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/snapshot-jobs/{id}", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/history", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/snapshots/{sha}", "chunkId": "api/snapshots#routes" }, { "kind": "code", "literal": "GET /v2/activity/snapshots", "chunkId": "api/snapshots#routes" } ], "sources": [ { "chunkId": "api/snapshots#routes", "url": "/docs/api/snapshots#routes", "anchor": "routes" } ], "mode": "source-primary", "terms": [ "routes", "snapshot", "operations", "create", "inspect", "jobs", "manage", "automatic", "policy", "list", "durable", "history", "fetch", "bodies", "lifecycle", "activity", "direct", "callers", "checkpoints", "need", "named", "rather", "scan", "post", "namespaces", "snapshots", "facetfields", "interval", "retention", "index", "spec", "route", "method", "behavior", "demand", "field", "read", "managed", "shape", "memory" ] }, { "id": "api/snapshots#snapshot-body", "kind": "section", "title": "Snapshot History", "heading": "Snapshot body", "group": "API", "url": "/docs/api/snapshots#snapshot-body", "summary": "A snapshot body records namespace, watermark, content digest, row count, complete facet histograms, and fields skipped for excessive cardinality. Values scans remain available for skipped fields with a larger cap.", "facts": [ { "kind": "code", "literal": "body = await client.get_namespace_snapshot(\"products\", \"3f9e8b2\")", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "body, err := client.GetNamespaceSnapshot(ctx, \"products\", \"3f9e8b2\")", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "const body = await client.getNamespaceSnapshot(\"products\", \"3f9e8b2\");", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/snapshots/3f9e8b2\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "fields[].values[].v", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "fields[].values[].n", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "row_count", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "indexed", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "index_lag_rows", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "fields[]", "chunkId": "api/snapshots#snapshot-body" }, { "kind": "code", "literal": "fields_skipped[]", "chunkId": "api/snapshots#snapshot-body" } ], "sources": [ { "chunkId": "api/snapshots#snapshot-body", "url": "/docs/api/snapshots#snapshot-body", "anchor": "snapshot-body" } ], "mode": "source-primary", "terms": [ "snapshot", "body", "records", "namespace", "watermark", "content", "digest", "count", "complete", "facet", "histograms", "fields", "skipped", "excessive", "cardinality", "values", "scans", "remain", "available", "larger", "await", "client", "products", "3f9e8b2", "getnamespacesnapshot", "const", "curl", "layer", "gateway", "namespaces", "snapshots", "authorization", "bearer", "indexed", "index", "rows", "layergatewayurl", "layergatewayapikey", "watermarkms", "1747300000123" ] }, { "id": "api/snapshots#snapshot-policy", "kind": "section", "title": "Snapshot History", "heading": "Snapshot policy", "group": "API", "url": "/docs/api/snapshots#snapshot-policy", "summary": "Automatic snapshots are enabled by declaring facet fields plus minimum spacing and retention. Writes are event-driven by stable advances, policy edits refresh without restart, and origin work shares the scan fan-out limit.", "facts": [ { "kind": "code", "literal": "apiVersion: hevlayer.com/v1\nkind: Index\nmetadata:\n name: products\nspec:\n backend:\n namespace: products\n snapshot:\n interval: 5m\n retention: 30d\n facetFields:\n - category\n - brand", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "curl -X PUT \"$LAYER_GATEWAY_URL/v2/namespaces/products/snapshot-policy\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"facetFields\": [\"category\", \"brand\"],\n \"interval\": \"5m\",\n \"retention\": \"30d\"\n }'", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "Index.spec.snapshot", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "Index", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "facetFields", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "[]", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "interval", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "5m", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "LAYER_SNAPSHOT_MIN_INTERVAL_MS", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "retention", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "never", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "30d", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "GET /v2/namespaces/{ns}/snapshot-policy", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "POST /snapshots", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "source: origin", "chunkId": "api/snapshots#snapshot-policy" }, { "kind": "code", "literal": "spec.scan.threads", "chunkId": "api/snapshots#snapshot-policy" } ], "sources": [ { "chunkId": "api/snapshots#snapshot-policy", "url": "/docs/api/snapshots#snapshot-policy", "anchor": "snapshot-policy" } ], "mode": "source-primary", "terms": [ "snapshot", "policy", "automatic", "snapshots", "enabled", "declaring", "facet", "fields", "plus", "minimum", "spacing", "retention", "writes", "event", "driven", "stable", "advances", "edits", "refresh", "without", "restart", "origin", "work", "shares", "scan", "limit", "apiversion", "hevlayer", "kind", "index", "metadata", "name", "products", "spec", "backend", "namespace", "interval", "facetfields", "category", "brand" ] }, { "id": "api/warm-cache", "kind": "section", "title": "Warm cache", "heading": null, "group": "API", "url": "/docs/api/warm-cache", "summary": "Layer supports both the backing store's warm hint and a gateway-specific asynchronous job that warms documents and recent snapshot data.", "facts": [ { "kind": "code", "literal": "hint_cache_warm", "chunkId": "api/warm-cache" }, { "kind": "code", "literal": "warm", "chunkId": "api/warm-cache" }, { "kind": "code", "literal": "GET /v1/namespaces/{ns}/hint_cache_warm", "chunkId": "api/warm-cache" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/warm-cache" }, { "kind": "value", "literal": "Callout.astro", "chunkId": "api/warm-cache" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/warm-cache" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/warm-cache" } ], "sources": [ { "chunkId": "api/warm-cache", "url": "/docs/api/warm-cache", "anchor": null } ], "mode": "source-primary", "terms": [ "layer", "supports", "both", "backing", "store", "warm", "hint", "gateway", "specific", "asynchronous", "warms", "documents", "recent", "snapshot", "data", "cache", "namespaces", "upstream", "astro", "callout", "codetabs", "turbopuffer", "namespace", "document", "mirror", "exposes", "endpoints", "hintcachewarm", "compatible", "only", "shortcut", "creates", "matches", "call", "advises", "index", "load", "additionally", "runs", "steps" ] }, { "id": "api/warm-cache#cache-cold-behavior", "kind": "section", "title": "Warm cache", "heading": "Cache-cold behavior", "group": "API", "url": "/docs/api/warm-cache#cache-cold-behavior", "summary": "Throughput-oriented warm and cache-only operations fail clearly when the cache is unavailable, while correctness-oriented document fetch falls through to origin. A bare upstream warm hint remains independent of gateway cache health.", "facts": [ { "kind": "code", "literal": "cache_cold", "chunkId": "api/warm-cache#cache-cold-behavior" }, { "kind": "code", "literal": "x-layer-cache: miss-on-error", "chunkId": "api/warm-cache#cache-cold-behavior" }, { "kind": "code", "literal": "hint_cache_warm", "chunkId": "api/warm-cache#cache-cold-behavior" }, { "kind": "code", "literal": "documents", "chunkId": "api/warm-cache#cache-cold-behavior" }, { "kind": "code", "literal": "snapshots", "chunkId": "api/warm-cache#cache-cold-behavior" } ], "sources": [ { "chunkId": "api/warm-cache#cache-cold-behavior", "url": "/docs/api/warm-cache#cache-cold-behavior", "anchor": "cache-cold-behavior" } ], "mode": "source-primary", "terms": [ "cache", "cold", "behavior", "throughput", "oriented", "warm", "only", "operations", "fail", "clearly", "unavailable", "while", "correctness", "document", "fetch", "falls", "through", "origin", "bare", "upstream", "hint", "remains", "independent", "gateway", "health", "layer", "miss", "error", "documents", "snapshots", "jobs", "scans", "snapshot", "pipeline", "chunk", "reads", "return", "cachecold", "many", "fall" ] }, { "id": "api/warm-cache#hint-cache-warm", "kind": "section", "title": "Warm cache", "heading": "Hint-cache warm", "group": "API", "url": "/docs/api/warm-cache#hint-cache-warm", "summary": "Without options, the warm hint preserves upstream behavior exactly. With orchestration enabled, callers can independently warm the upstream index, document cache, and latest snapshot mirror and receive per-step status.", "facts": [ { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v1/namespaces/products/hint_cache_warm\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "result = await client.hint_cache_warm(\n \"products\",\n turbopuffer=False,\n documents=False,\n snapshots=True,\n)", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "const result = await client.hintCacheWarm(\"products\", {\n turbopuffer: false,\n documents: false,\n snapshots: true,\n});", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v1/namespaces/products/hint_cache_warm?turbopuffer=false&documents=false&snapshots=true\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "{\n \"namespace\": \"products\",\n \"turbopuffer\": { \"enabled\": true, \"status\": \"completed\" },\n \"documents\": {\n \"enabled\": true,\n \"status\": \"started\",\n \"job\": { \"id\": \"warm-job-uuid\", \"status\": \"running\" }\n },\n \"snapshots\": {\n \"enabled\": true,\n \"status\": \"completed\",\n \"key\": \"snapshots/products/...\",\n \"watermark_ms\": 1715600400000,\n \"sha\": \"...\"\n }\n}", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "turbopuffer", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "documents", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "snapshots", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "page_size", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "turbopuffer=true", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "documents=true", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "snapshots=true", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "false", "chunkId": "api/warm-cache#hint-cache-warm" }, { "kind": "code", "literal": "/warm-jobs/{id}", "chunkId": "api/warm-cache#hint-cache-warm" } ], "sources": [ { "chunkId": "api/warm-cache#hint-cache-warm", "url": "/docs/api/warm-cache#hint-cache-warm", "anchor": "hint-cache-warm" } ], "mode": "source-primary", "terms": [ "hint", "cache", "warm", "without", "options", "preserves", "upstream", "behavior", "exactly", "orchestration", "enabled", "callers", "independently", "index", "document", "latest", "snapshot", "mirror", "receive", "step", "status", "curl", "layer", "gateway", "namespaces", "products", "authorization", "bearer", "result", "await", "client", "turbopuffer", "false", "documents", "snapshots", "true", "const", "hintcachewarm", "namespace", "completed" ] }, { "id": "api/warm-cache#layer-warm", "kind": "section", "title": "Warm cache", "heading": "Layer warm", "group": "API", "url": "/docs/api/warm-cache#layer-warm", "summary": "A Layer warm job pages the backing store asynchronously, backfills the document cache, and advances the namespace's warmed-through watermark. This is useful after data was written outside the gateway.", "facts": [ { "kind": "code", "literal": "job = await client.warm_cache(\"products\", page_size=1000)", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "job, err := client.WarmCache(ctx, \"products\", &hevlayer.WarmCacheParams{\n PageSize: 1000,\n})", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "const job = await client.warmCache(\"products\", { pageSize: 1000 });", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/products/warm?page_size=1000\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "{\n \"id\": \"warm-job-uuid\",\n \"namespace\": \"products\",\n \"status\": \"running\",\n \"progress\": 0,\n \"documents_scanned\": 0,\n \"created_at\": \"2026-05-26T10:00:00Z\"\n}", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "job = await client.get_warm_job(\"products\", job.id)", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "job, err := client.GetWarmJob(ctx, \"products\", jobID)", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "const job = await client.getWarmJob(\"products\", jobId);", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/v2/namespaces/products/warm-jobs/warm-job-uuid\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\"", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "POST /v2/namespaces/{ns}/warm", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "cache_warmed_through", "chunkId": "api/warm-cache#layer-warm" }, { "kind": "code", "literal": "202 Accepted", "chunkId": "api/warm-cache#layer-warm" } ], "sources": [ { "chunkId": "api/warm-cache#layer-warm", "url": "/docs/api/warm-cache#layer-warm", "anchor": "layer-warm" } ], "mode": "source-primary", "terms": [ "layer", "warm", "pages", "backing", "store", "asynchronously", "backfills", "document", "cache", "advances", "namespace", "warmed", "through", "watermark", "useful", "after", "data", "written", "outside", "gateway", "await", "client", "products", "page", "size", "1000", "warmcache", "hevlayer", "warmcacheparams", "pagesize", "const", "curl", "post", "namespaces", "authorization", "bearer", "uuid", "status", "running", "progress" ] }, { "id": "api/write", "kind": "section", "title": "Write & Stage", "heading": null, "group": "API", "url": "/docs/api/write", "summary": "Namespace writes preserve native upsert, delete, patch, and filter-write behavior while validating Layer constraints, stamping each row-producing write, and mirroring explicit documents into cache best-effort.", "facts": [ { "kind": "code", "literal": "POST /v2/namespaces/{ns}", "chunkId": "api/write" }, { "kind": "code", "literal": "write_namespace", "chunkId": "api/write" }, { "kind": "code", "literal": "_hevlayer_upserted_at", "chunkId": "api/write" }, { "kind": "value", "literal": "StoreSwitch.astro", "chunkId": "api/write" }, { "kind": "value", "literal": "StoreNote.astro", "chunkId": "api/write" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/write" }, { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "api/write" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/write" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/write" } ], "sources": [ { "chunkId": "api/write", "url": "/docs/api/write", "anchor": null } ], "mode": "source-primary", "terms": [ "namespace", "writes", "preserve", "native", "upsert", "delete", "patch", "filter", "write", "behavior", "while", "validating", "layer", "constraints", "stamping", "producing", "mirroring", "explicit", "documents", "cache", "best", "effort", "post", "namespaces", "hevlayer", "upserted", "storeswitch", "astro", "storenote", "upstream", "featuregate", "codetabs", "turbopuffer", "rows", "stage", "body", "upserts", "deletes", "patches", "combined" ] }, { "id": "api/write#stage", "kind": "section", "title": "Write & Stage", "heading": "Stage", "group": "API", "url": "/docs/api/write#stage", "summary": "Pipeline staging stores document chunks for fast handoff and marks the document pending for embedding; re-staging replaces prior chunks. The cache copy is ephemeral, so durable pipeline backing is necessary for outage recovery.", "facts": [ { "kind": "code", "literal": "await client.put_pipeline_document_chunks(\"product-images\", \"asin-B08N5WRWNW\", {\n \"chunks\": [\n {\"id\": \"asin-B08N5WRWNW-0\", \"text\": \"Wireless noise-cancelling headphones\"},\n {\"id\": \"asin-B08N5WRWNW-1\", \"text\": \"40-hour battery life\", \"metadata\": {\"page\": 2}},\n ],\n})", "chunkId": "api/write#stage" }, { "kind": "code", "literal": "client.PutPipelineDocumentChunks(ctx, \"product-images\", \"asin-B08N5WRWNW\", &hevlayer.PutChunksRequest{\n Chunks: []hevlayer.Chunk{\n {ID: \"asin-B08N5WRWNW-0\", Text: \"Wireless noise-cancelling headphones\"},\n {ID: \"asin-B08N5WRWNW-1\", Text: \"40-hour battery life\", Metadata: map[string]interface{}{\"page\": 2}},\n },\n})", "chunkId": "api/write#stage" }, { "kind": "code", "literal": "await client.putPipelineDocumentChunks(\"product-images\", \"asin-B08N5WRWNW\", {\n chunks: [\n { id: \"asin-B08N5WRWNW-0\", text: \"Wireless noise-cancelling headphones\" },\n { id: \"asin-B08N5WRWNW-1\", text: \"40-hour battery life\", metadata: { page: 2 } },\n ],\n});", "chunkId": "api/write#stage" }, { "kind": "code", "literal": "curl -X PUT \"$LAYER_GATEWAY_URL/v2/pipelines/product-images/documents/asin-B08N5WRWNW\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"chunks\": [\n {\"id\": \"asin-B08N5WRWNW-0\", \"text\": \"Wireless noise-cancelling headphones\"},\n {\"id\": \"asin-B08N5WRWNW-1\", \"text\": \"40-hour battery life\", \"metadata\": {\"page\": 2}}\n ]\n }'", "chunkId": "api/write#stage" }, { "kind": "code", "literal": "pending", "chunkId": "api/write#stage" } ], "sources": [ { "chunkId": "api/write#stage", "url": "/docs/api/write#stage", "anchor": "stage" } ], "mode": "source-primary", "terms": [ "stage", "pipeline", "staging", "stores", "document", "chunks", "fast", "handoff", "marks", "pending", "embedding", "replaces", "prior", "cache", "copy", "ephemeral", "durable", "backing", "necessary", "outage", "recovery", "await", "client", "product", "images", "asin", "b08n5wrwnw", "text", "wireless", "noise", "cancelling", "headphones", "hour", "battery", "life", "metadata", "page", "putpipelinedocumentchunks", "hevlayer", "putchunksrequest" ] }, { "id": "api/write#status", "kind": "section", "title": "Write & Stage", "heading": "Status", "group": "API", "url": "/docs/api/write#status", "summary": "Layer may reject malformed, reserved, obsolete, or backend-incompatible writes before forwarding. Backing-store errors pass through unchanged, while connectivity failures indicate the write did not apply.", "facts": [ { "kind": "code", "literal": "_hevlayer_*", "chunkId": "api/write#status" }, { "kind": "code", "literal": "{ \"error\": \"validation_error\", … }", "chunkId": "api/write#status" }, { "kind": "code", "literal": "{ \"error\": \"UnsupportedByStore\", … }", "chunkId": "api/write#status" }, { "kind": "code", "literal": "{ \"error\": \"upstream_error\", … }", "chunkId": "api/write#status" }, { "kind": "code", "literal": "upsert_condition", "chunkId": "api/write#status" }, { "kind": "code", "literal": "patch_condition", "chunkId": "api/write#status" }, { "kind": "code", "literal": "delete_condition", "chunkId": "api/write#status" }, { "kind": "value", "literal": "non-2xx", "chunkId": "api/write#status" } ], "sources": [ { "chunkId": "api/write#status", "url": "/docs/api/write#status", "anchor": "status" } ], "mode": "source-primary", "terms": [ "status", "layer", "reject", "malformed", "reserved", "obsolete", "backend", "incompatible", "writes", "before", "forwarding", "backing", "store", "errors", "pass", "through", "unchanged", "while", "connectivity", "failures", "indicate", "write", "apply", "hevlayer", "error", "validation", "unsupportedbystore", "upstream", "upsert", "condition", "patch", "delete", "validates", "body", "fail", "independently", "path", "carries", "statuses", "plain" ] }, { "id": "cli", "kind": "section", "title": "Layer CLI", "heading": null, "group": "Operations", "url": "/docs/cli", "summary": "The Layer command-line client manages named environments, namespace initialization, stores, warehouses, indexes, pipelines, functions, credentials, and the operations interface. Read-only commands use the gateway, while running a Function is the main path that also requires Kubernetes access.", "facts": [ { "kind": "code", "literal": "layer", "chunkId": "cli" }, { "kind": "code", "literal": "run", "chunkId": "cli" }, { "kind": "code", "literal": "--kube-context", "chunkId": "cli" }, { "kind": "code", "literal": "--kube-namespace", "chunkId": "cli" }, { "kind": "code", "literal": "--context", "chunkId": "cli" } ], "sources": [ { "chunkId": "cli", "url": "/docs/cli", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "command", "line", "client", "manages", "named", "environments", "namespace", "initialization", "stores", "warehouses", "indexes", "pipelines", "functions", "credentials", "operations", "interface", "read", "only", "commands", "gateway", "while", "running", "function", "main", "path", "also", "requires", "kubernetes", "access", "kube", "context", "initializes", "sharding", "observes", "data", "supply", "resources", "udfs", "mints" ] }, { "id": "cli#ask-the-docs", "kind": "section", "title": "Layer CLI", "heading": "Ask The Docs", "group": "Operations", "url": "/docs/cli#ask-the-docs", "summary": "The command-line client can query the committed documentation digest locally and without credentials, discovering a nearby source checkout, installed package, or search binary. It can also target a deployed documentation endpoint.", "facts": [ { "kind": "code", "literal": "layer ask tree\nlayer ask grep \"warm cache\"\nlayer ask cat api/query\nlayer ask glossary get watermark\nlayer -o json ask tree", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "layer ask --endpoint https://hevlayer.com/api/ask tree", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "layer ask", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "ask", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "site/.hev-ask", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "../ask", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "@hevmind/ask", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "PATH", "chunkId": "cli#ask-the-docs" }, { "kind": "code", "literal": "--endpoint", "chunkId": "cli#ask-the-docs" } ], "sources": [ { "chunkId": "cli#ask-the-docs", "url": "/docs/cli#ask-the-docs", "anchor": "ask-the-docs" } ], "mode": "agent-primary", "terms": [ "docs", "command", "line", "client", "query", "committed", "documentation", "digest", "locally", "without", "credentials", "discovering", "nearby", "source", "checkout", "installed", "package", "search", "binary", "also", "target", "deployed", "endpoint", "layer", "tree", "grep", "warm", "cache", "glossary", "watermark", "json", "https", "hevlayer", "site", "hevmind", "path", "queries", "keyless", "local", "default" ] }, { "id": "cli#configuration", "kind": "section", "title": "Layer CLI", "heading": "Configuration", "group": "Operations", "url": "/docs/cli#configuration", "summary": "Named environments store gateway and optional Kubernetes settings in permission-restricted user configuration. Explicit invocation settings take precedence over environment variables, selected or active environments, and built-in defaults.", "facts": [ { "kind": "code", "literal": "active = \"partner\"\n\n[envs.partner]\nbase_url = \"https://aws-us-east-1.hevlayer.com\"\napi_key = \"...\"\nkube_context = \"partner-cluster\"\nkube_namespace = \"hevlayer\"\n\n[envs.local]\nbase_url = \"http://localhost:8080\"\napi_key = \"dev\"\nkube_context = \"kind-hevlayer\"", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "layer", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "~/.hevlayer/config.toml", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "0700", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "0600", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--base-url", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--api-key", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--context", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--kube-namespace", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "LAYER_BASE_URL", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "LAYER_API_KEY", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "HEVLAYER_", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--env", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "LAYER_ENV", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "HEVLAYER_BASE_URL", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "https://aws-us-east-1.hevlayer.com", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "HEVLAYER_API_KEY", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "-o", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "--output", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "table", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "json", "chunkId": "cli#configuration" }, { "kind": "code", "literal": "names", "chunkId": "cli#configuration" } ], "sources": [ { "chunkId": "cli#configuration", "url": "/docs/cli#configuration", "anchor": "configuration" } ], "mode": "agent-primary", "terms": [ "configuration", "named", "environments", "store", "gateway", "optional", "kubernetes", "settings", "permission", "restricted", "user", "explicit", "invocation", "take", "precedence", "environment", "variables", "selected", "active", "built", "defaults", "partner", "envs", "base", "https", "east", "hevlayer", "kube", "context", "cluster", "namespace", "local", "http", "localhost", "8080", "kind", "layer", "config", "toml", "0700" ] }, { "id": "cli#delete-an-index", "kind": "section", "title": "Layer CLI", "heading": "Delete An Index", "group": "Operations", "url": "/docs/cli#delete-an-index", "summary": "Index deletion removes the backing namespace, cache rows, durable snapshots and history, shard metadata, ephemeral jobs, and eligible discovered resources. Bulk prefix deletion requires confirmation and safely succeeds when nothing matches.", "facts": [ { "kind": "code", "literal": "layer index delete shop-products\nlayer index delete shop-products shop-products-staging\nlayer index delete --prefix shop-\nlayer index delete --prefix shop- --yes", "chunkId": "cli#delete-an-index" }, { "kind": "code", "literal": "index delete", "chunkId": "cli#delete-an-index" }, { "kind": "code", "literal": "--prefix", "chunkId": "cli#delete-an-index" }, { "kind": "code", "literal": "--yes", "chunkId": "cli#delete-an-index" } ], "sources": [ { "chunkId": "cli#delete-an-index", "url": "/docs/cli#delete-an-index", "anchor": "delete-an-index" } ], "mode": "agent-primary", "terms": [ "delete", "index", "deletion", "removes", "backing", "namespace", "cache", "rows", "durable", "snapshots", "history", "shard", "metadata", "ephemeral", "jobs", "eligible", "discovered", "resources", "bulk", "prefix", "requires", "confirmation", "safely", "succeeds", "nothing", "matches", "layer", "shop", "products", "staging", "purges", "upstream", "turbopuffer", "document", "snapshot", "mirrors", "search", "clickstream", "memory", "state" ] }, { "id": "cli#environments", "kind": "section", "title": "Layer CLI", "heading": "Environments", "group": "Operations", "url": "/docs/cli#environments", "summary": "Environment commands add, select, list, inspect, and remove named gateway and cluster targets. Interactive entry can prompt for missing values, while displayed credentials are masked.", "facts": [ { "kind": "code", "literal": "layer env add partner --base-url https://aws-us-east-1.hevlayer.com \\\n --api-key \"$LAYER_API_KEY\" --kube-context partner-cluster \\\n --kube-namespace hevlayer\nlayer env use partner\nlayer env ls\nlayer env show partner -o json\nlayer env rm partner", "chunkId": "cli#environments" }, { "kind": "code", "literal": "env add", "chunkId": "cli#environments" }, { "kind": "code", "literal": "env ls", "chunkId": "cli#environments" }, { "kind": "code", "literal": "env show", "chunkId": "cli#environments" } ], "sources": [ { "chunkId": "cli#environments", "url": "/docs/cli#environments", "anchor": "environments" } ], "mode": "agent-primary", "terms": [ "environments", "environment", "commands", "select", "list", "inspect", "remove", "named", "gateway", "cluster", "targets", "interactive", "entry", "prompt", "missing", "values", "while", "displayed", "credentials", "masked", "layer", "partner", "base", "https", "east", "hevlayer", "kube", "context", "namespace", "show", "json", "layerapikey", "prompts", "required", "must", "supplied", "flags", "keys" ] }, { "id": "cli#initialize-a-namespace", "kind": "section", "title": "Layer CLI", "heading": "Initialize a Namespace", "group": "Operations", "url": "/docs/cli#initialize-a-namespace", "summary": "Namespace initialization creates or reuses a shard marker, begins backfilling shard assignments, and normally watches until no rows lag and scatter/gather is active. Repeating the same shard count is safe; changing it conflicts.", "facts": [ { "kind": "code", "literal": "layer init products --shards 8\nlayer init products --shards 8 --watch=false\nlayer init products --shards 8 --poll-interval 5s", "chunkId": "cli#initialize-a-namespace" }, { "kind": "code", "literal": "init", "chunkId": "cli#initialize-a-namespace" }, { "kind": "code", "literal": "POST /v2/namespaces/{namespace}/init", "chunkId": "cli#initialize-a-namespace" }, { "kind": "code", "literal": "shard_lag_rows", "chunkId": "cli#initialize-a-namespace" } ], "sources": [ { "chunkId": "cli#initialize-a-namespace", "url": "/docs/cli#initialize-a-namespace", "anchor": "initialize-a-namespace" } ], "mode": "agent-primary", "terms": [ "initialize", "namespace", "initialization", "creates", "reuses", "shard", "marker", "begins", "backfilling", "assignments", "normally", "watches", "until", "rows", "scatter", "gather", "active", "repeating", "same", "count", "safe", "changing", "conflicts", "layer", "init", "products", "shards", "watch", "false", "poll", "interval", "post", "namespaces", "calls", "through", "selected", "gateway", "environment", "command", "reattaches" ] }, { "id": "cli#inspect-an-index", "kind": "section", "title": "Layer CLI", "heading": "Inspect An Index", "group": "Operations", "url": "/docs/cli#inspect-an-index", "summary": "Index inspection reports schema, size, row count, write time, stable freshness, indexing lag, cache health, and snapshot history, with structured output preserving full raw detail.", "facts": [ { "kind": "code", "literal": "layer index get shop-products\nlayer index get shop-products -o json", "chunkId": "cli#inspect-an-index" }, { "kind": "code", "literal": "index get", "chunkId": "cli#inspect-an-index" }, { "kind": "code", "literal": "-o json", "chunkId": "cli#inspect-an-index" } ], "sources": [ { "chunkId": "cli#inspect-an-index", "url": "/docs/cli#inspect-an-index", "anchor": "inspect-an-index" } ], "mode": "agent-primary", "terms": [ "inspect", "index", "inspection", "reports", "schema", "size", "count", "write", "time", "stable", "freshness", "indexing", "cache", "health", "snapshot", "history", "structured", "output", "preserving", "full", "detail", "layer", "shop", "products", "json", "summary", "last", "watermark", "status", "state", "timestamps", "sizes", "epoch", "bytes", "carries", "list" ] }, { "id": "cli#install", "kind": "section", "title": "Layer CLI", "heading": "Install", "group": "Operations", "url": "/docs/cli#install", "summary": "Build the Layer command-line client from its repository source.", "facts": [ { "kind": "code", "literal": "go build -o layer ./apps/layer-cli", "chunkId": "cli#install" } ], "sources": [ { "chunkId": "cli#install", "url": "/docs/cli#install", "anchor": "install" } ], "mode": "agent-primary", "terms": [ "install", "build", "layer", "command", "line", "client", "repository", "source", "apps", "root" ] }, { "id": "cli#keys", "kind": "section", "title": "Layer CLI", "heading": "Keys", "group": "Operations", "url": "/docs/cli#keys", "summary": "Credential commands mint, list, inspect, revoke, and permanently remove eligible keys through the gateway. Token material is shown once, while later views contain metadata only; manifests are preferable for complex entitlement sets.", "facts": [ { "kind": "code", "literal": "layer keys mint cohort-reader --owner acme \\\n --entitle vectorstore.prod-turbopuffer=read \\\n --namespaces \"cohort-*\" \\\n --claim warehouse.prod-snowflake=\"notes:cohort:*:read\"\nlayer keys ls\nlayer keys get cohort-reader\nlayer keys revoke cohort-reader\nlayer keys rm cohort-reader", "chunkId": "cli#keys" }, { "kind": "code", "literal": "keys mint", "chunkId": "cli#keys" }, { "kind": "code", "literal": "layer keys mint … | pbcopy", "chunkId": "cli#keys" }, { "kind": "code", "literal": "keys revoke", "chunkId": "cli#keys" }, { "kind": "code", "literal": "keys rm", "chunkId": "cli#keys" }, { "kind": "code", "literal": "Revoked", "chunkId": "cli#keys" }, { "kind": "code", "literal": "--entitle", "chunkId": "cli#keys" }, { "kind": "code", "literal": "TARGET[=SCOPE[+SCOPE]]", "chunkId": "cli#keys" }, { "kind": "code", "literal": "vectorstore.", "chunkId": "cli#keys" }, { "kind": "code", "literal": "warehouse.", "chunkId": "cli#keys" }, { "kind": "code", "literal": "layer", "chunkId": "cli#keys" }, { "kind": "code", "literal": "--namespaces", "chunkId": "cli#keys" }, { "kind": "code", "literal": "--claim", "chunkId": "cli#keys" }, { "kind": "code", "literal": "TARGET=STRING", "chunkId": "cli#keys" }, { "kind": "code", "literal": "--expires-after", "chunkId": "cli#keys" }, { "kind": "code", "literal": "never", "chunkId": "cli#keys" }, { "kind": "code", "literal": "365d", "chunkId": "cli#keys" }, { "kind": "code", "literal": "--entitle layer=admin", "chunkId": "cli#keys" }, { "kind": "code", "literal": "layer keys mint -f key.yaml", "chunkId": "cli#keys" }, { "kind": "code", "literal": "ApiKey", "chunkId": "cli#keys" }, { "kind": "code", "literal": "kubectl apply", "chunkId": "cli#keys" }, { "kind": "code", "literal": "keys ls", "chunkId": "cli#keys" }, { "kind": "code", "literal": "keys get", "chunkId": "cli#keys" }, { "kind": "code", "literal": "revoke", "chunkId": "cli#keys" } ], "sources": [ { "chunkId": "cli#keys", "url": "/docs/cli#keys", "anchor": "keys" } ], "mode": "agent-primary", "terms": [ "keys", "credential", "commands", "mint", "list", "inspect", "revoke", "permanently", "remove", "eligible", "through", "gateway", "token", "material", "shown", "once", "while", "later", "views", "contain", "metadata", "only", "manifests", "preferable", "complex", "entitlement", "sets", "layer", "cohort", "reader", "owner", "acme", "entitle", "vectorstore", "prod", "turbopuffer", "read", "namespaces", "claim", "warehouse" ] }, { "id": "cli#manage-snapshots", "kind": "section", "title": "Layer CLI", "heading": "Manage Snapshots", "group": "Operations", "url": "/docs/cli#manage-snapshots", "summary": "The command-line client can run an on-demand facet snapshot to completion and update the same automatic facet, interval, and retention policy used by Kubernetes-managed indexes.", "facts": [ { "kind": "code", "literal": "layer index snapshot shop-products --field category\nlayer index policy shop-products --facet-field category --facet-field brand --interval 5m --retention 30d", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "index snapshot", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "index policy", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "facetFields", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "interval", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "retention", "chunkId": "cli#manage-snapshots" }, { "kind": "code", "literal": "Index.spec.snapshot", "chunkId": "cli#manage-snapshots" } ], "sources": [ { "chunkId": "cli#manage-snapshots", "url": "/docs/cli#manage-snapshots", "anchor": "manage-snapshots" } ], "mode": "agent-primary", "terms": [ "manage", "snapshots", "command", "line", "client", "demand", "facet", "snapshot", "completion", "update", "same", "automatic", "interval", "retention", "policy", "kubernetes", "managed", "indexes", "layer", "index", "shop", "products", "field", "category", "brand", "facetfields", "spec", "creates", "waits", "complete", "writes", "shape", "shared", "gateway", "namespaces", "enable", "writer", "without", "applying", "resource" ] }, { "id": "cli#pipelines", "kind": "section", "title": "Layer CLI", "heading": "Pipelines", "group": "Operations", "url": "/docs/cli#pipelines", "summary": "Pipeline views combine registered configuration with live queue depth, processing, failure, and throughput data. They are gateway-backed and tolerate pipelines that have not yet staged work.", "facts": [ { "kind": "code", "literal": "layer pipeline list\nlayer pipeline get product-images", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "pipeline list", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "pending", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "processing", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "failed", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "rate/min", "chunkId": "cli#pipelines" }, { "kind": "code", "literal": "layer push", "chunkId": "cli#pipelines" } ], "sources": [ { "chunkId": "cli#pipelines", "url": "/docs/cli#pipelines", "anchor": "pipelines" } ], "mode": "agent-primary", "terms": [ "pipelines", "pipeline", "views", "combine", "registered", "configuration", "live", "queue", "depth", "processing", "failure", "throughput", "data", "gateway", "backed", "tolerate", "staged", "work", "layer", "list", "product", "images", "pending", "failed", "rate", "push", "reads", "fans", "status", "adds", "target", "namespace", "distance", "metric", "created", "worker", "renders", "without", "counts", "rather" ] }, { "id": "cli#run-a-function", "kind": "section", "title": "Layer CLI", "heading": "Run A Function", "group": "Operations", "url": "/docs/cli#run-a-function", "summary": "Running a Function applies or references its Kubernetes manifest, registers the versioned workload, triggers discovery, and optionally watches the queue to a clean drain. Failures keep resources for inspection, while successful temporary runs can clean up afterward.", "facts": [ { "kind": "code", "literal": "layer run -f tag-products.yaml\nlayer run -f tag-products.yaml --index amazon-products-staging\nlayer run -f tag-products.yaml --detach\nlayer run -f tag-products.yaml --rm", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "layer udf list\nlayer udf get product-tags --watch", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "Function", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--index", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "spec.targetNamespaces", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--context", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--kube-namespace", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--no-apply", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "spec.version", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--detach", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "pending_count", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "processing_count", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--rm", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "udf list", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "udf get", "chunkId": "cli#run-a-function" }, { "kind": "code", "literal": "--watch", "chunkId": "cli#run-a-function" } ], "sources": [ { "chunkId": "cli#run-a-function", "url": "/docs/cli#run-a-function", "anchor": "run-a-function" } ], "mode": "agent-primary", "terms": [ "function", "running", "applies", "references", "kubernetes", "manifest", "registers", "versioned", "workload", "triggers", "discovery", "optionally", "watches", "queue", "clean", "drain", "failures", "keep", "resources", "inspection", "while", "successful", "temporary", "runs", "afterward", "layer", "products", "yaml", "index", "amazon", "staging", "detach", "list", "product", "tags", "watch", "spec", "targetnamespaces", "context", "kube" ] }, { "id": "cli#tui", "kind": "section", "title": "Layer CLI", "heading": "TUI", "group": "Operations", "url": "/docs/cli#tui", "summary": "An interactive terminal opens a read-only operations browser for environments, indexes, functions, pipelines, and credentials. Every view has a non-interactive counterpart suitable for scripts, while mutations stay in explicit commands.", "facts": [ { "kind": "code", "literal": "layer", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer browse", "chunkId": "cli#tui" }, { "kind": "code", "literal": "enter", "chunkId": "cli#tui" }, { "kind": "code", "literal": "esc", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer env ls", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer udf list", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer udf get UDF_ID [--watch]", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer index list", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer index get NAME", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer pipeline list", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer pipeline get ID", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer keys ls", "chunkId": "cli#tui" }, { "kind": "code", "literal": "layer keys get KEY_ID", "chunkId": "cli#tui" } ], "sources": [ { "chunkId": "cli#tui", "url": "/docs/cli#tui", "anchor": "tui" } ], "mode": "agent-primary", "terms": [ "interactive", "terminal", "opens", "read", "only", "operations", "browser", "environments", "indexes", "functions", "pipelines", "credentials", "every", "view", "counterpart", "suitable", "scripts", "while", "mutations", "stay", "explicit", "commands", "layer", "browse", "enter", "list", "watch", "index", "name", "pipeline", "keys", "bare", "spelling", "prints", "usage", "exits", "press", "switch", "between", "open" ] }, { "id": "cli#vector-store-and-warehouse", "kind": "section", "title": "Layer CLI", "heading": "Vector Store And Warehouse", "group": "Operations", "url": "/docs/cli#vector-store-and-warehouse", "summary": "Read-only store and warehouse commands expose connection identity, safe secret references, health, verification, and dependency counts without reading credential contents. Store detail can infer the default resource when unambiguous.", "facts": [ { "kind": "code", "literal": "layer vectorstore list\nlayer vectorstore get\nlayer vectorstore get prod-turbopuffer -o json\nlayer warehouse list\nlayer warehouse get prod-snowflake", "chunkId": "cli#vector-store-and-warehouse" }, { "kind": "code", "literal": "vectorstore list", "chunkId": "cli#vector-store-and-warehouse" }, { "kind": "code", "literal": "vectorstore get", "chunkId": "cli#vector-store-and-warehouse" }, { "kind": "code", "literal": "spec.turbopuffer.orgId", "chunkId": "cli#vector-store-and-warehouse" }, { "kind": "code", "literal": "warehouse list", "chunkId": "cli#vector-store-and-warehouse" }, { "kind": "code", "literal": "warehouse get NAME", "chunkId": "cli#vector-store-and-warehouse" } ], "sources": [ { "chunkId": "cli#vector-store-and-warehouse", "url": "/docs/cli#vector-store-and-warehouse", "anchor": "vector-store-and-warehouse" } ], "mode": "agent-primary", "terms": [ "vector", "store", "warehouse", "read", "only", "commands", "expose", "connection", "identity", "safe", "secret", "references", "health", "verification", "dependency", "counts", "without", "reading", "credential", "contents", "detail", "infer", "default", "resource", "unambiguous", "layer", "vectorstore", "list", "prod", "turbopuffer", "json", "snowflake", "spec", "orgid", "name", "shows", "declared", "stores", "kind", "marker" ] }, { "id": "concepts", "kind": "section", "title": "Concepts", "heading": null, "group": "Overview", "url": "/docs/concepts", "summary": "Layer composes a search backend, hot document cache, indexing-state database, durable object storage, and metrics into one gateway and compute runtime.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "concepts" } ], "sources": [ { "chunkId": "concepts", "url": "/docs/concepts", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "composes", "search", "backend", "document", "cache", "indexing", "state", "database", "durable", "object", "storage", "metrics", "gateway", "compute", "runtime", "callout", "astro", "turbopuffer", "postgresql", "core", "nouns", "work" ] }, { "id": "concepts#control-loops", "kind": "section", "title": "Concepts", "heading": "Control loops", "group": "Overview", "url": "/docs/concepts#control-loops", "summary": "Control loops reconcile index state from search-system metrics, maintain stable views, and coordinate row-level transformation work.", "facts": [], "sources": [ { "chunkId": "concepts#control-loops", "url": "/docs/concepts#control-loops", "anchor": "control-loops" } ], "mode": "agent-primary", "terms": [ "control", "loops", "reconcile", "index", "state", "search", "system", "metrics", "maintain", "stable", "views", "coordinate", "level", "transformation", "work", "layer", "uses", "loop", "core", "primitive", "managing", "indexes", "reconciles", "against", "emitted", "applies", "transformations", "udfs", "keeps", "view", "current", "related", "snapshots", "watermark" ] }, { "id": "concepts#document-cache", "kind": "section", "title": "Concepts", "heading": "Document cache", "group": "Overview", "url": "/docs/concepts#document-cache", "summary": "One logical cache accelerates pull-through document reads, pipeline chunk handoff, and recent snapshot data in separate sets. Origin or durable object storage remains the recovery path, so cache failure primarily affects latency.", "facts": [], "sources": [ { "chunkId": "concepts#document-cache", "url": "/docs/concepts#document-cache", "anchor": "document-cache" } ], "mode": "agent-primary", "terms": [ "document", "cache", "logical", "accelerates", "pull", "through", "reads", "pipeline", "chunk", "handoff", "recent", "snapshot", "data", "separate", "sets", "origin", "durable", "object", "storage", "remains", "recovery", "path", "failure", "primarily", "affects", "latency", "layer", "does", "jobs", "served", "gateway", "checks", "first", "miss", "turbopuffer", "snapshots", "returns", "backfills", "best", "effort" ] }, { "id": "concepts#gateway-enhancements", "kind": "section", "title": "Concepts", "heading": "Gateway enhancements", "group": "Overview", "url": "/docs/concepts#gateway-enhancements", "summary": "The gateway adds common retrieval and filtering behavior using reserved metadata while keeping one API surface across generated clients and plain HTTP. Consistently routing traffic through it preserves the strongest guarantees.", "facts": [ { "kind": "code", "literal": "_hevlayer_*", "chunkId": "concepts#gateway-enhancements" } ], "sources": [ { "chunkId": "concepts#gateway-enhancements", "url": "/docs/concepts#gateway-enhancements", "anchor": "gateway-enhancements" } ], "mode": "agent-primary", "terms": [ "gateway", "enhancements", "adds", "common", "retrieval", "filtering", "behavior", "reserved", "metadata", "while", "keeping", "surface", "across", "generated", "clients", "plain", "http", "consistently", "routing", "traffic", "through", "preserves", "strongest", "guarantees", "hevlayer", "helpful", "extends", "search", "system", "query", "patterns", "primitives", "layer", "attributes", "changing", "schema", "those", "breaks", "should", "degrade" ] }, { "id": "concepts#glossary", "kind": "section", "title": "Concepts", "heading": "Glossary", "group": "Overview", "url": "/docs/concepts#glossary", "summary": "The glossary defines Layer's core nouns for namespaces, documents, cache, watermarks, readiness, pipelines, snapshots, facets, scans, functions, operators, shards, fusion legs, routing, deferrals, Kubernetes resources, and metrics queries.", "facts": [ { "kind": "code", "literal": "/v2/namespaces/{namespace}", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "row_count", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "indexed", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "index_lag_rows", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "fields[].values[].v", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "fields[].values[].n", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "values[].n", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "fts", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "ann", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "_hevlayer_shard", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "rerank_by: [\"RRF\", ...]", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "HybridText", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "alyze", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "word_v4", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "Auto", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "semantic", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "fused", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "routing", "chunkId": "concepts#glossary" }, { "kind": "code", "literal": "executed: false", "chunkId": "concepts#glossary" } ], "sources": [ { "chunkId": "concepts#glossary", "url": "/docs/concepts#glossary", "anchor": "glossary" } ], "mode": "agent-primary", "terms": [ "glossary", "defines", "layer", "core", "nouns", "namespaces", "documents", "cache", "watermarks", "readiness", "pipelines", "snapshots", "facets", "scans", "functions", "operators", "shards", "fusion", "legs", "routing", "deferrals", "kubernetes", "resources", "metrics", "queries", "namespace", "count", "indexed", "index", "rows", "fields", "values", "hevlayer", "shard", "rerank", "hybridtext", "alyze", "word", "auto", "hybrid" ] }, { "id": "concepts#kubernetes-autoscaling", "kind": "section", "title": "Concepts", "heading": "Kubernetes autoscaling", "group": "Overview", "url": "/docs/concepts#kubernetes-autoscaling", "summary": "Layer's stateless tiers scale independently: node capacity follows workload demand and worker replicas follow queue signals. The scaling queue contains recoverable indexing state rather than irreplaceable application data.", "facts": [], "sources": [ { "chunkId": "concepts#kubernetes-autoscaling", "url": "/docs/concepts#kubernetes-autoscaling", "anchor": "kubernetes-autoscaling" } ], "mode": "agent-primary", "terms": [ "kubernetes", "autoscaling", "layer", "stateless", "tiers", "scale", "independently", "node", "capacity", "follows", "workload", "demand", "worker", "replicas", "follow", "queue", "signals", "scaling", "contains", "recoverable", "indexing", "state", "rather", "irreplaceable", "application", "data", "because", "autoscale", "every", "tier", "karpenter", "handles", "level", "keda", "scales", "pods", "against", "embedded", "postgresql", "decisions" ] }, { "id": "concepts#scattergather", "kind": "section", "title": "Concepts", "heading": "Scatter/gather", "group": "Overview", "url": "/docs/concepts#scattergather", "summary": "A namespace can be partitioned into hash-based shards so the gateway runs filtered subqueries in parallel and merges one ranked response. Adopted namespaces activate this path only after a backfill stamps every row, preventing missed unstamped data.", "facts": [ { "kind": "code", "literal": "_hevlayer_shard", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "top_k", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "POST /v2/namespaces/{namespace}/init", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "shard_count", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "layer.shard_lag_rows: 0", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "layer init --shards N", "chunkId": "concepts#scattergather" }, { "kind": "code", "literal": "shard_lag_rows", "chunkId": "concepts#scattergather" }, { "kind": "flag", "literal": "-filtered", "chunkId": "concepts#scattergather" } ], "sources": [ { "chunkId": "concepts#scattergather", "url": "/docs/concepts#scattergather", "anchor": "scattergather" } ], "mode": "agent-primary", "terms": [ "scatter", "gather", "namespace", "partitioned", "hash", "based", "shards", "gateway", "runs", "filtered", "subqueries", "parallel", "merges", "ranked", "response", "adopted", "namespaces", "activate", "path", "only", "after", "backfill", "stamps", "every", "preventing", "missed", "unstamped", "data", "hevlayer", "shard", "post", "init", "count", "layer", "rows", "partition", "single", "buckets", "called", "assigning" ] }, { "id": "dashboard", "kind": "section", "title": "Dashboard", "heading": null, "group": "Operations", "url": "/docs/dashboard", "summary": "The in-cluster dashboard is the operator interface for observing and managing Layer, with separate concerns for data access, cluster permissions, networking, authentication, and optional deployment.", "facts": [ { "kind": "code", "literal": "layer-dashboard", "chunkId": "dashboard" }, { "kind": "value", "literal": "Callout.astro", "chunkId": "dashboard" } ], "sources": [ { "chunkId": "dashboard", "url": "/docs/dashboard", "anchor": null } ], "mode": "agent-primary", "terms": [ "cluster", "dashboard", "operator", "interface", "observing", "managing", "layer", "separate", "concerns", "data", "access", "permissions", "networking", "authentication", "optional", "deployment", "callout", "astro", "running", "operations", "needs", "auth", "turning", "ships", "alongside", "gateway", "service", "page", "covers", "reach", "gate", "turn" ] }, { "id": "dashboard#access-it-needs", "kind": "section", "title": "Dashboard", "heading": "Access it needs", "group": "Operations", "url": "/docs/dashboard#access-it-needs", "summary": "The dashboard reads product and metrics data through the gateway, cluster state through Kubernetes permissions, and cost data through gateway services. Optional write access adds controlled resource and credential changes, while standard views never read backing databases or raw secrets directly.", "facts": [ { "kind": "code", "literal": "/v2/metrics", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "VectorStore", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "keys", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "/v2/cost", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "hevlayer.com", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "dashboard.kubeAccess.enabled", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "dashboard.writeAccess.enabled", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "false", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "dashboard.serviceAccount.roleArn", "chunkId": "dashboard#access-it-needs" }, { "kind": "code", "literal": "layer_dashboard_role_arn", "chunkId": "dashboard#access-it-needs" } ], "sources": [ { "chunkId": "dashboard#access-it-needs", "url": "/docs/dashboard#access-it-needs", "anchor": "access-it-needs" } ], "mode": "agent-primary", "terms": [ "access", "needs", "dashboard", "reads", "product", "metrics", "data", "through", "gateway", "cluster", "state", "kubernetes", "permissions", "cost", "services", "optional", "write", "adds", "controlled", "resource", "credential", "changes", "while", "standard", "views", "never", "read", "backing", "databases", "secrets", "directly", "layer", "derivefromstore", "vectorstore", "keys", "hevlayer", "kubeaccess", "enabled", "writeaccess", "false" ] }, { "id": "dashboard#basic-auth", "kind": "section", "title": "Dashboard", "heading": "Basic auth", "group": "Operations", "url": "/docs/dashboard#basic-auth", "summary": "Dashboard access always requires HTTP basic authentication, and installation is rejected when enabled without both credentials.", "facts": [ { "kind": "code", "literal": "dashboard:\n basicAuth:\n user: ops\n password: ", "chunkId": "dashboard#basic-auth" } ], "sources": [ { "chunkId": "dashboard#basic-auth", "url": "/docs/dashboard#basic-auth", "anchor": "basic-auth" } ], "mode": "agent-primary", "terms": [ "basic", "auth", "dashboard", "access", "always", "requires", "http", "authentication", "installation", "rejected", "enabled", "without", "both", "credentials", "basicauth", "user", "password", "strong", "sits", "front", "every", "route", "required", "refuses", "start", "through", "chart", "render", "fails", "either", "field", "blank", "while" ] }, { "id": "dashboard#disabling-the-dashboard", "kind": "section", "title": "Dashboard", "heading": "Disabling the dashboard", "group": "Operations", "url": "/docs/dashboard#disabling-the-dashboard", "summary": "The dashboard can be disabled entirely without changing gateway or compute-runtime behavior; only the operator user interface and its supporting resources are omitted.", "facts": [ { "kind": "code", "literal": "dashboard:\n enabled: false", "chunkId": "dashboard#disabling-the-dashboard" } ], "sources": [ { "chunkId": "dashboard#disabling-the-dashboard", "url": "/docs/dashboard#disabling-the-dashboard", "anchor": "disabling-the-dashboard" } ], "mode": "agent-primary", "terms": [ "disabling", "dashboard", "disabled", "entirely", "without", "changing", "gateway", "compute", "runtime", "behavior", "only", "operator", "user", "interface", "supporting", "resources", "omitted", "enabled", "false", "optional", "disable", "deployment", "service", "rbac", "ingress", "skip", "rendering", "transform", "unchanged", "lose" ] }, { "id": "dashboard#networking", "kind": "section", "title": "Dashboard", "heading": "Networking", "group": "Operations", "url": "/docs/dashboard#networking", "summary": "The dashboard is intended for operators over a private forwarding path, while customer workloads receive only gateway access and credentials.", "facts": [ { "kind": "code", "literal": "kubectl port-forward -n svc/layer-dashboard 8081:8081", "chunkId": "dashboard#networking" }, { "kind": "code", "literal": "http://localhost:8081", "chunkId": "dashboard#networking" } ], "sources": [ { "chunkId": "dashboard#networking", "url": "/docs/dashboard#networking", "anchor": "networking" } ], "mode": "agent-primary", "terms": [ "networking", "dashboard", "intended", "operators", "private", "forwarding", "path", "while", "customer", "workloads", "receive", "only", "gateway", "access", "credentials", "kubectl", "port", "forward", "release", "namespace", "layer", "8081", "http", "localhost", "operator", "tool", "reach", "rather", "exposing", "publicly", "open", "ever", "base", "never" ] }, { "id": "dashboard#operational-notes", "kind": "section", "title": "Dashboard", "heading": "Operational notes", "group": "Operations", "url": "/docs/dashboard#operational-notes", "summary": "This section reserves space for dashboard-specific operational guidance.", "facts": [], "sources": [ { "chunkId": "dashboard#operational-notes", "url": "/docs/dashboard#operational-notes", "anchor": "operational-notes" } ], "mode": "agent-primary", "terms": [ "operational", "notes", "section", "reserves", "space", "dashboard", "specific", "guidance" ] }, { "id": "dashboard#pipeline-queue-states", "kind": "section", "title": "Dashboard", "heading": "Pipeline queue states", "group": "Operations", "url": "/docs/dashboard#pipeline-queue-states", "summary": "Pipeline cards distinguish intentional pauses and schedule gates from genuine stalls or active backlog using queue, worker, and scaling signals. Data-supply panes show credential-safe gateway projections, and mutations require separate write access and explicit controls.", "facts": [ { "kind": "code", "literal": "Pipeline", "chunkId": "dashboard#pipeline-queue-states" }, { "kind": "code", "literal": "spec.paused: true", "chunkId": "dashboard#pipeline-queue-states" }, { "kind": "code", "literal": "/v2/namespaces", "chunkId": "dashboard#pipeline-queue-states" }, { "kind": "code", "literal": "/v2/vectorstores", "chunkId": "dashboard#pipeline-queue-states" }, { "kind": "code", "literal": "/v2/warehouses", "chunkId": "dashboard#pipeline-queue-states" }, { "kind": "code", "literal": "dashboard.writeAccess.enabled", "chunkId": "dashboard#pipeline-queue-states" } ], "sources": [ { "chunkId": "dashboard#pipeline-queue-states", "url": "/docs/dashboard#pipeline-queue-states", "anchor": "pipeline-queue-states" } ], "mode": "agent-primary", "terms": [ "pipeline", "queue", "states", "cards", "distinguish", "intentional", "pauses", "schedule", "gates", "genuine", "stalls", "active", "backlog", "worker", "scaling", "signals", "data", "supply", "panes", "show", "credential", "safe", "gateway", "projections", "mutations", "require", "separate", "write", "access", "explicit", "controls", "spec", "paused", "true", "namespaces", "vectorstores", "warehouses", "dashboard", "writeaccess", "enabled" ] }, { "id": "demos", "kind": "section", "title": "Demos", "heading": null, "group": "Overview", "url": "/docs/demos", "summary": "Live demos combine shipped Layer features over books, clinical case reports, scientific abstracts, and product data to make routing, fuzzy fusion, semantic retrieval, pipelines, snapshots, and functions visible.", "facts": [ { "kind": "value", "literal": "shelf.hevlayer.com", "chunkId": "demos" }, { "kind": "value", "literal": "chart.hevlayer.com", "chunkId": "demos" }, { "kind": "value", "literal": "hybrid-text.hevlayer.com", "chunkId": "demos" }, { "kind": "value", "literal": "shop.hevlayer.com", "chunkId": "demos" } ], "sources": [ { "chunkId": "demos", "url": "/docs/demos", "anchor": null } ], "mode": "agent-primary", "terms": [ "live", "demos", "combine", "shipped", "layer", "features", "books", "clinical", "case", "reports", "scientific", "abstracts", "product", "data", "make", "routing", "fuzzy", "fusion", "semantic", "retrieval", "pipelines", "snapshots", "functions", "visible", "shelf", "hevlayer", "chart", "hybrid", "text", "shop", "applications", "built", "query", "image", "search", "full", "storefront", "workload", "composing", "gateway" ] }, { "id": "demos#chart--clinical-patient-notes-search-that-shows-its-routing", "kind": "section", "title": "Demos", "heading": "chart — clinical patient-notes search that shows its routing", "group": "Overview", "url": "/docs/demos#chart--clinical-patient-notes-search-that-shows-its-routing", "summary": "The clinical search demo makes routing measurable across exact medical tokens and longer symptom descriptions using published relevance judgments. It also showcases an open-model function pipeline over de-identified case reports and is explicitly not clinical advice.", "facts": [ { "kind": "code", "literal": "metformin 500mg", "chunkId": "demos#chart--clinical-patient-notes-search-that-shows-its-routing" }, { "kind": "code", "literal": "CABG", "chunkId": "demos#chart--clinical-patient-notes-search-that-shows-its-routing" }, { "kind": "code", "literal": "aspirn", "chunkId": "demos#chart--clinical-patient-notes-search-that-shows-its-routing" }, { "kind": "value", "literal": "chart.hevlayer.com", "chunkId": "demos#chart--clinical-patient-notes-search-that-shows-its-routing" } ], "sources": [ { "chunkId": "demos#chart--clinical-patient-notes-search-that-shows-its-routing", "url": "/docs/demos#chart--clinical-patient-notes-search-that-shows-its-routing", "anchor": "chart--clinical-patient-notes-search-that-shows-its-routing" } ], "mode": "agent-primary", "terms": [ "chart", "clinical", "patient", "notes", "search", "shows", "routing", "demo", "makes", "measurable", "across", "exact", "medical", "tokens", "longer", "symptom", "descriptions", "published", "relevance", "judgments", "also", "showcases", "open", "model", "function", "pipeline", "identified", "case", "reports", "explicitly", "advice", "metformin", "500mg", "cabg", "aspirn", "hevlayer", "live", "same", "hero", "corpus" ] }, { "id": "demos#hybrid-text--hybrid-text-fusion-over-scifact", "kind": "section", "title": "Demos", "heading": "hybrid-text — hybrid text fusion over SciFact", "group": "Overview", "url": "/docs/demos#hybrid-text--hybrid-text-fusion-over-scifact", "summary": "The scientific-abstract demo evaluates purely lexical full-text and fuzzy fusion with published judgments, showing typo resilience, retrieval metrics, latency, and fusion details without embeddings or GPUs.", "facts": [ { "kind": "value", "literal": "hybrid-text.hevlayer.com", "chunkId": "demos#hybrid-text--hybrid-text-fusion-over-scifact" }, { "kind": "value", "literal": "github.com", "chunkId": "demos#hybrid-text--hybrid-text-fusion-over-scifact" } ], "sources": [ { "chunkId": "demos#hybrid-text--hybrid-text-fusion-over-scifact", "url": "/docs/demos#hybrid-text--hybrid-text-fusion-over-scifact", "anchor": "hybrid-text--hybrid-text-fusion-over-scifact" } ], "mode": "agent-primary", "terms": [ "hybrid", "text", "fusion", "scifact", "scientific", "abstract", "demo", "evaluates", "purely", "lexical", "full", "fuzzy", "published", "judgments", "showing", "typo", "resilience", "retrieval", "metrics", "latency", "details", "without", "embeddings", "gpus", "hevlayer", "github", "live", "source", "eval", "shaped", "sibling", "routing", "demos", "abstracts", "beir", "query", "string", "fans", "input", "bm25" ] }, { "id": "demos#shelf--book-search-that-shows-its-routing", "kind": "section", "title": "Demos", "heading": "shelf — book search that shows its routing", "group": "Overview", "url": "/docs/demos#shelf--book-search-that-shows-its-routing", "summary": "The book demo visibly routes short identifiers, titles, and longer descriptive queries among lexical, semantic, and fused retrieval, making the deterministic routing policy the main user experience.", "facts": [ { "kind": "code", "literal": "Auto", "chunkId": "demos#shelf--book-search-that-shows-its-routing" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "demos#shelf--book-search-that-shows-its-routing" }, { "kind": "code", "literal": "semantic", "chunkId": "demos#shelf--book-search-that-shows-its-routing" }, { "kind": "code", "literal": "fused", "chunkId": "demos#shelf--book-search-that-shows-its-routing" }, { "kind": "value", "literal": "shelf.hevlayer.com", "chunkId": "demos#shelf--book-search-that-shows-its-routing" }, { "kind": "value", "literal": "github.com", "chunkId": "demos#shelf--book-search-that-shows-its-routing" } ], "sources": [ { "chunkId": "demos#shelf--book-search-that-shows-its-routing", "url": "/docs/demos#shelf--book-search-that-shows-its-routing", "anchor": "shelf--book-search-that-shows-its-routing" } ], "mode": "agent-primary", "terms": [ "shelf", "book", "search", "shows", "routing", "demo", "visibly", "routes", "short", "identifiers", "titles", "longer", "descriptive", "queries", "among", "lexical", "semantic", "fused", "retrieval", "making", "deterministic", "policy", "main", "user", "experience", "auto", "hybrid", "text", "hevlayer", "github", "live", "source", "three", "type", "author", "title", "vibe", "gateway", "rank", "expression" ] }, { "id": "demos#shop--semantic-shopping-everything-together", "kind": "section", "title": "Demos", "heading": "shop — semantic shopping, everything together", "group": "Overview", "url": "/docs/demos#shop--semantic-shopping-everything-together", "summary": "The storefront demo combines image embeddings, indexing pipelines, semantic search, seed-based recommendations, snapshot facets, freshness, history, and autoscaling across a product catalog.", "facts": [ { "kind": "code", "literal": "hev-shop.com", "chunkId": "demos#shop--semantic-shopping-everything-together" }, { "kind": "code", "literal": "nearest_to_id", "chunkId": "demos#shop--semantic-shopping-everything-together" }, { "kind": "value", "literal": "shop.hevlayer.com", "chunkId": "demos#shop--semantic-shopping-everything-together" }, { "kind": "value", "literal": "github.com", "chunkId": "demos#shop--semantic-shopping-everything-together" } ], "sources": [ { "chunkId": "demos#shop--semantic-shopping-everything-together", "url": "/docs/demos#shop--semantic-shopping-everything-together", "anchor": "shop--semantic-shopping-everything-together" } ], "mode": "agent-primary", "terms": [ "shop", "semantic", "shopping", "everything", "together", "storefront", "demo", "combines", "image", "embeddings", "indexing", "pipelines", "search", "seed", "based", "recommendations", "snapshot", "facets", "freshness", "history", "autoscaling", "across", "product", "catalog", "nearest", "hevlayer", "github", "live", "formerly", "redirects", "source", "application", "workload", "pipeline", "observability", "embeds", "images", "clip", "writes", "vector" ] }, { "id": "document-model", "kind": "section", "title": "Document model", "heading": null, "group": "Overview", "url": "/docs/document-model", "summary": "Layer owns a reserved document-attribute family for server write time, shard assignment, function completion versions, and function invalidation. Callers and workers must not set these values because they underpin consistency, scatter/gather, and discovery guarantees.", "facts": [ { "kind": "code", "literal": "_hevlayer_*", "chunkId": "document-model" }, { "kind": "code", "literal": "_hevlayer_upserted_at", "chunkId": "document-model" }, { "kind": "code", "literal": "_hevlayer_shard", "chunkId": "document-model" }, { "kind": "code", "literal": "xxh64(id) % shard_count", "chunkId": "document-model" }, { "kind": "code", "literal": "_hevlayer_udf__v", "chunkId": "document-model" }, { "kind": "code", "literal": "spec.version", "chunkId": "document-model" }, { "kind": "code", "literal": "_hevlayer_udf__stale_after", "chunkId": "document-model" }, { "kind": "code", "literal": "_hevlayer_", "chunkId": "document-model" }, { "kind": "value", "literal": "StoreSwitch.astro", "chunkId": "document-model" }, { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "document-model" } ], "sources": [ { "chunkId": "document-model", "url": "/docs/document-model", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "owns", "reserved", "document", "attribute", "family", "server", "write", "time", "shard", "assignment", "function", "completion", "versions", "invalidation", "callers", "workers", "must", "these", "values", "because", "underpin", "consistency", "scatter", "gather", "discovery", "guarantees", "hevlayer", "upserted", "xxh64", "count", "spec", "version", "stale", "after", "storeswitch", "astro", "featuregate", "attributes", "gateway" ] }, { "id": "failure-modes", "kind": "section", "title": "Failure Modes", "heading": null, "group": "Operations", "url": "/docs/failure-modes", "summary": "Layer aims to keep backing-store queries and document reads available when surrounding components fail, while documenting paths that depend on gateway-owned state and therefore cannot degrade the same way.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "failure-modes" } ], "sources": [ { "chunkId": "failure-modes", "url": "/docs/failure-modes", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "aims", "keep", "backing", "store", "queries", "document", "reads", "available", "surrounding", "components", "fail", "while", "documenting", "paths", "depend", "gateway", "owned", "state", "therefore", "cannot", "degrade", "same", "callout", "astro", "writes", "cache", "pipeline", "runs", "trouble", "strives", "gracefully", "fetch", "served", "turbopuffer", "functioning", "around", "page", "details", "scenarios" ] }, { "id": "failure-modes#client-failures", "kind": "section", "title": "Failure Modes", "heading": "Client failures", "group": "Operations", "url": "/docs/failure-modes#client-failures", "summary": "When the gateway is unreachable, clients return that connection error rather than selecting a store-specific fallback, preserving the abstraction that namespace routing belongs to the gateway.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "failure-modes#client-failures" } ], "sources": [ { "chunkId": "failure-modes#client-failures", "url": "/docs/failure-modes#client-failures", "anchor": "client-failures" } ], "mode": "agent-primary", "terms": [ "client", "failures", "gateway", "unreachable", "clients", "return", "connection", "error", "rather", "selecting", "store", "specific", "fallback", "preserving", "abstraction", "namespace", "routing", "belongs", "vectorstore", "sdks", "retry", "directly", "against", "backing", "keeps", "surface", "backend", "neutral", "backed", "turbopuffer", "another", "selected", "callers", "should", "need", "credential", "path" ] }, { "id": "failure-modes#pipeline-stop-writes", "kind": "section", "title": "Failure Modes", "heading": "Pipeline stop-writes", "group": "Operations", "url": "/docs/failure-modes#pipeline-stop-writes", "summary": "Pipeline chunks are persisted to object storage and state to the indexing database before cache writes, so cache stop-writes do not lose work. The cache can restart and refill on demand while operators monitor explicit stop-write, cold-read, and recovery signals.", "facts": [ { "kind": "code", "literal": "documentCache.autoRestartOnStopWrites: true", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "layer_aerospike_op_duration_seconds{status=\"aerospike_stop_writes\"}", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "hevlayer_cache_cold_responses_total", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "hevlayer_document_cache_cold_starts_total", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "hevlayer_document_cache_cold_start_seconds", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "Aerospike chunk write failed (best-effort)", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "code", "literal": "Aerospike chunk read failed; falling back to S3 backing", "chunkId": "failure-modes#pipeline-stop-writes" }, { "kind": "value", "literal": "documentCache.storage.resetOnStart", "chunkId": "failure-modes#pipeline-stop-writes" } ], "sources": [ { "chunkId": "failure-modes#pipeline-stop-writes", "url": "/docs/failure-modes#pipeline-stop-writes", "anchor": "pipeline-stop-writes" } ], "mode": "agent-primary", "terms": [ "pipeline", "stop", "writes", "chunks", "persisted", "object", "storage", "state", "indexing", "database", "before", "cache", "lose", "work", "restart", "refill", "demand", "while", "operators", "monitor", "explicit", "write", "cold", "read", "recovery", "signals", "documentcache", "autorestartonstopwrites", "true", "layer", "aerospike", "duration", "seconds", "status", "hevlayer", "responses", "total", "document", "starts", "start" ] }, { "id": "failure-modes#read", "kind": "section", "title": "Failure Modes", "heading": "Read", "group": "Operations", "url": "/docs/failure-modes#read", "summary": "Compatible queries may continue directly against the backing store during a gateway outage, losing Layer-specific enhancements, while gateway-owned reads fail fast. Cache outages degrade document-fetch latency because origin remains available.", "facts": [], "sources": [ { "chunkId": "failure-modes#read", "url": "/docs/failure-modes#read", "anchor": "read" } ], "mode": "agent-primary", "terms": [ "read", "compatible", "queries", "continue", "directly", "against", "backing", "store", "during", "gateway", "outage", "losing", "layer", "specific", "enhancements", "while", "owned", "reads", "fail", "fast", "cache", "outages", "degrade", "document", "fetch", "latency", "because", "origin", "remains", "available", "route", "through", "does", "take", "dark", "python", "sdks", "fall", "turbopuffer", "direct" ] }, { "id": "failure-modes#write", "kind": "section", "title": "Failure Modes", "heading": "Write", "group": "Operations", "url": "/docs/failure-modes#write", "summary": "Compatible writes may continue directly to the durable backing store when the gateway is unreachable, but they skip cache warming and pipeline staging until gateway service returns.", "facts": [], "sources": [ { "chunkId": "failure-modes#write", "url": "/docs/failure-modes#write", "anchor": "write" } ], "mode": "agent-primary", "terms": [ "write", "compatible", "writes", "continue", "directly", "durable", "backing", "store", "gateway", "unreachable", "skip", "cache", "warming", "pipeline", "staging", "until", "service", "returns", "also", "fall", "through", "turbopuffer", "direct", "again", "client", "upstream", "still", "accepts", "skips", "document" ] }, { "id": "faq", "kind": "section", "title": "FAQ", "heading": null, "group": "Overview", "url": "/docs/faq", "summary": "The frequently asked questions cover licensing, deployment pricing, trials, project ownership, and initial adoption.", "facts": [], "sources": [ { "chunkId": "faq", "url": "/docs/faq", "anchor": null } ], "mode": "agent-primary", "terms": [ "frequently", "asked", "questions", "cover", "licensing", "deployment", "pricing", "trials", "project", "ownership", "initial", "adoption", "started", "page", "answers", "rest", "docs", "headed" ] }, { "id": "faq#how-do-i-know-whether-my-license-is-healthy", "kind": "section", "title": "FAQ", "heading": "How do I know whether my license is healthy?", "group": "Overview", "url": "/docs/faq#how-do-i-know-whether-my-license-is-healthy", "summary": "Read the gateway's local license projection to distinguish fully licensed, grace-period, and community-floor operation.", "facts": [ { "kind": "code", "literal": "GET /v2/license", "chunkId": "faq#how-do-i-know-whether-my-license-is-healthy" }, { "kind": "code", "literal": "licensed", "chunkId": "faq#how-do-i-know-whether-my-license-is-healthy" }, { "kind": "code", "literal": "grace", "chunkId": "faq#how-do-i-know-whether-my-license-is-healthy" }, { "kind": "code", "literal": "floor", "chunkId": "faq#how-do-i-know-whether-my-license-is-healthy" } ], "sources": [ { "chunkId": "faq#how-do-i-know-whether-my-license-is-healthy", "url": "/docs/faq#how-do-i-know-whether-my-license-is-healthy", "anchor": "how-do-i-know-whether-my-license-is-healthy" } ], "mode": "agent-primary", "terms": [ "know", "whether", "license", "healthy", "read", "gateway", "local", "projection", "distinguish", "fully", "licensed", "grace", "period", "community", "floor", "operation", "call", "reports", "configured", "install", "operator", "dashboard", "surfaces", "same", "state", "model", "their", "enforcement", "ship" ] }, { "id": "faq#how-do-i-start-a-trial", "kind": "section", "title": "FAQ", "heading": "How do I start a trial?", "group": "Overview", "url": "/docs/faq#how-do-i-start-a-trial", "summary": "Trial signup uses a work email and returns a signed trial credential together with current installation guidance.", "facts": [], "sources": [ { "chunkId": "faq#how-do-i-start-a-trial", "url": "/docs/faq#how-do-i-start-a-trial", "anchor": "how-do-i-start-a-trial" } ], "mode": "agent-primary", "terms": [ "start", "trial", "signup", "uses", "work", "email", "returns", "signed", "credential", "together", "current", "installation", "guidance", "submit", "layer", "emails", "plus", "install", "instructions" ] }, { "id": "faq#how-much-will-it-cost", "kind": "section", "title": "FAQ", "heading": "How much will it cost?", "group": "Overview", "url": "/docs/faq#how-much-will-it-cost", "summary": "Commercial licensing is per operator installation rather than replica, so production, staging, and recovery clusters are separate deployments. Design-partner pricing is handled directly after a trial.", "facts": [], "sources": [ { "chunkId": "faq#how-much-will-it-cost", "url": "/docs/faq#how-much-will-it-cost", "anchor": "how-much-will-it-cost" } ], "mode": "agent-primary", "terms": [ "much", "cost", "commercial", "licensing", "operator", "installation", "rather", "replica", "production", "staging", "recovery", "clusters", "separate", "deployments", "design", "partner", "pricing", "handled", "directly", "after", "trial", "layer", "licensed", "deployment", "license", "install", "cluster", "carry", "their", "replicas", "within", "count", "final", "start", "terms" ] }, { "id": "faq#what-is-the-licensing-for-hev-layer", "kind": "section", "title": "FAQ", "heading": "What is the licensing for hev layer?", "group": "Overview", "url": "/docs/faq#what-is-the-licensing-for-hev-layer", "summary": "The standalone gateway is source-available and later converts to a permissive license, while the operator, function runtime, and dashboard require a signed commercial or trial license.", "facts": [ { "kind": "code", "literal": "LICENSE", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "code", "literal": "license.token", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "value", "literal": "Apache-2", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "value", "literal": "1.1", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "value", "literal": "github.com", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "value", "literal": "Apache-2.0", "chunkId": "faq#what-is-the-licensing-for-hev-layer" }, { "kind": "value", "literal": "2.0", "chunkId": "faq#what-is-the-licensing-for-hev-layer" } ], "sources": [ { "chunkId": "faq#what-is-the-licensing-for-hev-layer", "url": "/docs/faq#what-is-the-licensing-for-hev-layer", "anchor": "what-is-the-licensing-for-hev-layer" } ], "mode": "agent-primary", "terms": [ "licensing", "layer", "standalone", "gateway", "source", "available", "later", "converts", "permissive", "license", "while", "operator", "function", "runtime", "dashboard", "require", "signed", "commercial", "trial", "token", "apache", "github", "under", "business", "free", "self", "host", "scale", "change", "date", "licensed", "installs", "keys", "access", "supplied", "helm", "through", "referenced", "kubernetes", "secret" ] }, { "id": "faq#who-built-hev-layer", "kind": "section", "title": "FAQ", "heading": "Who built hev layer?", "group": "Overview", "url": "/docs/faq#who-built-hev-layer", "summary": "Hev Layer was built by Adam Hevenor as a hev mind product.", "facts": [ { "kind": "value", "literal": "hevmind.com", "chunkId": "faq#who-built-hev-layer" } ], "sources": [ { "chunkId": "faq#who-built-hev-layer", "url": "/docs/faq#who-built-hev-layer", "anchor": "who-built-hev-layer" } ], "mode": "agent-primary", "terms": [ "built", "layer", "adam", "hevenor", "mind", "product", "hevmind" ] }, { "id": "guarantees", "kind": "section", "title": "No Guarantees", "heading": null, "group": "Overview", "url": "/docs/guarantees", "summary": "Layer does not promise absolute guarantees; it documents concrete commitments around security, operations, compatibility, and user responsibility instead.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "guarantees" } ], "sources": [ { "chunkId": "guarantees", "url": "/docs/guarantees", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "does", "promise", "absolute", "guarantees", "documents", "concrete", "commitments", "around", "security", "operations", "compatibility", "user", "responsibility", "instead", "callout", "astro", "offer", "here", "commit", "best", "provide", "secure", "hands", "infrastructure", "ultimately", "responsible", "while", "make", "promises", "design", "distribute", "software", "believe", "easy", "stand", "test", "time", "page", "covers" ] }, { "id": "guarantees#commitments", "kind": "section", "title": "No Guarantees", "heading": "Commitments", "group": "Overview", "url": "/docs/guarantees#commitments", "summary": "Layer commits to durable object-storage history, cache-accelerated hot data, accurate documentation, graceful degradation, broad client compatibility, and one stable cut across every expanded query leg. The project is human-directed and produced through agentic coding workflows.", "facts": [ { "kind": "value", "literal": "hevmind.com", "chunkId": "guarantees#commitments" } ], "sources": [ { "chunkId": "guarantees#commitments", "url": "/docs/guarantees#commitments", "anchor": "commitments" } ], "mode": "agent-primary", "terms": [ "commitments", "layer", "commits", "durable", "object", "storage", "history", "cache", "accelerated", "data", "accurate", "documentation", "graceful", "degradation", "broad", "client", "compatibility", "stable", "across", "every", "expanded", "query", "project", "human", "directed", "produced", "through", "agentic", "coding", "workflows", "hevmind", "backed", "search", "namespace", "snapshots", "written", "bucket", "specify", "format", "change" ] }, { "id": "index", "kind": "section", "title": "Introduction", "heading": null, "group": "Overview", "url": "/docs", "summary": "Layer combines a transparent retrieval gateway with a Kubernetes function runtime for elastic indexing and row-level compute. Durable history lives in object storage, workers scale from queue demand, and generated clients share one specification across languages.", "facts": [ { "kind": "code", "literal": "Function", "chunkId": "index" }, { "kind": "value", "literal": "Apache-2", "chunkId": "index" }, { "kind": "value", "literal": "AGPL-3", "chunkId": "index" }, { "kind": "value", "literal": "Diagram.astro", "chunkId": "index" }, { "kind": "value", "literal": "karpenter.sh", "chunkId": "index" }, { "kind": "value", "literal": "Apache-2.0", "chunkId": "index" }, { "kind": "value", "literal": "aerospike.com", "chunkId": "index" }, { "kind": "value", "literal": "AGPL-3.0", "chunkId": "index" }, { "kind": "value", "literal": "www.postgresql.org", "chunkId": "index" }, { "kind": "value", "literal": "victoriametrics.com", "chunkId": "index" }, { "kind": "value", "literal": "2.0", "chunkId": "index" }, { "kind": "value", "literal": "3.0", "chunkId": "index" } ], "sources": [ { "chunkId": "index", "url": "/docs", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "combines", "transparent", "retrieval", "gateway", "kubernetes", "function", "runtime", "elastic", "indexing", "level", "compute", "durable", "history", "lives", "object", "storage", "workers", "scale", "queue", "demand", "generated", "clients", "share", "specification", "across", "languages", "apache", "agpl", "diagram", "astro", "karpenter", "aerospike", "postgresql", "victoriametrics", "modern", "systems", "scales", "multi", "stage" ] }, { "id": "install", "kind": "section", "title": "Install", "heading": null, "group": "Operations", "url": "/docs/install", "summary": "A normal installation first provisions AWS networking, identity, storage, registry, and optionally a fresh cluster, then installs the runtime into that cluster with Helm. Existing clusters may supply equivalent resources directly.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "install" } ], "sources": [ { "chunkId": "install", "url": "/docs/install", "anchor": null } ], "mode": "agent-primary", "terms": [ "normal", "installation", "first", "provisions", "networking", "identity", "storage", "registry", "optionally", "fresh", "cluster", "installs", "runtime", "helm", "existing", "clusters", "supply", "equivalent", "resources", "directly", "callout", "astro", "bring", "layer", "environment", "terraform", "install", "stages", "required", "cost", "read", "roles", "recommended", "path", "gateway", "operator", "document", "cache", "wires", "produced" ] }, { "id": "install#cluster-recommended", "kind": "section", "title": "Install", "heading": "Cluster: recommended", "group": "Operations", "url": "/docs/install#cluster-recommended", "summary": "Design-partner deployments should generally use a fresh managed Kubernetes cluster with one always-on system node, local cache storage, autoscaled CPU and GPU workers, ingress support, and durable object storage. Existing clusters must provide equivalent identity, networking, autoscaling, registry, and ingress prerequisites.", "facts": [ { "kind": "code", "literal": "system", "chunkId": "install#cluster-recommended" }, { "kind": "code", "literal": "i4i.large", "chunkId": "install#cluster-recommended" }, { "kind": "code", "literal": "worker-cpu", "chunkId": "install#cluster-recommended" }, { "kind": "code", "literal": "worker-gpu", "chunkId": "install#cluster-recommended" } ], "sources": [ { "chunkId": "install#cluster-recommended", "url": "/docs/install#cluster-recommended", "anchor": "cluster-recommended" } ], "mode": "agent-primary", "terms": [ "cluster", "recommended", "design", "partner", "deployments", "should", "generally", "fresh", "managed", "kubernetes", "always", "system", "node", "local", "cache", "storage", "autoscaled", "workers", "ingress", "support", "durable", "object", "existing", "clusters", "must", "provide", "equivalent", "identity", "networking", "autoscaling", "registry", "prerequisites", "large", "worker", "installs", "unless", "there", "specific", "reason", "bind" ] }, { "id": "install#cost-notes", "kind": "section", "title": "Install", "heading": "Cost notes", "group": "Operations", "url": "/docs/install#cost-notes", "summary": "The baseline AWS footprint is driven by the managed control plane, one system node, ingress, and small storage, while indexing workers scale with burst demand. Private egress, heavier gateway traffic, or sustained cache pressure can materially raise cost.", "facts": [ { "kind": "code", "literal": "system", "chunkId": "install#cost-notes" }, { "kind": "value", "literal": "us-east-1", "chunkId": "install#cost-notes" } ], "sources": [ { "chunkId": "install#cost-notes", "url": "/docs/install#cost-notes", "anchor": "cost-notes" } ], "mode": "agent-primary", "terms": [ "cost", "notes", "baseline", "footprint", "driven", "managed", "control", "plane", "system", "node", "ingress", "small", "storage", "while", "indexing", "workers", "scale", "burst", "demand", "private", "egress", "heavier", "gateway", "traffic", "sustained", "cache", "pressure", "materially", "raise", "east", "terraform", "designed", "deploy", "efficient", "autoscaling", "work", "rest", "fixed", "costs", "mostly" ] }, { "id": "install#default-infrarules", "kind": "section", "title": "Install", "heading": "Default InfraRules", "group": "Operations", "url": "/docs/install#default-infrarules", "summary": "The chart can create shared infrastructure rules with stock general CPU, storage-heavy CPU, and single-GPU compute pools. Workloads select a pool explicitly or inherit one from their compute class, and operators can tune resources, placement, hardware hints, and replica ceilings.", "facts": [ { "kind": "code", "literal": "operator.infraRules.create=true", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "spec.scaling.pool", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "scaling.pool", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "worker.computeClass: cpu", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "gpu", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "cpu", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "cpu-large", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "layer.hev.dev/node-role=worker-cpu", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "worker-gpu", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "workerKarpenter", "chunkId": "install#default-infrarules" }, { "kind": "code", "literal": "operator.infraRules.computePools", "chunkId": "install#default-infrarules" } ], "sources": [ { "chunkId": "install#default-infrarules", "url": "/docs/install#default-infrarules", "anchor": "default-infrarules" } ], "mode": "agent-primary", "terms": [ "default", "infrarules", "chart", "create", "shared", "infrastructure", "rules", "stock", "general", "storage", "heavy", "single", "compute", "pools", "workloads", "select", "pool", "explicitly", "inherit", "their", "class", "operators", "tune", "resources", "placement", "hardware", "hints", "replica", "ceilings", "operator", "true", "spec", "scaling", "worker", "computeclass", "large", "layer", "node", "role", "workerkarpenter" ] }, { "id": "install#gateway-auth-modes", "kind": "section", "title": "Install", "heading": "Gateway auth modes", "group": "Operations", "url": "/docs/install#gateway-auth-modes", "summary": "Single-tenant deployments can derive gateway access from the default store credential. Gateway-only key mode instead supplies scoped inbound credentials and a designated worker bearer used by operators, autoscaling, and dashboard components.", "facts": [ { "kind": "code", "literal": "vectorStore:\n credential:\n apiKey: tpuf_...\n inboundAuth:\n mode: deriveFromStore", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "vectorStore:\n credential:\n apiKey: tpuf_...\n inboundAuth:\n mode: keys\n workerSecretKey: layer-inbound-worker-api-key\n keys:\n - name: worker\n scopes: [read, write, admin]\n apiKey: layer_worker_...\n secretRef:\n key: layer-inbound-worker-api-key", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "keys", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "apiKey", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "VectorStore", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "workerSecretName", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "workerSecretKey", "chunkId": "install#gateway-auth-modes" }, { "kind": "code", "literal": "layer-inbound-worker-api-key", "chunkId": "install#gateway-auth-modes" } ], "sources": [ { "chunkId": "install#gateway-auth-modes", "url": "/docs/install#gateway-auth-modes", "anchor": "gateway-auth-modes" } ], "mode": "agent-primary", "terms": [ "gateway", "auth", "modes", "single", "tenant", "deployments", "derive", "access", "default", "store", "credential", "only", "mode", "instead", "supplies", "scoped", "inbound", "credentials", "designated", "worker", "bearer", "operators", "autoscaling", "dashboard", "components", "vectorstore", "apikey", "tpuf", "inboundauth", "derivefromstore", "keys", "workersecretkey", "layer", "name", "scopes", "read", "write", "admin", "secretref", "workersecretname" ] }, { "id": "install#helm", "kind": "section", "title": "Install", "heading": "Helm", "group": "Operations", "url": "/docs/install#helm", "summary": "The Helm chart installs the gateway, operator, and document cache into a cluster whose AWS dependencies were created by the supplied Terraform or equivalent infrastructure.", "facts": [ { "kind": "code", "literal": "infra/helm/layer/", "chunkId": "install#helm" } ], "sources": [ { "chunkId": "install#helm", "url": "/docs/install#helm", "anchor": "helm" } ], "mode": "agent-primary", "terms": [ "helm", "chart", "installs", "gateway", "operator", "document", "cache", "cluster", "whose", "dependencies", "were", "created", "supplied", "terraform", "equivalent", "infrastructure", "infra", "layer", "already", "resources", "manage" ] }, { "id": "install#image-coordinates", "kind": "section", "title": "Install", "heading": "Image Coordinates", "group": "Operations", "url": "/docs/install#image-coordinates", "summary": "Layer-owned gateway, operator, and dashboard images are pulled publicly from the container registry but licensed features require a valid key. Search backends and customer worker images follow separate distribution and build paths.", "facts": [ { "kind": "code", "literal": "gateway:\n image: hevlayer/layer-gateway-pro:\n\noperator:\n enabled: true\n image: hevlayer/layer-operator:\n\ndashboard:\n enabled: true\n image: hevlayer/layer-dashboard:", "chunkId": "install#image-coordinates" }, { "kind": "code", "literal": "license.token", "chunkId": "install#image-coordinates" }, { "kind": "code", "literal": "license.existingSecret", "chunkId": "install#image-coordinates" }, { "kind": "code", "literal": "search", "chunkId": "install#image-coordinates" } ], "sources": [ { "chunkId": "install#image-coordinates", "url": "/docs/install#image-coordinates", "anchor": "image-coordinates" } ], "mode": "agent-primary", "terms": [ "image", "coordinates", "layer", "owned", "gateway", "operator", "dashboard", "images", "pulled", "publicly", "container", "registry", "licensed", "features", "require", "valid", "search", "backends", "customer", "worker", "follow", "separate", "distribution", "build", "paths", "hevlayer", "version", "enabled", "true", "license", "token", "existingsecret", "pull", "path", "runtime", "docker", "these", "public", "surfaces", "only" ] }, { "id": "install#install-shape", "kind": "section", "title": "Install", "heading": "Install shape", "group": "Operations", "url": "/docs/install#install-shape", "summary": "Each environment normally has one Helm release and one durable bucket. The chart creates a default serving store, while additional stores can carry separate credentials and namespace routing policies.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "install#install-shape" }, { "kind": "code", "literal": "Index.spec.backend.storeRef", "chunkId": "install#install-shape" }, { "kind": "code", "literal": "keys", "chunkId": "install#install-shape" } ], "sources": [ { "chunkId": "install#install-shape", "url": "/docs/install#install-shape", "anchor": "install-shape" } ], "mode": "agent-primary", "terms": [ "install", "shape", "environment", "normally", "helm", "release", "durable", "bucket", "chart", "creates", "default", "serving", "store", "while", "additional", "stores", "carry", "separate", "credentials", "namespace", "routing", "policies", "vectorstore", "index", "spec", "backend", "storeref", "keys", "snapshot", "history", "data", "renders", "credential", "provide", "define", "resources", "upstream", "inbound", "auth", "policy" ] }, { "id": "install#layer-operated-search", "kind": "section", "title": "Install", "heading": "Layer-Operated Search", "group": "Operations", "url": "/docs/install#layer-operated-search", "summary": "An optional in-cluster search backend shares the gateway's identity, stores durable data in object storage, uses node-local caching, exposes metrics internally, and accepts traffic only from Layer components. Its default store authentication must suit a backend without its own upstream credential.", "facts": [ { "kind": "code", "literal": "search.enabled=true", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "search", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "s3:///search", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "kind: search", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "vectorStore.inboundAuth.mode", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "keys", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "open", "chunkId": "install#layer-operated-search" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "install#layer-operated-search" } ], "sources": [ { "chunkId": "install#layer-operated-search", "url": "/docs/install#layer-operated-search", "anchor": "layer-operated-search" } ], "mode": "agent-primary", "terms": [ "layer", "operated", "search", "optional", "cluster", "backend", "shares", "gateway", "identity", "stores", "durable", "data", "object", "storage", "uses", "node", "local", "caching", "exposes", "metrics", "internally", "accepts", "traffic", "only", "components", "default", "store", "authentication", "must", "suit", "without", "upstream", "credential", "enabled", "true", "bucket", "kind", "vectorstore", "inboundauth", "mode" ] }, { "id": "install#local-gateway-development", "kind": "section", "title": "Install", "heading": "Local gateway development", "group": "Operations", "url": "/docs/install#local-gateway-development", "summary": "Local containers supply gateway dependencies but not the Kubernetes control plane. Development still needs current cluster resources and secrets, and local backend addresses must be reachable from the container network.", "facts": [ { "kind": "code", "literal": "docker compose", "chunkId": "install#local-gateway-development" }, { "kind": "code", "literal": "VectorStore", "chunkId": "install#local-gateway-development" }, { "kind": "code", "literal": "Index", "chunkId": "install#local-gateway-development" }, { "kind": "code", "literal": "VectorStore.endpoint.url", "chunkId": "install#local-gateway-development" } ], "sources": [ { "chunkId": "install#local-gateway-development", "url": "/docs/install#local-gateway-development", "anchor": "local-gateway-development" } ], "mode": "agent-primary", "terms": [ "local", "gateway", "development", "containers", "supply", "dependencies", "kubernetes", "control", "plane", "still", "needs", "current", "cluster", "resources", "secrets", "backend", "addresses", "must", "reachable", "container", "network", "docker", "compose", "vectorstore", "index", "endpoint", "starts", "replacement", "resolves", "startup", "based", "kube", "context", "layer", "crds", "installed", "matching", "secret", "objects", "applied" ] }, { "id": "install#one-script-install", "kind": "section", "title": "Install", "heading": "One-script install", "group": "Operations", "url": "/docs/install#one-script-install", "summary": "The fast installation path provisions the opinionated AWS footprint and installs the runtime in one flow, assuming standard infrastructure tools, source access, an upstream store credential, and optional license and dashboard settings. It can also reuse previously provisioned outputs.", "facts": [ { "kind": "code", "literal": "export TURBOPUFFER_API_KEY=\"tpuf_...\"\ncurl -fsSL https://hevlayer.com/install.sh | bash", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "aws", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "terraform", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "helm", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "kubectl", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "jq", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "openssl", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "LAYER_SRC", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "AWS_REGION", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "us-east-1", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "CLUSTER_NAME", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "layer", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "NAMESPACE", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "HELM_RELEASE", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "LAYER_VERSION", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "latest", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "LICENSE_TOKEN", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "admin", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "DASHBOARD_USER", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "DASHBOARD_PASSWORD", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "SKIP_TERRAFORM=1", "chunkId": "install#one-script-install" } ], "sources": [ { "chunkId": "install#one-script-install", "url": "/docs/install#one-script-install", "anchor": "one-script-install" } ], "mode": "agent-primary", "terms": [ "script", "install", "fast", "installation", "path", "provisions", "opinionated", "footprint", "installs", "runtime", "flow", "assuming", "standard", "infrastructure", "tools", "source", "access", "upstream", "store", "credential", "optional", "license", "dashboard", "settings", "also", "reuse", "previously", "provisioned", "outputs", "export", "turbopuffer", "tpuf", "curl", "fssl", "https", "hevlayer", "bash", "terraform", "helm", "kubectl" ] }, { "id": "install#outputs", "kind": "section", "title": "Install", "heading": "Outputs", "group": "Operations", "url": "/docs/install#outputs", "summary": "Terraform returns the bucket, gateway identity role, dashboard role, and cluster metadata consumed by Helm. Managed resources carry a project cost tag that should be activated for scoped cost reporting.", "facts": [ { "kind": "code", "literal": "Project=hevlayer", "chunkId": "install#outputs" } ], "sources": [ { "chunkId": "install#outputs", "url": "/docs/install#outputs", "anchor": "outputs" } ], "mode": "agent-primary", "terms": [ "outputs", "terraform", "returns", "bucket", "gateway", "identity", "role", "dashboard", "cluster", "metadata", "consumed", "helm", "managed", "resources", "carry", "project", "cost", "should", "activated", "scoped", "reporting", "hevlayer", "emits", "values", "chart", "needs", "install", "name", "irsa", "runtime", "images", "pulled", "docker", "layer", "owned", "operator", "containers", "pass", "these", "file" ] }, { "id": "install#required-values", "kind": "section", "title": "Install", "heading": "Required values", "group": "Operations", "url": "/docs/install#required-values", "summary": "Typical installations provide a serving-store credential and endpoint, runtime images, durable bucket, identity roles, dashboard identity, and a trial or commercial license. Optional settings control inbound authentication, in-cluster search, index policy discovery, cleanup, consistency cadence, cost tags, and ingress.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.credential.apiKey", "chunkId": "install#required-values" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.endpoint.url", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.endpoint.region", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.inboundAuth.mode", "chunkId": "install#required-values" }, { "kind": "code", "literal": "keys", "chunkId": "install#required-values" }, { "kind": "code", "literal": "open", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.inboundAuth.keys", "chunkId": "install#required-values" }, { "kind": "code", "literal": "read", "chunkId": "install#required-values" }, { "kind": "code", "literal": "write", "chunkId": "install#required-values" }, { "kind": "code", "literal": "admin", "chunkId": "install#required-values" }, { "kind": "code", "literal": "search.enabled", "chunkId": "install#required-values" }, { "kind": "code", "literal": "search", "chunkId": "install#required-values" }, { "kind": "code", "literal": "vectorStore.kind=search", "chunkId": "install#required-values" }, { "kind": "code", "literal": "search.image", "chunkId": "install#required-values" }, { "kind": "code", "literal": "ghcr.io/hev/*", "chunkId": "install#required-values" }, { "kind": "code", "literal": "gateway.image", "chunkId": "install#required-values" }, { "kind": "code", "literal": "hevlayer/layer-gateway-pro:", "chunkId": "install#required-values" }, { "kind": "code", "literal": "operator.image", "chunkId": "install#required-values" }, { "kind": "code", "literal": "operator.enabled", "chunkId": "install#required-values" }, { "kind": "code", "literal": "hevlayer/layer-operator:", "chunkId": "install#required-values" }, { "kind": "code", "literal": "dashboard.image", "chunkId": "install#required-values" }, { "kind": "code", "literal": "dashboard.enabled", "chunkId": "install#required-values" } ], "sources": [ { "chunkId": "install#required-values", "url": "/docs/install#required-values", "anchor": "required-values" } ], "mode": "agent-primary", "terms": [ "required", "values", "typical", "installations", "provide", "serving", "store", "credential", "endpoint", "runtime", "images", "durable", "bucket", "identity", "roles", "dashboard", "trial", "commercial", "license", "optional", "settings", "control", "inbound", "authentication", "cluster", "search", "index", "policy", "discovery", "cleanup", "consistency", "cadence", "cost", "tags", "ingress", "vectorstore", "apikey", "derivefromstore", "region", "inboundauth" ] }, { "id": "install#run-the-install", "kind": "section", "title": "Install", "heading": "Run the install", "group": "Operations", "url": "/docs/install#run-the-install", "summary": "Install or upgrade the chart from its source or onboarding artifact into a dedicated namespace; it is not distributed through a public chart repository.", "facts": [ { "kind": "code", "literal": "helm upgrade --install layer ./infra/helm/layer \\\n --namespace layer --create-namespace \\\n -f values.customer.yaml", "chunkId": "install#run-the-install" } ], "sources": [ { "chunkId": "install#run-the-install", "url": "/docs/install#run-the-install", "anchor": "run-the-install" } ], "mode": "agent-primary", "terms": [ "install", "upgrade", "chart", "source", "onboarding", "artifact", "dedicated", "namespace", "distributed", "through", "public", "repository", "helm", "layer", "infra", "create", "values", "customer", "yaml", "published", "path", "provided", "during" ] }, { "id": "install#terraform", "kind": "section", "title": "Install", "heading": "Terraform", "group": "Operations", "url": "/docs/install#terraform", "summary": "The Terraform configuration provisions the AWS resources required for correct gateway and operator behavior while leaving public DNS and certificates opt-in.", "facts": [ { "kind": "code", "literal": "infra/terraform/", "chunkId": "install#terraform" } ], "sources": [ { "chunkId": "install#terraform", "url": "/docs/install#terraform", "anchor": "terraform" } ], "mode": "agent-primary", "terms": [ "terraform", "configuration", "provisions", "resources", "required", "correct", "gateway", "operator", "behavior", "while", "leaving", "public", "certificates", "infra", "need", "opinionated", "about", "layer", "needs", "behave", "correctly", "conservative", "around", "route53", "hosted", "zones", "most", "installs", "bring", "existing" ] }, { "id": "install#what-gets-installed", "kind": "section", "title": "Install", "heading": "What gets installed", "group": "Operations", "url": "/docs/install#what-gets-installed", "summary": "The runtime includes the Rust gateway, Kubernetes operator, Aerospike-backed document cache, optional worker node pools, identities, ingress, and custom resource definitions. Larger deployments can isolate the cache onto dedicated capacity.", "facts": [ { "kind": "code", "literal": "layer-gateway", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "layer-operator", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "layer-document-cache", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "NodePool", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "EC2NodeClass", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "worker-cpu", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "worker-gpu", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "workerKarpenter.enabled=true", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "document-cache", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "documentCache.nodeRole=document-cache", "chunkId": "install#what-gets-installed" }, { "kind": "code", "literal": "documentCache.karpenter.enabled=true", "chunkId": "install#what-gets-installed" } ], "sources": [ { "chunkId": "install#what-gets-installed", "url": "/docs/install#what-gets-installed", "anchor": "what-gets-installed" } ], "mode": "agent-primary", "terms": [ "gets", "installed", "runtime", "includes", "rust", "gateway", "kubernetes", "operator", "aerospike", "backed", "document", "cache", "optional", "worker", "node", "pools", "identities", "ingress", "custom", "resource", "definitions", "larger", "deployments", "isolate", "onto", "dedicated", "capacity", "layer", "nodepool", "ec2nodeclass", "workerkarpenter", "enabled", "true", "documentcache", "noderole", "karpenter", "turbopuffer", "compatible", "routes", "fetch" ] }, { "id": "install#what-it-sets-up", "kind": "section", "title": "Install", "heading": "What it sets up", "group": "Operations", "url": "/docs/install#what-it-sets-up", "summary": "Provisioned infrastructure includes durable object storage, identity roles, a customer worker registry, and usually a managed cluster, network, and worker pools, with optional DNS and certificates. Layer-owned runtime images come from the public container registry.", "facts": [ { "kind": "code", "literal": "manage_public_dns=true", "chunkId": "install#what-it-sets-up" } ], "sources": [ { "chunkId": "install#what-it-sets-up", "url": "/docs/install#what-it-sets-up", "anchor": "what-it-sets-up" } ], "mode": "agent-primary", "terms": [ "sets", "provisioned", "infrastructure", "includes", "durable", "object", "storage", "identity", "roles", "customer", "worker", "registry", "usually", "managed", "cluster", "network", "pools", "optional", "certificates", "layer", "owned", "runtime", "images", "come", "public", "container", "manage", "true", "resource", "purpose", "bucket", "namespace", "snapshots", "search", "history", "clickstream", "events", "irsa", "policies", "gateway" ] }, { "id": "kubernetes/agent-crd", "kind": "section", "title": "Agent CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/agent-crd", "summary": "An Agent is a named, governed reasoning loop that binds a model, time budget, and searchable indices. It improves ranking through query reformulation and federated retrieval while returning ordinary search rows rather than a generated answer.", "facts": [ { "kind": "code", "literal": "Agent", "chunkId": "kubernetes/agent-crd" }, { "kind": "code", "literal": "POST /v2/agents/{name}/query", "chunkId": "kubernetes/agent-crd" }, { "kind": "code", "literal": "Auto", "chunkId": "kubernetes/agent-crd" }, { "kind": "code", "literal": "kubectl get agent -o yaml", "chunkId": "kubernetes/agent-crd" }, { "kind": "code", "literal": "client.agent(\"support-search\").apply()", "chunkId": "kubernetes/agent-crd" }, { "kind": "value", "literal": "Callout.astro", "chunkId": "kubernetes/agent-crd" } ], "sources": [ { "chunkId": "kubernetes/agent-crd", "url": "/docs/kubernetes/agent-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "agent", "named", "governed", "reasoning", "loop", "binds", "model", "time", "budget", "searchable", "indices", "improves", "ranking", "through", "query", "reformulation", "federated", "retrieval", "while", "returning", "ordinary", "search", "rows", "rather", "generated", "answer", "post", "agents", "name", "auto", "kubectl", "yaml", "client", "support", "apply", "callout", "astro", "agentic", "kubernetes", "resource" ] }, { "id": "kubernetes/agent-crd#auth", "kind": "section", "title": "Agent CRD", "heading": "Auth", "group": "Operations", "url": "/docs/kubernetes/agent-crd#auth", "summary": "Invoking an agent requires a matching key entitlement, while access to each searched namespace follows the same caller permissions as federated search.", "facts": [ { "kind": "code", "literal": "agent.", "chunkId": "kubernetes/agent-crd#auth" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#auth", "url": "/docs/kubernetes/agent-crd#auth", "anchor": "auth" } ], "mode": "agent-primary", "terms": [ "auth", "invoking", "agent", "requires", "matching", "entitlement", "while", "access", "searched", "namespace", "follows", "same", "caller", "permissions", "federated", "search", "name", "model", "other", "endpoints", "multi", "queries", "follow", "query", "behavior", "invoke", "apikey" ] }, { "id": "kubernetes/agent-crd#budget", "kind": "section", "title": "Agent CRD", "heading": "Budget", "group": "Operations", "url": "/docs/kubernetes/agent-crd#budget", "summary": "The request budget sets an overall wall-clock deadline and chooses whether a timeout returns the best ranking available or fails the request.", "facts": [ { "kind": "code", "literal": "deadlineMs", "chunkId": "kubernetes/agent-crd#budget" }, { "kind": "code", "literal": "onDeadline", "chunkId": "kubernetes/agent-crd#budget" }, { "kind": "code", "literal": "bestEffort", "chunkId": "kubernetes/agent-crd#budget" }, { "kind": "code", "literal": "error", "chunkId": "kubernetes/agent-crd#budget" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#budget", "url": "/docs/kubernetes/agent-crd#budget", "anchor": "budget" } ], "mode": "agent-primary", "terms": [ "budget", "request", "sets", "overall", "wall", "clock", "deadline", "chooses", "whether", "timeout", "returns", "best", "ranking", "available", "fails", "deadlinems", "ondeadline", "besteffort", "error", "field", "purpose", "whole", "default", "agent", "hits", "instead" ] }, { "id": "kubernetes/agent-crd#indices", "kind": "section", "title": "Agent CRD", "heading": "Indices", "group": "Operations", "url": "/docs/kubernetes/agent-crd#indices", "summary": "An agent searches its configured namespace set using the caller's own grants. The operator validates that the set is nonempty and well formed, but does not yet verify that every named namespace exists.", "facts": [ { "kind": "code", "literal": "indices", "chunkId": "kubernetes/agent-crd#indices" }, { "kind": "code", "literal": "namespaces", "chunkId": "kubernetes/agent-crd#indices" }, { "kind": "code", "literal": "IndicesResolved", "chunkId": "kubernetes/agent-crd#indices" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#indices", "url": "/docs/kubernetes/agent-crd#indices", "anchor": "indices" } ], "mode": "agent-primary", "terms": [ "indices", "agent", "searches", "configured", "namespace", "caller", "grants", "operator", "validates", "nonempty", "well", "formed", "does", "verify", "every", "named", "exists", "namespaces", "indicesresolved", "passed", "federated", "query", "checks", "list", "present", "entry", "empty", "string", "surfaced", "condition", "currently", "confirm", "names", "reads", "listed", "under", "credential", "only", "reaches" ] }, { "id": "kubernetes/agent-crd#model", "kind": "section", "title": "Agent CRD", "heading": "Model", "group": "Operations", "url": "/docs/kubernetes/agent-crd#model", "summary": "The model configuration selects the inference provider, primary model, optional fallback, and a secret-backed credential. Inline provider tokens are only a local development escape hatch and are forbidden in deployed resources.", "facts": [ { "kind": "code", "literal": "provider", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "openrouter", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "name", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "anthropic/claude-haiku-4-5", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "fallback", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "apiKeySecretRef", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "key", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "model.apiKey", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "code", "literal": "Agent", "chunkId": "kubernetes/agent-crd#model" }, { "kind": "value", "literal": "e.g", "chunkId": "kubernetes/agent-crd#model" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#model", "url": "/docs/kubernetes/agent-crd#model", "anchor": "model" } ], "mode": "agent-primary", "terms": [ "model", "configuration", "selects", "inference", "provider", "primary", "optional", "fallback", "secret", "backed", "credential", "inline", "tokens", "only", "local", "development", "escape", "hatch", "forbidden", "deployed", "resources", "openrouter", "name", "anthropic", "claude", "haiku", "apikeysecretref", "apikey", "agent", "field", "purpose", "backend", "passed", "times", "errors", "holding", "token", "never", "resource", "same" ] }, { "id": "kubernetes/agent-crd#naming", "kind": "section", "title": "Agent CRD", "heading": "Naming", "group": "Operations", "url": "/docs/kubernetes/agent-crd#naming", "summary": "Agent names must be unique across the cluster because callers address them without a namespace. A collision is resolved deterministically with a warning, so relying on duplicate names is unsafe.", "facts": [], "sources": [ { "chunkId": "kubernetes/agent-crd#naming", "url": "/docs/kubernetes/agent-crd#naming", "anchor": "naming" } ], "mode": "agent-primary", "terms": [ "naming", "agent", "names", "must", "unique", "across", "cluster", "because", "callers", "address", "without", "namespace", "collision", "resolved", "deterministically", "warning", "relying", "duplicate", "unsafe", "gateway", "agents", "name", "only", "namespaces", "define", "same", "sorts", "keeps", "lexicographically", "later", "logs", "both", "keep" ] }, { "id": "kubernetes/agent-crd#observability", "kind": "section", "title": "Agent CRD", "heading": "Observability", "group": "Operations", "url": "/docs/kubernetes/agent-crd#observability", "summary": "Per-agent deadline misses, provider latency, and token usage are exported as metrics, while reasoning traces join ordinary queries in search history. Monetary cost can be derived downstream from returned token counts.", "facts": [ { "kind": "code", "literal": "hevlayer_*", "chunkId": "kubernetes/agent-crd#observability" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#observability", "url": "/docs/kubernetes/agent-crd#observability", "anchor": "observability" } ], "mode": "agent-primary", "terms": [ "observability", "agent", "deadline", "misses", "provider", "latency", "token", "usage", "exported", "metrics", "while", "reasoning", "traces", "join", "ordinary", "queries", "search", "history", "monetary", "cost", "derived", "downstream", "returned", "counts", "hevlayer", "rate", "export", "come", "back", "inference", "response", "extra", "call", "dollar", "rather", "fetched", "request", "path", "trace", "written" ] }, { "id": "kubernetes/agent-crd#output", "kind": "section", "title": "Agent CRD", "heading": "Output", "group": "Operations", "url": "/docs/kubernetes/agent-crd#output", "summary": "Optional output controls can expose per-row retrieval and relevance scores and, separately, the reasoning trace. With both disabled, the response is indistinguishable from a normal federated query.", "facts": [ { "kind": "code", "literal": "provenance", "chunkId": "kubernetes/agent-crd#output" }, { "kind": "code", "literal": "$agent", "chunkId": "kubernetes/agent-crd#output" }, { "kind": "code", "literal": "retrievalScore", "chunkId": "kubernetes/agent-crd#output" }, { "kind": "code", "literal": "relevanceScore", "chunkId": "kubernetes/agent-crd#output" }, { "kind": "code", "literal": "agent", "chunkId": "kubernetes/agent-crd#output" }, { "kind": "code", "literal": "trace", "chunkId": "kubernetes/agent-crd#output" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#output", "url": "/docs/kubernetes/agent-crd#output", "anchor": "output" } ], "mode": "agent-primary", "terms": [ "output", "optional", "controls", "expose", "retrieval", "relevance", "scores", "separately", "reasoning", "trace", "both", "disabled", "response", "indistinguishable", "normal", "federated", "query", "provenance", "agent", "retrievalscore", "relevancescore", "field", "purpose", "true", "carries", "gains", "level", "echo", "also", "full", "default", "byte", "shape", "client", "cannot", "tell", "loop", "produced", "agentic", "search" ] }, { "id": "kubernetes/agent-crd#retrieval", "kind": "section", "title": "Agent CRD", "heading": "Retrieval", "group": "Operations", "url": "/docs/kubernetes/agent-crd#retrieval", "summary": "Agent retrieval reuses federated search, with controls for parallel reformulations, candidate depth, route choice, and the balance between recall and model relevance. Increasing breadth can improve recall at the cost of latency, and semantic legs require a caller-supplied vector.", "facts": [ { "kind": "code", "literal": "fanout", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "recallDepth", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "50", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "top_k", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "rankBy", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "auto", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "hybridText", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "semantic", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "vector", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "relevanceWeight", "chunkId": "kubernetes/agent-crd#retrieval" }, { "kind": "code", "literal": "0.6", "chunkId": "kubernetes/agent-crd#retrieval" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#retrieval", "url": "/docs/kubernetes/agent-crd#retrieval", "anchor": "retrieval" } ], "mode": "agent-primary", "terms": [ "retrieval", "agent", "reuses", "federated", "search", "controls", "parallel", "reformulations", "candidate", "depth", "route", "choice", "balance", "between", "recall", "model", "relevance", "increasing", "breadth", "improve", "cost", "latency", "semantic", "legs", "require", "caller", "supplied", "vector", "fanout", "recalldepth", "rankby", "auto", "hybridtext", "relevanceweight", "behavior", "expressed", "against", "query", "nothing", "reaches" ] }, { "id": "kubernetes/agent-crd#status", "kind": "section", "title": "Agent CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/agent-crd#status", "summary": "Agent status records validation and health, while operational usage belongs in metrics and history. Resources progress through callable, degraded, or invalid phases, and applied changes become visible after the gateway's periodic refresh.", "facts": [ { "kind": "code", "literal": "status", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "SecretResolved", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "model.apiKeySecretRef", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "ModelReachable", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "IndicesResolved", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "spec.indices", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "Ready", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "Degraded", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "Invalid", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "kubectl get agent", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "MODEL", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "INDICES", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "PHASE", "chunkId": "kubernetes/agent-crd#status" }, { "kind": "code", "literal": "kubectl apply", "chunkId": "kubernetes/agent-crd#status" } ], "sources": [ { "chunkId": "kubernetes/agent-crd#status", "url": "/docs/kubernetes/agent-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "agent", "records", "validation", "health", "while", "operational", "usage", "belongs", "metrics", "history", "resources", "progress", "through", "callable", "degraded", "invalid", "phases", "applied", "changes", "become", "visible", "after", "gateway", "periodic", "refresh", "secretresolved", "model", "apikeysecretref", "modelreachable", "indicesresolved", "spec", "indices", "ready", "kubectl", "phase", "apply", "carries", "only", "latency" ] }, { "id": "kubernetes/apikey-crd", "kind": "section", "title": "ApiKey CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/apikey-crd", "summary": "An ApiKey is a managed credential with minting, verification, revocation, and expiration lifecycle. Its per-resource entitlements combine Layer scopes with opaque claims that external applications may interpret themselves.", "facts": [ { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/apikey-crd" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/apikey-crd" }, { "kind": "code", "literal": "Warehouse", "chunkId": "kubernetes/apikey-crd" }, { "kind": "code", "literal": "Agent", "chunkId": "kubernetes/apikey-crd" }, { "kind": "code", "literal": "kubectl get apikey -o yaml", "chunkId": "kubernetes/apikey-crd" }, { "kind": "code", "literal": "GET /v2/keys/{keyId}", "chunkId": "kubernetes/apikey-crd" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd", "url": "/docs/kubernetes/apikey-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "apikey", "managed", "credential", "minting", "verification", "revocation", "expiration", "lifecycle", "resource", "entitlements", "combine", "layer", "scopes", "opaque", "claims", "external", "applications", "interpret", "themselves", "vectorstore", "warehouse", "agent", "kubectl", "yaml", "keys", "keyid", "minted", "kubernetes", "resources", "owns", "mint", "verify", "revoke", "expire", "opens", "declared", "entitlement", "names", "itself", "carries" ] }, { "id": "kubernetes/apikey-crd#backup-and-migration", "kind": "section", "title": "ApiKey CRD", "heading": "Backup and migration", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#backup-and-migration", "summary": "Portable key migration requires a full namespace or control-plane backup that preserves resource status, verifier hashes, the shared pepper, and token-delivery secrets. Restore ordering, operator quiescence, discovery freshness, and post-restore validation are essential because a specification-only copy cannot preserve working credentials.", "facts": [ { "kind": "code", "literal": "SOURCE_CONTEXT=layer-a \\\nTARGET_CONTEXT=layer-b \\\nLAYER_NAMESPACE=layer \\\nSOURCE_BASE_URL=https://source.example.com \\\nTARGET_BASE_URL=https://target.example.com \\\nSOURCE_ADMIN_KEY=hvl_... \\\nscripts/apikey-velero-migration.sh", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "status", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "status.keyId", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "phase", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "lookupHash", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "tokenHash", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "*-keys", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "LAYER_KEY_PEPPER", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "status.secretRef", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "--status-include-resources apikeys.hevlayer.com", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "Restore", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "Backup", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "Completed", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "MintBlocked", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "Pending", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "apikeys.hevlayer.com", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "Expired", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "/v2/keys", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "code", "literal": "kid", "chunkId": "kubernetes/apikey-crd#backup-and-migration" }, { "kind": "value", "literal": "spec.restoreStatus.includedResources", "chunkId": "kubernetes/apikey-crd#backup-and-migration" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#backup-and-migration", "url": "/docs/kubernetes/apikey-crd#backup-and-migration", "anchor": "backup-and-migration" } ], "mode": "agent-primary", "terms": [ "backup", "migration", "portable", "requires", "full", "namespace", "control", "plane", "preserves", "resource", "status", "verifier", "hashes", "shared", "pepper", "token", "delivery", "secrets", "restore", "ordering", "operator", "quiescence", "discovery", "freshness", "post", "validation", "essential", "because", "specification", "only", "copy", "cannot", "preserve", "working", "credentials", "source", "context", "layer", "target", "base" ] }, { "id": "kubernetes/apikey-crd#bootstrapping", "kind": "section", "title": "ApiKey CRD", "heading": "Bootstrapping", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#bootstrapping", "summary": "The bootstrap credential creates the first administrator key, after which routine key management uses minted administrators. Cluster operators may instead bootstrap through the declarative resource surface.", "facts": [ { "kind": "code", "literal": "spec:\n entitlements:\n layer:\n scopes: [admin]", "chunkId": "kubernetes/apikey-crd#bootstrapping" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "kubernetes/apikey-crd#bootstrapping" }, { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/apikey-crd#bootstrapping" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#bootstrapping", "url": "/docs/kubernetes/apikey-crd#bootstrapping", "anchor": "bootstrapping" } ], "mode": "agent-primary", "terms": [ "bootstrapping", "bootstrap", "credential", "creates", "first", "administrator", "after", "routine", "management", "uses", "minted", "administrators", "cluster", "operators", "instead", "through", "declarative", "resource", "surface", "spec", "entitlements", "layer", "scopes", "admin", "gateway", "apikey", "layergatewayapikey", "mints", "minting", "keys", "equally", "applying", "since", "authoring", "needs", "only", "kubectl", "access" ] }, { "id": "kubernetes/apikey-crd#entitlements", "kind": "section", "title": "ApiKey CRD", "heading": "Entitlements", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#entitlements", "summary": "Entitlements can grant scoped vector-store access, permission to invoke an agent, control-plane administration, or opaque warehouse claims. Missing targets grant nothing but do not block creation, and claim-only keys authenticate without opening any Layer route.", "facts": [ { "kind": "code", "literal": "vectorstore.", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "scopes", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "read", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "write", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "Index", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "namespaces", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "warehouse.", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "claims", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "agent.", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "Agent", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "POST /v2/agents//query", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "vectorstore", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "layer", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "scopes: [admin]", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "service:resource_type:resource_id:action", "chunkId": "kubernetes/apikey-crd#entitlements" }, { "kind": "code", "literal": "EntitlementTargetMissing", "chunkId": "kubernetes/apikey-crd#entitlements" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#entitlements", "url": "/docs/kubernetes/apikey-crd#entitlements", "anchor": "entitlements" } ], "mode": "agent-primary", "terms": [ "entitlements", "grant", "scoped", "vector", "store", "access", "permission", "invoke", "agent", "control", "plane", "administration", "opaque", "warehouse", "claims", "missing", "targets", "nothing", "block", "creation", "claim", "only", "keys", "authenticate", "without", "opening", "layer", "route", "vectorstore", "name", "scopes", "read", "write", "index", "namespaces", "post", "agents", "query", "admin", "service" ] }, { "id": "kubernetes/apikey-crd#kubernetes-rbac", "kind": "section", "title": "ApiKey CRD", "heading": "Kubernetes RBAC", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#kubernetes-rbac", "summary": "Dedicated cluster roles separate full key administration and token collection from read-only key auditing. Neither permission is inherited through Kubernetes' standard aggregate roles, so delegation must be explicit.", "facts": [ { "kind": "code", "literal": "hevlayer-key-admin", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "apikeys", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "get", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "hevlayer-key-viewer", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "list", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "watch", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "view", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "edit", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "admin", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" }, { "kind": "code", "literal": "rbac.keyRoleBindings", "chunkId": "kubernetes/apikey-crd#kubernetes-rbac" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#kubernetes-rbac", "url": "/docs/kubernetes/apikey-crd#kubernetes-rbac", "anchor": "kubernetes-rbac" } ], "mode": "agent-primary", "terms": [ "kubernetes", "rbac", "dedicated", "cluster", "roles", "separate", "full", "administration", "token", "collection", "read", "only", "auditing", "neither", "permission", "inherited", "through", "standard", "aggregate", "delegation", "must", "explicit", "hevlayer", "admin", "apikeys", "viewer", "list", "watch", "view", "edit", "keyrolebindings", "authoring", "makes", "kubectl", "minting", "surface", "chart", "ships", "delegate", "without" ] }, { "id": "kubernetes/apikey-crd#minting", "kind": "section", "title": "ApiKey CRD", "heading": "Minting", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#minting", "summary": "Keys minted through the API reveal the raw token once and persist only one-way verifiers. Declaratively authored keys deliver their token through an owned secret, and rotation is performed by deploying a replacement before revoking the old credential.", "facts": [ { "kind": "code", "literal": "POST /v2/keys # 201 { keyId, …, token } — token returned once\nGET /v2/keys # metadata only; ?includeRevoked\nGET /v2/keys/{keyId}\nPOST /v2/keys/{keyId}/revoke # idempotent\nDELETE /v2/keys/{keyId} # hard delete; Revoked keys only\nPOST /v2/keys/authenticate # body { token } → 200 { keyId, entitlements, … } | 401", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "POST /v2/keys", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "layer", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "admin", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "POST /v2/keys/authenticate", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "status.secretRef", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "token", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "phase", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "Pending", "chunkId": "kubernetes/apikey-crd#minting" }, { "kind": "code", "literal": "Active", "chunkId": "kubernetes/apikey-crd#minting" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#minting", "url": "/docs/kubernetes/apikey-crd#minting", "anchor": "minting" } ], "mode": "agent-primary", "terms": [ "minting", "keys", "minted", "through", "reveal", "token", "once", "persist", "only", "verifiers", "declaratively", "authored", "deliver", "their", "owned", "secret", "rotation", "performed", "deploying", "replacement", "before", "revoking", "credential", "post", "keyid", "returned", "metadata", "includerevoked", "revoke", "idempotent", "delete", "hard", "revoked", "authenticate", "body", "entitlements", "apikey", "layer", "admin", "status" ] }, { "id": "kubernetes/apikey-crd#spec", "kind": "section", "title": "ApiKey CRD", "heading": "Spec", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#spec", "summary": "A key specification can carry optional ownership metadata, a target-keyed entitlement map, and an expiration duration. The final expiration time is calculated when the key is minted.", "facts": [ { "kind": "code", "literal": "owner", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "description", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "entitlements", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "scopes", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "namespaces", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "claims", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "expiresAfter", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "never", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "365d", "chunkId": "kubernetes/apikey-crd#spec" }, { "kind": "code", "literal": "status.expiresAt", "chunkId": "kubernetes/apikey-crd#spec" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#spec", "url": "/docs/kubernetes/apikey-crd#spec", "anchor": "spec" } ], "mode": "agent-primary", "terms": [ "spec", "specification", "carry", "optional", "ownership", "metadata", "target", "keyed", "entitlement", "expiration", "duration", "final", "time", "calculated", "minted", "owner", "description", "entitlements", "scopes", "namespaces", "claims", "expiresafter", "never", "365d", "status", "expiresat", "field", "purpose", "free", "form", "label", "echoed", "list", "authenticate", "responses", "resource", "entry", "carries", "defaults", "computed" ] }, { "id": "kubernetes/apikey-crd#verification", "kind": "section", "title": "ApiKey CRD", "heading": "Verification", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#verification", "summary": "Verification uses an in-memory indexed lookup and hash check, returning a stable actor identity and entitlements for external authorization. Revocation is the normal retained audit state; permanent deletion is allowed only after revocation and removes both lifecycle record and owned token delivery.", "facts": [ { "kind": "code", "literal": "POST /v2/keys/authenticate", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "keyId", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "entitlements", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "Active", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "status.lastSeenAt", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "Pending", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "Revoked", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "POST /v2/keys/{keyId}/revoke", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "Expired", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "status.expiresAt", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "DELETE /v2/keys/{keyId}", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "409 Conflict", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/apikey-crd#verification" }, { "kind": "code", "literal": "Warehouse", "chunkId": "kubernetes/apikey-crd#verification" } ], "sources": [ { "chunkId": "kubernetes/apikey-crd#verification", "url": "/docs/kubernetes/apikey-crd#verification", "anchor": "verification" } ], "mode": "agent-primary", "terms": [ "verification", "uses", "memory", "indexed", "lookup", "hash", "check", "returning", "stable", "actor", "identity", "entitlements", "external", "authorization", "revocation", "normal", "retained", "audit", "state", "permanent", "deletion", "allowed", "only", "after", "removes", "both", "lifecycle", "record", "owned", "token", "delivery", "post", "keys", "authenticate", "keyid", "active", "status", "lastseenat", "pending", "revoked" ] }, { "id": "kubernetes/function-crd", "kind": "section", "title": "Function CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/function-crd", "summary": "A Function declares stateless computation over rows already stored in an index, with the gateway managing discovery, queues, leases, retries, and completion markers. Pipelines are preferred when external data becomes rows, while Functions handle enrichment, backfills, and other in-place derived work.", "facts": [ { "kind": "code", "literal": "Function", "chunkId": "kubernetes/function-crd" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "kubernetes/function-crd" } ], "sources": [ { "chunkId": "kubernetes/function-crd", "url": "/docs/kubernetes/function-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "function", "declares", "stateless", "computation", "rows", "already", "stored", "index", "gateway", "managing", "discovery", "queues", "leases", "retries", "completion", "markers", "pipelines", "preferred", "external", "data", "becomes", "while", "functions", "handle", "enrichment", "backfills", "other", "place", "derived", "work", "codetabs", "astro", "user", "defined", "declared", "kubernetes", "resources", "runs", "exist", "right" ] }, { "id": "kubernetes/function-crd#gpu-classifier", "kind": "section", "title": "Function CRD", "heading": "GPU classifier", "group": "Operations", "url": "/docs/kubernetes/function-crd#gpu-classifier", "summary": "GPU-backed classifiers use a GPU compute pool and should package model weights in the worker image to avoid repeated downloads. Batch, timeout, lease, and minimum-replica choices trade utilization savings against inference duration and cold-start latency.", "facts": [ { "kind": "code", "literal": "worker.computeClass: gpu", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "scaling.pool", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "layer.hev.dev/node-role=worker-gpu", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "torch", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "transformers", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "pillow", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "httpx", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "hevlayer", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "worker.batchSize", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "worker.timeoutSeconds", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "schedule.leaseSeconds", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "replicas.min: 1", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "code", "literal": "min: 0", "chunkId": "kubernetes/function-crd#gpu-classifier" }, { "kind": "value", "literal": "e.g", "chunkId": "kubernetes/function-crd#gpu-classifier" } ], "sources": [ { "chunkId": "kubernetes/function-crd#gpu-classifier", "url": "/docs/kubernetes/function-crd#gpu-classifier", "anchor": "gpu-classifier" } ], "mode": "agent-primary", "terms": [ "classifier", "backed", "classifiers", "compute", "pool", "should", "package", "model", "weights", "worker", "image", "avoid", "repeated", "downloads", "batch", "timeout", "lease", "minimum", "replica", "choices", "trade", "utilization", "savings", "against", "inference", "duration", "cold", "start", "latency", "computeclass", "scaling", "infrarules", "default", "layer", "node", "role", "torch", "transformers", "pillow", "httpx" ] }, { "id": "kubernetes/function-crd#lifecycle", "kind": "section", "title": "Function CRD", "heading": "Lifecycle", "group": "Operations", "url": "/docs/kubernetes/function-crd#lifecycle", "summary": "A Function registers during reconciliation even when paused, so pause is an observable state rather than absence. Specification updates preserve queue state under the same identity, while a missing status indicates registration failure.", "facts": [ { "kind": "code", "literal": "GET /v2/udfs\n → 200 {\"udfs\": [{\"id\": \"product-tags\", \"paused\": true, ...}]}\n\nGET /v2/udfs/product-tags/status\n → 200 {\"udf_id\": \"product-tags\", \"paused\": true, ...}", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "spec.paused: true", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "paused: true", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "404", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "/v2/udfs/{id}/status", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "paused", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "Udf", "chunkId": "kubernetes/function-crd#lifecycle" }, { "kind": "code", "literal": "UdfStatus", "chunkId": "kubernetes/function-crd#lifecycle" } ], "sources": [ { "chunkId": "kubernetes/function-crd#lifecycle", "url": "/docs/kubernetes/function-crd#lifecycle", "anchor": "lifecycle" } ], "mode": "agent-primary", "terms": [ "lifecycle", "function", "registers", "during", "reconciliation", "even", "paused", "pause", "observable", "state", "rather", "absence", "specification", "updates", "preserve", "queue", "under", "same", "identity", "while", "missing", "status", "indicates", "registration", "failure", "udfs", "product", "tags", "true", "spec", "udfstatus", "kubectl", "describe", "layer", "patch", "type", "merge", "false", "curl", "post" ] }, { "id": "kubernetes/function-crd#scaling", "kind": "section", "title": "Function CRD", "heading": "Scaling", "group": "Operations", "url": "/docs/kubernetes/function-crd#scaling", "summary": "Functions share the common pool and replica scaling model, with autoscaling driven by queued work and bounded by pool ceilings. A warm cooldown is especially useful for scale-to-zero GPU work that would otherwise repeatedly pay node, image, and model startup costs.", "facts": [ { "kind": "code", "literal": "spec.scaling", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "mode: autoscale", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "ScaledObject", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "layer_udf_queue_depth", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "maxReplicasPerWorkload", "chunkId": "kubernetes/function-crd#scaling" }, { "kind": "code", "literal": "spec.scaling.warmWindowSeconds", "chunkId": "kubernetes/function-crd#scaling" } ], "sources": [ { "chunkId": "kubernetes/function-crd#scaling", "url": "/docs/kubernetes/function-crd#scaling", "anchor": "scaling" } ], "mode": "agent-primary", "terms": [ "scaling", "functions", "share", "common", "pool", "replica", "model", "autoscaling", "driven", "queued", "work", "bounded", "ceilings", "warm", "cooldown", "especially", "useful", "scale", "zero", "would", "otherwise", "repeatedly", "node", "image", "startup", "costs", "spec", "infrarules", "default", "mode", "autoscale", "scaledobject", "layer", "queue", "depth", "maxreplicasperworkload", "warmwindowseconds", "same", "config", "pipelines" ] }, { "id": "kubernetes/function-crd#selection", "kind": "section", "title": "Function CRD", "heading": "Selection", "group": "Operations", "url": "/docs/kubernetes/function-crd#selection", "summary": "Functions can target explicit namespaces or select indexes by labels, then apply an arbitrary preserved filter during discovery. Completion-version filtering is generated automatically and should not be duplicated by the user.", "facts": [ { "kind": "code", "literal": "targetNamespaces", "chunkId": "kubernetes/function-crd#selection" }, { "kind": "code", "literal": "indexSelector", "chunkId": "kubernetes/function-crd#selection" }, { "kind": "code", "literal": "Index", "chunkId": "kubernetes/function-crd#selection" }, { "kind": "code", "literal": "filter", "chunkId": "kubernetes/function-crd#selection" }, { "kind": "code", "literal": "spec.version", "chunkId": "kubernetes/function-crd#selection" } ], "sources": [ { "chunkId": "kubernetes/function-crd#selection", "url": "/docs/kubernetes/function-crd#selection", "anchor": "selection" } ], "mode": "agent-primary", "terms": [ "selection", "functions", "target", "explicit", "namespaces", "select", "indexes", "labels", "apply", "arbitrary", "preserved", "filter", "during", "discovery", "completion", "version", "filtering", "generated", "automatically", "should", "duplicated", "user", "targetnamespaces", "indexselector", "index", "spec", "resources", "choose", "preserves", "json", "including", "array", "form", "turbopuffer", "filters", "operator", "stores", "shape", "gateway", "evaluates" ] }, { "id": "kubernetes/function-crd#simple-classifier", "kind": "section", "title": "Function CRD", "heading": "Simple classifier", "group": "Operations", "url": "/docs/kubernetes/function-crd#simple-classifier", "summary": "Worker clients implement the same claim, process, complete, and fail protocol across supported languages. Returned attributes and completion tracking are written together, and failures are classified as retryable or permanent.", "facts": [ { "kind": "code", "literal": "output=\"tags\"", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "run_udf_worker", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "attributes.tags", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "inputs", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "TransientError", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "PermanentError", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "FailUdfItems", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "failUdfItems", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "kind: \"transient\"", "chunkId": "kubernetes/function-crd#simple-classifier" }, { "kind": "code", "literal": "kind: \"permanent\"", "chunkId": "kubernetes/function-crd#simple-classifier" } ], "sources": [ { "chunkId": "kubernetes/function-crd#simple-classifier", "url": "/docs/kubernetes/function-crd#simple-classifier", "anchor": "simple-classifier" } ], "mode": "agent-primary", "terms": [ "simple", "classifier", "worker", "clients", "implement", "same", "claim", "process", "complete", "fail", "protocol", "across", "supported", "languages", "returned", "attributes", "completion", "tracking", "written", "together", "failures", "classified", "retryable", "permanent", "output", "tags", "inputs", "transienterror", "permanenterror", "failudfitems", "kind", "transient", "python", "client", "turns", "normal", "function", "loop", "side", "metadata" ] }, { "id": "kubernetes/function-crd#tuning-knobs", "kind": "section", "title": "Function CRD", "heading": "Tuning knobs", "group": "Operations", "url": "/docs/kubernetes/function-crd#tuning-knobs", "summary": "Function tuning bounds batch size, worker timeout, claim duration, discovery cadence, concurrent batches, concurrent scans, and retry attempts. These controls balance throughput, duplicate work, and failure isolation.", "facts": [ { "kind": "code", "literal": "worker.batchSize", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "worker.timeoutSeconds", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "schedule.leaseSeconds", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "schedule.discoveryIntervalSeconds", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "schedule.maxInFlightBatches", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "schedule.maxConcurrentScans", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "retry.maxAttempts", "chunkId": "kubernetes/function-crd#tuning-knobs" }, { "kind": "code", "literal": "failed", "chunkId": "kubernetes/function-crd#tuning-knobs" } ], "sources": [ { "chunkId": "kubernetes/function-crd#tuning-knobs", "url": "/docs/kubernetes/function-crd#tuning-knobs", "anchor": "tuning-knobs" } ], "mode": "agent-primary", "terms": [ "tuning", "knobs", "function", "bounds", "batch", "size", "worker", "timeout", "claim", "duration", "discovery", "cadence", "concurrent", "batches", "scans", "retry", "attempts", "these", "controls", "balance", "throughput", "duplicate", "work", "failure", "isolation", "batchsize", "timeoutseconds", "schedule", "leaseseconds", "discoveryintervalseconds", "maxinflightbatches", "maxconcurrentscans", "maxattempts", "failed", "knob", "rows", "call", "long", "held", "before" ] }, { "id": "kubernetes/function-crd#version-markers", "kind": "section", "title": "Function CRD", "heading": "Version markers", "group": "Operations", "url": "/docs/kubernetes/function-crd#version-markers", "summary": "Each completed row receives a version marker that discovery uses to find missing, outdated, or stale results. Changing the declared version safely schedules recomputation after a model, prompt, or taxonomy update.", "facts": [ { "kind": "code", "literal": "spec.version", "chunkId": "kubernetes/function-crd#version-markers" }, { "kind": "code", "literal": "v1", "chunkId": "kubernetes/function-crd#version-markers" }, { "kind": "code", "literal": "_hevlayer_udf__v", "chunkId": "kubernetes/function-crd#version-markers" }, { "kind": "code", "literal": "metadata.name: product-color", "chunkId": "kubernetes/function-crd#version-markers" }, { "kind": "code", "literal": "_hevlayer_udf_product_color_v", "chunkId": "kubernetes/function-crd#version-markers" }, { "kind": "code", "literal": "_hevlayer_udf__stale_after", "chunkId": "kubernetes/function-crd#version-markers" } ], "sources": [ { "chunkId": "kubernetes/function-crd#version-markers", "url": "/docs/kubernetes/function-crd#version-markers", "anchor": "version-markers" } ], "mode": "agent-primary", "terms": [ "version", "markers", "completed", "receives", "marker", "discovery", "uses", "find", "missing", "outdated", "stale", "results", "changing", "declared", "safely", "schedules", "recomputation", "after", "model", "prompt", "taxonomy", "update", "spec", "hevlayer", "function", "metadata", "name", "product", "color", "safety", "rail", "defaults", "completion", "gateway", "stamps", "hevlayerudf", "normalizing", "hyphens", "underscores", "hevlayerudfproductcolorv" ] }, { "id": "kubernetes/function-crd#worker", "kind": "section", "title": "Function CRD", "heading": "Worker", "group": "Operations", "url": "/docs/kubernetes/function-crd#worker", "summary": "Worker configuration chooses an image, pull or push dispatch, compute class, batching, timeouts, and optional pod customization. The operator injects workload identity, gateway connection details, execution limits, and an appropriate bearer credential.", "facts": [ { "kind": "code", "literal": "image", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "dispatch", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "pull", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "push", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "/run", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "computeClass", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "scaling.pool", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "port", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "batchSize", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "timeoutSeconds", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "podSpec", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "layer run -f", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_UDF_ID", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_BASE_URL", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_UDF_BATCH_SIZE", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_UDF_TIMEOUT_SECONDS", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_UDF_LEASE_SECONDS", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "kubernetes/function-crd#worker" }, { "kind": "code", "literal": "keys", "chunkId": "kubernetes/function-crd#worker" } ], "sources": [ { "chunkId": "kubernetes/function-crd#worker", "url": "/docs/kubernetes/function-crd#worker", "anchor": "worker" } ], "mode": "agent-primary", "terms": [ "worker", "configuration", "chooses", "image", "pull", "push", "dispatch", "compute", "class", "batching", "timeouts", "optional", "customization", "operator", "injects", "workload", "identity", "gateway", "connection", "details", "execution", "limits", "appropriate", "bearer", "credential", "computeclass", "scaling", "pool", "port", "batchsize", "timeoutseconds", "podspec", "layer", "hevlayer", "base", "batch", "size", "timeout", "seconds", "lease" ] }, { "id": "kubernetes/function-crd#writeback", "kind": "section", "title": "Function CRD", "heading": "Writeback", "group": "Operations", "url": "/docs/kubernetes/function-crd#writeback", "summary": "Workers return attribute or vector updates, and the gateway combines them with completion metadata in an idempotent writeback path. Deleting a Function removes its managed runtime resources but deliberately leaves previously written data in place.", "facts": [ { "kind": "code", "literal": "@udf(output=\"tags\")", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "run_udf_worker", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "attributes.tags", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "attributes", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "patch_columns", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "_hevlayer_*", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "vector", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "vectors", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "@udf(kind=\"embedding\")", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "tpuf", "chunkId": "kubernetes/function-crd#writeback" }, { "kind": "code", "literal": "None", "chunkId": "kubernetes/function-crd#writeback" } ], "sources": [ { "chunkId": "kubernetes/function-crd#writeback", "url": "/docs/kubernetes/function-crd#writeback", "anchor": "writeback" } ], "mode": "agent-primary", "terms": [ "writeback", "workers", "return", "attribute", "vector", "updates", "gateway", "combines", "completion", "metadata", "idempotent", "path", "deleting", "function", "removes", "managed", "runtime", "resources", "deliberately", "leaves", "previously", "written", "data", "place", "output", "tags", "worker", "attributes", "patch", "columns", "hevlayer", "vectors", "kind", "embedding", "tpuf", "none", "writes", "common", "single", "case" ] }, { "id": "kubernetes/index-crd", "kind": "section", "title": "Index CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/index-crd", "summary": "An Index represents one gateway-managed namespace and declares its backend binding plus snapshot, cache, consistency, scan, search, and embedding policy. Connection details remain owned by the referenced vector store.", "facts": [ { "kind": "code", "literal": "Index", "chunkId": "kubernetes/index-crd" } ], "sources": [ { "chunkId": "kubernetes/index-crd", "url": "/docs/kubernetes/index-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "index", "represents", "gateway", "managed", "namespace", "declares", "backend", "binding", "plus", "snapshot", "cache", "consistency", "scan", "search", "embedding", "policy", "connection", "details", "remain", "owned", "referenced", "vector", "store", "declarative", "representation", "layer", "exposed", "through", "upstream", "posture", "mode", "itself", "lives", "vectorstore", "apiversion", "hevlayer", "kind", "metadata", "name", "products" ] }, { "id": "kubernetes/index-crd#backend", "kind": "section", "title": "Index CRD", "heading": "Backend", "group": "Operations", "url": "/docs/kubernetes/index-crd#backend", "summary": "Backend policy chooses a vector store, optionally maps to a different upstream namespace, and declares the distance metric. Metrics unsupported by the chosen search backend leave the index unready.", "facts": [ { "kind": "code", "literal": "backend.storeRef", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "backend.namespace", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "backend.distanceMetric", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "cosine_distance", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "kind: search", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "Ready=False", "chunkId": "kubernetes/index-crd#backend" }, { "kind": "code", "literal": "MetricMismatch", "chunkId": "kubernetes/index-crd#backend" } ], "sources": [ { "chunkId": "kubernetes/index-crd#backend", "url": "/docs/kubernetes/index-crd#backend", "anchor": "backend" } ], "mode": "agent-primary", "terms": [ "backend", "policy", "chooses", "vector", "store", "optionally", "maps", "different", "upstream", "namespace", "declares", "distance", "metric", "metrics", "unsupported", "chosen", "search", "leave", "index", "unready", "storeref", "vectorstore", "distancemetric", "cosine", "kind", "ready", "false", "metricmismatch", "field", "purpose", "optional", "name", "same", "gateway", "routes", "requests", "defaults", "default", "override", "cosinedistance" ] }, { "id": "kubernetes/index-crd#cache-policy", "kind": "section", "title": "Index CRD", "heading": "Cache policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#cache-policy", "summary": "The document cache is ephemeral, while durable snapshot history remains in object storage. Cache warming follows the same bounded scan fan-out as other origin reads.", "facts": [], "sources": [ { "chunkId": "kubernetes/index-crd#cache-policy", "url": "/docs/kubernetes/index-crd#cache-policy", "anchor": "cache-policy" } ], "mode": "agent-primary", "terms": [ "cache", "policy", "document", "ephemeral", "while", "durable", "snapshot", "history", "remains", "object", "storage", "warming", "follows", "same", "bounded", "scan", "other", "origin", "reads", "aerospike", "stays", "uses", "scans" ] }, { "id": "kubernetes/index-crd#embedding", "kind": "section", "title": "Index CRD", "heading": "Embedding", "group": "Operations", "url": "/docs/kubernetes/index-crd#embedding", "summary": "Embedding metadata identifies the model version, output width, normalization, and distance metric needed to compare vectors across namespaces. Federated vector fusion requires all parts of that profile to match; otherwise results are interleaved by rank or rejected in strict mode.", "facts": [ { "kind": "code", "literal": "spec.embedding", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "embedding.model", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "voyage-3-large@v1", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "embedding.outputDim", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "embedding.normalization", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "l2", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "none", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "backend.distanceMetric", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "code", "literal": "strict", "chunkId": "kubernetes/index-crd#embedding" }, { "kind": "value", "literal": "e.g", "chunkId": "kubernetes/index-crd#embedding" } ], "sources": [ { "chunkId": "kubernetes/index-crd#embedding", "url": "/docs/kubernetes/index-crd#embedding", "anchor": "embedding" } ], "mode": "agent-primary", "terms": [ "embedding", "metadata", "identifies", "model", "version", "output", "width", "normalization", "distance", "metric", "needed", "compare", "vectors", "across", "namespaces", "federated", "vector", "fusion", "requires", "parts", "profile", "match", "otherwise", "results", "interleaved", "rank", "rejected", "strict", "mode", "spec", "voyage", "large", "outputdim", "none", "backend", "distancemetric", "declares", "identity", "namespace", "optional" ] }, { "id": "kubernetes/index-crd#scan-policy", "kind": "section", "title": "Index CRD", "heading": "Scan policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#scan-policy", "summary": "Scan policy sets the namespace default for parallel upstream requests during scatter and gather. The effective concurrency is bounded by server capacity and active shards, and a request may override it for one scan.", "facts": [ { "kind": "code", "literal": "scan.threads", "chunkId": "kubernetes/index-crd#scan-policy" }, { "kind": "code", "literal": "threads", "chunkId": "kubernetes/index-crd#scan-policy" } ], "sources": [ { "chunkId": "kubernetes/index-crd#scan-policy", "url": "/docs/kubernetes/index-crd#scan-policy", "anchor": "scan-policy" } ], "mode": "agent-primary", "terms": [ "scan", "policy", "sets", "namespace", "default", "parallel", "upstream", "requests", "during", "scatter", "gather", "effective", "concurrency", "bounded", "server", "capacity", "active", "shards", "request", "override", "threads", "origin", "maximum", "concurrent", "issue", "defaults", "clamped", "gateway", "shard", "count", "level", "overrides" ] }, { "id": "kubernetes/index-crd#search-backend-policy", "kind": "section", "title": "Index CRD", "heading": "Search backend policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#search-backend-policy", "summary": "Indexes backed by a search engine can ask the operator to manage the backend's text-index lifecycle. Full-text indexing should be enabled for lexical and hybrid text workloads.", "facts": [ { "kind": "code", "literal": "spec.search", "chunkId": "kubernetes/index-crd#search-backend-policy" }, { "kind": "code", "literal": "kind: search", "chunkId": "kubernetes/index-crd#search-backend-policy" }, { "kind": "code", "literal": "search.fullText", "chunkId": "kubernetes/index-crd#search-backend-policy" }, { "kind": "code", "literal": "false", "chunkId": "kubernetes/index-crd#search-backend-policy" }, { "kind": "code", "literal": "text", "chunkId": "kubernetes/index-crd#search-backend-policy" } ], "sources": [ { "chunkId": "kubernetes/index-crd#search-backend-policy", "url": "/docs/kubernetes/index-crd#search-backend-policy", "anchor": "search-backend-policy" } ], "mode": "agent-primary", "terms": [ "search", "backend", "policy", "indexes", "backed", "engine", "operator", "manage", "text", "index", "lifecycle", "full", "indexing", "should", "enabled", "lexical", "hybrid", "workloads", "spec", "kind", "fulltext", "false", "applies", "targets", "vectorstore", "uses", "drive", "explicit", "field", "default", "purpose", "build", "bm25", "namespace", "column", "enable", "namespaces" ] }, { "id": "kubernetes/index-crd#snapshot-policy", "kind": "section", "title": "Index CRD", "heading": "Snapshot policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#snapshot-policy", "summary": "Snapshot policy chooses which facets receive durable materialization, the minimum interval between stable-state writes, and how long old bodies are retained. An empty facet set disables automatic snapshot generation.", "facts": [ { "kind": "code", "literal": "snapshot.facetFields", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "[]", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "snapshot.interval", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "5m", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "snapshot.retention", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "never", "chunkId": "kubernetes/index-crd#snapshot-policy" }, { "kind": "code", "literal": "30d", "chunkId": "kubernetes/index-crd#snapshot-policy" } ], "sources": [ { "chunkId": "kubernetes/index-crd#snapshot-policy", "url": "/docs/kubernetes/index-crd#snapshot-policy", "anchor": "snapshot-policy" } ], "mode": "agent-primary", "terms": [ "snapshot", "policy", "chooses", "facets", "receive", "durable", "materialization", "minimum", "interval", "between", "stable", "state", "writes", "long", "bodies", "retained", "empty", "facet", "disables", "automatic", "generation", "facetfields", "retention", "never", "field", "default", "purpose", "fields", "gateway", "materializes", "snapshots", "writer", "spacing", "after", "upstream", "advances", "keeps", "duration", "such", "prunes" ] }, { "id": "kubernetes/index-crd#status", "kind": "section", "title": "Index CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/index-crd#status", "summary": "Index status reports the observed resource generation, metadata synchronization, and readiness conditions. Snapshot run timestamps are reserved for the gateway's history integration.", "facts": [ { "kind": "code", "literal": "status.snapshot.lastRun", "chunkId": "kubernetes/index-crd#status" }, { "kind": "code", "literal": "lastSuccess", "chunkId": "kubernetes/index-crd#status" } ], "sources": [ { "chunkId": "kubernetes/index-crd#status", "url": "/docs/kubernetes/index-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "index", "reports", "observed", "resource", "generation", "metadata", "synchronization", "readiness", "conditions", "snapshot", "timestamps", "reserved", "gateway", "history", "integration", "lastrun", "lastsuccess", "operator", "sync", "state", "bridge" ] }, { "id": "kubernetes/operator", "kind": "section", "title": "Operator Overview", "heading": null, "group": "Operations", "url": "/docs/kubernetes/operator", "summary": "The operator manages declarative cluster state such as vector stores, indexes, worker scaling, and functions, while the gateway owns live reads and writes. Custom resources are the desired-state interface between users and reconciliation.", "facts": [ { "kind": "code", "literal": "layer-operator", "chunkId": "kubernetes/operator" } ], "sources": [ { "chunkId": "kubernetes/operator", "url": "/docs/kubernetes/operator", "anchor": null } ], "mode": "agent-primary", "terms": [ "operator", "manages", "declarative", "cluster", "state", "such", "vector", "stores", "indexes", "worker", "scaling", "functions", "while", "gateway", "owns", "live", "reads", "writes", "custom", "resources", "desired", "interface", "between", "users", "reconciliation", "layer", "reconciles", "relates", "deployment", "serves", "crucial", "monitoring", "changes", "managing", "does", "through", "abstractions", "known", "resource", "definitions" ] }, { "id": "kubernetes/operator#crds", "kind": "section", "title": "Operator Overview", "heading": "CRDs", "group": "Operations", "url": "/docs/kubernetes/operator#crds", "summary": "The operator reconciles resources for serving backends, namespaces, shared infrastructure policy, row-changing pipelines, and row-preserving functions. Each resource isolates a distinct operational concern.", "facts": [], "sources": [ { "chunkId": "kubernetes/operator#crds", "url": "/docs/kubernetes/operator#crds", "anchor": "crds" } ], "mode": "agent-primary", "terms": [ "crds", "operator", "reconciles", "resources", "serving", "backends", "namespaces", "shared", "infrastructure", "policy", "changing", "pipelines", "preserving", "functions", "resource", "isolates", "distinct", "operational", "concern", "five", "kinds", "documented", "page", "vectorstore", "upstream", "store", "endpoint", "credential", "reference", "gateway", "inbound", "auth", "index", "turbopuffer", "namespace", "should", "manage", "infrarules", "cluster", "wide" ] }, { "id": "kubernetes/operator#relationship-to-the-gateway", "kind": "section", "title": "Operator Overview", "heading": "Relationship to the gateway", "group": "Operations", "url": "/docs/kubernetes/operator#relationship-to-the-gateway", "summary": "The operator and gateway are decoupled, so reconciliation delays do not enter the serving hot path. The gateway may read resource status for configuration but never writes declarative state.", "facts": [], "sources": [ { "chunkId": "kubernetes/operator#relationship-to-the-gateway", "url": "/docs/kubernetes/operator#relationship-to-the-gateway", "anchor": "relationship-to-the-gateway" } ], "mode": "agent-primary", "terms": [ "relationship", "gateway", "operator", "decoupled", "reconciliation", "delays", "enter", "serving", "path", "read", "resource", "status", "configuration", "never", "writes", "declarative", "state", "reconciles", "serves", "write", "neither", "sits", "other", "keeps", "even", "restarted", "lagging", "link", "between", "directional", "only", "some", "features", "reads", "such", "indexes", "exist", "worker", "pools", "ready" ] }, { "id": "kubernetes/operator#scheduling-and-node-pools", "kind": "section", "title": "Operator Overview", "heading": "Scheduling and node pools", "group": "Operations", "url": "/docs/kubernetes/operator#scheduling-and-node-pools", "summary": "Shared compute pools apply resource requests, node placement, and tolerations to pipelines and functions. Stock CPU and GPU pools align workloads with provisioned node classes, while operators can centralize custom placement rules.", "facts": [ { "kind": "code", "literal": "nodeSelector", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "tolerations", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "cpu-large", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "layer.hev.dev/node-role=worker-cpu", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "layer.hev.dev/node-role=worker-gpu", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "nvidia.com/gpu: \"1\"", "chunkId": "kubernetes/operator#scheduling-and-node-pools" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "kubernetes/operator#scheduling-and-node-pools" } ], "sources": [ { "chunkId": "kubernetes/operator#scheduling-and-node-pools", "url": "/docs/kubernetes/operator#scheduling-and-node-pools", "anchor": "scheduling-and-node-pools" } ], "mode": "agent-primary", "terms": [ "scheduling", "node", "pools", "shared", "compute", "apply", "resource", "requests", "placement", "tolerations", "pipelines", "functions", "stock", "align", "workloads", "provisioned", "classes", "while", "operators", "centralize", "custom", "rules", "nodeselector", "large", "layer", "role", "worker", "nvidia", "infrarules", "default", "operator", "applies", "pool", "chosen", "pipeline", "function", "container", "resources", "storage", "heavy" ] }, { "id": "kubernetes/pipeline-crd", "kind": "section", "title": "Pipeline CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/pipeline-crd", "summary": "A Pipeline declares staged ingestion that may transform one external input into a different number of Layer rows. Scaling is typically kept declarative, while workers receive source and target configuration rather than hardcoding it.", "facts": [ { "kind": "code", "literal": "Pipeline", "chunkId": "kubernetes/pipeline-crd" }, { "kind": "code", "literal": "spec.sourceRef", "chunkId": "kubernetes/pipeline-crd" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd", "url": "/docs/kubernetes/pipeline-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "pipeline", "declares", "staged", "ingestion", "transform", "external", "input", "different", "number", "layer", "rows", "scaling", "typically", "kept", "declarative", "while", "workers", "receive", "source", "target", "configuration", "rather", "hardcoding", "spec", "sourceref", "changing", "work", "declared", "kubernetes", "resource", "characteristics", "want", "ingesting", "data", "runs", "stages", "stage", "chunking", "extraction", "followed" ] }, { "id": "kubernetes/pipeline-crd#chunking", "kind": "section", "title": "Pipeline CRD", "heading": "Chunking", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#chunking", "summary": "Optional chunking splits source documents into reproducible indexing units using common text strategies, size units, overlap, and a pinned tokenizer. Generated chunks retain parent identity and order, while uncommon strategies can use a custom worker.", "facts": [ { "kind": "code", "literal": "chunk", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "strategy", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "none", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "fixed", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "recursive", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "size", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "sentence", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "markdown", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "unit", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "tokens", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "characters", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "overlap", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "tokenizer", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "unit: tokens", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "text", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "{documentId}#{i}", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "_hevlayer_parent_id", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "_hevlayer_chunk_index", "chunkId": "kubernetes/pipeline-crd#chunking" }, { "kind": "code", "literal": "spec.worker.image", "chunkId": "kubernetes/pipeline-crd#chunking" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#chunking", "url": "/docs/kubernetes/pipeline-crd#chunking", "anchor": "chunking" } ], "mode": "agent-primary", "terms": [ "chunking", "optional", "splits", "source", "documents", "reproducible", "indexing", "units", "common", "text", "strategies", "size", "overlap", "pinned", "tokenizer", "generated", "chunks", "retain", "parent", "identity", "order", "while", "uncommon", "custom", "worker", "chunk", "strategy", "none", "fixed", "recursive", "sentence", "markdown", "unit", "tokens", "characters", "documentid", "hevlayer", "index", "spec", "image" ] }, { "id": "kubernetes/pipeline-crd#pipeline-id", "kind": "section", "title": "Pipeline CRD", "heading": "Pipeline id", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#pipeline-id", "summary": "A pipeline identity names the shared gateway queue used for staging and scaling. Multiple worker resources can intentionally share that identity to form separate stages of one workflow.", "facts": [ { "kind": "code", "literal": "spec.pipelineId", "chunkId": "kubernetes/pipeline-crd#pipeline-id" }, { "kind": "code", "literal": "pipelineId: products", "chunkId": "kubernetes/pipeline-crd#pipeline-id" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#pipeline-id", "url": "/docs/kubernetes/pipeline-crd#pipeline-id", "anchor": "pipeline-id" } ], "mode": "agent-primary", "terms": [ "pipeline", "identity", "names", "shared", "gateway", "queue", "staging", "scaling", "multiple", "worker", "resources", "intentionally", "share", "form", "separate", "stages", "workflow", "spec", "pipelineid", "products", "scales", "defaults", "resource", "name", "extract", "embed", "stage", "both" ] }, { "id": "kubernetes/pipeline-crd#scaling", "kind": "section", "title": "Pipeline CRD", "heading": "Scaling", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#scaling", "summary": "Pipeline scaling can follow queue depth, pin a fixed replica count, or disable workers entirely, with placement selected from a shared pool. Scheduling, pausing, warm cooldowns, and pool replica ceilings further constrain runtime behavior.", "facts": [ { "kind": "code", "literal": "scaling:\n pool: cpu\n mode: autoscale\n replicas:\n min: 0\n max: 8", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "spec.scaling.pool", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "worker.computeClass", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "cpu-large", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "mode: autoscale", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "ScaledObject", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "spec.schedule", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "mode: fixed", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "replicas.min", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "mode: disabled", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "spec.scaling.warmWindowSeconds", "chunkId": "kubernetes/pipeline-crd#scaling" }, { "kind": "code", "literal": "spec.paused: true", "chunkId": "kubernetes/pipeline-crd#scaling" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#scaling", "url": "/docs/kubernetes/pipeline-crd#scaling", "anchor": "scaling" } ], "mode": "agent-primary", "terms": [ "scaling", "pipeline", "follow", "queue", "depth", "fixed", "replica", "count", "disable", "workers", "entirely", "placement", "selected", "shared", "pool", "scheduling", "pausing", "warm", "cooldowns", "ceilings", "further", "constrain", "runtime", "behavior", "mode", "autoscale", "replicas", "spec", "infrarules", "default", "worker", "computeclass", "large", "scaledobject", "schedule", "disabled", "warmwindowseconds", "paused", "true", "must" ] }, { "id": "kubernetes/pipeline-crd#schedule", "kind": "section", "title": "Pipeline CRD", "heading": "Schedule", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#schedule", "summary": "An optional schedule wakes workers during a cron window instead of reacting to queue depth. The worker still owns source cursors and extraction semantics, and scheduled workloads must be able to return to zero replicas.", "facts": [ { "kind": "code", "literal": "schedule:\n cron: \"0 2 * * *\" # 5-field UTC cron; minute must be a single integer\n leaseSeconds: 600 # sizes the cron window", "chunkId": "kubernetes/pipeline-crd#schedule" }, { "kind": "code", "literal": "spec.schedule", "chunkId": "kubernetes/pipeline-crd#schedule" }, { "kind": "code", "literal": "scaling.replicas.min: 0", "chunkId": "kubernetes/pipeline-crd#schedule" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#schedule", "url": "/docs/kubernetes/pipeline-crd#schedule", "anchor": "schedule" } ], "mode": "agent-primary", "terms": [ "schedule", "optional", "wakes", "workers", "during", "cron", "window", "instead", "reacting", "queue", "depth", "worker", "still", "owns", "source", "cursors", "extraction", "semantics", "scheduled", "workloads", "must", "able", "return", "zero", "replicas", "field", "minute", "single", "integer", "leaseseconds", "sizes", "spec", "scaling", "operator", "pipeline", "keda", "pending", "pull", "wake", "advance" ] }, { "id": "kubernetes/pipeline-crd#source", "kind": "section", "title": "Pipeline CRD", "heading": "Source", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#source", "summary": "A source reference describes the external system feeding a worker. Open source kinds preserve arbitrary configuration for the worker image, which owns all source-specific behavior.", "facts": [ { "kind": "code", "literal": "spec.sourceRef", "chunkId": "kubernetes/pipeline-crd#source" }, { "kind": "code", "literal": "kind", "chunkId": "kubernetes/pipeline-crd#source" }, { "kind": "code", "literal": "sourceRef", "chunkId": "kubernetes/pipeline-crd#source" }, { "kind": "code", "literal": "HEVLAYER_SOURCE_REF", "chunkId": "kubernetes/pipeline-crd#source" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#source", "url": "/docs/kubernetes/pipeline-crd#source", "anchor": "source" } ], "mode": "agent-primary", "terms": [ "source", "reference", "describes", "external", "system", "feeding", "worker", "open", "kinds", "preserve", "arbitrary", "configuration", "image", "owns", "specific", "behavior", "spec", "sourceref", "kind", "hevlayer", "declares", "feeds", "selects", "operator", "treats", "kafka", "events", "partner", "migration", "json", "injected", "verbatim", "hevlayersourceref", "extract", "chunk", "reading" ] }, { "id": "kubernetes/pipeline-crd#status", "kind": "section", "title": "Pipeline CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#status", "summary": "Detailed queue counts, stage progress, and worker state come from the pipeline status service. The Kubernetes resource itself limits status to readiness and references to objects managed by the operator.", "facts": [], "sources": [ { "chunkId": "kubernetes/pipeline-crd#status", "url": "/docs/kubernetes/pipeline-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "detailed", "queue", "counts", "stage", "progress", "worker", "state", "come", "pipeline", "service", "kubernetes", "resource", "itself", "limits", "readiness", "references", "objects", "managed", "operator", "reports", "only", "object", "conditions" ] }, { "id": "kubernetes/pipeline-crd#target", "kind": "section", "title": "Pipeline CRD", "heading": "Target", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#target", "summary": "The target selects the upstream namespace receiving pipeline output. The gateway's pipeline machinery manages documents, chunks, and vector writes for that destination.", "facts": [ { "kind": "code", "literal": "spec.target.namespace", "chunkId": "kubernetes/pipeline-crd#target" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#target", "url": "/docs/kubernetes/pipeline-crd#target", "anchor": "target" } ], "mode": "agent-primary", "terms": [ "target", "selects", "upstream", "namespace", "receiving", "pipeline", "output", "gateway", "machinery", "manages", "documents", "chunks", "vector", "writes", "destination", "spec", "turbopuffer", "owns", "document", "state" ] }, { "id": "kubernetes/pipeline-crd#typed-sources", "kind": "section", "title": "Pipeline CRD", "heading": "Typed sources", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#typed-sources", "summary": "Typed warehouse sources are validated against a verified source resource and receive credentials separately from connection metadata. Stock workers make common source kinds usable without a custom image, while an override remains available.", "facts": [ { "kind": "code", "literal": "snowflake", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "rest", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "kind", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "Warehouse", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "warehouseRef", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "Verified", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "HEVLAYER_WAREHOUSE", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "spec.worker.image", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": ".dkr.ecr.us-east-1.amazonaws.com/hev-huggingface-source", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": ".dkr.ecr.us-east-1.amazonaws.com/hev-rest-source", "chunkId": "kubernetes/pipeline-crd#typed-sources" }, { "kind": "code", "literal": "worker.image", "chunkId": "kubernetes/pipeline-crd#typed-sources" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#typed-sources", "url": "/docs/kubernetes/pipeline-crd#typed-sources", "anchor": "typed-sources" } ], "mode": "agent-primary", "terms": [ "typed", "sources", "warehouse", "validated", "against", "verified", "source", "resource", "receive", "credentials", "separately", "connection", "metadata", "stock", "workers", "make", "common", "kinds", "usable", "without", "custom", "image", "while", "override", "remains", "available", "snowflake", "huggingface", "rest", "kind", "warehouseref", "hevlayer", "spec", "worker", "acct", "east", "amazonaws", "backed", "selects", "shape" ] }, { "id": "kubernetes/pipeline-crd#worker", "kind": "section", "title": "Pipeline CRD", "heading": "Worker", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#worker", "summary": "Pipeline worker settings choose the image, compute class, batch sizing, timeout, and pod customization. The operator creates one deployment and injects pipeline identity, target, gateway, source, schedule, warehouse, and authentication context.", "facts": [ { "kind": "code", "literal": "image", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "computeClass", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "scaling.pool", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "batchSize", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "timeoutSeconds", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "podSpec", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_PIPELINE_ID", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "spec.pipelineId", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_TARGET_NAMESPACE", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "spec.target.namespace", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_BASE_URL", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_SOURCE_REF", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "spec.sourceRef", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_PIPELINE_SCHEDULE", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "spec.schedule", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "HEVLAYER_WAREHOUSE", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "Warehouse", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/pipeline-crd#worker" }, { "kind": "code", "literal": "keys", "chunkId": "kubernetes/pipeline-crd#worker" } ], "sources": [ { "chunkId": "kubernetes/pipeline-crd#worker", "url": "/docs/kubernetes/pipeline-crd#worker", "anchor": "worker" } ], "mode": "agent-primary", "terms": [ "worker", "pipeline", "settings", "choose", "image", "compute", "class", "batch", "sizing", "timeout", "customization", "operator", "creates", "deployment", "injects", "identity", "target", "gateway", "source", "schedule", "warehouse", "authentication", "context", "computeclass", "scaling", "pool", "batchsize", "timeoutseconds", "podspec", "hevlayer", "spec", "pipelineid", "namespace", "base", "sourceref", "layer", "derivefromstore", "vectorstore", "keys", "field" ] }, { "id": "kubernetes/scaling-crd", "kind": "section", "title": "InfraRules CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/scaling-crd", "summary": "A single cluster-wide infrastructure policy defines compute pools, document-cache rules, and shared scaling constraints. Pipelines and Functions choose those pools through their own inline scaling policy.", "facts": [ { "kind": "code", "literal": "InfraRules", "chunkId": "kubernetes/scaling-crd" }, { "kind": "code", "literal": "InfraRules/default", "chunkId": "kubernetes/scaling-crd" }, { "kind": "code", "literal": "spec.scaling", "chunkId": "kubernetes/scaling-crd" }, { "kind": "code", "literal": "InfraRules/default.spec.computePools", "chunkId": "kubernetes/scaling-crd" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd", "url": "/docs/kubernetes/scaling-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "single", "cluster", "wide", "infrastructure", "policy", "defines", "compute", "pools", "document", "cache", "rules", "shared", "scaling", "constraints", "pipelines", "functions", "choose", "those", "through", "their", "inline", "infrarules", "default", "spec", "computepools", "workload", "scoped", "object", "layer", "managed", "runtime", "there", "exactly", "reference", "separate", "autoscaling", "resource", "pool" ] }, { "id": "kubernetes/scaling-crd#compute-pools", "kind": "section", "title": "InfraRules CRD", "heading": "Compute pools", "group": "Operations", "url": "/docs/kubernetes/scaling-crd#compute-pools", "summary": "Compute pools centralize workload placement, tolerations, resource envelopes, GPU description, and per-workload replica ceilings. Unknown pools or requests above a ceiling make the workload unready rather than silently choosing different capacity.", "facts": [ { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "cpu-large", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "layer.hev.dev/node-role=worker-cpu", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "worker-gpu", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "nvidia.com/gpu: \"1\"", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "nodeSelector", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "gpuType", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "operator.infraRules.computePools", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "name", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "spec.scaling.pool", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "kind", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "tolerations", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "resources", "chunkId": "kubernetes/scaling-crd#compute-pools" }, { "kind": "code", "literal": "maxReplicasPerWorkload", "chunkId": "kubernetes/scaling-crd#compute-pools" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd#compute-pools", "url": "/docs/kubernetes/scaling-crd#compute-pools", "anchor": "compute-pools" } ], "mode": "agent-primary", "terms": [ "compute", "pools", "centralize", "workload", "placement", "tolerations", "resource", "envelopes", "description", "replica", "ceilings", "unknown", "requests", "above", "ceiling", "make", "unready", "rather", "silently", "choosing", "different", "capacity", "large", "layer", "node", "role", "worker", "nvidia", "nodeselector", "gputype", "operator", "infrarules", "computepools", "name", "spec", "scaling", "pool", "kind", "resources", "maxreplicasperworkload" ] }, { "id": "kubernetes/scaling-crd#document-cache-rules", "kind": "section", "title": "InfraRules CRD", "heading": "Document cache rules", "group": "Operations", "url": "/docs/kubernetes/scaling-crd#document-cache-rules", "summary": "Document-cache policy declares capacity, replication, and node-count expectations for operator validation. The chart still renders the actual cache autoscaler directly.", "facts": [ { "kind": "code", "literal": "documentCache", "chunkId": "kubernetes/scaling-crd#document-cache-rules" }, { "kind": "code", "literal": "InfraRules", "chunkId": "kubernetes/scaling-crd#document-cache-rules" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd#document-cache-rules", "url": "/docs/kubernetes/scaling-crd#document-cache-rules", "anchor": "document-cache-rules" } ], "mode": "agent-primary", "terms": [ "document", "cache", "rules", "policy", "declares", "capacity", "replication", "node", "count", "expectations", "operator", "validation", "chart", "still", "renders", "actual", "autoscaler", "directly", "documentcache", "infrarules", "captures", "owned", "settings", "factor", "helm", "keda", "object", "declared", "shape", "reports", "validates", "against" ] }, { "id": "kubernetes/scaling-crd#infrarules", "kind": "section", "title": "InfraRules CRD", "heading": "InfraRules", "group": "Operations", "url": "/docs/kubernetes/scaling-crd#infrarules", "summary": "The singleton infrastructure resource normally defines general CPU, storage-heavy CPU, and GPU pools plus document-cache scaling. The operator validates its required identity, and the chart can create a default instance.", "facts": [ { "kind": "code", "literal": "default", "chunkId": "kubernetes/scaling-crd#infrarules" }, { "kind": "code", "literal": "operator.infraRules.create=true", "chunkId": "kubernetes/scaling-crd#infrarules" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd#infrarules", "url": "/docs/kubernetes/scaling-crd#infrarules", "anchor": "infrarules" } ], "mode": "agent-primary", "terms": [ "infrarules", "singleton", "infrastructure", "resource", "normally", "defines", "general", "storage", "heavy", "pools", "plus", "document", "cache", "scaling", "operator", "validates", "required", "identity", "chart", "create", "default", "instance", "true", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "spec", "computepools", "nodeselector", "layer", "node", "role", "worker", "compute", "tolerations", "equal", "value" ] }, { "id": "kubernetes/scaling-crd#warm-window", "kind": "section", "title": "InfraRules CRD", "heading": "Warm window", "group": "Operations", "url": "/docs/kubernetes/scaling-crd#warm-window", "summary": "A warm window delays scale-down after work drains and also protects the worker node from consolidation during that cooldown. It is designed to amortize expensive GPU cold starts, applies only to autoscaling, and eventually permits genuine scale-to-zero.", "facts": [ { "kind": "code", "literal": "warmWindowSeconds", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "ScaledObject", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "cooldownPeriod", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "replicas.min", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "60", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "karpenter.sh/do-not-disrupt", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": ">= 0", "chunkId": "kubernetes/scaling-crd#warm-window" }, { "kind": "code", "literal": "mode: autoscale", "chunkId": "kubernetes/scaling-crd#warm-window" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd#warm-window", "url": "/docs/kubernetes/scaling-crd#warm-window", "anchor": "warm-window" } ], "mode": "agent-primary", "terms": [ "warm", "window", "delays", "scale", "down", "after", "work", "drains", "also", "protects", "worker", "node", "consolidation", "during", "cooldown", "designed", "amortize", "expensive", "cold", "starts", "applies", "only", "autoscaling", "eventually", "permits", "genuine", "zero", "warmwindowseconds", "scaledobject", "cooldownperiod", "replicas", "karpenter", "disrupt", "mode", "autoscale", "maps", "keda", "operator", "waits", "long" ] }, { "id": "kubernetes/scaling-crd#workload-scaling", "kind": "section", "title": "InfraRules CRD", "heading": "Workload scaling", "group": "Operations", "url": "/docs/kubernetes/scaling-crd#workload-scaling", "summary": "Workloads may autoscale within bounds, run at a fixed minimum, or remain disabled at zero. Pool ceilings, pause state, and warm cooldowns constrain those modes, while a nonzero minimum avoids cold starts at ongoing capacity cost.", "facts": [ { "kind": "code", "literal": "scaling:\n pool: gpu\n mode: autoscale\n warmWindowSeconds: 300\n replicas:\n min: 0\n max: 4", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "autoscale", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "ScaledObject", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "min", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "max", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "fixed", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "replicas.min", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "disabled", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "pool", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "InfraRules/default.spec.computePools", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "worker.computeClass", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "cpu", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "gpu", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "mode", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "replicas", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "maxReplicasPerWorkload", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "warmWindowSeconds", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "mode: autoscale", "chunkId": "kubernetes/scaling-crd#workload-scaling" }, { "kind": "code", "literal": "replicas.min: 1", "chunkId": "kubernetes/scaling-crd#workload-scaling" } ], "sources": [ { "chunkId": "kubernetes/scaling-crd#workload-scaling", "url": "/docs/kubernetes/scaling-crd#workload-scaling", "anchor": "workload-scaling" } ], "mode": "agent-primary", "terms": [ "workload", "scaling", "workloads", "autoscale", "within", "bounds", "fixed", "minimum", "remain", "disabled", "zero", "pool", "ceilings", "pause", "state", "warm", "cooldowns", "constrain", "those", "modes", "while", "nonzero", "avoids", "cold", "starts", "ongoing", "capacity", "cost", "mode", "warmwindowseconds", "replicas", "scaledobject", "infrarules", "default", "spec", "computepools", "worker", "computeclass", "maxreplicasperworkload", "behavior" ] }, { "id": "kubernetes/vectorstore-crd", "kind": "section", "title": "VectorStore CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd", "summary": "A VectorStore defines an upstream serving backend, its endpoint and secret-backed credential, and the gateway's inbound authorization policy. Multiple stores can coexist, with each index selecting its backend.", "facts": [ { "kind": "code", "literal": "apiVersion: hevlayer.com/v1alpha1\nkind: VectorStore\nmetadata:\n name: turbopuffer-default\n namespace: layer\nspec:\n kind: turbopuffer\n default: true\n endpoint:\n url: https://aws-us-east-1.turbopuffer.com\n region: aws-us-east-1\n turbopuffer:\n orgId: org_123\n credential:\n secretRef:\n name: layer\n key: turbopuffer-api-key\n inboundAuth:\n mode: deriveFromStore", "chunkId": "kubernetes/vectorstore-crd" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/vectorstore-crd" }, { "kind": "code", "literal": "Index.spec.backend.storeRef", "chunkId": "kubernetes/vectorstore-crd" }, { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "kubernetes/vectorstore-crd" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd", "url": "/docs/kubernetes/vectorstore-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "vectorstore", "defines", "upstream", "serving", "backend", "endpoint", "secret", "backed", "credential", "gateway", "inbound", "authorization", "policy", "multiple", "stores", "coexist", "index", "selecting", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "turbopuffer", "default", "namespace", "layer", "spec", "true", "https", "east", "region", "orgid", "secretref", "inboundauth", "mode", "derivefromstore", "storeref", "featuregate" ] }, { "id": "kubernetes/vectorstore-crd#connection", "kind": "section", "title": "VectorStore CRD", "heading": "Connection", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#connection", "summary": "Connection policy identifies the backend engine, default-store role, endpoint, region, optional organization metadata, and a same-namespace credential secret. Reserved but unsupported engines are rejected, and credentials never live in the resource itself.", "facts": [ { "kind": "code", "literal": "kind", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "turbopuffer", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "pinecone", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "default", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "Index", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "spec.backend.storeRef", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "endpoint.url", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "endpoint.region", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "turbopuffer.orgId", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "credential.secretRef", "chunkId": "kubernetes/vectorstore-crd#connection" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/vectorstore-crd#connection" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd#connection", "url": "/docs/kubernetes/vectorstore-crd#connection", "anchor": "connection" } ], "mode": "agent-primary", "terms": [ "connection", "policy", "identifies", "backend", "engine", "default", "store", "role", "endpoint", "region", "optional", "organization", "metadata", "same", "namespace", "credential", "secret", "reserved", "unsupported", "engines", "rejected", "credentials", "never", "live", "resource", "itself", "kind", "turbopuffer", "pinecone", "index", "spec", "storeref", "orgid", "secretref", "vectorstore", "field", "purpose", "today", "schema", "operator" ] }, { "id": "kubernetes/vectorstore-crd#inbound-auth", "kind": "section", "title": "VectorStore CRD", "heading": "Inbound auth", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#inbound-auth", "summary": "Inbound authorization can derive the bearer from the default store, use independently scoped keys, or deliberately run open. Minted key entitlements are also honored in every mode, including scope and namespace restrictions.", "facts": [ { "kind": "code", "literal": "spec:\n inboundAuth:\n mode: keys\n keys:\n - name: shop-rw\n scopes: [read, write]\n secretRef:\n name: layer\n key: layer-inbound-shop-rw-api-key", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "inboundAuth.mode", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "deriveFromStore", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "keys", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "read", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "write", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "admin", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "open", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "Authorization: Bearer ", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "LAYER_GATEWAY_API_KEY", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" }, { "kind": "code", "literal": "vectorstore.", "chunkId": "kubernetes/vectorstore-crd#inbound-auth" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd#inbound-auth", "url": "/docs/kubernetes/vectorstore-crd#inbound-auth", "anchor": "inbound-auth" } ], "mode": "agent-primary", "terms": [ "inbound", "auth", "authorization", "derive", "bearer", "default", "store", "independently", "scoped", "keys", "deliberately", "open", "minted", "entitlements", "also", "honored", "every", "mode", "including", "scope", "namespace", "restrictions", "spec", "inboundauth", "name", "shop", "scopes", "read", "write", "secretref", "layer", "derivefromstore", "admin", "gateway", "apikey", "vectorstore", "controls", "token", "accepts", "behavior" ] }, { "id": "kubernetes/vectorstore-crd#routing", "kind": "section", "title": "VectorStore CRD", "heading": "Routing", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#routing", "summary": "The gateway maintains a client for each store and routes indexed namespaces to their selected backend, falling back to the default for others. Two index resources cannot claim the same upstream namespace.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/vectorstore-crd#routing" }, { "kind": "code", "literal": "Index", "chunkId": "kubernetes/vectorstore-crd#routing" }, { "kind": "code", "literal": "spec.backend.storeRef", "chunkId": "kubernetes/vectorstore-crd#routing" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd#routing", "url": "/docs/kubernetes/vectorstore-crd#routing", "anchor": "routing" } ], "mode": "agent-primary", "terms": [ "routing", "gateway", "maintains", "client", "store", "routes", "indexed", "namespaces", "their", "selected", "backend", "falling", "back", "default", "others", "index", "resources", "cannot", "claim", "same", "upstream", "namespace", "vectorstore", "spec", "storeref", "builds", "requests", "whose", "other", "objects", "resolve" ] }, { "id": "kubernetes/vectorstore-crd#standalone-config", "kind": "section", "title": "VectorStore CRD", "heading": "Standalone config", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#standalone-config", "summary": "Standalone deployments use the same vector-store resource vocabulary from a local configuration file or inline value, resolving secret references from the environment. This keeps Docker and bare-binary setups portable to Kubernetes without schema rewrites.", "facts": [ { "kind": "code", "literal": "apiVersion: hevlayer.com/v1alpha1\nkind: VectorStore\nmetadata:\n name: turbopuffer-default\nspec:\n kind: turbopuffer\n default: true\n endpoint:\n url: https://api.turbopuffer.com\n region: aws-us-east-1\n credential:\n secretRef:\n name: layer\n key: turbopuffer-api-key\n inboundAuth:\n mode: deriveFromStore", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "layer", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "LAYER_STORE_FILE", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "LAYER_SECRET_LAYER_TURBOPUFFER_API_KEY=tpuf_...", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "LAYER_SECRET_", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "credential.secretRef", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "secretRef", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "code", "literal": "LAYER_STORE_JSON", "chunkId": "kubernetes/vectorstore-crd#standalone-config" }, { "kind": "value", "literal": "github.com", "chunkId": "kubernetes/vectorstore-crd#standalone-config" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd#standalone-config", "url": "/docs/kubernetes/vectorstore-crd#standalone-config", "anchor": "standalone-config" } ], "mode": "agent-primary", "terms": [ "standalone", "config", "deployments", "same", "vector", "store", "resource", "vocabulary", "local", "configuration", "file", "inline", "value", "resolving", "secret", "references", "environment", "keeps", "docker", "bare", "binary", "setups", "portable", "kubernetes", "without", "schema", "rewrites", "apiversion", "hevlayer", "v1alpha1", "kind", "vectorstore", "metadata", "name", "turbopuffer", "default", "spec", "true", "endpoint", "https" ] }, { "id": "kubernetes/vectorstore-crd#status", "kind": "section", "title": "VectorStore CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#status", "summary": "The operator marks a store ready after its secret references validate and a probe of the backend namespace service succeeds.", "facts": [ { "kind": "code", "literal": "status.reachable", "chunkId": "kubernetes/vectorstore-crd#status" }, { "kind": "code", "literal": "Ready", "chunkId": "kubernetes/vectorstore-crd#status" }, { "kind": "code", "literal": "GET /v1/namespaces", "chunkId": "kubernetes/vectorstore-crd#status" } ], "sources": [ { "chunkId": "kubernetes/vectorstore-crd#status", "url": "/docs/kubernetes/vectorstore-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "operator", "marks", "store", "ready", "after", "secret", "references", "validate", "probe", "backend", "namespace", "service", "succeeds", "reachable", "namespaces", "sets", "condition", "validating", "probing", "endpoint" ] }, { "id": "kubernetes/warehouse-crd", "kind": "section", "title": "Warehouse CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/warehouse-crd", "summary": "A Warehouse represents the identity, credential, and verified reachability of an external system of record. Pipelines derive reconstructible Layer data from warehouses, while vector stores serve the resulting indexes.", "facts": [ { "kind": "code", "literal": "Warehouse", "chunkId": "kubernetes/warehouse-crd" }, { "kind": "code", "literal": "VectorStore", "chunkId": "kubernetes/warehouse-crd" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd", "url": "/docs/kubernetes/warehouse-crd", "anchor": null } ], "mode": "agent-primary", "terms": [ "warehouse", "represents", "identity", "credential", "verified", "reachability", "external", "system", "record", "pipelines", "derive", "reconstructible", "layer", "data", "warehouses", "while", "vector", "stores", "serve", "resulting", "indexes", "vectorstore", "declared", "upstream", "source", "declares", "extract", "rows", "plus", "shape", "needed", "reach", "derived", "serving", "side", "opposite", "sides", "gateway" ] }, { "id": "kubernetes/warehouse-crd#connection", "kind": "section", "title": "Warehouse CRD", "heading": "Connection", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#connection", "summary": "Warehouse connection policy selects one supported source kind and a probe cadence, with exactly one matching kind-specific configuration. The resource describes where and how to connect, while each pipeline chooses the concrete dataset or query.", "facts": [ { "kind": "code", "literal": "spec.kind", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "snowflake", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "rest", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "databricks", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "iceberg", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "verifyInterval", "chunkId": "kubernetes/warehouse-crd#connection" }, { "kind": "code", "literal": "1h", "chunkId": "kubernetes/warehouse-crd#connection" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#connection", "url": "/docs/kubernetes/warehouse-crd#connection", "anchor": "connection" } ], "mode": "agent-primary", "terms": [ "connection", "warehouse", "policy", "selects", "supported", "source", "kind", "probe", "cadence", "exactly", "matching", "specific", "configuration", "resource", "describes", "connect", "while", "pipeline", "chooses", "concrete", "dataset", "query", "spec", "snowflake", "huggingface", "rest", "databricks", "iceberg", "verifyinterval", "system", "select", "reserved", "schema", "rejected", "operator", "until", "implemented", "block", "must", "present" ] }, { "id": "kubernetes/warehouse-crd#deletion", "kind": "section", "title": "Warehouse CRD", "heading": "Deletion", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#deletion", "summary": "Warehouse deletion is blocked while pipelines or entitled keys still reference it. A deliberate force override can bypass this consumer fence.", "facts": [ { "kind": "code", "literal": "status.consumers", "chunkId": "kubernetes/warehouse-crd#deletion" }, { "kind": "code", "literal": "hevlayer.com/force-delete: \"true\"", "chunkId": "kubernetes/warehouse-crd#deletion" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#deletion", "url": "/docs/kubernetes/warehouse-crd#deletion", "anchor": "deletion" } ], "mode": "agent-primary", "terms": [ "deletion", "warehouse", "blocked", "while", "pipelines", "entitled", "keys", "still", "reference", "deliberate", "force", "override", "bypass", "consumer", "fence", "status", "consumers", "hevlayer", "delete", "true", "deleting", "fences", "everything", "drawing", "finalizer", "blocks", "zero", "extracting", "annotate" ] }, { "id": "kubernetes/warehouse-crd#hugging-face", "kind": "section", "title": "Warehouse CRD", "heading": "Hugging Face", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#hugging-face", "summary": "A Hugging Face pipeline source chooses the repository, configuration, split, revision, cursor, and field mapping, while the Warehouse supplies endpoint and optional token. Revisions are pinned for stable enumeration, and stock workers support mapping and chunking without custom code.", "facts": [ { "kind": "code", "literal": "spec:\n sourceRef:\n kind: huggingface\n warehouseRef: huggingface-hub\n repo: McAuley-Lab/Amazon-Reviews-2023\n config: raw_meta_Electronics\n split: train\n revision: main\n cursor:\n field: parent_asin", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "mapping", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "text", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "id", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "{config}/{split}#{offset}", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "attributes", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "[]", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "spec.worker.image", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "HEVLAYER_WAREHOUSE", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "revision", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "chunk", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "sourceRef.kind", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "warehouseRef", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "Verified", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "repo", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "tokenSecretRef", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "/var/run/hevlayer/warehouse/token", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "tokenPath", "chunkId": "kubernetes/warehouse-crd#hugging-face" }, { "kind": "code", "literal": "HEVLAYER_SOURCE_REF", "chunkId": "kubernetes/warehouse-crd#hugging-face" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#hugging-face", "url": "/docs/kubernetes/warehouse-crd#hugging-face", "anchor": "hugging-face" } ], "mode": "agent-primary", "terms": [ "hugging", "face", "pipeline", "source", "chooses", "repository", "configuration", "split", "revision", "cursor", "field", "mapping", "while", "warehouse", "supplies", "endpoint", "optional", "token", "revisions", "pinned", "stable", "enumeration", "stock", "workers", "support", "chunking", "without", "custom", "code", "spec", "sourceref", "kind", "huggingface", "warehouseref", "repo", "mcauley", "amazon", "reviews", "2023", "config" ] }, { "id": "kubernetes/warehouse-crd#keys", "kind": "section", "title": "Warehouse CRD", "heading": "Keys", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#keys", "summary": "Warehouse key entitlements carry opaque claims for an external application to interpret. They do not open a Layer data route and become inert if the warehouse disappears.", "facts": [ { "kind": "code", "literal": "ApiKey", "chunkId": "kubernetes/warehouse-crd#keys" }, { "kind": "code", "literal": "warehouse.", "chunkId": "kubernetes/warehouse-crd#keys" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#keys", "url": "/docs/kubernetes/warehouse-crd#keys", "anchor": "keys" } ], "mode": "agent-primary", "terms": [ "keys", "warehouse", "entitlements", "carry", "opaque", "claims", "external", "application", "interpret", "open", "layer", "data", "route", "become", "inert", "disappears", "apikey", "name", "binds", "entitlement", "carrying", "list", "strings", "stores", "echoes", "routes", "client", "reaches", "source", "system", "clients", "touch", "indexes", "warehouses", "grants", "nothing", "inerts", "deleted" ] }, { "id": "kubernetes/warehouse-crd#pipeline-source", "kind": "section", "title": "Warehouse CRD", "heading": "Pipeline source", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#pipeline-source", "summary": "A warehouse-backed pipeline separates source identity and credentials from the specific query, dataset, cursor, and mapping to read. The operator requires a verified, same-namespace warehouse of the matching kind before passing source details to the worker.", "facts": [ { "kind": "code", "literal": "spec.sourceRef", "chunkId": "kubernetes/warehouse-crd#pipeline-source" }, { "kind": "code", "literal": "warehouseRef", "chunkId": "kubernetes/warehouse-crd#pipeline-source" }, { "kind": "code", "literal": "Verified", "chunkId": "kubernetes/warehouse-crd#pipeline-source" }, { "kind": "code", "literal": "HEVLAYER_SOURCE_REF", "chunkId": "kubernetes/warehouse-crd#pipeline-source" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#pipeline-source", "url": "/docs/kubernetes/warehouse-crd#pipeline-source", "anchor": "pipeline-source" } ], "mode": "agent-primary", "terms": [ "pipeline", "source", "warehouse", "backed", "separates", "identity", "credentials", "specific", "query", "dataset", "cursor", "mapping", "read", "operator", "requires", "verified", "same", "namespace", "matching", "kind", "before", "passing", "details", "worker", "spec", "sourceref", "warehouseref", "hevlayer", "extracting", "names", "block", "owns", "snowflake", "database", "hugging", "face", "split", "field", "name", "carries" ] }, { "id": "kubernetes/warehouse-crd#rest", "kind": "section", "title": "Warehouse CRD", "heading": "REST", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#rest", "summary": "A REST pipeline source declaratively describes an endpoint path, static query, offset pagination, record extraction, cursor, and field mapping. A stock worker can ingest compatible paginated JSON APIs, and shared chunking handles document-like text.", "facts": [ { "kind": "code", "literal": "request.path", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "request.query", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "baseUrl", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "pagination", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "kind: offset", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "pageSizeParam", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "offsetParam", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "pageSize", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "searchAfter", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "link", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "Link", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "response.items", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "cursor.field", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "mapping", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "id", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "text", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "attributes", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "spec.worker.image", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "HEVLAYER_WAREHOUSE", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "auth", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "HEVLAYER_SOURCE_REF", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "chunk", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "section", "chunkId": "kubernetes/warehouse-crd#rest" }, { "kind": "code", "literal": "sectionSource: jsonFields", "chunkId": "kubernetes/warehouse-crd#rest" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#rest", "url": "/docs/kubernetes/warehouse-crd#rest", "anchor": "rest" } ], "mode": "agent-primary", "terms": [ "rest", "pipeline", "source", "declaratively", "describes", "endpoint", "path", "static", "query", "offset", "pagination", "record", "extraction", "cursor", "field", "mapping", "stock", "worker", "ingest", "compatible", "paginated", "json", "apis", "shared", "chunking", "handles", "document", "like", "text", "request", "baseurl", "kind", "pagesizeparam", "offsetparam", "pagesize", "searchafter", "link", "response", "items", "attributes" ] }, { "id": "kubernetes/warehouse-crd#rest--http-json-api", "kind": "section", "title": "Warehouse CRD", "heading": "REST / HTTP JSON API", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#rest--http-json-api", "summary": "A REST warehouse defines an API origin, optional query or header credential, optional client-side rate cap, and a verification request. Endpoint selection, pagination, and mapping remain pipeline concerns so one warehouse can serve many API paths.", "facts": [ { "kind": "code", "literal": "rest", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "auth", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "Verified", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "rest.baseUrl", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "request.path", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "rest.auth", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "in", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "query", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "header", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "name", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "secretRef", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "token", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "rest.rateLimit", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "requestsPerSecond", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "rest.verify", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "path", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "code", "literal": "GET", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" }, { "kind": "flag", "literal": "-with-no-Secret", "chunkId": "kubernetes/warehouse-crd#rest--http-json-api" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#rest--http-json-api", "url": "/docs/kubernetes/warehouse-crd#rest--http-json-api", "anchor": "rest--http-json-api" } ], "mode": "agent-primary", "terms": [ "rest", "http", "json", "warehouse", "defines", "origin", "optional", "query", "header", "credential", "client", "side", "rate", "verification", "request", "endpoint", "selection", "pagination", "mapping", "remain", "pipeline", "concerns", "serve", "many", "paths", "auth", "verified", "baseurl", "path", "name", "secretref", "token", "ratelimit", "requestspersecond", "verify", "secret", "declares", "public", "apis", "need" ] }, { "id": "kubernetes/warehouse-crd#rotation", "kind": "section", "title": "Warehouse CRD", "heading": "Rotation", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#rotation", "summary": "Credential rotation updates or repoints the referenced secret, causing re-verification while new connections pick up the new material without a workload redeploy. Switching between anonymous and authenticated access follows the same specification-edit flow.", "facts": [ { "kind": "code", "literal": "status.verifiedAt", "chunkId": "kubernetes/warehouse-crd#rotation" }, { "kind": "code", "literal": "keyPairSecretRef", "chunkId": "kubernetes/warehouse-crd#rotation" }, { "kind": "code", "literal": "tokenSecretRef", "chunkId": "kubernetes/warehouse-crd#rotation" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#rotation" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#rotation", "url": "/docs/kubernetes/warehouse-crd#rotation", "anchor": "rotation" } ], "mode": "agent-primary", "terms": [ "rotation", "credential", "updates", "repoints", "referenced", "secret", "causing", "verification", "while", "connections", "pick", "material", "without", "workload", "redeploy", "switching", "between", "anonymous", "authenticated", "access", "follows", "same", "specification", "edit", "flow", "status", "verifiedat", "keypairsecretref", "tokensecretref", "huggingface", "swap", "content", "operator", "verifies", "advances", "consumers", "resolve", "credentials", "through", "warehouse" ] }, { "id": "kubernetes/warehouse-crd#snowflake", "kind": "section", "title": "Warehouse CRD", "heading": "Snowflake", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#snowflake", "summary": "Supported warehouse connections include key-pair Snowflake, optional-token Hugging Face, and optional-auth REST sources, each with periodic verification. The warehouse owns connection identity and credentials, while pipelines own database, table, repository, or split selection.", "facts": [ { "kind": "code", "literal": "kind", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "rest", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "databricks", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "iceberg", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.account", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.user", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.role", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.warehouse", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.keyPairSecretRef", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "private-key.pem", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "passphrase", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "snowflake.pool", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "size", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "timeout", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "huggingface.endpoint", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "https://huggingface.co", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "huggingface.tokenSecretRef", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "token", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "verifyInterval", "chunkId": "kubernetes/warehouse-crd#snowflake" }, { "kind": "code", "literal": "1h", "chunkId": "kubernetes/warehouse-crd#snowflake" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#snowflake", "url": "/docs/kubernetes/warehouse-crd#snowflake", "anchor": "snowflake" } ], "mode": "agent-primary", "terms": [ "snowflake", "supported", "warehouse", "connections", "include", "pair", "optional", "token", "hugging", "face", "auth", "rest", "sources", "periodic", "verification", "owns", "connection", "identity", "credentials", "while", "pipelines", "database", "table", "repository", "split", "selection", "kind", "huggingface", "databricks", "iceberg", "account", "user", "role", "keypairsecretref", "private", "passphrase", "pool", "size", "timeout", "endpoint" ] }, { "id": "kubernetes/warehouse-crd#snowflake-1", "kind": "section", "title": "Warehouse CRD", "heading": "Snowflake", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#snowflake-1", "summary": "A Snowflake pipeline source supplies the database query and incremental cursor, while the operator mounts key-pair material separately and injects nonsecret connection metadata for the worker to combine.", "facts": [ { "kind": "code", "literal": "spec:\n sourceRef:\n kind: snowflake\n warehouseRef: prod-snowflake\n database: ANALYTICS\n query: >-\n SELECT ID, TITLE, BODY, REFRESH_ID FROM PUBLIC.NOTES\n WHERE REFRESH_ID > :cursor\n cursor:\n column: REFRESH_ID", "chunkId": "kubernetes/warehouse-crd#snowflake-1" }, { "kind": "code", "literal": "/var/run/hevlayer/warehouse/", "chunkId": "kubernetes/warehouse-crd#snowflake-1" }, { "kind": "code", "literal": "HEVLAYER_WAREHOUSE", "chunkId": "kubernetes/warehouse-crd#snowflake-1" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#snowflake-1", "url": "/docs/kubernetes/warehouse-crd#snowflake-1", "anchor": "snowflake-1" } ], "mode": "agent-primary", "terms": [ "snowflake", "pipeline", "source", "supplies", "database", "query", "incremental", "cursor", "while", "operator", "mounts", "pair", "material", "separately", "injects", "nonsecret", "connection", "metadata", "worker", "combine", "spec", "sourceref", "kind", "warehouseref", "prod", "analytics", "select", "title", "body", "refresh", "public", "notes", "column", "hevlayer", "warehouse", "refreshid", "secret", "hevlayerwarehouse", "json", "resolved" ] }, { "id": "kubernetes/warehouse-crd#status", "kind": "section", "title": "Warehouse CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#status", "summary": "Warehouse status records verification phase and time, failure details, resolved source revisions, and counts of consuming pipelines and keys. Phase transitions also produce cluster events.", "facts": [ { "kind": "code", "literal": "status:\n phase: Verified\n verifiedAt: \"2026-06-10T00:00:00Z\"\n failureReason: null\n sourceRevisions:\n McAuley-Lab/Amazon-Reviews-2023@main: 2b6d039ed471f2ba5fd2acb718bf33b0a7e5598e\n consumers:\n pipelines: 2\n apiKeys: 1", "chunkId": "kubernetes/warehouse-crd#status" }, { "kind": "code", "literal": "status.consumers", "chunkId": "kubernetes/warehouse-crd#status" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#status", "url": "/docs/kubernetes/warehouse-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "warehouse", "records", "verification", "phase", "time", "failure", "details", "resolved", "source", "revisions", "counts", "consuming", "pipelines", "keys", "transitions", "also", "produce", "cluster", "events", "verified", "verifiedat", "2026", "10t00", "failurereason", "null", "sourcerevisions", "mcauley", "amazon", "reviews", "2023", "main", "2b6d039ed471f2ba5fd2acb718bf33b0a7e5598e", "consumers", "apikeys", "operator", "emits", "kubernetes", "observed", "references" ] }, { "id": "kubernetes/warehouse-crd#supported-warehouses", "kind": "section", "title": "Warehouse CRD", "heading": "Supported Warehouses", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#supported-warehouses", "summary": "Snowflake, Hugging Face, and paginated JSON APIs are supported warehouse kinds, while Databricks and Iceberg remain schema-reserved but rejected. Sources may be credentialed or public where the upstream permits anonymous access.", "facts": [ { "kind": "code", "literal": "apiVersion: hevlayer.com/v1alpha1\nkind: Warehouse\nmetadata:\n name: prod-snowflake\n namespace: layer\nspec:\n kind: snowflake\n snowflake:\n account: acme-xy12345\n user: SVC_LAYER\n role: SVC_LAYER_ROLE\n warehouse: EXTRACT_WH\n keyPairSecretRef:\n name: snowflake-rsa\n pool:\n size: 5\n timeout: 30s\n verifyInterval: 1h", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "apiVersion: hevlayer.com/v1alpha1\nkind: Warehouse\nmetadata:\n name: huggingface-hub\n namespace: hev-shop\nspec:\n kind: huggingface\n huggingface:\n endpoint: https://huggingface.co\n # tokenSecretRef is optional for public datasets.\n # tokenSecretRef:\n # name: hf-read # key: token\n verifyInterval: 1h", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "snowflake", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "rest", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "databricks", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" }, { "kind": "code", "literal": "iceberg", "chunkId": "kubernetes/warehouse-crd#supported-warehouses" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#supported-warehouses", "url": "/docs/kubernetes/warehouse-crd#supported-warehouses", "anchor": "supported-warehouses" } ], "mode": "agent-primary", "terms": [ "supported", "warehouses", "snowflake", "hugging", "face", "paginated", "json", "apis", "warehouse", "kinds", "while", "databricks", "iceberg", "remain", "schema", "reserved", "rejected", "sources", "credentialed", "public", "upstream", "permits", "anonymous", "access", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "prod", "namespace", "layer", "spec", "account", "acme", "xy12345", "user", "role", "extract" ] }, { "id": "kubernetes/warehouse-crd#verification", "kind": "section", "title": "Warehouse CRD", "heading": "Verification", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#verification", "summary": "The operator probes a warehouse when applied, when credentials change, and on a configured cadence, using a source-appropriate check. Failed verification blocks new pipeline starts but does not terminate in-flight work, and only verified warehouses may launch consumers.", "facts": [ { "kind": "code", "literal": "verifyInterval", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "snowflake", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "SELECT 1", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "huggingface", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "repo@revision", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "status.sourceRevisions", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "rest", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "GET", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "rest.verify.path", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "query", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "auth", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "2xx", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "Verified", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "Pending", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "status.verifiedAt", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "Failed", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "status.failureReason", "chunkId": "kubernetes/warehouse-crd#verification" }, { "kind": "code", "literal": "kubectl get warehouse", "chunkId": "kubernetes/warehouse-crd#verification" } ], "sources": [ { "chunkId": "kubernetes/warehouse-crd#verification", "url": "/docs/kubernetes/warehouse-crd#verification", "anchor": "verification" } ], "mode": "agent-primary", "terms": [ "verification", "operator", "probes", "warehouse", "applied", "credentials", "change", "configured", "cadence", "source", "appropriate", "check", "failed", "blocks", "pipeline", "starts", "does", "terminate", "flight", "work", "only", "verified", "warehouses", "launch", "consumers", "verifyinterval", "snowflake", "select", "huggingface", "repo", "revision", "status", "sourcerevisions", "rest", "verify", "path", "query", "auth", "pending", "verifiedat" ] }, { "id": "licensing", "kind": "section", "title": "Licensing", "heading": null, "group": "Overview", "url": "/docs/licensing", "summary": "Layer licenses are issued per environment and follow one installation and monitoring path for trials, design partners, and production. The signed key is installed with the deployment and evaluated locally.", "facts": [], "sources": [ { "chunkId": "licensing", "url": "/docs/licensing", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "licenses", "issued", "environment", "follow", "installation", "monitoring", "path", "trials", "design", "partners", "production", "signed", "installed", "deployment", "evaluated", "locally", "install", "monitor", "trial", "commercial", "license", "licensed", "partner", "installs", "same", "sign", "receive", "email", "helm", "gateway", "local", "state" ] }, { "id": "licensing#client-sdks", "kind": "section", "title": "Licensing", "heading": "Client SDKs", "group": "Overview", "url": "/docs/licensing#client-sdks", "summary": "Generated client libraries remain permissively licensed as low-friction entry points to the public API, independent of the server's commercial licensing.", "facts": [ { "kind": "value", "literal": "Apache-2", "chunkId": "licensing#client-sdks" }, { "kind": "value", "literal": "Apache-2.0", "chunkId": "licensing#client-sdks" }, { "kind": "value", "literal": "2.0", "chunkId": "licensing#client-sdks" } ], "sources": [ { "chunkId": "licensing#client-sdks", "url": "/docs/licensing#client-sdks", "anchor": "client-sdks" } ], "mode": "agent-primary", "terms": [ "client", "sdks", "generated", "libraries", "remain", "permissively", "licensed", "friction", "entry", "points", "public", "independent", "server", "commercial", "licensing", "apache", "stay", "pure", "onramps", "surface", "intended", "easy", "adopt", "application" ] }, { "id": "licensing#end-to-end-runbook", "kind": "section", "title": "Licensing", "heading": "End-to-End Runbook", "group": "Overview", "url": "/docs/licensing#end-to-end-runbook", "summary": "The license acceptance workflow uses an isolated cluster to exercise signup, installation, local state, and optional telemetry checks. Grace testing is never run against the shared production cluster, and an unlicensed install does not receive a free grace period.", "facts": [ { "kind": "code", "literal": "scripts/license-e2e-real.sh", "chunkId": "licensing#end-to-end-runbook" }, { "kind": "code", "literal": "infra/helm/layer", "chunkId": "licensing#end-to-end-runbook" }, { "kind": "code", "literal": "license.token", "chunkId": "licensing#end-to-end-runbook" }, { "kind": "code", "literal": "GET /v2/license", "chunkId": "licensing#end-to-end-runbook" }, { "kind": "code", "literal": "exp", "chunkId": "licensing#end-to-end-runbook" } ], "sources": [ { "chunkId": "licensing#end-to-end-runbook", "url": "/docs/licensing#end-to-end-runbook", "anchor": "end-to-end-runbook" } ], "mode": "agent-primary", "terms": [ "runbook", "license", "acceptance", "workflow", "uses", "isolated", "cluster", "exercise", "signup", "installation", "local", "state", "optional", "telemetry", "checks", "grace", "testing", "never", "against", "shared", "production", "unlicensed", "install", "does", "receive", "free", "period", "scripts", "real", "infra", "helm", "layer", "token", "full", "fidelity", "scripted", "script", "plus", "addressed", "inbox" ] }, { "id": "licensing#governing-terms", "kind": "section", "title": "Licensing", "heading": "Governing Terms", "group": "Overview", "url": "/docs/licensing#governing-terms", "summary": "Trademark policy governs product names and marks, hosted-service terms govern the operated service, and the privacy policy governs hosted data and telemetry. Self-hosting remains subject to the gateway license plus trademark rules.", "facts": [ { "kind": "code", "literal": "TRADEMARKS.md", "chunkId": "licensing#governing-terms" }, { "kind": "value", "literal": "github.com", "chunkId": "licensing#governing-terms" }, { "kind": "value", "literal": "hevlayer.com", "chunkId": "licensing#governing-terms" } ], "sources": [ { "chunkId": "licensing#governing-terms", "url": "/docs/licensing#governing-terms", "anchor": "governing-terms" } ], "mode": "agent-primary", "terms": [ "governing", "terms", "trademark", "policy", "governs", "product", "names", "marks", "hosted", "service", "govern", "operated", "privacy", "data", "telemetry", "self", "hosting", "remains", "subject", "gateway", "license", "plus", "rules", "trademarks", "github", "hevlayer", "document", "brand", "layer", "identity", "including", "acceptable", "billing", "liability", "support", "handling", "site", "governed" ] }, { "id": "licensing#install-the-key", "kind": "section", "title": "Licensing", "heading": "Install the Key", "group": "Overview", "url": "/docs/licensing#install-the-key", "summary": "A deployment can receive the emailed license directly through chart configuration or reference a pre-created secret managed by cluster policy.", "facts": [ { "kind": "code", "literal": "helm upgrade --install layer ./infra/helm/layer \\\n --namespace layer --create-namespace \\\n --set license.token=\"$HEVLAYER_LICENSE\" \\\n -f values.customer.yaml", "chunkId": "licensing#install-the-key" }, { "kind": "code", "literal": "license.token", "chunkId": "licensing#install-the-key" }, { "kind": "code", "literal": "license.existingSecret", "chunkId": "licensing#install-the-key" }, { "kind": "code", "literal": "license.secretKey", "chunkId": "licensing#install-the-key" } ], "sources": [ { "chunkId": "licensing#install-the-key", "url": "/docs/licensing#install-the-key", "anchor": "install-the-key" } ], "mode": "agent-primary", "terms": [ "install", "deployment", "receive", "emailed", "license", "directly", "through", "chart", "configuration", "reference", "created", "secret", "managed", "cluster", "policy", "helm", "upgrade", "layer", "infra", "namespace", "create", "token", "hevlayer", "values", "customer", "yaml", "existingsecret", "secretkey", "installs", "pass", "hevlayerlicense", "requires", "kubernetes", "secrets", "normal", "workflow", "point", "guide", "full", "table" ] }, { "id": "licensing#license-claims", "kind": "section", "title": "Licensing", "heading": "License Claims", "group": "Overview", "url": "/docs/licensing#license-claims", "summary": "The signed license is verified offline by each Layer component and describes subject, tier, features, limits, issuance, and expiration. Licensing determines which product surfaces are available, while API keys separately determine caller identity and permissions; core data routes remain available in every license state.", "facts": [ { "kind": "code", "literal": "v4.public", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "sub", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "tier", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "features", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "limits", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "iat", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "exp", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "transform-runtime", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "agents", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "rbac", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "warehouses", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "doc-cache", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "history", "chunkId": "licensing#license-claims" }, { "kind": "code", "literal": "cost", "chunkId": "licensing#license-claims" } ], "sources": [ { "chunkId": "licensing#license-claims", "url": "/docs/licensing#license-claims", "anchor": "license-claims" } ], "mode": "agent-primary", "terms": [ "license", "claims", "signed", "verified", "offline", "layer", "component", "describes", "subject", "tier", "features", "limits", "issuance", "expiration", "licensing", "determines", "product", "surfaces", "available", "while", "keys", "separately", "determine", "caller", "identity", "permissions", "core", "data", "routes", "remain", "every", "state", "public", "transform", "runtime", "agents", "rbac", "warehouses", "cache", "history" ] }, { "id": "licensing#license-states", "kind": "section", "title": "Licensing", "heading": "License States", "group": "Overview", "url": "/docs/licensing#license-states", "summary": "A deployment is fully licensed before expiration, remains temporarily functional during a post-expiration grace window, and drops gated surfaces to community behavior after grace or without a valid key. Gateway, operator, and dashboard use the same local state model.", "facts": [ { "kind": "code", "literal": "curl -H \"Authorization: Bearer $LAYER_API_KEY\" \\\n https:///v2/license", "chunkId": "licensing#license-states" }, { "kind": "code", "literal": "licensed", "chunkId": "licensing#license-states" }, { "kind": "code", "literal": "grace", "chunkId": "licensing#license-states" }, { "kind": "code", "literal": "floor", "chunkId": "licensing#license-states" } ], "sources": [ { "chunkId": "licensing#license-states", "url": "/docs/licensing#license-states", "anchor": "license-states" } ], "mode": "agent-primary", "terms": [ "license", "states", "deployment", "fully", "licensed", "before", "expiration", "remains", "temporarily", "functional", "during", "post", "grace", "window", "drops", "gated", "surfaces", "community", "behavior", "after", "without", "valid", "gateway", "operator", "dashboard", "same", "local", "state", "model", "curl", "authorization", "bearer", "layer", "https", "host", "floor", "evaluates", "locally", "configured", "does" ] }, { "id": "licensing#metrics", "kind": "section", "title": "Licensing", "heading": "Metrics", "group": "Overview", "url": "/docs/licensing#metrics", "summary": "License metrics expose validity, time to expiration, grace remaining, degraded state, and requests admitted during grace. Practical alerts cover approaching expiry, any grace traffic, and entry into the degraded floor.", "facts": [ { "kind": "code", "literal": "license_tier", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "license_sub", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "surface", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "surface=\"gateway\"", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_valid", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_expiry_seconds", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "exp", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_grace_seconds_remaining", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_degraded", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_grace_requests_total", "chunkId": "licensing#metrics" }, { "kind": "code", "literal": "hevlayer_license_degraded == 1", "chunkId": "licensing#metrics" } ], "sources": [ { "chunkId": "licensing#metrics", "url": "/docs/licensing#metrics", "anchor": "metrics" } ], "mode": "agent-primary", "terms": [ "metrics", "license", "expose", "validity", "time", "expiration", "grace", "remaining", "degraded", "state", "requests", "admitted", "during", "practical", "alerts", "cover", "approaching", "expiry", "traffic", "entry", "floor", "tier", "surface", "gateway", "hevlayer", "valid", "seconds", "total", "health", "exported", "uses", "licensetier", "licensesub", "labels", "also", "include", "phase", "emits", "metric", "type" ] }, { "id": "licensing#renewals", "kind": "section", "title": "Licensing", "heading": "Renewals", "group": "Overview", "url": "/docs/licensing#renewals", "summary": "Renewal replaces the deployment's configured key or referenced secret with a newly issued value, followed by a rollout so components load it.", "facts": [], "sources": [ { "chunkId": "licensing#renewals", "url": "/docs/licensing#renewals", "anchor": "renewals" } ], "mode": "agent-primary", "terms": [ "renewals", "renewal", "replaces", "deployment", "configured", "referenced", "secret", "newly", "issued", "value", "followed", "rollout", "components", "load", "trial", "commercial", "license", "close", "expiration", "request", "through", "layer", "contact", "reply", "email", "replace", "helm", "roll", "gateway", "release", "reads" ] }, { "id": "licensing#start-a-trial", "kind": "section", "title": "Licensing", "heading": "Start a Trial", "group": "Overview", "url": "/docs/licensing#start-a-trial", "summary": "Trial signup returns a signed key that should be protected like any deployment secret. Commercial images require a valid license; otherwise gated gateway, operator, and dashboard capabilities reduce to the license floor.", "facts": [ { "kind": "code", "literal": "hevlayer/layer-gateway-pro:", "chunkId": "licensing#start-a-trial" }, { "kind": "code", "literal": "hevlayer/layer-operator:", "chunkId": "licensing#start-a-trial" }, { "kind": "code", "literal": "hevlayer/layer-dashboard:", "chunkId": "licensing#start-a-trial" } ], "sources": [ { "chunkId": "licensing#start-a-trial", "url": "/docs/licensing#start-a-trial", "anchor": "start-a-trial" } ], "mode": "agent-primary", "terms": [ "start", "trial", "signup", "returns", "signed", "should", "protected", "like", "deployment", "secret", "commercial", "images", "require", "valid", "license", "otherwise", "gated", "gateway", "operator", "dashboard", "capabilities", "reduce", "floor", "hevlayer", "layer", "version", "site", "submit", "email", "address", "want", "associated", "install", "emails", "back", "current", "instructions", "only", "material", "need" ] }, { "id": "limits", "kind": "section", "title": "Limits", "heading": null, "group": "Overview", "url": "/docs/limits", "summary": "Current hard ceilings arise mainly from the single-node cache, backend namespace capacity, cache licensing, and in-memory facet aggregation. Snapshot facets omit fields beyond their cardinality cap, while oversized on-demand value scans retain exact counts only for the most frequent values.", "facts": [ { "kind": "code", "literal": "fields_skipped[]", "chunkId": "limits" }, { "kind": "code", "literal": "fields[]", "chunkId": "limits" }, { "kind": "code", "literal": "truncated: true", "chunkId": "limits" } ], "sources": [ { "chunkId": "limits", "url": "/docs/limits", "anchor": null } ], "mode": "agent-primary", "terms": [ "current", "hard", "ceilings", "arise", "mainly", "single", "node", "cache", "backend", "namespace", "capacity", "licensing", "memory", "facet", "aggregation", "snapshot", "facets", "omit", "fields", "beyond", "their", "cardinality", "while", "oversized", "demand", "value", "scans", "retain", "exact", "counts", "only", "most", "frequent", "values", "skipped", "truncated", "true", "inherited", "components", "ship" ] }, { "id": "limits#no-limits", "kind": "section", "title": "Limits", "heading": "No limits", "group": "Overview", "url": "/docs/limits#no-limits", "summary": "Several surfaces have no Layer-enforced ceiling, including resource count, durable histories, event volume, function concurrency, queue depth, and document shape. Their practical limits instead come from cluster throughput, storage cost, autoscaling capacity, object storage, databases, and upstream record constraints.", "facts": [ { "kind": "code", "literal": "Index", "chunkId": "limits#no-limits" }, { "kind": "code", "literal": "Function", "chunkId": "limits#no-limits" }, { "kind": "code", "literal": "Pipeline", "chunkId": "limits#no-limits" }, { "kind": "code", "literal": "Scaling", "chunkId": "limits#no-limits" }, { "kind": "code", "literal": "spec.snapshot.retention", "chunkId": "limits#no-limits" }, { "kind": "code", "literal": "retention: never", "chunkId": "limits#no-limits" } ], "sources": [ { "chunkId": "limits#no-limits", "url": "/docs/limits#no-limits", "anchor": "no-limits" } ], "mode": "agent-primary", "terms": [ "limits", "several", "surfaces", "layer", "enforced", "ceiling", "including", "resource", "count", "durable", "histories", "event", "volume", "function", "concurrency", "queue", "depth", "document", "shape", "their", "practical", "instead", "come", "cluster", "throughput", "storage", "cost", "autoscaling", "capacity", "object", "databases", "upstream", "record", "constraints", "index", "pipeline", "scaling", "spec", "snapshot", "retention" ] }, { "id": "quickstart", "kind": "section", "title": "Quickstart", "heading": null, "group": "Operations", "url": "/docs/quickstart", "summary": "The community gateway can run in front of an existing Turbopuffer account without signup or a license. A short local flow starts the gateway, initializes an existing namespace, and sends a query using the upstream key as bearer authentication.", "facts": [ { "kind": "code", "literal": "export TURBOPUFFER_API_KEY=\"tpuf_...\"\nexport LAYER_NAMESPACE=\"products\"\nexport LAYER_GATEWAY_URL=\"http://localhost:8080\"", "chunkId": "quickstart" }, { "kind": "code", "literal": "curl", "chunkId": "quickstart" } ], "sources": [ { "chunkId": "quickstart", "url": "/docs/quickstart", "anchor": null } ], "mode": "agent-primary", "terms": [ "community", "gateway", "front", "existing", "turbopuffer", "account", "without", "signup", "license", "short", "local", "flow", "starts", "initializes", "namespace", "sends", "query", "upstream", "bearer", "authentication", "export", "tpuf", "layer", "products", "http", "localhost", "8080", "curl", "docker", "initialize", "three", "steps", "needed", "token", "data", "stays", "need", "rows" ] }, { "id": "quickstart#1-start-the-gateway", "kind": "section", "title": "Quickstart", "heading": "1. Start the Gateway", "group": "Operations", "url": "/docs/quickstart#1-start-the-gateway", "summary": "The gateway starts as a local container configured with one default Turbopuffer store and a secret supplied through the environment, then exposes a health check on the local port.", "facts": [ { "kind": "code", "literal": "curl \"$LAYER_GATEWAY_URL/health\"", "chunkId": "quickstart#1-start-the-gateway" } ], "sources": [ { "chunkId": "quickstart#1-start-the-gateway", "url": "/docs/quickstart#1-start-the-gateway", "anchor": "1-start-the-gateway" } ], "mode": "agent-primary", "terms": [ "start", "gateway", "starts", "local", "container", "configured", "default", "turbopuffer", "store", "secret", "supplied", "through", "environment", "exposes", "health", "check", "port", "curl", "layer", "docker", "8080", "layersecretlocalapikey", "turbopufferapikey", "layerstorejson", "apiversion", "hevlayer", "v1alpha1", "kind", "vectorstore", "metadata", "name", "spec", "true", "endpoint", "https", "region", "east", "credential", "secretref", "inboundauth" ] }, { "id": "quickstart#2-initialize-the-namespace", "kind": "section", "title": "Quickstart", "heading": "2. Initialize the Namespace", "group": "Operations", "url": "/docs/quickstart#2-initialize-the-namespace", "summary": "Namespace initialization adds Layer's reserved shard metadata to existing rows through an idempotent, self-throttled backfill. Queries remain available while metadata reports progress toward readiness.", "facts": [ { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/init\" \\\n -H \"Authorization: Bearer $TURBOPUFFER_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"schema_version\": 1, \"shard_count\": 8}'", "chunkId": "quickstart#2-initialize-the-namespace" }, { "kind": "code", "literal": "init_state", "chunkId": "quickstart#2-initialize-the-namespace" }, { "kind": "code", "literal": "ready", "chunkId": "quickstart#2-initialize-the-namespace" }, { "kind": "code", "literal": "GET /v2/namespaces/$LAYER_NAMESPACE/metadata", "chunkId": "quickstart#2-initialize-the-namespace" } ], "sources": [ { "chunkId": "quickstart#2-initialize-the-namespace", "url": "/docs/quickstart#2-initialize-the-namespace", "anchor": "2-initialize-the-namespace" } ], "mode": "agent-primary", "terms": [ "initialize", "namespace", "initialization", "adds", "layer", "reserved", "shard", "metadata", "existing", "rows", "through", "idempotent", "self", "throttled", "backfill", "queries", "remain", "available", "while", "reports", "progress", "toward", "readiness", "curl", "post", "gateway", "namespaces", "init", "authorization", "bearer", "turbopuffer", "content", "type", "application", "json", "schema", "version", "count", "state", "ready" ] }, { "id": "quickstart#3-run-a-query", "kind": "section", "title": "Quickstart", "heading": "3. Run a Query", "group": "Operations", "url": "/docs/quickstart#3-run-a-query", "summary": "Applications can send Turbopuffer-compatible queries through the gateway with the same upstream bearer. Initialization then enables Layer's routed search and scatter-and-gather scan capabilities.", "facts": [ { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/query\" \\\n -H \"Authorization: Bearer $TURBOPUFFER_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"rank_by\": [\"title\", \"BM25\", \"wireless earbuds\"],\n \"top_k\": 10\n }'", "chunkId": "quickstart#3-run-a-query" } ], "sources": [ { "chunkId": "quickstart#3-run-a-query", "url": "/docs/quickstart#3-run-a-query", "anchor": "3-run-a-query" } ], "mode": "agent-primary", "terms": [ "query", "applications", "send", "turbopuffer", "compatible", "queries", "through", "gateway", "same", "upstream", "bearer", "initialization", "enables", "layer", "routed", "search", "scatter", "gather", "scan", "capabilities", "curl", "post", "namespaces", "namespace", "authorization", "content", "type", "application", "json", "rank", "title", "bm25", "wireless", "earbuds", "layergatewayurl", "layernamespace", "turbopufferapikey", "rankby", "topk", "routes" ] }, { "id": "roadmap", "kind": "section", "title": "Changelog", "heading": null, "group": "Overview", "url": "/docs/roadmap", "summary": "The roadmap summarizes capabilities already delivered and the remaining work toward later product milestones.", "facts": [ { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "roadmap" } ], "sources": [ { "chunkId": "roadmap", "url": "/docs/roadmap", "anchor": null } ], "mode": "agent-primary", "terms": [ "roadmap", "summarizes", "capabilities", "already", "delivered", "remaining", "work", "toward", "later", "product", "milestones", "featuregate", "astro", "shipped", "layer", "coming", "next" ] }, { "id": "roadmap#04", "kind": "section", "title": "Changelog", "heading": "0.4", "group": "Overview", "url": "/docs/roadmap#04", "summary": "This section marks the product's 0.4 roadmap milestone.", "facts": [ { "kind": "value", "literal": "0.4", "chunkId": "roadmap#04" } ], "sources": [ { "chunkId": "roadmap#04", "url": "/docs/roadmap#04", "anchor": "04" } ], "mode": "agent-primary", "terms": [ "section", "marks", "product", "roadmap", "milestone" ] }, { "id": "roadmap#api-hardening", "kind": "section", "title": "Changelog", "heading": "API hardening", "group": "Overview", "url": "/docs/roadmap#api-hardening", "summary": "API hardening focuses on finalizing declarative resources, preserving wire-compatible data operations, and settling consistent naming.", "facts": [], "sources": [ { "chunkId": "roadmap#api-hardening", "url": "/docs/roadmap#api-hardening", "anchor": "api-hardening" } ], "mode": "agent-primary", "terms": [ "hardening", "focuses", "finalizing", "declarative", "resources", "preserving", "wire", "compatible", "data", "operations", "settling", "consistent", "naming", "finalize", "crds", "pass", "through", "reads", "writes", "things" ] }, { "id": "roadmap#lifecycle-and-operability", "kind": "section", "title": "Changelog", "heading": "Lifecycle and operability", "group": "Overview", "url": "/docs/roadmap#lifecycle-and-operability", "summary": "Lifecycle and operability work spans autoscaling, document caching, snapshot history, coordinated deletion, deployment tooling, scoped keys, licensing, audit logs, warehouse sources, and production topology.", "facts": [ { "kind": "code", "literal": "ApiKey", "chunkId": "roadmap#lifecycle-and-operability" } ], "sources": [ { "chunkId": "roadmap#lifecycle-and-operability", "url": "/docs/roadmap#lifecycle-and-operability", "anchor": "lifecycle-and-operability" } ], "mode": "agent-primary", "terms": [ "lifecycle", "operability", "work", "spans", "autoscaling", "document", "caching", "snapshot", "history", "coordinated", "deletion", "deployment", "tooling", "scoped", "keys", "licensing", "audit", "logs", "warehouse", "sources", "production", "topology", "apikey", "compute", "pipelines", "udfs", "cache", "endpoint", "multi", "stage", "index", "delete", "helm", "terraform", "install", "scripts", "minted", "resources", "license", "validation" ] }, { "id": "roadmap#polish", "kind": "section", "title": "Changelog", "heading": "Polish", "group": "Overview", "url": "/docs/roadmap#polish", "summary": "The remaining polish before 1.0 centers on documentation plus user acceptance testing for cost and dashboard experiences.", "facts": [ { "kind": "value", "literal": "1.0", "chunkId": "roadmap#polish" } ], "sources": [ { "chunkId": "roadmap#polish", "url": "/docs/roadmap#polish", "anchor": "polish" } ], "mode": "agent-primary", "terms": [ "polish", "remaining", "before", "centers", "documentation", "plus", "user", "acceptance", "testing", "cost", "dashboard", "experiences", "stands", "between", "today" ] }, { "id": "roadmap#search", "kind": "section", "title": "Changelog", "heading": "Search", "group": "Overview", "url": "/docs/roadmap#search", "summary": "Search work covers stable reads, temporal selectors, readiness, snapshot facets, flexible scans, identifier lookup, hybrid fusion, automatic routing, agentic reranking, history, trends, and richer namespace metadata.", "facts": [ { "kind": "code", "literal": "as_of", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "between", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "fts", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "hybrid_text", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "ann", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "Auto", "chunkId": "roadmap#search" }, { "kind": "code", "literal": "Agent", "chunkId": "roadmap#search" } ], "sources": [ { "chunkId": "roadmap#search", "url": "/docs/roadmap#search", "anchor": "search" } ], "mode": "agent-primary", "terms": [ "search", "work", "covers", "stable", "reads", "temporal", "selectors", "readiness", "snapshot", "facets", "flexible", "scans", "identifier", "lookup", "hybrid", "fusion", "automatic", "routing", "agentic", "reranking", "history", "trends", "richer", "namespace", "metadata", "between", "text", "auto", "agent", "during", "heavy", "writes", "queries", "asof", "selector", "ready", "signal", "reports", "every", "indexed" ] }, { "id": "roadmap#surfaces", "kind": "section", "title": "Changelog", "heading": "Surfaces", "group": "Overview", "url": "/docs/roadmap#surfaces", "summary": "Product surfaces include an operational dashboard, a documentation site, and official clients for Python, Go, and TypeScript.", "facts": [], "sources": [ { "chunkId": "roadmap#surfaces", "url": "/docs/roadmap#surfaces", "anchor": "surfaces" } ], "mode": "agent-primary", "terms": [ "surfaces", "product", "include", "operational", "dashboard", "documentation", "site", "official", "clients", "python", "typescript", "management", "observability" ] }, { "id": "roadmap#up-next", "kind": "section", "title": "Changelog", "heading": "Up Next", "group": "Overview", "url": "/docs/roadmap#up-next", "summary": "Planned follow-up work includes additional vector-store backends, declarative typed ingestion and chunking, published performance benchmarks, and experiment variants of indexes.", "facts": [ { "kind": "code", "literal": "VectorStore", "chunkId": "roadmap#up-next" }, { "kind": "value", "literal": "e.g", "chunkId": "roadmap#up-next" } ], "sources": [ { "chunkId": "roadmap#up-next", "url": "/docs/roadmap#up-next", "anchor": "up-next" } ], "mode": "agent-primary", "terms": [ "next", "planned", "follow", "work", "includes", "additional", "vector", "store", "backends", "declarative", "typed", "ingestion", "chunking", "published", "performance", "benchmarks", "experiment", "variants", "indexes", "vectorstore", "more", "pipeline", "sources", "hugging", "face", "worker", "code", "pass", "through", "overhead", "variant" ] }, { "id": "tradeoffs", "kind": "section", "title": "Tradeoffs", "heading": null, "group": "Overview", "url": "/docs/tradeoffs", "summary": "Layer deliberately adds a network hop, stable-read planning, and per-request authorization checks to the query path. Turbopuffer-backed namespaces also consume extra index storage for time-based filtering and scatter-and-gather sharding, with only some planning behavior configurable per index.", "facts": [ { "kind": "flag", "literal": "--muted", "chunkId": "tradeoffs" }, { "kind": "flag", "literal": "--signal", "chunkId": "tradeoffs" } ], "sources": [ { "chunkId": "tradeoffs", "url": "/docs/tradeoffs", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "deliberately", "adds", "network", "stable", "read", "planning", "request", "authorization", "checks", "query", "path", "turbopuffer", "backed", "namespaces", "also", "consume", "extra", "index", "storage", "time", "based", "filtering", "scatter", "gather", "sharding", "only", "some", "behavior", "configurable", "muted", "signal", "current", "product", "posture", "cases", "trying", "cover", "makes", "design" ] } ], "edges": [] } ``` --- # Introduction Source: https://hevlayer.com/docs import Diagram from "../../components/docs/Diagram.astro"; import { layerMapDiagram } from "../../lib/diagrams"; Layer provides a set of drop-in enhancements to your favorite retrieval systems. One install gives you two products: a **retrieval gateway** you adopt without changing client code, and a **function runtime** that runs your own code across every row of your index. {layerMapDiagram} You run two server components in your own cluster: a Rust **gateway** and a Kubernetes **operator**. The **gateway** is a transparent proxy in front of turbopuffer. It extends native clients with [fetch](/docs/api/query#fetch), [scans](/docs/api/scans), [snapshots](/docs/api/snapshots), and operator-facing semantics around the cache, write path, and [pipelines](/docs/api/pipelines) — you swap in Layer's drop-in client and change nothing else. It also lets you scale your own compute over multi-stage pipelines, reason about the [state of your index](/docs/api/namespace-metadata), observe [clickstream](/docs/api/search-history), and track [cost](/docs/dashboard). The **function runtime** is one primitive for every per-row job over an index. Embedding, classification, tagging, and attribute migration are all the same thing: a stateless [UDF](/docs/kubernetes/function-crd) declared as a Kubernetes-native `Function`. The gateway discovers the work, leases it to worker pools, retries, and writes results back, with KEDA scaling each pool to zero between bursts. You write and declare the function, and Layer runs the worker fleet for you. You call the gateway four ways: the [Python client](/docs/api/introduction#install), the [Go client](/docs/api/introduction#install), the [TypeScript client](/docs/api/introduction#install), or the REST API directly — the clients are generated from the same OpenAPI spec, and every endpoint page shows them side by side. Layer also ships an optional GUI [dashboard](/docs/dashboard). The dashboard manages cluster configuration through CRDs; all other state is persisted in object storage (S3). No durable state lives in a Layer process, so the compute tier is stateless and fully elastic. Because indexing is bursty, especially GPU-bound work, our [Terraform](/docs/install#terraform) installs [Karpenter](https://karpenter.sh) as a cluster autoscaler to provision and scale the nodes Layer's compute runs on. The remaining backing services are the document cache, the indexing-state store, and the metrics store. Every component Layer runs alongside is open source: - **[Karpenter](https://karpenter.sh)** — cluster autoscaler that provisions and scales nodes for Layer's bursty, GPU-bound compute (Apache-2.0). - **[Aerospike](https://aerospike.com)** — ephemeral document cache (AGPL-3.0). - **[PostgreSQL](https://www.postgresql.org)** — indexing-state store for the pipeline and embed queue (PostgreSQL License). - **[VictoriaMetrics](https://victoriametrics.com)** — metrics store (Apache-2.0). To get started, see the [install guide](/docs/install). For more technical detail, see [Concepts](/docs/concepts), [Guarantees](/docs/guarantees), and [Tradeoffs](/docs/tradeoffs). --- # Concepts Source: https://hevlayer.com/docs/concepts import Callout from "../../components/docs/Callout.astro"; ## Control loops Layer uses a control loop as a core primitive for managing your indexes. It reconciles index state against metrics emitted by the search system, which is how Layer applies row-level transformations ([UDFs](/docs/kubernetes/function-crd)) and keeps an index's stable view current. Related: [UDFs](/docs/kubernetes/function-crd), [snapshots](/docs/api/snapshots), stable watermark. ## Kubernetes autoscaling Because Layer is stateless, you can autoscale every tier independently. Karpenter handles node-level scaling, and KEDA scales pods against signals from an embedded PostgreSQL queue. The data in that queue is used for scaling decisions only — it carries no non-recoverable system state. ## Gateway enhancements Where helpful, the gateway extends your search system with common query patterns and filtering primitives. Layer's enhancements use reserved `_hevlayer_*` attributes; changing the schema on those attributes breaks Layer's guarantees but should degrade gracefully. All functionality is exposed through one API surface, the [Python, Go, or TypeScript client, or plain REST](/docs/api/introduction#install), so applications can route every call through the gateway. Layer works best when traffic flows through it consistently, even for requests that need no extra behavior. ## Scatter/gather Layer can partition a single namespace into hash buckets, called shards, by assigning each row a reserved `_hevlayer_shard` attribute (xxh64 of its id, modulo the shard count). The gateway then scatters a query to every bucket in parallel, one `_hevlayer_shard`-filtered query per shard, and gathers the results: it merges and re-ranks the combined rows down to your requested `top_k` before returning them. Sharding stays invisible to the client — you issue one query and get one ranked result set. The same scatter/gather path backs [scans](/docs/api/scans) (filter, full-text, and radius) and [UDF](/docs/kubernetes/function-crd) discovery scans. For an existing turbopuffer namespace adopted by Layer, initialize sharding with `POST /v2/namespaces/{namespace}/init` and a `shard_count`. The gateway writes a reserved namespace marker, stamps new writes immediately, and runs an embedded scan-and-patch backfill for rows that do not yet have `_hevlayer_shard`. Scatter/gather activates only after namespace metadata reports `layer.shard_lag_rows: 0`; until then queries and scans use the single-namespace path so unstamped rows are not missed. Run `layer init --shards N` to create the namespace shard marker, start the backfill, and watch `shard_lag_rows` drain until scatter/gather activates. ## Document cache The Layer document cache does two jobs. Document [reads](/docs/api/query#fetch) are served pull-through: the gateway checks the cache first, and on a miss reads through to turbopuffer (or S3 for snapshots), returns the row, and backfills the cache best-effort. [Pipeline](/docs/api/pipelines) chunk handoff uses the same store as the queue between CPU and GPU workers. Neither job makes it a hard dependency: document reads fall through to origin if the cache is unavailable, and chunk reads fall back to S3 backing (see [Failure modes](/docs/failure-modes)). One logical cache serves every path, with different uses (document fetch, pipeline chunks, snapshot field-values) separated into dedicated cache sets. ## Glossary | Concept | Current meaning | | --- | --- | | [Namespace](/docs/api/introduction) | A turbopuffer namespace addressed through `/v2/namespaces/{namespace}`. | | Document | A row id plus attributes, and optionally a vector when writing/searching. | | Document cache | Layer-managed hot records keyed by namespace and document id, plus cache sets for pipeline chunks and snapshots. | | Stable watermark | Epoch-ms cut tracked by the consistency watcher when turbopuffer reports up-to-date, or when a backing store without an index watermark settles its `row_count` across consecutive polls. | | Ready signal | Whether a namespace is fully indexed: `indexed` / `index_lag_rows` on [namespace metadata](/docs/api/namespace-metadata), reconciled from the latest snapshot when every row's vector is indexed. | | [Pipeline](/docs/api/pipelines) | A PostgreSQL-backed state machine for CPU extraction and GPU embedding work. | | [Snapshot](/docs/api/snapshots) | A content-addressed S3 facet histogram written after a namespace is observed stable. | | Facet listing | The distinct values for a field, precomputed in snapshots as `fields[].values[].v` or computed on demand by a values scan. | | Facet count | The document count for a facet value, returned as `fields[].values[].n` in snapshots and `values[].n` in values scan results. | | [Scan](/docs/api/scans) | On-demand row selection by filter, full-text (`fts`), or radius (`ann`) that returns matching IDs or field values asynchronously, or a row count synchronously. | | [UDF](/docs/kubernetes/function-crd) | A stateless worker the gateway coordinates over existing rows to enrich, fan out, or re-upsert data. | | Gateway | The Rust proxy fronting turbopuffer that serves the compatible API plus cache, scans, snapshots, pipelines, and the UDF runtime. | | [Operator](/docs/kubernetes/operator) | The Kubernetes operator that reconciles Layer's CRDs — functions, pipelines, scaling, and cluster config. | | Shard | A hash bucket within a single namespace. Each row carries a reserved `_hevlayer_shard` value (xxh64 of its id, modulo the shard count) so the gateway can scatter/gather a query across buckets. | | Leg | One subquery in a [hybrid text](/docs/api/query#hybrid-text-fusion) expansion: the full-input BM25 leg or one per-token fuzzy leg. Every leg of a query reads the same stable watermark cut. | | RRF | Reciprocal rank fusion — turbopuffer-native re-ranking (`rerank_by: ["RRF", ...]`) that merges legs into one list. Layer delegates all fusion math upstream. | | Tokenizer policy | The documented transform from a `HybridText` input to query tokens: UAX #29 word boundaries and lowercasing via turbopuffer's open-source `alyze` tokenizer (the production `word_v4` code), then drop tokens under 2 characters, dedupe, cap at 15. | | Route | The retrieval strategy the [query router](/docs/api/query#query-routing) picks for an `Auto` query (`hybrid_text`, `semantic`, or `fused`), chosen from the shape of the input text alone. Vector availability gates execution, not the choice. | | Routing policy | The deterministic, versioned decision function behind `Auto`. The version travels in the `routing` echo block and search history so threshold changes are visible. | | Deferral | The response to a vectorless `Auto` query routed `semantic` or `fused`: the routing decision with `executed: false` and no rows. The application embeds and re-issues with the route forced. | | CRD | Custom Resource Definition: the Kubernetes-native resources the operator reconciles — [functions](/docs/kubernetes/function-crd), [pipelines](/docs/kubernetes/pipeline-crd), [scaling](/docs/kubernetes/scaling-crd), and [indexes](/docs/kubernetes/index-crd). | | PromQL | The Prometheus query language. The gateway proxies it to the embedded VictoriaMetrics so you can query metrics without a separate scraper. | --- # Document model Source: https://hevlayer.com/docs/document-model import StoreSwitch from "../../components/docs/StoreSwitch.astro"; import FeatureGate from "../../components/docs/FeatureGate.astro"; Layer reserves the `_hevlayer_*` attribute prefix for its own bookkeeping. **These attributes are read-only.** The gateway stamps and maintains them; your writes and [UDF](/docs/kubernetes/function-crd) completion patches must not set or change them. The gateway rejects or overwrites any `_hevlayer_*` value you send, and editing one directly breaks Layer's guarantees. The reserved set depends on the engine backing the namespace.
| Attribute | Type | Purpose | | --- | --- | --- | | `_hevlayer_upserted_at` | integer (epoch ms) | Server-stamped on every write. The watermark Layer's [stable reads](/docs/api/query#stable-reads) are taken against. | | `_hevlayer_shard` | integer | Hash bucket assigned at write time (`xxh64(id) % shard_count`), present only on sharded namespaces. Lets the gateway [scatter/gather](/docs/concepts#scattergather) a query across the shards of one namespace. | | `_hevlayer_udf__v` | string | Function completion marker. The gateway stamps the Function's `spec.version` here when a worker completes a row. Hyphens in the Function id are normalized to underscores. | | `_hevlayer_udf__stale_after` | integer or null | Function invalidation marker. Discovery reclaims rows once this epoch-ms timestamp expires; completion clears the marker. |
The `_hevlayer_` prefix also namespaces internal cache sets (snapshot field-values and search-history clickstream), but those are cache keys, not part of your document schema. --- # No Guarantees Source: https://hevlayer.com/docs/guarantees import Callout from "../../components/docs/Callout.astro"; Layer can't offer guarantees. We try our best to provide secure, hands-off infrastructure that you are ultimately responsible for. While we can't offer guarantees, we make a set of promises in how we design, secure, and distribute our software that we believe make it easy to use and will stand the test of time. This page covers the specific status of those promises. ## Commitments - Your history is backed up to S3. Search history and namespace snapshots are written to the S3 bucket you specify. The format of this data may change. - Hot data served from cache. Customer document and chunk data is served from Layer's local document cache for price/performance. We try not to stray from this pattern, though some use cases may justify a smaller in-memory document cache. - This documentation is accurate and up to date. When it isn't, that's a bug in the software — report it. - Graceful degradation. We add graceful degradation support whenever possible — the gateway degrades rather than failing hard. The per-scenario behavior and recovery signals live in the [failure-mode runbook](/docs/failure-modes). - Client compatibility. We will (almost) always stay client-compatible with the search systems we front. Where we diverge, it's a feature making an explicit tradeoff we believe is an improvement. - One consistency cut per query. When the gateway expands a query into multiple legs ([hybrid text fusion](/docs/api/query#hybrid-text-fusion), [scatter/gather](/docs/concepts#scattergather)), every leg is filtered at the same stable watermark, injected from a single read. Legs never see different cuts. Layer was developed by a [single person](https://hevmind.com/about) orchestrating agentic coding tools, leveraging open source and building automation. Not a single line of code was hand-written. That said, it was made with ❤️ by a human as much as it is built by AI. --- # Tradeoffs Source: https://hevlayer.com/docs/tradeoffs Layer makes a set of design tradeoffs we believe improve functionality of your search system. This page makes those tradeoffs explicit. As this list grows, we will offer configuration where possible to allow users to configure their preference. Layer adds latency to the query path in the following ways. - An additional network hop (not configurable). - A query plan that allows for [stable reads](/docs/api/query#stable-reads) during heavy writes ([index configurable](/docs/kubernetes/index-crd)). - The same query plan also checks [RBAC entitlements](/docs/kubernetes/apikey-crd#entitlements) on every request (not configurable). On a turbopuffer-backed namespace, Layer also increases index storage requirements via. - A secondary indexing for filtering by upsert time (not configurable). - A secondary indexing used for scatter gather sharding (not configurable). --- # Limits Source: https://hevlayer.com/docs/limits Layer is limited by certain constraints of the underlying components we ship with. We will lift these as demand increases. - **Single-node document cache.** We enforce this for simplicity and also believe that a single large local drive offers enough storage for almost every dataset. - **~4,090 turbopuffer namespaces.** We use Aerospike sets for logical separation of data, which are limited by the Aerospike Community Edition AGPL license. - **~3 TB cache size.** Another limitation of the Aerospike license. - **10,000 distinct values per scan facet field.** Pre-computed snapshot scans cap each facet field's cardinality. If a field exceeds the cap, it is noted in `fields_skipped[]` rather than `fields[]`, so readers can treat every emitted field as complete. See [snapshots](/docs/api/snapshots). - **1,000,000 distinct values per values scan.** On-demand values scans accumulate their histogram in gateway memory. A job that crosses the cap completes with `truncated: true`: the cap applies after the full pass, keeping the top values by count — each with an exact count — and dropping the low-count tail. See [scans](/docs/api/scans#values-mode). ## No limits These have no enforced ceiling, but practical limits exist and will show up under load — see [failure modes](/docs/failure-modes) for how each surface degrades. - **CRD instances** (`Index`, `Function`, `Pipeline`, `Scaling`) — bounded only by the etcd and operator throughput of your Kubernetes cluster. - **Snapshot history per namespace** — durable in S3; bounded by `spec.snapshot.retention` when set, or by object storage cost under `retention: never`. - **Search history retention** — accumulates indefinitely in S3; no automatic expiry. - **Clickstream event volume** — accumulates indefinitely in S3; no automatic expiry. - **UDF concurrency per function** — KEDA scales replicas to match queue depth, bounded by your cluster's capacity. - **Pipeline queue depth** — pipeline queues, including chunked document queues, store document IDs and chunk ID lists in S3 manifests and keep only segment state and counters in Postgres. - **Document size and attribute count** — bounded by turbopuffer and Aerospike record limits, not by Layer. --- # Agents Source: https://hevlayer.com/docs/agents import Callout from "../../components/docs/Callout.astro"; These docs are queryable from the command line. The same engine behind the `⌘K` search on this site ships as a CLI, so your coding agent can search, read, and cite the Layer docs directly — no scraping, no MCP server, no API key. The `layer` CLI also lets agents operate environments, indexes, pipelines, UDFs, and Function runs. The skill bodies below are plain `SKILL.md` files. Use your agent harness' native skill directory when it has one, or paste the same Markdown into `AGENTS.md` or the harness equivalent. ## 1. Install the CLIs ```sh go install github.com/hev/ask/cmd/ask@latest ``` The `ask` binary is self-contained; any agent harness that can run a shell command can use it. From a Layer checkout, build the `layer` CLI when the agent should operate Layer environments instead of only searching docs: ```sh go build -o layer ./apps/layer-cli ``` ## 2. Add the docs skill Set `AGENT_SKILL_HOME` to your harness's skill directory, such as `~/.codex/skills` for Codex or `~/.claude/skills` for Claude Code. ```sh AGENT_SKILL_HOME="${AGENT_SKILL_HOME:-${CODEX_HOME:-$HOME/.codex}/skills}" mkdir -p "$AGENT_SKILL_HOME/hevlayer-docs" cat > "$AGENT_SKILL_HOME/hevlayer-docs/SKILL.md" <<'EOF' --- name: hevlayer-docs description: >- Query the hev layer docs. Use when the user asks about Layer — the turbopuffer gateway, stable reads, the stable watermark, the document cache, warm jobs, scans (filter, full-text, and radius), snapshots, pipelines, UDFs, the Index/InfraRules/Pipeline/Function CRDs, compute pools, install via Terraform or Helm, failure modes, or the dashboard. --- # hev layer docs Answer Layer questions from the docs, not from memory. Every verb is a keyless read: ask --endpoint https://hevlayer.com/api/ask search "" ask --endpoint https://hevlayer.com/api/ask section get "" ask --endpoint https://hevlayer.com/api/ask overview ask --endpoint https://hevlayer.com/api/ask glossary get "" Start with `search`; fetch sections for detail; use `overview` when you need the full map. Section ids look like `api/query#stable-reads`. Cite sections in your answer as https://hevlayer.com plus the returned `url` field. If `ask` is missing, install it: `go install github.com/hev/ask/cmd/ask@latest` EOF ``` ## 3. Add the layer CLI skill Use this skill when an agent should inspect or operate Layer through the `layer` CLI. The skill keeps read-only inspection, docs lookup, and mutating operations separate. ```sh AGENT_SKILL_HOME="${AGENT_SKILL_HOME:-${CODEX_HOME:-$HOME/.codex}/skills}" mkdir -p "$AGENT_SKILL_HOME/hevlayer-layer-cli" cat > "$AGENT_SKILL_HOME/hevlayer-layer-cli/SKILL.md" <<'EOF' --- name: hevlayer-layer-cli description: >- Use the hevlayer layer CLI. Use when the user asks an agent to inspect Layer environments, query docs through layer ask, list or get indexes, pipelines, or UDFs, open the operations TUI, delete indexes, or run Function manifests with the layer CLI. --- # hevlayer layer CLI Use `layer` to operate hevlayer from the terminal. In a Layer checkout, prefer a repo-local binary: go build -o layer ./apps/layer-cli ./layer --help Use `./layer ...` for a repo-local binary and `layer ...` for one on `PATH`. Prefer `-o json` for agent parsing and do not print API keys. For docs questions, start with `layer ask` against the committed digest: layer ask grep "" layer ask cat "" layer ask tree layer ask glossary get "" For read-only operational inspection, prefer: layer -o json env ls layer -o json env show [NAME] layer -o json index list layer -o json index get NAME layer -o json pipeline list layer -o json pipeline get ID layer -o json udf list layer -o json udf get UDF_ID Only `layer run` needs Kubernetes access by default. It applies a Function CR, registers the UDF spec with the gateway, triggers discovery, and optionally watches until the queue drains. Confirm the target environment, gateway URL, kube context, and Kubernetes namespace before mutating state. Mutating commands include `layer env add`, `layer env use`, `layer env rm`, `layer index delete`, `layer run`, and `layer run --rm`. Resolve configuration in this order: explicit flags, `LAYER_*` or `HEVLAYER_*` environment variables, `--env` or `LAYER_ENV`, the active `~/.hevlayer/config.toml` environment, then the built-in base URL. EOF ``` ## 4. Ask ```sh ask --endpoint https://hevlayer.com/api/ask search "cache is down" ``` ```json { "results": [ { "title": "Concepts", "heading": "Document cache", "url": "/docs/concepts#document-cache", "group": "Overview", "snippet": "The document cache does two jobs: pull-through document reads..." } ] } ``` From here your agent typically runs `section get` on the winning id and answers with the citation. ## The verbs | Verb | Returns | | --- | --- | | `overview` | Orientation context plus the full section map with stable ids | | `search ""` | Ranked sections with snippets and deep links | | `section get ""` | One section: summary, exact identifiers, source URL | | `glossary get ""` | A product term resolved through its aliases (`watermark` → stable watermark) | ## Why answers stay grounded Search runs over a committed, reviewable digest of these docs — the same corpus, heading by heading, that renders on this site. Every anchor in it is verified against the rendered pages in CI, so a cited deep link like [/docs/api/query#stable-reads](/docs/api/query#stable-reads) always resolves. When the docs change, the digest is rebuilt and recommitted with them. Every verb above is a read against the public docs. Nothing to sign up for, nothing to configure beyond the endpoint URL. The docs are also available as plain text for direct ingestion: [/llms.txt](/llms.txt) (index) and [/llms-full.txt](/llms-full.txt) (full corpus). The CLI is the better path for agents that can run commands — it ranks, resolves aliases, and costs a fraction of the tokens. --- # Demos Source: https://hevlayer.com/docs/demos Every demo below is a live app built on Layer that reimplements nothing. Each composes shipped gateway features — [routing](/docs/api/query#query-routing), [hybrid text fusion](/docs/api/query#hybrid-text-fusion), fuzzy matching, [pipelines](/docs/api/pipelines), [snapshots](/docs/api/snapshots), and the [function runtime](/docs/kubernetes/function-crd) — over a different corpus, and makes the gateway's behavior legible in the UI. They are also the fastest way to see what the gateway does without standing up a cluster. | Demo | What it shows | Corpus | | --- | --- | --- | | [shelf](https://shelf.hevlayer.com) | The query router, made legible | Books | | [chart](https://chart.hevlayer.com) | Query routing on clinical search, with a number | PMC-Patients case reports | | [hybrid-text](https://hybrid-text.hevlayer.com) | Hybrid text fusion, proven with qrels | BEIR/SciFact abstracts | | [shop](https://shop.hevlayer.com) | Everything together — an end-to-end app | Amazon product catalog | ## shelf — book search that shows its routing **Live:** [shelf.hevlayer.com](https://shelf.hevlayer.com) · **Source:** [github.com/hev/shelf](https://github.com/hev/shelf) One search box, three routes. Type an author, a title, or a vibe; the gateway's `Auto` rank expression picks keyword (`hybrid_text`), `semantic`, or a `fused` blend from the shape of the query, and shelf renders that decision as a badge with the reason. The routing policy keys on token count, so the canned chips visibly change route as the query gets longer. This is the text-native routing showcase: it makes the [query router](/docs/api/query#query-routing) decision the hero, not a footnote. Built on the [query router](/docs/api/query#query-routing) (`Auto`), [hybrid text fusion](/docs/api/query#hybrid-text-fusion), and fuzzy matching. ## chart — clinical patient-notes search that shows its routing **Live:** [chart.hevlayer.com](https://chart.hevlayer.com) The same routing hero on the corpus with the sharpest bimodal query distribution there is: clinicians search both by exact token (`metformin 500mg`, `CABG`, `aspirn`) and by clinical picture (`elderly woman with progressive dyspnea and bilateral lower-extremity edema`). chart is the first Layer demo with real relevance judgments — PMC-Patients ReCDS qrels — so the routing and hybrid claims are measured, not asserted. Behind the search box, an open-weight Gemma cascade (vLLM, scale-to-zero on the GPU pool) reads each note once and extracts clinical events and facet labels: the [function runtime](/docs/kubernetes/function-crd) showcase. The corpus is published, de-identified case reports (PMC-Patients, CC-BY-NC-SA). It is a search demo — not raw EHR, and not clinical advice. Built on the [query router](/docs/api/query#query-routing), [hybrid text fusion](/docs/api/query#hybrid-text-fusion) with fuzzy matching, [pipelines](/docs/api/pipelines), the [function runtime](/docs/kubernetes/function-crd), and [snapshots](/docs/api/snapshots). ## hybrid-text — hybrid text fusion over SciFact **Live:** [hybrid-text.hevlayer.com](https://hybrid-text.hevlayer.com) · **Source:** [github.com/hev/hybrid-text-fusion-demo](https://github.com/hev/hybrid-text-fusion-demo) The eval-shaped sibling of the routing demos, over ~5,000 scientific abstracts from BEIR/SciFact. One query string fans out into a full-input BM25 leg plus one fuzzy leg per token, fused by reciprocal rank fusion — so results survive typos and morphological variants without losing BM25's signal. It is purely lexical: no embeddings, no GPU, no vector index. SciFact ships qrels, so the UI flags known-relevant abstracts and the demo scores nDCG@10 / recall@10; every search also shows its gateway round-trip time and a fusion inspector (tokens, legs, RRF constant). Built on [hybrid text fusion](/docs/api/query#hybrid-text-fusion) and fuzzy matching. ## shop — semantic shopping, everything together **Live:** [shop.hevlayer.com](https://shop.hevlayer.com) (formerly `hev-shop.com`, which redirects) · **Source:** [github.com/hev/shop](https://github.com/hev/shop) The end-to-end application workload: an indexing pipeline, semantic search, recommendations, facets, and observability in one app. shop embeds product images with CLIP ViT-L/14 and writes one vector per product through Layer [pipelines](/docs/api/pipelines) into turbopuffer; the storefront serves image-native semantic search, [`nearest_to_id`](/docs/api/query#query-by-id) recommendations, facet exploration from [namespace snapshots](/docs/api/snapshots), and Layer freshness signals. KEDA scales workers from pipeline metrics and Karpenter scales nodes next to the workload that creates the demand. Where shelf is the text-native routing showcase, shop is the image-native one — and the demo that exercises the most of Layer at once. Built on [pipelines](/docs/api/pipelines), the [write path](/docs/api/write), [query](/docs/api/query#query-by-id) (`nearest_to_id`), [snapshots](/docs/api/snapshots), [search history](/docs/api/search-history), and [autoscaling](/docs/kubernetes/scaling-crd). --- # Changelog Source: https://hevlayer.com/docs/roadmap import FeatureGate from "../../components/docs/FeatureGate.astro"; ## Polish What stands between today and the 1.0 cut: - 📚 Polish documentation - 💸 Cost UAT - 🪟 Dashboard UAT ## Up Next Planned next: - 🧭 More `VectorStore` backends - 🤗 Declarative ingestion — typed pipeline sources (e.g. Hugging Face) and chunking, no worker code - 📊 Performance benchmarks — published pass-through overhead - 🧪 A/B variant indexes ## 0.4 ### API hardening - 🧩 Finalize CRDs - 🚆 Wire-compatible pass-through reads and writes - 🏷️ Naming things ### Lifecycle and operability - 🎚️ [Autoscaling compute](/docs/kubernetes/scaling-crd) for pipelines and UDFs - 🗄️ [Document cache endpoint](/docs/api/query#fetch) for multi-stage pipelines - 📸 [Index snapshot history](/docs/api/snapshots) - 🧨 Coordinated delete - ⛵ [Helm and Terraform install](/docs/install) scripts - 🔐 [Scoped API keys](/docs/api/keys) — minted [`ApiKey` resources](/docs/kubernetes/apikey-crd) - 🔑 [License key validation](/docs/licensing) - 🧾 [Key audit logs](/docs/api/keys) — lifecycle events to S3- 🏭 [Warehouse CRD](/docs/kubernetes/warehouse-crd) — declared Snowflake and Hugging Face sources - 🏗️ Production cluster cutover — lean topology live in prod ### Surfaces - 🪟 [Dashboard MVP](/docs/dashboard) — CRD management and observability - 📚 Documentation site - 🧰 Official Python, Go, and TypeScript clients ### Search - 🎯 [Stable reads](/docs/api/query#stable-reads) during heavy writes - 🕰️ [Temporal queries](/docs/api/query) — `as_of` / `between` selector on reads - 🚦 [Ready signal](/docs/api/namespace-metadata) — namespace reports when every row is indexed - 📜 Precomputed facet listings in [snapshots](/docs/api/snapshots) - 🪙 Precomputed facet counts in [snapshots](/docs/api/snapshots) - 🪃 [Scans](/docs/api/scans) — row selection by filter, `fts`, `hybrid_text`, or `ann` - 🆔 Search by id via document-cached vector - 🪢 [Hybrid text fusion](/docs/api/query#hybrid-text-fusion) — fuzzy + BM25 fused by RRF - 🧭 [Query routing](/docs/api/query#query-routing) — `Auto` picks the search mode - 🤖 [Agentic search](/docs/api/agents) — an [`Agent`](/docs/kubernetes/agent-crd) runs a budgeted plan → recall → relevance-score loop above `Auto` - 📰 [Search history](/docs/api/search-history) saved to S3 - 🔥 Trending searches — reduce-shaped UDFs over search history - 🗂️ Enhanced [namespace metadata](/docs/api/namespace-metadata) --- # FAQ Source: https://hevlayer.com/docs/faq This page answers the questions the rest of the docs don't: licensing, pricing, trials, and where the project is headed. ## What is the licensing for hev layer? The standalone gateway is source-available under the Business Source License 1.1 in [hev/layer](https://github.com/hev/layer). It is free to self-host at any scale and converts to Apache-2.0 on the change date in its `LICENSE`. The operator, function runtime, and dashboard require a commercial license. Licensed installs use signed license keys for trial and commercial access. The key is supplied to Helm as `license.token` or through a referenced Kubernetes Secret. See [licensing](/docs/licensing) for the install and lifecycle details. ## How much will it cost? Layer is licensed per operator deployment: one license per operator install, so a production, staging, and DR cluster each carry their own. Replicas within an install do not count. Pricing is not final for the design-partner cut. Start with a trial license; commercial terms are handled directly with each design partner. ## How do I start a trial? Use the [trial signup](/#start-trial). Submit your work email and hev layer emails a signed trial key plus the current install instructions. ## How do I know whether my license is healthy? Call [`GET /v2/license`](/docs/licensing#license-states) on your gateway. The gateway reports `licensed`, `grace`, or `floor` from the key configured in the install. Operator and dashboard license surfaces use the same state model when their enforcement surfaces ship. ## Who built hev layer? [Adam Hevenor](https://hevmind.com/about). hev layer is a [hev mind](https://hevmind.com) product. --- # Quickstart Source: https://hevlayer.com/docs/quickstart Run the community gateway in front of your existing turbopuffer account in three steps. No license key or signup needed — your turbopuffer API key is the gateway bearer token, and your data stays where it is. You need Docker, `curl`, and a turbopuffer namespace with rows in it: ```sh export TURBOPUFFER_API_KEY="tpuf_..." export LAYER_NAMESPACE="products" export LAYER_GATEWAY_URL="http://localhost:8080" ``` ## 1. Start the Gateway ```sh docker run --rm -p 8080:8080 \ -e PORT=8080 \ -e LAYER_SECRET_LOCAL_API_KEY="$TURBOPUFFER_API_KEY" \ -e LAYER_STORE_JSON='apiVersion: hevlayer.com/v1alpha1 kind: VectorStore metadata: name: local spec: kind: turbopuffer default: true endpoint: url: https://api.turbopuffer.com region: aws-us-east-1 credential: secretRef: name: local key: api-key inboundAuth: mode: deriveFromStore' \ hevlayer/layer-gateway ``` Check it in another shell: ```sh curl "$LAYER_GATEWAY_URL/health" ``` ## 2. Initialize the Namespace ```sh curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/init" \ -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \ -H "Content-Type: application/json" \ -d '{"schema_version": 1, "shard_count": 8}' ``` Init stamps existing rows with Layer-reserved shard metadata — it is idempotent and self-throttled, and queries keep working while the backfill drains. Watch `init_state` reach `ready` at `GET /v2/namespaces/$LAYER_NAMESPACE/metadata`. ## 3. Run a Query ```sh curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/$LAYER_NAMESPACE/query" \ -H "Authorization: Bearer $TURBOPUFFER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rank_by": ["title", "BM25", "wireless earbuds"], "top_k": 10 }' ``` The same turbopuffer-compatible routes your application already calls now go through the gateway. From here: - [Query & Fetch](/docs/api/query) — routing, hybrid text fusion, rank expressions - [Scans](/docs/api/scans) — scatter/gather counts across the shards you just initialized - [Install](/docs/install) — the Helm chart for a real cluster --- # Install Source: https://hevlayer.com/docs/install import Callout from "../../components/docs/Callout.astro"; A hev layer install has two stages. **Terraform** provisions the required AWS resources: IAM, S3, ECR, networking, cost-read roles, and, for the recommended path, a fresh EKS cluster. **Helm** installs the gateway, operator, and document cache into that cluster and wires them to the AWS resources Terraform produced. You can skip Terraform if you already have the AWS resources hev layer needs. At minimum, provide an S3 bucket and gateway IRSA role for snapshots and history. For the full feature set, also provide gateway cost-read IAM, image registry locations, and cluster-level components equivalent to the Terraform outputs. ## One-script install The fast path runs both stages from one script. It provisions the opinionated AWS footprint — VPC, EKS, IAM/IRSA, S3, ECR — and installs the Helm release wired to those outputs, from a single upstream store credential: ```sh export TURBOPUFFER_API_KEY="tpuf_..." curl -fsSL https://hevlayer.com/install.sh | bash ``` Prerequisites: `aws` (with credentials configured), `terraform`, `helm`, `kubectl`, `jq`, and `openssl`, plus the Layer source checkout or onboarding artifact (set `LAYER_SRC` to it). Useful knobs: `AWS_REGION` (default `us-east-1`), `CLUSTER_NAME` (default `layer`), `NAMESPACE` (default `layer`), `HELM_RELEASE` (default `layer`), `LAYER_VERSION` (default `latest`), and `LICENSE_TOKEN` for trial and commercial installs. The dashboard user defaults to `admin`; set `DASHBOARD_USER` and `DASHBOARD_PASSWORD` to choose its Basic Auth credentials, or the script generates and prints a password. Set `SKIP_TERRAFORM=1` to reuse existing Terraform outputs and rerun the cluster components and Helm release without another apply. On that path, the saved cluster name and namespace are authoritative. The rest of this page is the reference for what the script sets up and the bring-your-own-cluster alternative. ## Install shape An install is one Helm release per environment with one S3 bucket for snapshot and history data. The chart renders a default [`VectorStore`](/docs/kubernetes/vectorstore-crd) from the credential you provide; an install can define additional `VectorStore` resources, each with its own upstream credential and inbound auth policy, and route namespaces between them with `Index.spec.backend.storeRef`. Scoped gateway-only bearer keys are available through the `keys` inbound auth mode described below. ## Terraform The Terraform configuration in `infra/terraform/` provisions the AWS resources that the gateway and operator need. It is opinionated about the resources hev layer needs to behave correctly and conservative about resources around it. Route53 hosted zones and ACM certificates are opt-in; most installs bring existing DNS and TLS. ### What it sets up | Resource | Purpose | | --- | --- | | S3 bucket | Durable storage for namespace snapshots, search history, and clickstream events. | | IAM roles + IRSA policies | Gateway S3 and Cost Explorer access, plus worker/operator AWS access. | | ECR repositories | Registry space for customer-built function and pipeline worker images. Layer-owned gateway, operator, and dashboard images are pulled from Docker Hub. | | EKS + VPC + node pools | Recommended fresh-cluster runtime for design partners. | | Route53 + ACM | Optional DNS zones, records, and TLS certificates when `manage_public_dns=true`. | ### Cluster: recommended Design-partner installs should use a fresh EKS cluster unless there is a specific reason to bind hev layer to an existing one. The cluster path provisions: - a VPC with the subnets and endpoints hev layer expects - an EKS control plane and one always-on `system` node group, defaulting to an `i4i.large` so the serving path and document cache share local instance storage - public worker subnets by default, with no NAT Gateway in the fresh cluster path - Karpenter for scale-from-zero `worker-cpu` and `worker-gpu` indexing capacity - the AWS Load Balancer Controller for ingress - EFS for shared persistent volumes If you already operate an EKS cluster, you can disable the cluster modules and point hev layer at the existing cluster. You are still responsible for the functional prerequisites: an S3 bucket for snapshots/history, gateway IRSA that can read/write that bucket and call AWS Cost Explorer for tag-scoped cost reads, Docker Hub pull access for Layer-owned images, registry access for worker images, Karpenter or equivalent node autoscaling for workers, and the AWS Load Balancer Controller if you use public ingress. For design partners, deploy hev layer to a fresh cluster. The baseline is one always-on i4i node for the gateway, dashboard, control loops, and document cache. CPU and GPU indexing workers scale from zero, so embedding and extraction cost follows indexing duty cycle instead of becoming a standing line item. The fresh path also avoids a NAT Gateway: workers run in public subnets, so the large data volumes that flow during indexing skip NAT's per-GB processing charge. Existing clusters typically route worker egress through NAT already, which turns every pipeline run into a metered transfer. ### Cost notes The Terraform is designed to deploy a cost-efficient AWS footprint with autoscaling for on-demand indexing work. At rest, the fixed costs are mostly EKS, one i4i `system` node, the shared ALB, and small storage lines. On current us-east-1 on-demand pricing, that baseline is roughly the low hundreds of dollars per month before variable traffic, object storage, and upstream vector-store usage. Indexing bursts scale CPU or GPU worker nodes up through Karpenter and back down when queues drain. If you switch workers to private subnets, enabling NAT adds a standing hourly and egress cost. Heavier search use cases may need more read-side infrastructure: additional gateway replicas, larger always-on nodes, or a dedicated document-cache pool for steady cache pressure. Contact hev layer for help sizing read-heavy deployments. ### Outputs Terraform emits the values the Helm chart needs to install: the S3 bucket name, gateway IRSA role ARN, and cluster metadata. Runtime images are pulled from Docker Hub for the Layer-owned gateway, operator, and dashboard containers. Pass these into the Helm values file described below. The Terraform provider tags managed resources with `Project=hevlayer`; activate that tag as a cost-allocation tag in AWS Billing so the gateway can scope Cost Explorer reads to the Layer stack. ## Helm The Helm chart at `infra/helm/layer/` installs the gateway, operator, and document cache into a cluster that already has the AWS resources from [Terraform](#terraform) or equivalent resources you manage. ### Local gateway development `docker compose` starts the gateway's local dependencies, not a replacement control plane. The gateway still resolves [`VectorStore`](/docs/kubernetes/vectorstore-crd) and [`Index`](/docs/kubernetes/index-crd) resources from Kubernetes at startup, so a compose-based gateway run needs a current kube context with Layer CRDs installed and the matching `VectorStore`, `Index`, and Secret objects applied. For a local search backend running on the compose network, use a local-only `VectorStore.endpoint.url` that the gateway container can reach; cluster Service DNS names only work inside Kubernetes. ### Required values Most of the chart is opinionated defaults. In a typical install the credential you bring from outside the cluster becomes the default `VectorStore` credential. | Value | Required | Notes | | --- | --- | --- | | `vectorStore.credential.apiKey` | yes | Upstream store credential. With the default `deriveFromStore` auth mode, clients also send this as the gateway bearer key. | | `vectorStore.endpoint.url` | yes | Upstream store API base URL. Defaults to turbopuffer's AWS us-east-1 endpoint. | | `vectorStore.endpoint.region` | yes | Region label for the rendered `VectorStore`. | | `vectorStore.inboundAuth.mode` | no | `deriveFromStore`, `keys`, or `open`. Defaults to `deriveFromStore`. | | `vectorStore.inboundAuth.keys` | for `keys` mode | Gateway-only bearer keys with `read`, `write`, and `admin` scopes. | | `search.enabled` | no | Installs the Layer-operated `search` backend in-cluster and, when `vectorStore.kind=search` and `vectorStore.endpoint.url` is blank, points the default `VectorStore` at that Service. | | `search.image` | for `search.enabled` | Container image for the `search` backend, distributed separately from the Layer repo images. The chart rejects `ghcr.io/hev/*`. | | `gateway.image` | yes | Gateway image URL. Customer installs pull the pro image from Docker Hub, `hevlayer/layer-gateway-pro:`. | | `operator.image` | for `operator.enabled` | Operator image URL. Customer installs pull `hevlayer/layer-operator:` from Docker Hub. | | `dashboard.image` | for `dashboard.enabled` | Dashboard image URL. Customer installs pull `hevlayer/layer-dashboard:` from Docker Hub. | | `license.token` | trial/commercial installs | Signed hev layer license key from the trial or commercial license email. The chart writes it to a Kubernetes Secret and surfaces it to the gateway. | | `license.existingSecret` / `license.secretKey` | optional | Existing Secret name and key containing the license key, for clusters where secret material is managed outside Helm. | | `s3.bucket` | yes | S3 bucket Terraform created for snapshots and history. | | `serviceAccount.roleArn` | yes | IRSA role ARN that grants the gateway access to the S3 bucket and Cost Explorer. | | `dashboard.serviceAccount.name` | yes | Dashboard ServiceAccount name from Terraform output `layer_dashboard_service_account_name`. | | `dashboard.serviceAccount.roleArn` | yes | Dashboard IRSA role ARN from Terraform output `layer_dashboard_role_arn`; this renders the EKS role annotation on the dashboard ServiceAccount at first boot. | | `gateway.indexNamespace` | no | Namespace containing `Index` CRs. Blank follows `operator.discovery.indexNamespace`, then the Helm release namespace. | | `gateway.indexConfig.enabled` | no | Enables gateway reads of `Index` CR routing and policy such as `spec.backend.storeRef`, `spec.snapshot.facetFields`, and `spec.scan.threads`. | | `gateway.indexGc.enabled` | no | Enables namespace hard-delete cleanup of operator-discovered `Index` CRs. | | `gateway.consistency.stablePollIntervalMs` | no | Slow polling cadence for namespaces last observed stable. Defaults to `60000`; cold and updating namespaces keep the fast gateway default. | | `gateway.cost.tagKey` / `gateway.cost.tagValue` | no | Cost-allocation tag filter for AWS Cost Explorer. Defaults to `Project=hevlayer`. | | `ingress.host` | optional | Set when you want a public ingress; use your DNS/TLS or enable Terraform-managed Route53/ACM. | Most other Helm inputs are wiring between resources the install process already produced. The store API key is the credential hev layer cannot generate for you. The chart stores it in a Kubernetes Secret, points the default `VectorStore` at that Secret, and the gateway derives its default inbound bearer from the same key. After you [start a trial](/#start-trial), hev layer emails a signed license key. Set it as `license.token` or store it in an existing Secret referenced by `license.existingSecret` and `license.secretKey`. The gateway exposes local license health at [`/v2/license`](/docs/licensing#license-states), with `licensed`, `grace`, and `floor` states. ### Image Coordinates The customer pull path for the Layer-owned runtime images is Docker Hub: ```yaml gateway: image: hevlayer/layer-gateway-pro: operator: enabled: true image: hevlayer/layer-operator: dashboard: enabled: true image: hevlayer/layer-dashboard: ``` These pro images are public to pull, but licensed surfaces are only useful with a valid hevlayer license key installed through `license.token` or `license.existingSecret`. Without a valid key, the gateway, operator, and dashboard project the install to the license floor described in [Licensing](/docs/licensing#license-states). The in-cluster `search` backend image is distributed separately from the Layer repo images. Demo worker images are not part of the first Docker Hub release lane; build customer Function and Pipeline images into the registry your cluster already pulls from. ### Layer-Operated Search Set `search.enabled=true` to run the `search` backend beside the gateway. The chart uses the existing service account/IRSA, stores backend data under `s3:///search` by default, mounts a node-local object cache, adds Prometheus scrape annotations for the bundled vmsingle, and restricts backend ingress to Layer's own components (gateway, operator, and metrics scraper). The in-chart backend takes no credential of its own and is reachable only through that internal connection. For a default `kind: search` VectorStore, set `vectorStore.inboundAuth.mode` to `keys` or `open`; `deriveFromStore` is only valid when the upstream store has its own credential. ### Gateway auth modes The default `deriveFromStore` mode is the single-tenant BYOC path: ```yaml vectorStore: credential: apiKey: tpuf_... inboundAuth: mode: deriveFromStore ``` For an install that needs a gateway-only bearer, use `keys` mode. The chart renders `apiKey` values into the release Secret and references them from the `VectorStore`; omit `apiKey` when pointing at a pre-created Secret. ```yaml vectorStore: credential: apiKey: tpuf_... inboundAuth: mode: keys workerSecretKey: layer-inbound-worker-api-key keys: - name: worker scopes: [read, write, admin] apiKey: layer_worker_... secretRef: key: layer-inbound-worker-api-key ``` In `keys` mode, operator workers, KEDA, and the dashboard use `workerSecretName` / `workerSecretKey` as their gateway bearer. Blank `workerSecretName` uses the release Secret; blank `workerSecretKey` uses `layer-inbound-worker-api-key`. ### Run the install ```sh helm upgrade --install layer ./infra/helm/layer \ --namespace layer --create-namespace \ -f values.customer.yaml ``` The chart is not published to a public Helm repository — install from the source path or from the chart artifact provided during onboarding. ### What gets installed - `layer-gateway` — Rust gateway for turbopuffer-compatible routes, fetch, scans, snapshots, warm jobs, and pipeline state. - `layer-operator` — reconciler for VectorStore, Index, InfraRules, Pipeline, and Function CRDs documented in [Kubernetes](/docs/kubernetes/operator). - `layer-document-cache` — Aerospike-backed document cache, scale-to-zero by default, scheduled onto the always-on i4i system node in the baseline profile. - Optional Karpenter `NodePool` / `EC2NodeClass` resources for `worker-cpu` and `worker-gpu` indexing capacity when `workerKarpenter.enabled=true`. A dedicated `document-cache` pool is still available for larger installs by setting `documentCache.nodeRole=document-cache` and `documentCache.karpenter.enabled=true`. - Supporting resources: service accounts, IRSA bindings, ingress, and CRDs. ### Default InfraRules When `operator.infraRules.create=true`, Helm renders the cluster-scoped `InfraRules/default` object used by every Pipeline and Function `spec.scaling.pool` reference. If a workload omits `scaling.pool`, the operator maps `worker.computeClass: cpu` or `gpu` to the stock `cpu` or `gpu` pool. The default compute pools are: | Pool | Use | | --- | --- | | `cpu` | General CPU workers such as extraction, ingestion, and lightweight Functions. | | `cpu-large` | CPU workers that need local ephemeral-storage headroom for per-pod source caches. | | `gpu` | One-NVIDIA-GPU workers for embedding and model inference. | The stock pools select `layer.hev.dev/node-role=worker-cpu` or `worker-gpu`, matching the chart's `workerKarpenter` NodePools. Override `operator.infraRules.computePools` to tune resource requests, limits, node selectors, tolerations, GPU SKU hints, or per-workload replica ceilings for your cluster. See [InfraRules CRD](/docs/kubernetes/scaling-crd) for the full field shape. --- # Operator Overview Source: https://hevlayer.com/docs/kubernetes/operator `layer-operator` manages declarative state for your hev layer deployment. It serves a few crucial functions — monitoring for changes to your indexes and managing scaling. It does this through a set of abstractions known as [custom resource definitions (CRDs)](/docs/concepts#glossary). The gateway handles the read and write path; the operator handles everything that wants to be expressed as desired state in the cluster: which vector store the gateway fronts, which indexes exist, how worker pools scale, and which stateless functions run against which indexes. ## CRDs The operator reconciles five resource kinds, each documented on its own page: - [VectorStore CRD](/docs/kubernetes/vectorstore-crd) — the upstream store endpoint, credential reference, and gateway inbound auth policy. - [Index CRD](/docs/kubernetes/index-crd) — one resource per turbopuffer namespace the gateway should manage. - [InfraRules CRD](/docs/kubernetes/scaling-crd) — cluster-wide compute pools, document cache rules, and shared scaling policy. - [Pipeline CRD](/docs/kubernetes/pipeline-crd) — staged work that changes row count. - [Function CRD](/docs/kubernetes/function-crd) — stateless user-defined functions that read and write attributes on an index. ## Relationship to the gateway The gateway and the operator are decoupled. The operator reconciles declarative state; the gateway serves the read and write path. Neither sits in the other's hot path, so the gateway keeps serving even if the operator is restarted or lagging. The link between them is one-directional and read-only. For some features the gateway reads CRD status, such as which indexes exist and which worker pools are ready, to inform what it serves. It never writes to the CRDs; declarative state is authored by you and reconciled by the operator, and the gateway is only ever a reader of it. ## Scheduling and node pools The operator applies the compute pool chosen by each Pipeline and Function. A pool can set container resources, `nodeSelector`, and `tolerations`, so operators can pin CPU, storage-heavy CPU, and GPU work to the right node capacity. Helm installs `cpu`, `cpu-large`, and `gpu` pools by default. The stock pools select the chart-rendered Karpenter worker pools: `layer.hev.dev/node-role=worker-cpu` for CPU and `layer.hev.dev/node-role=worker-gpu` for GPU. The GPU pool also requests `nvidia.com/gpu: "1"` and carries the standard NVIDIA toleration. This is configured once on `InfraRules/default`, not per workload — see [InfraRules](/docs/kubernetes/scaling-crd) for the compute-pool fields and how Pipelines and Functions choose a pool. --- # VectorStore CRD Source: https://hevlayer.com/docs/kubernetes/vectorstore-crd import FeatureGate from "../../../components/docs/FeatureGate.astro"; A `VectorStore` is the gateway's upstream connection. It names the store kind, endpoint, credential Secret, and the inbound auth policy the gateway applies to client requests. An install may define more than one `VectorStore`; each `Index.spec.backend.storeRef` selects which store serves that upstream namespace. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: VectorStore metadata: name: turbopuffer-default namespace: layer spec: kind: turbopuffer default: true endpoint: url: https://aws-us-east-1.turbopuffer.com region: aws-us-east-1 turbopuffer: orgId: org_123 credential: secretRef: name: layer key: turbopuffer-api-key inboundAuth: mode: deriveFromStore ``` ## Standalone config **Why this exists:** the open [`layer` (CE)](https://github.com/hev/layer) runs standalone — Docker, Compose, or a bare binary — with no Kubernetes control plane available. Config-derived resolution gives those deployments the exact same `VectorStore` vocabulary as a cluster install: one schema, two entry points, so a standalone config file promotes to a CR (and back) without rewrites. Standalone and compose runs do not need Kubernetes to resolve `VectorStore`s. Set `LAYER_STORE_FILE` to a YAML or JSON file containing the same resource shape as the CR: ```yaml apiVersion: hevlayer.com/v1alpha1 kind: VectorStore metadata: name: turbopuffer-default spec: kind: turbopuffer default: true endpoint: url: https://api.turbopuffer.com region: aws-us-east-1 credential: secretRef: name: layer key: turbopuffer-api-key inboundAuth: mode: deriveFromStore ``` For this example, set `LAYER_SECRET_LAYER_TURBOPUFFER_API_KEY=tpuf_...` before starting the gateway. The env var name is `LAYER_SECRET_` plus the Secret name and key uppercased, with punctuation replaced by underscores. For more than one store, use a Kubernetes-style list: ```yaml apiVersion: v1 kind: List items: - apiVersion: hevlayer.com/v1alpha1 kind: VectorStore metadata: name: turbopuffer-default spec: kind: turbopuffer default: true endpoint: url: https://api.turbopuffer.com region: aws-us-east-1 credential: secretRef: name: layer key: turbopuffer-api-key inboundAuth: mode: deriveFromStore ``` The standalone file mirrors the CR schema. Kubernetes installs read `credential.secretRef` from the cluster; standalone runs resolve the same `secretRef` from env. Inline `LAYER_STORE_JSON` accepts the same resource shape for short-lived local runs. If neither variable is set, the gateway uses a single default turbopuffer store and derives inbound auth from the request bearer. ## Connection | Field | Purpose | | --- | --- | | `kind` | The backend engine. `turbopuffer` today. `pinecone` is reserved by the schema but rejected by the operator until implemented. | | `default` | Marks the store used when an `Index` omits `spec.backend.storeRef`. A single store is treated as the default. | | `endpoint.url` | Upstream API base URL. | | `endpoint.region` | Operator-visible region label for this store. | | `turbopuffer.orgId` | Optional turbopuffer organization id for dashboard deep links and support orientation. It is not used for auth or routing. | | `credential.secretRef` | Secret key in the same namespace as the `VectorStore`. The credential is never stored in the CRD. | ## Routing The gateway builds one upstream client per `VectorStore` in the namespace. Requests whose namespace has an `Index` with `spec.backend.storeRef` use that store; other namespaces use the default store. Two `Index` objects cannot resolve to the same upstream namespace. ## Inbound auth `inboundAuth.mode` controls what bearer token the gateway accepts: | Mode | Behavior | | --- | --- | | `deriveFromStore` | Default. The gateway accepts the default store's credential as the inbound bearer. This is the single-tenant BYOC shape. | | `keys` | The gateway accepts the listed independent key Secrets and enforces their `read`, `write`, and `admin` scopes. | | `open` | No inbound auth. Use only for explicitly open environments. | Under `deriveFromStore`, clients set `Authorization: Bearer ` when calling the gateway. Operator-managed workers and KEDA use the same Secret through `LAYER_GATEWAY_API_KEY`. Under `keys`, each key points at a Secret in the same namespace: ```yaml spec: inboundAuth: mode: keys keys: - name: shop-rw scopes: [read, write] secretRef: name: layer key: layer-inbound-shop-rw-api-key ``` `read` covers GET/HEAD routes and read-shaped POST routes such as query, batch fetch, scans, and metrics proxy queries. `write` covers namespace writes and worker queue claim/complete routes. `admin` covers Pipeline and Function create/delete/control routes and also satisfies `read` and `write`. In every mode the gateway also accepts a minted [`ApiKey`](/docs/kubernetes/apikey-crd) token whose `vectorstore.` entitlement names this store, enforcing that entitlement's scopes and namespace globs. ## Status The operator sets `status.reachable` and a `Ready` condition after validating the Secret references and probing `GET /v1/namespaces` on the store endpoint. --- # ApiKey CRD Source: https://hevlayer.com/docs/kubernetes/apikey-crd An `ApiKey` is a minted credential as a resource. Layer owns the credential lifecycle — mint, verify, revoke, expire — and what the key opens is declared per resource: each entitlement names a [`VectorStore`](/docs/kubernetes/vectorstore-crd), a [`Warehouse`](/docs/kubernetes/warehouse-crd), an [`Agent`](/docs/kubernetes/agent-crd), or Layer itself, and carries the scopes and claims for that target. Claims are opaque to Layer — an external system can use Layer as its key store and keep authorization decisions to itself. Keys have two authoring surfaces that round-trip through one schema: `kubectl get apikey -o yaml` and `GET /v2/keys/{keyId}` are two spellings of the same object. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: ApiKey metadata: name: cohort-reader namespace: layer spec: owner: acme description: cohort read access entitlements: vectorstore.prod-turbopuffer: scopes: [read] namespaces: ["cohort-*"] warehouse.prod-snowflake: claims: - "notes:cohort:*:read" expiresAfter: 365d status: keyId: 0a1b2c3d-… phase: Active lookupHash: sha256:… createdAt: "2026-06-10T00:00:00Z" expiresAt: "2027-06-10T00:00:00Z" secretRef: name: apikey-cohort-reader ``` ## Spec | Field | Purpose | | --- | --- | | `owner` | Optional free-form owner label, echoed in list and authenticate responses. | | `description` | Optional free-form description. | | `entitlements` | Map keyed by target resource. Each entry carries `scopes`, `namespaces`, and `claims` for that target. | | `expiresAfter` | Duration or `never`. Defaults to `365d`; `status.expiresAt` is computed at mint. | ## Entitlements | Key | Target | | --- | --- | | `vectorstore.` | Data-plane access through the named store. `scopes` (`read`, `write`) gate routes whose `Index` resolves to that store; `namespaces` globs constrain which upstream namespaces. | | `warehouse.` | A list of opaque `claims` strings bound to the source system. Layer stores and echoes them; the application routes on them. No client route reaches a source — clients touch indexes, not warehouses — so the entitlement grants nothing in Layer and inerts when the warehouse is deleted. | | `agent.` | Invocation of the named [`Agent`](/docs/kubernetes/agent-crd): the right to call `POST /v2/agents//query`. Data access is separate — the agent's reads run under the caller's own `vectorstore` grants — so this governs *who may invoke*, not *what it reads*. Inerts when the agent is deleted. | | `layer` | The control plane itself. `scopes: [admin]` covers key management and Pipeline/Function create/delete/control routes, and satisfies `read` and `write` everywhere. | Scope meanings match [inbound auth](/docs/kubernetes/vectorstore-crd#inbound-auth): `read` covers query, fetch, scans, and metrics; `write` covers namespace writes and worker routes. `claims` is a list of opaque strings, allowed on any entitlement and the only field on a warehouse entitlement. Layer stores them, returns them from list, get, and authenticate, and never interprets them — an existing permission grammar (`service:resource_type:resource_id:action` strings, a legacy entitlement vocabulary) drops in verbatim, and the consuming application maps them to its own authorization. An entitlement whose target does not exist grants nothing and surfaces as a status condition (`EntitlementTargetMissing`) — not an admission error, so keys and their targets can be applied in either order. Check the condition after applying: a typo in a target name looks the same as a missing target. A key whose entitlements carry only claims — no scopes — is a pure external-store key: it authenticates, but opens no Layer route. ## Minting **REST.** `POST /v2/keys` generates the token, creates the `ApiKey` resource, and returns the token in the response — once. The raw token is never persisted; Layer stores only one-way hashes on the resource. ```http POST /v2/keys # 201 { keyId, …, token } — token returned once GET /v2/keys # metadata only; ?includeRevoked GET /v2/keys/{keyId} POST /v2/keys/{keyId}/revoke # idempotent DELETE /v2/keys/{keyId} # hard delete; Revoked keys only POST /v2/keys/authenticate # body { token } → 200 { keyId, entitlements, … } | 401 ``` Key-management routes require a key with the `layer` entitlement at `admin` scope. `POST /v2/keys/authenticate` is unauthenticated by construction — the token is the credential. **CRD.** Apply an `ApiKey` with no credential. The operator mints the token, writes it to a Secret named in `status.secretRef` (key `token`), and moves `phase` from `Pending` to `Active`. The Secret is the token delivery; it is owned by the `ApiKey` and garbage-collected with it. Rotate by minting a replacement, deploying it, and revoking the old key. ## Verification External systems present the raw token to `POST /v2/keys/authenticate` and get back `keyId` (a stable actor id) plus the full `entitlements` map, then make their own authorization decisions from the claims. The gateway also accepts any `Active` key's token as a bearer on its own routes, enforcing the entitlement for the store or control-plane surface the route resolves to. Verification is one indexed lookup plus one hash check against a watch-fed in-memory map — the hot path never reads the control plane per request. `status.lastSeenAt` advances at most once per five minutes per key. | Phase | Meaning | | --- | --- | | `Pending` | CRD-authored key awaiting mint. | | `Active` | Verifiable; token works. | | `Revoked` | `POST /v2/keys/{keyId}/revoke` was called; token refused. | | `Expired` | `status.expiresAt` passed; token refused. | Revoke is the default lifecycle end-state. Revoked `ApiKey` resources are retained indefinitely for audit and are not automatically garbage-collected. Operators should set a retention policy appropriate to their obligations. Hard delete is rare and deliberate: `DELETE /v2/keys/{keyId}` accepts only a `Revoked` key and permanently removes the resource, its lifecycle record, and any owned token Secret. Other phases return `409 Conflict`; revoke first, then delete only after the retention period has passed or policy requires the record itself to be forgotten. Deleting a `VectorStore` or `Warehouse` inerts every entitlement that names it: the keys stay `Active` for their other entitlements, and the deletion is finalizer-guarded on the target's side while keys still reference it. ## Backup and migration Use a full namespace Velero backup, or an equivalent etcd snapshot, for portable `ApiKey` migration. Do not export and apply YAML: the verifier lives in `status`, and apply paths do not preserve that subresource. 1. Back up these Layer namespace objects: - `ApiKey` resources with `status`: `status.keyId`, `phase`, `lookupHash`, and `tokenHash` are the credential record; the raw token is not recoverable. - The chart's `*-keys` Secret: it holds `LAYER_KEY_PEPPER`, which must match every restored verifier. - Token-delivery Secrets referenced by CRD-authored keys through `status.secretRef`. 2. Restore `ApiKey` status explicitly. Velero restores specs by default and drops `status` unless the restore uses `--status-include-resources apikeys.hevlayer.com`, or the `Restore` sets `spec.restoreStatus.includedResources: ["apikeys.hevlayer.com"]`. 3. Restore the namespace, including the pepper Secret, before running Helm on the target release. If Helm touches an empty namespace first, it can generate a new random pepper, making restored argon2id verifiers unusable. 4. If source and target Velero servers share object storage, wait until the target server lists the completed source backup before creating the restore; otherwise its local `Backup` object may not have synced. 5. Refresh source Velero discovery before backup. Install Layer CRDs before Velero discovers resources, or restart the source Velero deployment after CRD installation and wait for readiness; stale discovery can produce a `Completed` backup that omits `ApiKey`. 6. Quiesce the Layer operator before backup and keep it quiesced through initial restore. Velero restores `ApiKey` spec and `status` separately; an operator that starts in that window can mark a transient spec-only key `MintBlocked` or `Pending`. 7. Inspect the completed backup from inside the Velero server's cluster. Its item list must include `apikeys.hevlayer.com`, expected `ApiKey` objects, the chart's `*-keys` pepper Secret, and token-delivery Secrets referenced by `status.secretRef`. 8. Restart gateway/operator discovery after restore so the watch-fed key map rebuilds from restored `ApiKey` status and Secrets before traffic depends on the migrated tokens. 9. Treat `MintBlocked` as a failed restore, not a key rotation. The operator refuses to mint a replacement when `status.keyId` is empty but the deterministic delivery Secret exists; it writes a `MintBlocked` condition and warning Event instead. A new CRD-authored `ApiKey` with no delivery Secret still mints normally. Validate the key store before accepting traffic: ```sh SOURCE_CONTEXT=layer-a \ TARGET_CONTEXT=layer-b \ LAYER_NAMESPACE=layer \ SOURCE_BASE_URL=https://source.example.com \ TARGET_BASE_URL=https://target.example.com \ SOURCE_ADMIN_KEY=hvl_... \ scripts/apikey-velero-migration.sh ``` The script mints REST and CRD-authored keys, backs up the namespace, waits for the target Velero server to sync the completed backup, restores with `--status-include-resources apikeys.hevlayer.com`, and asserts: - original active tokens still authenticate - revoked and expired tokens remain refused - the completed backup contains expected `ApiKey` resources and Secrets - the source operator was quiesced and the expired control key reached `Expired` before backup - the restored pepper Secret matches the source - restored key status fields are present, so spec-only, incomplete, racing, or misordered restores fail loudly Local reproduction currently needs the temporary test-license setup from the `/v2/keys` test `kid` keygen work in PR #199. Velero backups are credential-bearing: they contain one-way verifiers, the pepper, and any remaining CRD-authored delivery Secrets. Store and encrypt them like other credential material. ## Kubernetes RBAC CRD authoring makes kubectl a minting surface, so the chart ships roles to delegate key administration without cluster-admin: | ClusterRole | Grants | | --- | --- | | `hevlayer-key-admin` | Full verbs on `apikeys`, plus `get` on delivered token Secrets. Can mint, revoke, and collect tokens. | | `hevlayer-key-viewer` | `get`/`list`/`watch` on `apikeys`. No Secret access — status hashes are one-way, so viewing is audit, not credential access. | Neither role aggregates into the built-in `view`/`edit`/`admin` ClusterRoles: namespace viewer never silently means key viewer. Bindings are the cluster operator's explicit act; set `rbac.keyRoleBindings` in Helm values to render them for the single-team case. ## Bootstrapping `LAYER_GATEWAY_API_KEY` is the bootstrap credential: it mints the first admin key — ```yaml spec: entitlements: layer: scopes: [admin] ``` — after which routine minting uses minted admin keys. Cluster operators can equally bootstrap by applying an `ApiKey` resource, since CRD authoring needs only kubectl access. --- # Warehouse CRD Source: https://hevlayer.com/docs/kubernetes/warehouse-crd A `Warehouse` declares an upstream source system — the system of record pipelines extract rows from, plus the verified reachability and credential shape needed to reach it. Data in Layer is derived from a warehouse and reconstructible from it. The serving side is the [`VectorStore`](/docs/kubernetes/vectorstore-crd); the two sit on opposite sides of the gateway. ## Supported Warehouses | Kind | Status | Source | | --- | --- | --- | | `snowflake` | Shipped | Snowflake databases and tables, key-pair credential | | `huggingface` | Shipped | Hugging Face Hub datasets, public or token-gated | | `rest` | Shipped | Any paginated JSON HTTP API | | `databricks` | Reserved | Schema-reserved; rejected by the operator until implemented | | `iceberg` | Reserved | Schema-reserved; rejected by the operator until implemented | Snowflake warehouses hold a key-pair credential. Hugging Face dataset warehouses can be public and credentialless, or can point at a read-token Secret for gated/private datasets. REST warehouses declare a JSON HTTP API — a base URL, optional auth, and a pagination rule — so any paginated JSON API is a source without a bespoke kind. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Warehouse metadata: name: prod-snowflake namespace: layer spec: kind: snowflake snowflake: account: acme-xy12345 user: SVC_LAYER role: SVC_LAYER_ROLE warehouse: EXTRACT_WH keyPairSecretRef: name: snowflake-rsa pool: size: 5 timeout: 30s verifyInterval: 1h ``` ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Warehouse metadata: name: huggingface-hub namespace: hev-shop spec: kind: huggingface huggingface: endpoint: https://huggingface.co # tokenSecretRef is optional for public datasets. # tokenSecretRef: # name: hf-read # key: token verifyInterval: 1h ``` ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Warehouse metadata: name: openfda namespace: layer spec: kind: rest rest: baseUrl: https://api.fda.gov # auth is optional — omit for open APIs. # auth: # in: query # query | header # name: api_key # the param/header carrying the credential # secretRef: # name: openfda-key # key: token rateLimit: requestsPerSecond: 4 verify: path: /drug/label.json # a cheap GET the operator probes query: limit: "1" verifyInterval: 24h ``` ## Connection `spec.kind` selects the source system. `snowflake`, `huggingface`, and `rest` select a source; `databricks` and `iceberg` are reserved by the schema but rejected by the operator until implemented. Exactly one kind block must be present and match `spec.kind`. `verifyInterval` (default `1h`) sets the probe cadence for any kind. A warehouse is identity and credential — not a catalog. What to read — a Snowflake database and table, a Hugging Face dataset and split — belongs to the [pipeline source](#pipeline-source); one credential reaches many. ### Snowflake | Field | Purpose | | --- | --- | | `kind` | `snowflake`, `huggingface`, or `rest`. `databricks` and `iceberg` are reserved by the schema but rejected by the operator until implemented. | | `snowflake.account` | Snowflake account identifier. | | `snowflake.user` | Service user the key pair authenticates. | | `snowflake.role` | Optional role assumed on connect. | | `snowflake.warehouse` | Snowflake compute warehouse extraction queries run on. | | `snowflake.keyPairSecretRef` | Secret in the same namespace holding `private-key.pem` and optional `passphrase`. The credential is never stored in the CRD. | | `snowflake.pool` | Connection pool tuning: `size`, `timeout`. | | `huggingface.endpoint` | Hub endpoint. Defaults to `https://huggingface.co`; override for Enterprise Hub or a mirror. | | `huggingface.tokenSecretRef` | Optional Secret in the same namespace holding `token` for gated/private datasets. Omit for public datasets. | | `verifyInterval` | Probe cadence. Defaults to `1h`. | A warehouse is source identity and credential — not a catalog. Which database, schema, table, dataset repo, config, or split to read belongs to the [pipeline source](#pipeline-source); one credential can reach many tables or repos. ### REST / HTTP JSON API A `rest` warehouse declares a JSON HTTP API. The credential is optional — many public APIs need none, or take a key that only raises a rate limit (omit `auth` for the anonymous case, the same `Verified`-with-no-Secret shape as a public Hugging Face dataset). | Field | Purpose | | --- | --- | | `rest.baseUrl` | Required. API origin. A source's `request.path` resolves against it. | | `rest.auth` | Optional. `in` (`query` or `header`), `name` (the param or header carrying the credential), and `secretRef` (Secret holding `token`). Omit for open APIs. | | `rest.rateLimit` | Optional. `requestsPerSecond` is a client-side request cap, to stay under the API's fair-access ceiling. Omit to leave pacing to the source worker's defaults. | | `rest.verify` | Required. The reachability probe: a `path` and optional `query` the operator `GET`s to verify the API — and the credential, when `auth` is set. | `rest` holds access only; which endpoint, query, pagination, and field mapping to read belongs to the [pipeline source](#rest) — one warehouse serves many endpoints on the same API. ## Verification The operator probes the warehouse on apply, whenever the referenced Secret's content changes, and every `verifyInterval`. For `snowflake`, the probe opens a key-pair session, runs `SELECT 1` on the declared compute warehouse, and closes. For `huggingface`, the probe calls the Hub dataset API with the optional token. If pipelines reference the warehouse, the operator resolves each declared `repo@revision` and records the resolved commit SHA in `status.sourceRevisions`. With no consumers yet, it verifies that the Hub dataset API is reachable. For `rest`, the probe issues a single `GET` of `rest.verify.path` (with the optional `query`, and `auth` applied when set). Any `2xx` is `Verified`, confirming both reachability and — when a credential is configured — that it is accepted. | Phase | Meaning | | --- | --- | | `Pending` | Not yet probed. | | `Verified` | Last probe succeeded; `status.verifiedAt` is the probe time. | | `Failed` | Last probe failed; `status.failureReason` says why. | `Failed` is a loud signal, not an outage: in-flight pipeline runs keep their connections, new runs refuse to start, and the condition surfaces in `kubectl get warehouse` and the dashboard. Pipelines start only against a `Verified` warehouse. ## Rotation Swap the referenced Secret's content. The operator re-verifies and `status.verifiedAt` advances; consumers resolve credentials through the warehouse at connection-build time, so new connections pick up the new key with no redeploy. Pointing `keyPairSecretRef` or `tokenSecretRef` at a different Secret name is a spec edit with the same flow. For `huggingface`, swapping the token Secret's content re-verifies the same way. Adding or removing `tokenSecretRef` — moving a warehouse between anonymous and authenticated access — is a spec edit the operator re-verifies. ## Pipeline source A pipeline extracting from a warehouse names it in `spec.sourceRef`. The source block owns the *what* — for Snowflake a database, query, and cursor; for Hugging Face a dataset, split, and field mapping — and the warehouse owns the *where* and *who*. The operator requires `warehouseRef` to name a `Verified` warehouse of the matching kind in the same namespace, and carries the source block verbatim to the worker as `HEVLAYER_SOURCE_REF`, as for [any other source](/docs/kubernetes/pipeline-crd#source). ### Snowflake ```yaml spec: sourceRef: kind: snowflake warehouseRef: prod-snowflake database: ANALYTICS query: >- SELECT ID, TITLE, BODY, REFRESH_ID FROM PUBLIC.NOTES WHERE REFRESH_ID > :cursor cursor: column: REFRESH_ID ``` The operator mounts the warehouse's key-pair Secret into the worker pod at `/var/run/hevlayer/warehouse/` and injects `HEVLAYER_WAREHOUSE` — connection JSON resolved from the warehouse spec (account, user, role, compute warehouse, pool), no credential material. The worker builds its own connection from the two. ### Hugging Face ```yaml spec: target: namespace: squad sourceRef: kind: huggingface warehouseRef: hf-public dataset: rajpurkar/squad # Hub repo id config: plain_text # dataset config; omit for the default split: train # train | validation | test | … revision: ~ # omit → the operator resolves and records the parquet-ref commit mapping: id: id # column → document id text: context # column to index or embed attributes: [title, question] # columns to carry as attributes ``` | `mapping` field | Purpose | | --- | --- | | `text` | Required. The column indexed, and embedded by a following stage. | | `id` | Optional. Column used as the document id. Omitted, the worker synthesizes `{config}/{split}#{offset}` — stable within a revision; name a natural key for anything long-lived. | | `attributes` | Optional. Columns carried as attributes. Omit or `[]` for every remaining scalar column; binary feature columns (image, audio) are skipped. | `spec.worker.image` defaults to the stock Hugging Face source image from the mesh-account ECR registry, so no custom image is needed; set it to override. The operator mounts the warehouse's token Secret (when present) into the worker and injects `HEVLAYER_WAREHOUSE` with the endpoint only, no token. The worker streams rows from the dataset's Parquet conversion at the pinned `revision`; the row offset is the cursor. Omitting `revision` pins to the dataset's current parquet-ref commit, which the operator resolves and records, so a long run never drifts onto a newer version mid-flight and re-enumeration is exact. Reading a newer version is a deliberate `revision` edit. A dataset's `text` column is often a whole document that must be split into chunks before it is embedded. Add a `chunk` block to the source to declare how — it is a pipeline-source feature, not specific to Hugging Face. See [Chunking](/docs/kubernetes/pipeline-crd#chunking) on the Pipeline CRD page. ```yaml spec: sourceRef: kind: huggingface warehouseRef: huggingface-hub repo: McAuley-Lab/Amazon-Reviews-2023 config: raw_meta_Electronics split: train revision: main cursor: field: parent_asin ``` When `sourceRef.kind` is `huggingface`, the operator requires `warehouseRef` to name a `Verified` Hugging Face warehouse in the same namespace and requires `repo` on the source block. It injects `HEVLAYER_WAREHOUSE` with the Hub endpoint and, when `tokenSecretRef` is set, mounts the Secret at `/var/run/hevlayer/warehouse/token` and adds `tokenPath` to the connection JSON. `HEVLAYER_SOURCE_REF` remains the verbatim source block and owns the dataset repo, config, split, revision, and cursor. ### REST ```yaml spec: target: namespace: drug-labels sourceRef: kind: rest warehouseRef: openfda request: path: /drug/label.json query: # static query params search: 'openfda.product_type:"HUMAN PRESCRIPTION DRUG"' pagination: kind: offset # offset only in v1 (searchAfter, link: not yet supported) pageSizeParam: limit # required for offset offsetParam: skip # required for offset pageSize: 1000 # required for offset; must be > 0 response: items: $.results # JSONPath to the record array on each page cursor: field: effective_time # incremental + re-enumeration key (JSONPath per item) mapping: id: openfda.spl_set_id # JSONPath into each item text: ~ # omit when a chunk strategy supplies the section text attributes: [openfda.generic_name, openfda.brand_name, dea_schedule] ``` | Source field | Purpose | | --- | --- | | `request.path` / `request.query` | The endpoint (resolved against `baseUrl`) and any static query params — the *what*. | | `pagination` | How to walk pages. v1 supports `kind: offset` only — `pageSizeParam`, `offsetParam`, and `pageSize` (a positive integer) are all required. `searchAfter` (a cursor token the API echoes) and `link` (a `Link` header) are not yet supported and are rejected on apply. | | `response.items` | JSONPath to the record array on each page. | | `cursor.field` | JSONPath into each item, used as the incremental refresh key and the re-enumeration cursor. | | `mapping` | JSONPath expressions for `id`, `text`, and `attributes` — the same mapping shape as Hugging Face, over JSON instead of Parquet columns. | `spec.worker.image` defaults to the stock REST source image from the mesh-account ECR registry, which pages any JSON API by these rules — there is no per-API worker. The operator injects `HEVLAYER_WAREHOUSE` with the `baseUrl` (and mounts the `auth` Secret when set); `HEVLAYER_SOURCE_REF` is the verbatim source block. A `text` field that is a whole document is split by a [`chunk`](/docs/kubernetes/pipeline-crd#chunking) block, as for any source; the `section` strategy with `sectionSource: jsonFields` makes each top-level JSON field its own section. ## Keys An [`ApiKey`](/docs/kubernetes/apikey-crd) binds to a warehouse with a `warehouse.` entitlement carrying a list of opaque claims strings. Layer stores and echoes the strings; the application routes on them. No client route reaches a source system — clients touch indexes, not warehouses — so the entitlement grants nothing in Layer, and it inerts when the warehouse is deleted. ## Deletion Deleting a warehouse fences everything drawing from it. A finalizer blocks deletion while `status.consumers` is non-zero — pipelines extracting from it or keys entitled to it — annotate with `hevlayer.com/force-delete: "true"` to override. ## Status ```yaml status: phase: Verified verifiedAt: "2026-06-10T00:00:00Z" failureReason: null sourceRevisions: McAuley-Lab/Amazon-Reviews-2023@main: 2b6d039ed471f2ba5fd2acb718bf33b0a7e5598e consumers: pipelines: 2 apiKeys: 1 ``` The operator emits Kubernetes Events on phase transitions and counts observed references in `status.consumers`. --- # Index CRD Source: https://hevlayer.com/docs/kubernetes/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](/docs/kubernetes/vectorstore-crd). ```yaml 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](/docs/api/federated-query#vector-merge-requires-a-matching-embedding-space): 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. --- # InfraRules CRD Source: https://hevlayer.com/docs/kubernetes/scaling-crd `InfraRules` is the cluster-scoped policy object for Layer-managed runtime infrastructure. There is exactly one object: `InfraRules/default`. Pipelines and Functions do not reference a separate autoscaling resource. They set `spec.scaling` inline and choose a pool from `InfraRules/default.spec.computePools`. ## InfraRules ```yaml apiVersion: hevlayer.com/v1alpha1 kind: InfraRules metadata: name: default spec: computePools: - name: cpu kind: cpu nodeSelector: layer.hev.dev/node-role: worker-cpu layer.hev.dev/compute: cpu tolerations: - key: layer.hev.dev/node-role operator: Equal value: worker-cpu effect: NoSchedule resources: requests: cpu: "1" memory: 2Gi limits: cpu: "2" memory: 4Gi maxReplicasPerWorkload: 32 - name: cpu-large kind: cpu nodeSelector: layer.hev.dev/node-role: worker-cpu layer.hev.dev/compute: cpu tolerations: - key: layer.hev.dev/node-role operator: Equal value: worker-cpu effect: NoSchedule resources: requests: cpu: "1" memory: 2Gi ephemeral-storage: 35Gi limits: cpu: "4" memory: 4Gi ephemeral-storage: 40Gi maxReplicasPerWorkload: 8 - name: gpu kind: gpu nodeSelector: layer.hev.dev/node-role: worker-gpu layer.hev.dev/compute: gpu tolerations: - key: layer.hev.dev/node-role operator: Equal value: worker-gpu effect: NoSchedule - key: nvidia.com/gpu operator: Exists effect: NoSchedule resources: requests: cpu: 250m memory: 4Gi nvidia.com/gpu: "1" limits: cpu: "2" memory: 10Gi nvidia.com/gpu: "1" maxReplicasPerWorkload: 4 documentCache: capGiB: 256 replicationFactor: 1 scaling: mode: autoscale nodes: min: 0 max: 1 ``` The operator validates that the object is named `default`. Helm can render the default object with `operator.infraRules.create=true`. ## Compute pools The Helm defaults define three well-known pools: | Pool | Use | | --- | --- | | `cpu` | General CPU workers. | | `cpu-large` | CPU workers that need local ephemeral-storage headroom. | | `gpu` | One-NVIDIA-GPU workers for embedding and inference. | The default pools select the Karpenter-backed worker nodes with `layer.hev.dev/node-role=worker-cpu` or `worker-gpu`. The default `gpu` pool also requests `nvidia.com/gpu: "1"` and includes the standard NVIDIA toleration. Override `nodeSelector`, `gpuType`, or resource envelopes in `operator.infraRules.computePools` when your cluster uses different worker pool names or specific SKUs. | Field | Purpose | | --- | --- | | `name` | Referenced by `spec.scaling.pool` on Pipeline and Function resources. | | `kind` | Pool class label such as `cpu` or `gpu`. | | `gpuType` | Optional descriptive GPU type for GPU pools. | | `nodeSelector` | Applied to worker pods that choose the pool. | | `tolerations` | Applied to worker pods that choose the pool. | | `resources` | Container resources applied to worker pods. | | `maxReplicasPerWorkload` | Hard ceiling for one Pipeline or Function. | If a workload names an unknown pool or asks for more replicas than the pool ceiling, the operator leaves the workload unready and records a condition on its status. ## Workload scaling ```yaml scaling: pool: gpu mode: autoscale warmWindowSeconds: 300 replicas: min: 0 max: 4 ``` | Mode | Behavior | | --- | --- | | `autoscale` | Emit a KEDA `ScaledObject` and let queue depth scale the Deployment between `min` and `max`. | | `fixed` | Set Deployment replicas to `replicas.min`; no KEDA object is emitted. | | `disabled` | Scale the Deployment to 0; no KEDA object is emitted. | | Field | Purpose | | --- | --- | | `pool` | Names a pool in `InfraRules/default.spec.computePools`. When omitted, the operator maps `worker.computeClass` to the stock `cpu` or `gpu` pool. | | `mode` | `autoscale`, `fixed`, or `disabled` (see the table above). | | `replicas` | `min`/`max` bounds for the Deployment. `max` may not exceed the pool's `maxReplicasPerWorkload`. | | `warmWindowSeconds` | Cooldown that holds a workload warm after its last scaling trigger drains, before `autoscale` returns it to `replicas.min`. See below. | Paused workloads also scale to 0. To keep a cold-start-heavy worker warm, set `mode: autoscale` and `replicas.min: 1`. ### Warm window `warmWindowSeconds` maps to the KEDA `ScaledObject` `cooldownPeriod`: the operator waits this long after the last trigger fires before scaling the Deployment back to `replicas.min`. It defaults to `60` when unset. A non-zero value also annotates the worker pods with `karpenter.sh/do-not-disrupt`, so Karpenter retains the *node* — not just the replica — for the window rather than consolidating it away. This is aimed at scale-to-zero GPU pools, where each wake otherwise pays a full cold start (fresh nodeclaim, multi-GB image pull, model load). A warm window lets adjacent batches reuse one warm node, then lets the pool return to genuine scale-to-zero once the window elapses. It must be `>= 0` and requires `mode: autoscale`; the operator leaves the workload unready and records a condition otherwise. ## Document cache rules `documentCache` captures the operator-owned document cache settings: capacity, replication factor, and node count. Helm still renders the document-cache KEDA object directly; `InfraRules` is the declared policy shape the operator reports and validates against. --- # Pipeline CRD Source: https://hevlayer.com/docs/kubernetes/pipeline-crd The `Pipeline` CRD declares the scaling characteristics you want for ingesting data. Ingestion typically runs in stages: a CPU stage for chunking and extraction, followed by a GPU stage for embedding. You can declare the spec in YAML, from code through the [pipeline API](/docs/api/pipelines), or a combination of both — it is recommended you declare your pipeline scaling characteristics in YAML while setting your namespace via the client. `spec.sourceRef` lets you declare your pipeline's upstream details as well — the operator hands it to the worker as an environment variable, so the worker reads its source from config instead of hardcoding it. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Pipeline metadata: name: product-images namespace: layer spec: target: namespace: products sourceRef: kind: sqs queueUrl: https://sqs.us-east-1.amazonaws.com/123456789/product-images schedule: cron: "0 2 * * *" leaseSeconds: 600 worker: image: .dkr.ecr.us-east-1.amazonaws.com/hev-product-image-worker:latest computeClass: cpu batchSize: 64 timeoutSeconds: 60 scaling: pool: cpu mode: autoscale replicas: min: 0 max: 8 ``` ## Target `spec.target.namespace` is the turbopuffer namespace the pipeline writes. The gateway pipeline API owns document state, chunks, and vector writes for that target namespace. ## Pipeline id `spec.pipelineId` names the gateway pipeline (the queue) the worker stages into and scales on. It defaults to the resource name. Set it when multiple worker resources share one queue: the extract and embed stages of a [two-stage pipeline](/docs/api/pipelines) both set `pipelineId: products`. ## Source `spec.sourceRef` declares the external source that feeds the worker. Its `kind` selects how the operator treats it. For **open kinds** — SQS, Kafka, S3 events, a partner API, a one-off migration — `sourceRef` is arbitrary JSON injected into the worker pod verbatim as `HEVLAYER_SOURCE_REF`; the worker image owns source-specific behavior. See [Extract and chunk](/docs/api/pipelines#extract-and-chunk) for a worker reading it. ### Typed sources For **warehouse-backed kinds** — `snowflake`, `huggingface`, and `rest` — `kind` selects a typed shape the operator validates. The source names a [`Warehouse`](/docs/kubernetes/warehouse-crd) with `warehouseRef`; the operator resolves it (it must be `Verified`), mounts its credential Secret, and injects connection details as `HEVLAYER_WAREHOUSE` with no credential material. `spec.worker.image` is then optional: omit it and the operator defaults to the stock worker for that kind from the mesh-account ECR registry (for example, `.dkr.ecr.us-east-1.amazonaws.com/hev-huggingface-source` or `.dkr.ecr.us-east-1.amazonaws.com/hev-rest-source`), so a typed source needs no custom image. Set `worker.image` to override with your own. The per-kind source fields are on the [Warehouse CRD](/docs/kubernetes/warehouse-crd#pipeline-source) page. ### Chunking A source's text column is often a whole document that must be split before it is embedded. An optional `chunk` block declares how, with no code for the common strategies. It applies to any source whose worker honors it — the stock workers do. ```yaml spec: sourceRef: kind: huggingface warehouseRef: hf-public dataset: wikimedia/wikipedia config: 20231101.en split: train mapping: text: text attributes: [title, url] chunk: strategy: recursive # none | fixed | recursive | sentence | markdown unit: tokens # tokens | characters size: 512 overlap: 64 tokenizer: cl100k_base # when unit: tokens ``` | `chunk` field | Purpose | | --- | --- | | `strategy` | `none` (default — one document per row), `fixed`, `recursive` (a paragraph→line→sentence→word ladder kept under `size`), `sentence`, or `markdown` (split on headings). | | `unit` | `tokens` or `characters` — what `size` and `overlap` count in. | | `size` | Target maximum chunk length. | | `overlap` | Units repeated between adjacent chunks for context. | | `tokenizer` | Token model when `unit: tokens`. Pinned so chunk boundaries stay reproducible. | Each row maps to one document; `text` splits into chunks. The chunk is the unit indexed and embedded — a row with id `{documentId}#{i}` carrying the document's attributes plus reserved `_hevlayer_parent_id` and `_hevlayer_chunk_index`. For splits the stock strategies can't express, set `spec.worker.image` to your own chunker. ## Schedule `spec.schedule` is optional. When it is set, the operator wakes the Pipeline worker on a KEDA cron window instead of scaling it on pending pipeline queue depth: ```yaml schedule: cron: "0 2 * * *" # 5-field UTC cron; minute must be a single integer leaseSeconds: 600 # sizes the cron window ``` The worker still owns source semantics: what to pull on wake, how to advance cursors, and how to stage rows. The schedule only controls when the worker runs. Scheduled Pipelines must use `scaling.replicas.min: 0`; the cron window is the wake trigger. ## Worker | Field | Purpose | | --- | --- | | `image` | Worker image. Optional for [typed sources](#typed-sources), where it defaults to the stock worker for the source kind; required otherwise. | | `computeClass` | `cpu` or `gpu`. Defaults to `cpu`; when `scaling.pool` is omitted, the operator maps this to the stock `cpu` or `gpu` pool. | | `batchSize` | Work items per batch. | | `timeoutSeconds` | Worker call timeout. | | `podSpec` | Optional pod-level merge patch. | The operator creates one Deployment per Pipeline and injects: | Variable | Value | | --- | --- | | `HEVLAYER_PIPELINE_ID` | `spec.pipelineId`, defaulting to the resource name. | | `HEVLAYER_TARGET_NAMESPACE` | `spec.target.namespace`. | | `HEVLAYER_BASE_URL` | The gateway base URL. | | `HEVLAYER_SOURCE_REF` | `spec.sourceRef` as JSON, when set. | | `HEVLAYER_PIPELINE_SCHEDULE` | `1` when `spec.schedule` is set. | | `HEVLAYER_WAREHOUSE` | Resolved `Warehouse` connection JSON (no credential material), for [typed sources](#typed-sources). The credential Secret is mounted separately. | | `LAYER_GATEWAY_API_KEY` | Gateway bearer token. In `deriveFromStore` mode this is the default `VectorStore` credential; in `keys` mode it is the configured inbound worker key. | ## Scaling ```yaml scaling: pool: cpu mode: autoscale replicas: min: 0 max: 8 ``` `spec.scaling.pool`, when set, must name a pool in [`InfraRules/default`](/docs/kubernetes/scaling-crd). When omitted, the operator uses `worker.computeClass` to choose the stock `cpu` or `gpu` pool. Helm installs the well-known `cpu`, `cpu-large`, and `gpu` pools by default. `mode: autoscale` creates a KEDA `ScaledObject` backed by pipeline queue depth, or by the cron window when `spec.schedule` is set. `mode: fixed` pins the Deployment to `replicas.min`; `mode: disabled` scales it to zero. `spec.scaling.warmWindowSeconds` sets a cooldown (and node retention) that holds the worker warm after its queue drains — see [Workload scaling](/docs/kubernetes/scaling-crd#warm-window). `spec.paused: true` also scales the worker to zero. ## Status Use the [pipeline status API](/docs/api/pipelines#wait-for-completion) for status: queue counts, stage progress, and worker state. The resource itself reports only managed object references and readiness conditions. --- # Function CRD Source: https://hevlayer.com/docs/kubernetes/function-crd import CodeTabs from "../../../components/docs/CodeTabs.astro"; The `Function` CRD is a User Defined Function (UDF) that runs over rows that already exist in an [Index](/docs/kubernetes/index-crd). It is the right shape for classifiers, enrichment, backfills, fan-out from an existing row, and deterministic re-upserts. UDFs are best defined in YAML and invoked by the [layer CLI](/docs/cli#run-a-function). The operator creates worker resources; the gateway owns discovery, queueing, retries, leases, and completion markers. Workers own their data writes. Use a [Pipeline](/docs/kubernetes/pipeline-crd) when external data becomes rows in Layer. Use a Function when compute starts from rows that are already in Layer. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Function metadata: name: tag-products namespace: layer spec: targetNamespaces: - products inputs: - id - title version: v1 filter: - category - Eq - outdoor worker: image: .dkr.ecr.us-east-1.amazonaws.com/hev-tag-products:latest dispatch: pull computeClass: cpu batchSize: 32 timeoutSeconds: 30 schedule: discoveryIntervalSeconds: 300 leaseSeconds: 120 maxInFlightBatches: 8 maxConcurrentScans: 1 retry: maxAttempts: 8 initialBackoffSeconds: 5 maxBackoffSeconds: 300 triggers: - discovery scaling: pool: cpu mode: autoscale replicas: min: 0 max: 6 ``` ## Selection Use `targetNamespaces` for explicit namespaces. Use `indexSelector` when labels on `Index` resources should choose the namespaces. `filter` preserves arbitrary JSON, including array-form turbopuffer filters. The operator stores the shape as-is; the gateway evaluates it during discovery after AND-ing it with the generated completion-marker predicate. Do not include a version-marker predicate in `filter`; the gateway creates that from `spec.version`. ## Worker | Field | Purpose | | --- | --- | | `image` | Worker image. | | `dispatch` | `pull` for SDK claim/poll workers, `push` for HTTP `/run` workers. | | `computeClass` | `cpu` or `gpu`. Defaults to `cpu`; when `scaling.pool` is omitted, the operator maps this to the stock `cpu` or `gpu` pool. | | `port` | Push-dispatch service port. | | `batchSize` | Rows per batch. | | `timeoutSeconds` | Worker call timeout. | | `podSpec` | Optional pod-level merge patch. | To apply the CR, register the gateway UDF, trigger discovery, and watch the queue with one command, use [`layer run -f`](/docs/cli#run-a-function). The worker pod receives `HEVLAYER_UDF_ID`, `HEVLAYER_BASE_URL`, `HEVLAYER_UDF_BATCH_SIZE`, `HEVLAYER_UDF_TIMEOUT_SECONDS`, `HEVLAYER_UDF_LEASE_SECONDS`, and `LAYER_GATEWAY_API_KEY`. The gateway bearer is sourced from the default `VectorStore` credential in `deriveFromStore` mode, or from the configured inbound worker key in `keys` mode. ## Simple classifier The Python client turns a normal function into the claim/process/complete loop. `output="tags"` is client-side metadata: the CRD does not declare an output attribute. `run_udf_worker` sends the returned value as a completion `attributes.tags` patch, and the gateway stamps the reserved completion marker in the same patch. The Go client drives the same worker protocol directly, as does the TypeScript client — claim a batch, process rows, report completions and failures. ```python import asyncio from hevlayer.udf import PermanentError, TransientError, run_udf_worker, udf @udf(inputs=["id", "title", "description"], output="tags", kind="tags") def tag_product(*, id: str, title: str | None, description: str | None) -> list[str]: if not title: raise PermanentError(f"{id}: missing title") try: text = f"{title} {description or ''}".lower() except TypeError as exc: raise TransientError(str(exc)) from exc tags: list[str] = [] if "wireless" in text: tags.append("wireless") if "waterproof" in text: tags.append("waterproof") return tags or ["uncategorized"] if __name__ == "__main__": asyncio.run(run_udf_worker(tag_product, udf_id="product-tags")) ``` ```go package main import ( "context" "os" "strings" hevlayer "github.com/hev/layer-go" ) func tags(title, description string) []string { text := strings.ToLower(title + " " + description) var out []string if strings.Contains(text, "wireless") { out = append(out, "wireless") } if strings.Contains(text, "waterproof") { out = append(out, "waterproof") } if len(out) == 0 { out = []string{"uncategorized"} } return out } func main() { ctx := context.Background() udfID := os.Getenv("HEVLAYER_UDF_ID") layer := hevlayer.NewClient( hevlayer.WithBaseURL(os.Getenv("HEVLAYER_BASE_URL")), hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")), ) for { claimed, err := layer.ClaimUdfItems(ctx, udfID, &hevlayer.UdfClaimRequest{ WorkerID: "tag-products-0", Limit: 32, }) if err != nil { continue } var done []hevlayer.UdfCompleteItem var failed []hevlayer.UdfFailItem for _, item := range claimed.Items { title, _ := item.Input["title"].(string) description, _ := item.Input["description"].(string) if title == "" { failed = append(failed, hevlayer.UdfFailItem{ Namespace: item.Namespace, ID: item.ID, Kind: "permanent", Message: "missing title", }) continue } done = append(done, hevlayer.UdfCompleteItem{ Namespace: item.Namespace, ID: item.ID, Attributes: map[string]interface{}{"tags": tags(title, description)}, }) } if len(done) > 0 { layer.CompleteUdfItems(ctx, udfID, &hevlayer.UdfCompleteRequest{ WorkerID: "tag-products-0", Items: done, }) } if len(failed) > 0 { layer.FailUdfItems(ctx, udfID, &hevlayer.UdfFailRequest{ WorkerID: "tag-products-0", Items: failed, }) } } } ``` ```typescript import { Hevlayer } from "hevlayer"; function tags(title: string, description: string): string[] { const text = `${title} ${description}`.toLowerCase(); const out: string[] = []; if (text.includes("wireless")) out.push("wireless"); if (text.includes("waterproof")) out.push("waterproof"); return out.length ? out : ["uncategorized"]; } const udfId = process.env.HEVLAYER_UDF_ID!; const layer = new Hevlayer({ baseUrl: process.env.HEVLAYER_BASE_URL, apiKey: process.env.LAYER_GATEWAY_API_KEY, }); while (true) { const claimed = await layer.claimUdfItems(udfId, { worker_id: "tag-products-0", limit: 32, }); const done = []; const failed = []; for (const item of claimed.items) { const title = typeof item.input.title === "string" ? item.input.title : ""; const description = typeof item.input.description === "string" ? item.input.description : ""; if (!title) { failed.push({ namespace: item.namespace, id: item.id, kind: "permanent", message: "missing title", }); continue; } done.push({ namespace: item.namespace, id: item.id, attributes: { tags: tags(title, description) }, }); } if (done.length > 0) { await layer.completeUdfItems(udfId, { worker_id: "tag-products-0", items: done }); } if (failed.length > 0) { await layer.failUdfItems(udfId, { worker_id: "tag-products-0", items: failed }); } } ``` In Python, function parameters are keyword-only and named to match `inputs`; raise `TransientError` for retryable work and `PermanentError` for unrecoverable input. In Go and TypeScript, report the same split through `FailUdfItems` / `failUdfItems` with `kind: "transient"` or `kind: "permanent"`. ## GPU classifier More complicated classifiers (e.g. a vision-language classifier) may require a model to run on a GPU. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Function metadata: name: product-color namespace: layer spec: targetNamespaces: - amazon-products inputs: - id - image_url version: v1 worker: image: .dkr.ecr.us-east-1.amazonaws.com/hev-shop-udf-product-color:latest dispatch: pull computeClass: gpu batchSize: 8 timeoutSeconds: 120 schedule: leaseSeconds: 300 maxInFlightBatches: 2 triggers: - discovery scaling: pool: gpu mode: autoscale replicas: min: 0 max: 2 ``` `worker.computeClass: gpu` defaults omitted `scaling.pool` to the `gpu` pool from [`InfraRules/default`](/docs/kubernetes/scaling-crd). The stock pool selects `layer.hev.dev/node-role=worker-gpu`, requests one NVIDIA GPU, and carries the worker and NVIDIA tolerations: ```yaml computePools: - name: gpu kind: gpu maxReplicasPerWorkload: 4 nodeSelector: layer.hev.dev/node-role: worker-gpu layer.hev.dev/compute: gpu tolerations: - key: layer.hev.dev/node-role operator: Equal value: worker-gpu effect: NoSchedule - key: nvidia.com/gpu operator: Exists effect: NoSchedule resources: requests: { memory: 4Gi, nvidia.com/gpu: "1" } limits: { memory: 10Gi, nvidia.com/gpu: "1" } ``` The worker loads the model once at startup and classifies per row. CLIP zero-shot classification labels each product image with its dominant color: ```python import asyncio import io import httpx import torch from PIL import Image from transformers import pipeline from hevlayer.udf import PermanentError, TransientError, run_udf_worker, udf COLORS = ["black", "white", "gray", "red", "blue", "green", "brown", "multicolor"] classifier = pipeline( "zero-shot-image-classification", model="openai/clip-vit-large-patch14", device="cuda" if torch.cuda.is_available() else "cpu", ) @udf(inputs=["id", "image_url"], output="color", kind="classification") def classify_color(*, id: str, image_url: str | None) -> str: if not image_url: raise PermanentError(f"{id}: missing image_url") try: resp = httpx.get(image_url, timeout=10.0, follow_redirects=True) resp.raise_for_status() image = Image.open(io.BytesIO(resp.content)).convert("RGB") except httpx.HTTPError as exc: raise TransientError(f"{id}: image fetch failed: {exc}") from exc except OSError as exc: raise PermanentError(f"{id}: undecodable image: {exc}") from exc scores = classifier(image, candidate_labels=COLORS) return scores[0]["label"] if __name__ == "__main__": asyncio.run(run_udf_worker(classify_color, udf_id="product-color")) ``` The worker image needs `torch`, `transformers`, `pillow`, and `httpx` alongside the `hevlayer` Python client. Bake the model weights into the image so autoscaled pods do not re-download them on every cold start. Sizing for inference: keep `worker.batchSize` low and `worker.timeoutSeconds` high enough for one batch of forward passes, and make `schedule.leaseSeconds` outlast a full batch so claims do not reissue mid-inference. `replicas.min: 1` keeps a warm worker when model cold-start dominates; `min: 0` scales to zero between sweeps. ## Scaling `spec.scaling` is the same scaling config [Pipelines use](/docs/kubernetes/pipeline-crd#scaling): a pool from `InfraRules/default`, a mode, and replica bounds. For Functions, `mode: autoscale` emits a KEDA `ScaledObject` triggered by `layer_udf_queue_depth`. Replica maxima above the pool's `maxReplicasPerWorkload` are rejected in status. For GPU Functions on a scale-to-zero pool, set `spec.scaling.warmWindowSeconds` to hold the worker — and its node — warm for a cooldown after the queue drains, so adjacent batches skip the cold start (fresh node, image pull, model load) before the pool returns to zero. See [Workload scaling](/docs/kubernetes/scaling-crd#warm-window). ## Writeback Workers own data writes. The common single-attribute case uses the Python client's sugar: `@udf(output="tags")` makes `run_udf_worker` send returned values as `attributes.tags` in the completion call — in Go (or over REST) the same thing is `attributes` on each completion item. The gateway applies those attributes and the reserved completion marker in one `patch_columns` write. Completion attributes must not use the reserved `_hevlayer_*` prefix. Embedding Functions can include `vector` on each completion item; hev search multivector Functions can include `vectors` with a vector bag. The Python helper emits `vector` for `@udf(kind="embedding")` return values. The gateway fetches the existing row, merges returned attributes and reserved markers, then re-upserts the full row with the replacement vector or multivector bag. This is the writeback path for search-backed stores, which can replace vectors directly without a column-patch primitive. Python workers that need more control can declare the `tpuf` parameter, write through the client, and return `None`; completion then stamps only the marker. Use deterministic IDs when a Function creates rows so at-least-once retries remain idempotent. Deleting a Function garbage-collects operator-managed Kubernetes resources. It does not delete already-written attributes. ## Lifecycle ```sh kubectl get function product-tags kubectl describe function product-tags layer udf get product-tags kubectl patch function product-tags --type=merge -p '{"spec":{"paused":true}}' kubectl patch function product-tags --type=merge -p '{"spec":{"paused":false}}' curl -X POST -H "authorization: Bearer $LAYER_GATEWAY_API_KEY" \ $LAYER_GATEWAY_URL/v2/udfs/product-tags/reset-failed kubectl delete function product-tags ``` Registration in the gateway's UDF registry happens at reconciliation, not at first discovery run — a Function created with `spec.paused: true` (or paused later) is registered immediately with `paused: true`, so it is observable from creation onward: When the Function spec changes, reconciliation upserts the registered UDF definition in place. Pending, processing, failed, and indexed queue state remain attached to the same UDF id. ``` GET /v2/udfs → 200 {"udfs": [{"id": "product-tags", "paused": true, ...}]} GET /v2/udfs/product-tags/status → 200 {"udf_id": "product-tags", "paused": true, ...} ``` A `404` from `/v2/udfs/{id}/status` means the Function was never registered — a real failure, not an intentional pause. `paused` on the `Udf` and `UdfStatus` resources is the single source of truth for "is this installed and paused" versus "does this exist at all." ## Version markers `spec.version` is the re-run safety rail and defaults to `v1`. On completion, the gateway stamps `_hevlayer_udf__v` with that version, normalizing hyphens in the Function name to underscores. For `metadata.name: product-color`, the marker is `_hevlayer_udf_product_color_v`. Discovery automatically looks for rows whose marker is missing, differs from `spec.version`, or has an expired `_hevlayer_udf__stale_after` marker. Bump `spec.version` when a model, taxonomy, or prompt changes. ## Tuning knobs | Knob | What it bounds | | --- | --- | | `worker.batchSize` | Rows per worker batch. | | `worker.timeoutSeconds` | Worker call timeout. | | `schedule.leaseSeconds` | How long a claim is held before reissue. | | `schedule.discoveryIntervalSeconds` | Time between discovery scan jobs. | | `schedule.maxInFlightBatches` | Concurrent worker batches per UDF. | | `schedule.maxConcurrentScans` | Concurrent namespace discovery jobs. | | `retry.maxAttempts` | Tries before a row lands in `failed`. | --- # Agent CRD Source: https://hevlayer.com/docs/kubernetes/agent-crd import Callout from "../../../components/docs/Callout.astro"; An `Agent` is a saved agentic-search configuration as a resource. It binds an inference model, a turn budget, and a set of [indices](/docs/kubernetes/index-crd) to a name, so a caller searches with [`POST /v2/agents/{name}/query`](/docs/api/agents) and sends only a query string. Everything that decides what a call costs and what it can read lives on the resource, not in the request. An agent adds no retrieval primitive. Its only tool is the [federated query](/docs/api/federated-query); it sits one level above the [`Auto`](/docs/api/query#query-routing) router, using a model to reformulate the query, fan out for recall, and score the candidates for relevance. What it returns is the same row shape as every other search endpoint — a better-ranked result set, not a generated answer. Like the other CRDs here, an Agent has two authoring surfaces that round-trip through one schema: `kubectl get agent -o yaml` and `client.agent("support-search").apply()` are two spellings of the same object. ```yaml apiVersion: hevlayer.com/v1alpha1 kind: Agent metadata: name: support-search namespace: layer spec: model: provider: openrouter name: anthropic/claude-haiku-4-5 fallback: anthropic/claude-sonnet-4-6 # optional; used on primary timeout/error apiKeySecretRef: name: openrouter key: credential budget: deadlineMs: 60000 onDeadline: bestEffort indices: [docs, tickets] retrieval: fanout: 8 recallDepth: 50 rankBy: auto relevanceWeight: 0.6 output: provenance: false trace: false status: phase: Ready conditions: - type: SecretResolved status: "True" - type: ModelReachable status: "True" - type: IndicesResolved status: "True" ``` ## Model | Field | Purpose | | --- | --- | | `provider` | Inference backend. `openrouter`. | | `name` | Model id passed to the provider, e.g. `anthropic/claude-haiku-4-5`. | | `fallback` | Optional model used when the primary times out or errors. | | `apiKeySecretRef` | Secret holding the provider credential (`name`, `key`). The token is never inline on the resource — the same rule the [ApiKey](/docs/kubernetes/apikey-crd) and [VectorStore](/docs/kubernetes/vectorstore-crd) CRDs follow. | The gateway's in-memory agent spec also accepts a raw inline `model.apiKey` token. This exists only as a local dev-seed escape hatch for running an agent without provisioning a Secret. It is deliberately absent from the `Agent` CRD — the operator rejects anything but `apiKeySecretRef`, and RFC 0074 bans a raw token on the resource. Do not use it in any deployed configuration. ## Budget | Field | Purpose | | --- | --- | | `deadlineMs` | Wall-clock deadline for the whole request. | | `onDeadline` | `bestEffort` (default) returns the best ranking the agent has when the deadline hits; `error` fails the request instead. | ## Indices `indices` is the set of namespaces the agent searches, passed to the [federated query](/docs/api/federated-query) as its `namespaces`. The operator checks that the list is present and every entry is a non-empty string, surfaced as the `IndicesResolved` condition; it does not currently confirm each entry names a namespace that exists. The agent reads each listed namespace under the caller's credential, so a caller only reaches the namespaces its own key grants. ## Retrieval All retrieval behavior is expressed against the [federated query](/docs/api/federated-query) — nothing new reaches the upstream. | Field | Default | Purpose | | --- | --- | --- | | `fanout` | `8` | Query reformulations the agent issues, run in parallel via layer's [scatter/gather](/docs/concepts#scattergather) and merged for recall. Higher fan-out trades latency for recall. | | `recallDepth` | `50` | Candidates gathered for ranking before `top_k`, at least `top_k`. Bounds how much the model reads. | | `rankBy` | `auto` | Default route per leg: `auto`, `hybridText`, or `semantic`. A `semantic` leg needs a query vector, which the caller supplies on the request (`vector`) — layer never embeds query text; see [Agentic search](/docs/api/agents#bring-your-own-embedding). Without a supplied vector, semantic legs fall back to the lexical route. | | `relevanceWeight` | `0.6` | Weight of the relevance score against the recall score in the final ranking. | ## Output | Field | Purpose | | --- | --- | | `provenance` | When true, each row carries a `$agent` field with its `retrievalScore` and `relevanceScore`, and the response gains a top-level `agent` echo. | | `trace` | When true, the `agent` echo also carries the full reasoning trace. | Default off, the response is byte-for-byte the [federated query](/docs/api/federated-query#response) shape: a client cannot tell a reasoning loop produced it. See [Agentic search](/docs/api/agents) for the request and response contract. ## Auth Auth follows the same model as the other API endpoints; multi-namespace queries follow [federated query](/docs/api/federated-query#entitlements) auth behavior. Who may invoke an agent is an `agent.` entitlement on the [ApiKey](/docs/kubernetes/apikey-crd#entitlements). ## Status `status` carries health and validation only; latency, turn counts, and spend go to metrics and history, never into etcd. | Condition | Meaning | | --- | --- | | `SecretResolved` | `model.apiKeySecretRef` exists and is readable. | | `ModelReachable` | the provider answered with the bound credential. | | `IndicesResolved` | `spec.indices` is non-empty and every entry is a non-empty string. (It does not yet verify each entry is a known namespace.) | | Phase | Meaning | | --- | --- | | `Ready` | Resolvable and callable. | | `Degraded` | Reachable but a condition is failing — calls may fall back or error. | | `Invalid` | A required field or reference does not resolve; calls are refused. | `kubectl get agent` print columns: `MODEL`, `INDICES`, `PHASE`. Edits are picked up shortly after they apply: the gateway resolves agents — spec, provider credential, and per-index schema — into memory and refreshes on a periodic tick, so a `kubectl apply` lands within the refresh interval rather than instantly. ## Naming Agent names are cluster-unique at the gateway because callers address agents by name only. If two namespaces define the same Agent name, the gateway sorts by agent name and namespace, keeps the lexicographically later namespace, and logs a warning naming both namespaces. Keep Agent names unique across the cluster. ## Observability Deadline-hit rate, provider latency, and token usage per agent export as `hevlayer_*` metrics. Token counts come back on the inference response, so they cost no extra call; dollar cost is derived from them downstream rather than fetched in the request path. The reasoning trace is written to the [search-history](/docs/api/search-history) record alongside the query it belongs to, so agentic and plain searches share one history surface for evaluation. --- # Failure Modes Source: https://hevlayer.com/docs/failure-modes import Callout from "../../components/docs/Callout.astro"; Layer strives to degrade gracefully: queries and document fetch served from turbopuffer keep functioning when components around them fail. This page details the scenarios where that does not apply. ## Read Reads route through the gateway, but a gateway outage does not take your queries dark. The Python and Go SDKs fall through to turbopuffer direct when the gateway is unreachable, so turbopuffer-compatible queries keep serving rather than failing, minus the document cache, search history, and Layer's query enhancements (see [Client fall-through](#client-fall-through) below). Layer-only read paths (document fetch, warm jobs, pipeline and UDF status, snapshots, and search history) fail fast, because they depend on gateway-owned cache, queue, history, and consistency state. The document cache is stateless and can scale to zero with no disruption: document fetches fall through to origin (turbopuffer, or S3 for snapshots) on a miss or cache outage, so a cache failure degrades latency, not availability. ## Write Writes also fall through to turbopuffer direct when the gateway is unreachable (again, see [Client fall-through](#client-fall-through)); the durable upstream still accepts the row, but the write skips document-cache warming and pipeline staging until the gateway returns. ### Pipeline stop-writes The primary failure mode for writes through a healthy gateway is Aerospike stop-writes during a multi-stage pipeline job: staged documents stay warm in the cache but carry no vector data yet, and once that data exceeds the Aerospike drive allocation the cache rejects further writes. The pipeline does not stall. Each stage persists its chunk bodies to S3 before it touches the cache, and pipeline state lives in PostgreSQL, so the Aerospike write is best-effort: on stop-writes the gateway logs the skipped write and the stage still completes. Downstream chunk reads degrade to the S3 backing for as long as the cache is rejecting writes. Recovery is automatic. The Helm document cache restarts on stop-writes by default (`documentCache.autoRestartOnStopWrites: true`) and clears its Aerospike backing file on pod start (`documentCache.storage.resetOnStart: true`); the gateway reconnects in the background and refills the cache from S3 on demand. No pipeline work is lost — S3 and PostgreSQL are the durable recovery boundary and must stay healthy. Operator signals: - `layer_aerospike_op_duration_seconds{status="aerospike_stop_writes"}` — the stop-writes condition itself, the same series the [dashboard](/docs/dashboard) charts. - `hevlayer_cache_cold_responses_total` — reads being served from S3 backing instead of the cache while it recovers. - `hevlayer_document_cache_cold_starts_total` and `hevlayer_document_cache_cold_start_seconds` — the demand-triggered reconnect-and-refill cycle after the cache restarts. - Gateway warn logs `Aerospike chunk write failed (best-effort)` and `Aerospike chunk read failed; falling back to S3 backing`. ## Client failures When the gateway is unreachable, the SDKs return the gateway connection error. They do not retry directly against a backing store. That keeps the client surface backend-neutral: a namespace may be backed by turbopuffer or another store selected by `VectorStore`, and callers should not need a store-specific credential or fallback path. --- # Layer CLI Source: https://hevlayer.com/docs/cli The `layer` CLI operates hevlayer from the terminal. It manages named environments, initializes adopted namespaces for sharding, observes index, pipeline, and UDF state from the gateway, mints and revokes API keys, shows VectorStore and Warehouse health, and runs Function manifests. Every read goes through the gateway API with an API key; only `run` touches Kubernetes — it applies the Function CR, registers the UDF spec with the gateway, triggers discovery, and optionally watches until the queue drains. `run` is the only command that needs a kube context: set it on the environment with `--kube-context`/`--kube-namespace` or per invocation with `--context`/`--kube-namespace`. ## Install From the repository root: ```sh go build -o layer ./apps/layer-cli ``` ## Configuration `layer` reads named environments from `~/.hevlayer/config.toml`. The directory is created with mode `0700`; the config file is written with mode `0600`. ```toml active = "partner" [envs.partner] base_url = "https://aws-us-east-1.hevlayer.com" api_key = "..." kube_context = "partner-cluster" kube_namespace = "hevlayer" [envs.local] base_url = "http://localhost:8080" api_key = "dev" kube_context = "kind-hevlayer" ``` Resolution order is: | Priority | Source | | --- | --- | | 1 | Explicit flags such as `--base-url`, `--api-key`, `--context`, and `--kube-namespace` | | 2 | `LAYER_BASE_URL`, `LAYER_API_KEY`, and the `HEVLAYER_` twins | | 3 | Environment selected by `--env` or `LAYER_ENV` | | 4 | Active environment in `~/.hevlayer/config.toml` | | 5 | Built-in base URL default | A shell exporting `LAYER_BASE_URL` or `LAYER_API_KEY` keeps the env-var-only behavior and does not need a config file. `--env` and `LAYER_ENV` select an environment for one invocation without changing the active environment. | Flag | Environment | Default | | --- | --- | --- | | `--base-url` | `LAYER_BASE_URL`, `HEVLAYER_BASE_URL` | `https://aws-us-east-1.hevlayer.com` | | `--api-key` | `LAYER_API_KEY`, `HEVLAYER_API_KEY` | none | | `--env` | `LAYER_ENV` | active config env | | `-o`, `--output` | none | `table` | Output formats are `table`, `json`, and `names`. ## Environments ```sh layer env add partner --base-url https://aws-us-east-1.hevlayer.com \ --api-key "$LAYER_API_KEY" --kube-context partner-cluster \ --kube-namespace hevlayer layer env use partner layer env ls layer env show partner -o json layer env rm partner ``` `env add` prompts for missing values on a TTY. On a non-TTY, the required values must be supplied by flags. API keys are masked in `env ls` and `env show`. ## Initialize a Namespace ```sh layer init products --shards 8 layer init products --shards 8 --watch=false layer init products --shards 8 --poll-interval 5s ``` `init` calls `POST /v2/namespaces/{namespace}/init` through the selected gateway environment. The command creates or reattaches to the namespace shard marker, starts the shard backfill, and watches by default until `shard_lag_rows` reaches `0` and scatter/gather is active. Re-running with the same shard count is idempotent; requesting a different shard count returns a conflict message instead of changing the marker. ## Run A Function ```sh layer run -f tag-products.yaml layer run -f tag-products.yaml --index amazon-products-staging layer run -f tag-products.yaml --detach layer run -f tag-products.yaml --rm ``` The input is a Kubernetes `Function` manifest. `--index` overrides `spec.targetNamespaces` with one target. `--context` selects a kubeconfig context; `--kube-namespace` selects the Kubernetes namespace for the Function CR. `--no-apply` skips the Kubernetes apply step for workers managed outside the operator. `spec.version` is registered with the gateway as the Function completion marker version. Bump it before re-running a Function after changing a model, prompt, taxonomy, or worker write contract. `--detach` returns after registration and discovery. Without `--detach`, the CLI polls UDF status until discovery has completed and `pending_count` and `processing_count` are both zero. A drained queue with failures exits non-zero. `--rm` deletes the gateway registration and, unless `--no-apply` is set, the Function CR after the queue drains cleanly. A drain with failures leaves both in place so you can inspect them. Watch a run from another terminal: ```sh layer udf list layer udf get product-tags --watch ``` `udf list` lists registered UDFs with pending, processing, failed, discovery sweep count, and indexed rate. `udf get` shows those fields for one UDF; `--watch` polls until `pending_count` and `processing_count` are both zero. ## TUI Bare `layer` on a TTY opens the read-only operations TUI (`layer browse` is the explicit spelling); on a non-TTY it prints usage and exits `2`. Press `i`/`f`/`p`/`k`/`e` to switch between indexes, functions, pipelines, keys, and environments from any view, `enter` to open a detail view, and `esc`/`q` to back out. Every view has a non-interactive command twin with the same data — the TUI humanizes timestamps and sizes; the commands emit raw values for scripting. | TUI view | Command | | --- | --- | | Environments | `layer env ls` | | Functions | `layer udf list` | | Function detail | `layer udf get UDF_ID [--watch]` | | Indexes | `layer index list` | | Index detail | `layer index get NAME` | | Pipelines | `layer pipeline list` | | Pipeline detail | `layer pipeline get ID` | | Keys | `layer keys ls` | | Key detail | `layer keys get KEY_ID` | The keys views are read-only like the rest of the TUI: minting and revoking stay in the commands. ## Keys ```sh layer keys mint cohort-reader --owner acme \ --entitle vectorstore.prod-turbopuffer=read \ --namespaces "cohort-*" \ --claim warehouse.prod-snowflake="notes:cohort:*:read" layer keys ls layer keys get cohort-reader layer keys revoke cohort-reader layer keys rm cohort-reader ``` `keys mint` creates the key through the gateway and prints the token once — alone on stdout, so `layer keys mint … | pbcopy` captures it; the metadata table goes to stderr. There is no way to print it again. `keys revoke` is the default way to retire a key and keeps its audit record. `keys rm` is rare permanent cleanup and accepts only a key already in the `Revoked` phase. | Flag | Shape | | --- | --- | | `--entitle` | `TARGET[=SCOPE[+SCOPE]]`, repeatable. Targets are `vectorstore.`, `warehouse.`, or `layer`. | | `--namespaces` | Upstream-namespace globs for the vectorstore entitlement, comma-separated. | | `--claim` | `TARGET=STRING`, repeatable. Appends an opaque claim string to that target's entitlement. | | `--expires-after` | Duration or `never`; defaults to `365d`. | `--entitle layer=admin` mints an admin key. For anything longer than a couple of flags, write the object instead: `layer keys mint -f key.yaml` takes the same `ApiKey` manifest `kubectl apply` does. `keys ls` and `keys get` show metadata only — key id, owner, phase, entitlement targets, expiry, last seen — never tokens or hashes. `revoke` is idempotent and keeps the record; `rm` hard-deletes it. All `keys` commands call the gateway key routes, which require a key with the `layer` entitlement at `admin` scope (or the bootstrap gateway key); no kube access is involved. ## Vector Store And Warehouse ```sh layer vectorstore list layer vectorstore get layer vectorstore get prod-turbopuffer -o json layer warehouse list layer warehouse get prod-snowflake ``` `vectorstore list` shows declared stores with kind, default marker, region, reachability, and turbopuffer org id. `vectorstore get` prints endpoint, credential Secret reference, inbound auth mode, reachability, observed generation, and the turbopuffer dashboard link when the store has `spec.turbopuffer.orgId`. Without a name, `vectorstore get` selects the default-marked store, or the only store when exactly one exists. `warehouse list` leads with name, kind, phase, verification time, and consumer counts. `warehouse get NAME` shows the Snowflake source identity, credential Secret reference, verification status, failure reason, and what still depends on the warehouse. These commands are read-only and gateway-backed; they never read or print Secret contents. ## Ask The Docs `layer ask` queries the committed docs digest with the `ask` CLI. It is keyless and local by default: from a checkout, it finds `site/.hev-ask`, prefers a sibling `../ask` source checkout, and falls back to the docs site's installed `@hevmind/ask` package or an `ask` binary on `PATH`. ```sh layer ask tree layer ask grep "warm cache" layer ask cat api/query layer ask glossary get watermark layer -o json ask tree ``` Use `--endpoint` to query a deployed hev ask endpoint instead of the local digest: ```sh layer ask --endpoint https://hevlayer.com/api/ask tree ``` ## Inspect An Index ```sh layer index get shop-products layer index get shop-products -o json ``` `index get` reports row count, size, schema summary, last write, stable watermark and lag, index (WAL) status, cache state, and snapshot history. Timestamps and sizes are raw (epoch-ms, bytes); `-o json` carries the full snapshot list. ## Manage Snapshots ```sh layer index snapshot shop-products --field category layer index policy shop-products --facet-field category --facet-field brand --interval 5m --retention 30d ``` `index snapshot` creates an on-demand snapshot job and waits for it to complete. `index policy` writes the same `facetFields`, `interval`, and `retention` shape used by `Index.spec.snapshot`, so shared-gateway namespaces can enable the automatic writer without applying a Kubernetes resource. ## Delete An Index ```sh layer index delete shop-products layer index delete shop-products shop-products-staging layer index delete --prefix shop- layer index delete --prefix shop- --yes ``` `index delete` purges the upstream turbopuffer namespace, document cache rows and snapshot mirrors, S3 snapshots/search history/clickstream/shard metadata, in-memory job state, and the operator-discovered Index CR where GC is enabled. Pass one or more names, or `--prefix` to delete every index whose name starts with that prefix — name arguments and `--prefix` are mutually exclusive, and the prefix must be non-empty. The prefix form lists the matched indexes for confirmation before deleting; on a TTY it prompts, and `--yes` skips the prompt. `--yes` is required when stdin is not a TTY. A prefix that matches nothing exits `0` without deleting. ## Pipelines ```sh layer pipeline list layer pipeline get product-images ``` `pipeline list` reads registered pipelines and fans out to the [pipeline status API](/docs/api/pipelines#wait-for-completion) for each one's live queue depth (`pending`, `processing`, `failed`, `rate/min`); `pipeline get` adds target namespace, distance metric, and created-at. A pipeline with no worker staged into it yet renders without queue counts rather than erroring. Reads need only an API key — no kube access. `layer push` is deferred to the managed build/dev-loop milestone. --- # Dashboard Source: https://hevlayer.com/docs/dashboard import Callout from "../../components/docs/Callout.astro"; The Layer dashboard is the operator UI that ships in-cluster alongside the gateway, as the `layer-dashboard` Deployment and Service. This page covers running it: the access it needs, how to reach it, how to gate it, and how to turn it off. ## Access it needs The dashboard is read-mostly and backed by three sources, each with its own grant: - **The gateway API** — the same endpoints customers use, plus the Prometheus-compatible metrics proxy at `/v2/metrics`. Authenticated with a gateway bearer (`LAYER_GATEWAY_API_KEY`). In `deriveFromStore` mode this is the default `VectorStore` credential; in `keys` mode it is the configured inbound worker key. It does not touch PostgreSQL, Aerospike, or VictoriaMetrics directly — metrics and cost arrive through the gateway proxy and `/v2/cost`. - **The Kubernetes API** — reads `hevlayer.com` CRDs (VectorStores, Indexes, InfraRules, Pipelines) and the workload objects behind them (pods, deployments/statefulsets, HPAs, KEDA ScaledObjects, nodes) through RBAC bound to its ServiceAccount. `dashboard.kubeAccess.enabled` grants the read role; with it off the dashboard still runs but the cluster/scaling views show a "kube access not configured" banner. `dashboard.writeAccess.enabled` adds the operator write role: Index spec patches, Karpenter NodePool disruption, VectorStore and Warehouse create/edit, and namespace-scoped Secret writes for credentials. Set it `false` for a read-only install. - **Cost data** — the cost view reads the gateway cost API. turbopuffer spend is metered from upstream billing counters; AWS spend is read by the gateway from Cost Explorer using the gateway IRSA role. The dashboard does not need direct AWS cost API permissions for the standard cost view. In a Terraform install, still pass `dashboard.serviceAccount.roleArn` from the `layer_dashboard_role_arn` output so the dashboard ServiceAccount is annotated with its cluster-specific IRSA role at first boot. ## Networking The dashboard is an operator tool. **Reach it over a port-forward** rather than exposing it publicly: ```sh kubectl port-forward -n svc/layer-dashboard 8081:8081 ``` Then open `http://localhost:8081`. Customer workloads only ever receive the gateway base URL and credentials — never the dashboard. ## Basic auth HTTP Basic auth sits in front of every dashboard route and is **required** — the dashboard refuses to start without it. Set credentials through the chart: ```yaml dashboard: basicAuth: user: ops password: ``` The chart render fails if either field is blank while the dashboard is enabled. ## Disabling the dashboard The dashboard is optional. Disable it and the Deployment, Service, RBAC, and ingress all skip rendering: ```yaml dashboard: enabled: false ``` The gateway and transform runtime run unchanged without it; you lose only the operator UI. ## Operational notes ### Pipeline queue states The pipeline overview combines gateway queue counters with the matching `Pipeline` resources and their operator-managed Deployments and KEDA ScaledObjects. A queue with pending work is presented as: - **PAUSED** when every matching `Pipeline` has `spec.paused: true`. Its workers are intentionally at zero replicas; pending documents remain queued. - **CRON-GATED** when its cron ScaledObject is inactive. The card shows the next UTC window, scaler activity, and managed worker replica counts. - **STALLED** when work is pending with no processing or indexing activity and neither an intentional pause nor a closed cron window explains the stop. Failed-document counts, operator condition messages, and missing or inactive managed workers appear as reason hints on the same card. A growing queue that is still processing remains **BACKLOG** rather than **STALLED**. The **data** tab is split into indexes, vector store, and warehouse views. Indexes come from `/v2/namespaces`; vector stores and warehouses come from the gateway's `/v2/vectorstores` and `/v2/warehouses` projections, so the dashboard shows the same credential-safe shape as the CLI and SDKs. When write access is enabled, the vector store and warehouse panes can create and edit those CRDs. Raw credentials are accepted only in the form submission; the dashboard writes them into Kubernetes Secrets first, then creates or patches the CR. The read views keep showing only Secret references. The dashboard is intentionally read-mostly. Mutating actions (UDF pause, InfraRules or scaling edits, data-supply CRD apply) are gated through CRD apply or explicit confirm dialogs, and write access is governed separately by `dashboard.writeAccess.enabled`. --- # Introduction Source: https://hevlayer.com/docs/api/introduction import CodeTabs from "../../../components/docs/CodeTabs.astro"; import StoreSwitch from "../../../components/docs/StoreSwitch.astro"; import StoreNote from "../../../components/docs/StoreNote.astro"; import Upstream from "../../../components/docs/Upstream.astro"; import FeatureGate from "../../../components/docs/FeatureGate.astro"; Layer speaks the upstream store's native wire protocol, adding the fields it needs through `x-layer-*` headers, so pointing a client at the gateway just works — and gains stable reads, the document cache, and Layer's enhanced search features without changing the requests you already send. ## Install There are four ways to call Layer: the Python client, the Go client, the TypeScript client, and the REST API itself. The clients are generated from `apps/layer-gateway/openapi.yaml`, so all four expose the same operations — every endpoint page on this site shows them side by side. Anything the clients can do, plain HTTP can do. ```sh pip install hevlayer # Python 3.11+ go get github.com/hev/layer-go # Go 1.22+ npm install hevlayer # Node 18+ ``` Point a client at the gateway: ```python import os from hevlayer import AsyncHevlayer client = AsyncHevlayer( base_url=os.environ["LAYER_GATEWAY_URL"], api_key=os.environ["LAYER_GATEWAY_API_KEY"], ) ``` ```go import ( "os" hevlayer "github.com/hev/layer-go" ) client := hevlayer.NewClient( hevlayer.WithBaseURL(os.Getenv("LAYER_GATEWAY_URL")), hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")), ) ``` ```typescript import { Hevlayer } from "hevlayer"; const client = new Hevlayer({ baseUrl: process.env.LAYER_GATEWAY_URL, apiKey: process.env.LAYER_GATEWAY_API_KEY, }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` Code examples across these pages assume this `client` — and in Go, a `ctx context.Context`. The cURL tab on each page is the bare REST contract; any HTTP stack works the same way. ## Authentication Every request carries `Authorization: Bearer `. The gateway accepts two kinds of bearer: - **The store key.** The default `VectorStore` credential (the turbopuffer key you already own) is accepted as an admin bearer. This is the drop-in default for a turbopuffer-backed store: point an existing client at the gateway and keep your key. No setup, full access. - **A minted key.** Admin can mint keys scoped to a set of namespaces crossed with `read`/`write` — hand one to a team or a service without exposing the rest of the store. Minted keys are gateway-only and never work against the upstream directly. See [API keys](/docs/api/keys). Routes are classified `read`, `write`, or `admin`; each endpoint page notes anything beyond the obvious (GET/query-shaped routes are `read`, namespace writes are `write`, Pipeline/Function/key management is `admin`). A request past a key's scope or namespace grant answers 403 with the reason named. Connection environment variables: | Variable | Purpose | | --- | --- | | `LAYER_GATEWAY_URL` | Base URL of the gateway. | | `LAYER_GATEWAY_API_KEY` | Bearer token sent on every gateway request. In `deriveFromStore` mode this is the default `VectorStore` credential; in `keys` mode it is one of the configured inbound keys. | A turbopuffer-backed store also accepts a direct fallback for turbopuffer-compatible SDK calls when the gateway is unreachable: | Variable | Purpose | | --- | --- | | `TURBOPUFFER_API_KEY` | Optional direct fallback key. | | `TURBOPUFFER_API_URL` | Optional direct fallback base URL; defaults to `https://aws-us-east-1.turbopuffer.com`. | Additional language targets are added through the SDK harness rather than maintained by hand. ## Gateway failures The Python, Go, and TypeScript SDKs talk to the Layer gateway. If the gateway is unreachable, the original connection error is returned. SDKs do not retry directly against a backing store, because the server chooses that store from the namespace's `VectorStore` and the client surface stays backend-neutral. ## Enhancements to upstream routes Each of the routes below is wire-compatible with turbopuffer. The body of each section describes only what Layer overlays on top. ### Write — `POST /v2/namespaces/{ns}` Upstream contract for upsert, delete, and `patch_rows`. - Best-effort Aerospike document-cache mirror before explicit-id upstream writes. - Server-stamped `_hevlayer_upserted_at` on every upsert and patch, which powers the consistency watermark on the query path. - `_hevlayer_*` attributes are reserved — writes to them are rejected. Page: [Write](/docs/api/write). ### Query — `POST /v2/namespaces/{ns}/query` Upstream contract for vector and FTS queries — request shape, ranking, filters, attribute selection. - Stable reads via an injected `_hevlayer_upserted_at <= watermark` predicate while the upstream index is `updating`. - One-shot 429 retry with the watermark filter forced on, for queries that race a write storm. - `x-layer-stable-as-of` returned on stable-read responses so callers can correlate freshness across reads. Page: [Query](/docs/api/query). ### Metadata — `GET /v2/namespaces/{ns}/metadata` Upstream contract for namespace metadata — schema, row count, index status, timestamps. - Proxied upstream verbatim, then enriched with a `layer` block containing `stable_as_of` and `is_stable`. Page: [Namespace metadata](/docs/api/namespace-metadata). ### Cache warm hint — `GET /v1/namespaces/{ns}/hint_cache_warm` Upstream contract for the cache warm hint. - With no query parameters: a raw upstream passthrough, response returned verbatim. - With any warm option supplied: forwards the hint upstream and runs Layer-side warm steps — a warm job to backfill the Aerospike document cache from origin, plus a mirror of the latest S3 snapshot body into Aerospike. Each step is independently toggleable per request. Page: [Warm cache](/docs/api/warm-cache). ## Cross-cutting conventions These apply to every endpoint Layer proxies, whether the route is upstream-compatible or Layer-only. - **`_hevlayer_*` reserved.** Document attributes prefixed with `_hevlayer_` are reserved for the proxy layer. Writing to them is a validation error; reading them is fine when explicitly requested. The gateway stamps `_hevlayer_upserted_at` itself on every upsert and patch — a caller-supplied value is ignored and overwritten with the server's epoch-ms watermark. - **Hard vs soft failures.** The backing engine's write and query failures are hard failures and return 5xx. Aerospike document-cache failures are soft and never block the response. - **`x-layer-cache` header.** Fetch responses include `hit`, `miss`, or `miss-on-error` so callers can distinguish a cold cache from an outage. - **Response headers.** Query pagination uses `x-layer-next-cursor`. See [Response headers](/docs/api/response-headers). ## Compatibility posture Layer is a drop-in for existing turbopuffer clients. Routes the upstream does not implement are namespaced under `/v2/` and do not shadow upstream behavior; a request to a route Layer doesn't proxy returns 404 rather than being silently re-routed to an upstream that might handle it differently. --- # Write & Stage Source: https://hevlayer.com/docs/api/write import StoreSwitch from "../../../components/docs/StoreSwitch.astro"; import StoreNote from "../../../components/docs/StoreNote.astro"; import Upstream from "../../../components/docs/Upstream.astro"; import FeatureGate from "../../../components/docs/FeatureGate.astro"; import CodeTabs from "../../../components/docs/CodeTabs.astro"; This is Layer's write API: `POST /v2/namespaces/{ns}` with a native write body (upserts, deletes, patches, and filter writes, combined in one request), sent with `write_namespace`. Backed by turbopuffer, writes are wire-compatible with the upstream `POST /v2/namespaces/{ns}` endpoint and forwarded as-is after validation. The request body is documented upstream; the sections below are what Layer adds on top. Layer stamps every row-producing write with `_hevlayer_upserted_at` and mirrors it to the document cache. The stamp is what holds the [read watermark](/docs/api/query); the full set of reserved attributes Layer manages on a row lives in the [document model](/docs/document-model). ## Status Layer validates the body before forwarding and can fail independently of the backing store, so the write path carries a few statuses a plain proxy wouldn't: - **200 OK** — applied to the store and stamped. - **422 Unprocessable Entity** — Layer rejected the body before forwarding: no recognized native write operation, a reserved `_hevlayer_*` attribute name, a removed custom-write key, or a schema type the configured store cannot represent. The body is a Layer error (`{ "error": "validation_error", … }` or `{ "error": "UnsupportedByStore", … }`), not a store one. - **Upstream passthrough** — any non-2xx the backing store returns is relayed verbatim. - **502 Bad Gateway** — Layer could not reach the backing store (`{ "error": "upstream_error", … }`); the write did not apply. The passthrough case includes a failed conditional write (`upsert_condition`, `patch_condition`, `delete_condition`) — turbopuffer's error body comes back untouched. ## Stage Stage caches a document before it's upserted into your vector store. That O(1) read/write is especially useful for queuing chunks in a [two-stage pipeline](/docs/api/pipelines), where a CPU worker stages chunks and a GPU worker reads them back to write vectors. Staged documents are ephemeral until they're upserted, though — a Layer document cache outage loses anything still staged. ```python await client.put_pipeline_document_chunks("product-images", "asin-B08N5WRWNW", { "chunks": [ {"id": "asin-B08N5WRWNW-0", "text": "Wireless noise-cancelling headphones"}, {"id": "asin-B08N5WRWNW-1", "text": "40-hour battery life", "metadata": {"page": 2}}, ], }) ``` ```go client.PutPipelineDocumentChunks(ctx, "product-images", "asin-B08N5WRWNW", &hevlayer.PutChunksRequest{ Chunks: []hevlayer.Chunk{ {ID: "asin-B08N5WRWNW-0", Text: "Wireless noise-cancelling headphones"}, {ID: "asin-B08N5WRWNW-1", Text: "40-hour battery life", Metadata: map[string]interface{}{"page": 2}}, }, }) ``` ```typescript await client.putPipelineDocumentChunks("product-images", "asin-B08N5WRWNW", { chunks: [ { id: "asin-B08N5WRWNW-0", text: "Wireless noise-cancelling headphones" }, { id: "asin-B08N5WRWNW-1", text: "40-hour battery life", metadata: { page: 2 } }, ], }); ``` ```bash curl -X PUT "$LAYER_GATEWAY_URL/v2/pipelines/product-images/documents/asin-B08N5WRWNW" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chunks": [ {"id": "asin-B08N5WRWNW-0", "text": "Wireless noise-cancelling headphones"}, {"id": "asin-B08N5WRWNW-1", "text": "40-hour battery life", "metadata": {"page": 2}} ] }' ``` Staging stores chunks in the Aerospike document cache and marks the document `pending`. Re-staging the same document ID replaces the chunks and resets state to `pending`. The full pipeline API is documented under [Pipelines](/docs/api/pipelines). --- # Blobs Source: https://hevlayer.com/docs/api/blobs import CodeTabs from "../../../components/docs/CodeTabs.astro"; Blobs store opaque bytes in Layer's S3 bucket and serve them through the gateway with Aerospike as a pull-through hot cache. A row never stores the bytes themselves. It stores an ordinary string attribute such as `image_blob: "blob://products/"`. Use blobs for media or other binary payloads that must have a durable home outside the vector engine while still riding the gateway read path. ## Routes | Route | Method | Behavior | | --- | --- | --- | | `PUT /v1/namespaces/{ns}/blobs` | PUT | Store raw bytes by sha256 and return a `blob://` reference. | | `GET /v1/namespaces/{ns}/blobs/{sha256}` | GET | Serve bytes from Aerospike raw cache, falling back to S3 and backfilling cache. | ## Store ```python with open("image.jpg", "rb") as f: stored = await client.put_blob("products", f.read()) print(stored.ref) ``` ```go body, _ := os.ReadFile("image.jpg") stored, err := client.PutBlob(ctx, "products", body, nil) ``` ```typescript import fs from "node:fs/promises"; const bytes = await fs.readFile("image.jpg"); const stored = await client.putBlob("products", bytes); ``` ```bash curl -X PUT "$LAYER_GATEWAY_URL/v1/namespaces/products/blobs" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/octet-stream" \ --data-binary @image.jpg ``` Response: ```json { "ref": "blob://products/9f86d081884c7d659a2feaa0c55ad015...", "sha256": "9f86d081884c7d659a2feaa0c55ad015...", "size": 48213 } ``` The same bytes always return the same reference. The route rejects empty bodies and bodies over the gateway's blob size cap. Write the returned `ref` as a normal row attribute: ```json { "id": "B0123", "vector": [0.1, 0.2], "image_blob": "blob://products/9f86d081884c7d659a2feaa0c55ad015..." } ``` The removed document `blobs` payload shape is still rejected. Binary bytes do not traverse `/v2/namespaces/{ns}` writes. ## Fetch ```python image = await client.get_blob("products", stored.sha256) ``` ```go image, err := client.GetBlob(ctx, "products", stored.Sha256) ``` ```typescript const image = await client.getBlob("products", stored.sha256); ``` ```bash curl "$LAYER_GATEWAY_URL/v1/namespaces/products/blobs/$SHA256" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -o image.jpg ``` Successful responses include immutable cache headers: ```http Cache-Control: public, max-age=31536000, immutable ETag: "" ``` The gateway sniffs common image types (`jpeg`, `png`, `gif`, `webp`) for `Content-Type`; otherwise it returns `application/octet-stream`. ## Warm Policy Blob reads are pull-through today: cache miss reads S3, then backfills Aerospike best-effort. `PUT ...?warm=true` can write through to cache for one object. Bulk `hint_cache_warm?blobs=true` is intentionally not part of the first slice. It needs a namespace declaration for which attributes are blob references and an explicit cache budget because images are much larger than document attributes. --- # Query & Fetch Source: https://hevlayer.com/docs/api/query import CodeTabs from "../../../components/docs/CodeTabs.astro"; import StoreSwitch from "../../../components/docs/StoreSwitch.astro"; import StoreNote from "../../../components/docs/StoreNote.astro"; import Upstream from "../../../components/docs/Upstream.astro"; import FeatureGate from "../../../components/docs/FeatureGate.astro"; This is Layer's query API. Layer reports its own metadata in `x-layer-*` response headers. Backed by turbopuffer, Layer runs on top of your own turbopuffer namespace, adding stable reads, the document cache, and search history around it. The native query body — `vector`, `rank_by`, `filters`, and multi-query — is documented upstream; the sections below are what Layer adds on top. ## Stable reads Layer's query API defaults to [stable reads](/docs/concepts#control-loops). Every response carries an `x-layer-stable-as-of` watermark: the point the backing index is known to be caught up to. A query issued right after an upsert never returns partially-indexed rows and never 429s under write pressure, so derived views like [facets](/docs/api/snapshots) and [counts](/docs/api/scans) stay in sync with your index. ```http HTTP/1.1 200 OK x-layer-stable-as-of: 1715600400000 {"rows":[{"id":"asin-B08N5WRWNW","$dist":0.42,"title":"..."}]} ``` This is achieved by: 1. Queries run at `consistency=eventual` upstream, so they never block on indexing. 2. A [control loop](/docs/concepts#control-loops) polls each registered namespace's `index.status` and records the latest status plus, when stable, a watermark equal to `poll_start - safety_margin`. Cold or updating namespaces use the fast polling interval; stable namespaces back off to the stable interval until the next write re-arms the fast tier. 3. Per-query decision: - `Updating` → inject a hidden `_hevlayer_upserted_at <= watermark` predicate so the read never sees partially-indexed rows. - `Stable` or `Unknown` → run without the predicate. The upstream index is caught up (or no contrary evidence exists). 4. On a 429 to an unfiltered query, Layer retries once with the watermark filter forced on. Responses report `x-layer-stable-as-of` (epoch ms) when the watcher has a watermark for the namespace. It is omitted on a cold-start gateway that has not yet observed a stable poll. Query responses always carry a top-level `next_cursor` in the body — the next page token when more results may exist, or `null` on the last page — and mirror a non-null token in the `x-layer-next-cursor` header. Pass a non-null value back as `cursor` in the next request body. Native vector queries use a score-band cursor. Layer-fused `HybridText` and executed `Auto` routes use a bounded server-side re-fetch cursor, capped at 10,000 ranked rows. To pin a query to an explicit temporal cut, pass either `as_of` or `between` in the request body. `as_of: 1747300000123` conjoins `_hevlayer_upserted_at <= 1747300000123`; `between: [lo, hi]` conjoins `lo < _hevlayer_upserted_at <= hi`. They are mutually exclusive. Temporal selectors compose with `filters`, `nearest_to_id`, a top-level batch query, and the Layer `HybridText` / `Auto` rank expressions. Native turbopuffer passthrough bodies remain upstream-shaped and are not rewritten. Stable-read behavior is set per namespace with the `consistency` field on the [Index CRD](/docs/kubernetes/index-crd). Two gateway tunables control the watcher: | Variable | Default | Purpose | | --- | --- | --- | | `CONSISTENCY_POLL_INTERVAL_MS` | 1000 | Fast cadence for cold and updating namespaces. | | `CONSISTENCY_STABLE_POLL_INTERVAL_MS` | 60000 | Slow cadence for namespaces last observed stable. Set equal to the fast interval to restore one uniform cadence. | | `CONSISTENCY_SAFETY_MARGIN_MS` | 500 | Cushion between poll time and watermark to cover in-flight upserts. | ## Query by id Pass `nearest_to_id` in place of `vector` to rank by stored document vectors instead of a raw query vector — exactly one of the two is required. `nearest_to_id` takes an **array of document ids**: the gateway resolves each id's vector (document cache first, the namespace's configured VectorStore on miss with a cache backfill) and averages them component-wise into a single centroid, then ranks nearest neighbors to that centroid. Pass one id to rank by a single document; pass several to get "more like these" over a set of seeds. ```python response = await client.query_namespace("products", { "nearest_to_id": ["asin-B08N5WRWNW", "asin-B07PXGQC1Q"], "top_k": 10, "include_attributes": ["title", "category"], }) ``` ```go response, err := client.QueryNamespace(ctx, "products", &hevlayer.QueryRequest{ NearestToID: []string{"asin-B08N5WRWNW", "asin-B07PXGQC1Q"}, TopK: 10, IncludeAttributes: []string{"title", "category"}, }) ``` ```typescript const response = await client.queryNamespace("products", { nearest_to_id: ["asin-B08N5WRWNW", "asin-B07PXGQC1Q"], top_k: 10, include_attributes: ["title", "category"], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "nearest_to_id": ["asin-B08N5WRWNW", "asin-B07PXGQC1Q"], "top_k": 10, "include_attributes": ["title", "category"] }' ``` | Outcome | Status | | --- | --- | | Every id resolved (cache or origin) | 200, ranked results | | Any id has no stored vector anywhere | 404 (names the missing ids) | | `nearest_to_id` empty, or both/neither of `vector` / `nearest_to_id` | 422 | The centroid is an unweighted mean, so seed ids contribute equally regardless of how many you pass. All resolved vectors share the namespace's dimensionality, so no reconciliation is needed across seeds. This fuses the seeds into one ranking; to run several *independent* rankings in a single request, see [batch query](#batch-query). ## Rank expressions Pass `rank_by` with `top_k` when you need an explicit ranking operator instead of the top-level `vector` / `nearest_to_id` shape. Layer handles the portable subset with the same cache, history, and stable-read behavior as vector queries. Native upstream query bodies that omit `top_k` remain pass-through. `rank_by` is mutually exclusive with `vector` and `nearest_to_id`. ## Batch query `nearest_to_id` fuses several seeds into a **single** ranking. To run several **independent** queries in one round trip, each with its own ranking, post a `queries` array. The response is a parallel `results` array — one ranked result set per query, in request order: `{ "results": [{ "rows": ... }] }`. Layer holds every leg on the same stable cut, so a batch reads one consistent view of the index. (The method is `batch_query_namespace`. It is named apart from turbopuffer's own upstream multi-query — a `rerank_by` body, which Layer passes through unchanged, as noted at the end of this section — to keep the two distinct.) ```python batch = await client.batch_query_namespace("products", { "queries": [ {"rank_by": ["vector", "ANN", [0.1, 0.2, 0.3]], "top_k": 10}, {"rank_by": ["title", "BM25", "wireless earbuds"], "top_k": 10}, ], }) # batch.results[0].rows ranked by vector; batch.results[1].rows by text ``` ```go batch, err := client.BatchQueryNamespace(ctx, "products", &hevlayer.BatchQueryRequest{ Queries: []hevlayer.TurbopufferQueryRequest{ {"rank_by": []any{"vector", "ANN", []float64{0.1, 0.2, 0.3}}, "top_k": 10}, {"rank_by": []any{"title", "BM25", "wireless earbuds"}, "top_k": 10}, }, }) ``` ```typescript const batch = await client.batchQueryNamespace("products", { queries: [ { rank_by: ["vector", "ANN", [0.1, 0.2, 0.3]], top_k: 10 }, { rank_by: ["title", "BM25", "wireless earbuds"], top_k: 10 }, ], }); // batch.results[0].rows ranked by vector; batch.results[1].rows by text ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "queries": [ {"rank_by": ["vector", "ANN", [0.1, 0.2, 0.3]], "top_k": 10}, {"rank_by": ["title", "BM25", "wireless earbuds"], "top_k": 10} ] }' ``` All legs in a non-fused batch share one `x-layer-stable-as-of` value. A leg may use native `rank_by`, or the Layer `vector` / `nearest_to_id` single-query shape; `nearest_to_id` is resolved before the leg is sent upstream. Batches must contain 2 to 16 legs. `cursor` is rejected at the top level and per leg because pagination is single-query only. When `rerank_by` is present, Layer treats the request as an upstream fused query and passes the body through unchanged. Reach for a batch query when you genuinely need N rankings — distinct user queries batched into one round trip, or hybrid retrieval fused upstream with RRF. Reach for `nearest_to_id` when many seeds should collapse into one "more like these" ranking. To get typo-tolerant text search without building the fused query yourself, see [hybrid text fusion](#hybrid-text-fusion). Every leg here targets the namespace in the path. To fan one query across a **set** of namespaces — and merge them into a single ranked list — see [federated query](/docs/api/federated-query). ## Hybrid text fusion BM25 misses typos and morphological variants; fuzzy matching alone loses the relevance signal BM25 provides. `HybridText` runs both in one request: the gateway tokenizes your input string, expands it into one BM25 leg plus one fuzzy leg per token, and the effective legs are RRF-fused into one ranking. One expression in, typo-tolerant ranked results out. `HybridText` is a Layer-only `rank_by` spelling on the existing query route — no new endpoint, no client changes beyond the expression. The gateway tokenizes with [`alyze`](https://github.com/turbopuffer/alyze), turbopuffer's own open-source tokenizer and the same code that segmented your text at index time, so query tokens match index terms by construction. The ranked field must be indexed for both full-text and fuzzy matching — declare it `{"type": "string", "full_text_search": true, "fuzzy": true}` in the namespace schema. The BM25 leg uses the full-text index; the per-token fuzzy legs use the fuzzy index. ```python response = await client.query_namespace("support-tickets", { "rank_by": ["content", "HybridText", "conection timout kubernets"], "top_k": 10, "filters": ["tenant", "Eq", "t-42"], "include_attributes": ["content", "title"], }) ``` ```go response, err := client.QueryNamespace(ctx, "support-tickets", &hevlayer.QueryRequest{ RankBy: []any{"content", "HybridText", "conection timout kubernets"}, TopK: 10, Filters: []any{"tenant", "Eq", "t-42"}, IncludeAttributes: []string{"content", "title"}, }) ``` ```typescript const response = await client.queryNamespace("support-tickets", { rank_by: ["content", "HybridText", "conection timout kubernets"], top_k: 10, filters: ["tenant", "Eq", "t-42"], include_attributes: ["content", "title"], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/support-tickets/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rank_by": ["content", "HybridText", "conection timout kubernets"], "top_k": 10, "filters": ["tenant", "Eq", "t-42"], "include_attributes": ["content", "title"] }' ``` An optional fourth tuple element tunes the expansion. Defaults: ```json ["content", "HybridText", "conection timout kubernets", { "fuzziness": "auto", "rank_constant": 60, "per_leg_limit": null }] ``` | Option | Default | Meaning | | --- | --- | --- | | `fuzziness` | `"auto"` | Edit-distance tolerance for the fuzzy legs, keyed to each token's length (turbopuffer requires at least 3 query characters per edit). `"auto"` permits up to distance 2: exact for tokens of 3–5 characters, distance 1 for 6–8, distance 2 for 9 or more. Fixed `0`, `1`, or `2` caps the ladder, so `0` is exact-only. | | `rank_constant` | `60` | turbopuffer's RRF constant, passed through verbatim. Integer > 0. | | `per_leg_limit` | `clamp(5 × top_k, 50, 200)` | How deep each leg retrieves before fusion. Integer > 0. | | `threads` | `Index.spec.scan.threads`, else `8` | Maximum concurrent upstream requests when the gateway scatter/gathers the expansion across a [sharded](/docs/concepts#scattergather) namespace — the same fan-out control as [scans](/docs/api/scans). Clamped to active shards. No effect on unsharded namespaces, where the expansion is a single fused upstream call. | Set top-level `include_leg_breakdown: true` to return per-row `$fused.legs` attribution. Each leg entry reports the leg label, that row's 1-based rank within the leg, and the leg's raw score or distance. `rank` and `score` are `null` when the row fell outside that leg's `per_leg_limit` cut. Labels are `bm25`, `fuzzy:`, and `semantic` on routed fused queries. ### Tokenization The input string becomes tokens under a fixed, documented policy: 1. Split on Unicode (UAX #29) word boundaries and lowercase, using `alyze` — the code behind turbopuffer's production `word_v4` tokenizer. Punctuation-only tokens never survive the split. 2. Drop tokens shorter than 2 characters. 3. Dedupe. 4. Cap at 15 tokens (15 fuzzy legs + 1 BM25 leg = 16, the upstream subquery limit). Tokens cut by the cap are counted in `tokens_dropped`. Stemming, stopword removal, and language detection are not applied. The input must yield at least one token; one token is fine (that is still two legs, the RRF minimum). ### Response Results are the RRF-fused list. A `hybrid` block echoes the effective expansion so defaults are never invisible: ```json { "rows": [ { "id": "ticket-4117", "$score": 0.0639, "content": "...", "title": "Connection timeout on Kubernetes ingress" } ], "hybrid": { "tokens": ["conection", "timout", "kubernets"], "tokens_dropped": 0, "fuzziness": "auto", "rank_constant": 60, "legs": 4, "per_leg_limit": 50 }, "next_cursor": null } ``` | Field | Meaning | | --- | --- | | `$score` | RRF score. Comparable **within** a response, not across requests — do not threshold on it. | | `$fused.legs` | Present only when `include_leg_breakdown: true`. Per-leg attribution in effective leg order; each item has `leg`, `rank`, and `score`. | | `tokens` | Tokens that produced fuzzy legs, post-policy. | | `tokens_dropped` | Tokens removed by the 15-token cap (not by the length or punctuation rules). | | `legs` | Total effective subqueries in the fused expansion. Normally the fuzzy legs + 1 BM25 leg (plus 1 ANN leg on routed fused queries). On the `surfaced` fallback there is no BM25 leg, so `legs` equals the token count (one fuzzy leg per token). | | `surfaced` | Present and `true` only when the empty-result fallback fired (see [Surfacing fallback](#surfacing-fallback)). Absent on the normal path. | | `next_cursor` | Top-level field (not inside `hybrid`), always present in the body: the next page token, or `null` on the last page. Mirrors the `x-layer-next-cursor` header. Pass a non-null value back as `cursor`. | The `hybrid` block appears only on `HybridText` responses. On sharded namespaces it also reports the effective `threads` fan-out width. Requests without a `HybridText` expression, including native turbopuffer multi-query + `rerank_by` bodies, keep their upstream-shaped responses byte-for-byte. ### Surfacing fallback Every primary leg ranks by BM25 over the full input, which upstream scores at zero — and drops — when no token matches a stored term exactly. A fully-misspelled query therefore fuses to zero rows. When the primary expansion returns nothing, Layer re-runs one fuzzy leg per token, reorders each leg by field/token edit distance, and fuses those instead, so a typo-heavy query still surfaces near matches. The response then carries `"surfaced": true` in the `hybrid` block, and `legs` reflects the surfacing expansion — one fuzzy leg per token, with no BM25 leg. Working queries never reach this path; the fallback is purely additive and absent (`surfaced` omitted) on the normal path. ### Semantics - **Fusion.** RRF uses the effective leg order: BM25 first, then one fuzzy leg per token, then the semantic ANN leg on routed fused queries. `include_leg_breakdown: true` can require one upstream query per leg on unsharded namespaces so Layer can report per-leg ranks. - **One consistency cut.** Request-level `filters` are replicated to every leg, and the [stable-read](#stable-reads) watermark predicate is injected into every leg from a single read — all legs see the same cut. Responses carry `x-layer-stable-as-of` as usual. - **All-or-nothing.** Any leg failure fails the request; Layer does not return a partial fusion over surviving legs. - **Replay as a unit.** The query logs to [search history](/docs/api/search-history) as one entry carrying the `HybridText` expression, so replaying it reproduces the whole expansion. ### Validation All return `422`: | Condition | Why | | --- | --- | | Input yields zero tokens under the policy | Nothing to expand. | | `HybridText` inside a `queries` array | The expansion is already one batch deep by construction. | | `fuzziness` not in `"auto" \| 0 \| 1 \| 2`; `rank_constant` ≤ 0; `per_leg_limit` ≤ 0; `threads` < 1 | Out of range. | To let the gateway pick between hybrid text and semantic retrieval per query, see [query routing](#query-routing). ## Query routing Real search boxes receive both `"timout"` and `"why do pods lose their connection during deploys"`. The first wants [hybrid text fusion](#hybrid-text-fusion); the second wants semantic retrieval — lexical legs add noise on long conversational input, and ANN underperforms on short identifier-shaped tokens. `Auto` is a Layer-only `rank_by` spelling that makes that call per query, so the branch doesn't live ad hoc in your application code. The gateway never embeds. The route is chosen from the shape of the input alone, and when the chosen route needs a query vector the request didn't include, the response is the routing decision instead of results — your application embeds and re-issues with the route forced. Short keyword traffic executes immediately and never pays for an embedding. ```python response = await client.query_namespace("support-tickets", { "rank_by": ["content", "Auto", user_input], "top_k": 10, "filters": ["tenant", "Eq", "t-42"], }) if not response.routing.executed: vector = await embed(user_input) # your model or API response = await client.query_namespace("support-tickets", { "rank_by": ["content", "Auto", user_input, { "route": response.routing.route, "vector": vector, }], "top_k": 10, "filters": ["tenant", "Eq", "t-42"], }) ``` ```go response, err := client.QueryNamespace(ctx, "support-tickets", &hevlayer.QueryRequest{ RankBy: []any{"content", "Auto", userInput}, TopK: 10, Filters: []any{"tenant", "Eq", "t-42"}, }) if err == nil && !response.Routing.Executed { vector := embed(userInput) // your model or API response, err = client.QueryNamespace(ctx, "support-tickets", &hevlayer.QueryRequest{ RankBy: []any{"content", "Auto", userInput, map[string]any{ "route": response.Routing.Route, "vector": vector, }}, TopK: 10, Filters: []any{"tenant", "Eq", "t-42"}, }) } ``` ```typescript let response = await client.queryNamespace("support-tickets", { rank_by: ["content", "Auto", userInput], top_k: 10, filters: ["tenant", "Eq", "t-42"], }); if (!response.routing.executed) { const vector = await embed(userInput); // your model or API response = await client.queryNamespace("support-tickets", { rank_by: ["content", "Auto", userInput, { route: response.routing.route, vector, }], top_k: 10, filters: ["tenant", "Eq", "t-42"], }); } ``` ```bash # First request: no vector. Executes lexically, or returns the decision. curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/support-tickets/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rank_by": ["content", "Auto", "why do pods lose their connection during deploys"], "top_k": 10, "filters": ["tenant", "Eq", "t-42"] }' # Routed semantic without a vector, so the body is the decision, not rows: # {"rows": [], "routing": {"route": "semantic", "policy": "v1", "tokens": 8, "executed": false}} # Embed, then re-issue with the route forced: curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/support-tickets/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "rank_by": ["content", "Auto", "why do pods lose their connection during deploys", { "route": "semantic", "vector": [0.0012, -0.043] }], "top_k": 10, "filters": ["tenant", "Eq", "t-42"] }' ``` ### Routing policy The v1 policy reads the token count of the input under the same [tokenizer policy](#tokenization) as hybrid text fusion: | Tokens | Route | Runs | | --- | --- | --- | | ≤ 2 | `hybrid_text` | The [hybrid text fusion](#hybrid-text-fusion) expansion. | | ≥ 8 | `semantic` | ANN over the supplied query vector. | | 3 – 7 | `fused` | Both, merged upstream by RRF. | Vector availability never changes which route is chosen — only whether it executes in this request. `hybrid_text` always executes; `semantic` and `fused` execute when the request supplies a `vector` and defer otherwise. The policy is versioned (`"policy": "v1"`) so threshold changes are visible in [search history](/docs/api/search-history). ### Options The optional fourth tuple element: | Option | Default | Meaning | | --- | --- | --- | | `route` | `"auto"` | Force `"hybrid_text"`, `"semantic"`, or `"fused"` instead of applying the policy. Used on re-issue after a deferral, and for A/B comparison of strategies on the same input. | | `vector` | — | The query vector for the semantic leg. Dimensionality must match the namespace. | | `fuzziness` | `"auto"` | Forwarded to the `HybridText` expansion on the `hybrid_text` and `fused` routes: `"auto"`, `0`, `1`, or `2`. `0` forces exact-only matching. No effect on the `semantic` route. | When the chosen route expands hybrid-text legs, the hybrid defaults apply and the [`hybrid` echo block](#response) appears alongside `routing`. Set top-level `include_leg_breakdown: true` to add `$fused.legs` to each fused row; the fused route includes a final `semantic` leg after the BM25 and fuzzy-token legs. ### Response Every `Auto` response carries a `routing` block: ```json { "rows": [{"id": "ticket-4117", "$score": 0.0639, "title": "..."}], "routing": { "route": "hybrid_text", "policy": "v1", "tokens": 1, "executed": true }, "hybrid": {"tokens": ["timout"], "tokens_dropped": 0, "fuzziness": "auto", "rank_constant": 60, "legs": 2, "per_leg_limit": 50} } ``` | Field | Meaning | | --- | --- | | `route` | The strategy chosen (or forced). | | `policy` | Routing policy version that made the decision. `"forced"` when `route` was supplied. | | `tokens` | Token count the policy read, post tokenizer policy. | | `executed` | `false` on a deferral: the route needs a vector the request didn't supply. `rows` is empty; embed and re-issue with the route forced. | Routed queries follow the same semantics as their underlying strategy: one consistency cut across all legs, all-or-nothing leg failure, and a single [search history](/docs/api/search-history) entry carrying the `Auto` expression and the decision. ### Validation All return `422`: | Condition | Why | | --- | --- | | Forced `"semantic"` or `"fused"` without `vector` | Forcing asserts you have the vector; only auto-routing defers. | | Input yields zero tokens under the policy | Nothing to route. | | `vector` dimensionality mismatch | Same check as a plain vector query. | | `Auto` inside a `queries` array | Inherited from [hybrid text fusion](#validation). | ## Counting matches To count how many rows match a full-text or vector query, use [scan](/docs/api/scans) count mode with the `fts` or `ann` selector. Ranked counts share the single `/scans` endpoint with filter counts — `fts` is exact, `ann` is a radius scan flagged `approximate`, and both honor the `exhaustive` flag and the count deadline. ## Fetch Fetch is a Layer-only endpoint with no upstream equivalent. The document cache is checked first; on miss or error the gateway falls through to the backing store and backfills the cache best-effort. ### Single fetch ```python doc = await client.fetch_document( "products", "asin-B08N5WRWNW", include_attributes=["title", "category"], ) ``` ```go doc, err := client.FetchDocument(ctx, "products", "asin-B08N5WRWNW", &hevlayer.FetchDocumentParams{ IncludeAttributes: []string{"title", "category"}, }) ``` ```typescript const doc = await client.fetchDocument("products", "asin-B08N5WRWNW", { includeAttributes: ["title", "category"], }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/documents/asin-B08N5WRWNW?include_attributes=title,category" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` | Outcome | Status | Header | | --- | --- | --- | | Cached hit | 200 | `x-layer-cache: hit` | | Cache miss, upstream hit, cache backfilled | 200 | `x-layer-cache: miss` | | Cache unavailable, upstream hit | 200 | `x-layer-cache: miss-on-error` | | Missing from both layers | 404 | — | ### Batch fetch ```python batch = await client.fetch_documents("products", { "ids": ["asin-1", "asin-2", "asin-3"], "include_attributes": ["title"], }) ``` ```go batch, err := client.FetchDocuments(ctx, "products", &hevlayer.FetchDocumentsRequest{ Ids: []string{"asin-1", "asin-2", "asin-3"}, IncludeAttributes: []string{"title"}, }) ``` ```typescript const batch = await client.fetchDocuments("products", { ids: ["asin-1", "asin-2", "asin-3"], include_attributes: ["title"], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/documents" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ids": ["asin-1", "asin-2", "asin-3"], "include_attributes": ["title"] }' ``` ```json { "documents": [ {"id": "asin-1", "attributes": {"title": "..."}}, {"id": "asin-3", "attributes": {"title": "..."}} ], "missing": ["asin-2"] } ``` Batch fetch returns found documents and missing ids inline instead of a partial 404. `documents` preserves request order; ids the gateway could not find anywhere land in `missing`. Because order is preserved, batch fetch is a convenient way to reassemble a [pipeline](/docs/api/pipelines)'s chunks back into their original document — request the chunk ids in sequence and concatenate the results. ### Behavior matrix | Cache state | Single fetch | Batch fetch | | --- | --- | --- | | Hit | cache | cache | | Miss, upstream present | upstream + backfill | upstream + backfill | | Miss, upstream absent | 404 | inline `missing` | | Cache unavailable | upstream, `miss-on-error` | upstream, `miss-on-error` | --- # Federated query Source: https://hevlayer.com/docs/api/federated-query import CodeTabs from "../../../components/docs/CodeTabs.astro"; A **federated query** runs one query across a **set** of namespaces. `POST /v2/query` is namespace-less: the per-namespace [query endpoint](/docs/api/query) names its namespace in the path, while this endpoint takes the set in the body, so the namespace is no longer a path parameter. It has no upstream equivalent — turbopuffer's multi-query is single-namespace, so the fan-out and the merge are a Layer composition over per-namespace reads. One ranking is spread across every namespace in the set and merged into a single ranked list — "search my whole feed / my whole library." For several **independent** rankings instead, query each namespace separately; a federated query always returns one fused list. ## Fan-out and fuse Supply one ranking and a `namespaces` set. The gateway runs the ranking against each namespace and returns one merged `rows` list, each row tagged with the namespace it came from. ```python response = await client.query({ "namespaces": ["moment-pod-changelog", "moment-pod-latent-space", "moment-pod-no-priors"], "rank_by": ["text", "Auto", "evaluating RAG systems"], "top_k": 12, "filters": ["published_at", "Gte", 1740000000], "include_attributes": ["text", "show", "source_url", "start_sec"], }) ``` ```go response, err := client.Query(ctx, &hevlayer.FederatedQueryRequest{ Namespaces: []string{"moment-pod-changelog", "moment-pod-latent-space", "moment-pod-no-priors"}, RankBy: []any{"text", "Auto", "evaluating RAG systems"}, TopK: 12, Filters: []any{"published_at", "Gte", 1740000000}, IncludeAttributes: []string{"text", "show", "source_url", "start_sec"}, }) ``` ```typescript const response = await client.query({ namespaces: ["moment-pod-changelog", "moment-pod-latent-space", "moment-pod-no-priors"], rank_by: ["text", "Auto", "evaluating RAG systems"], top_k: 12, filters: ["published_at", "Gte", 1740000000], include_attributes: ["text", "show", "source_url", "start_sec"], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "namespaces": ["moment-pod-changelog", "moment-pod-latent-space", "moment-pod-no-priors"], "rank_by": ["text", "Auto", "evaluating RAG systems"], "top_k": 12, "filters": ["published_at", "Gte", 1740000000], "include_attributes": ["text", "show", "source_url", "start_sec"] }' ``` `rank_by` accepts the same vocabulary as a single-namespace query, including the Layer [`HybridText`](/docs/api/query#hybrid-text-fusion) and [`Auto`](/docs/api/query#query-routing) expressions. The query text is identical across the fan-out, so `Auto` routes **once** and the chosen route runs against every namespace — a single `routing` block is echoed. `filters` apply to every namespace. Name the explicit set to search, or pass `namespaces: ["*"]` to expand the authenticated key's namespace allowlist at request time. Omitting `namespaces` is equivalent to `["*"]`. ### Response One fused list. Each row carries `$namespace` (its origin) and `$rank` (its position within that namespace's results — the key the merge orders on). A `merge` block names the strategy, and a `namespaces` block reports each namespace's freshness and how many rows it returned to the merge. ```json { "rows": [ { "id": "ep123#7", "$namespace": "moment-pod-latent-space", "$rank": 1, "$score": 11.4, "show": "Latent Space", "text": "..." } ], "merge": { "method": "rank-interleave", "route": "fused" }, "routing": { "route": "fused", "policy": "v1", "tokens": 3, "executed": true }, "hybrid": { "tokens": ["evaluating", "rag", "systems"], "tokens_dropped": 0, "fuzziness": "auto", "rank_constant": 60, "legs": 4, "per_leg_limit": 60 }, "namespaces": [ { "namespace": "moment-pod-latent-space", "stable_as_of": 1747300000123, "matched": 14 }, { "namespace": "moment-pod-changelog", "stable_as_of": 1747299999001, "matched": 9 }, { "namespace": "moment-pod-no-priors", "stable_as_of": 1747300000050, "matched": 0 } ] } ``` | Field | Meaning | | --- | --- | | `$namespace` | The namespace this row came from. | | `$rank` | The row's 1-based rank **within its namespace**. The merge orders on this on a text route; see [Merge](#merge). | | `$score` / `$dist` | The row's native score within its namespace, carried as provenance. Comparable **within** a namespace, not across the fused list — do not threshold on it. On a vector route `$dist` is the merged ordering key and *is* globally comparable. | | `merge` | The merge applied. `method` is `"distance"` on a vector route, `"rank-interleave"` on a text route; `route` is currently always `"fused"` (reserved for future route-specific provenance). | | `namespaces` | Per-namespace echo: each reached namespace's `stable_as_of` watermark and `matched` — the rows it **returned to the merge** (up to [`per_namespace_limit`](#fusion-options)), not its surviving share of the final `top_k`. A namespace that matched nothing reports `matched: 0`. | `routing` and `hybrid` echo exactly as they do for a single-namespace [`Auto`](/docs/api/query#query-routing) / [`HybridText`](/docs/api/query#response) query, since the route runs once for the whole fan-out. ### Fusion options | Option | Default | Meaning | | --- | --- | --- | | `fusion.per_namespace_limit` | `clamp(2 × top_k, 10, 100)` | How many rows each namespace returns to the merge. Shallower than the single-namespace `per_leg_limit`: across a wide fan-out most namespaces contribute nothing to the final `top_k`, so deep per-namespace retrieval is wasted. Integer > 0. | | `fusion.rank_constant` | `60` | Reserved for route-dependent fusion tuning. It is accepted for forward compatibility and is inert in the current gateway. | ## Entitlements The `namespaces` set uses the same store-derived authentication path as individual namespace queries: the upstream key must be able to read each listed namespace. A namespace read failure is reported under [partial failure](#partial-failure) unless `strict` is enabled. For minted scoped keys, explicitly named namespaces must be inside a `vectorstore.` read grant. Naming a namespace outside the grant is a hard `403`, not a partial result. `namespaces: ["*"]` expands by listing upstream namespaces and filtering them through the key's vectorstore namespace globs, so the key is the feed/library set and the client does not enumerate it. ## Filters One `filters` expression is applied to **every** namespace in the set, and each namespace evaluates it independently against its own schema. So a filter only behaves uniformly when the attributes it references are part of a **shared filterable schema** across the set — present in every namespace, with the same type, and declared filterable. This is the filter analog of the [shared embedding space](#vector-merge-requires-a-matching-embedding-space) a vector merge needs: a federated query is only as coherent as the contract its namespaces share. A namespace that cannot evaluate the filter — the attribute is absent, has an incompatible type, or is not filterable there — is reported as `filter_schema_mismatch`, not as `matched: 0`. This is a per-namespace validity failure: the namespace did not participate in the filtered ranking because it could not evaluate the predicate. In default best-effort mode, the namespace is omitted from `rows`, listed in `errors`, and the response carries `x-layer-partial: true`. With `strict: true`, the whole request fails with `422`. This docs contract selects `422` for the strict-mode failure because the namespace set and filter expression are valid only if every required namespace can evaluate the filter. A feed or library assembled from namespaces indexed by one pipeline shares a filterable schema by construction, so this is invisible in the common case. The contract bites when a set spans heterogeneously-indexed namespaces — keep a filter to attributes the whole set declares, or scope the set to namespaces that share them. ## Merge A federated query merges by the quantity the route makes comparable across namespaces: - **Vector route** (`ANN` over a query vector) — distances are comparable across namespaces that share an embedding space, so the gateway merges by `$dist` and the fused order is the exact global nearest-neighbor ranking. `merge.method` is `"distance"`. - **Text route** (`BM25`, `HybridText`, or a routed `fused`/`hybrid_text`) — BM25 and hybrid scores are **not** comparable across corpora (different term statistics; a hybrid `$score` is already a per-namespace fusion). The gateway merges by **rank-interleave**: rows are ordered by their `$rank` within their namespace, ties broken by `id`. `merge.method` is `"rank-interleave"`. No single pod dominates the head of the list; each contributes its best matches in rank order. The fused list exposes `$rank` as the ordering key and carries each row's native `$score` only as provenance. `top_k` truncates the merged list. Each namespace returns [`fusion.per_namespace_limit`](#fusion-options) rows to the merge. ### Vector merge requires a matching embedding space Merging by distance is only meaningful when every namespace in the set embeds into the same geometry. Declare each namespace's embedding identity with [`spec.embedding`](/docs/kubernetes/index-crd#embedding) on its `Index` — model, output dimension, and normalization, alongside the existing `spec.backend.distanceMetric`. The gateway compares those profiles before a vector fan-out uses distance merge: - All reached namespaces have the same profile → `merge.method: "distance"`. - A profile is missing or differs → best-effort responses downgrade to `merge.method: "rank-interleave"` and include `merge.downgraded_reason` (`"missing_embedding_profile"` or `"embedding_profile_mismatch"`). - With `strict: true`, a missing or mismatched profile is a `422`. A text fan-out is rank-interleave regardless, so embedding profiles do not affect it. ## Consistency Each namespace has its own [stable-read](/docs/api/query#stable-reads) watermark; there is no single consistent cut across independent namespaces. The `namespaces` block reports each namespace's `stable_as_of`, and the response header `x-layer-stable-as-of` carries the **minimum** across the reached namespaces — the most conservative answer to "as of when." Layer does not manufacture a global watermark. ## Partial failure Across many namespaces, one may be deleted, time out, error upstream, or fail to evaluate the [filter](#filters). Unlike single-namespace [multi-query](/docs/api/query#multi-query), the fan-out defaults to **best-effort**: it returns the namespaces that succeeded, lists the rest in an `errors` block, and sets `x-layer-partial: true`. A feed search does not blank because one pod is briefly unavailable. ```json { "rows": [ "..." ], "errors": [ { "namespace": "moment-pod-no-priors", "error": "Upstream error: namespace not found" } ] } ``` Availability failures carry a human-readable upstream message in `error`, not a stable machine code — match on `namespace`, not on the `error` string. Filter schema mismatches are the exception: they carry the stable `code: "filter_schema_mismatch"` plus a human-readable `detail` so clients can separate "namespace unavailable" from "namespace cannot evaluate this filter." ```json { "rows": [ { "id": "ep123#7", "$namespace": "moment-pod-latent-space", "$rank": 1 } ], "errors": [ { "namespace": "moment-pod-no-priors", "code": "filter_schema_mismatch", "error": "filter schema mismatch", "detail": "filter attribute published_at is absent, not filterable, or has an incompatible type" } ] } ``` Set `"strict": true` to opt into fail-fast: any namespace error fails the whole request. Reach for it when a missing namespace would make the result misleading rather than merely thinner. ## Limits | Limit | Value | | --- | --- | | Namespaces per request | 512. Over the cap → `422` naming the excess. | | Pagination | Not supported. `cursor` is rejected — a fused cursor across independent namespaces does not form the monotone bands pagination relies on. | ## Validation | Condition | Status | | --- | --- | | A named namespace is outside the minted key's namespace grant | 403 | | A namespace read fails upstream | 200 with `errors`, or 502 with `strict: true` | | A namespace cannot evaluate `filters` (attribute absent, wrong type, or not filterable) | 200 with `errors[].code: "filter_schema_mismatch"` and `x-layer-partial: true`, or 422 with `strict: true` | | `namespaces` is empty | 422 | | `namespaces: ["*"]` mixed with other names | 422 | | `namespaces` set exceeds the cap | 422 | | Vector route missing/mismatched embedding profiles with `strict: true` | 422 | | `cursor` present | 422 | | `rank_by` expression invalid | 422 (same checks as a single-namespace query) | --- # Agentic search Source: https://hevlayer.com/docs/api/agents import CodeTabs from "../../../components/docs/CodeTabs.astro"; **Agentic search** runs a configured reasoning loop over one or more namespaces and returns the same row shape as every other search endpoint. A model reads the query, fans out diverse phrasings in parallel via layer's [scatter/gather](/docs/concepts#scattergather), ranks the candidates for relevance, and returns a ranking fused from both signals. It is a better-ranked result set, not a generated answer — the response is the [federated query](/docs/api/federated-query#response) shape, so any client that reads `/v2/query` reads this with no changes. The endpoint names a configured [`Agent`](/docs/kubernetes/agent-crd) in the path. The model, the turn budget, the indices, and the output shaping are bound on that resource, so the request body is just a query, an optional query embedding, and a result count. ``` POST /v2/agents/{name}/query ``` ## Request ```python response = await client.agent("support-search").query({ "query": "auth errors after the june upgrade", "top_k": 20, }) ``` ```go response, err := client.Agent("support-search").Query(ctx, &hevlayer.AgentQueryRequest{ Query: "auth errors after the june upgrade", TopK: 20, }) ``` ```typescript const response = await client.agent("support-search").query({ query: "auth errors after the june upgrade", top_k: 20, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/agents/support-search/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "auth errors after the june upgrade", "top_k": 20 }' ``` | Field | Purpose | | --- | --- | | `query` | The natural-language query. The agent reformulates it; you do not pre-shape it into a route expression. | | `vector` | Optional. The embedding of `query`, used for the agent's semantic recall leg. See [Bring your own embedding](#bring-your-own-embedding). | | `top_k` | Rows to return after fusion. | The model, fan-out, fusion weighting, and output are bound on the [`Agent`](/docs/kubernetes/agent-crd), which keeps the request trivial and makes the agent the single source of truth for what a call costs and what it can read. `query` and `vector` are the only request inputs, and they are data, not config — there are no per-request overrides of the agent's configured behavior. ### Bring your own embedding The agent fans out for recall over both routes: a lexical leg on your query text and a semantic leg on a query vector. Layer never embeds query text — you supply the vector, the same bring-your-own-embedding contract as [`/v2/query`](/docs/api/query). Pass it as `vector`: ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/agents/support-search/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "auth errors after the june upgrade", "vector": [0.0123, -0.0456, 0.0789], "top_k": 20 }' ``` `vector` is the embedding of `query`. The agent uses this one vector for every planned semantic leg — it does not embed the reformulated phrasings, so the vector carries the query's semantic intent while the text reformulations broaden lexical recall. Embed `query` with the same model your indices were embedded with, and match their dimensionality. Omit `vector` and the agent's semantic legs fall back to the lexical route: recall runs on the reformulations alone, which is the right behavior when an index has no vector column or you have no embedder on the client. ## Response The response is the [federated query](/docs/api/federated-query#response) shape: `rows` each carrying `$namespace`, `$rank`, and a native `$score`/`$dist`, plus a `merge` block and a `namespaces` block. The merge names the dual-score fusion. ```json { "rows": [ { "id": "T-4821", "$namespace": "tickets", "$rank": 1, "$score": 9.7, "subject": "SSO login fails after upgrade" } ], "merge": { "method": "weighted-rrf", "route": "dual-score" }, "namespaces": [ { "namespace": "tickets", "stable_as_of": 1747300000123, "matched": 20 } ] } ``` By default the response is byte-shape-identical to a [federated query](/docs/api/federated-query): a client cannot tell whether a reasoning loop produced it. Set [`output.provenance`](/docs/kubernetes/agent-crd#output) on the agent to surface the scores. ### Provenance and trace With provenance on, the response gains an `agent` echo and each row carries a `$agent` field with both scores: ```json { "rows": [ { "id": "T-4821", "$namespace": "tickets", "$rank": 1, "$score": 9.7, "$agent": { "retrievalScore": 3, "relevanceScore": 0.92, "query": "authentication failure post-upgrade", "queryIndex": 0 } } ], "merge": { "method": "weighted-rrf", "route": "dual-score" }, "namespaces": [ { "namespace": "tickets", "stable_as_of": 1747300000123, "matched": 20 } ], "agent": { "turns": 2, "deadlineHit": false, "recallDepth": 50, "relevanceWeight": 0.6, "queries": [ { "namespaces": ["tickets"], "rankBy": "hybridText", "query": "authentication failure post-upgrade", "filters": { "created_at": { "$gte": "2026-06-01" } } } ] } } ``` | Field | Meaning | | --- | --- | | `$agent.retrievalScore` | The row's rank within the leg that first surfaced it — the per-query position (1-based; lower is better), not the fused-pool rank. With `fanout` > 1 a row can appear in several legs; this records the first leg's rank. The fused recall signal is computed separately (RRF over every leg the row appeared in). | | `$agent.relevanceScore` | The model's graded relevance for the row (the precision signal). | | `$agent.query` | The planned variant that first surfaced the row. | | `$agent.queryIndex` | Zero-based index of that planned variant in `agent.queries`. | | `agent.turns` | Model turns the call spent. | | `agent.deadlineHit` | True when the deadline ended the request early and returned the best ranking so far. | | `agent.queries` | The planned variants: route, reformulated text, and inferred filters. | With [`output.trace`](/docs/kubernetes/agent-crd#output) the `agent` echo also carries the full reasoning trace. The trace is written to the [search-history](/docs/api/search-history) record whether or not it is echoed, so agentic and plain searches share one surface for evaluation. ## Auth Auth follows the same model as the other API endpoints; multi-namespace queries follow [federated query](/docs/api/federated-query#entitlements) auth behavior. A minted key additionally needs an `agent.` entitlement on its [ApiKey](/docs/kubernetes/apikey-crd#entitlements) to invoke the agent. ## Configuration Everything the request omits is bound on the [`Agent`](/docs/kubernetes/agent-crd) resource: the model and its credential, the deadline, the indices, the fan-out and fusion weighting, and the output shaping. `kubectl get agent -o yaml` and `client.agent("support-search").apply()` are two spellings of the same object. ## Validation | Condition | Status | | --- | --- | | `{name}` is not a known, `Ready` agent | 404 | | The minted key lacks the `agent.` entitlement | 403 | | A bound index is outside the key's namespace grant | 403 | | `query` is empty | 422 | | `vector` is present and its dimensionality does not match the bound indices' vector schema | 422 | | Deadline hit with `onDeadline: bestEffort` | 200, best ranking so far, `agent.deadlineHit: true` | | Deadline hit with `onDeadline: error` | 504 | | The provider is unreachable on both primary and fallback | 502 | --- # Scan Source: https://hevlayer.com/docs/api/scans import CodeTabs from "../../../components/docs/CodeTabs.astro"; A scan is on-demand row selection over a namespace. It picks rows by one of four **selectors** and returns their IDs (`mode: ids`, an asynchronous job), their count (`mode: count`, synchronous), or the distinct values of one attribute field (`mode: values`, an asynchronous job): | Input | Field | Meaning | Notes | | --- | --- | --- | --- | | Filter selector | `filters` | An attribute predicate, or all rows when omitted. | Exact | | Full-text selector | `fts` | A BM25 predicate against a text field. | Exact | | Hybrid-text selector | `hybrid_text` | The BM25 leg, the per-token fuzzy legs, and the per-token surfacing legs — a superset of the `hybrid_text` query route (see [Hybrid text count](#hybrid-text-count)). | Exact | | Radius selector | `ann` | Rows within `radius` of a query vector. | Approximate (ANN recall) | | Fan-out control | `threads` | Maximum concurrent upstream requests for origin scatter/gather. | Origin only; defaults from `Index.spec.scan.threads`, then `8`. | Origin scatter/gather is enabled only for namespaces whose shard backfill is complete. For adopted namespaces initialized through `POST /v2/namespaces/{ns}/init`, scans stay on the single-namespace origin path while `layer.shard_lag_rows` is greater than `0`; this keeps count, ID, and values scans from missing rows that have not yet been stamped with `_hevlayer_shard`. A request carries **at most one** ranked selector (`fts`, `hybrid_text`, or `ann`). `filters` is always optional and, when present alongside a ranked selector, is ANDed onto the match set as an extra constraint. A request with more than one ranked selector is a `422`. At cutover, `mode: ids` is filter-only (ranked IDs are a defined fast-follow), while `mode: count` and `mode: values` support all four selectors. Use scans for bulk exports, manual inspection, UDF discovery debugging, cache/origin consistency checks, exact or approximate counts, and field value discovery. ## Routes | Route | Method | Behavior | | --- | --- | --- | | `POST /v2/namespaces/{ns}/scans` | POST | Create an ID or values scan job, or return a count. | | `GET /v2/namespaces/{ns}/scans` | GET | List scan jobs for the namespace. | | `GET /v2/namespaces/{ns}/scans/{id}` | GET | Read one scan job. | | `GET /v2/namespaces/{ns}/scans/{id}/results` | GET | Read completed scan IDs or values. | | `DELETE /v2/namespaces/{ns}/scans/{id}` | DELETE | Drop the in-memory scan job. | ## ID Mode ```python job = await client.create_scan("products", { "source": "auto", "mode": "ids", "filters": ["category", "Eq", "Electronics"], "threads": 8, "page_size": 1000, }) ``` ```go job, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Source: "auto", Mode: "ids", Filters: []interface{}{"category", "Eq", "Electronics"}, Threads: 8, PageSize: 1000, }) ``` ```typescript const job = await client.createScan("products", { source: "auto", mode: "ids", filters: ["category", "Eq", "Electronics"], threads: 8, page_size: 1000, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "auto", "mode": "ids", "filters": ["category", "Eq", "Electronics"], "threads": 8, "page_size": 1000 }' ``` `mode` defaults to `ids`. Valid ID-mode sources are `auto`, `cache`, and `origin`. The Python and TypeScript clients also ship `scan(...)` helpers that create the job and poll until it completes; in Go, poll `GetScan` until `status` is `completed`. The create response is `202 Accepted`: ```json { "id": "scan-uuid", "namespace": "products", "source": "auto", "effective_source": "origin", "status": "running", "progress": 0, "documents_scanned": 0, "threads": 8, "created_at": "2026-05-26T10:00:00Z" } ``` Read IDs after `status` is `completed`: ```python results = await client.get_scan_results("products", job.id, limit=1000, offset=0) ``` ```go results, err := client.GetScanResults(ctx, "products", scanID, &hevlayer.GetScanResultsParams{Limit: 1000, Offset: 0}) ``` ```typescript const results = await client.getScanResults("products", job.id, { limit: 1000, offset: 0, }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/scans/scan-uuid/results?limit=1000&offset=0" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```json { "ids": ["doc-1", "doc-2"], "total": 2 } ``` ## Count Mode ```python count = await client.create_scan("products", { "mode": "count", "source": "auto", "filters": ["category", "Eq", "Electronics"], "threads": 8, "timeout_seconds": 30, }) ``` ```go count, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Mode: "count", Source: "auto", Filters: []interface{}{"category", "Eq", "Electronics"}, Threads: 8, TimeoutSeconds: 30, }) ``` ```typescript const count = await client.createScan("products", { mode: "count", source: "auto", filters: ["category", "Eq", "Electronics"], threads: 8, timeout_seconds: 30, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "count", "source": "auto", "filters": ["category", "Eq", "Electronics"], "threads": 8, "timeout_seconds": 30 }' ``` ```json { "count": 4210, "served_by": "snapshot", "snapshot_sha": "3f9e8b21", "watermark_ms": 1747300000123, "elapsed_ms": 3 } ``` When `watermark_ms` is present, the response also includes `x-layer-stable-as-of` with the same epoch-ms value. Count-mode sources are `auto`, `snapshot`, `cache`, and `origin`. Snapshot reads are eligible only for a single leaf `Eq` or `In` filter on a field present in the latest snapshot `fields[]`. `And`, `Or`, `Not`, range operators, fields absent from the snapshot, and skipped fields fall through under `auto` and fail with `412 precondition_failed` under `source: snapshot`. All scan modes accept the same temporal selectors as query: `as_of` conjoins `_hevlayer_upserted_at <= as_of`; `between: [lo, hi]` conjoins `lo < _hevlayer_upserted_at <= hi`. The temporal predicate is ANDed with `filters` and with any ranked selector (`fts`, `hybrid_text`, or `ann`). Snapshot-served scans cannot evaluate temporal windows from a pre-aggregated body, so `source: auto` falls through to cache/origin when a temporal selector is present and `source: snapshot` fails with `412 precondition_failed`. Live count responses include: ```json { "count": 4210, "served_by": "origin", "bounded": false, "timed_out": false, "shards_saturated": 0, "shards_total": 1, "threads": 1, "elapsed_ms": 42 } ``` ## Values Mode A values scan enumerates the distinct values of one attribute `field` over the rows the selector picks, each with its document count. Use it to discover a field's value set — what product categories exist, what tags appear on rows matching a query — instead of confirming values you already know with counts. `field` is required for `mode: values` (and rejected on other modes with `422`). It must name a scalar string or integer attribute, or an array of strings — each array element counts once per containing document. Vector fields are a `422`. ```python job = await client.create_scan("products", { "mode": "values", "field": "category", "source": "auto", "filters": ["in_stock", "Eq", True], }) ``` ```go job, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Mode: "values", Field: "category", Source: "auto", Filters: []interface{}{"in_stock", "Eq", true}, }) ``` ```typescript const job = await client.createScan("products", { mode: "values", field: "category", source: "auto", filters: ["in_stock", "Eq", true], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "values", "field": "category", "source": "auto", "filters": ["in_stock", "Eq", true] }' ``` Like ID mode, the create response is a `202 Accepted` job, and the `scan(...)` SDK helpers poll it to completion: ```json { "id": "scan-uuid", "namespace": "products", "mode": "values", "field": "category", "source": "auto", "effective_source": "origin", "status": "running", "progress": 0, "documents_scanned": 0, "threads": 8, "created_at": "2026-05-26T10:00:00Z" } ``` Read values from the same results route after `status` is `completed`, with the same `limit`/`offset` pagination as scan IDs: ```json { "values": [ {"v": "electronics", "n": 4210}, {"v": "books", "n": 1240} ], "total": 2, "truncated": false } ``` `v`/`n` is the same vocabulary [snapshot](/docs/api/snapshots) facet histograms use: `v` is the value, `n` its document count. Ordering is deterministic — `n` descending, then `v` ascending. Counts are exact for filter-selector scans; on a ranked scan with a saturated shard the job carries `bounded: true` and each `n` is a `>=` lower bound. ### Precomputed serving An unfiltered values scan (no `filters`, no ranked selector) on a field present in the latest snapshot `fields[]` is answered straight from the snapshot's facet histogram: the job completes during the create call — the `202` body already shows `status: completed` — and carries `effective_source: snapshot` with `snapshot_sha` and `watermark_ms`. Fields in `fields_skipped[]` or absent from the snapshot fall through to cache/origin under `auto` and fail with `412 precondition_failed` under explicit `source: snapshot`, as do scans carrying any selector. ### High cardinality Snapshot facet histograms cap each field at 10,000 distinct values and skip fields beyond it; values scans are the enumeration path for exactly those fields. A values job accumulates its histogram in gateway memory and caps the listing at **1,000,000 distinct values**. A scan that crosses the cap completes rather than failing: - The cap applies after the full pass, so every emitted `n` stays exact. - The listing truncates deterministically to the top 1,000,000 values by count (value-ascending tiebreak); the low-count tail is dropped. - The job and its results carry `truncated: true`, meaning the listing is incomplete. `truncated`, `bounded`, and `approximate` are independent flags: `truncated` is a gateway memory bound on the listing, `bounded` is upstream `top_k` saturation on a ranked scan's counts, and `approximate` is ANN recall fuzz on a radius ball's membership. ## Fan-out width Origin scans fan out one upstream request per active shard. `threads` sets the maximum number of those upstream requests a single scan may have in flight at once. It means concurrent requests, not operating-system threads; the gateway is async. Resolution order: 1. `threads` on the scan request. 2. `spec.scan.threads` on the namespace's `Index` resource. 3. The gateway default, `8`. The effective value is clamped to the active shard count and the server cap, `32`, then echoed as `threads` on origin responses and completed scan jobs. Snapshot and cache reads do not fan out, so they ignore this field and omit the echo. ## Full-text count Count rows matching a BM25 query with the `fts` selector. Full-text counts are exact and always run origin scatter/gather, so `source` must be omitted, `auto`, or `origin`. A `filters` array, when present, is ANDed on as an extra constraint. ```python count = await client.create_scan("products", { "mode": "count", "fts": {"field": "title", "query": "wireless headphones"}, "filters": ["category", "Eq", "Electronics"], "exhaustive": True, }) ``` ```go count, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Mode: "count", Fts: &hevlayer.FtsScan{Field: "title", Query: "wireless headphones"}, Filters: []interface{}{"category", "Eq", "Electronics"}, Exhaustive: true, }) ``` ```typescript const count = await client.createScan("products", { mode: "count", fts: { field: "title", query: "wireless headphones" }, filters: ["category", "Eq", "Electronics"], exhaustive: true, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "count", "fts": {"field": "title", "query": "wireless headphones"}, "filters": ["category", "Eq", "Electronics"], "exhaustive": true }' ``` ## Hybrid text count Count rows in the keyword/fuzzy neighborhood of a `HybridText` query with the `hybrid_text` selector. The scan tokenizes `query` with the HybridText policy, then evaluates the BM25 leg, one fuzzy leg per token, **and** one surfacing leg per token (the RFC 0057 empty-result fallback's legs), and counts the de-duplicated union of returned row ids. This count is a **superset** of the `hybrid_text` query route's deduped rows: the scan always includes the surfacing legs, whereas the query route only adds them when its primary legs (BM25 + fuzzy) return nothing. On a partial-typo query whose primary legs do match, the scan can therefore count more rows than the route returns. Use this selector for a generous live count next to `hybrid_text` or `auto` results that routed to `hybrid_text`; plain `fts` counts exact BM25 only. ```python count = await client.create_scan("products", { "mode": "count", "hybrid_text": {"field": "title", "query": "wireles headphones"}, "filters": ["category", "Eq", "Electronics"], }) ``` ```go count, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Mode: "count", HybridText: &hevlayer.HybridTextScan{Field: "title", Query: "wireles headphones"}, Filters: []interface{}{"category", "Eq", "Electronics"}, }) ``` ```typescript const count = await client.createScan("products", { mode: "count", hybrid_text: { field: "title", query: "wireles headphones" }, filters: ["category", "Eq", "Electronics"], }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "count", "hybrid_text": {"field": "title", "query": "wireles headphones"}, "filters": ["category", "Eq", "Electronics"] }' ``` ## Radius count Count rows within `radius` of a query vector with the `ann` selector — a distance-ball scan. `radius` is required and finite (without an upper bound every row is in the ball); `field` defaults to `vector`. Like `fts`, radius counts always run origin scatter/gather. The count is **approximate**: ANN recall means the index's membership of the ball may differ from the true set, independent of saturation, so the response carries `approximate: true`. The radius bound is applied by the gateway to the `$dist` returned by the ranked query. It is not sent upstream as a filter. ```python count = await client.create_scan("products", { "mode": "count", "ann": {"field": "vector", "vector": [0.12, -0.3, 0.88], "radius": 0.25}, }) ``` ```go count, err := client.CreateScan(ctx, "products", &hevlayer.CreateScanRequest{ Mode: "count", Ann: &hevlayer.AnnScan{Field: "vector", Vector: []float64{0.12, -0.3, 0.88}, Radius: 0.25}, }) ``` ```typescript const count = await client.createScan("products", { mode: "count", ann: { field: "vector", vector: [0.12, -0.3, 0.88], radius: 0.25 }, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/scans" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "count", "ann": {"field": "vector", "vector": [0.12, -0.3, 0.88], "radius": 0.25} }' ``` ```json { "count": 980, "served_by": "origin", "approximate": true, "bounded": false, "timed_out": false, "shards_saturated": 0, "shards_total": 1, "threads": 1, "elapsed_ms": 51 } ``` ### Bounding ranked scans Ranked selectors fan out one turbopuffer query per shard, each capped at `top_k = 10_000`. `threads` bounds fan-out width: how many shard requests can run at once. `exhaustive` and `timeout_seconds` bound depth: what happens when a shard hits that cap and how long recursion can run. - `exhaustive: false` (default) — one scatter/gather. A saturated shard contributes its cap as a lower bound; the response carries `bounded: true` with `shards_saturated > 0`. - `exhaustive: true` — for BM25, recurse on each saturated shard via score-band pagination (`$score < last` with an `id` tiebreak) until every page is short or `timeout_seconds` elapses. ANN radius scans do not push `$dist` filters upstream; the gateway counts returned rows whose `$dist <= radius` and marks the shard exhausted when the first over-radius row appears. If the full page is still inside the radius, the shard remains `bounded`. The same `threads` value applies to the initial round and every exhaustive round over the remaining saturated shards. `bounded` and `approximate` are independent. `bounded` means a shard saturated and the count is a `>=` lower bound for the rows the index returned; `approximate` means the distance ball's membership is itself fuzzy. An `ann` count can be `bounded: false` yet still `approximate: true`. ## Sources | Source | ID mode | Count mode | Values mode | | --- | --- | --- | --- | | `auto` | Cache when fresh enough, otherwise origin | Snapshot first, then cache/origin. | Snapshot when eligible, then cache/origin. | | `snapshot` | Not supported | Latest snapshot only; requires eligible `Eq` or `In`. | Latest snapshot facet listing; requires an unfiltered scan on a field in `fields[]`. | | `cache` | Aerospike document cache only | Aerospike document cache only | Aerospike document cache only. | | `origin` | turbopuffer paginated scan | turbopuffer paginated scan | turbopuffer paginated scan with gateway-side dedupe. | This table covers the filter selector. The `fts`, `hybrid_text`, and `ann` selectors have no snapshot or cache evaluator, so they always run origin scatter/gather: omitted, `auto`, and `origin` all resolve to origin, and `snapshot` or `cache` returns `422`. ## Filters Scans accept the same turbopuffer filter array as [query](/docs/api/query). On origin scans, the filter is pushed to turbopuffer. On cache scans, the gateway evaluates it against cached document attributes. Supported cache operators are `Eq`, `NotEq`, `Gt`, `Gte`, `Lt`, `Lte`, `In`, `NotIn`, `And`, `Or`, and `Not`. If `auto` sees a filter the cache cannot evaluate, it uses origin. Explicit `source: cache` with an unsupported filter fails rather than returning partial results. ## Auto-Mode Policy Auto ties cache freshness to the same consistency watermark used by [stable reads](/docs/api/query#stable-reads). The gateway tracks per-namespace `cache_warmed_through`, the watermark observed at the end of the last successful origin warm. | Cache state | Watermark state | Action | | --- | --- | --- | | Empty | any | Run origin and stamp `cache_warmed_through`. | | Populated, `cache_warmed_through >= watermark` | observed | Serve cache. | | Populated, `cache_warmed_through < watermark` | observed | Serve cache and start a background origin warm. | | Populated, no `cache_warmed_through` yet | observed | Serve cache and start a background origin warm. | | Populated | not yet observed | Serve cache. | When cache is used, `_hevlayer_upserted_at <= cache_warmed_through` is added before the user filter so the scan is a stable warmed view. ## Operational notes - ID and values scan state is in-memory and ephemeral; it resets on gateway restart. - Count scans have a deadline, default 30s and maximum 300s. - Values jobs cap at 1,000,000 distinct values per scan and set `truncated: true` when crossed; the listing keeps the top values by count, each with an exact count. - Origin scan fan-out defaults to 8 concurrent upstream requests per scan unless the request or `Index.spec.scan.threads` sets a different value. - Snapshot-served count scans are exact at the snapshot `watermark_ms`. --- # Pipelines Source: https://hevlayer.com/docs/api/pipelines import CodeTabs from "../../../components/docs/CodeTabs.astro"; The pipeline API keeps the code you need to index data simple and organized. A typical pipeline has two stages: extraction and chunking on CPU, followed by embedding on GPU. This guide walks through a best-practice layout for that pipeline; the concepts expand to N stages. ## Document lifecycle ``` put chunks put vectors (new doc) ──────────► pending ──────────────► indexed ▲ │ re-stage (idempotent) ``` - **pending** — chunks stored, waiting for embedding. - **indexed** — vectors written to the namespace's configured VectorStore. `embedding` is a claim stage: documents sit in it only while leased to a worker, and recover to `pending` when a lease expires. Re-staging a document resets it to `pending` with new chunks, which is how you reprocess after source data changes. ## File tree ``` indexer/ ├── pipelines/ │ ├── extract-chunk.yaml # CPU stage — Pipeline resource │ └── embed.yaml # GPU stage — Pipeline resource ├── extract_chunk.py # read the source, stage chunks ├── embed.py # claim pending docs, write vectors └── app.py # REST API: trigger a run, wait for completion ``` The two YAML files declare the worker images, pools, and scaling — see the [Pipeline CRD](/docs/kubernetes/pipeline-crd) for the fields. Both set `pipelineId: products` so the two workers share one queue. The rest of this page is the worker code — shown in Python and Go; every call is also a plain REST endpoint (see [Write & Stage](/docs/api/write)). ## Extract and chunk The CPU worker reads the source, splits text into chunks, and stages them. Staging chunks stores them durably (S3, cached in the document cache) and marks the document `pending`. The worker hardcodes nothing: the operator injects the pipeline id, the gateway URL, and `spec.sourceRef` as environment variables — see the [worker variables](/docs/kubernetes/pipeline-crd#worker) on the CRD page. The queue URL below comes from the `sourceRef` declared in `pipelines/extract-chunk.yaml`. ```python # extract_chunk.py import asyncio import json import os import boto3 from hevlayer import AsyncHevlayer PIPELINE = os.environ["HEVLAYER_PIPELINE_ID"] SOURCE = json.loads(os.environ["HEVLAYER_SOURCE_REF"]) sqs = boto3.client("sqs") def chunks(text: str, size: int = 800) -> list[str]: return [text[i : i + size] for i in range(0, len(text), size)] async def main() -> None: async with AsyncHevlayer( base_url=os.environ["HEVLAYER_BASE_URL"], api_key=os.environ.get("LAYER_GATEWAY_API_KEY"), ) as layer: while True: batch = sqs.receive_message( QueueUrl=SOURCE["queueUrl"], MaxNumberOfMessages=10, ).get("Messages", []) for m in batch: doc = json.loads(m["Body"]) await layer.put_pipeline_document_chunks(PIPELINE, doc["id"], { "chunks": [ {"id": f"{doc['id']}-{i}", "text": t} for i, t in enumerate(chunks(doc["text"])) ], }) sqs.delete_message(QueueUrl=SOURCE["queueUrl"], ReceiptHandle=m["ReceiptHandle"]) asyncio.run(main()) ``` ```go // extract_chunk.go package main import ( "context" "encoding/json" "fmt" "os" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/service/sqs" hevlayer "github.com/hev/layer-go" ) func chunks(text string, size int) []string { var out []string for i := 0; i < len(text); i += size { out = append(out, text[i:min(i+size, len(text))]) } return out } func main() { ctx := context.Background() pipeline := os.Getenv("HEVLAYER_PIPELINE_ID") var source struct { QueueURL string `json:"queueUrl"` } json.Unmarshal([]byte(os.Getenv("HEVLAYER_SOURCE_REF")), &source) cfg, _ := config.LoadDefaultConfig(ctx) queue := sqs.NewFromConfig(cfg) layer := hevlayer.NewClient( hevlayer.WithBaseURL(os.Getenv("HEVLAYER_BASE_URL")), hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")), ) for { batch, err := queue.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{ QueueUrl: &source.QueueURL, MaxNumberOfMessages: 10, }) if err != nil { continue } for _, m := range batch.Messages { var doc struct { ID string `json:"id"` Text string `json:"text"` } json.Unmarshal([]byte(*m.Body), &doc) var staged []hevlayer.Chunk for i, t := range chunks(doc.Text, 800) { staged = append(staged, hevlayer.Chunk{ID: fmt.Sprintf("%s-%d", doc.ID, i), Text: t}) } layer.PutPipelineDocumentChunks(ctx, pipeline, doc.ID, &hevlayer.PutChunksRequest{Chunks: staged}) queue.DeleteMessage(ctx, &sqs.DeleteMessageInput{ QueueUrl: &source.QueueURL, ReceiptHandle: m.ReceiptHandle, }) } } } ``` ```typescript // extract_chunk.ts import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient, } from "@aws-sdk/client-sqs"; import { Hevlayer } from "hevlayer"; const PIPELINE = process.env.HEVLAYER_PIPELINE_ID!; const SOURCE = JSON.parse(process.env.HEVLAYER_SOURCE_REF!); const sqs = new SQSClient({}); const layer = new Hevlayer({ baseUrl: process.env.HEVLAYER_BASE_URL, apiKey: process.env.LAYER_GATEWAY_API_KEY, }); function chunks(text: string, size = 800): string[] { const out: string[] = []; for (let i = 0; i < text.length; i += size) out.push(text.slice(i, i + size)); return out; } while (true) { const batch = await sqs.send(new ReceiveMessageCommand({ QueueUrl: SOURCE.queueUrl, MaxNumberOfMessages: 10, })); for (const message of batch.Messages ?? []) { const doc = JSON.parse(message.Body ?? "{}"); await layer.putPipelineDocumentChunks(PIPELINE, doc.id, { chunks: chunks(doc.text).map((text, i) => ({ id: `${doc.id}-${i}`, text })), }); await sqs.send(new DeleteMessageCommand({ QueueUrl: SOURCE.queueUrl, ReceiptHandle: message.ReceiptHandle, })); } } ``` ## Embed The GPU worker claims pending documents, reads their chunks back, and writes vectors. Writing vectors upserts to the namespace's configured VectorStore and marks the document `indexed`. Claims are leased, so a worker that crashes loses nothing. For multivector namespaces on a `kind: search` store, send `vectors: [[...], [...]]` on an entry instead of `vector: [...]`; the gateway forwards the bag and caches the first inner vector for `nearest_to_id` lookup. ```python # embed.py import asyncio import os from hevlayer import AsyncHevlayer from sentence_transformers import SentenceTransformer PIPELINE = os.environ["HEVLAYER_PIPELINE_ID"] model = SentenceTransformer("all-MiniLM-L6-v2") async def main() -> None: async with AsyncHevlayer( base_url=os.environ["HEVLAYER_BASE_URL"], api_key=os.environ.get("LAYER_GATEWAY_API_KEY"), ) as layer: while True: claimed = await layer.claim_documents(PIPELINE, { "stage": "pending", "claim_stage": "embedding", "limit": 16, "worker_id": "embed-0", }) for doc_id in claimed.documents: doc_chunks = await layer.get_pipeline_document_chunks(PIPELINE, doc_id) vectors = model.encode([c.text for c in doc_chunks]) await layer.put_pipeline_document_vectors(PIPELINE, doc_id, { "vectors": [ {"id": c.id, "vector": v.tolist(), "attributes": {"text": c.text}} for c, v in zip(doc_chunks, vectors) ], }) asyncio.run(main()) ``` ```go // embed.go package main import ( "context" "os" hevlayer "github.com/hev/layer-go" ) func main() { ctx := context.Background() pipeline := os.Getenv("HEVLAYER_PIPELINE_ID") layer := hevlayer.NewClient( hevlayer.WithBaseURL(os.Getenv("HEVLAYER_BASE_URL")), hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")), ) for { claimed, err := layer.ClaimDocuments(ctx, pipeline, &hevlayer.ClaimDocumentsRequest{ Stage: "pending", ClaimStage: "embedding", Limit: 16, WorkerID: "embed-0", }) if err != nil { continue } for _, docID := range claimed.Documents { docChunks, err := layer.GetPipelineDocumentChunks(ctx, pipeline, docID) if err != nil { continue } texts := make([]string, len(*docChunks)) for i, c := range *docChunks { texts[i] = c.Text } vectors := embed(texts) // your embedding model or service entries := make([]hevlayer.VectorEntry, len(*docChunks)) for i, c := range *docChunks { entries[i] = hevlayer.VectorEntry{ ID: c.ID, Vector: vectors[i], Attributes: map[string]interface{}{"text": c.Text}, } } layer.PutPipelineDocumentVectors(ctx, pipeline, docID, &hevlayer.PutVectorsRequest{Vectors: entries}) } } } ``` ```typescript // embed.ts import { Hevlayer } from "hevlayer"; const PIPELINE = process.env.HEVLAYER_PIPELINE_ID!; const layer = new Hevlayer({ baseUrl: process.env.HEVLAYER_BASE_URL, apiKey: process.env.LAYER_GATEWAY_API_KEY, }); while (true) { const claimed = await layer.claimDocuments(PIPELINE, { stage: "pending", claim_stage: "embedding", limit: 16, worker_id: "embed-0", }); for (const docId of claimed.documents) { const docChunks = await layer.getPipelineDocumentChunks(PIPELINE, docId); const vectors = await embed(docChunks.map((chunk) => chunk.text)); await layer.putPipelineDocumentVectors(PIPELINE, docId, { vectors: docChunks.map((chunk, i) => ({ id: chunk.id, vector: vectors[i], attributes: { text: chunk.text }, })), }); } } ``` ## Deploy Build the two workers into the images your YAML references and push them to a registry your cluster can pull — Layer does not build images. Then apply the resources: ```sh kubectl apply -f pipelines/ ``` The operator creates one Deployment per resource and the embed pool's KEDA object. Order doesn't matter here: the app creates the gateway pipeline before it enqueues a batch (staging into a pipeline id that doesn't exist returns 404), so workers never see a missing pipeline. Nothing else to wire: the CRD [types themselves](/docs/install#helm) install with the Helm chart. ## Trigger a run The app exposes the pipeline to the rest of your system as one endpoint: `POST /index-runs` sends a batch to the source queue, then waits for the run to complete and returns the snapshot it produced. The pipeline is created on first use — this is where the target namespace is set in code. ```python # app.py import asyncio import json import os import time import boto3 from fastapi import FastAPI from hevlayer import AsyncHevlayer, HevlayerError QUEUE = "https://sqs.us-east-1.amazonaws.com/123456789/product-updates" sqs = boto3.client("sqs") app = FastAPI() layer = AsyncHevlayer( base_url=os.environ["HEVLAYER_BASE_URL"], api_key=os.environ.get("LAYER_GATEWAY_API_KEY"), ) @app.post("/index-runs") async def index_run(documents: list[dict]) -> dict: started_ms = int(time.time() * 1000) try: await layer.create_pipeline({"id": "products", "target_namespace": "products"}) except HevlayerError as e: if e.status_code != 409: # 409: already exists raise for doc in documents: sqs.send_message(QueueUrl=QUEUE, MessageBody=json.dumps(doc)) await drain() sha = await next_snapshot(after_ms=started_ms) return {"documents": len(documents), "snapshot": sha} ``` ```go // app.go var ( queueURL = "https://sqs.us-east-1.amazonaws.com/123456789/product-updates" queue *sqs.Client // sqs.NewFromConfig in main layer = hevlayer.NewClient( hevlayer.WithBaseURL(os.Getenv("HEVLAYER_BASE_URL")), hevlayer.WithAPIKey(os.Getenv("LAYER_GATEWAY_API_KEY")), ) ) func indexRun(w http.ResponseWriter, r *http.Request) { ctx := r.Context() startedMs := time.Now().UnixMilli() var documents []map[string]interface{} json.NewDecoder(r.Body).Decode(&documents) _, err := layer.CreatePipeline(ctx, &hevlayer.CreatePipelineRequest{ ID: "products", TargetNamespace: "products", }) var herr *hevlayer.HevlayerError if err != nil && !(errors.As(err, &herr) && herr.StatusCode == 409) { // 409: already exists http.Error(w, err.Error(), http.StatusBadGateway) return } for _, doc := range documents { body, _ := json.Marshal(doc) mb := string(body) queue.SendMessage(ctx, &sqs.SendMessageInput{QueueUrl: &queueURL, MessageBody: &mb}) } drain(ctx) sha := nextSnapshot(ctx, startedMs) json.NewEncoder(w).Encode(map[string]interface{}{ "documents": len(documents), "snapshot": sha, }) } ``` ```typescript // app.ts import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs"; import { Hevlayer } from "hevlayer"; const queueUrl = "https://sqs.us-east-1.amazonaws.com/123456789/product-updates"; const queue = new SQSClient({}); const layer = new Hevlayer({ baseUrl: process.env.HEVLAYER_BASE_URL, apiKey: process.env.LAYER_GATEWAY_API_KEY, }); async function indexRun(documents: Record[]) { const startedMs = Date.now(); await layer.ensurePipeline({ id: "products", target_namespace: "products" }); for (const doc of documents) { await queue.send(new SendMessageCommand({ QueueUrl: queueUrl, MessageBody: JSON.stringify(doc), })); } await drain(); return { documents: documents.length, snapshot: await nextSnapshot(startedMs) }; } ``` ## Wait for completion A run is complete in two steps: the queue drains, then the consistency watcher observes the namespace stable and writes a [snapshot](/docs/api/snapshots) past the run's watermark. `pending_count` is the same signal KEDA scales on — when it reaches zero, the embed pool scales back to zero. `status` is `waiting_on_upstream` when a downstream worker has no pending rows to claim while upstream stages are still active. If a worker cannot load a document's durable chunk payload after the configured retry budget, Layer moves that document to `failed` and adds the dead-letter reason to `failed_reasons`, such as `{"chunks_unavailable": 2}`. The snapshot SHA addresses facet listings and counts exact at that watermark; flip your application to it. ```python # app.py async def drain() -> None: while True: status = await layer.get_pipeline_status("products") if status.pending_count == 0: # status.counts: {"pending": 0, "indexed": 8530} return await asyncio.sleep(10) async def next_snapshot(after_ms: int) -> str: while True: history = await layer.list_namespace_history("products", limit=1) if history and history[0].watermark_ms >= after_ms: return history[0].sha await asyncio.sleep(30) ``` ```go // app.go func drain(ctx context.Context) { for { status, err := layer.GetPipelineStatus(ctx, "products") if err == nil && status.PendingCount == 0 { // status.Counts: {"pending": 0, "indexed": 8530} return } time.Sleep(10 * time.Second) } } func nextSnapshot(ctx context.Context, afterMs int64) string { for { history, err := layer.ListNamespaceHistory(ctx, "products", &hevlayer.ListNamespaceHistoryParams{Limit: 1}) if err == nil && len(history) > 0 && history[0].WatermarkMs >= afterMs { return history[0].Sha } time.Sleep(30 * time.Second) } } ``` ```typescript // app.ts const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); async function drain() { while (true) { const status = await layer.getPipelineStatus("products"); if (status.pending_count === 0) return; await sleep(10_000); } } async function nextSnapshot(afterMs: number): Promise { while (true) { const history = await layer.listNamespaceHistory("products", { limit: 1 }); if (history.length > 0 && history[0].watermark_ms >= afterMs) { return history[0].sha; } await sleep(30_000); } } ``` Once vectors are indexed, query and fetch them through the namespace API — see [Query & Fetch](/docs/api/query). ## Failure model - VectorStore write failures are hard: the vectors route returns 502 and the document stays in `embedding` for re-claim. - Aerospike cache failures do not block chunk reads when S3 backing is present; PostgreSQL connectivity failures return 500 and should be retried with backoff. The stop-writes recovery path and the metrics to watch live in the [failure-mode runbook](/docs/failure-modes#pipeline-stop-writes). - Lease expiry is handled server-side. A worker that crashes mid-embedding has its documents recovered on the next claim sweep. --- # Namespace metadata Source: https://hevlayer.com/docs/api/namespace-metadata import Upstream from "../../../components/docs/Upstream.astro"; import CodeTabs from "../../../components/docs/CodeTabs.astro"; The metadata payload is proxied verbatim from the upstream `/v2/namespaces/{ns}/metadata` endpoint. Schema, row counts, index status, and timestamps follow the upstream contract. Layer adds a single sub-object on top. ## Request ```python metadata = await client.get_namespace_metadata("products") ``` ```go metadata, err := client.GetNamespaceMetadata(ctx, "products") ``` ```typescript const metadata = await client.getNamespaceMetadata("products"); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/metadata" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```jsonc { // Proxied from turbopuffer verbatim "schema": { }, "approx_row_count": 12500, "approx_logical_bytes": 48800000, "created_at": "2026-03-15T10:30:45Z", "updated_at": "2026-05-12T18:49:00Z", "last_write_at": "2026-05-12T18:48:30Z", "index": { "status": "up-to-date" }, // Layer enhancement "layer": { "stable_as_of": 1715600400000, "is_stable": true, "indexed": true, "index_lag_rows": 0 } } ``` ## The `layer` block | Field | Meaning | | --- | --- | | `stable_as_of` | Epoch-ms watermark from the most recent stable poll. Null on cold start before the watcher has observed a stable namespace. | | `is_stable` | Whether the most recent poll observed `index.status == "up-to-date"`. False on cold start, true once the watcher catches up. | | `indexed` | Whether every row in the namespace carries an indexed vector. True once the snapshot's indexed-vector row count has caught up to the namespace row count; false while rows are still awaiting their first index, as during a bulk load or a [pipeline](/docs/api/pipelines) mid-flight. Null for FTS-only namespaces, which have no vector column to reconcile. | | `index_lag_rows` | Count of rows present in the namespace that do not yet have an indexed vector. Zero when `indexed` is true. Reconciled from the most recent [snapshot](/docs/api/snapshots), so it trails live writes by the snapshot cadence. | A read for a namespace that does not exist returns upstream's 404, matching turbopuffer's own metadata endpoint. `is_stable` is the *current* signal — it drives the per-query filter-skip decision on the query path. `stable_as_of` is the *historical* watermark — the cut a filtered query would apply. After a namespace is observed stable, the watcher refreshes this watermark on the stable-tier cadence (`CONSISTENCY_STABLE_POLL_INTERVAL_MS`, default 60000 ms). Writes re-arm the fast tier, so active namespaces are polled on `CONSISTENCY_POLL_INTERVAL_MS`. `indexed` answers a different question than `is_stable`. `is_stable` reports whether the upstream index has caught up on the rows it has *seen*, which is what read-after-write depends on. `indexed` reports whether every row that *should* be present is present and queryable, which is what a bulk load or a [pipeline](/docs/api/pipelines) needs to know it has finished: rows can be staged and counted before their vectors are indexed, so a namespace can read `is_stable: true` while `indexed: false` with a non-zero `index_lag_rows`. The reconciliation runs against the latest [snapshot](/docs/api/snapshots), so `indexed` advances on the snapshot cadence rather than per write. For snapshot history derived from these freshness signals, see [Snapshots](/docs/api/snapshots). ## List namespaces `GET /v2/namespaces` is a Layer-only augmented listing. It pages the upstream namespace list and enriches each row with stability and cache signals. It is the endpoint the dashboard's inventory view reads. ```python namespaces = await client.list_namespaces(prefix="prod", page_size=100) ``` ```go namespaces, err := client.ListNamespaces(ctx, &hevlayer.ListNamespacesParams{ Prefix: "prod", PageSize: 100, }) ``` ```typescript const namespaces = await client.listNamespaces({ prefix: "prod", pageSize: 100, }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces?prefix=prod&page_size=100" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```jsonc { "namespaces": [ { "name": "products", "row_count": 12500, "size_bytes": 48800000, "stable_as_of_ms": 1715600400000, "is_stable": true, "index": { "status": "up-to-date" }, "cache_state": {"state": "warm", "warm_inflight": false}, "last_write_ms": 1715600399000, "shadow": false, "labels": {} } ], "next_cursor": "..." } ``` Each row carries freshness signals derived from that row's metadata fetch. `is_stable` is true when `index.status` is `"up-to-date"`, false when it is `"updating"`, and omitted when metadata has no index signal or the fetch failed. `stable_as_of_ms` is set to the metadata observation time for rows reported up to date. `indexed` and `index_lag_rows` live on `GET /v2/namespaces/{namespace}/metadata`, where the gateway can do the snapshot lookup for one namespace without adding object-store reads to the high-fanout list path. `index` is turbopuffer's indexing state, passed through verbatim: | Field | Meaning | | --- | --- | | `index.status` | `"updating"` or `"up-to-date"`. | | `index.unindexed_bytes` | Write-ahead-log bytes not yet indexed. Present only while `updating` (omitted once caught up). Unindexed data is still searched by queries, so a non-zero value means *behind, but serving* — watch it fall to confirm indexing is draining rather than wedged. | Listing is read-only and does not register namespaces with the consistency watcher. Write traffic and snapshot facet configuration register the namespaces that need durable watermarks. | Query param | Purpose | | --- | --- | | `prefix` | Restrict to namespaces whose name starts with this string. | | `cursor` | Pagination cursor from a prior `next_cursor`. | | `page_size` | Page size; the upstream list page is capped at 1000. | A per-row metadata failure degrades to a row with `metadata_error` set rather than dropping the namespace, so the list stays complete even when a single namespace's metadata call fails. Responses are served from a short-TTL cache (`NAMESPACE_LIST_CACHE_TTL_MS`, default `10000`) so dashboard polling does not fan out a metadata call per namespace per refresh. --- # VectorStores And Warehouses Source: https://hevlayer.com/docs/api/data-supply Layer exposes the declared data-supply resources through read-only gateway routes. `VectorStore` is the serving-side connection; `Warehouse` is the source-side connection used by pipelines. The responses are safe to show in operator tools: they include Secret reference names and keys, never Secret contents. All routes require a key with `read` scope. Create and edit these resources through the Kubernetes CRDs or the dashboard's apply forms. The gateway surface is the credential-safe read projection. ## VectorStores ```sh curl -H "Authorization: Bearer $LAYER_API_KEY" \ "$LAYER_BASE_URL/v2/vectorstores" ``` ```json { "vectorstores": [ { "name": "prod-turbopuffer", "kind": "turbopuffer", "default": true, "endpoint": { "url": "https://aws-us-east-1.turbopuffer.com", "region": "aws-us-east-1" }, "turbopuffer": { "orgId": "org_123" }, "credential": { "secretRef": { "name": "layer-turbopuffer", "key": "turbopuffer-api-key" } }, "inboundAuth": { "mode": "deriveFromStore" }, "status": { "reachable": true, "observedGeneration": 7, "conditions": [] }, "turbopufferUrl": "https://turbopuffer.com/organizations/org_123" } ] } ``` `GET /v2/vectorstores/{name}` returns one object in the same shape. `turbopufferUrl` is omitted when `spec.turbopuffer.orgId` is not set. ## Warehouses ```sh curl -H "Authorization: Bearer $LAYER_API_KEY" \ "$LAYER_BASE_URL/v2/warehouses" ``` ```json { "warehouses": [ { "name": "prod-snowflake", "kind": "snowflake", "snowflake": { "account": "acme-xy12345", "user": "SVC_LAYER", "role": "SVC_LAYER_ROLE", "warehouse": "EXTRACT_WH", "keyPairSecretRef": { "name": "snowflake-rsa" }, "pool": { "size": 5, "timeout": "30s" } }, "verifyInterval": "1h", "status": { "phase": "Verified", "verifiedAt": "2026-06-10T00:00:00Z", "consumers": { "pipelines": 2, "apiKeys": 1 }, "conditions": [] } } ] } ``` `GET /v2/warehouses/{name}` returns one object in the same shape. `phase` is `Pending`, `Verified`, or `Failed`; failed warehouses include `status.failureReason`. `status.consumers` counts pipelines and API keys that still reference the warehouse. --- # Warm cache Source: https://hevlayer.com/docs/api/warm-cache import Upstream from "../../../components/docs/Upstream.astro"; import Callout from "../../../components/docs/Callout.astro"; import CodeTabs from "../../../components/docs/CodeTabs.astro"; Layer exposes two warm endpoints. `hint_cache_warm` is the turbopuffer-compatible hint; `warm` is the Layer-only shortcut that creates a gateway warm job. `GET /v1/namespaces/{ns}/hint_cache_warm` matches turbopuffer's warm-cache hint. The upstream call advises the index to pre-load. Layer additionally runs cache-warm steps on the gateway side. ## Hint-cache warm With no query parameters, the call is a raw passthrough: the gateway forwards it to turbopuffer unchanged and returns the upstream response verbatim. Existing turbopuffer clients keep their exact wire behavior. ```bash curl "$LAYER_GATEWAY_URL/v1/namespaces/products/hint_cache_warm" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` Supplying any warm option (`turbopuffer`, `documents`, `snapshots`, `page_size`) switches the call into Layer orchestration. Steps then default on; each is independently toggleable: | Step | What it does | | --- | --- | | `turbopuffer=true` | Forwards the warm hint upstream. | | `documents=true` | Starts an origin warm job to backfill the document cache. | | `snapshots=true` | Mirrors the latest S3 snapshot body into the cache. | ```python result = await client.hint_cache_warm( "products", turbopuffer=False, documents=False, snapshots=True, ) ``` ```typescript const result = await client.hintCacheWarm("products", { turbopuffer: false, documents: false, snapshots: true, }); ``` ```bash curl "$LAYER_GATEWAY_URL/v1/namespaces/products/hint_cache_warm?turbopuffer=false&documents=false&snapshots=true" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` The generated Go client omits `false` query parameters, so it cannot turn steps off — disable steps over REST (or the Python client) instead. The orchestrated response reports per-step status: ```json { "namespace": "products", "turbopuffer": { "enabled": true, "status": "completed" }, "documents": { "enabled": true, "status": "started", "job": { "id": "warm-job-uuid", "status": "running" } }, "snapshots": { "enabled": true, "status": "completed", "key": "snapshots/products/...", "watermark_ms": 1715600400000, "sha": "..." } } ``` If `documents` is enabled, the response includes a warm job; poll it through `/warm-jobs/{id}`. ## Layer warm `POST /v2/namespaces/{ns}/warm` creates an asynchronous job that pages through turbopuffer, backfills Aerospike, and refreshes `cache_warmed_through`. Use it when bootstrapping a namespace whose data was written outside the gateway. ```python job = await client.warm_cache("products", page_size=1000) ``` ```go job, err := client.WarmCache(ctx, "products", &hevlayer.WarmCacheParams{ PageSize: 1000, }) ``` ```typescript const job = await client.warmCache("products", { pageSize: 1000 }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/warm?page_size=1000" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` The response is `202 Accepted` with the warm job: ```json { "id": "warm-job-uuid", "namespace": "products", "status": "running", "progress": 0, "documents_scanned": 0, "created_at": "2026-05-26T10:00:00Z" } ``` Poll it through: ```python job = await client.get_warm_job("products", job.id) ``` ```go job, err := client.GetWarmJob(ctx, "products", jobID) ``` ```typescript const job = await client.getWarmJob("products", jobId); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/warm-jobs/warm-job-uuid" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ## Cache-cold behavior Warm jobs, cache scans, cache snapshot jobs, and pipeline chunk reads return 503 `cache_cold` when the document cache is unavailable. Fetch and fetch-many fall through to turbopuffer with `x-layer-cache: miss-on-error` instead. The split is deliberate. Fetch is correctness-first: a cache outage must not turn into a missing document. Warm is throughput-first: warming on a cold cache would be wasted work, so the gateway reports the cold state to the caller rather than silently no-op-ing. A bare `hint_cache_warm` passthrough never touches the gateway cache, so it succeeds even while the cache is cold. The orchestrated form returns 503 `cache_cold` only when `documents` or `snapshots` is requested. For how the cache recovers from an outage and the signals to watch, see the [failure-mode runbook](/docs/failure-modes#read). --- # Snapshot History Source: https://hevlayer.com/docs/api/snapshots import CodeTabs from "../../../components/docs/CodeTabs.astro"; Snapshots are materialized facet histograms for a namespace. They carry facet listings in `values[].v` and facet counts in `values[].n`, stored durably in S3 and mirrored into Aerospike for the latest body. Use `POST /snapshots` to materialize a field now. Use history and body routes to read the durable chronology written by the consistency watcher. ## Snapshot policy Configure automatic snapshot writes with the `Index.spec.snapshot` shape. Kubernetes operators put the shape on the namespace's `Index` CR: ```yaml apiVersion: hevlayer.com/v1 kind: Index metadata: name: products spec: backend: namespace: products snapshot: interval: 5m retention: 30d facetFields: - category - brand ``` | Field | Default | Behavior | | --- | --- | --- | | `facetFields` | `[]` | Facet fields to histogram. Empty or unset disables the automatic snapshot writer for the namespace, so history and activity stay empty. | | `interval` | `5m` | Minimum spacing between automatic snapshot writes. The writer fires on each upstream-stable advance; `interval` only floors how often a write lands. The gateway fallback is `LAYER_SNAPSHOT_MIN_INTERVAL_MS`. | | `retention` | `never` | `never` keeps all history. A duration such as `30d` prunes S3 bodies older than the window, while always keeping the most recent body. | Snapshots are event-driven, not scheduled: an idle namespace does not get a new snapshot just because `interval` elapsed. The gateway refreshes Index policy periodically, so edits take effect without a pod restart. API-only namespaces can set the same shape on the gateway: ```bash curl -X PUT "$LAYER_GATEWAY_URL/v2/namespaces/products/snapshot-policy" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "facetFields": ["category", "brand"], "interval": "5m", "retention": "30d" }' ``` The API policy is stored gateway-side and takes effect immediately for the automatic writer. `GET /v2/namespaces/{ns}/snapshot-policy` returns the API-managed policy for review and automation. Manual `POST /snapshots` jobs with `source: origin` and the automatic writer use the same shard fan-out path. Origin work is bounded by `spec.scan.threads`; stored and cache snapshot reads do not fan out. ## Routes | Route | Method | Behavior | | --- | --- | --- | | `POST /v2/namespaces/{ns}/snapshots` | POST | Create an on-demand snapshot job for one field. | | `GET /v2/namespaces/{ns}/snapshot-policy` | GET | Read the API-managed snapshot policy. | | `PUT /v2/namespaces/{ns}/snapshot-policy` | PUT | Set `facetFields`, `interval`, and `retention` using the `Index.spec.snapshot` shape. | | `GET /v2/namespaces/{ns}/snapshot-jobs` | GET | List in-memory snapshot jobs. | | `GET /v2/namespaces/{ns}/snapshot-jobs/{id}` | GET | Read one snapshot job. | | `GET /v2/namespaces/{ns}/history` | GET | Newest-first durable snapshot history. | | `GET /v2/namespaces/{ns}/snapshots/{sha}` | GET | Full snapshot body by full SHA or 7-char prefix. | | `GET /v2/activity/snapshots` | GET | Cross-namespace snapshot-write activity stream. | Need a named cut for a downstream app? Use [checkpoints](/docs/api/checkpoints) to label the newest durable snapshot watermark without running a scan. ## Manual snapshot ```python job = await client.create_snapshot("products", { "field": "category", "source": "auto", "filters": ["brand", "Eq", "Acme"], "page_size": 1000, }) ``` ```go job, err := client.CreateSnapshot(ctx, "products", &hevlayer.CreateSnapshotRequest{ Field: "category", Source: "auto", Filters: []interface{}{"brand", "Eq", "Acme"}, PageSize: 1000, }) ``` ```typescript const job = await client.createSnapshot("products", { field: "category", source: "auto", filters: ["brand", "Eq", "Acme"], page_size: 1000, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/snapshots" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "field": "category", "source": "auto", "filters": ["brand", "Eq", "Acme"], "page_size": 1000 }' ``` Valid sources are `auto`, `stored`, `cache`, and `origin`. | Source | Reads from | Notes | | --- | --- | --- | | `auto` | Stored snapshot when possible, otherwise cache/origin policy | Default. Stored snapshots only support unfiltered configured fields. | | `stored` | Latest S3 snapshot body, with Aerospike mirror as a cache | Fastest path for configured facet fields. | | `cache` | Aerospike document cache | Supports filters the cache can evaluate. | | `origin` | turbopuffer paginated scan | Authoritative. Persists the computed snapshot body to S3. | The response is `202 Accepted`: ```json { "id": "snapshot-job-uuid", "namespace": "products", "field": "category", "source": "auto", "status": "running", "progress": 0, "documents_scanned": 0, "created_at": "2026-05-26T10:00:00Z" } ``` Poll the job: ```python job = await client.get_snapshot_job("products", job.id) ``` ```go job, err := client.GetSnapshotJob(ctx, "products", jobID) ``` ```typescript const job = await client.getSnapshotJob("products", jobId); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/snapshot-jobs/snapshot-job-uuid" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` Completed jobs include `sha` when a body was materialized: ```json { "id": "snapshot-job-uuid", "namespace": "products", "field": "category", "source": "origin", "status": "completed", "documents_scanned": 12844, "sha": "3f9e8b21", "stable_as_of": 1747300000123 } ``` ## History ```python history = await client.list_namespace_history("products", limit=20) ``` ```go history, err := client.ListNamespaceHistory(ctx, "products", &hevlayer.ListNamespaceHistoryParams{Limit: 20}) ``` ```typescript const history = await client.listNamespaceHistory("products", { limit: 20 }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/history?limit=20" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```json [ {"watermark_ms": 1747300000123, "sha": "3f9e8b21...", "tags": ["pre-migration"]}, {"watermark_ms": 1747299600045, "sha": "a1c5b09f...", "tags": []} ] ``` | Query param | Default | Purpose | | --- | --- | --- | | `limit` | 50 | Maximum entries returned. Capped at 500. | | `before` | none | Return entries older than this SHA. 7-char prefixes are accepted. | The history endpoint lists S3 keys only; it does not read every snapshot body. `tags` is metadata for operator grouping and restore workflows; it is not part of the snapshot content hash. ## Snapshot body ```python body = await client.get_namespace_snapshot("products", "3f9e8b2") ``` ```go body, err := client.GetNamespaceSnapshot(ctx, "products", "3f9e8b2") ``` ```typescript const body = await client.getNamespaceSnapshot("products", "3f9e8b2"); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/snapshots/3f9e8b2" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```json { "namespace": "products", "watermark_ms": 1747300000123, "sha": "3f9e8b21", "row_count": 12500, "fields": [ { "name": "category", "values": [ {"v": "books", "n": 1240}, {"v": "electronics", "n": 873} ] } ], "fields_skipped": [ { "name": "tags", "reason": "exceeded_cap", "distinct_observed": 247000, "cap": 10000 } ] } ``` `fields[].values[].v` is the facet listing. `fields[].values[].n` is the facet count. `row_count` is the number of rows scanned into the snapshot; for vector namespaces, [namespace metadata](/docs/api/namespace-metadata) compares it with the upstream namespace row count to report `indexed` and `index_lag_rows`. Fields present in `fields[]` are complete. Fields above the 10,000 distinct-value cap are listed in `fields_skipped[]` instead of being partially materialized. A skipped field is still enumerable on demand with a [values scan](/docs/api/scans#values-mode), which carries a 1,000,000-value cap instead. ## Activity ```python activity = await client.list_snapshot_activity(since=1747200000000, limit=50) ``` ```go activity, err := client.ListSnapshotActivity(ctx, &hevlayer.ListSnapshotActivityParams{Since: 1747200000000, Limit: 50}) ``` ```typescript const activity = await client.listSnapshotActivity({ since: 1747200000000, limit: 50, }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/activity/snapshots?since=1747200000000&limit=50" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` | Query param | Required | Purpose | | --- | --- | --- | | `since` | yes | Epoch-ms lower bound on `ts_ms`. | | `limit` | no | Cap 500, default 50. | | `namespace` | no | Exact namespace filter. | | `cursor` | no | Pagination cursor from `next_cursor`. | Activity is snapshot lifecycle only. Search history and clickstream events have separate feeds. --- # Checkpoints Source: https://hevlayer.com/docs/api/checkpoints import CodeTabs from "../../../components/docs/CodeTabs.astro"; Checkpoints give an application a stable name for a known-good namespace cut. Creating a checkpoint labels the newest durable [snapshot](/docs/api/snapshots) body for the namespace and stores that small label record in S3. It does not run a scan or write rows. Use checkpoints when a downstream app needs to browse, diff, or drop data by a named catalog cut instead of by an ad hoc `catalog_run_id` filter. The checkpoint response includes the snapshot `watermark_ms`, content `sha`, and `row_count` added since the previous checkpoint. ## Routes | Route | Method | Behavior | | --- | --- | --- | | `POST /v2/namespaces/{ns}/checkpoints` | POST | Create or return an immutable checkpoint label. | | `GET /v2/namespaces/{ns}/checkpoints` | GET | List checkpoints newest first. | | `GET /v2/namespaces/{ns}/checkpoints/{label}` | GET | Resolve one checkpoint label. | ## Create ```python checkpoint = await client.create_checkpoint("products", { "label": "catalog-2026-06-15", }) ``` ```go checkpoint, err := client.CreateCheckpoint(ctx, "products", &hevlayer.CreateCheckpointRequest{Label: "catalog-2026-06-15"}) ``` ```typescript const checkpoint = await client.createCheckpoint("products", { label: "catalog-2026-06-15", }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"label": "catalog-2026-06-15"}' ``` Response: ```json { "namespace": "products", "label": "catalog-2026-06-15", "watermark_ms": 1749513600000, "sha": "3f9e8b21...", "row_count": 10000 } ``` Re-posting the same `label` returns the existing checkpoint unchanged, even if newer snapshots have landed. Labels are namespace-local and may contain ASCII letters, numbers, `-`, `_`, `.`, and `:`. The namespace must already have at least one durable snapshot. If no snapshot body exists yet, creation returns `412 precondition_failed`. ## List ```python page = await client.list_checkpoints("products", limit=20) ``` ```go page, err := client.ListCheckpoints(ctx, "products", &hevlayer.ListCheckpointsParams{Limit: 20}) ``` ```typescript const page = await client.listCheckpoints("products", { limit: 20 }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints?limit=20" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ```json { "checkpoints": [ { "namespace": "products", "label": "catalog-2026-06-15", "watermark_ms": 1749513600000, "sha": "3f9e8b21...", "row_count": 10000 } ], "next_cursor": null } ``` | Query param | Default | Purpose | | --- | --- | --- | | `limit` | 50 | Maximum entries returned. Capped at 500. | | `before` | none | Opaque cursor from the previous page's `next_cursor`. | ## Resolve ```python checkpoint = await client.get_checkpoint("products", "catalog-2026-06-15") ``` ```go checkpoint, err := client.GetCheckpoint(ctx, "products", "catalog-2026-06-15") ``` ```typescript const checkpoint = await client.getCheckpoint("products", "catalog-2026-06-15"); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/checkpoints/catalog-2026-06-15" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` Resolve returns `404 not_found` when the label does not exist in that namespace. --- # Query History Source: https://hevlayer.com/docs/api/search-history import CodeTabs from "../../../components/docs/CodeTabs.astro"; Layer logs every query the gateway serves into a durable JSONL trail in S3, mirrored into Layer's hot cache for fast recent reads. Fetch events that downstream consumers tag back to a query land in a sibling clickstream feed. Together they make a search session reconstructable after the fact — for relevance tuning, A/B comparison, or incident review. Both feeds are Layer-only. ## Routes | Route | Behavior | | --- | --- | | `GET /v2/namespaces/{ns}/search-history` | Per-namespace query log, newest first. | | `GET /v2/namespaces/{ns}/clickstream` | Fetch events correlated to a search, newest first. | The `/v1/` versions of both routes are identical aliases held for client compatibility. ## Search history entry ```json { "entries": [ { "timestamp": "2026-05-22T08:00:00.000Z", "timestamp_nanos": 1747900800000000000, "namespace": "products", "trace_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "raw_query": "wireless headphones", "stable_as_of": 1747900700000, "query": {"vector": "[…]", "top_k": 10, "filters": "[…]"}, "top_result_ids": ["asin-B08N5WRWNW", "asin-B07PXGQC1Q"], "tags": ["app:hev-shop", "route:search", "surface:storefront"] } ], "next_cursor": "1747900799000000000" } ``` | Field | Meaning | | --- | --- | | `timestamp` / `timestamp_nanos` | Wall-clock and nanosecond timestamps. `timestamp_nanos` is the pagination cursor. | | `trace_id` | Trace context propagated or generated for the query. Joins to the clickstream feed. | | `raw_query` | Caller-supplied query string from the `x-hevlayer-search-query` header (e.g. the BM25 input). Omitted when the header is absent. | | `stable_as_of` | Epoch-ms namespace watermark used by the served response. Omitted on cold-start gateways before the namespace has a watermark. | | `query` | Structured query summary — vector shape, filters, ranking. | | `top_result_ids` | IDs from the served response, in rank order. | | `tags` | Caller-supplied labels propagated through request headers. Used for ad-hoc segmentation. | [Hybrid text](/docs/api/query#hybrid-text-fusion) queries log as a single entry whose `query` carries the `HybridText` expression, not the expanded legs, so re-issuing the logged query reproduces the whole expansion (tokenization, fuzzy legs, fusion) as a unit. [Routed](/docs/api/query#query-routing) queries additionally carry the routing decision (route, policy version, executed), so per-route engagement can be measured against the clickstream and a logged query can be replayed under a forced route. ### Writing metadata Set `x-hevlayer-search-query` on query requests to capture the human input, and set `x-hevlayer-tags` to a comma-separated list of segmentation tags. The Python client exposes these as the `raw_query` and `tags` keyword arguments; the Go client as the `WithSearchQuery` and `WithSearchTags` request options: ```python query = await client.query_namespace( "products", {"vector": embedding, "top_k": 10, "include_attributes": ["title"]}, raw_query="wireless headphones", tags=["app:hev-shop", "surface:storefront", "route:search", "page:first"], ) history = await client.list_search_history( "products", tags=["app:hev-shop", "route:search", "page:first"], limit=20, ) ``` ```go query, err := client.QueryNamespace(ctx, "products", &hevlayer.QueryRequest{Vector: embedding, TopK: 10, IncludeAttributes: []string{"title"}}, hevlayer.WithSearchQuery("wireless headphones"), hevlayer.WithSearchTags([]string{"app:hev-shop", "surface:storefront", "route:search", "page:first"}), ) history, err := client.ListSearchHistory(ctx, "products", &hevlayer.ListSearchHistoryParams{ Tag: []string{"app:hev-shop", "route:search", "page:first"}, Limit: 20, }) ``` ```typescript const query = await client.queryNamespace( "products", { vector: embedding, top_k: 10, include_attributes: ["title"] }, { searchQuery: "wireless headphones", tags: ["app:hev-shop", "surface:storefront", "route:search", "page:first"], }, ); const history = await client.listSearchHistory("products", { tags: ["app:hev-shop", "route:search", "page:first"], limit: 20, }); ``` ```bash curl -X POST "$LAYER_GATEWAY_URL/v2/namespaces/products/query" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -H "x-hevlayer-search-query: wireless headphones" \ -H "x-hevlayer-tags: app:hev-shop,surface:storefront,route:search,page:first" \ -d '{"vector": [0.0012, -0.043], "top_k": 10, "include_attributes": ["title"]}' curl "$LAYER_GATEWAY_URL/v2/namespaces/products/search-history?tag=app:hev-shop,route:search,page:first&limit=20" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` Keep the query text in `raw_query`; use tags for segmentation, not for duplicating the query string. ### Tag contract Layer splits `x-hevlayer-tags` and `?tag=` on commas, trims whitespace, drops empty values, then sorts and dedupes tags before storing or matching them. Commas are separators and cannot be escaped. Limits: | Limit | Value | | --- | --- | | Max tags | 32 unique tags per request or filter | | Max tag length | 128 bytes | | Allowed characters | ASCII letters, digits, `:`, `_`, `-`, `.`, `/`, `=`, `+` | The list filter uses AND semantics: `?tag=a,b` returns only entries that carry both `a` and `b`. ### Query parameters | Param | Purpose | | --- | --- | | `tag` | Comma-separated tag filter. AND semantics — every tag must match. | | `from` / `to` | RFC3339 time bounds. | | `before` | Pagination cursor; return entries strictly older than the given `timestamp_nanos`. | | `limit` | Cap 500, default 50. | ## Clickstream entry ```json { "events": [ { "timestamp": "2026-05-22T08:00:02.143Z", "timestamp_nanos": 1747900802143000000, "trace_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "namespace": "products", "doc_id": "asin-B08N5WRWNW", "tags": ["session:abc123"], "source": "fetch", "served_from": "cache" } ], "next_cursor": "1747900802142000000" } ``` `trace_id` joins to the search-history entry that produced the result; `served_from` distinguishes a cache hit from an upstream fetch. `trace_id` is also a supported query parameter so you can pull every event for a single search session: ```python events = await client.list_clickstream( "products", trace_id="f81d4fae-7dec-11d0-a765-00a0c91e6bf6", ) ``` ```go events, err := client.ListClickstream(ctx, "products", &hevlayer.ListClickstreamParams{ TraceID: "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", }) ``` ```typescript const events = await client.listClickstream("products", { traceId: "f81d4fae-7dec-11d0-a765-00a0c91e6bf6", }); ``` ```bash curl "$LAYER_GATEWAY_URL/v2/namespaces/products/clickstream?trace_id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6" \ -H "Authorization: Bearer $LAYER_GATEWAY_API_KEY" ``` ## Storage ```text search-history/{namespace}/{YYYY-MM-DD}/{timestamp_nanos}.jsonl ``` Writes are best-effort and never block the query response. Aerospike holds a recent window for fast reads; S3 is the durable store. A cache outage degrades read latency but not durability — list calls walk the S3 prefix and merge inline.