Config options
Using Vector is the same ground with the calls; the overview is what the capability is for; pithy vector provisions and reprocesses it.
| Option | Default | Meaning |
|---|---|---|
indexes | — | Each index’s dimensions and its metadata schema |
defaultTopK | 10 | Matches returned when the caller names none. A search page, not a scan |
An index’s metadata schema is where filterable is declared, and that declaration is the capability.
Bindings
| Binding | Type | Written by |
|---|---|---|
AI | ai, remote | pithy add |
DB | d1 | pithy add |
VECTORIZE | vectorize, remote | pithy vector provision |
VECTOR_REPROCESS | workflow, optional | pithy vector provision |
Two are declared remote, because Cloudflare ships no local emulation for either — so --env dev reaches real services and costs real calls.
The index binding cannot be written by add: it needs an index name provisioning mints.
The two hard limits
Ten metadata indexes per index. Choose deliberately; you cannot have them all.
A metadata index created after vectors were written covers none of them, and there is no backfill.
Both are the store’s, not the kit’s. Both fail quietly — a filter on an unindexed field returns partial results with no error — which is why the kit turns them into schema and boot-time concerns.
VECTOR_PROVISIONED
A variable recording exactly what provisioning observed on the live index — every metadata index that was live when it finished, declared and undeclared alike.
The Worker compares its declarations against that record at boot and refuses to serve on drift.
The admin surface still answers. The check is a readiness guard, so every composed capability’s admin routes and the control plane’s ping and manifest are exempt, and so is GET /health. Every other route refuses with a 500 vector/metadata_index_drift. That surface is also where the drift is reported: the index read names each drifted field.
It is written last, and only on success, so it never claims more than provisioning got done.
What provisioning reports
| Field | Meaning |
|---|---|
created | Metadata indexes created on this run. Empty on a re-run — that is what idempotent looks like |
extra | Indexes that exist but the config does not declare. Not fatal — they still cost a slot |
observed | Everything live when it finished. This is what the boot check compares against |
The observed type is recorded verbatim rather than narrowed to the three the package declares.
Commands
| Command | Does |
|---|---|
provision | Creates the index and its metadata indexes, waits for each to go live, deploys the reprocess host, writes the bindings and the record |
reset | Deletes, rebuilds, re-embeds from the corpus. Destructive |
reprocess | Re-embeds one index or all of them |
Provisioning waits before deploying the writer, because a write landing before an index exists is permanently unfilterable.
reset has no --yes, deliberately. --yes elsewhere authorizes additive writes; this deletes every vector. It takes the environment-named phrase instead — the same gate a schema reset uses.
The reprocess report
The Workflow’s own return value, passed through verbatim — it crosses no schema on the way out, and is absent entirely when a completed Workflow returned nothing.
| Key | Meaning |
|---|---|
indexName | The index reprocessed |
pages | Pages taken — one durable step each |
scanned | Rows read |
reembedded | Rows re-embedded and written back |
skipped | Rows selected but skipped because the corpus holds no text for them |
The index read
GET {basePath}/indexes — /vector/indexes by default — is vector’s one route on the control plane, behind the vector:indexes:read scope. The manifest names the mounted path, so a moved basePath is followed rather than answered with a 404. It answers for the Worker it reaches, with every index config declares, in config order. None is omitted.
| Part | Read from | What it says |
|---|---|---|
declared | pithy.config.ts | The model, dimensions and metric |
vectorize | describe() on the index’s own binding. No API token | vectorCount, dimensions, processedUpToDatetime, processedUpToMutation, and dimensionMismatch |
documents | D1 | Counts embedded under the declared model (declaredModel), under another (otherModel), and never embedded (unembedded) |
namespaces | D1 | How many distinct namespaces the index uses, the default not counted |
provision | VECTOR_PROVISIONED | unprovisioned, provisioned or drifted |
processedUpToDatetime answers have my writes landed. Vectorize says every mutation before it is reflected in the index.
A dimension mismatch names a decision, not a fix. Dimensions are fixed at creation, so the message names pithy vector reset as a person’s call: it deletes every vector in the index.
An index Vectorize could not describe is unreadable, never zero vectors. Its reason is unbound (no binding on the Worker), unsupported (the binding has no describe) or failed.
otherModel is the count that matters after a model change. Queries compare vectors from two embedding spaces and nothing errors. pithy vector reprocess re-embeds them.
drifted names each field. missing lists fields declared filterable with no metadata index, and mismatched lists fields indexed as another type. The read is on the admin surface, so a drifted Worker answers it.
Namespaces are a count and never a list. A namespace often partitions one index by tenant or organization, so naming them would hand those ids to every holder of the scope.
Two health keys
Both sit on the capability’s manifest entry, behind vector:indexes:read. A caller without the scope gets no value, never a zero.
| Key | Kind | Nominal |
|---|---|---|
vectorCorpusEmbedding | A state: current or stale | current |
unprovisionedVectorIndexes | A count, from the provision record | At most 0 |
vectorCorpusEmbedding is a state and not a count, on purpose. It is stale when any document is embedded under another model or never embedded. Finding one is three seeks per declared index, each stopping at its first row, so the manifest read costs the same however large the corpus grows. The count is the index read’s.
Peer capabilities
Required: none.
Optional: auth — effectively required, since results are scoped to a caller.
Composes naturally with media, whose transcripts and extracted text are the obvious corpus.
What is not here
No chunking. A wrong default produces bad search that looks like a model problem.
No retrieval framework. No prompt templates, no chains, no reranking.
No keyword search. A different question, answered by a full-text index.
No local path. Dev reaches the real service.