# hev layer — full docs > Concatenated docs surface. Index at https://hevlayer.com/llms.txt. --- ## Search knowledge graph Version: 2 Generated: 2026-07-28T14:02:31.026Z Content hash: a6e863a42cf528914f7a7396afa18ca84725389a9e6fe4f2ce1ae2d135112319 Context: hevlayer is a gateway and Kubernetes runtime around Turbopuffer-compatible vector stores. The gateway preserves familiar document and query APIs while adding stable reads, caching, federated and agentic retrieval, operational metadata, and durable support data in object storage. Pipelines ingest external data or change row cardinality; Functions enrich rows already stored in Layer. Kubernetes resources configure indexes, vector stores, warehouses, compute pools, credentials, snapshots, and serving policy while keeping the gateway data path independent from reconciliation. Licensing is verified locally: core gateway operations remain available at the open floor, expired trials enter the floor immediately, and only commercial licenses receive post-expiration grace. The system favors explicit lifecycle, authorization, observability, and reconstructible state, accepting some gateway and indexing overhead in return. Glossary: - stable watermark: The per-namespace point through which the backing index is known to be fully caught up. Aliases: stable read watermark, stable-as-of. - document cache: The ephemeral pull-through store used to accelerate document reads and pipeline staging while durable data remains elsewhere. Aliases: cache. - VectorStore: A declared search backend and its credentials, endpoint, and inbound authorization policy. Aliases: vector store, backing store. - Index: The control-plane resource that binds a namespace to backend, snapshot, scan, and scaling policy. Aliases: namespace index. - Pipeline: A staged compute workflow whose processing may change row cardinality and whose workers scale with queue depth. Aliases: indexing pipeline. - Function: A declared computation over rows that runs through operator-managed workers and preserves the intended row-level contract. Aliases: UDF, user-defined function. - snapshot: A durable, content-addressed view of namespace state and facet information at a known watermark. Aliases: namespace snapshot. - checkpoint: An immutable human-readable label for a durable namespace snapshot cut. Aliases: snapshot label. - grace: A temporary license state in which gated capabilities continue while operators are warned to renew or replace the key. Aliases: license grace. - license floor: The reduced capability set projected when no currently usable license or grace window remains. Aliases: floor. - Agent: A saved, governed reasoning configuration that reformulates federated searches and reranks retrieved rows. - ApiKey: A managed credential resource carrying scoped entitlements and opaque claims. - InfraRules: The singleton cluster policy for compute pools, cache settings, and shared scaling constraints. - Warehouse: A verified external source identity and credential used by ingestion pipelines. - warm window: A cooldown that retains a worker and its node briefly after demand drains. Raw JSON: ```json { "version": 2, "generatedAt": "2026-07-28T14:02:31.026Z", "contentHash": "a6e863a42cf528914f7a7396afa18ca84725389a9e6fe4f2ce1ae2d135112319", "context": "hevlayer is a gateway and Kubernetes runtime around Turbopuffer-compatible vector stores. The gateway preserves familiar document and query APIs while adding stable reads, caching, federated and agentic retrieval, operational metadata, and durable support data in object storage. Pipelines ingest external data or change row cardinality; Functions enrich rows already stored in Layer. Kubernetes resources configure indexes, vector stores, warehouses, compute pools, credentials, snapshots, and serving policy while keeping the gateway data path independent from reconciliation. Licensing is verified locally: core gateway operations remain available at the open floor, expired trials enter the floor immediately, and only commercial licenses receive post-expiration grace. The system favors explicit lifecycle, authorization, observability, and reconstructible state, accepting some gateway and indexing overhead in return.", "glossary": [ { "term": "stable watermark", "aliases": [ "stable read watermark", "stable-as-of" ], "definition": "The per-namespace point through which the backing index is known to be fully caught up." }, { "term": "document cache", "aliases": [ "cache" ], "definition": "The ephemeral pull-through store used to accelerate document reads and pipeline staging while durable data remains elsewhere." }, { "term": "VectorStore", "aliases": [ "vector store", "backing store" ], "definition": "A declared search backend and its credentials, endpoint, and inbound authorization policy." }, { "term": "Index", "aliases": [ "namespace index" ], "definition": "The control-plane resource that binds a namespace to backend, snapshot, scan, and scaling policy." }, { "term": "Pipeline", "aliases": [ "indexing pipeline" ], "definition": "A staged compute workflow whose processing may change row cardinality and whose workers scale with queue depth." }, { "term": "Function", "aliases": [ "UDF", "user-defined function" ], "definition": "A declared computation over rows that runs through operator-managed workers and preserves the intended row-level contract." }, { "term": "snapshot", "aliases": [ "namespace snapshot" ], "definition": "A durable, content-addressed view of namespace state and facet information at a known watermark." }, { "term": "checkpoint", "aliases": [ "snapshot label" ], "definition": "An immutable human-readable label for a durable namespace snapshot cut." }, { "term": "grace", "aliases": [ "license grace" ], "definition": "A temporary license state in which gated capabilities continue while operators are warned to renew or replace the key." }, { "term": "license floor", "aliases": [ "floor" ], "definition": "The reduced capability set projected when no currently usable license or grace window remains." }, { "term": "Agent", "aliases": [], "definition": "A saved, governed reasoning configuration that reformulates federated searches and reranks retrieved rows." }, { "term": "ApiKey", "aliases": [], "definition": "A managed credential resource carrying scoped entitlements and opaque claims." }, { "term": "InfraRules", "aliases": [], "definition": "The singleton cluster policy for compute pools, cache settings, and shared scaling constraints." }, { "term": "Warehouse", "aliases": [], "definition": "A verified external source identity and credential used by ingestion pipelines." }, { "term": "warm window", "aliases": [], "definition": "A cooldown that retains a worker and its node briefly after demand drains." } ], "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- Embed — `api/embed`\n- Embed and Auto routing — `api/embed#embed-and-auto-routing`\n- Embedding cost — `api/embed#embedding-cost`\n- Model resolution — `api/embed#model-resolution`\n- Token accounting — `api/embed#token-accounting`\n- Using Embed — `api/embed#using-embed`\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- Install An AWS Environment — `cli#install-an-aws-environment`\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- Guided CLI install — `install#guided-cli-install`\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- Chunking — `kubernetes/index-crd#chunking`\n- Embedding — `kubernetes/index-crd#embedding`\n- Model-serving policy — `kubernetes/index-crd#model-serving-policy`\n- Scan policy — `kubernetes/index-crd#scan-policy`\n- Schema-attribute embedding — `kubernetes/index-crd#schema-attribute-embedding`\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. Clone the repo — `quickstart#1-clone-the-repo`\n- 2. Configure and start the gateway — `quickstart#2-configure-and-start-the-gateway`\n- 3. Initialize the namespace — `quickstart#3-initialize-the-namespace`\n- 4. Run a query — `quickstart#4-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": [ "When should I use a Pipeline instead of a Function?", "How does Layer keep reads stable across vector stores?", "How do I install and operate Layer on Kubernetes?", "How are API keys and resource entitlements scoped?", "What happens when a trial or commercial license expires?" ], "nodes": [ { "id": "agents", "kind": "section", "title": "Agents", "heading": null, "group": "Overview", "url": "/docs/agents", "summary": "Shows how coding agents can query Layer documentation and operate Layer environments using portable skill files and command-line tools.", "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": [ "shows", "coding", "agents", "query", "layer", "documentation", "operate", "environments", "portable", "skill", "files", "command", "line", "tools", "callout", "astro", "docs", "agent", "file", "skills", "work", "across", "harnesses", "these", "queryable", "same", "engine", "behind", "search", "site", "ships", "read", "cite", "directly", "scraping", "server", "also", "lets", "indexes", "pipelines" ] }, { "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": "Explains how to install the command-line tools needed for agent-based documentation lookup and Layer operations.", "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", "explains", "command", "line", "tools", "needed", "agent", "based", "documentation", "lookup", "layer", "operations", "github", "latest", "build", "apps", "binary", "self", "contained", "harness", "shell", "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": "Provides a portable agent skill that grounds Layer answers in the published documentation and cites the relevant sections.", "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", "provides", "portable", "agent", "grounds", "layer", "answers", "published", "documentation", "cites", "relevant", "sections", "home", "codex", "skills", "claude", "agentskillhome", "harness", "directory", "such", "code", "codexhome", "mkdir", "hevlayer", "name", "description", "query", "user", "asks", "about", "turbopuffer", "gateway", "stable", "reads", "watermark", "document", "cache", "warm", "jobs" ] }, { "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": "Provides a portable agent skill for safe Layer inspection and operation, separating read-only work from state-changing actions.", "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", "provides", "portable", "agent", "safe", "inspection", "operation", "separating", "read", "only", "work", "state", "changing", "actions", "should", "inspect", "operate", "through", "keeps", "docs", "lookup", "mutating", "operations", "separate", "agentskillhome", "codexhome", "home", "codex", "skills", "mkdir", "hevlayer", "name", "description", "user", "asks", "environments", "query", "list", "indexes" ] }, { "id": "agents#4-ask", "kind": "section", "title": "Agents", "heading": "4. Ask", "group": "Overview", "url": "/docs/agents#4-ask", "summary": "Demonstrates the typical grounded-answer workflow: search the documentation, retrieve the best matching section, and cite it.", "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": [ "demonstrates", "typical", "grounded", "answer", "workflow", "search", "documentation", "retrieve", "best", "matching", "section", "cite", "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", "citation" ] }, { "id": "agents#the-verbs", "kind": "section", "title": "Agents", "heading": "The verbs", "group": "Overview", "url": "/docs/agents#the-verbs", "summary": "Summarizes the documentation query capabilities for orientation, ranked search, section retrieval, and glossary resolution.", "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", "summarizes", "documentation", "query", "capabilities", "orientation", "ranked", "search", "section", "retrieval", "glossary", "resolution", "overview", "term", "watermark", "verb", "returns", "context", "plus", "full", "stable", "sections", "snippets", "deep", "links", "summary", "exact", "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": "Explains how a committed, reviewable documentation digest and verified deep links keep agent answers current, traceable, and inexpensive to retrieve.", "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", "explains", "committed", "reviewable", "documentation", "digest", "verified", "deep", "links", "keep", "agent", "current", "traceable", "inexpensive", "retrieve", "llms", "full", "search", "runs", "these", "docs", "same", "corpus", "heading", "renders", "site", "every", "anchor", "against", "rendered", "pages", "cited", "link", "like", "query", "stable", "reads", "always" ] }, { "id": "api/agents", "kind": "section", "title": "Agentic search", "heading": null, "group": "API", "url": "/docs/api/agents", "summary": "Provides an overview of Agentic search, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "agentic", "search", "purpose", "behavior", "users", "should", "expect", "post", "agents", "name", "query", "agent", "codetabs", "astro", "configured", "reasoning", "loop", "indices", "plan", "recall", "score", "relevance", "return", "standard", "shape", "runs", "more", "namespaces", "returns", "same", "every", "other", "endpoint", "model", "reads", "fans", "diverse", "phrasings" ] }, { "id": "api/agents#auth", "kind": "section", "title": "Agentic search", "heading": "Auth", "group": "API", "url": "/docs/api/agents#auth", "summary": "Explains the authentication and authorization rules that apply to Agentic search.", "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", "explains", "authentication", "authorization", "rules", "apply", "agentic", "search", "agent", "name", "follows", "same", "model", "other", "endpoints", "multi", "namespace", "queries", "follow", "federated", "query", "behavior", "minted", "additionally", "needs", "entitlement", "apikey", "invoke" ] }, { "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": "Explains bring your own embedding in the context of Agentic search, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "agentic", "search", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "curl", "post", "layer", "gateway", "agents", "support", "query", "authorization", "bearer", "content", "type", "application", "json", "auth", "errors", "after", "june", "upgrade", "vector", "0123", "0456", "0789", "agent", "fans", "recall", "both", "routes", "lexical" ] }, { "id": "api/agents#configuration", "kind": "section", "title": "Agentic search", "heading": "Configuration", "group": "API", "url": "/docs/api/agents#configuration", "summary": "Explains which settings control Agentic search and where those settings are defined.", "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", "explains", "settings", "control", "agentic", "search", "those", "defined", "agent", "kubectl", "yaml", "client", "support", "apply", "everything", "request", "omits", "bound", "resource", "model", "credential", "deadline", "indices", "fusion", "weighting", "output", "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": "Explains provenance and trace in the context of Agentic search, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "agentic", "search", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "agent", "retrievalscore", "fanout", "relevancescore", "query", "queryindex", "queries", "turns", "deadlinehit", "output", "response", "gains", "echo", "carries", "field", "both", "scores", "rows", "4821", "namespace", "tickets", "rank", "score", "authentication", "failure", "post", "upgrade", "merge" ] }, { "id": "api/agents#request", "kind": "section", "title": "Agentic search", "heading": "Request", "group": "API", "url": "/docs/api/agents#request", "summary": "Describes the inputs accepted by Agentic search and the boundaries between request data and configured behavior.", "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", "describes", "inputs", "accepted", "agentic", "search", "boundaries", "between", "data", "configured", "behavior", "response", "await", "client", "agent", "support", "query", "auth", "errors", "after", "june", "upgrade", "hevlayer", "agentqueryrequest", "topk", "const", "curl", "post", "layer", "gateway", "agents", "authorization", "bearer", "content", "type", "application", "json", "vector", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/agents#response", "kind": "section", "title": "Agentic search", "heading": "Response", "group": "API", "url": "/docs/api/agents#response", "summary": "Describes the response behavior and metadata returned by Agentic search.", "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", "describes", "behavior", "metadata", "returned", "agentic", "search", "rows", "4821", "namespace", "tickets", "rank", "score", "subject", "login", "fails", "after", "upgrade", "merge", "method", "weighted", "route", "dual", "namespaces", "stable", "1747300000123", "matched", "dist", "output", "provenance", "federated", "query", "shape", "carrying", "native", "plus", "block", "names", "fusion", "stableasof" ] }, { "id": "api/agents#validation", "kind": "section", "title": "Agentic search", "heading": "Validation", "group": "API", "url": "/docs/api/agents#validation", "summary": "Summarizes invalid conditions, authorization failures, and runtime errors for Agentic search, including how callers can distinguish them.", "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", "summarizes", "invalid", "conditions", "authorization", "failures", "runtime", "errors", "agentic", "search", "including", "callers", "distinguish", "name", "ready", "agent", "query", "vector", "ondeadline", "besteffort", "deadlinehit", "true", "error", "condition", "status", "known", "minted", "lacks", "entitlement", "bound", "index", "outside", "namespace", "grant", "empty", "present", "dimensionality", "does", "match", "indices" ] }, { "id": "api/blobs", "kind": "section", "title": "Blobs", "heading": null, "group": "API", "url": "/docs/api/blobs", "summary": "Provides an overview of Blobs, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "blobs", "purpose", "behavior", "users", "should", "expect", "image", "blob", "products", "sha256", "codetabs", "astro", "durable", "content", "addressed", "bytes", "served", "through", "gateway", "store", "opaque", "layer", "bucket", "serve", "aerospike", "pull", "cache", "never", "stores", "themselves", "ordinary", "string", "attribute", "such", "imageblob", "media", "other", "binary" ] }, { "id": "api/blobs#fetch", "kind": "section", "title": "Blobs", "heading": "Fetch", "group": "API", "url": "/docs/api/blobs#fetch", "summary": "Explains fetch in the context of Blobs, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "blobs", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "image", "await", "client", "blob", "products", "stored", "sha256", "getblob", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "cache", "control", "public", "31536000", "immutable", "etag", "jpeg", "webp", "content", "type", "application", "octet", "stream", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/blobs#routes", "kind": "section", "title": "Blobs", "heading": "Routes", "group": "API", "url": "/docs/api/blobs#routes", "summary": "Summarizes the available operations for Blobs and the behavior of each operation.", "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", "summarizes", "available", "operations", "blobs", "behavior", "operation", "namespaces", "blob", "sha256", "route", "method", "store", "bytes", "return", "reference", "serve", "aerospike", "cache", "falling", "back", "backfilling" ] }, { "id": "api/blobs#store", "kind": "section", "title": "Blobs", "heading": "Store", "group": "API", "url": "/docs/api/blobs#store", "summary": "Explains store in the context of Blobs, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "blobs", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "open", "image", "stored", "await", "client", "blob", "products", "read", "print", "body", "readfile", "putblob", "import", "node", "promises", "const", "bytes", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "content", "type", "application", "octet", "stream", "data", "binary" ] }, { "id": "api/blobs#warm-policy", "kind": "section", "title": "Blobs", "heading": "Warm Policy", "group": "API", "url": "/docs/api/blobs#warm-policy", "summary": "Explains warm policy in the context of Blobs, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "blobs", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "true", "hint", "cache", "blob", "reads", "pull", "through", "today", "miss", "backfills", "aerospike", "best", "effort", "write", "object", "bulk", "hintcachewarm", "intentionally", "part", "first", "slice", "needs", "namespace", "declaration", "attributes", "references", "explicit", "budget", "because" ] }, { "id": "api/checkpoints", "kind": "section", "title": "Checkpoints", "heading": null, "group": "API", "url": "/docs/api/checkpoints", "summary": "Provides an overview of Checkpoints, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "checkpoints", "purpose", "behavior", "users", "should", "expect", "catalog", "watermark", "count", "codetabs", "astro", "immutable", "labels", "namespace", "snapshot", "watermarks", "give", "application", "stable", "name", "known", "good", "creating", "checkpoint", "newest", "durable", "body", "stores", "small", "label", "record", "does", "scan", "write", "rows", "downstream", "needs", "browse" ] }, { "id": "api/checkpoints#create", "kind": "section", "title": "Checkpoints", "heading": "Create", "group": "API", "url": "/docs/api/checkpoints#create", "summary": "Explains create in the context of Checkpoints, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "checkpoints", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "checkpoint", "await", "client", "products", "label", "catalog", "2026", "createcheckpoint", "hevlayer", "createcheckpointrequest", "const", "curl", "post", "layer", "gateway", "namespaces", "authorization", "bearer", "content", "type", "application", "json", "namespace", "watermark", "1749513600000", "3f9e8b21", "count", "10000", "precondition", "failed" ] }, { "id": "api/checkpoints#list", "kind": "section", "title": "Checkpoints", "heading": "List", "group": "API", "url": "/docs/api/checkpoints#list", "summary": "Explains list in the context of Checkpoints, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "checkpoints", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "page", "await", "client", "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", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/checkpoints#resolve", "kind": "section", "title": "Checkpoints", "heading": "Resolve", "group": "API", "url": "/docs/api/checkpoints#resolve", "summary": "Explains resolve in the context of Checkpoints, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "checkpoints", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "checkpoint", "await", "client", "products", "catalog", "2026", "getcheckpoint", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "found", "layergatewayurl", "layergatewayapikey", "returns", "notfound", "label", "does", "exist", "namespace" ] }, { "id": "api/checkpoints#routes", "kind": "section", "title": "Checkpoints", "heading": "Routes", "group": "API", "url": "/docs/api/checkpoints#routes", "summary": "Summarizes the available operations for Checkpoints and the behavior of each operation.", "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", "summarizes", "available", "operations", "checkpoints", "behavior", "operation", "post", "namespaces", "label", "route", "method", "create", "return", "immutable", "checkpoint", "list", "newest", "first", "resolve" ] }, { "id": "api/data-supply", "kind": "section", "title": "VectorStores And Warehouses", "heading": null, "group": "API", "url": "/docs/api/data-supply", "summary": "Provides an overview of VectorStores And Warehouses, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "vectorstores", "warehouses", "purpose", "behavior", "users", "should", "expect", "vectorstore", "warehouse", "read", "declared", "vector", "stores", "upstream", "through", "gateway", "layer", "exposes", "data", "supply", "resources", "only", "routes", "serving", "side", "connection", "source", "pipelines", "responses", "safe", "show", "operator", "tools", "include", "secret", "reference", "names", "keys" ] }, { "id": "api/data-supply#vectorstores", "kind": "section", "title": "VectorStores And Warehouses", "heading": "VectorStores", "group": "API", "url": "/docs/api/data-supply#vectorstores", "summary": "Explains vectorstores in the context of VectorStores And Warehouses, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "warehouses", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "curl", "authorization", "bearer", "layer", "base", "name", "turbopufferurl", "spec", "turbopuffer", "orgid", "layerapikey", "layerbaseurl", "prod", "kind", "default", "true", "endpoint", "https", "east", "region", "org123", "credential", "secretref", "inboundauth", "mode", "derivefromstore", "status", "reachable", "observedgeneration", "conditions" ] }, { "id": "api/data-supply#warehouses", "kind": "section", "title": "VectorStores And Warehouses", "heading": "Warehouses", "group": "API", "url": "/docs/api/data-supply#warehouses", "summary": "Explains warehouses in the context of VectorStores And Warehouses, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "vectorstores", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "curl", "authorization", "bearer", "layer", "base", "name", "phase", "pending", "verified", "failed", "status", "failurereason", "consumers", "layerapikey", "layerbaseurl", "prod", "snowflake", "kind", "account", "acme", "xy12345", "user", "svclayer", "role", "svclayerrole", "warehouse", "extractwh", "keypairsecretref", "pool", "size" ] }, { "id": "api/embed", "kind": "section", "title": "Embed", "heading": null, "group": "API", "url": "/docs/api/embed", "summary": "Provides an overview of Embed, its purpose, and the behavior users should expect.", "facts": [ { "kind": "code", "literal": "Embed", "chunkId": "api/embed" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/embed" }, { "kind": "code", "literal": "prefer: native", "chunkId": "api/embed" }, { "kind": "value", "literal": "StoreSwitch.astro", "chunkId": "api/embed" }, { "kind": "value", "literal": "StoreNote.astro", "chunkId": "api/embed" }, { "kind": "value", "literal": "Upstream.astro", "chunkId": "api/embed" }, { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/embed" }, { "kind": "value", "literal": "turbopuffer.com", "chunkId": "api/embed" } ], "sources": [ { "chunkId": "api/embed", "url": "/docs/api/embed", "anchor": null } ], "mode": "source-primary", "terms": [ "provides", "overview", "embed", "purpose", "behavior", "users", "should", "expect", "rank", "prefer", "native", "storeswitch", "astro", "storenote", "upstream", "codetabs", "turbopuffer", "query", "time", "embedding", "function", "token", "accounting", "cost", "side", "half", "schema", "attribute", "rankby", "turns", "text", "vector", "server", "caller", "never", "runs", "step", "matches", "embeddings", "wire" ] }, { "id": "api/embed#embed-and-auto-routing", "kind": "section", "title": "Embed", "heading": "Embed and Auto routing", "group": "API", "url": "/docs/api/embed#embed-and-auto-routing", "summary": "Explains embed and auto routing in the context of Embed, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "Embed", "chunkId": "api/embed#embed-and-auto-routing" }, { "kind": "code", "literal": "Auto", "chunkId": "api/embed#embed-and-auto-routing" }, { "kind": "code", "literal": "routing.executed: false", "chunkId": "api/embed#embed-and-auto-routing" }, { "kind": "code", "literal": "embed:", "chunkId": "api/embed#embed-and-auto-routing" } ], "sources": [ { "chunkId": "api/embed#embed-and-auto-routing", "url": "/docs/api/embed#embed-and-auto-routing", "anchor": "embed-and-auto-routing" } ], "mode": "source-primary", "terms": [ "embed", "auto", "routing", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "executed", "false", "query", "spelling", "defers", "caller", "chosen", "route", "needs", "vector", "request", "didn", "supply", "passing", "inline", "source", "retires", "round", "trip", "column", "declared", "profile", "semantic", "fused", "legs", "resolve", "execute", "deferral", "remains" ] }, { "id": "api/embed#embedding-cost", "kind": "section", "title": "Embed", "heading": "Embedding cost", "group": "API", "url": "/docs/api/embed#embedding-cost", "summary": "Explains embedding cost in the context of Embed, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "billing", "chunkId": "api/embed#embedding-cost" }, { "kind": "code", "literal": "hevlayer_embed_tokens_total", "chunkId": "api/embed#embedding-cost" }, { "kind": "code", "literal": "/v2/cost", "chunkId": "api/embed#embedding-cost" }, { "kind": "code", "literal": "/v2/cost/rate-card", "chunkId": "api/embed#embedding-cost" }, { "kind": "code", "literal": "tpuf_embeddings:/", "chunkId": "api/embed#embedding-cost" } ], "sources": [ { "chunkId": "api/embed#embedding-cost", "url": "/docs/api/embed#embedding-cost", "anchor": "embedding-cost" } ], "mode": "source-primary", "terms": [ "embedding", "cost", "explains", "context", "embed", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "billing", "hevlayer", "tokens", "total", "rate", "card", "tpuf", "embeddings", "provider", "model", "serving", "modes", "release", "managed", "menu", "billed", "gateway", "ingests", "object", "existing", "turbopuffer", "counters", "prices", "hevlayerembedtokenstotal", "published", "million", "token", "rates", "same" ] }, { "id": "api/embed#model-resolution", "kind": "section", "title": "Embed", "heading": "Model resolution", "group": "API", "url": "/docs/api/embed#model-resolution", "summary": "Explains model resolution in the context of Embed, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "voyage/voyage-4-lite", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "cohere/embed-v4.0", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "google/gemini-embedding-*", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "qwen/qwen3-embedding-*", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "baai/bge-m3", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "voyage-3-lite", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "embed.revision", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "embed.instructions.query", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "embed.instructions.document", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "modality: image", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "Embed", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "autoscaler", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "blended", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "rank_by", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "{model}", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "embed_", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "422", "chunkId": "api/embed#model-resolution" }, { "kind": "code", "literal": "a model name must be provided", "chunkId": "api/embed#model-resolution" } ], "sources": [ { "chunkId": "api/embed#model-resolution", "url": "/docs/api/embed#model-resolution", "anchor": "model-resolution" } ], "mode": "source-primary", "terms": [ "model", "resolution", "explains", "context", "embed", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "voyage", "lite", "cohere", "google", "gemini", "embedding", "qwen", "qwen3", "baai", "revision", "instructions", "query", "document", "modality", "image", "autoscaler", "blended", "rank", "attr", "name", "must", "provided", "provider", "namespaced", "example", "bare", "such", "rejected", "layer" ] }, { "id": "api/embed#token-accounting", "kind": "section", "title": "Embed", "heading": "Token accounting", "group": "API", "url": "/docs/api/embed#token-accounting", "summary": "Explains token accounting in the context of Embed, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "{\n \"rows\": [ /* ... */ ],\n \"performance\": {\n \"embedding_tokens\": 8,\n \"embedding_ms\": 42\n }\n}", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "performance", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "embedding_tokens", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "embedding_ms", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "namespace", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "store_kind", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "model", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "serving", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "hevlayer_embed_tokens_total", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "performance.embedding_tokens", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "hevlayer_embed_compute_seconds_total", "chunkId": "api/embed#token-accounting" }, { "kind": "code", "literal": "performance.embedding_ms", "chunkId": "api/embed#token-accounting" } ], "sources": [ { "chunkId": "api/embed#token-accounting", "url": "/docs/api/embed#token-accounting", "anchor": "token-accounting" } ], "mode": "source-primary", "terms": [ "token", "accounting", "explains", "context", "embed", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "rows", "performance", "embedding", "tokens", "namespace", "store", "kind", "model", "serving", "hevlayer", "total", "compute", "seconds", "write", "query", "responses", "preserve", "tpuf", "measurements", "under", "embeddingtokens", "embeddingms", "writes", "include", "queries", "always", "present", "only", "cache" ] }, { "id": "api/embed#using-embed", "kind": "section", "title": "Embed", "heading": "Using Embed", "group": "API", "url": "/docs/api/embed#using-embed", "summary": "Explains using embed in the context of Embed, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "// source attribute: the schema's model is inferred\n\"rank_by\": [\"text\", \"ANN\", [\"Embed\", \"chest pain radiating to left arm\"]]\n\n// derived vector column: the model is required explicitly\n\"rank_by\": [\"embed_text\", \"ANN\", [\"Embed\", \"chest pain radiating to left arm\", {\n \"model\": \"voyage/voyage-4-lite\"\n}]]", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "response = await client.query_namespace(\"clinical-notes\", {\n \"rank_by\": [\"text\", \"ANN\", [\"Embed\", \"chest pain radiating to left arm\"]],\n \"top_k\": 10,\n})\nprint(response.rows, response.performance.embedding_tokens)", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "response, err := client.QueryNamespace(ctx, \"clinical-notes\", &hevlayer.QueryRequest{\n RankBy: []any{\"text\", \"ANN\", []any{\"Embed\", \"chest pain radiating to left arm\"}},\n TopK: 10,\n})", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "const response = await client.queryNamespace(\"clinical-notes\", {\n rank_by: [\"text\", \"ANN\", [\"Embed\", \"chest pain radiating to left arm\"]],\n top_k: 10,\n});", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "curl -X POST \"$LAYER_GATEWAY_URL/v2/namespaces/clinical-notes/query\" \\\n -H \"Authorization: Bearer $LAYER_GATEWAY_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"rank_by\": [\"text\", \"ANN\", [\"Embed\", \"chest pain radiating to left arm\"]],\n \"top_k\": 10\n }'", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "Embed", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "prefer: native", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "performance", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "prefer: autoscaler", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "prefer: blended", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "LAYER_EMBED_CACHE_TTL_MS", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "kind: turbopuffer", "chunkId": "api/embed#using-embed" }, { "kind": "code", "literal": "503 service_unavailable", "chunkId": "api/embed#using-embed" } ], "sources": [ { "chunkId": "api/embed#using-embed", "url": "/docs/api/embed#using-embed", "anchor": "using-embed" } ], "mode": "source-primary", "terms": [ "embed", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "source", "attribute", "schema", "model", "inferred", "rank", "text", "chest", "pain", "radiating", "left", "derived", "vector", "column", "required", "explicitly", "voyage", "lite", "response", "await", "client", "query", "namespace", "clinical", "notes", "print", "rows", "performance", "embedding", "tokens", "querynamespace" ] }, { "id": "api/federated-query", "kind": "section", "title": "Federated query", "heading": null, "group": "API", "url": "/docs/api/federated-query", "summary": "Provides an overview of Federated query, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "federated", "query", "purpose", "behavior", "users", "should", "expect", "post", "codetabs", "astro", "federate", "across", "namespaces", "merge", "results", "single", "ranked", "list", "scoped", "entitlements", "runs", "namespace", "less", "endpoint", "names", "path", "while", "takes", "body", "longer", "parameter", "upstream", "equivalent", "turbopuffer", "multi", "layer", "composition", "reads" ] }, { "id": "api/federated-query#consistency", "kind": "section", "title": "Federated query", "heading": "Consistency", "group": "API", "url": "/docs/api/federated-query#consistency", "summary": "Explains consistency in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "namespaces", "stable", "layer", "namespace", "read", "watermark", "there", "single", "consistent", "across", "independent", "block", "reports", "stableasof", "response", "header", "carries", "minimum", "reached", "most", "conservative", "answer", "does", "manufacture", "global" ] }, { "id": "api/federated-query#entitlements", "kind": "section", "title": "Federated query", "heading": "Entitlements", "group": "API", "url": "/docs/api/federated-query#entitlements", "summary": "Explains entitlements in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "namespaces", "strict", "vectorstore", "name", "uses", "same", "store", "derived", "authentication", "path", "individual", "namespace", "queries", "upstream", "must", "able", "read", "listed", "failure", "reported", "under", "partial", "unless", "enabled", "minted", "scoped", "keys", "explicitly", "named" ] }, { "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": "Explains fan-out and fuse in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "response", "await", "client", "namespaces", "moment", "changelog", "latent", "space", "priors", "rank", "text", "auto", "evaluating", "systems", "filters", "published", "1740000000", "include", "attributes", "show", "source", "start", "const", "rows", "hybridtext", "routing", "supply", "ranking", "gateway" ] }, { "id": "api/federated-query#filters", "kind": "section", "title": "Federated query", "heading": "Filters", "group": "API", "url": "/docs/api/federated-query#filters", "summary": "Explains filters in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "filter", "schema", "mismatch", "matched", "rows", "errors", "layer", "partial", "true", "strict", "expression", "applied", "every", "namespace", "evaluates", "independently", "against", "only", "behaves", "uniformly", "attributes", "references", "part", "shared", "filterable", "across", "present", "same", "type" ] }, { "id": "api/federated-query#fusion-options", "kind": "section", "title": "Federated query", "heading": "Fusion options", "group": "API", "url": "/docs/api/federated-query#fusion-options", "summary": "Explains fusion options in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "namespace", "limit", "clamp", "rank", "constant", "option", "default", "meaning", "pernamespacelimit", "topk", "many", "rows", "returns", "merge", "shallower", "single", "perleglimit", "across", "wide", "most", "namespaces", "contribute", "nothing", "final", "deep", "retrieval", "wasted", "integer" ] }, { "id": "api/federated-query#limits", "kind": "section", "title": "Federated query", "heading": "Limits", "group": "API", "url": "/docs/api/federated-query#limits", "summary": "Explains limits in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "cursor", "limit", "value", "namespaces", "request", "naming", "excess", "pagination", "supported", "rejected", "fused", "across", "independent", "does", "form", "monotone", "bands", "relies" ] }, { "id": "api/federated-query#merge", "kind": "section", "title": "Federated query", "heading": "Merge", "group": "API", "url": "/docs/api/federated-query#merge", "summary": "Explains merge in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "dist", "method", "distance", "bm25", "hybridtext", "fused", "hybrid", "text", "score", "rank", "interleave", "fusion", "namespace", "limit", "merges", "quantity", "route", "makes", "comparable", "across", "namespaces", "vector", "distances", "share", "embedding", "space", "gateway", "order", "exact" ] }, { "id": "api/federated-query#partial-failure", "kind": "section", "title": "Federated query", "heading": "Partial failure", "group": "API", "url": "/docs/api/federated-query#partial-failure", "summary": "Explains partial failure in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "rows", "errors", "namespace", "moment", "priors", "error", "upstream", "found", "ep123", "latent", "space", "rank", "code", "filter", "schema", "mismatch", "detail", "attribute", "published", "absent", "filterable", "incompatible", "type", "layer", "true", "strict", "across", "many" ] }, { "id": "api/federated-query#response", "kind": "section", "title": "Federated query", "heading": "Response", "group": "API", "url": "/docs/api/federated-query#response", "summary": "Describes the response behavior and metadata returned by Federated query.", "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", "describes", "behavior", "metadata", "returned", "federated", "query", "namespace", "rank", "merge", "namespaces", "score", "dist", "method", "distance", "interleave", "route", "fused", "stable", "matched", "limit", "routing", "hybrid", "auto", "hybridtext", "list", "carries", "origin", "position", "within", "results", "orders", "block", "names", "strategy", "reports", "freshness", "many", "rows", "ep123" ] }, { "id": "api/federated-query#validation", "kind": "section", "title": "Federated query", "heading": "Validation", "group": "API", "url": "/docs/api/federated-query#validation", "summary": "Summarizes invalid conditions, authorization failures, and runtime errors for Federated query, including how callers can distinguish them.", "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", "summarizes", "invalid", "conditions", "authorization", "failures", "runtime", "errors", "federated", "query", "including", "callers", "distinguish", "strict", "true", "filters", "code", "filter", "schema", "mismatch", "layer", "partial", "namespaces", "cursor", "rank", "condition", "status", "named", "namespace", "outside", "minted", "grant", "read", "fails", "upstream", "cannot", "evaluate", "attribute", "absent", "wrong" ] }, { "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": "Explains vector merge requires a matching embedding space in the context of Federated query, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "federated", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "spec", "index", "backend", "distancemetric", "method", "distance", "rank", "interleave", "downgraded", "reason", "missing", "profile", "mismatch", "strict", "true", "merging", "only", "meaningful", "every", "namespace", "embeds", "same", "geometry", "declare" ] }, { "id": "api/introduction", "kind": "section", "title": "Introduction", "heading": null, "group": "API", "url": "/docs/api/introduction", "summary": "Provides an overview of Introduction, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "introduction", "purpose", "behavior", "users", "should", "expect", "layer", "codetabs", "astro", "storeswitch", "storenote", "upstream", "featuregate", "adds", "turbopuffer", "compatible", "client", "wire", "point", "gateway", "speaks", "store", "native", "protocol", "adding", "fields", "needs", "through", "headers", "pointing", "just", "works", "gains", "stable", "reads", "document", "cache", "enhanced" ] }, { "id": "api/introduction#authentication", "kind": "section", "title": "Introduction", "heading": "Authentication", "group": "API", "url": "/docs/api/introduction#authentication", "summary": "Explains the authentication and authorization rules that apply to Introduction.", "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", "explains", "authorization", "rules", "apply", "introduction", "bearer", "vectorstore", "read", "write", "admin", "layer", "gateway", "derivefromstore", "keys", "turbopuffer", "https", "east", "every", "request", "carries", "accepts", "kinds", "store", "default", "credential", "already", "accepted", "drop", "backed", "point", "existing", "client", "keep", "setup", "full", "access", "minted", "mint", "scoped" ] }, { "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": "Explains cache warm hint in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "turbopuffer", "hintcachewarm", "upstream", "contract", "query", "parameters", "passthrough", "response", "returned", "verbatim", "option", "supplied", "forwards", "runs", "layer", "side", "steps", "backfill", "aerospike", "document", "origin", "plus", "mirror", "latest", "snapshot", "body", "step" ] }, { "id": "api/introduction#compatibility-posture", "kind": "section", "title": "Introduction", "heading": "Compatibility posture", "group": "API", "url": "/docs/api/introduction#compatibility-posture", "summary": "Explains compatibility posture in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "turbopuffer", "layer", "drop", "existing", "clients", "routes", "upstream", "does", "implement", "namespaced", "under", "shadow", "request", "route", "doesn", "proxy", "returns", "rather", "being", "silently", "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": "Explains cross-cutting conventions in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "upserted", "layer", "cache", "miss", "error", "next", "cursor", "these", "apply", "every", "endpoint", "proxies", "whether", "route", "upstream", "compatible", "only", "reserved", "document", "attributes", "prefixed", "proxy", "writing", "validation", "reading", "fine", "explicitly" ] }, { "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": "Explains enhancements to upstream routes in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "below", "wire", "compatible", "turbopuffer", "body", "section", "describes", "only", "layer", "overlays" ] }, { "id": "api/introduction#gateway-failures", "kind": "section", "title": "Introduction", "heading": "Gateway failures", "group": "API", "url": "/docs/api/introduction#gateway-failures", "summary": "Explains gateway failures in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "python", "typescript", "sdks", "talk", "layer", "unreachable", "original", "connection", "error", "returned", "retry", "directly", "against", "backing", "store", "because", "server", "chooses", "namespace", "client", "surface", "stays", "backend", "neutral" ] }, { "id": "api/introduction#install", "kind": "section", "title": "Introduction", "heading": "Install", "group": "API", "url": "/docs/api/introduction#install", "summary": "Explains how to install the components needed to use Introduction.", "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", "explains", "components", "needed", "introduction", "hevlayer", "python", "github", "layer", "node", "import", "asynchevlayer", "client", "base", "environ", "gateway", "newclient", "withbaseurl", "getenv", "withapikey", "const", "baseurl", "process", "apikey", "curl", "namespaces", "authorization", "bearer", "apps", "openapi", "yaml", "context", "there", "four", "ways", "call", "typescript", "rest", "itself", "clients" ] }, { "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": "Explains metadata in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "stable", "turbopuffer", "upstream", "contract", "namespace", "schema", "count", "index", "status", "timestamps", "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": "Explains query in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "upserted", "watermark", "updating", "layer", "stable", "turbopuffer", "upstream", "contract", "vector", "queries", "request", "shape", "ranking", "filters", "attribute", "selection", "reads", "injected", "hevlayerupsertedat", "predicate", "while", "index", "shot", "retry", "filter", "forced", "race" ] }, { "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": "Explains write in the context of Introduction, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "introduction", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "patch", "rows", "hevlayer", "upserted", "turbopuffer", "upstream", "contract", "upsert", "delete", "patchrows", "best", "effort", "aerospike", "document", "cache", "mirror", "before", "explicit", "writes", "server", "stamped", "hevlayerupsertedat", "every", "powers", "consistency", "watermark", "query", "path" ] }, { "id": "api/keys", "kind": "section", "title": "API keys", "heading": null, "group": "API", "url": "/docs/api/keys", "summary": "Provides an overview of API keys, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "keys", "purpose", "behavior", "users", "should", "expect", "vectorstore", "warehouse", "apikey", "codetabs", "astro", "mint", "verify", "revoke", "rest", "entitlements", "open", "stores", "warehouses", "layer", "itself", "mints", "opens", "declared", "resource", "entitlement", "names", "carries", "scopes", "claims", "target", "page", "covers", "model", "surface", "anything", "default", "credential" ] }, { "id": "api/keys#authenticate", "kind": "section", "title": "API keys", "heading": "Authenticate", "group": "API", "url": "/docs/api/keys#authenticate", "summary": "Explains authenticate in the context of API keys, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "keys", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "identity", "await", "client", "token", "presented", "claims", "entitlements", "warehouse", "prod", "snowflake", "authenticatekey", "hevlayer", "authenticatekeyrequest", "const", "curl", "post", "layer", "gateway", "content", "type", "application", "json", "iqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "keyid", "name", "owner", "expiresat", "external", "systems", "present" ] }, { "id": "api/keys#cli", "kind": "section", "title": "API keys", "heading": "CLI", "group": "API", "url": "/docs/api/keys#cli", "summary": "Explains how to perform the documented API keys lifecycle through the command-line interface.", "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": [ "explains", "perform", "documented", "keys", "lifecycle", "through", "command", "line", "interface", "layer", "mint", "cohort", "reader", "owner", "acme", "entitle", "vectorstore", "prod", "turbopuffer", "read", "namespaces", "claim", "warehouse", "snowflake", "notes", "revoke", "rare", "cleanup", "after", "retention", "period", "same", "operations", "prints", "token", "once", "alone", "stdout", "piping", "metadata" ] }, { "id": "api/keys#key-model", "kind": "section", "title": "API keys", "heading": "Key model", "group": "API", "url": "/docs/api/keys#key-model", "summary": "Explains key model in the context of API keys, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "keys", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "iqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "apikey", "audit", "trail", "revoked", "tokens", "look", "like", "hvliqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "token", "returned", "once", "mint", "response", "layer", "stores", "only", "hashes", "lost", "minted", "never", "recovered", "every", "resource", "cluster", "kubectl", "apikeys", "apply", "equal", "authoring" ] }, { "id": "api/keys#kubectl", "kind": "section", "title": "API keys", "heading": "kubectl", "group": "API", "url": "/docs/api/keys#kubectl", "summary": "Explains how Kubernetes resources provide an alternative authoring surface for API keys.", "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", "explains", "kubernetes", "resources", "provide", "alternative", "authoring", "surface", "keys", "apply", "yaml", "apikeys", "layer", "secret", "apikey", "cohort", "reader", "jsonpath", "data", "token", "base64", "status", "secretref", "other", "credential", "operator", "mints", "named", "both", "surfaces", "round", "trip", "through", "schema", "keyid", "spellings", "same", "object", "page", "full" ] }, { "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": "Explains how to inspect collections and individual records for API keys without exposing secret material.", "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", "explains", "inspect", "collections", "individual", "records", "keys", "without", "exposing", "secret", "material", "await", "client", "0a1b2c3d", "4e5f", "6071", "8293", "a4b5c6d7e8f9", "listkeys", "getkey", "const", "curl", "layer", "gateway", "authorization", "bearer", "lastseenat", "layergatewayurl", "layergatewayapikey", "keyid", "name", "cohort", "reader", "owner", "acme", "entitlements", "vectorstore", "prod", "turbopuffer", "scopes" ] }, { "id": "api/keys#mint", "kind": "section", "title": "API keys", "heading": "Mint", "group": "API", "url": "/docs/api/keys#mint", "summary": "Explains mint in the context of API keys, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "keys", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "const", "await", "client", "mintkey", "name", "cohort", "reader", "owner", "acme", "entitlements", "vectorstore", "prod", "turbopuffer", "scopes", "read", "namespaces", "warehouse", "snowflake", "claims", "notes", "expiresafter", "365d", "console", "token", "shown", "once", "never", "again", "created", "apikey" ] }, { "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": "Explains revoke by default in the context of API keys, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "keys", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "0a1b2c3d", "4e5f", "6071", "8293", "a4b5c6d7e8f9", "revokekey", "curl", "post", "layer", "gateway", "authorization", "bearer", "delete", "includerevoked", "revoked", "active", "pending", "expired", "conflict", "apikey", "layergatewayurl", "keyid", "layergatewayapikey", "stops", "accepting", "within", "seconds" ] }, { "id": "api/keys#routes", "kind": "section", "title": "API keys", "heading": "Routes", "group": "API", "url": "/docs/api/keys#routes", "summary": "Summarizes the available operations for API keys and the behavior of each operation.", "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", "summarizes", "available", "operations", "keys", "behavior", "operation", "includerevoked", "keyid", "revoke", "revoked", "authenticate", "layer", "admin", "route", "method", "auth", "post", "mint", "only", "response", "contains", "token", "list", "metadata", "never", "material", "adds", "expired", "idempotent", "record", "stays", "delete", "hard", "permanently", "remove", "audit", "none", "exchange", "identity" ] }, { "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": "Explains using a minted key in the context of API keys, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "keys", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "curl", "layer", "gateway", "namespaces", "cohort", "query", "post", "authorization", "bearer", "iqgfsdd2pnkyhcqr59jjvkukl47vqxmz", "content", "type", "application", "json", "rank", "text", "bm25", "acme", "error", "namespace", "grant", "orders", "insufficient", "scope", "required", "admin", "vectorstore", "name", "works", "anywhere" ] }, { "id": "api/license", "kind": "section", "title": "License", "heading": null, "group": "API", "url": "/docs/api/license", "summary": "Provides an overview of License, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "license", "purpose", "behavior", "users", "should", "expect", "curl", "layer", "gateway", "authorization", "bearer", "codetabs", "astro", "read", "local", "state", "returns", "projection", "operator", "dashboard", "oracle", "never", "phones", "home", "derives", "configured", "plus", "codified", "grace", "cushion", "layergatewayurl", "layergatewayapikey" ] }, { "id": "api/license#client-call", "kind": "section", "title": "License", "heading": "Client Call", "group": "API", "url": "/docs/api/license#client-call", "summary": "Explains client call in the context of License, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "license", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "state", "await", "print", "gateway", "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": "Explains the fields exposed by License, when they appear, and what they mean.", "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", "explains", "exposed", "license", "appear", "mean", "valid", "state", "reason", "missing", "tier", "trial", "design", "partner", "features", "limits", "gateway", "licensed", "grace", "floor", "seconds", "deadline", "remaining", "field", "present", "meaning", "always", "whether", "currently", "treats", "deployment", "invalid", "level", "marker", "human", "readable", "verifier", "account", "subject", "label" ] }, { "id": "api/license#response", "kind": "section", "title": "License", "heading": "Response", "group": "API", "url": "/docs/api/license#response", "summary": "Describes the response behavior and metadata returned by License.", "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", "describes", "behavior", "metadata", "returned", "license", "valid", "true", "acme", "corp", "tier", "design", "partner", "features", "transform", "runtime", "agents", "rbac", "warehouses", "cache", "history", "cost", "limits", "namespaces", "workers", "2026", "14t00", "gateway", "state", "licensed", "seconds", "deadline", "1209600", "grace", "remaining", "false", "floor", "reason", "missing", "still" ] }, { "id": "api/license#state-effects", "kind": "section", "title": "License", "heading": "State Effects", "group": "API", "url": "/docs/api/license#state-effects", "summary": "Explains state effects in the context of License, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "license", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "licensed", "features", "grace", "hevlayer", "true", "floor", "error", "required", "gateway", "gated", "route", "feature", "routes", "work", "includes", "always", "works", "responses", "include", "return", "licenserequired", "query", "point", "read", "write", "scan", "namespace", "metadata", "snapshot" ] }, { "id": "api/namespace-metadata", "kind": "section", "title": "Namespace metadata", "heading": null, "group": "API", "url": "/docs/api/namespace-metadata", "summary": "Provides an overview of Namespace metadata, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "namespace", "metadata", "purpose", "behavior", "users", "should", "expect", "namespaces", "upstream", "astro", "codetabs", "turbopuffer", "read", "enriched", "layer", "freshness", "signals", "payload", "proxied", "verbatim", "endpoint", "schema", "counts", "index", "status", "timestamps", "follow", "contract", "adds", "single", "object" ] }, { "id": "api/namespace-metadata#list-namespaces", "kind": "section", "title": "Namespace metadata", "heading": "List namespaces", "group": "API", "url": "/docs/api/namespace-metadata#list-namespaces", "summary": "Explains list namespaces in the context of Namespace metadata, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "namespace", "metadata", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "prefix", "prod", "page", "size", "listnamespaces", "hevlayer", "listnamespacesparams", "pagesize", "const", "curl", "layer", "gateway", "authorization", "bearer", "name", "products", "count", "12500", "bytes", "48800000", "stable", "1715600400000", "true", "index", "status", "date" ] }, { "id": "api/namespace-metadata#request", "kind": "section", "title": "Namespace metadata", "heading": "Request", "group": "API", "url": "/docs/api/namespace-metadata#request", "summary": "Describes the inputs accepted by Namespace metadata and the boundaries between request data and configured behavior.", "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", "describes", "inputs", "accepted", "namespace", "metadata", "boundaries", "between", "data", "configured", "behavior", "await", "client", "products", "getnamespacemetadata", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "layergatewayurl", "layergatewayapikey", "proxied", "turbopuffer", "verbatim", "schema", "approxrowcount", "12500", "approxlogicalbytes", "48800000", "createdat", "2026", "15t10", "updatedat", "12t18", "lastwriteat", "index", "status" ] }, { "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": "Explains the layer block in the context of Namespace metadata, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "namespace", "metadata", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "stable", "index", "status", "date", "indexed", "rows", "consistency", "poll", "interval", "true", "false", "field", "meaning", "stableasof", "epoch", "watermark", "most", "recent", "null", "cold", "start", "before", "watcher", "observed", "isstable", "whether", "once", "catches" ] }, { "id": "api/pipelines", "kind": "section", "title": "Pipelines", "heading": null, "group": "API", "url": "/docs/api/pipelines", "summary": "Provides an overview of Pipelines, its purpose, and the behavior users should expect.", "facts": [ { "kind": "value", "literal": "CodeTabs.astro", "chunkId": "api/pipelines" } ], "sources": [ { "chunkId": "api/pipelines", "url": "/docs/api/pipelines", "anchor": null } ], "mode": "source-primary", "terms": [ "provides", "overview", "pipelines", "purpose", "behavior", "users", "should", "expect", "codetabs", "astro", "organize", "stage", "indexing", "pipeline", "extract", "chunk", "embed", "trigger", "runs", "wait", "completion", "keeps", "code", "need", "index", "data", "simple", "organized", "typical", "stages", "extraction", "chunking", "followed", "embedding", "guide", "walks", "through", "best", "practice", "layout" ] }, { "id": "api/pipelines#deploy", "kind": "section", "title": "Pipelines", "heading": "Deploy", "group": "API", "url": "/docs/api/pipelines#deploy", "summary": "Explains deploy in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "kubectl", "apply", "build", "workers", "images", "yaml", "references", "push", "registry", "cluster", "pull", "layer", "does", "resources", "operator", "creates", "deployment", "resource", "embed", "pool", "keda", "object", "order", "doesn", "matter", "here", "gateway", "pipeline", "before", "enqueues" ] }, { "id": "api/pipelines#document-lifecycle", "kind": "section", "title": "Pipelines", "heading": "Document lifecycle", "group": "API", "url": "/docs/api/pipelines#document-lifecycle", "summary": "Explains document lifecycle in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "chunks", "vectors", "pending", "indexed", "stage", "idempotent", "embedding", "stored", "waiting", "written", "namespace", "configured", "vectorstore", "claim", "documents", "only", "while", "leased", "worker", "recover", "lease", "expires", "staging", "resets", "reprocess", "after", "source", "data", "changes" ] }, { "id": "api/pipelines#embed", "kind": "section", "title": "Pipelines", "heading": "Embed", "group": "API", "url": "/docs/api/pipelines#embed", "summary": "Explains embed in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "indexed", "kind", "search", "vectors", "vector", "nearest", "worker", "claims", "pending", "documents", "reads", "their", "chunks", "back", "writes", "writing", "upserts", "namespace", "configured", "vectorstore", "marks", "document", "leased", "crashes", "loses", "nothing", "multivector", "namespaces", "store", "send" ] }, { "id": "api/pipelines#extract-and-chunk", "kind": "section", "title": "Pipelines", "heading": "Extract and chunk", "group": "API", "url": "/docs/api/pipelines#extract-and-chunk", "summary": "Explains extract and chunk in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "pending", "spec", "sourceref", "yaml", "worker", "reads", "source", "splits", "text", "chunks", "stages", "staging", "stores", "durably", "cached", "document", "cache", "marks", "hardcodes", "nothing", "operator", "injects", "pipeline", "gateway", "environment", "variables", "page", "queue", "below" ] }, { "id": "api/pipelines#failure-model", "kind": "section", "title": "Pipelines", "heading": "Failure model", "group": "API", "url": "/docs/api/pipelines#failure-model", "summary": "Explains failure model in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "embedding", "vectorstore", "write", "failures", "hard", "vectors", "route", "returns", "document", "stays", "claim", "aerospike", "cache", "block", "chunk", "reads", "backing", "present", "postgresql", "connectivity", "return", "should", "retried", "backoff", "stop", "writes", "recovery", "path", "metrics" ] }, { "id": "api/pipelines#file-tree", "kind": "section", "title": "Pipelines", "heading": "File tree", "group": "API", "url": "/docs/api/pipelines#file-tree", "summary": "Explains file tree in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "indexer", "extract", "chunk", "yaml", "stage", "pipeline", "resource", "embed", "read", "source", "chunks", "claim", "pending", "docs", "write", "vectors", "rest", "trigger", "wait", "completion", "pipelineid", "products", "extractchunk", "files", "declare", "worker", "images", "pools", "scaling" ] }, { "id": "api/pipelines#trigger-a-run", "kind": "section", "title": "Pipelines", "heading": "Trigger a run", "group": "API", "url": "/docs/api/pipelines#trigger-a-run", "summary": "Explains trigger a run in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "post", "index", "runs", "exposes", "pipeline", "rest", "system", "endpoint", "sends", "batch", "source", "queue", "waits", "complete", "returns", "snapshot", "produced", "created", "first", "target", "namespace", "code", "fastapi", "import", "hevlayer", "asynchevlayer", "hevlayererror", "https", "east", "amazonaws" ] }, { "id": "api/pipelines#wait-for-completion", "kind": "section", "title": "Pipelines", "heading": "Wait for completion", "group": "API", "url": "/docs/api/pipelines#wait-for-completion", "summary": "Explains wait for completion in the context of Pipelines, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "pipelines", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "pending", "count", "status", "waiting", "upstream", "failed", "reasons", "chunks", "unavailable", "complete", "steps", "queue", "drains", "consistency", "watcher", "observes", "namespace", "stable", "writes", "snapshot", "past", "watermark", "pendingcount", "same", "signal", "keda", "scales", "reaches", "zero" ] }, { "id": "api/query", "kind": "section", "title": "Query & Fetch", "heading": null, "group": "API", "url": "/docs/api/query", "summary": "Provides an overview of Query & Fetch, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "query", "fetch", "purpose", "behavior", "users", "should", "expect", "layer", "vector", "rank", "filters", "codetabs", "astro", "storeswitch", "storenote", "upstream", "featuregate", "turbopuffer", "similarity", "search", "stable", "reads", "cached", "document", "reports", "metadata", "response", "headers", "backed", "runs", "namespace", "adding", "cache", "history", "around", "native", "body", "rankby" ] }, { "id": "api/query#batch-fetch", "kind": "section", "title": "Query & Fetch", "heading": "Batch fetch", "group": "API", "url": "/docs/api/query#batch-fetch", "summary": "Explains batch fetch in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "documents", "products", "asin", "include", "attributes", "title", "fetchdocuments", "hevlayer", "fetchdocumentsrequest", "string", "includeattributes", "const", "curl", "post", "layer", "gateway", "namespaces", "authorization", "bearer", "content", "type", "application", "json", "missing", "layergatewayurl", "layergatewayapikey", "returns" ] }, { "id": "api/query#batch-query", "kind": "section", "title": "Query & Fetch", "heading": "Batch query", "group": "API", "url": "/docs/api/query#batch-query", "summary": "Explains batch query in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "namespace", "products", "queries", "rank", "vector", "title", "bm25", "wireless", "earbuds", "results", "rows", "ranked", "text", "batchquerynamespace", "hevlayer", "batchqueryrequest", "turbopufferqueryrequest", "float64", "const", "curl", "post", "layer", "gateway", "namespaces", "authorization", "bearer", "content" ] }, { "id": "api/query#behavior-matrix", "kind": "section", "title": "Query & Fetch", "heading": "Behavior matrix", "group": "API", "url": "/docs/api/query#behavior-matrix", "summary": "Explains behavior matrix in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "relevant", "operational", "constraints", "missing", "miss", "error", "cache", "state", "single", "batch", "upstream", "present", "backfill", "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": "Explains counting matches in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "scans", "approximate", "exhaustive", "count", "many", "rows", "match", "full", "text", "vector", "scan", "mode", "selector", "ranked", "counts", "share", "single", "endpoint", "filter", "exact", "radius", "flagged", "both", "honor", "flag", "deadline" ] }, { "id": "api/query#fetch", "kind": "section", "title": "Query & Fetch", "heading": "Fetch", "group": "API", "url": "/docs/api/query#fetch", "summary": "Explains fetch in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "api/query#fetch", "url": "/docs/api/query#fetch", "anchor": "fetch" } ], "mode": "source-primary", "terms": [ "fetch", "explains", "context", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "only", "endpoint", "upstream", "equivalent", "document", "cache", "checked", "first", "miss", "error", "gateway", "falls", "through", "backing", "store", "backfills", "best", "effort" ] }, { "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": "Explains hybrid text fusion in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "response", "await", "client", "namespace", "support", "tickets", "rank", "content", "hybridtext", "conection", "timout", "kubernets", "filters", "tenant", "include", "attributes", "title", "querynamespace", "hevlayer", "queryrequest", "rankby", "topk", "includeattributes", "string", "const", "curl", "post" ] }, { "id": "api/query#options", "kind": "section", "title": "Query & Fetch", "heading": "Options", "group": "API", "url": "/docs/api/query#options", "summary": "Explains options in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "route", "auto", "hybrid", "text", "semantic", "fused", "vector", "fuzziness", "hybridtext", "routing", "include", "breakdown", "true", "legs", "optional", "fourth", "tuple", "element", "option", "default", "meaning", "force", "instead", "applying", "policy", "issue", "after", "deferral", "comparison" ] }, { "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": "Explains query by id in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "response", "await", "client", "namespace", "products", "nearest", "asin", "b08n5wrwnw", "b07pxgqc1q", "include", "attributes", "title", "category", "querynamespace", "hevlayer", "queryrequest", "nearesttoid", "string", "topk", "includeattributes", "const", "curl", "post", "layer", "gateway", "namespaces", "authorization", "bearer", "content", "type" ] }, { "id": "api/query#query-routing", "kind": "section", "title": "Query & Fetch", "heading": "Query routing", "group": "API", "url": "/docs/api/query#query-routing", "summary": "Explains query routing in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "timout", "auto", "rank", "real", "search", "boxes", "receive", "both", "pods", "lose", "their", "connection", "during", "deploys", "first", "wants", "hybrid", "text", "fusion", "second", "semantic", "retrieval", "lexical", "legs", "noise", "long", "conversational", "input", "underperforms" ] }, { "id": "api/query#rank-expressions", "kind": "section", "title": "Query & Fetch", "heading": "Rank expressions", "group": "API", "url": "/docs/api/query#rank-expressions", "summary": "Explains rank expressions in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vector", "nearest", "pass", "rankby", "topk", "need", "explicit", "ranking", "operator", "instead", "level", "nearesttoid", "shape", "layer", "handles", "portable", "subset", "same", "cache", "history", "stable", "read", "queries", "native", "upstream", "bodies", "omit", "remain" ] }, { "id": "api/query#response", "kind": "section", "title": "Query & Fetch", "heading": "Response", "group": "API", "url": "/docs/api/query#response", "summary": "Describes the response behavior and metadata returned by Query & Fetch.", "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", "describes", "behavior", "metadata", "returned", "query", "fetch", "rows", "ticket", "4117", "score", "0639", "content", "title", "connection", "timeout", "kubernetes", "ingress", "hybrid", "tokens", "conection", "timout", "kubernets", "dropped", "fuzziness", "auto", "rank", "constant", "legs", "limit", "next", "cursor", "null", "fused", "include", "breakdown", "true", "surfaced", "layer", "hybridtext" ] }, { "id": "api/query#response-1", "kind": "section", "title": "Query & Fetch", "heading": "Response", "group": "API", "url": "/docs/api/query#response-1", "summary": "Describes the response behavior and metadata returned by Query & Fetch.", "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", "describes", "behavior", "metadata", "returned", "query", "fetch", "rows", "ticket", "4117", "score", "0639", "title", "routing", "route", "hybrid", "text", "policy", "tokens", "executed", "true", "timout", "dropped", "fuzziness", "auto", "rank", "constant", "legs", "limit", "forced", "false", "every", "carries", "block", "hybridtext", "tokensdropped", "rankconstant", "perleglimit", "field", "meaning" ] }, { "id": "api/query#routing-policy", "kind": "section", "title": "Query & Fetch", "heading": "Routing policy", "group": "API", "url": "/docs/api/query#routing-policy", "summary": "Explains routing policy in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hybrid", "text", "semantic", "fused", "vector", "reads", "token", "count", "input", "under", "same", "tokenizer", "fusion", "tokens", "route", "runs", "hybridtext", "expansion", "supplied", "both", "merged", "upstream", "availability", "never", "changes", "chosen", "only", "whether" ] }, { "id": "api/query#semantics", "kind": "section", "title": "Query & Fetch", "heading": "Semantics", "group": "API", "url": "/docs/api/query#semantics", "summary": "Explains semantics in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "include", "breakdown", "true", "filters", "layer", "stable", "hybridtext", "fusion", "uses", "effective", "order", "bm25", "first", "fuzzy", "token", "semantic", "routed", "fused", "queries", "includelegbreakdown", "require", "upstream", "unsharded", "namespaces", "report", "ranks", "consistency", "request", "level" ] }, { "id": "api/query#single-fetch", "kind": "section", "title": "Query & Fetch", "heading": "Single fetch", "group": "API", "url": "/docs/api/query#single-fetch", "summary": "Explains single fetch in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "document", "products", "asin", "b08n5wrwnw", "include", "attributes", "title", "category", "fetchdocument", "hevlayer", "fetchdocumentparams", "includeattributes", "string", "const", "curl", "layer", "gateway", "namespaces", "documents", "authorization", "bearer", "cache", "miss", "error", "layergatewayurl", "layergatewayapikey", "outcome" ] }, { "id": "api/query#stable-reads", "kind": "section", "title": "Query & Fetch", "heading": "Stable reads", "group": "API", "url": "/docs/api/query#stable-reads", "summary": "Explains stable reads in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "http", "layer", "1715600400000", "rows", "asin", "b08n5wrwnw", "dist", "title", "consistency", "eventual", "index", "status", "poll", "start", "safety", "margin", "updating", "hevlayer", "upserted", "watermark", "unknown", "next", "cursor", "null", "hybridtext", "auto", "between", "1747300000123" ] }, { "id": "api/query#surfacing-fallback", "kind": "section", "title": "Query & Fetch", "heading": "Surfacing fallback", "group": "API", "url": "/docs/api/query#surfacing-fallback", "summary": "Explains surfacing fallback in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "surfaced", "true", "hybrid", "legs", "every", "primary", "ranks", "bm25", "full", "input", "upstream", "scores", "zero", "drops", "token", "matches", "stored", "term", "exactly", "fully", "misspelled", "therefore", "fuses", "rows", "expansion", "returns", "nothing", "layer" ] }, { "id": "api/query#tokenization", "kind": "section", "title": "Query & Fetch", "heading": "Tokenization", "group": "API", "url": "/docs/api/query#tokenization", "summary": "Explains tokenization in the context of Query & Fetch, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "fetch", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "alyze", "word", "tokens", "dropped", "input", "string", "becomes", "under", "fixed", "documented", "policy", "split", "unicode", "boundaries", "lowercase", "code", "behind", "turbopuffer", "production", "wordv4", "tokenizer", "punctuation", "only", "never", "survive", "drop", "shorter", "characters", "dedupe" ] }, { "id": "api/query#validation", "kind": "section", "title": "Query & Fetch", "heading": "Validation", "group": "API", "url": "/docs/api/query#validation", "summary": "Summarizes invalid conditions, authorization failures, and runtime errors for Query & Fetch, including how callers can distinguish them.", "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", "summarizes", "invalid", "conditions", "authorization", "failures", "runtime", "errors", "query", "fetch", "including", "callers", "distinguish", "hybridtext", "queries", "fuzziness", "auto", "rank", "constant", "limit", "threads", "return", "condition", "input", "yields", "zero", "tokens", "under", "policy", "nothing", "expand", "inside", "array", "expansion", "already", "batch", "deep", "construction", "rankconstant", "perleglimit" ] }, { "id": "api/query#validation-1", "kind": "section", "title": "Query & Fetch", "heading": "Validation", "group": "API", "url": "/docs/api/query#validation-1", "summary": "Summarizes invalid conditions, authorization failures, and runtime errors for Query & Fetch, including how callers can distinguish them.", "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", "summarizes", "invalid", "conditions", "authorization", "failures", "runtime", "errors", "query", "fetch", "including", "callers", "distinguish", "semantic", "fused", "vector", "auto", "queries", "return", "condition", "forced", "without", "forcing", "asserts", "only", "routing", "defers", "input", "yields", "zero", "tokens", "under", "policy", "nothing", "route", "dimensionality", "mismatch", "same", "check", "plain" ] }, { "id": "api/response-headers", "kind": "section", "title": "Response Headers", "heading": null, "group": "API", "url": "/docs/api/response-headers", "summary": "Provides an overview of Response Headers, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "response", "headers", "purpose", "behavior", "users", "should", "expect", "layer", "stable", "next", "cursor", "cache", "miss", "error", "warning", "vector", "attribute", "dropped", "hevlayer", "license", "grace", "true", "traceparent", "query", "namespace", "rows", "metadata", "returned", "alongside", "wire", "compatible", "bodies", "keeps", "turbopuffer", "read", "upstream", "shape", "returns" ] }, { "id": "api/scans", "kind": "section", "title": "Scan", "heading": null, "group": "API", "url": "/docs/api/scans", "summary": "Provides an overview of Scan, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "scan", "purpose", "behavior", "users", "should", "expect", "mode", "count", "values", "filters", "hybrid", "text", "radius", "threads", "index", "spec", "post", "namespaces", "init", "layer", "shard", "rows", "hevlayer", "codetabs", "astro", "demand", "selection", "filter", "full", "namespace", "picks", "four", "selectors", "returns", "their", "asynchronous", "synchronous", "distinct" ] }, { "id": "api/scans#auto-mode-policy", "kind": "section", "title": "Scan", "heading": "Auto-Mode Policy", "group": "API", "url": "/docs/api/scans#auto-mode-policy", "summary": "Explains auto-mode policy in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "cache", "warmed", "through", "watermark", "hevlayer", "upserted", "ties", "freshness", "same", "consistency", "stable", "reads", "gateway", "tracks", "namespace", "cachewarmedthrough", "observed", "last", "successful", "origin", "warm", "state", "action", "empty", "stamp", "populated", "serve", "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": "Explains bounding ranked scans in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "threads", "exhaustive", "timeout", "seconds", "false", "bounded", "true", "shards", "saturated", "score", "last", "dist", "radius", "approximate", "selectors", "turbopuffer", "query", "shard", "capped", "topk", "10000", "bounds", "width", "many", "requests", "once", "timeoutseconds", "bound" ] }, { "id": "api/scans#count-mode", "kind": "section", "title": "Scan", "heading": "Count Mode", "group": "API", "url": "/docs/api/scans#count-mode", "summary": "Explains count mode in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "source", "auto", "filters", "category", "electronics", "threads", "timeout", "seconds", "createscan", "hevlayer", "createscanrequest", "interface", "timeoutseconds", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization", "bearer", "content", "type", "application" ] }, { "id": "api/scans#fan-out-width", "kind": "section", "title": "Scan", "heading": "Fan-out width", "group": "API", "url": "/docs/api/scans#fan-out-width", "summary": "Explains fan-out width in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "threads", "spec", "index", "origin", "scans", "upstream", "request", "active", "shard", "sets", "maximum", "number", "those", "requests", "single", "flight", "once", "means", "concurrent", "operating", "system", "gateway", "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": "Explains filters in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "noteq", "notin", "auto", "source", "cache", "scans", "accept", "same", "turbopuffer", "filter", "array", "query", "origin", "pushed", "gateway", "evaluates", "against", "cached", "document", "attributes", "supported", "operators", "sees", "cannot", "evaluate", "uses", "explicit", "unsupported", "fails", "rather" ] }, { "id": "api/scans#full-text-count", "kind": "section", "title": "Scan", "heading": "Full-text count", "group": "API", "url": "/docs/api/scans#full-text-count", "summary": "Explains full-text count in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "mode", "field", "title", "query", "wireless", "headphones", "filters", "category", "electronics", "exhaustive", "true", "createscan", "hevlayer", "createscanrequest", "ftsscan", "interface", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization" ] }, { "id": "api/scans#high-cardinality", "kind": "section", "title": "Scan", "heading": "High cardinality", "group": "API", "url": "/docs/api/scans#high-cardinality", "summary": "Explains high cardinality in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "truncated", "true", "bounded", "approximate", "snapshot", "facet", "histograms", "field", "distinct", "values", "skip", "fields", "beyond", "scans", "enumeration", "path", "exactly", "those", "accumulates", "histogram", "gateway", "memory", "caps", "listing", "crosses", "completes", "rather", "failing", "applies" ] }, { "id": "api/scans#hybrid-text-count", "kind": "section", "title": "Scan", "heading": "Hybrid text count", "group": "API", "url": "/docs/api/scans#hybrid-text-count", "summary": "Explains hybrid text count in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "mode", "field", "title", "query", "wireles", "headphones", "filters", "category", "electronics", "createscan", "hevlayer", "createscanrequest", "hybridtext", "hybridtextscan", "interface", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization", "bearer" ] }, { "id": "api/scans#id-mode", "kind": "section", "title": "Scan", "heading": "ID Mode", "group": "API", "url": "/docs/api/scans#id-mode", "summary": "Explains id mode in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "source", "auto", "filters", "category", "electronics", "threads", "page", "size", "1000", "createscan", "hevlayer", "createscanrequest", "interface", "pagesize", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization", "bearer", "content", "type", "application" ] }, { "id": "api/scans#operational-notes", "kind": "section", "title": "Scan", "heading": "Operational notes", "group": "API", "url": "/docs/api/scans#operational-notes", "summary": "Collects operational limits, persistence characteristics, and failure considerations for Scan.", "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", "collects", "limits", "persistence", "characteristics", "failure", "considerations", "scan", "truncated", "true", "index", "spec", "threads", "watermark", "values", "state", "memory", "ephemeral", "resets", "gateway", "restart", "count", "scans", "deadline", "default", "maximum", "300s", "jobs", "distinct", "crossed", "listing", "keeps", "exact", "origin", "defaults", "concurrent", "upstream", "requests", "unless" ] }, { "id": "api/scans#precomputed-serving", "kind": "section", "title": "Scan", "heading": "Precomputed serving", "group": "API", "url": "/docs/api/scans#precomputed-serving", "summary": "Explains precomputed serving in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "filters", "fields", "status", "completed", "effective", "source", "snapshot", "watermark", "skipped", "auto", "precondition", "failed", "unfiltered", "values", "ranked", "selector", "field", "present", "latest", "answered", "straight", "facet", "histogram", "completes", "during", "create", "call", "body", "already" ] }, { "id": "api/scans#radius-count", "kind": "section", "title": "Scan", "heading": "Radius count", "group": "API", "url": "/docs/api/scans#radius-count", "summary": "Explains radius count in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "mode", "field", "vector", "createscan", "hevlayer", "createscanrequest", "annscan", "float64", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization", "bearer", "content", "type", "application", "json", "served", "origin", "approximate", "true" ] }, { "id": "api/scans#routes", "kind": "section", "title": "Scan", "heading": "Routes", "group": "API", "url": "/docs/api/scans#routes", "summary": "Summarizes the available operations for Scan and the behavior of each operation.", "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", "summarizes", "available", "operations", "scan", "behavior", "operation", "post", "namespaces", "scans", "results", "delete", "route", "method", "create", "values", "return", "count", "list", "jobs", "namespace", "read", "completed", "drop", "memory" ] }, { "id": "api/scans#sources", "kind": "section", "title": "Scan", "heading": "Sources", "group": "API", "url": "/docs/api/scans#sources", "summary": "Explains sources in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "auto", "snapshot", "fields", "cache", "origin", "hybrid", "text", "source", "mode", "count", "values", "fresh", "enough", "otherwise", "first", "eligible", "supported", "latest", "only", "requires", "facet", "listing", "unfiltered", "field", "aerospike", "document", "turbopuffer", "paginated", "gateway", "side" ] }, { "id": "api/scans#values-mode", "kind": "section", "title": "Scan", "heading": "Values Mode", "group": "API", "url": "/docs/api/scans#values-mode", "summary": "Explains values mode in the context of Scan, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "scan", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "field", "category", "source", "auto", "filters", "stock", "true", "createscan", "hevlayer", "createscanrequest", "interface", "const", "curl", "post", "layer", "gateway", "namespaces", "scans", "authorization", "bearer", "content", "type", "application", "json", "uuid" ] }, { "id": "api/search-history", "kind": "section", "title": "Query History", "heading": null, "group": "API", "url": "/docs/api/search-history", "summary": "Provides an overview of Query History, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "query", "history", "purpose", "behavior", "users", "should", "expect", "codetabs", "astro", "namespace", "clickstream", "backed", "jsonl", "layer", "logs", "every", "gateway", "serves", "durable", "trail", "mirrored", "cache", "fast", "recent", "reads", "fetch", "events", "downstream", "consumers", "back", "land", "sibling", "feed", "together", "make", "search", "session", "reconstructable" ] }, { "id": "api/search-history#clickstream-entry", "kind": "section", "title": "Query History", "heading": "Clickstream entry", "group": "API", "url": "/docs/api/search-history#clickstream-entry", "summary": "Explains clickstream entry in the context of Query History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "events", "timestamp", "2026", "22t08", "143z", "nanos", "1747900802143000000", "trace", "f81d4fae", "7dec", "11d0", "a765", "00a0c91e6bf6", "namespace", "products", "asin", "b08n5wrwnw", "tags", "session", "abc123", "source", "fetch", "served", "cache", "next", "cursor", "1747900802142000000", "await" ] }, { "id": "api/search-history#query-parameters", "kind": "section", "title": "Query History", "heading": "Query parameters", "group": "API", "url": "/docs/api/search-history#query-parameters", "summary": "Explains query parameters in the context of Query History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "before", "timestamp", "nanos", "limit", "param", "purpose", "comma", "separated", "filter", "semantics", "every", "must", "match", "rfc3339", "time", "bounds", "pagination", "cursor", "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": "Summarizes the available operations for Query History and the behavior of each operation.", "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", "summarizes", "available", "operations", "query", "history", "behavior", "operation", "namespaces", "search", "clickstream", "route", "namespace", "newest", "first", "fetch", "events", "correlated", "versions", "both", "identical", "aliases", "held", "client", "compatibility" ] }, { "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": "Explains search history entry in the context of Query History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "timestamp", "nanos", "trace", "hevlayer", "stable", "result", "tags", "hybridtext", "entries", "2026", "22t08", "000z", "timestampnanos", "1747900800000000000", "namespace", "products", "traceid", "f81d4fae", "7dec", "11d0", "a765", "00a0c91e6bf6", "rawquery", "wireless", "headphones", "stableasof", "1747900700000", "vector" ] }, { "id": "api/search-history#storage", "kind": "section", "title": "Query History", "heading": "Storage", "group": "API", "url": "/docs/api/search-history#storage", "summary": "Explains how Query History data is stored, cached, retained, and recovered when a cache is unavailable.", "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", "explains", "query", "history", "data", "stored", "cached", "retained", "recovered", "cache", "unavailable", "search", "namespace", "yyyy", "timestamp", "nanos", "jsonl", "timestampnanos", "writes", "best", "effort", "never", "block", "response", "aerospike", "holds", "recent", "window", "fast", "reads", "durable", "store", "outage", "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": "Explains tag contract in the context of Query History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "tags", "layer", "splits", "commas", "trims", "whitespace", "drops", "empty", "values", "sorts", "dedupes", "before", "storing", "matching", "separators", "cannot", "escaped", "limits", "limit", "value", "unique", "request", "filter", "length", "bytes", "allowed", "characters", "ascii" ] }, { "id": "api/search-history#writing-metadata", "kind": "section", "title": "Query History", "heading": "Writing metadata", "group": "API", "url": "/docs/api/search-history#writing-metadata", "summary": "Explains writing metadata in the context of Query History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "query", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "namespace", "products", "vector", "embedding", "include", "attributes", "title", "wireless", "headphones", "tags", "shop", "surface", "storefront", "route", "search", "page", "first", "list", "limit", "const", "querynamespace", "searchquery", "listsearchhistory", "hevlayer", "withsearchquery", "withsearchtags" ] }, { "id": "api/snapshots", "kind": "section", "title": "Snapshot History", "heading": null, "group": "API", "url": "/docs/api/snapshots", "summary": "Provides an overview of Snapshot History, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "snapshot", "history", "purpose", "behavior", "users", "should", "expect", "values", "post", "snapshots", "codetabs", "astro", "facet", "jobs", "bodies", "activity", "streams", "materialized", "histograms", "namespace", "carry", "listings", "counts", "stored", "durably", "mirrored", "aerospike", "latest", "body", "materialize", "field", "routes", "read", "durable", "chronology", "written", "consistency", "watcher" ] }, { "id": "api/snapshots#activity", "kind": "section", "title": "Snapshot History", "heading": "Activity", "group": "API", "url": "/docs/api/snapshots#activity", "summary": "Explains activity in the context of Snapshot History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "snapshot", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "list", "since", "1747200000000", "limit", "listsnapshotactivity", "hevlayer", "listsnapshotactivityparams", "const", "curl", "layer", "gateway", "snapshots", "authorization", "bearer", "namespace", "cursor", "next", "layergatewayurl", "layergatewayapikey", "query", "param", "required", "purpose", "epoch", "lower", "bound", "tsms" ] }, { "id": "api/snapshots#history", "kind": "section", "title": "Snapshot History", "heading": "History", "group": "API", "url": "/docs/api/snapshots#history", "summary": "Explains history in the context of Snapshot History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "snapshot", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "list", "namespace", "products", "limit", "listnamespacehistory", "hevlayer", "listnamespacehistoryparams", "const", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "watermark", "1747300000123", "3f9e8b21", "tags", "migration", "1747299600045", "a1c5b09f", "before", "layergatewayurl", "layergatewayapikey", "watermarkms", "query", "param", "default" ] }, { "id": "api/snapshots#manual-snapshot", "kind": "section", "title": "Snapshot History", "heading": "Manual snapshot", "group": "API", "url": "/docs/api/snapshots#manual-snapshot", "summary": "Explains manual snapshot in the context of Snapshot History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "create", "products", "field", "category", "source", "auto", "filters", "brand", "acme", "page", "size", "1000", "createsnapshot", "hevlayer", "createsnapshotrequest", "interface", "pagesize", "const", "curl", "post", "layer", "gateway", "namespaces", "snapshots", "authorization", "bearer", "content" ] }, { "id": "api/snapshots#routes", "kind": "section", "title": "Snapshot History", "heading": "Routes", "group": "API", "url": "/docs/api/snapshots#routes", "summary": "Summarizes the available operations for Snapshot History and the behavior of each operation.", "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", "summarizes", "available", "operations", "snapshot", "history", "behavior", "operation", "post", "namespaces", "snapshots", "policy", "facetfields", "interval", "retention", "index", "spec", "jobs", "activity", "route", "method", "create", "demand", "field", "read", "managed", "shape", "list", "memory", "newest", "first", "durable", "full", "body", "char", "prefix", "cross", "namespace", "write", "stream" ] }, { "id": "api/snapshots#snapshot-body", "kind": "section", "title": "Snapshot History", "heading": "Snapshot body", "group": "API", "url": "/docs/api/snapshots#snapshot-body", "summary": "Explains snapshot body in the context of Snapshot History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "namespace", "products", "3f9e8b2", "getnamespacesnapshot", "const", "curl", "layer", "gateway", "namespaces", "snapshots", "authorization", "bearer", "fields", "values", "count", "indexed", "index", "rows", "skipped", "layergatewayurl", "layergatewayapikey", "watermarkms", "1747300000123", "3f9e8b21", "rowcount", "12500", "name" ] }, { "id": "api/snapshots#snapshot-policy", "kind": "section", "title": "Snapshot History", "heading": "Snapshot policy", "group": "API", "url": "/docs/api/snapshots#snapshot-policy", "summary": "Explains snapshot policy in the context of Snapshot History, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "history", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "apiversion", "hevlayer", "kind", "index", "metadata", "name", "products", "spec", "backend", "namespace", "interval", "retention", "facetfields", "category", "brand", "curl", "layer", "gateway", "namespaces", "authorization", "bearer", "content", "type", "application", "json", "never", "post", "snapshots", "source" ] }, { "id": "api/warm-cache", "kind": "section", "title": "Warm cache", "heading": null, "group": "API", "url": "/docs/api/warm-cache", "summary": "Provides an overview of Warm cache, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "warm", "cache", "purpose", "behavior", "users", "should", "expect", "hint", "namespaces", "upstream", "astro", "callout", "codetabs", "turbopuffer", "namespace", "document", "snapshot", "mirror", "layer", "exposes", "endpoints", "hintcachewarm", "compatible", "only", "shortcut", "creates", "gateway", "matches", "call", "advises", "index", "load", "additionally", "runs", "steps", "side" ] }, { "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": "Explains cache-cold behavior in the context of Warm cache, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "warm", "focusing", "expected", "relevant", "operational", "constraints", "layer", "miss", "error", "hint", "documents", "snapshots", "jobs", "scans", "snapshot", "pipeline", "chunk", "reads", "return", "cachecold", "document", "unavailable", "fetch", "many", "fall", "through", "turbopuffer", "instead", "split", "deliberate", "correctness", "first", "outage", "must", "turn" ] }, { "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": "Explains hint-cache warm in the context of Warm cache, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "curl", "layer", "gateway", "namespaces", "products", "authorization", "bearer", "result", "await", "client", "turbopuffer", "false", "documents", "snapshots", "true", "const", "hintcachewarm", "namespace", "enabled", "status", "completed", "started", "uuid", "running", "watermark", "1715600400000", "page", "size", "jobs" ] }, { "id": "api/warm-cache#layer-warm", "kind": "section", "title": "Warm cache", "heading": "Layer warm", "group": "API", "url": "/docs/api/warm-cache#layer-warm", "summary": "Explains layer warm in the context of Warm cache, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "cache", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "products", "page", "size", "1000", "warmcache", "hevlayer", "warmcacheparams", "pagesize", "const", "curl", "post", "gateway", "namespaces", "authorization", "bearer", "uuid", "namespace", "status", "running", "progress", "documents", "scanned", "created", "2026", "26t10", "getwarmjob", "jobid" ] }, { "id": "api/write", "kind": "section", "title": "Write & Stage", "heading": null, "group": "API", "url": "/docs/api/write", "summary": "Provides an overview of Write & Stage, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "write", "stage", "purpose", "behavior", "users", "should", "expect", "post", "namespaces", "namespace", "hevlayer", "upserted", "storeswitch", "astro", "storenote", "upstream", "featuregate", "codetabs", "turbopuffer", "rows", "documents", "cache", "layer", "native", "body", "upserts", "deletes", "patches", "filter", "writes", "combined", "request", "sent", "writenamespace", "backed", "wire", "compatible", "endpoint" ] }, { "id": "api/write#stage", "kind": "section", "title": "Write & Stage", "heading": "Stage", "group": "API", "url": "/docs/api/write#stage", "summary": "Explains stage in the context of Write & Stage, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "write", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "await", "client", "pipeline", "document", "chunks", "product", "images", "asin", "b08n5wrwnw", "text", "wireless", "noise", "cancelling", "headphones", "hour", "battery", "life", "metadata", "page", "putpipelinedocumentchunks", "hevlayer", "putchunksrequest", "chunk", "string", "interface", "curl", "layer", "gateway", "pipelines", "documents" ] }, { "id": "api/write#status", "kind": "section", "title": "Write & Stage", "heading": "Status", "group": "API", "url": "/docs/api/write#status", "summary": "Explains status in the context of Write & Stage, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "write", "stage", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "error", "validation", "unsupportedbystore", "upstream", "upsert", "condition", "patch", "delete", "layer", "validates", "body", "before", "forwarding", "fail", "independently", "backing", "store", "path", "carries", "statuses", "plain", "proxy", "wouldn", "applied", "stamped", "unprocessable", "entity", "rejected" ] }, { "id": "cli", "kind": "section", "title": "Layer CLI", "heading": null, "group": "Operations", "url": "/docs/cli", "summary": "Provides an overview of Layer CLI, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "layer", "purpose", "behavior", "users", "should", "expect", "kube", "context", "namespace", "manages", "environments", "initializes", "sharding", "observes", "data", "supply", "resources", "indexes", "pipelines", "udfs", "mints", "keys", "runs", "function", "manifests", "operates", "hevlayer", "terminal", "named", "adopted", "namespaces", "index", "pipeline", "state", "gateway", "revokes", "shows", "vectorstore" ] }, { "id": "cli#ask-the-docs", "kind": "section", "title": "Layer CLI", "heading": "Ask The Docs", "group": "Operations", "url": "/docs/cli#ask-the-docs", "summary": "Explains ask the docs in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "tree", "grep", "warm", "cache", "query", "glossary", "watermark", "json", "endpoint", "https", "hevlayer", "site", "hevmind", "path", "queries", "committed", "digest", "keyless", "local", "default", "checkout", "finds", "prefers", "sibling", "source", "falls", "back", "installed", "package", "binary" ] }, { "id": "cli#configuration", "kind": "section", "title": "Layer CLI", "heading": "Configuration", "group": "Operations", "url": "/docs/cli#configuration", "summary": "Explains which settings control Layer CLI and where those settings are defined.", "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", "explains", "settings", "control", "layer", "those", "defined", "active", "partner", "envs", "base", "https", "east", "hevlayer", "kube", "context", "cluster", "namespace", "local", "http", "localhost", "8080", "kind", "config", "toml", "0700", "0600", "output", "table", "json", "names", "reads", "named", "environments", "directory", "created", "mode", "file", "written", "baseurl" ] }, { "id": "cli#delete-an-index", "kind": "section", "title": "Layer CLI", "heading": "Delete An Index", "group": "Operations", "url": "/docs/cli#delete-an-index", "summary": "Explains delete an index in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "shop", "products", "staging", "prefix", "purges", "upstream", "turbopuffer", "namespace", "document", "cache", "rows", "snapshot", "mirrors", "snapshots", "search", "history", "clickstream", "shard", "metadata", "memory", "state", "operator", "discovered", "enabled", "pass", "more", "names", "every", "whose" ] }, { "id": "cli#environments", "kind": "section", "title": "Layer CLI", "heading": "Environments", "group": "Operations", "url": "/docs/cli#environments", "summary": "Explains environments in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "partner", "base", "https", "east", "hevlayer", "kube", "cluster", "namespace", "show", "json", "layerapikey", "prompts", "missing", "values", "required", "must", "supplied", "flags", "keys", "masked" ] }, { "id": "cli#initialize-a-namespace", "kind": "section", "title": "Layer CLI", "heading": "Initialize a Namespace", "group": "Operations", "url": "/docs/cli#initialize-a-namespace", "summary": "Explains initialize a namespace in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "init", "products", "shards", "watch", "false", "poll", "interval", "post", "namespaces", "shard", "rows", "calls", "through", "selected", "gateway", "environment", "command", "creates", "reattaches", "marker", "starts", "backfill", "watches", "default", "until", "shardlagrows", "reaches", "scatter", "gather" ] }, { "id": "cli#inspect-an-index", "kind": "section", "title": "Layer CLI", "heading": "Inspect An Index", "group": "Operations", "url": "/docs/cli#inspect-an-index", "summary": "Explains inspect an index in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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": "index list", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "shop", "products", "json", "list", "reports", "count", "size", "schema", "summary", "last", "write", "stable", "watermark", "cache", "state", "gateway", "recent", "snapshots", "table", "snapshot", "column", "additionally", "need", "history", "served", "only", "managed", "timestamps", "sizes" ] }, { "id": "cli#install", "kind": "section", "title": "Layer CLI", "heading": "Install", "group": "Operations", "url": "/docs/cli#install", "summary": "Explains how to install the components needed to use Layer CLI.", "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", "explains", "components", "needed", "layer", "build", "apps", "repository", "root" ] }, { "id": "cli#install-an-aws-environment", "kind": "section", "title": "Layer CLI", "heading": "Install An AWS Environment", "group": "Operations", "url": "/docs/cli#install-an-aws-environment", "summary": "Explains install an aws environment in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "git clone https://github.com/hev/layer\ncd layer\ngo build -o layer ./apps/layer-cli\n./layer install aws", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "layer install aws", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "scripts/install-layer.sh", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "hev/layer", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "us-east-1", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "i4i.large", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--profile", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "AWS_PROFILE", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--region", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "AWS_REGION", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--cluster-name", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "layer", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--namespace", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--node-type", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--turbopuffer-api-key", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "TURBOPUFFER_API_KEY", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--version", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "latest", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--license-token", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "LICENSE_TOKEN", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--source", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "LAYER_SRC", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--skip-terraform", "chunkId": "cli#install-an-aws-environment" }, { "kind": "code", "literal": "--yes", "chunkId": "cli#install-an-aws-environment" } ], "sources": [ { "chunkId": "cli#install-an-aws-environment", "url": "/docs/cli#install-an-aws-environment", "anchor": "install-an-aws-environment" } ], "mode": "agent-primary", "terms": [ "install", "environment", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "clone", "https", "github", "build", "apps", "scripts", "east", "large", "profile", "region", "cluster", "name", "namespace", "node", "type", "turbopuffer", "version", "latest", "license", "token", "source", "skip", "terraform", "guided", "wizard", "collects", "base", "instance", "runs" ] }, { "id": "cli#keys", "kind": "section", "title": "Layer CLI", "heading": "Keys", "group": "Operations", "url": "/docs/cli#keys", "summary": "Explains keys in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "mint", "cohort", "reader", "owner", "acme", "entitle", "vectorstore", "prod", "turbopuffer", "read", "namespaces", "claim", "warehouse", "snowflake", "notes", "revoke", "pbcopy", "revoked", "target", "scope", "name", "string", "expires", "after", "never", "365d", "admin", "yaml", "apikey", "kubectl" ] }, { "id": "cli#manage-snapshots", "kind": "section", "title": "Layer CLI", "heading": "Manage Snapshots", "group": "Operations", "url": "/docs/cli#manage-snapshots", "summary": "Explains manage snapshots in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "index", "snapshot", "shop", "products", "field", "category", "policy", "facet", "brand", "interval", "retention", "facetfields", "spec", "creates", "demand", "waits", "complete", "writes", "same", "shape", "shared", "gateway", "namespaces", "enable", "automatic", "writer", "without", "applying", "kubernetes" ] }, { "id": "cli#pipelines", "kind": "section", "title": "Layer CLI", "heading": "Pipelines", "group": "Operations", "url": "/docs/cli#pipelines", "summary": "Explains pipelines in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "pipeline", "list", "product", "images", "pending", "processing", "failed", "rate", "push", "reads", "registered", "fans", "status", "live", "queue", "depth", "adds", "target", "namespace", "distance", "metric", "created", "worker", "staged", "renders", "without", "counts", "rather", "erroring", "need" ] }, { "id": "cli#run-a-function", "kind": "section", "title": "Layer CLI", "heading": "Run A Function", "group": "Operations", "url": "/docs/cli#run-a-function", "summary": "Explains run a function in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "products", "yaml", "index", "amazon", "staging", "detach", "list", "product", "tags", "watch", "spec", "targetnamespaces", "kube", "namespace", "apply", "version", "pending", "count", "processing", "input", "kubernetes", "manifest", "overrides", "target", "selects", "kubeconfig", "skips", "step", "workers", "managed" ] }, { "id": "cli#tui", "kind": "section", "title": "Layer CLI", "heading": "TUI", "group": "Operations", "url": "/docs/cli#tui", "summary": "Explains tui in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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": [ "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "browse", "enter", "list", "watch", "index", "name", "pipeline", "keys", "bare", "opens", "read", "only", "operations", "explicit", "spelling", "prints", "usage", "exits", "press", "switch", "between", "indexes", "functions", "pipelines", "environments", "view", "open", "detail", "back", "every", "interactive" ] }, { "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": "Explains vector store and warehouse in the context of Layer CLI, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "layer", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "list", "prod", "turbopuffer", "json", "snowflake", "spec", "orgid", "name", "shows", "declared", "stores", "kind", "default", "marker", "region", "reachability", "prints", "endpoint", "credential", "secret", "reference", "inbound", "auth", "mode", "observed", "generation", "dashboard" ] }, { "id": "concepts", "kind": "section", "title": "Concepts", "heading": null, "group": "Overview", "url": "/docs/concepts", "summary": "Provides an overview of Concepts, its purpose, and the behavior users should expect.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "concepts" } ], "sources": [ { "chunkId": "concepts", "url": "/docs/concepts", "anchor": null } ], "mode": "agent-primary", "terms": [ "provides", "overview", "concepts", "purpose", "behavior", "users", "should", "expect", "callout", "astro", "gateway", "composes", "turbopuffer", "document", "cache", "postgresql", "metrics", "core", "nouns", "work" ] }, { "id": "concepts#control-loops", "kind": "section", "title": "Concepts", "heading": "Control loops", "group": "Overview", "url": "/docs/concepts#control-loops", "summary": "Explains control loops in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "concepts#control-loops", "url": "/docs/concepts#control-loops", "anchor": "control-loops" } ], "mode": "agent-primary", "terms": [ "control", "loops", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "uses", "loop", "core", "primitive", "managing", "indexes", "reconciles", "index", "state", "against", "metrics", "emitted", "search", "system", "applies", "level", "transformations", "udfs", "keeps", "stable", "view", "current", "related", "snapshots", "watermark" ] }, { "id": "concepts#document-cache", "kind": "section", "title": "Concepts", "heading": "Document cache", "group": "Overview", "url": "/docs/concepts#document-cache", "summary": "Explains document cache in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "concepts#document-cache", "url": "/docs/concepts#document-cache", "anchor": "document-cache" } ], "mode": "agent-primary", "terms": [ "document", "cache", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "does", "jobs", "reads", "served", "pull", "through", "gateway", "checks", "first", "miss", "turbopuffer", "snapshots", "returns", "backfills", "best", "effort", "pipeline", "chunk", "handoff", "uses", "same", "store", "queue", "between", "workers", "neither", "makes", "hard" ] }, { "id": "concepts#gateway-enhancements", "kind": "section", "title": "Concepts", "heading": "Gateway enhancements", "group": "Overview", "url": "/docs/concepts#gateway-enhancements", "summary": "Explains gateway enhancements in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "helpful", "extends", "search", "system", "common", "query", "patterns", "filtering", "primitives", "layer", "reserved", "attributes", "changing", "schema", "those", "breaks", "guarantees", "should", "degrade", "gracefully", "functionality", "exposed", "through", "surface", "python", "typescript", "client", "plain" ] }, { "id": "concepts#glossary", "kind": "section", "title": "Concepts", "heading": "Glossary", "group": "Overview", "url": "/docs/concepts#glossary", "summary": "Explains glossary in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "namespaces", "namespace", "count", "indexed", "index", "rows", "fields", "values", "hevlayer", "shard", "rerank", "hybridtext", "alyze", "word", "auto", "hybrid", "text", "semantic", "fused", "routing", "executed", "false", "concept", "current", "meaning", "turbopuffer", "addressed", "through", "document", "plus" ] }, { "id": "concepts#kubernetes-autoscaling", "kind": "section", "title": "Concepts", "heading": "Kubernetes autoscaling", "group": "Overview", "url": "/docs/concepts#kubernetes-autoscaling", "summary": "Explains kubernetes autoscaling in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "concepts#kubernetes-autoscaling", "url": "/docs/concepts#kubernetes-autoscaling", "anchor": "kubernetes-autoscaling" } ], "mode": "agent-primary", "terms": [ "kubernetes", "autoscaling", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "because", "layer", "stateless", "autoscale", "every", "tier", "independently", "karpenter", "handles", "node", "level", "scaling", "keda", "scales", "pods", "against", "signals", "embedded", "postgresql", "queue", "data", "decisions", "only", "carries", "recoverable", "system", "state" ] }, { "id": "concepts#scattergather", "kind": "section", "title": "Concepts", "heading": "Scatter/gather", "group": "Overview", "url": "/docs/concepts#scattergather", "summary": "Explains scatter/gather in the context of Concepts, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "concepts", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "shard", "post", "namespaces", "namespace", "init", "count", "layer", "rows", "shards", "filtered", "partition", "single", "hash", "buckets", "called", "assigning", "reserved", "hevlayershard", "attribute", "xxh64", "modulo", "gateway", "scatters", "query", "every", "bucket", "parallel", "gathers" ] }, { "id": "dashboard", "kind": "section", "title": "Dashboard", "heading": null, "group": "Operations", "url": "/docs/dashboard", "summary": "Provides an overview of Dashboard, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "dashboard", "purpose", "behavior", "users", "should", "expect", "layer", "callout", "astro", "running", "cluster", "operations", "access", "needs", "networking", "auth", "turning", "operator", "ships", "alongside", "gateway", "deployment", "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": "Explains access it needs in the context of Dashboard, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "dashboard", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "metrics", "layer", "gateway", "derivefromstore", "vectorstore", "keys", "cost", "hevlayer", "kubeaccess", "enabled", "writeaccess", "false", "serviceaccount", "rolearn", "role", "read", "mostly", "backed", "three", "sources", "grant", "same", "endpoints", "customers", "plus", "prometheus", "compatible", "proxy", "authenticated" ] }, { "id": "dashboard#basic-auth", "kind": "section", "title": "Dashboard", "heading": "Basic auth", "group": "Operations", "url": "/docs/dashboard#basic-auth", "summary": "Explains basic auth in the context of Dashboard, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "dashboard", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "basicauth", "user", "password", "strong", "http", "sits", "front", "every", "route", "required", "refuses", "start", "without", "credentials", "through", "chart", "render", "fails", "either", "field", "blank", "while", "enabled" ] }, { "id": "dashboard#disabling-the-dashboard", "kind": "section", "title": "Dashboard", "heading": "Disabling the dashboard", "group": "Operations", "url": "/docs/dashboard#disabling-the-dashboard", "summary": "Explains disabling the dashboard in the context of Dashboard, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "enabled", "false", "optional", "disable", "deployment", "service", "rbac", "ingress", "skip", "rendering", "gateway", "transform", "runtime", "unchanged", "without", "lose", "only", "operator" ] }, { "id": "dashboard#networking", "kind": "section", "title": "Dashboard", "heading": "Networking", "group": "Operations", "url": "/docs/dashboard#networking", "summary": "Explains networking in the context of Dashboard, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "dashboard", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "kubectl", "port", "forward", "release", "namespace", "layer", "8081", "http", "localhost", "operator", "tool", "reach", "rather", "exposing", "publicly", "open", "customer", "workloads", "only", "ever", "receive", "gateway", "base", "credentials", "never" ] }, { "id": "dashboard#operational-notes", "kind": "section", "title": "Dashboard", "heading": "Operational notes", "group": "Operations", "url": "/docs/dashboard#operational-notes", "summary": "Collects operational limits, persistence characteristics, and failure considerations for Dashboard.", "facts": [], "sources": [ { "chunkId": "dashboard#operational-notes", "url": "/docs/dashboard#operational-notes", "anchor": "operational-notes" } ], "mode": "agent-primary", "terms": [ "operational", "notes", "collects", "limits", "persistence", "characteristics", "failure", "considerations", "dashboard" ] }, { "id": "dashboard#pipeline-queue-states", "kind": "section", "title": "Dashboard", "heading": "Pipeline queue states", "group": "Operations", "url": "/docs/dashboard#pipeline-queue-states", "summary": "Explains pipeline queue states in the context of Dashboard, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "dashboard", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "spec", "paused", "true", "namespaces", "vectorstores", "warehouses", "writeaccess", "enabled", "overview", "combines", "gateway", "counters", "matching", "resources", "their", "operator", "managed", "deployments", "keda", "scaledobjects", "pending", "work", "presented", "every", "workers", "intentionally", "zero", "replicas" ] }, { "id": "demos", "kind": "section", "title": "Demos", "heading": null, "group": "Overview", "url": "/docs/demos", "summary": "Provides an overview of Demos, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "demos", "purpose", "behavior", "users", "should", "expect", "shelf", "hevlayer", "chart", "hybrid", "text", "shop", "live", "applications", "built", "layer", "query", "routing", "fusion", "semantic", "image", "search", "full", "storefront", "workload", "composing", "shipped", "gateway", "features", "different", "corpus", "every", "demo", "below", "reimplements", "nothing", "composes", "fuzzy" ] }, { "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": "Explains chart in the context of Demos, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "demos", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "metformin", "500mg", "cabg", "aspirn", "hevlayer", "live", "same", "hero", "corpus", "sharpest", "bimodal", "query", "distribution", "there", "clinicians", "both", "exact", "token", "picture", "elderly", "woman", "progressive", "dyspnea", "bilateral" ] }, { "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": "Explains hybrid-text in the context of Demos, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "demos", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevlayer", "github", "live", "source", "demo", "eval", "shaped", "sibling", "routing", "scientific", "abstracts", "beir", "query", "string", "fans", "full", "input", "bm25", "plus", "fuzzy", "token", "fused", "reciprocal", "rank", "results", "survive", "typos" ] }, { "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": "Explains shelf in the context of Demos, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "demos", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "auto", "hybrid", "text", "semantic", "fused", "hevlayer", "github", "live", "source", "three", "routes", "type", "author", "title", "vibe", "gateway", "rank", "expression", "picks", "keyword", "hybridtext", "blend", "shape", "query", "renders", "decision" ] }, { "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": "Explains shop in the context of Demos, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "demos", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "nearest", "hevlayer", "github", "live", "formerly", "redirects", "source", "application", "workload", "indexing", "pipeline", "search", "recommendations", "facets", "observability", "embeds", "product", "images", "clip", "writes", "vector", "through", "layer", "pipelines", "turbopuffer", "storefront" ] }, { "id": "document-model", "kind": "section", "title": "Document model", "heading": null, "group": "Overview", "url": "/docs/document-model", "summary": "Provides an overview of Document model, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "document", "model", "purpose", "behavior", "users", "should", "expect", "hevlayer", "upserted", "shard", "xxh64", "count", "spec", "version", "stale", "after", "storeswitch", "astro", "featuregate", "layer", "reserved", "attributes", "gateway", "manages", "every", "reserves", "attribute", "prefix", "bookkeeping", "these", "read", "only", "stamps", "maintains", "writes", "completion", "patches", "must" ] }, { "id": "failure-modes", "kind": "section", "title": "Failure Modes", "heading": null, "group": "Operations", "url": "/docs/failure-modes", "summary": "Provides an overview of Failure Modes, its purpose, and the behavior users should expect.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "failure-modes" } ], "sources": [ { "chunkId": "failure-modes", "url": "/docs/failure-modes", "anchor": null } ], "mode": "agent-primary", "terms": [ "provides", "overview", "failure", "modes", "purpose", "behavior", "users", "should", "expect", "callout", "astro", "reads", "writes", "degrade", "gateway", "cache", "pipeline", "runs", "trouble", "layer", "strives", "gracefully", "queries", "document", "fetch", "served", "turbopuffer", "keep", "functioning", "components", "around", "fail", "page", "details", "scenarios", "does", "apply" ] }, { "id": "failure-modes#client-failures", "kind": "section", "title": "Failure Modes", "heading": "Client failures", "group": "Operations", "url": "/docs/failure-modes#client-failures", "summary": "Explains client failures in the context of Failure Modes, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "failure", "modes", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "gateway", "unreachable", "sdks", "return", "connection", "error", "retry", "directly", "against", "backing", "store", "keeps", "surface", "backend", "neutral", "namespace", "backed", "turbopuffer", "another", "selected", "callers", "should", "need", "specific", "credential", "fallback", "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": "Explains pipeline stop-writes in the context of Failure Modes, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "failure", "modes", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "documentcache", "autorestartonstopwrites", "true", "layer", "aerospike", "duration", "seconds", "status", "hevlayer", "cache", "cold", "responses", "total", "document", "starts", "start", "chunk", "write", "failed", "best", "effort", "read", "falling", "back", "backing", "storage", "resetonstart" ] }, { "id": "failure-modes#read", "kind": "section", "title": "Failure Modes", "heading": "Read", "group": "Operations", "url": "/docs/failure-modes#read", "summary": "Explains read in the context of Failure Modes, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "failure-modes#read", "url": "/docs/failure-modes#read", "anchor": "read" } ], "mode": "agent-primary", "terms": [ "read", "explains", "context", "failure", "modes", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "reads", "route", "through", "gateway", "outage", "does", "take", "queries", "dark", "python", "sdks", "fall", "turbopuffer", "direct", "unreachable", "compatible", "keep", "serving", "rather", "failing", "minus", "document", "cache", "search", "history", "layer", "query", "enhancements", "client" ] }, { "id": "failure-modes#write", "kind": "section", "title": "Failure Modes", "heading": "Write", "group": "Operations", "url": "/docs/failure-modes#write", "summary": "Explains write in the context of Failure Modes, focusing on expected behavior and relevant operational constraints.", "facts": [], "sources": [ { "chunkId": "failure-modes#write", "url": "/docs/failure-modes#write", "anchor": "write" } ], "mode": "agent-primary", "terms": [ "write", "explains", "context", "failure", "modes", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "writes", "also", "fall", "through", "turbopuffer", "direct", "gateway", "unreachable", "again", "client", "durable", "upstream", "still", "accepts", "skips", "document", "cache", "warming", "pipeline", "staging", "until", "returns" ] }, { "id": "faq", "kind": "section", "title": "FAQ", "heading": null, "group": "Overview", "url": "/docs/faq", "summary": "Provides an overview of FAQ, its purpose, and the behavior users should expect.", "facts": [], "sources": [ { "chunkId": "faq", "url": "/docs/faq", "anchor": null } ], "mode": "agent-primary", "terms": [ "provides", "overview", "purpose", "behavior", "users", "should", "expect", "licensing", "pricing", "trials", "started", "page", "answers", "questions", "rest", "docs", "project", "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": "Explains how do i know whether my license is healthy? in the context of FAQ, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "licensed", "grace", "floor", "call", "gateway", "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": "Explains how do i start a trial? in the context of FAQ, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "signup", "submit", "work", "email", "layer", "emails", "signed", "plus", "current", "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": "Explains how much will it cost? in the context of FAQ, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "licensed", "operator", "deployment", "license", "install", "production", "staging", "cluster", "carry", "their", "replicas", "within", "count", "pricing", "final", "design", "partner", "start", "trial", "commercial", "terms", "handled", "directly" ] }, { "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": "Explains what is the licensing for hev layer? in the context of FAQ, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "license", "token", "apache", "github", "standalone", "gateway", "source", "available", "under", "business", "free", "self", "host", "scale", "converts", "change", "date", "operator", "function", "runtime", "dashboard", "require", "commercial", "licensed", "installs", "signed", "keys", "trial", "access", "supplied" ] }, { "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": "Explains who built hev layer? in the context of FAQ, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevmind", "adam", "hevenor", "mind", "product" ] }, { "id": "guarantees", "kind": "section", "title": "No Guarantees", "heading": null, "group": "Overview", "url": "/docs/guarantees", "summary": "Provides an overview of No Guarantees, its purpose, and the behavior users should expect.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "guarantees" } ], "sources": [ { "chunkId": "guarantees", "url": "/docs/guarantees", "anchor": null } ], "mode": "agent-primary", "terms": [ "provides", "overview", "guarantees", "purpose", "behavior", "users", "should", "expect", "callout", "astro", "layer", "offer", "here", "commit", "instead", "best", "provide", "secure", "hands", "infrastructure", "ultimately", "responsible", "while", "make", "promises", "design", "distribute", "software", "believe", "easy", "stand", "test", "time", "page", "covers", "specific", "status", "those" ] }, { "id": "guarantees#commitments", "kind": "section", "title": "No Guarantees", "heading": "Commitments", "group": "Overview", "url": "/docs/guarantees#commitments", "summary": "Explains commitments in the context of No Guarantees, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "value", "literal": "hevmind.com", "chunkId": "guarantees#commitments" } ], "sources": [ { "chunkId": "guarantees#commitments", "url": "/docs/guarantees#commitments", "anchor": "commitments" } ], "mode": "agent-primary", "terms": [ "commitments", "explains", "context", "guarantees", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "hevmind", "history", "backed", "search", "namespace", "snapshots", "written", "bucket", "specify", "format", "data", "change", "served", "cache", "customer", "document", "chunk", "layer", "local", "price", "performance", "stray", "pattern", "though", "some", "cases", "justify", "smaller", "memory", "documentation" ] }, { "id": "index", "kind": "section", "title": "Introduction", "heading": null, "group": "Overview", "url": "/docs", "summary": "Provides an overview of Introduction, its purpose, and the behavior users should expect.", "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": [ "provides", "overview", "introduction", "purpose", "behavior", "users", "should", "expect", "function", "apache", "agpl", "diagram", "astro", "karpenter", "aerospike", "postgresql", "victoriametrics", "layer", "gateway", "runtime", "modern", "retrieval", "systems", "scales", "compute", "multi", "stage", "indexing", "pipelines", "runs", "functions", "across", "every", "index", "durable", "state", "object", "storage", "drop", "enhancements" ] }, { "id": "install", "kind": "section", "title": "Install", "heading": null, "group": "Operations", "url": "/docs/install", "summary": "Provides an overview of Install, its purpose, and the behavior users should expect.", "facts": [ { "kind": "value", "literal": "Callout.astro", "chunkId": "install" } ], "sources": [ { "chunkId": "install", "url": "/docs/install", "anchor": null } ], "mode": "agent-primary", "terms": [ "provides", "overview", "install", "purpose", "behavior", "users", "should", "expect", "callout", "astro", "bring", "layer", "environment", "resources", "terraform", "runtime", "helm", "stages", "provisions", "required", "networking", "cost", "read", "roles", "recommended", "path", "fresh", "cluster", "installs", "gateway", "operator", "document", "cache", "wires", "produced", "skip", "already", "needs", "minimum", "provide" ] }, { "id": "install#cluster-recommended", "kind": "section", "title": "Install", "heading": "Cluster: recommended", "group": "Operations", "url": "/docs/install#cluster-recommended", "summary": "Explains cluster: recommended in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "system", "large", "worker", "design", "partner", "installs", "should", "fresh", "unless", "there", "specific", "reason", "bind", "layer", "existing", "path", "provisions", "subnets", "endpoints", "expects", "control", "plane", "always", "node", "group", "defaulting", "serving", "document", "cache" ] }, { "id": "install#cost-notes", "kind": "section", "title": "Install", "heading": "Cost notes", "group": "Operations", "url": "/docs/install#cost-notes", "summary": "Explains cost notes in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "system", "east", "terraform", "designed", "deploy", "efficient", "footprint", "autoscaling", "demand", "indexing", "work", "rest", "fixed", "costs", "mostly", "node", "shared", "small", "storage", "lines", "current", "pricing", "baseline", "roughly", "hundreds", "dollars", "month", "before", "variable" ] }, { "id": "install#default-infrarules", "kind": "section", "title": "Install", "heading": "Default InfraRules", "group": "Operations", "url": "/docs/install#default-infrarules", "summary": "Explains default infrarules in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "operator", "create", "true", "spec", "scaling", "pool", "worker", "computeclass", "large", "layer", "node", "role", "workerkarpenter", "computepools", "helm", "renders", "cluster", "scoped", "object", "every", "pipeline", "function", "reference", "workload", "omits", "maps", "stock", "compute", "pools" ] }, { "id": "install#gateway-auth-modes", "kind": "section", "title": "Install", "heading": "Gateway auth modes", "group": "Operations", "url": "/docs/install#gateway-auth-modes", "summary": "Explains gateway auth modes in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "credential", "apikey", "tpuf", "inboundauth", "mode", "derivefromstore", "keys", "workersecretkey", "layer", "inbound", "worker", "name", "scopes", "read", "write", "admin", "secretref", "workersecretname", "default", "single", "tenant", "byoc", "path", "needs", "only", "bearer", "chart" ] }, { "id": "install#guided-cli-install", "kind": "section", "title": "Install", "heading": "Guided CLI install", "group": "Operations", "url": "/docs/install#guided-cli-install", "summary": "Explains guided cli install in the context of Install, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "git clone https://github.com/hev/layer\ncd layer\ngo build -o layer ./apps/layer-cli\n./layer install aws", "chunkId": "install#guided-cli-install" }, { "kind": "code", "literal": "hev/layer", "chunkId": "install#guided-cli-install" }, { "kind": "code", "literal": "layer install aws", "chunkId": "install#guided-cli-install" }, { "kind": "code", "literal": "i4i.large", "chunkId": "install#guided-cli-install" }, { "kind": "code", "literal": "--dry-run", "chunkId": "install#guided-cli-install" } ], "sources": [ { "chunkId": "install#guided-cli-install", "url": "/docs/install#guided-cli-install", "anchor": "guided-cli-install" } ], "mode": "agent-primary", "terms": [ "guided", "install", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "clone", "https", "github", "layer", "build", "apps", "large", "fast", "path", "wizard", "repository", "carries", "terraform", "configuration", "helm", "chart", "script", "drives", "checkout", "asks", "profile", "region", "base", "node", "instance", "type", "always", "system", "default", "upstream" ] }, { "id": "install#helm", "kind": "section", "title": "Install", "heading": "Helm", "group": "Operations", "url": "/docs/install#helm", "summary": "Explains helm in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "infra", "layer", "chart", "installs", "gateway", "operator", "document", "cache", "cluster", "already", "resources", "terraform", "equivalent", "manage" ] }, { "id": "install#image-coordinates", "kind": "section", "title": "Install", "heading": "Image Coordinates", "group": "Operations", "url": "/docs/install#image-coordinates", "summary": "Explains image coordinates in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "gateway", "hevlayer", "layer", "version", "operator", "enabled", "true", "dashboard", "license", "token", "existingsecret", "search", "customer", "pull", "path", "owned", "runtime", "images", "docker", "these", "public", "licensed", "surfaces", "only", "useful", "valid", "installed", "through", "without" ] }, { "id": "install#install-shape", "kind": "section", "title": "Install", "heading": "Install shape", "group": "Operations", "url": "/docs/install#install-shape", "summary": "Explains install shape in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "index", "spec", "backend", "storeref", "keys", "helm", "release", "environment", "bucket", "snapshot", "history", "data", "chart", "renders", "default", "credential", "provide", "define", "additional", "resources", "upstream", "inbound", "auth", "policy", "route", "namespaces", "between", "scoped", "gateway" ] }, { "id": "install#layer-operated-search", "kind": "section", "title": "Install", "heading": "Layer-Operated Search", "group": "Operations", "url": "/docs/install#layer-operated-search", "summary": "Explains layer-operated search in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "enabled", "true", "bucket", "kind", "vectorstore", "inboundauth", "mode", "keys", "open", "derivefromstore", "backend", "beside", "gateway", "chart", "uses", "existing", "service", "account", "irsa", "stores", "data", "under", "default", "mounts", "node", "local", "object", "cache" ] }, { "id": "install#local-gateway-development", "kind": "section", "title": "Install", "heading": "Local gateway development", "group": "Operations", "url": "/docs/install#local-gateway-development", "summary": "Explains local gateway development in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "docker", "compose", "vectorstore", "index", "endpoint", "starts", "dependencies", "replacement", "control", "plane", "still", "resolves", "resources", "kubernetes", "startup", "based", "needs", "current", "kube", "layer", "crds", "installed", "matching", "secret", "objects", "applied", "search", "backend" ] }, { "id": "install#one-script-install", "kind": "section", "title": "Install", "heading": "One-script install", "group": "Operations", "url": "/docs/install#one-script-install", "summary": "Explains one-script install in the context of Install, focusing on expected behavior and relevant operational constraints.", "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": "hev/layer", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "git clone https://github.com/hev/layer", "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": "SYSTEM_NODE_INSTANCE_TYPE", "chunkId": "install#one-script-install" }, { "kind": "code", "literal": "i4i.large", "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" } ], "sources": [ { "chunkId": "install#one-script-install", "url": "/docs/install#one-script-install", "anchor": "one-script-install" } ], "mode": "agent-primary", "terms": [ "script", "install", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "export", "turbopuffer", "tpuf", "curl", "fssl", "https", "hevlayer", "bash", "terraform", "helm", "kubectl", "openssl", "layer", "clone", "github", "region", "east", "cluster", "name", "namespace", "release", "version", "latest", "system", "node", "instance", "type", "large", "license", "token" ] }, { "id": "install#outputs", "kind": "section", "title": "Install", "heading": "Outputs", "group": "Operations", "url": "/docs/install#outputs", "summary": "Explains outputs in the context of Install, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "Project=hevlayer", "chunkId": "install#outputs" } ], "sources": [ { "chunkId": "install#outputs", "url": "/docs/install#outputs", "anchor": "outputs" } ], "mode": "agent-primary", "terms": [ "outputs", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "project", "hevlayer", "terraform", "emits", "values", "helm", "chart", "needs", "bucket", "name", "gateway", "irsa", "role", "cluster", "metadata", "runtime", "images", "pulled", "docker", "layer", "owned", "operator", "dashboard", "containers", "pass", "these", "file", "described", "below", "provider" ] }, { "id": "install#required-values", "kind": "section", "title": "Install", "heading": "Required values", "group": "Operations", "url": "/docs/install#required-values", "summary": "Explains required values in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "vectorstore", "credential", "apikey", "derivefromstore", "endpoint", "region", "inboundauth", "mode", "keys", "open", "read", "write", "admin", "search", "enabled", "kind", "image", "ghcr", "gateway", "hevlayer", "layer", "version", "operator", "dashboard", "most", "chart", "opinionated", "defaults", "typical" ] }, { "id": "install#run-the-install", "kind": "section", "title": "Install", "heading": "Run the install", "group": "Operations", "url": "/docs/install#run-the-install", "summary": "Explains run the install in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "helm", "upgrade", "layer", "infra", "namespace", "create", "values", "customer", "yaml", "chart", "published", "public", "repository", "source", "path", "artifact", "provided", "during", "onboarding" ] }, { "id": "install#terraform", "kind": "section", "title": "Install", "heading": "Terraform", "group": "Operations", "url": "/docs/install#terraform", "summary": "Explains terraform in the context of Install, focusing on expected behavior and relevant operational constraints.", "facts": [ { "kind": "code", "literal": "infra/terraform/", "chunkId": "install#terraform" } ], "sources": [ { "chunkId": "install#terraform", "url": "/docs/install#terraform", "anchor": "terraform" } ], "mode": "agent-primary", "terms": [ "terraform", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "infra", "configuration", "provisions", "resources", "gateway", "operator", "need", "opinionated", "about", "layer", "needs", "behave", "correctly", "conservative", "around", "route53", "hosted", "zones", "certificates", "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": "Explains what gets installed in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "layer", "gateway", "operator", "document", "cache", "nodepool", "ec2nodeclass", "worker", "workerkarpenter", "enabled", "true", "documentcache", "noderole", "karpenter", "rust", "turbopuffer", "compatible", "routes", "fetch", "scans", "snapshots", "warm", "jobs", "pipeline", "state", "reconciler", "vectorstore", "index", "infrarules" ] }, { "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": "Explains what it sets up in the context of Install, focusing on expected behavior and relevant operational constraints.", "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", "explains", "context", "install", "focusing", "expected", "behavior", "relevant", "operational", "constraints", "manage", "public", "true", "resource", "purpose", "bucket", "durable", "storage", "namespace", "snapshots", "search", "history", "clickstream", "events", "roles", "irsa", "policies", "gateway", "cost", "explorer", "access", "plus", "worker", "operator", "repositories", "registry", "space", "customer", "built", "function" ] }, { "id": "kubernetes/agent-crd", "kind": "section", "title": "Agent CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/agent-crd", "summary": "An Agent is a Kubernetes-managed search reasoning configuration that binds a model, request budget, and readable indexes. It reformulates and reranks federated retrieval results while returning ordinary search rows rather than generated prose.", "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", "kubernetes", "managed", "search", "reasoning", "configuration", "binds", "model", "request", "budget", "readable", "indexes", "reformulates", "reranks", "federated", "retrieval", "results", "while", "returning", "ordinary", "rows", "rather", "generated", "prose", "post", "agents", "name", "query", "auto", "kubectl", "yaml", "client", "support", "apply", "callout", "astro", "agentic", "resource", "governed", "loop" ] }, { "id": "kubernetes/agent-crd#auth", "kind": "section", "title": "Agent CRD", "heading": "Auth", "group": "Operations", "url": "/docs/kubernetes/agent-crd#auth", "summary": "Agent invocation requires a matching key entitlement, while access to each searched namespace is separately constrained by the caller's data grants.", "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", "agent", "invocation", "requires", "matching", "entitlement", "while", "access", "searched", "namespace", "separately", "constrained", "caller", "data", "grants", "name", "follows", "same", "model", "other", "endpoints", "multi", "queries", "follow", "federated", "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": "An agent request has a wall-clock deadline and can either return its best available ranking at expiry or fail 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", "agent", "request", "wall", "clock", "deadline", "either", "return", "best", "available", "ranking", "expiry", "fail", "deadlinems", "ondeadline", "besteffort", "error", "field", "purpose", "whole", "default", "returns", "hits", "fails", "instead" ] }, { "id": "kubernetes/agent-crd#indices", "kind": "section", "title": "Agent CRD", "heading": "Indices", "group": "Operations", "url": "/docs/kubernetes/agent-crd#indices", "summary": "The configured index list becomes the federated search scope. The operator validates list shape but not namespace existence, and runtime reads remain limited by the caller's credential.", "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", "configured", "index", "list", "becomes", "federated", "search", "scope", "operator", "validates", "shape", "namespace", "existence", "runtime", "reads", "remain", "limited", "caller", "credential", "namespaces", "indicesresolved", "agent", "searches", "passed", "query", "checks", "present", "every", "entry", "empty", "string", "surfaced", "condition", "does", "currently", "confirm", "names", "exists", "listed", "under" ] }, { "id": "kubernetes/agent-crd#model", "kind": "section", "title": "Agent CRD", "heading": "Model", "group": "Operations", "url": "/docs/kubernetes/agent-crd#model", "summary": "The resource selects an inference provider, primary model, optional fallback, and a Secret-backed credential. Inline provider tokens are limited to local development and are rejected from 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", "resource", "selects", "inference", "provider", "primary", "optional", "fallback", "secret", "backed", "credential", "inline", "tokens", "limited", "local", "development", "rejected", "deployed", "resources", "openrouter", "name", "anthropic", "claude", "haiku", "apikeysecretref", "apikey", "agent", "field", "purpose", "backend", "passed", "times", "errors", "holding", "token", "never", "same", "rule", "vectorstore", "crds" ] }, { "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 invocation addresses only the name. Conflicts resolve deterministically to one namespace and produce a warning.", "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", "invocation", "addresses", "only", "name", "conflicts", "resolve", "deterministically", "namespace", "produce", "warning", "gateway", "callers", "address", "agents", "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 metrics report deadline hits, provider latency, and token consumption, while cost can be derived downstream. Reasoning traces join ordinary search history for evaluation.", "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", "metrics", "report", "deadline", "hits", "provider", "latency", "token", "consumption", "while", "cost", "derived", "downstream", "reasoning", "traces", "join", "ordinary", "search", "history", "evaluation", "hevlayer", "rate", "usage", "export", "counts", "come", "back", "inference", "response", "extra", "call", "dollar", "rather", "fetched", "request", "path", "trace", "written", "record" ] }, { "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 attach retrieval and relevance provenance or a full 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", "attach", "retrieval", "relevance", "provenance", "full", "reasoning", "trace", "both", "disabled", "response", "indistinguishable", "normal", "federated", "query", "agent", "retrievalscore", "relevancescore", "field", "purpose", "true", "carries", "gains", "level", "echo", "also", "default", "byte", "shape", "client", "cannot", "tell", "loop", "produced", "agentic", "search", "request", "contract" ] }, { "id": "kubernetes/agent-crd#retrieval", "kind": "section", "title": "Agent CRD", "heading": "Retrieval", "group": "Operations", "url": "/docs/kubernetes/agent-crd#retrieval", "summary": "Agent retrieval uses parallel query reformulations, a bounded candidate pool, a selectable search route, and weighted final reranking. Semantic legs require a caller-provided vector and otherwise fall back to lexical retrieval.", "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", "uses", "parallel", "query", "reformulations", "bounded", "candidate", "pool", "selectable", "search", "route", "weighted", "final", "reranking", "semantic", "legs", "require", "caller", "provided", "vector", "otherwise", "fall", "back", "lexical", "fanout", "recalldepth", "rankby", "auto", "hybridtext", "relevanceweight", "behavior", "expressed", "against", "federated", "nothing", "reaches", "upstream", "field", "default" ] }, { "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 reachability rather than operational counters, distinguishing callable, degraded, and invalid configurations. Gateway resolution refreshes periodically, so edits become active shortly after reconciliation.", "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", "reachability", "rather", "operational", "counters", "distinguishing", "callable", "degraded", "invalid", "configurations", "gateway", "resolution", "refreshes", "periodically", "edits", "become", "active", "shortly", "after", "reconciliation", "secretresolved", "model", "apikeysecretref", "modelreachable", "indicesresolved", "spec", "indices", "ready", "kubectl", "phase", "apply", "carries", "health", "only", "latency", "turn", "counts" ] }, { "id": "kubernetes/apikey-crd", "kind": "section", "title": "ApiKey CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/apikey-crd", "summary": "An ApiKey resource represents a minted credential whose lifecycle and access are managed by Layer. Entitlements target stores, warehouses, agents, or the control plane, while opaque claims remain application-defined.", "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", "resource", "represents", "minted", "credential", "whose", "lifecycle", "access", "managed", "layer", "entitlements", "target", "stores", "warehouses", "agents", "control", "plane", "while", "opaque", "claims", "remain", "application", "defined", "vectorstore", "warehouse", "agent", "kubectl", "yaml", "keys", "keyid", "kubernetes", "resources", "owns", "mint", "verify", "revoke", "expire", "opens", "declared", "entitlement" ] }, { "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 namespace-level backup that preserves resource status, the verifier pepper, and delivery Secrets. Operators must quiesce reconciliation, verify backup contents and ordering, rebuild discovery after restore, and treat unexpected mint blocking as a failed restore.", "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", "namespace", "level", "preserves", "resource", "status", "verifier", "pepper", "delivery", "secrets", "operators", "must", "quiesce", "reconciliation", "verify", "contents", "ordering", "rebuild", "discovery", "after", "restore", "treat", "unexpected", "mint", "blocking", "failed", "source", "context", "layer", "target", "base", "https", "example", "admin", "scripts", "apikey", "velero" ] }, { "id": "kubernetes/apikey-crd#bootstrapping", "kind": "section", "title": "ApiKey CRD", "heading": "Bootstrapping", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#bootstrapping", "summary": "A bootstrap credential can mint the first administrator key, after which routine key management uses minted administration credentials. Cluster operators can alternatively bootstrap through direct resource authoring.", "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", "mint", "first", "administrator", "after", "routine", "management", "uses", "minted", "administration", "credentials", "cluster", "operators", "alternatively", "through", "direct", "resource", "authoring", "spec", "entitlements", "layer", "scopes", "admin", "gateway", "apikey", "layergatewayapikey", "mints", "minting", "keys", "equally", "applying", "since", "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 separately grant store data access, agent invocation, or control-plane administration, while warehouse claims are only stored for external interpretation. Missing targets grant nothing but do not prevent creation, and claim-only keys authenticate without opening Layer routes.", "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", "separately", "grant", "store", "data", "access", "agent", "invocation", "control", "plane", "administration", "while", "warehouse", "claims", "only", "stored", "external", "interpretation", "missing", "targets", "nothing", "prevent", "creation", "claim", "keys", "authenticate", "without", "opening", "layer", "routes", "vectorstore", "name", "scopes", "read", "write", "index", "namespaces", "post", "agents", "query" ] }, { "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 Kubernetes roles separate full key administration and token collection from metadata-only audit access. Neither role is implicitly included in standard namespace roles, so delegation is 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", "roles", "separate", "full", "administration", "token", "collection", "metadata", "only", "audit", "access", "neither", "role", "implicitly", "included", "standard", "namespace", "delegation", "explicit", "hevlayer", "admin", "apikeys", "viewer", "list", "watch", "view", "edit", "keyrolebindings", "authoring", "makes", "kubectl", "minting", "surface", "chart", "ships", "delegate", "without", "cluster" ] }, { "id": "kubernetes/apikey-crd#minting", "kind": "section", "title": "ApiKey CRD", "heading": "Minting", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#minting", "summary": "Keys may be minted through the API, which reveals the token once, or by applying a resource, which delivers it through an owned Secret. Layer persists only one-way verification material and rotation uses a replacement-before-revoke workflow.", "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", "reveals", "token", "once", "applying", "resource", "delivers", "owned", "secret", "layer", "persists", "only", "verification", "material", "rotation", "uses", "replacement", "before", "revoke", "workflow", "post", "keyid", "returned", "metadata", "includerevoked", "idempotent", "delete", "hard", "revoked", "authenticate", "body", "entitlements", "apikey", "admin", "status", "secretref", "phase" ] }, { "id": "kubernetes/apikey-crd#spec", "kind": "section", "title": "ApiKey CRD", "heading": "Spec", "group": "Operations", "url": "/docs/kubernetes/apikey-crd#spec", "summary": "A key specification may carry owner and description metadata, a target-keyed entitlement map, and an expiration policy. The expiration timestamp is calculated when the credential 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", "owner", "description", "metadata", "target", "keyed", "entitlement", "expiration", "policy", "timestamp", "calculated", "credential", "minted", "entitlements", "scopes", "namespaces", "claims", "expiresafter", "never", "365d", "status", "expiresat", "field", "purpose", "optional", "free", "form", "label", "echoed", "list", "authenticate", "responses", "resource", "entry", "carries", "duration", "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 stable identity and entitlements for external authorization. Keys progress through pending, active, revoked, and expired states; revocation is retained for audit, while hard deletion is restricted and target deletion safely inerts affected grants.", "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", "identity", "entitlements", "external", "authorization", "keys", "progress", "through", "pending", "active", "revoked", "expired", "states", "revocation", "retained", "audit", "while", "hard", "deletion", "restricted", "target", "safely", "inerts", "affected", "grants", "post", "authenticate", "keyid", "status", "lastseenat", "revoke", "expiresat" ] }, { "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 present in an index. The gateway manages discovery, queues, leases, retries, and completion state, while operator-created workers perform the data writes.", "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", "present", "index", "gateway", "manages", "discovery", "queues", "leases", "retries", "completion", "state", "while", "operator", "created", "workers", "perform", "data", "writes", "codetabs", "astro", "user", "defined", "functions", "declared", "kubernetes", "resources", "runs", "exist", "right", "shape", "classifiers", "enrichment", "backfills", "existing", "deterministic" ] }, { "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 select the GPU compute class and should package model weights into the worker image. Batch, timeout, lease, and minimum-replica settings balance inference duration against cold-start cost.", "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", "select", "compute", "class", "should", "package", "model", "weights", "worker", "image", "batch", "timeout", "lease", "minimum", "replica", "settings", "balance", "inference", "duration", "against", "cold", "start", "cost", "computeclass", "scaling", "pool", "infrarules", "default", "layer", "node", "role", "torch", "transformers", "pillow", "httpx", "hevlayer", "batchsize", "timeoutseconds" ] }, { "id": "kubernetes/function-crd#lifecycle", "kind": "section", "title": "Function CRD", "heading": "Lifecycle", "group": "Operations", "url": "/docs/kubernetes/function-crd#lifecycle", "summary": "Function reconciliation registers and updates the gateway definition even when paused, while preserving its queue state. Paused status is distinct from absence, and deletion removes the managed workload registration.", "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", "reconciliation", "registers", "updates", "gateway", "definition", "even", "paused", "while", "preserving", "queue", "state", "status", "distinct", "absence", "deletion", "removes", "managed", "workload", "registration", "udfs", "product", "tags", "true", "spec", "udfstatus", "kubectl", "describe", "layer", "patch", "type", "merge", "false", "curl", "post", "authorization", "bearer", "layergatewayapikey", "layergatewayurl" ] }, { "id": "kubernetes/function-crd#scaling", "kind": "section", "title": "Function CRD", "heading": "Scaling", "group": "Operations", "url": "/docs/kubernetes/function-crd#scaling", "summary": "Functions use the shared workload scaling policy and can autoscale from queue depth within compute-pool limits. A warm window is especially useful for scale-to-zero GPU work because it amortizes node and model startup.", "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", "shared", "workload", "policy", "autoscale", "queue", "depth", "within", "compute", "pool", "limits", "warm", "window", "especially", "useful", "scale", "zero", "work", "because", "amortizes", "node", "model", "startup", "spec", "infrarules", "default", "mode", "scaledobject", "layer", "maxreplicasperworkload", "warmwindowseconds", "same", "config", "pipelines", "replica", "bounds", "emits", "keda", "triggered" ] }, { "id": "kubernetes/function-crd#selection", "kind": "section", "title": "Function CRD", "heading": "Selection", "group": "Operations", "url": "/docs/kubernetes/function-crd#selection", "summary": "Functions can select explicit namespaces or indexes matched by labels, then apply an arbitrary source filter. Completion-version selection is added by the gateway and should not be duplicated in the user filter.", "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", "select", "explicit", "namespaces", "indexes", "matched", "labels", "apply", "arbitrary", "source", "filter", "completion", "version", "added", "gateway", "should", "duplicated", "user", "targetnamespaces", "indexselector", "index", "spec", "resources", "choose", "preserves", "json", "including", "array", "form", "turbopuffer", "filters", "operator", "stores", "shape", "evaluates", "during", "discovery", "after", "generated" ] }, { "id": "kubernetes/function-crd#simple-classifier", "kind": "section", "title": "Function CRD", "heading": "Simple classifier", "group": "Operations", "url": "/docs/kubernetes/function-crd#simple-classifier", "summary": "Client helpers implement the claim, process, completion, and failure loop for ordinary functions. Workers report retryable and permanent failures distinctly, and successful completion writes both result attributes and the internal completion marker.", "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", "client", "helpers", "implement", "claim", "process", "completion", "failure", "loop", "ordinary", "functions", "workers", "report", "retryable", "permanent", "failures", "distinctly", "successful", "writes", "both", "result", "attributes", "internal", "marker", "output", "tags", "worker", "inputs", "transienterror", "permanenterror", "failudfitems", "kind", "transient", "python", "turns", "normal", "function", "complete", "side" ] }, { "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 throughput and reliability are bounded by batch size, call timeout, claim lease, discovery cadence, concurrent batches, concurrent scans, and retry attempts.", "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", "throughput", "reliability", "bounded", "batch", "size", "call", "timeout", "claim", "lease", "discovery", "cadence", "concurrent", "batches", "scans", "retry", "attempts", "worker", "batchsize", "timeoutseconds", "schedule", "leaseseconds", "discoveryintervalseconds", "maxinflightbatches", "maxconcurrentscans", "maxattempts", "failed", "knob", "bounds", "rows", "long", "held", "before", "reissue", "time", "between", "scan", "jobs" ] }, { "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 Function version is stamped onto completed rows and drives rediscovery when absent, changed, or stale. Updating the version safely reruns work after behavior or model changes.", "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", "function", "stamped", "onto", "completed", "rows", "drives", "rediscovery", "absent", "changed", "stale", "updating", "safely", "reruns", "work", "after", "behavior", "model", "changes", "spec", "hevlayer", "metadata", "name", "product", "color", "safety", "rail", "defaults", "completion", "gateway", "stamps", "hevlayerudf", "normalizing", "hyphens", "underscores", "marker", "hevlayerudfproductcolorv", "discovery", "automatically" ] }, { "id": "kubernetes/function-crd#worker", "kind": "section", "title": "Function CRD", "heading": "Worker", "group": "Operations", "url": "/docs/kubernetes/function-crd#worker", "summary": "A Function worker declares its image, dispatch style, compute class, service settings, and optional pod customization. The operator injects runtime identity, gateway connection, processing limits, lease information, 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", "function", "declares", "image", "dispatch", "style", "compute", "class", "service", "settings", "optional", "customization", "operator", "injects", "runtime", "identity", "gateway", "connection", "processing", "limits", "lease", "information", "appropriate", "bearer", "credential", "pull", "push", "computeclass", "scaling", "pool", "port", "batchsize", "timeoutseconds", "podspec", "layer", "hevlayer", "base", "batch", "size", "timeout" ] }, { "id": "kubernetes/function-crd#writeback", "kind": "section", "title": "Function CRD", "heading": "Writeback", "group": "Operations", "url": "/docs/kubernetes/function-crd#writeback", "summary": "Workers own writeback and may return attributes, vectors, or multivector data together with completion state. The gateway merges updates safely, reserved fields are protected, retries should use deterministic identifiers, and deleting the Function does not erase prior results.", "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", "attributes", "vectors", "multivector", "data", "together", "completion", "state", "gateway", "merges", "updates", "safely", "reserved", "fields", "protected", "retries", "should", "deterministic", "identifiers", "deleting", "function", "does", "erase", "prior", "results", "output", "tags", "worker", "patch", "columns", "hevlayer", "vector", "kind", "embedding", "tpuf", "none", "writes", "common" ] }, { "id": "kubernetes/index-crd", "kind": "section", "title": "Index CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/index-crd", "summary": "An Index declares one gateway-visible namespace and its upstream binding, embedding identity, snapshot policy, cache posture, scan behavior, and consistency settings.", "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", "declares", "gateway", "visible", "namespace", "upstream", "binding", "embedding", "identity", "snapshot", "policy", "cache", "posture", "scan", "behavior", "consistency", "settings", "declarative", "representation", "managed", "layer", "represents", "exposed", "through", "mode", "backend", "connection", "itself", "lives", "vectorstore", "apiversion", "hevlayer", "kind", "metadata", "name", "products", "spec", "storeref", "turbopuffer", "default" ] }, { "id": "kubernetes/index-crd#backend", "kind": "section", "title": "Index CRD", "heading": "Backend", "group": "Operations", "url": "/docs/kubernetes/index-crd#backend", "summary": "An index can select a same-namespace store, override its upstream namespace, and choose a supported distance metric. Unsupported backend-metric combinations leave the resource 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", "index", "select", "same", "namespace", "store", "override", "upstream", "choose", "supported", "distance", "metric", "unsupported", "combinations", "leave", "resource", "unready", "storeref", "vectorstore", "distancemetric", "cosine", "kind", "search", "ready", "false", "metricmismatch", "field", "purpose", "optional", "name", "gateway", "routes", "requests", "defaults", "default", "vector", "cosinedistance", "stores", "operator", "accepts" ] }, { "id": "kubernetes/index-crd#cache-policy", "kind": "section", "title": "Index CRD", "heading": "Cache policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#cache-policy", "summary": "Document caching is ephemeral, while durable snapshot history remains in object storage. Cache warming shares the standard origin-scan fan-out controls.", "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", "caching", "ephemeral", "while", "durable", "snapshot", "history", "remains", "object", "storage", "warming", "shares", "standard", "origin", "scan", "controls", "aerospike", "stays", "uses", "same", "other", "scans" ] }, { "id": "kubernetes/index-crd#chunking", "kind": "section", "title": "Index CRD", "heading": "Chunking", "group": "Operations", "url": "/docs/kubernetes/index-crd#chunking", "summary": "Embedded text can be split with common scalar strategies or fanned out by structured sections before optional windowing. Chunks retain source attributes and parent metadata, and this write mode requires string identifiers and row-oriented upserts.", "facts": [ { "kind": "code", "literal": "embed.chunk", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "strategy", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "none", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "fixed", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "recursive", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "sentence", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "markdown", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "unit", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "characters", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "tokens", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "size", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "overlap", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "tokenizer", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "{id}#{i}", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "_hevlayer_parent_id", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "_hevlayer_chunk_index", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "split", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "{id}#{section}#{i}", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "upsert_rows", "chunkId": "kubernetes/index-crd#chunking" }, { "kind": "code", "literal": "422", "chunkId": "kubernetes/index-crd#chunking" } ], "sources": [ { "chunkId": "kubernetes/index-crd#chunking", "url": "/docs/kubernetes/index-crd#chunking", "anchor": "chunking" } ], "mode": "agent-primary", "terms": [ "chunking", "embedded", "text", "split", "common", "scalar", "strategies", "fanned", "structured", "sections", "before", "optional", "windowing", "chunks", "retain", "source", "attributes", "parent", "metadata", "write", "mode", "requires", "string", "identifiers", "oriented", "upserts", "embed", "chunk", "strategy", "none", "fixed", "recursive", "sentence", "markdown", "unit", "characters", "tokens", "size", "overlap", "tokenizer" ] }, { "id": "kubernetes/index-crd#embedding", "kind": "section", "title": "Index CRD", "heading": "Embedding", "group": "Operations", "url": "/docs/kubernetes/index-crd#embedding", "summary": "An index embedding profile identifies the model, output width, normalization, and distance metric needed for comparable federated vector distances. It describes existing vectors rather than computing them, and incompatible profiles fall back to rank interleaving unless strict behavior rejects them.", "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": "code", "literal": "embed:", "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", "index", "profile", "identifies", "model", "output", "width", "normalization", "distance", "metric", "needed", "comparable", "federated", "vector", "distances", "describes", "existing", "vectors", "rather", "computing", "incompatible", "profiles", "fall", "back", "rank", "interleaving", "unless", "strict", "behavior", "rejects", "spec", "voyage", "large", "outputdim", "none", "backend", "distancemetric", "embed", "declares", "identity" ] }, { "id": "kubernetes/index-crd#model-serving-policy", "kind": "section", "title": "Index CRD", "heading": "Model-serving policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#model-serving-policy", "summary": "Embedding serving can be delegated natively or resolved through the gateway before concrete vectors reach the active store. Gateway serving persists attribute profiles, caches query vectors briefly, requires full-row updates for embedded source changes, and needs a credentialed embedding provider.", "facts": [ { "kind": "code", "literal": "embed.serving.prefer", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "prefer", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "native", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "autoscaler", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "embed:", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "Embed", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "blended", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "schema", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "422", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "kind: turbopuffer", "chunkId": "kubernetes/index-crd#model-serving-policy" }, { "kind": "code", "literal": "503 service_unavailable", "chunkId": "kubernetes/index-crd#model-serving-policy" } ], "sources": [ { "chunkId": "kubernetes/index-crd#model-serving-policy", "url": "/docs/kubernetes/index-crd#model-serving-policy", "anchor": "model-serving-policy" } ], "mode": "agent-primary", "terms": [ "model", "serving", "policy", "embedding", "delegated", "natively", "resolved", "through", "gateway", "before", "concrete", "vectors", "reach", "active", "store", "persists", "attribute", "profiles", "caches", "query", "briefly", "requires", "full", "updates", "embedded", "source", "changes", "needs", "credentialed", "provider", "embed", "prefer", "native", "autoscaler", "blended", "schema", "kind", "turbopuffer", "service", "unavailable" ] }, { "id": "kubernetes/index-crd#scan-policy", "kind": "section", "title": "Index CRD", "heading": "Scan policy", "group": "Operations", "url": "/docs/kubernetes/index-crd#scan-policy", "summary": "Each index sets a default ceiling for concurrent origin requests during a scan. The effective value is constrained by server and shard capacity and may be overridden per request.", "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", "index", "sets", "default", "ceiling", "concurrent", "origin", "requests", "during", "effective", "value", "constrained", "server", "shard", "capacity", "overridden", "request", "threads", "namespace", "maximum", "upstream", "issue", "scatter", "gather", "defaults", "clamped", "gateway", "active", "count", "level", "overrides" ] }, { "id": "kubernetes/index-crd#schema-attribute-embedding", "kind": "section", "title": "Index CRD", "heading": "Schema-attribute embedding", "group": "Operations", "url": "/docs/kubernetes/index-crd#schema-attribute-embedding", "summary": "A schema attribute can request embedding during writes using a simple compatible form or an extended gateway-managed profile. Extended serving supports revisions, instructions, modalities, chunking, and derived-column control, while enforcing provider-qualified models and explicit initial distance configuration.", "facts": [ { "kind": "code", "literal": "embed:", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "voyage/voyage-4-lite", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.model", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.dims", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.attribute", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed_", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.serving.prefer", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "native", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "autoscaler", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "blended", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.revision", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.instructions", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "document", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "query", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.modality", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "text", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "image", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "Embed", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "embed.chunk", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "prefer: autoscaler", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "prefer: blended", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "422", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" }, { "kind": "code", "literal": "503 service_unavailable", "chunkId": "kubernetes/index-crd#schema-attribute-embedding" } ], "sources": [ { "chunkId": "kubernetes/index-crd#schema-attribute-embedding", "url": "/docs/kubernetes/index-crd#schema-attribute-embedding", "anchor": "schema-attribute-embedding" } ], "mode": "agent-primary", "terms": [ "schema", "attribute", "embedding", "request", "during", "writes", "simple", "compatible", "form", "extended", "gateway", "managed", "profile", "serving", "supports", "revisions", "instructions", "modalities", "chunking", "derived", "column", "control", "while", "enforcing", "provider", "qualified", "models", "explicit", "initial", "distance", "configuration", "embed", "voyage", "lite", "model", "dims", "attr", "prefer", "native", "autoscaler" ] }, { "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": "Search-backed indexes can request explicit backend index lifecycle behavior, including construction of a full-text index for lexical and hybrid retrieval.", "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", "backed", "indexes", "request", "explicit", "index", "lifecycle", "behavior", "including", "construction", "full", "text", "lexical", "hybrid", "retrieval", "spec", "kind", "fulltext", "false", "applies", "targets", "vectorstore", "operator", "uses", "drive", "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 facet fields, minimum write spacing after stable upstream progress, and retention. With no facet fields the automatic writer is disabled, and retention may keep all history or prune older bodies while retaining the latest.", "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", "facet", "fields", "minimum", "write", "spacing", "after", "stable", "upstream", "progress", "retention", "automatic", "writer", "disabled", "keep", "history", "prune", "older", "bodies", "while", "retaining", "latest", "facetfields", "interval", "never", "field", "default", "purpose", "gateway", "materializes", "durable", "snapshots", "empty", "disables", "between", "writes", "advances", "keeps" ] }, { "id": "kubernetes/index-crd#status", "kind": "section", "title": "Index CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/index-crd#status", "summary": "Index status reports observed configuration generation, metadata synchronization, and readiness conditions. Snapshot execution timestamps are reserved for the gateway 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", "configuration", "generation", "metadata", "synchronization", "readiness", "conditions", "snapshot", "execution", "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 reconciles Layer's desired cluster state, including stores, indexes, worker pools, and stateless compute. The gateway independently owns the live read and write path.", "facts": [ { "kind": "code", "literal": "layer-operator", "chunkId": "kubernetes/operator" } ], "sources": [ { "chunkId": "kubernetes/operator", "url": "/docs/kubernetes/operator", "anchor": null } ], "mode": "agent-primary", "terms": [ "operator", "reconciles", "layer", "desired", "cluster", "state", "including", "stores", "indexes", "worker", "pools", "stateless", "compute", "gateway", "independently", "owns", "live", "read", "write", "path", "relates", "manages", "declarative", "deployment", "serves", "crucial", "functions", "monitoring", "changes", "managing", "scaling", "does", "through", "abstractions", "known", "custom", "resource", "definitions", "crds", "handles" ] }, { "id": "kubernetes/operator#crds", "kind": "section", "title": "Operator Overview", "heading": "CRDs", "group": "Operations", "url": "/docs/kubernetes/operator#crds", "summary": "The operator's core resources represent backend connections, namespaces, shared infrastructure policy, row-changing pipelines, and row-preserving functions.", "facts": [], "sources": [ { "chunkId": "kubernetes/operator#crds", "url": "/docs/kubernetes/operator#crds", "anchor": "crds" } ], "mode": "agent-primary", "terms": [ "crds", "operator", "core", "resources", "represent", "backend", "connections", "namespaces", "shared", "infrastructure", "policy", "changing", "pipelines", "preserving", "functions", "reconciles", "five", "resource", "kinds", "documented", "page", "vectorstore", "upstream", "store", "endpoint", "credential", "reference", "gateway", "inbound", "auth", "index", "turbopuffer", "namespace", "should", "manage", "infrarules", "cluster", "wide", "compute", "pools" ] }, { "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 stop serving. The gateway may read resource status to inform behavior but never writes declarative resources.", "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", "stop", "serving", "read", "resource", "status", "inform", "behavior", "never", "writes", "declarative", "resources", "reconciles", "state", "serves", "write", "path", "neither", "sits", "other", "keeps", "even", "restarted", "lagging", "link", "between", "directional", "only", "some", "features", "reads", "such", "indexes", "exist", "worker" ] }, { "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 selection, and tolerations to Pipeline and Function workers. Default CPU and GPU pools align workloads with corresponding autoscaled node capacity.", "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", "selection", "tolerations", "pipeline", "function", "workers", "default", "align", "workloads", "corresponding", "autoscaled", "capacity", "nodeselector", "large", "layer", "role", "worker", "nvidia", "infrarules", "operator", "applies", "pool", "chosen", "container", "resources", "operators", "storage", "heavy", "work", "right", "helm", "installs", "stock" ] }, { "id": "kubernetes/pipeline-crd", "kind": "section", "title": "Pipeline CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/pipeline-crd", "summary": "A Pipeline declares staged ingestion or transformation work that changes row count, often separating CPU extraction from GPU embedding. Source details, target, worker behavior, schedule, and scaling can be managed declaratively while clients select runtime namespace context.", "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", "transformation", "work", "changes", "count", "often", "separating", "extraction", "embedding", "source", "details", "target", "worker", "behavior", "schedule", "scaling", "managed", "declaratively", "while", "clients", "select", "runtime", "namespace", "context", "spec", "sourceref", "changing", "declared", "kubernetes", "resource", "characteristics", "want", "ingesting", "data", "typically", "runs", "stages" ] }, { "id": "kubernetes/pipeline-crd#chunking", "kind": "section", "title": "Pipeline CRD", "heading": "Chunking", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#chunking", "summary": "Pipeline sources can declaratively split documents using fixed, recursive, sentence, or heading-aware strategies measured in tokens or characters. Each chunk becomes an indexed row with stable parent and position metadata, while custom workers handle unsupported splitting logic.", "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", "pipeline", "sources", "declaratively", "split", "documents", "fixed", "recursive", "sentence", "heading", "aware", "strategies", "measured", "tokens", "characters", "chunk", "becomes", "indexed", "stable", "parent", "position", "metadata", "while", "custom", "workers", "handle", "unsupported", "splitting", "logic", "strategy", "none", "size", "markdown", "unit", "overlap", "tokenizer", "text", "documentid", "hevlayer", "index" ] }, { "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 identifier names the gateway queue and normally follows the resource name. Multiple worker stages can share one identifier to operate on the same queue.", "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", "identifier", "names", "gateway", "queue", "normally", "follows", "resource", "name", "multiple", "worker", "stages", "share", "operate", "same", "spec", "pipelineid", "products", "scales", "defaults", "resources", "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 workers can autoscale from queue depth or schedule, run at a fixed replica count, be disabled, or pause at zero. Pool selection constrains placement and replica ceilings, and a cooldown can retain warm workers after demand drains.", "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", "workers", "autoscale", "queue", "depth", "schedule", "fixed", "replica", "count", "disabled", "pause", "zero", "pool", "selection", "constrains", "placement", "ceilings", "cooldown", "retain", "warm", "after", "demand", "drains", "mode", "replicas", "spec", "infrarules", "default", "worker", "computeclass", "large", "scaledobject", "warmwindowseconds", "paused", "true", "must", "name", "omitted", "operator" ] }, { "id": "kubernetes/pipeline-crd#schedule", "kind": "section", "title": "Pipeline CRD", "heading": "Schedule", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#schedule", "summary": "An optional schedule replaces queue-depth wakeups with a bounded recurring run window. The worker still owns source cursor and extraction semantics, and scheduled workloads must be able to scale down to zero.", "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", "replaces", "queue", "depth", "wakeups", "bounded", "recurring", "window", "worker", "still", "owns", "source", "cursor", "extraction", "semantics", "scheduled", "workloads", "must", "able", "scale", "down", "zero", "cron", "field", "minute", "single", "integer", "leaseseconds", "sizes", "spec", "scaling", "replicas", "operator", "wakes", "pipeline", "keda", "instead", "pending", "pull" ] }, { "id": "kubernetes/pipeline-crd#source", "kind": "section", "title": "Pipeline CRD", "heading": "Source", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#source", "summary": "A pipeline source describes the external input passed unchanged to the worker. Open-ended source kinds leave protocol-specific behavior entirely to the worker image.", "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", "pipeline", "describes", "external", "input", "passed", "unchanged", "worker", "open", "ended", "kinds", "leave", "protocol", "specific", "behavior", "entirely", "image", "spec", "sourceref", "kind", "hevlayer", "declares", "feeds", "selects", "operator", "treats", "kafka", "events", "partner", "migration", "arbitrary", "json", "injected", "verbatim", "hevlayersourceref", "owns", "extract", "chunk", "reading" ] }, { "id": "kubernetes/pipeline-crd#status", "kind": "section", "title": "Pipeline CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#status", "summary": "Operational queue, stage, and worker progress comes from the gateway status surface. The Kubernetes resource limits its own status to managed-object references and readiness.", "facts": [], "sources": [ { "chunkId": "kubernetes/pipeline-crd#status", "url": "/docs/kubernetes/pipeline-crd#status", "anchor": "status" } ], "mode": "agent-primary", "terms": [ "status", "operational", "queue", "stage", "worker", "progress", "comes", "gateway", "surface", "kubernetes", "resource", "limits", "managed", "object", "references", "readiness", "pipeline", "counts", "state", "itself", "reports", "only", "conditions" ] }, { "id": "kubernetes/pipeline-crd#target", "kind": "section", "title": "Pipeline CRD", "heading": "Target", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#target", "summary": "The pipeline target names the upstream namespace where gateway-managed document, chunk, and vector state is written.", "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", "pipeline", "names", "upstream", "namespace", "gateway", "managed", "document", "chunk", "vector", "state", "written", "spec", "turbopuffer", "writes", "owns", "chunks" ] }, { "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 matching Warehouse and receive resolved connection metadata plus a separately mounted credential. They can use stock source workers by default or an explicitly supplied custom image.", "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", "matching", "receive", "resolved", "connection", "metadata", "plus", "separately", "mounted", "credential", "stock", "source", "workers", "default", "explicitly", "supplied", "custom", "image", "snowflake", "huggingface", "rest", "kind", "warehouseref", "hevlayer", "spec", "worker", "acct", "east", "amazonaws", "backed", "kinds", "selects", "shape", "operator", "validates" ] }, { "id": "kubernetes/pipeline-crd#worker", "kind": "section", "title": "Pipeline CRD", "heading": "Worker", "group": "Operations", "url": "/docs/kubernetes/pipeline-crd#worker", "summary": "A pipeline worker declares its image, compute class, batch and timeout settings, and optional pod customization. The operator injects queue identity, target, source, scheduling, warehouse, gateway, and credential context as appropriate.", "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", "declares", "image", "compute", "class", "batch", "timeout", "settings", "optional", "customization", "operator", "injects", "queue", "identity", "target", "source", "scheduling", "warehouse", "gateway", "credential", "context", "appropriate", "computeclass", "scaling", "pool", "batchsize", "timeoutseconds", "podspec", "hevlayer", "spec", "pipelineid", "namespace", "base", "sourceref", "schedule", "layer", "derivefromstore", "vectorstore", "keys" ] }, { "id": "kubernetes/scaling-crd", "kind": "section", "title": "InfraRules CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/scaling-crd", "summary": "InfraRules is the single cluster-wide policy for Layer compute pools, document caching, and scaling constraints. Pipelines and Functions select these pools through their inline scaling configuration.", "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": [ "infrarules", "single", "cluster", "wide", "policy", "layer", "compute", "pools", "document", "caching", "scaling", "constraints", "pipelines", "functions", "select", "these", "through", "their", "inline", "configuration", "default", "spec", "computepools", "cache", "rules", "workload", "scoped", "object", "managed", "runtime", "infrastructure", "there", "exactly", "reference", "separate", "autoscaling", "resource", "choose", "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 define workload class, scheduling constraints, resource envelopes, and per-workload replica ceilings. Unknown pools or replica requests above the ceiling keep a workload unready.", "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", "define", "workload", "class", "scheduling", "constraints", "resource", "envelopes", "replica", "ceilings", "unknown", "requests", "above", "ceiling", "keep", "unready", "large", "layer", "node", "role", "worker", "nvidia", "nodeselector", "gputype", "operator", "infrarules", "computepools", "name", "spec", "scaling", "pool", "kind", "tolerations", "resources", "maxreplicasperworkload", "helm", "defaults", "three", "well" ] }, { "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 records capacity, replication, and node-count intent for operator validation, while the deployment chart currently renders its 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", "records", "capacity", "replication", "node", "count", "intent", "operator", "validation", "while", "deployment", "chart", "currently", "renders", "autoscaler", "directly", "documentcache", "infrarules", "captures", "owned", "settings", "factor", "helm", "still", "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 contains the default CPU, larger-ephemeral-storage CPU, and GPU pools plus document-cache scaling policy. The operator validates its required singleton identity.", "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", "contains", "default", "larger", "ephemeral", "storage", "pools", "plus", "document", "cache", "scaling", "policy", "operator", "validates", "required", "identity", "create", "true", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "spec", "computepools", "nodeselector", "layer", "node", "role", "worker", "compute", "tolerations", "equal", "value", "effect", "noschedule" ] }, { "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 return to the minimum replica count and asks the node autoscaler not to disrupt worker pods during that interval. It is valid only for autoscaling and is designed to reduce repeated cold starts before eventually returning 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", "return", "minimum", "replica", "count", "asks", "node", "autoscaler", "disrupt", "worker", "pods", "during", "interval", "valid", "only", "autoscaling", "designed", "reduce", "repeated", "cold", "starts", "before", "eventually", "returning", "zero", "warmwindowseconds", "scaledobject", "cooldownperiod", "replicas", "karpenter", "mode", "autoscale", "maps", "keda", "operator", "waits", "long", "after" ] }, { "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 choose a compute pool and an autoscaled, fixed, or disabled replica policy, with bounds limited by the pool. Pausing always scales to zero, while a positive minimum keeps expensive workers continuously warm.", "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", "choose", "compute", "pool", "autoscaled", "fixed", "disabled", "replica", "policy", "bounds", "limited", "pausing", "always", "scales", "zero", "while", "positive", "minimum", "keeps", "expensive", "workers", "continuously", "warm", "mode", "autoscale", "warmwindowseconds", "replicas", "scaledobject", "infrarules", "default", "spec", "computepools", "worker", "computeclass", "maxreplicasperworkload", "behavior", "emit", "keda" ] }, { "id": "kubernetes/vectorstore-crd", "kind": "section", "title": "VectorStore CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd", "summary": "A VectorStore declares an upstream engine connection, its Secret-backed credential, and the inbound authentication policy for gateway clients. Each Index either selects a store or uses the default.", "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", "declares", "upstream", "engine", "connection", "secret", "backed", "credential", "inbound", "authentication", "policy", "gateway", "clients", "index", "either", "selects", "store", "uses", "default", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "turbopuffer", "namespace", "layer", "spec", "true", "endpoint", "https", "east", "region", "orgid", "secretref", "inboundauth", "mode", "derivefromstore", "backend" ] }, { "id": "kubernetes/vectorstore-crd#connection", "kind": "section", "title": "VectorStore CRD", "heading": "Connection", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#connection", "summary": "A store specifies its supported backend kind, default status, endpoint, region metadata, and a same-namespace credential reference. Reserved but unimplemented 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", "store", "specifies", "supported", "backend", "kind", "default", "status", "endpoint", "region", "metadata", "same", "namespace", "credential", "reference", "reserved", "unimplemented", "engines", "rejected", "credentials", "never", "live", "resource", "itself", "turbopuffer", "pinecone", "index", "spec", "storeref", "orgid", "secretref", "vectorstore", "field", "purpose", "engine", "today", "schema", "operator", "until", "implemented" ] }, { "id": "kubernetes/vectorstore-crd#inbound-auth", "kind": "section", "title": "VectorStore CRD", "heading": "Inbound auth", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#inbound-auth", "summary": "Gateway bearer authentication can derive from the default backend credential, use independent scoped keys, or be explicitly open. Read, write, and administration scopes map to route classes, and minted keys are additionally constrained by store and namespace entitlements.", "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", "gateway", "bearer", "authentication", "derive", "default", "backend", "credential", "independent", "scoped", "keys", "explicitly", "open", "read", "write", "administration", "scopes", "route", "classes", "minted", "additionally", "constrained", "store", "namespace", "entitlements", "spec", "inboundauth", "mode", "name", "shop", "secretref", "layer", "derivefromstore", "admin", "authorization", "apikey", "vectorstore", "controls", "token" ] }, { "id": "kubernetes/vectorstore-crd#routing", "kind": "section", "title": "VectorStore CRD", "heading": "Routing", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#routing", "summary": "The gateway creates one client per declared store and routes indexed namespaces through their selected backend, with all others using the default. Duplicate index mappings to one upstream namespace are forbidden.", "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", "creates", "client", "declared", "store", "routes", "indexed", "namespaces", "through", "their", "selected", "backend", "others", "default", "duplicate", "index", "mappings", "upstream", "namespace", "forbidden", "vectorstore", "spec", "storeref", "builds", "requests", "whose", "other", "objects", "cannot", "resolve", "same" ] }, { "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 load the same store resource schema from configuration and resolve Secret references through environment values. This keeps Docker and bare-binary setups portable to Kubernetes without reshaping the model.", "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", "load", "same", "store", "resource", "schema", "configuration", "resolve", "secret", "references", "through", "environment", "values", "keeps", "docker", "bare", "binary", "setups", "portable", "kubernetes", "without", "reshaping", "model", "apiversion", "hevlayer", "v1alpha1", "kind", "vectorstore", "metadata", "name", "turbopuffer", "default", "spec", "true", "endpoint", "https", "region", "east" ] }, { "id": "kubernetes/vectorstore-crd#status", "kind": "section", "title": "VectorStore CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/vectorstore-crd#status", "summary": "Store readiness requires valid Secret references and a successful namespace probe against the configured endpoint.", "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", "store", "readiness", "requires", "valid", "secret", "references", "successful", "namespace", "probe", "against", "configured", "endpoint", "reachable", "ready", "namespaces", "operator", "sets", "condition", "after", "validating", "probing" ] }, { "id": "kubernetes/warehouse-crd", "kind": "section", "title": "Warehouse CRD", "heading": null, "group": "Operations", "url": "/docs/kubernetes/warehouse-crd", "summary": "A Warehouse declares a verified external system of record and the credential needed for pipeline extraction. It is distinct from the serving-side vector store, and Layer data is expected to be reconstructible from it.", "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", "declares", "verified", "external", "system", "record", "credential", "needed", "pipeline", "extraction", "distinct", "serving", "side", "vector", "store", "layer", "data", "expected", "reconstructible", "vectorstore", "declared", "upstream", "source", "identity", "reachability", "pipelines", "extract", "rows", "plus", "shape", "reach", "derived", "opposite", "sides", "gateway" ] }, { "id": "kubernetes/warehouse-crd#connection", "kind": "section", "title": "Warehouse CRD", "heading": "Connection", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#connection", "summary": "A warehouse chooses one implemented source kind with exactly one matching configuration block and a verification cadence. It describes connection identity rather than a particular table or dataset, allowing one credential to serve many pipeline sources.", "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", "chooses", "implemented", "source", "kind", "exactly", "matching", "configuration", "block", "verification", "cadence", "describes", "identity", "rather", "particular", "table", "dataset", "allowing", "credential", "serve", "many", "pipeline", "sources", "spec", "snowflake", "huggingface", "rest", "databricks", "iceberg", "verifyinterval", "selects", "system", "select", "reserved", "schema", "rejected", "operator", "until", "must" ] }, { "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 key entitlements still depend on it. Operators can explicitly override the safety fence when necessary.", "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", "entitlements", "still", "depend", "operators", "explicitly", "override", "safety", "fence", "necessary", "status", "consumers", "hevlayer", "force", "delete", "true", "deleting", "fences", "everything", "drawing", "finalizer", "blocks", "zero", "extracting", "keys", "entitled", "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 selects a repository, configuration, split, revision, field mapping, and optional chunking under a verified warehouse connection. Stock workers stream a pinned Parquet revision with stable cursors and separately mounted credentials, preventing datasets from drifting during a run.", "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", "selects", "repository", "configuration", "split", "revision", "field", "mapping", "optional", "chunking", "under", "verified", "warehouse", "connection", "stock", "workers", "stream", "pinned", "parquet", "stable", "cursors", "separately", "mounted", "credentials", "preventing", "datasets", "drifting", "during", "spec", "sourceref", "kind", "huggingface", "warehouseref", "repo", "mcauley", "amazon", "reviews" ] }, { "id": "kubernetes/warehouse-crd#keys", "kind": "section", "title": "Warehouse CRD", "heading": "Keys", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#keys", "summary": "A warehouse entitlement stores opaque claims for an external application but grants no direct Layer route. It becomes inert if the warehouse is removed.", "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", "entitlement", "stores", "opaque", "claims", "external", "application", "grants", "direct", "layer", "route", "becomes", "inert", "removed", "apikey", "name", "binds", "carrying", "list", "strings", "echoes", "routes", "client", "reaches", "source", "system", "clients", "touch", "indexes", "warehouses", "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 keeps connection identity and credentials on the Warehouse while its source block specifies the data selection and cursor. The operator requires a verified same-kind warehouse and passes source configuration unchanged 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", "keeps", "connection", "identity", "credentials", "while", "block", "specifies", "data", "selection", "cursor", "operator", "requires", "verified", "same", "kind", "passes", "configuration", "unchanged", "worker", "spec", "sourceref", "warehouseref", "hevlayer", "extracting", "names", "owns", "snowflake", "database", "query", "hugging", "face", "dataset", "split", "field", "mapping", "name" ] }, { "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 defines path, static query, offset pagination, item selection, cursor, and field mapping for a JSON API. A stock worker can page compatible APIs, while chunking can split whole documents or structured sections before indexing.", "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", "defines", "path", "static", "query", "offset", "pagination", "item", "selection", "cursor", "field", "mapping", "json", "stock", "worker", "page", "compatible", "apis", "while", "chunking", "split", "whole", "documents", "structured", "sections", "before", "indexing", "request", "baseurl", "kind", "pagesizeparam", "offsetparam", "pagesize", "searchafter", "link", "response", "items" ] }, { "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 header or query credential, optional client pacing, and a verification request. Endpoint-specific pagination and mapping remain on each pipeline source so one connection can support multiple 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", "header", "query", "credential", "client", "pacing", "verification", "request", "endpoint", "specific", "pagination", "mapping", "remain", "pipeline", "source", "connection", "support", "multiple", "paths", "auth", "verified", "baseurl", "path", "name", "secretref", "token", "ratelimit", "requestspersecond", "verify", "secret", "declares", "many", "public", "apis" ] }, { "id": "kubernetes/warehouse-crd#rotation", "kind": "section", "title": "Warehouse CRD", "heading": "Rotation", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#rotation", "summary": "Credential rotation replaces Secret contents or changes the referenced Secret, triggering re-verification. New connections resolve the latest material without requiring worker redeployment, including transitions between anonymous and authenticated dataset access.", "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", "replaces", "secret", "contents", "changes", "referenced", "triggering", "verification", "connections", "resolve", "latest", "material", "without", "requiring", "worker", "redeployment", "including", "transitions", "between", "anonymous", "authenticated", "dataset", "access", "status", "verifiedat", "keypairsecretref", "tokensecretref", "huggingface", "swap", "content", "operator", "verifies", "advances", "consumers", "credentials", "through", "warehouse", "connection", "build" ] }, { "id": "kubernetes/warehouse-crd#snowflake", "kind": "section", "title": "Warehouse CRD", "heading": "Snowflake", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#snowflake", "summary": "Warehouse configuration supports implemented database, dataset-hub, and HTTP-source kinds while reserving others for later. Snowflake uses a Secret-backed key pair and connection-pool settings; dataset hubs may be public or token-gated, and catalog selection belongs to pipelines.", "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", "warehouse", "configuration", "supports", "implemented", "database", "dataset", "http", "source", "kinds", "while", "reserving", "others", "later", "uses", "secret", "backed", "pair", "connection", "pool", "settings", "hubs", "public", "token", "gated", "catalog", "selection", "belongs", "pipelines", "kind", "huggingface", "rest", "databricks", "iceberg", "account", "user", "role", "keypairsecretref", "private", "passphrase" ] }, { "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 provides its database query and cursor separately from the Warehouse connection. The operator mounts key material and injects non-secret connection metadata so the worker can establish the session.", "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", "provides", "database", "query", "cursor", "separately", "warehouse", "connection", "operator", "mounts", "material", "injects", "secret", "metadata", "worker", "establish", "session", "spec", "sourceref", "kind", "warehouseref", "prod", "analytics", "select", "title", "body", "refresh", "public", "notes", "column", "hevlayer", "refreshid", "pair", "hevlayerwarehouse", "json", "resolved", "account", "user" ] }, { "id": "kubernetes/warehouse-crd#status", "kind": "section", "title": "Warehouse CRD", "heading": "Status", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#status", "summary": "Warehouse status reports verification phase and time, failure details, resolved source revisions, and counts of consuming pipelines and keys. Phase changes also emit 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", "reports", "verification", "phase", "time", "failure", "details", "resolved", "source", "revisions", "counts", "consuming", "pipelines", "keys", "changes", "also", "emit", "cluster", "events", "verified", "verifiedat", "2026", "10t00", "failurereason", "null", "sourcerevisions", "mcauley", "amazon", "reviews", "2023", "main", "2b6d039ed471f2ba5fd2acb718bf33b0a7e5598e", "consumers", "apikeys", "operator", "emits", "kubernetes", "transitions", "observed" ] }, { "id": "kubernetes/warehouse-crd#supported-warehouses", "kind": "section", "title": "Warehouse CRD", "heading": "Supported Warehouses", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#supported-warehouses", "summary": "Shipped warehouse kinds cover Snowflake, Hugging Face datasets, and paginated JSON APIs, with other kinds reserved but rejected. Credentials are optional where the source is public and always referenced through Secrets when present.", "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", "shipped", "warehouse", "kinds", "cover", "snowflake", "hugging", "face", "datasets", "paginated", "json", "apis", "other", "reserved", "rejected", "credentials", "optional", "source", "public", "always", "referenced", "through", "secrets", "present", "apiversion", "hevlayer", "v1alpha1", "kind", "metadata", "name", "prod", "namespace", "layer", "spec", "account", "acme", "xy12345", "user", "role" ] }, { "id": "kubernetes/warehouse-crd#verification", "kind": "section", "title": "Warehouse CRD", "heading": "Verification", "group": "Operations", "url": "/docs/kubernetes/warehouse-crd#verification", "summary": "The operator probes each warehouse on creation, credential change, and its configured cadence, using source-appropriate connectivity checks. Only verified warehouses start new pipelines; a later failed probe is visible and blocks new runs without terminating existing connections.", "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", "creation", "credential", "change", "configured", "cadence", "source", "appropriate", "connectivity", "checks", "only", "verified", "warehouses", "start", "pipelines", "later", "failed", "probe", "visible", "blocks", "runs", "without", "terminating", "existing", "connections", "verifyinterval", "snowflake", "select", "huggingface", "repo", "revision", "status", "sourcerevisions", "rest", "verify", "path", "query" ] }, { "id": "licensing", "kind": "section", "title": "Licensing", "heading": null, "group": "Overview", "url": "/docs/licensing", "summary": "Layer licensing is per environment and uses the same signed-key installation flow for trials, design partners, and production. Each component evaluates the locally installed key and exposes its current state for monitoring.", "facts": [], "sources": [ { "chunkId": "licensing", "url": "/docs/licensing", "anchor": null } ], "mode": "agent-primary", "terms": [ "layer", "licensing", "environment", "uses", "same", "signed", "installation", "flow", "trials", "design", "partners", "production", "component", "evaluates", "locally", "installed", "exposes", "current", "state", "monitoring", "install", "monitor", "trial", "commercial", "license", "licensed", "partner", "installs", "path", "sign", "receive", "email", "helm", "gateway", "local" ] }, { "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 and provide straightforward access to the public API from applications.", "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", "provide", "straightforward", "access", "public", "applications", "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 acceptance workflow provisions a disposable cluster, obtains and installs a trial key, checks local license projection, and optionally verifies telemetry. Trials and unlicensed installs receive no post-expiration grace, while commercial grace is measured from a genuine expiration.", "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", "acceptance", "workflow", "provisions", "disposable", "cluster", "obtains", "installs", "trial", "checks", "local", "license", "projection", "optionally", "verifies", "telemetry", "trials", "unlicensed", "receive", "post", "expiration", "grace", "while", "commercial", "measured", "genuine", "scripts", "real", "infra", "helm", "layer", "token", "full", "fidelity", "scripted", "script", "uses", "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 identity, while hosted-service terms and privacy policy govern operated services and their data handling. Self-hosting remains governed by the gateway license and 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", "identity", "while", "hosted", "service", "privacy", "govern", "operated", "services", "their", "data", "handling", "self", "hosting", "remains", "governed", "gateway", "license", "rules", "trademarks", "github", "hevlayer", "document", "brand", "layer", "names", "marks", "including", "acceptable", "billing", "liability", "support", "site", "telemetry" ] }, { "id": "licensing#install-the-key", "kind": "section", "title": "Licensing", "heading": "Install the Key", "group": "Overview", "url": "/docs/licensing#install-the-key", "summary": "A Helm installation can receive the emailed license directly or reference a pre-created Secret managed by the operator's normal secret workflow.", "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", "helm", "installation", "receive", "emailed", "license", "directly", "reference", "created", "secret", "managed", "operator", "normal", "workflow", "upgrade", "layer", "infra", "namespace", "create", "token", "hevlayer", "values", "customer", "yaml", "existingsecret", "secretkey", "installs", "pass", "hevlayerlicense", "cluster", "policy", "requires", "kubernetes", "secrets", "through", "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 and carries subject, tier, feature, limit, issuance, and expiration claims. Licensed product surfaces require both a valid deployment entitlement and caller authorization, while core reads, writes, scans, metadata, snapshots, and routing remain available at every license level.", "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", "carries", "subject", "tier", "feature", "limit", "issuance", "expiration", "licensed", "product", "surfaces", "require", "both", "valid", "deployment", "entitlement", "caller", "authorization", "while", "core", "reads", "writes", "scans", "metadata", "snapshots", "routing", "remain", "available", "every", "level", "public", "features", "limits", "transform", "runtime", "agents" ] }, { "id": "licensing#license-states", "kind": "section", "title": "Licensing", "heading": "License States", "group": "Overview", "url": "/docs/licensing#license-states", "summary": "Local license evaluation projects licensed, commercial-grace, or community-floor behavior. Trials never enter grace, and the status surface reports validity, identity, entitlements, expiration, and the active projection shared by gateway, operator, and dashboard.", "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", "local", "evaluation", "projects", "licensed", "commercial", "grace", "community", "floor", "behavior", "trials", "never", "enter", "status", "surface", "reports", "validity", "identity", "entitlements", "expiration", "active", "projection", "shared", "gateway", "operator", "dashboard", "curl", "authorization", "bearer", "layer", "https", "host", "evaluates", "state", "locally", "configured", "does", "require", "network" ] }, { "id": "licensing#metrics", "kind": "section", "title": "Licensing", "heading": "Metrics", "group": "Overview", "url": "/docs/licensing#metrics", "summary": "Metrics expose key validity, time to expiration, remaining grace, degraded floor state, and requests served during grace, labeled by license identity and surface. These support alerts before expiry and immediate detection of grace or degradation.", "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", "expose", "validity", "time", "expiration", "remaining", "grace", "degraded", "floor", "state", "requests", "served", "during", "labeled", "license", "identity", "surface", "these", "support", "alerts", "before", "expiry", "immediate", "detection", "degradation", "tier", "gateway", "hevlayer", "valid", "seconds", "total", "health", "exported", "uses", "licensetier", "licensesub", "labels", "also", "include", "phase" ] }, { "id": "licensing#renewals", "kind": "section", "title": "Licensing", "heading": "Renewals", "group": "Overview", "url": "/docs/licensing#renewals", "summary": "Renewal replaces the installed key through Helm or its referenced Secret, followed by a gateway rollout so the new entitlement is loaded.", "facts": [], "sources": [ { "chunkId": "licensing#renewals", "url": "/docs/licensing#renewals", "anchor": "renewals" } ], "mode": "agent-primary", "terms": [ "renewals", "renewal", "replaces", "installed", "through", "helm", "referenced", "secret", "followed", "gateway", "rollout", "entitlement", "loaded", "trial", "commercial", "license", "close", "expiration", "request", "layer", "contact", "reply", "email", "replace", "roll", "release", "reads", "value" ] }, { "id": "licensing#start-a-trial", "kind": "section", "title": "Licensing", "heading": "Start a Trial", "group": "Overview", "url": "/docs/licensing#start-a-trial", "summary": "Trial signup emails a signed deployment key that should be protected as a secret. Licensed self-hosted images require a valid key; otherwise gated routes and control surfaces fall back to community behavior.", "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", "emails", "signed", "deployment", "should", "protected", "secret", "licensed", "self", "hosted", "images", "require", "valid", "otherwise", "gated", "routes", "control", "surfaces", "fall", "back", "community", "behavior", "hevlayer", "layer", "gateway", "version", "operator", "dashboard", "site", "submit", "email", "address", "want", "associated", "install", "current", "instructions", "only" ] }, { "id": "limits", "kind": "section", "title": "Limits", "heading": null, "group": "Overview", "url": "/docs/limits", "summary": "Current enforced ceilings come primarily from bundled storage constraints and bounded in-memory aggregation. They include cache topology and size, namespace count, and facet or value cardinality, with truncation reported explicitly where supported.", "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", "enforced", "ceilings", "come", "primarily", "bundled", "storage", "constraints", "bounded", "memory", "aggregation", "include", "cache", "topology", "size", "namespace", "count", "facet", "value", "cardinality", "truncation", "reported", "explicitly", "supported", "fields", "skipped", "truncated", "true", "inherited", "components", "ship", "layer", "limited", "certain", "underlying", "lift", "these", "demand", "increases", "single" ] }, { "id": "limits#no-limits", "kind": "section", "title": "Limits", "heading": "No limits", "group": "Overview", "url": "/docs/limits#no-limits", "summary": "Some resources and histories have no Layer-enforced cap but remain bounded by cluster throughput, object-storage cost, autoscaling capacity, queue backing stores, or upstream record limits. Operators must plan retention and capacity even when the product does not impose a numeric ceiling.", "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", "some", "resources", "histories", "layer", "enforced", "remain", "bounded", "cluster", "throughput", "object", "storage", "cost", "autoscaling", "capacity", "queue", "backing", "stores", "upstream", "record", "operators", "must", "plan", "retention", "even", "product", "does", "impose", "numeric", "ceiling", "index", "function", "pipeline", "scaling", "spec", "snapshot", "never", "these", "practical", "exist" ] }, { "id": "quickstart", "kind": "section", "title": "Quickstart", "heading": null, "group": "Operations", "url": "/docs/quickstart", "summary": "The community gateway can run locally in front of an existing Turbopuffer account without signup or a license. The backend key doubles as the gateway bearer, and existing data remains in the upstream service.", "facts": [ { "kind": "code", "literal": "curl", "chunkId": "quickstart" } ], "sources": [ { "chunkId": "quickstart", "url": "/docs/quickstart", "anchor": null } ], "mode": "agent-primary", "terms": [ "community", "gateway", "locally", "front", "existing", "turbopuffer", "account", "without", "signup", "license", "backend", "doubles", "bearer", "data", "remains", "upstream", "service", "curl", "clone", "repo", "docker", "compose", "initialize", "namespace", "query", "needed", "token", "stays", "need", "rows" ] }, { "id": "quickstart#1-clone-the-repo", "kind": "section", "title": "Quickstart", "heading": "1. Clone the repo", "group": "Operations", "url": "/docs/quickstart#1-clone-the-repo", "summary": "Begin the local community setup by obtaining the public Layer source repository and entering its working directory.", "facts": [ { "kind": "code", "literal": "git clone https://github.com/hev/layer.git\ncd layer", "chunkId": "quickstart#1-clone-the-repo" } ], "sources": [ { "chunkId": "quickstart#1-clone-the-repo", "url": "/docs/quickstart#1-clone-the-repo", "anchor": "1-clone-the-repo" } ], "mode": "agent-primary", "terms": [ "clone", "repo", "begin", "local", "community", "setup", "obtaining", "public", "layer", "source", "repository", "entering", "working", "directory", "https", "github" ] }, { "id": "quickstart#2-configure-and-start-the-gateway", "kind": "section", "title": "Quickstart", "heading": "2. Configure and start the gateway", "group": "Operations", "url": "/docs/quickstart#2-configure-and-start-the-gateway", "summary": "Configure the backend credential in the example environment, start the Compose stack, and confirm the gateway health endpoint before continuing.", "facts": [ { "kind": "code", "literal": "cp .env.example .env\n# edit .env and set TURBOPUFFER_API_KEY=tpuf_...", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "docker compose up", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "curl http://localhost:8080/health", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "export TURBOPUFFER_API_KEY=\"tpuf_...\"\nexport LAYER_NAMESPACE=\"products\"\nexport LAYER_GATEWAY_URL=\"http://localhost:8080\"", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "docker-compose.yml", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "hevlayer/layer-gateway", "chunkId": "quickstart#2-configure-and-start-the-gateway" }, { "kind": "code", "literal": "api.turbopuffer.com", "chunkId": "quickstart#2-configure-and-start-the-gateway" } ], "sources": [ { "chunkId": "quickstart#2-configure-and-start-the-gateway", "url": "/docs/quickstart#2-configure-and-start-the-gateway", "anchor": "2-configure-and-start-the-gateway" } ], "mode": "agent-primary", "terms": [ "configure", "start", "gateway", "backend", "credential", "example", "environment", "compose", "stack", "confirm", "health", "endpoint", "before", "continuing", "edit", "turbopuffer", "tpuf", "docker", "curl", "http", "localhost", "8080", "export", "layer", "namespace", "products", "hevlayer", "copy", "file", "fill", "turbopufferapikey", "bundled", "runs", "image", "against", "restart", "policy", "check", "another", "shell" ] }, { "id": "quickstart#3-initialize-the-namespace", "kind": "section", "title": "Quickstart", "heading": "3. Initialize the namespace", "group": "Operations", "url": "/docs/quickstart#3-initialize-the-namespace", "summary": "Namespace initialization backfills Layer's reserved shard metadata over existing rows without interrupting queries. The operation is idempotent, self-throttled, and exposes readiness through namespace metadata.", "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#3-initialize-the-namespace" }, { "kind": "code", "literal": "init_state", "chunkId": "quickstart#3-initialize-the-namespace" }, { "kind": "code", "literal": "ready", "chunkId": "quickstart#3-initialize-the-namespace" }, { "kind": "code", "literal": "GET /v2/namespaces/$LAYER_NAMESPACE/metadata", "chunkId": "quickstart#3-initialize-the-namespace" } ], "sources": [ { "chunkId": "quickstart#3-initialize-the-namespace", "url": "/docs/quickstart#3-initialize-the-namespace", "anchor": "3-initialize-the-namespace" } ], "mode": "agent-primary", "terms": [ "initialize", "namespace", "initialization", "backfills", "layer", "reserved", "shard", "metadata", "existing", "rows", "without", "interrupting", "queries", "operation", "idempotent", "self", "throttled", "exposes", "readiness", "through", "curl", "post", "gateway", "namespaces", "init", "authorization", "bearer", "turbopuffer", "content", "type", "application", "json", "schema", "version", "count", "state", "ready", "layergatewayurl", "layernamespace", "turbopufferapikey" ] }, { "id": "quickstart#4-run-a-query", "kind": "section", "title": "Quickstart", "heading": "4. Run a query", "group": "Operations", "url": "/docs/quickstart#4-run-a-query", "summary": "Send a compatible text-ranking request through the gateway using the backend credential. The same surface then supports richer routing, hybrid retrieval, and scatter-gather scans.", "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#4-run-a-query" } ], "sources": [ { "chunkId": "quickstart#4-run-a-query", "url": "/docs/quickstart#4-run-a-query", "anchor": "4-run-a-query" } ], "mode": "agent-primary", "terms": [ "query", "send", "compatible", "text", "ranking", "request", "through", "gateway", "backend", "credential", "same", "surface", "supports", "richer", "routing", "hybrid", "retrieval", "scatter", "gather", "scans", "curl", "post", "layer", "namespaces", "namespace", "authorization", "bearer", "turbopuffer", "content", "type", "application", "json", "rank", "title", "bm25", "wireless", "earbuds", "layergatewayurl", "layernamespace", "turbopufferapikey" ] }, { "id": "roadmap", "kind": "section", "title": "Changelog", "heading": null, "group": "Overview", "url": "/docs/roadmap", "summary": "The roadmap summarizes shipped Layer capabilities and the remaining work toward a polished major release.", "facts": [ { "kind": "value", "literal": "FeatureGate.astro", "chunkId": "roadmap" } ], "sources": [ { "chunkId": "roadmap", "url": "/docs/roadmap", "anchor": null } ], "mode": "agent-primary", "terms": [ "roadmap", "summarizes", "shipped", "layer", "capabilities", "remaining", "work", "toward", "polished", "major", "release", "featuregate", "astro", "coming", "next" ] }, { "id": "roadmap#04", "kind": "section", "title": "Changelog", "heading": "0.4", "group": "Overview", "url": "/docs/roadmap#04", "summary": "The roadmap groups the current delivery milestone under version 0.4.", "facts": [ { "kind": "value", "literal": "0.4", "chunkId": "roadmap#04" } ], "sources": [ { "chunkId": "roadmap#04", "url": "/docs/roadmap#04", "anchor": "04" } ], "mode": "agent-primary", "terms": [ "roadmap", "groups", "current", "delivery", "milestone", "under", "version" ] }, { "id": "roadmap#api-hardening", "kind": "section", "title": "Changelog", "heading": "API hardening", "group": "Overview", "url": "/docs/roadmap#api-hardening", "summary": "API hardening focuses on finalizing resource schemas, preserving compatible reads and writes, and stabilizing naming.", "facts": [], "sources": [ { "chunkId": "roadmap#api-hardening", "url": "/docs/roadmap#api-hardening", "anchor": "api-hardening" } ], "mode": "agent-primary", "terms": [ "hardening", "focuses", "finalizing", "resource", "schemas", "preserving", "compatible", "reads", "writes", "stabilizing", "naming", "finalize", "crds", "wire", "pass", "through", "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 covers compute autoscaling, document caching, snapshot history, coordinated deletion, installation tooling, scoped keys, licensing, audits, warehouse sources, and production cutover.", "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", "covers", "compute", "autoscaling", "document", "caching", "snapshot", "history", "coordinated", "deletion", "installation", "tooling", "scoped", "keys", "licensing", "audits", "warehouse", "sources", "production", "cutover", "apikey", "pipelines", "udfs", "cache", "endpoint", "multi", "stage", "index", "delete", "helm", "terraform", "install", "scripts", "minted", "resources", "license", "validation", "audit" ] }, { "id": "roadmap#polish", "kind": "section", "title": "Changelog", "heading": "Polish", "group": "Overview", "url": "/docs/roadmap#polish", "summary": "Remaining release polish centers on documentation, cost acceptance testing, and dashboard acceptance testing.", "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", "release", "centers", "documentation", "cost", "acceptance", "testing", "dashboard", "stands", "between", "today" ] }, { "id": "roadmap#search", "kind": "section", "title": "Changelog", "heading": "Search", "group": "Overview", "url": "/docs/roadmap#search", "summary": "Search work spans stable and temporal reads, readiness, snapshot facets, scans, document-cached lookup, hybrid fusion, automatic and agentic routing, history, trends, and richer 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", "spans", "stable", "temporal", "reads", "readiness", "snapshot", "facets", "scans", "document", "cached", "lookup", "hybrid", "fusion", "automatic", "agentic", "routing", "history", "trends", "richer", "metadata", "between", "text", "auto", "agent", "during", "heavy", "writes", "queries", "asof", "selector", "ready", "signal", "namespace", "reports", "every", "indexed", "precomputed", "facet" ] }, { "id": "roadmap#surfaces", "kind": "section", "title": "Changelog", "heading": "Surfaces", "group": "Overview", "url": "/docs/roadmap#surfaces", "summary": "User-facing surfaces include the operations dashboard, 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", "user", "facing", "include", "operations", "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-on work includes more storage backends, declarative ingestion with typed sources and chunking, published performance benchmarks, and index variants for experimentation.", "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", "more", "storage", "backends", "declarative", "ingestion", "typed", "sources", "chunking", "published", "performance", "benchmarks", "index", "variants", "experimentation", "vectorstore", "pipeline", "hugging", "face", "worker", "code", "pass", "through", "overhead", "variant", "indexes" ] }, { "id": "tradeoffs", "kind": "section", "title": "Tradeoffs", "heading": null, "group": "Overview", "url": "/docs/tradeoffs", "summary": "Layer deliberately adds a network hop and per-request planning and authorization checks to gain stable reads and governed search. Turbopuffer-backed namespaces also carry additional indexes for write-time filtering and scatter-gather sharding.", "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", "request", "planning", "authorization", "checks", "gain", "stable", "reads", "governed", "search", "turbopuffer", "backed", "namespaces", "also", "carry", "additional", "indexes", "write", "time", "filtering", "scatter", "gather", "sharding", "muted", "signal", "current", "product", "posture", "cases", "trying", "cover", "makes", "design", "tradeoffs", "believe", "improve", "functionality" ] } ], "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. 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. ## 1. Clone the repo ```sh git clone https://github.com/hev/layer.git cd layer ``` ## 2. Configure and start the gateway Copy the example env file and fill in your turbopuffer API key: ```sh cp .env.example .env # edit .env and set TURBOPUFFER_API_KEY=tpuf_... ``` Then start the gateway: ```sh docker compose up ``` The bundled `docker-compose.yml` runs the `hevlayer/layer-gateway` image against `api.turbopuffer.com` with a restart policy and health check. Check it in another shell: ```sh curl http://localhost:8080/health ``` The rest of the steps use these in your shell: ```sh export TURBOPUFFER_API_KEY="tpuf_..." export LAYER_NAMESPACE="products" export LAYER_GATEWAY_URL="http://localhost:8080" ``` ## 3. 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`. ## 4. 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. ## Guided CLI install The fast path is the CLI wizard. Clone the `hev/layer` repository — it carries the Terraform configuration, the Helm chart, and the install script the wizard drives — and run `layer install aws` from the checkout: ```sh git clone https://github.com/hev/layer cd layer go build -o layer ./apps/layer-cli ./layer install aws ``` The wizard asks for the AWS profile, the region, the base node instance type for the always-on system node (default `i4i.large`), and the upstream Turbopuffer API key, then runs both stages in one shot: Terraform provisions the opinionated AWS footprint — VPC, EKS, IAM/IRSA, S3, ECR — and Helm installs the release wired to those outputs. It confirms the resolved plan before provisioning; `--dry-run` prints the plan without touching AWS. See [the CLI reference](/docs/cli/#install-an-aws-environment) for every flag and the non-interactive form. ## One-script install The same two stages also run non-interactively from one script, driven entirely by environment variables: ```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 a `hev/layer` checkout (`git clone https://github.com/hev/layer`; set `LAYER_SRC` to it when running the script from another directory). Useful knobs: `AWS_REGION` (default `us-east-1`), `CLUSTER_NAME` (default `layer`), `NAMESPACE` (default `layer`), `HELM_RELEASE` (default `layer`), `LAYER_VERSION` (default `latest`), `SYSTEM_NODE_INSTANCE_TYPE` (default `i4i.large`), 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`). `spec.embedding` declares an already-computed embedding's identity for comparison purposes; it does not compute anything. To have the gateway compute vectors for you, declare `embed:` on a schema attribute instead — see below. ## Schema-attribute embedding A schema attribute can declare `embed:` so its source value is embedded on write. This is Turbopuffer's native-embeddings wire (`embed` on a schema attribute, private beta at [turbopuffer.com/docs/embedding](https://turbopuffer.com/docs/embedding)). With native serving on a Turbopuffer store, Layer validates and transparently forwards the wire to Turbopuffer's managed embedding service. Autoscaler serving and the hev search fallback use that same service through the gateway, then write only concrete derived vectors to the active store. ```jsonc // simple form — tpuf-compatible "schema": { "text": { "type": "string", "embed": "voyage/voyage-4-lite" } } // extended form "schema": { "text": { "type": "string", "embed": { "model": "Snowflake/snowflake-arctic-embed-m-v1.5", "revision": "refs/pr/5", "dims": 768, "attribute": "text_vector", "instructions": { "document": "Represent this passage for retrieval: ", "query": "Represent this query for retrieving passages: " }, "chunk": { "strategy": "recursive", "unit": "characters", "size": 1200, "overlap": 120 }, "serving": { "prefer": "autoscaler" } } } } ``` | Field | tpuf-compatible | Purpose | | --- | --- | --- | | `embed` (string) | ✅ | Simple form. A provider-namespaced model id such as `voyage/voyage-4-lite`. | | `embed.model` | ✅ | Extended form's provider-namespaced model id. | | `embed.dims` | ✅ | Output dimensionality via Matryoshka truncation. | | `embed.attribute` | ✅ | Override the derived vector attribute name. Omitting it derives `embed_`. | | `embed.serving.prefer` | Layer extension | `native`, `autoscaler`, or `blended`. Defaults to `native`. Layer consumes this field before forwarding the native wire. | | `embed.revision` | Layer extension | Pin a Hugging Face model revision. It participates in profile identity and cache keys. | | `embed.instructions` | Layer extension | Optional `document` and `query` prefixes for asymmetric embedding models. | | `embed.modality` | Layer extension | `text` (default) or `image`. Image values are URLs or base64 strings for a CLIP-family checkpoint; query-time `Embed` still uses its text tower. | | `embed.chunk` | Layer extension | Split or fan out the source before embedding. See [Chunking](#chunking). | Layer extensions require `prefer: autoscaler` or `prefer: blended`; native serving rejects them with `422`. The gateway consumes every extension field and sends only concrete vectors to the active store. A missing production embedding provider returns `503 service_unavailable`. The first row write that establishes an embedded schema must include `distance_metric`. Omitting it returns `422`. The default derived vector column is **`embed_`** — for example, `embed_title` for source attribute `title`. The source attribute is stored alongside the vector. Model ids must be provider-namespaced. The native menu includes the Voyage 4 family, `cohere/embed-v4.0`, `google/gemini-embedding-*`, `qwen/qwen3-embedding-*`, and `baai/bge-m3`. Bare ids such as `voyage-3-lite` are rejected. The autoscaler leg does not apply a gateway model allowlist. It accepts any provider-namespaced Hugging Face repo id that the configured inference provider can serve, including mixed-case ids such as `Snowflake/snowflake-arctic-embed-m-v1.5` and CLIP-family checkpoints. Provider load or model-support failures are returned as upstream embedding errors. ### Chunking For scalar text, `embed.chunk` reuses the Pipeline chunk shape: `strategy` is `none`, `fixed`, `recursive`, `sentence`, or `markdown`; `unit` is `characters` or `tokens`; and `size`, `overlap`, and `tokenizer` control the window. A split document remains as its original row, while each embedded chunk is written as `{id}#{i}` with `_hevlayer_parent_id` and `_hevlayer_chunk_index`. Structured fields use a two-level section composition: ```jsonc "schema": { "text": { "type": "string", "embed": { "model": "BAAI/bge-m3", "chunk": { "strategy": "section", "sectionSource": "jsonFields", "fields": ["boxed_warning", "drug_interactions"], "sectionAttribute": "section", "split": { "strategy": "recursive", "unit": "characters", "size": 1200, "overlap": 120 } }, "serving": { "prefer": "autoscaler" } }} } ``` Each configured non-empty string field on the document row fans out into the embedded attribute first; optional `split` then windows that section. Rows use ids `{id}#{section}#{i}`, retain the document attributes, and add the configured section attribute plus the standard parent/index attributes. Chunked writes require string document ids and `upsert_rows`; columnar writes return `422`. ### Model-serving policy Per model, `embed.serving.prefer` chooses how vectors are computed. | `prefer` | Behavior | | --- | --- | | `native` (default) | On Turbopuffer, transparently forward the compatible wire to tpuf's managed service. On hev search, Layer resolves through its credentialed Turbopuffer provider and sends only concrete vectors to search. | | `autoscaler` | Resolve with Turbopuffer native embeddings through the gateway. The active store never receives `embed:` or `Embed`; writes contain derived vectors and queries contain a concrete ANN vector. | | `blended` | Uses the same provider handoff as `autoscaler`. The traffic-shift policy is independent of the embed wire and does not change request or response shapes. | Layer durably records gateway-served attribute profiles in S3, so later writes do not need to repeat `schema`. Query vectors use a short in-memory TTL cache. When changing an embedded source attribute, upsert the full row; patching that attribute returns `422` because Layer cannot safely recompute a vector from a partial row. For a hev search deployment, configure at least one credentialed `kind: turbopuffer` VectorStore alongside the search store; Layer uses the first one by name as the managed embedding provider. Without one, gateway-served embedding returns `503 service_unavailable`. ## 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 ``` ## Install An AWS Environment `layer install aws` is the guided install: a wizard that collects the AWS profile, region, and base node instance type, then runs both install stages — Terraform (VPC, EKS, IAM/IRSA, S3, ECR) followed by the Helm release — as a single shot. It is an interactive front end for `scripts/install-layer.sh`; the [Install](/docs/install/) page is the reference for every value it sets. The command runs from a `hev/layer` source checkout, which carries the Terraform configuration, the Helm chart, and the install scripts it drives: ```sh git clone https://github.com/hev/layer cd layer go build -o layer ./apps/layer-cli ./layer install aws ``` The wizard prompts for the AWS profile (ambient credentials by default), the region (default `us-east-1`), the base node instance type for the always-on system node (default `i4i.large`; i4i's NVMe instance store backs the serving path and document cache), and the upstream Turbopuffer API key. It prints the resolved plan and asks for confirmation before provisioning anything. | Flag | Environment | Default | | --- | --- | --- | | `--profile` | `AWS_PROFILE` | ambient credentials | | `--region` | `AWS_REGION` | `us-east-1` | | `--cluster-name` | none | `layer` | | `--namespace` | none | `layer` | | `--node-type` | none | `i4i.large` | | `--turbopuffer-api-key` | `TURBOPUFFER_API_KEY` | none (required) | | `--version` | none | `latest` | | `--license-token` | `LICENSE_TOKEN` | none | | `--source` | `LAYER_SRC` | walk up from the working directory | | `--skip-terraform` | none | off | | `--yes` | none | off | | `--dry-run` | none | off | Non-interactive installs (CI, scripts) pass every value as a flag or environment variable and must add `--yes`; without a terminal the command refuses to provision unconfirmed. `--dry-run` prints the resolved environment (secrets masked) and the exact command it would run, then exits. `--skip-terraform` reuses existing Terraform outputs and reruns only the cluster components and the Helm release. ## 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, and index (WAL) and cache state on any gateway. The RECENT SNAPSHOTS table (and `index list`'s last-snapshot column) additionally need snapshot history, which is served only by a managed/pro gateway; timestamps and sizes are raw (epoch-ms, bytes) and `-o json` carries the full snapshot list where available. ## 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. Both work against the free, self-hosted gateway — no operator or license required. ## 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.