For a Cloudflare Vectorize docs search split by product and language, when do you partition with a namespace and when with a metadata index?
answer
- one partition per vector
- one namespace name per query
- 10 metadata index slots
- $in for language fallback
basics
~20 sUse a namespace for one fixed partition every query names, such as product: it needs no metadata index and is applied first. Use metadata indexes, at most 10, for fields filtered in combination, by several values or by range, such as language.
solid answer
~40 sA namespace is one string per vector, set at write time, and a query names one namespace; it needs no metadata index, runs before metadata filters and the vector search, and an index holds up to 50,000 on Workers Paid (1,000 on Free). Metadata filters need one of at most 10 metadata indexes, but support `$in`, `$nin`, ranges and an implicit AND. For the docs site I would put product in the namespace, since every search names one product, and language in a string metadata index for a filter like `{ language: { $in: ["fr", "en"] } }`. The trade-off: a later all-products search would need product indexed as metadata too, plus a re-upsert.
code
javascript · 8 linesexport async function searchDocs(env, vector, product, language) {
return env.DOCS_INDEX.query(vector, {
topK: 10,
namespace: product,
filter: { language: { $in: [language, "en"] } },
returnMetadata: "indexed",
});
}go deeper
Recall that a namespace is set on each vector when it is written and named in the query, and that other metadata needs a metadata index to filter on.
Explain the limits that shape the choice: one namespace per vector and per query, 10 metadata indexes, the filter operators, and the plan-dependent namespace count.
Lay out a real index: which field is the namespace, which get metadata indexes, how cardinality affects range filters, and what a later global search would cost.
Treat the partition scheme as an index schema with a migration cost, and decide where a tenant boundary lives so the Worker, not the caller, sets it.
## Two ways to narrow a Vectorize search A documentation search that embeds pages per product and per language has to answer queries such as "Workers pages, in English or French". Vectorize gives two tools for narrowing a search, and they are not interchangeable. **A namespace** is an optional string on the vector, set when it is inserted or upserted (`namespace: "workers"`). A query that passes `namespace: "workers"` searches only the vectors in it. - Each vector belongs to at most one namespace. - A namespace name is up to 64 bytes. - An index holds up to **50,000 namespaces on Workers Paid** and **1,000 on the Free plan**. - Namespace filtering works by default; it needs no metadata index. - It is applied before any metadata filter, and before the vector search itself. **A metadata filter** matches fields in the vector's `metadata`, but only properties with a metadata index. - Up to **10 metadata indexes** per index, each of type `string`, `number` or `boolean`. - Operators: `$eq`, `$ne`, `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`. - Several keys in one filter combine as an implicit AND. - A lower and an upper range bound can be combined on one key, for example a prefix match on strings. - The filter's compact JSON must stay under 2,048 bytes. ## The trade, side by side | Question | Namespace | Metadata index | |---|---|---| | Values per vector | one | several fields | | Values per query | one namespace name | `$in`, `$nin`, ranges, AND across keys | | Setup | none | `create-metadata-index`, before loading | | Budget | 50,000 per index (Paid), 1,000 (Free) | 10 properties per index | | Changing a vector's value | upsert the whole vector | upsert the whole vector | ## Laying out the docs search A sensible layout for this site: 1. **Product as the namespace.** Every search is scoped to one product, the value never changes for a page, and the number of products is far below the namespace limit. It costs no metadata index slot, and it is applied before everything else. 2. **Language as a metadata index** (`--type=string`). Queries need "this language, or English as a fallback", which is `filter: { language: { $in: ["fr", "en"] } }`, something one namespace name per query cannot express. 3. **Version as a metadata index** if old docs stay online, filtered with `$eq` or a string range. 4. **Title, URL and summary as plain metadata.** They are returned for display but never filtered on, so they spend no metadata index slot. The cost of that choice is that a search across **all** products cannot name several namespaces at once. If the site later wants a global search box, the layout has to change: add `product` as a metadata index as well, and re-upsert every vector so the new index covers them. ## Cardinality decides how well a filter performs Vectorize resolves metadata filters through a reverse index from values to vector IDs, so the shape of the values matters: - **High cardinality suits `$eq`.** A filter on one page slug or one user ID is very selective and cheap. - **Low cardinality filters little.** A boolean true for 95% of vectors narrows almost nothing. - **High cardinality hurts ranges.** A range over millisecond timestamps touches many distinct values; Vectorize then degrades speed and accuracy to finish. Store a rounded bucket (say, the day) as the indexed field, and keep the precise timestamp as unindexed metadata. - Ranges over roughly 10 million vectors or more may lose accuracy. ## When the partition is a security boundary If the index holds content for different customers, the partition is an access-control decision, not a ranking one. The Worker must derive the namespace or filter value from the authenticated caller, never from a query parameter the caller controls. Why a tenant filter must be an authorization boundary is covered with filtered retrieval; here the point is that Vectorize applies whatever namespace or filter the code passes. ## Rules of thumb - Use a namespace for one fixed partition per vector that every query names. - Use metadata indexes for fields queried in combination, with several values, or as ranges. - Spend the 10 metadata index slots on fields that are actually filtered. - Decide both before the first load, since each later change means re-upserting.
- The product team now wants one search box across every product; what changes in this layout?A query names one namespace, so a global search cannot list several. Create a `product` metadata index, re-upsert every vector so the index covers them, and query without a namespace but with a `product` filter, or with none for an unfiltered search. Each new filterable property costs one of the 10 slots and a full re-upsert, which is why the layout is decided up front.
- Why store a rounded day rather than the millisecond timestamp as an indexed field?Vectorize resolves filters through a reverse index from values to vector IDs. A range over millisecond timestamps spans thousands of distinct values, and Vectorize degrades speed and accuracy to finish such a query. A day bucket groups many vectors under one value; the precise timestamp can stay as unindexed metadata for display.
A namespace is the drawer of a filing cabinet: each folder sits in exactly one drawer, and you open one drawer per search. Metadata indexes are labels on the folders, which let you pull several kinds at once, but the cabinet only has room for ten label types.
- Expects to pass a list of namespaces to one query
- Creates a metadata index for every field, including display-only ones
- Thinks a namespace needs its own metadata index to filter
- Uses millisecond timestamps as an indexed range field
- Takes the tenant namespace from a request parameter
Assumes Vectorize limits as of 2026-10-10: 50,000 namespaces per index on Workers Paid and 1,000 on Free; some older pages still give 1,000 for every plan.