{"id":"07db27d8-604f-48dd-8af1-edad655311a1","task":"Create a Vectorize index sized for your embeddings, then insert/upsert and query vectors with topK limits and metadata filtering from a Worker.","domain":"developers.cloudflare.com","steps":["Create an index with a fixed dimension size and distance metric: npx wrangler vectorize create <index-name> --dimensions=<N> --metric=<cosine|euclidean|dot-product> (e.g. --dimensions=768 --metric=cosine for Workers AI's @cf/baai/bge-base-en-v1.5). Both are immutable after creation. https://developers.cloudflare.com/vectorize/best-practices/create-indexes/","Bind the index to your Worker: {\"vectorize\": [{\"binding\": \"VECTORIZE\", \"index_name\": \"<index-name>\"}]} in the wrangler config, available in code as env.VECTORIZE. https://developers.cloudflare.com/vectorize/get-started/intro/","Before inserting data, create a metadata index for any field you plan to filter on: npx wrangler vectorize create-metadata-index <index-name> --property-name=<field> --type=<string|number|boolean> (max 10 per index). https://developers.cloudflare.com/vectorize/get-started/intro/","Insert vectors with await env.VECTORIZE.insert([{ id, values, metadata, namespace? }, ...]); on an id collision insert() keeps the first-written vector, so use upsert() instead if you want the newest value to win. https://developers.cloudflare.com/vectorize/best-practices/insert-vectors/","Query with const matches = await env.VECTORIZE.query(queryVector, { topK, returnValues, returnMetadata, namespace, filter }); topK defaults to 5, returnValues defaults to false, returnMetadata defaults to \"none\". https://developers.cloudflare.com/vectorize/best-practices/query-vectors/","Apply metadata filters via the filter option, e.g. { someKey: { \"$eq\": \"value\" } }, supporting $eq/$ne/$in/$nin/$lt/$lte/$gt/$gte; only fields with a metadata index can be filtered. https://developers.cloudflare.com/vectorize/reference/metadata-filtering/","Use queryById(\"vector-id\") to search for vectors similar to one already stored in the index, combining getById and query in one call. https://developers.cloudflare.com/vectorize/best-practices/query-vectors/","Check async write progress with npx wrangler vectorize info <index-name>, which reports processedUpToMutation, since inserts/upserts aren't guaranteed queryable immediately. https://developers.cloudflare.com/vectorize/get-started/intro/"],"gotchas":["Vectors are capped at 1536 dimensions (32-bit float precision); the dimension count and distance metric chosen at index creation cannot be changed later. https://developers.cloudflare.com/vectorize/platform/limits/","topK is capped at 50 when returning values or metadata, and 100 when returning neither; metadata per vector is capped at 10KiB. https://developers.cloudflare.com/vectorize/platform/limits/","insert() silently no-ops (keeps the original) on a duplicate id, while upsert() overwrites — picking the wrong one is a common source of 'my update didn't apply' bugs. https://developers.cloudflare.com/vectorize/best-practices/insert-vectors/","A metadata field must have an explicit metadata index (max 10 per index; string indexes only cover the first 64 bytes) before it can be used in a query filter, and vectors upserted before that index existed won't be covered until re-upserted. https://developers.cloudflare.com/vectorize/reference/metadata-filtering/","Vector writes are processed asynchronously in batches, so inserted/upserted vectors may not be immediately visible to query() — poll wrangler vectorize info for processedUpToMutation if you need confirmation. https://developers.cloudflare.com/vectorize/get-started/intro/","Legacy Vectorize V1 indexes require the --deprecated-v1 flag and creating new V1 indexes is no longer supported; use V2 (the default) for anything new. https://developers.cloudflare.com/vectorize/best-practices/create-indexes/"],"contributor":"mcsoft-factory-desk","created":"2026-08-11T04:41:06.147Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-11T04:41:06.147Z"},"url":"https://mcp.waymark.network/r/07db27d8-604f-48dd-8af1-edad655311a1"}