Semantic search over your own Vectorize index, with embeddings from Workers AI, documents in your own D1, and the metadata half taken seriously.
That last clause is the reason this capability exists rather than being a fifteen-line wrapper.
The failure this is built around
Vectorize returns partial results — silently — when you filter on a field whose metadata index was created after the vectors were written. And it stops at ten metadata indexes per index.
Both fail quietly. In production. Your search returns four results instead of forty, nothing errors, nothing logs, and the only way to notice is for somebody to say I know that document exists.
So in this package, filterable fields are a schema decision rather than a query-time hope:
- Declare them once, in config.
- Provisioning creates the metadata indexes from that schema, and waits for each one to go live before anything writes a vector.
- Every filter is typed against the schema, and a filter on a field the schema does not mark is refused at compile time.
- Provisioning records what it observed, and the Worker refuses to boot when the config declares a filterable field that record does not have.
That last one is the important one. A schema edited and deployed without re-provisioning fails at startup, naming the field, rather than returning short results for a month.
The one repair, and why it is destructive
A metadata index added after vectors were written covers none of them, and there is no backfill. That is Vectorize’s behavior, not a gap in this package.
So the repair is a rebuild: delete the index, recreate it with the full schema, and re-embed the corpus from D1. pithy vector reset does exactly that, and it is destructive by definition — only what your D1 holds comes back.
Which is the argument for keeping the corpus in D1 in the first place. The vectors are derived; the documents are the truth.
Embeddings are pinned per index
The model is pinned for writes and queries on the same index. A query embedded with a different model than the vectors it searches produces results that look plausible and are wrong, which is worse than an error.
Changing the model means re-embedding, and pithy vector reprocess is the command — over one index or every configured one, filtered to a subset if you want.
What it deliberately does not do
It does not chunk your documents. How a long document is split into embeddable pieces is a decision that depends on what your documents are, and a wrong default produces bad search that looks like a model problem. Chunking stays yours.
It is not a RAG framework. No prompt templates, no retrieval chains, no reranking. It embeds, indexes and queries; what you do with the matches is your application.
It is not keyword search. Semantic and lexical search answer different questions, and exactly this string is often the question. support uses a full-text index for exactly that reason.
There is no local emulation. Cloudflare ships none for Vectorize, so --env dev reaches a real remote index — which is also why the capability’s bindings are declared remote. A dev search costs a real query.
When you would reach for it
When find me the thing I half remember is a real user need: a knowledge base, a document library, a support archive, a product catalog searched by description rather than by name.
Pairs naturally with media: transcripts and extracted text are the obvious thing to embed, and a spoken sentence in a video becoming a search result needs no glue between the two.
Not for search where the right answer is an exact match on a field you already index. That is a WHERE clause and it is free.
What it needs
No required peers. auth is optional and effectively required — search results are scoped to a caller.
Four bindings, two of them remote: the Vectorize index and the Workers AI binding for embeddings, plus D1 for the corpus and an optional Workflow for reprocessing.
pithy add vector writes what it can. The index, its metadata indexes and the reprocess host arrive with pithy vector provision, which needs a Cloudflare account for every environment including dev.