Vector reference

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.

OptionDefaultMeaning
indexes—Each index’s dimensions and its metadata schema
defaultTopK10Matches 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

BindingTypeWritten by
AIai, remotepithy add
DBd1pithy add
VECTORIZEvectorize, remotepithy vector provision
VECTOR_REPROCESSworkflow, optionalpithy 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

FieldMeaning
createdMetadata indexes created on this run. Empty on a re-run — that is what idempotent looks like
extraIndexes that exist but the config does not declare. Not fatal — they still cost a slot
observedEverything 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

CommandDoes
provisionCreates the index and its metadata indexes, waits for each to go live, deploys the reprocess host, writes the bindings and the record
resetDeletes, rebuilds, re-embeds from the corpus. Destructive
reprocessRe-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.

KeyMeaning
indexNameThe index reprocessed
pagesPages taken — one durable step each
scannedRows read
reembeddedRows re-embedded and written back
skippedRows 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.

PartRead fromWhat it says
declaredpithy.config.tsThe model, dimensions and metric
vectorizedescribe() on the index’s own binding. No API tokenvectorCount, dimensions, processedUpToDatetime, processedUpToMutation, and dimensionMismatch
documentsD1Counts embedded under the declared model (declaredModel), under another (otherModel), and never embedded (unembedded)
namespacesD1How many distinct namespaces the index uses, the default not counted
provisionVECTOR_PROVISIONEDunprovisioned, 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.

KeyKindNominal
vectorCorpusEmbeddingA state: current or stalecurrent
unprovisionedVectorIndexesA count, from the provision recordAt 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.

ESC