Create a Cloudflare Vectorize index, upsert embeddings with metadata and namespaces, and query it with topK and metadata filters

Documented steps

1. Create the index with Wrangler: `npx wrangler vectorize create your-index-name --dimensions=768 --metric=cosine`. Dimensions must match your embedding model's output; metric is one of cosine, euclidean, or dot-product.
2. Or create over REST: `POST https://api.cloudflare.com/client/v4/accounts/{account_id}/vectorize/v2/indexes` with `Authorization: Bearer <token>` and body `{"name":"demo-index","description":"...","config":{"dimensions":1024,"metric":"euclidean"}}`.
3. Choose a kebab-cased index name. Dimensions and metric are fixed at creation and cannot be changed afterward.
4. Bind the index as a `vectorize` binding in wrangler config, then insert: `await env.YOUR_INDEX.insert([{ id: "1", values: [32.4, 74.1, ...], metadata: { url: "/products/sku/123" } }])`.
5. Use `insert()` for first-write-wins semantics (a duplicate id keeps the existing vector) or `upsert()` with the same call shape to overwrite by id.
6. Partition data with a `namespace` field per vector, e.g. `{ id: "1", values: [...], namespace: "images" }`, then scope queries to that namespace.
7. To bulk-load over HTTP instead of the binding, POST NDJSON: `POST .../vectorize/v2/indexes/{index}/insert` with `Authorization: Bearer <token>` and a multipart `vectors` field containing the .ndjson file.
8. Create a metadata index BEFORE filtering on a field: `npx wrangler vectorize create-metadata-index <index-name> --property-name=<name> --type=<string|number|boolean>`. You get up to 10 metadata indexes per Vectorize index.
9. Query with options: `await env.YOUR_INDEX.query(queryVector, { topK: 3, returnValues: true, returnMetadata: "all", filter: { category: "shoes" } })`. topK defaults to 5 and returnMetadata defaults to "none".
10. Build filters with `$eq`, `$ne`, `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`, e.g. `filter: { price: { $lt: 100 } }`. The filter object's compact JSON form must stay under 2048 bytes; keys cannot contain dots, cannot start with `$`, and cannot exceed 512 characters.
11. Query by an existing vector's id instead of supplying an embedding: `await env.YOUR_INDEX.queryById("some-vector-id")`.
12. For large loads, batch into files of up to 1,000 vectors per Workers-binding call or 5,000 per HTTP call; the hard per-request ceiling is 200,000 total vectors or 1,000 individual updates, whichever is hit first. Batching into ~100 files is dramatically faster than one-by-one inserts.
13. Manage indexes and vectors with `wrangler vectorize list | get | info | get-vectors | list-vectors | delete-vectors | list-metadata-index | delete-metadata-index`.
14. Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/vectorize/ | https://developers.cloudflare.com/vectorize/best-practices/create-indexes/ | https://developers.cloudflare.com/vectorize/best-practices/insert-vectors/ | https://developers.cloudflare.com/vectorize/best-practices/query-vectors/ | https://developers.cloudflare.com/vectorize/reference/metadata-filtering/ | https://developers.cloudflare.com/vectorize/platform/limits/ | https://developers.cloudflare.com/vectorize/reference/wrangler-commands/