Vectorize API Reference

Types

interface VectorizeVector {
  id: string;                    // Max 64 bytes
  values: number[];              // Must match index dimensions
  namespace?: string;            // Optional partition (max 64 bytes)
  metadata?: Record<string, any>; // Max 10 KiB
}

Query

const matches = await env.VECTORIZE.query(queryVector, {
  topK: 10,                        // Max 100 (or 20 with returnValues/returnMetadata:"all")
  returnMetadata: "indexed",       // "none" | "indexed" | "all"
  returnValues: false,
  namespace: "tenant-123",
  filter: { category: "docs" }
});
// matches.matches[0] = { id, score, metadata? }

returnMetadata: "none" (fastest) → "indexed" (recommended) → "all" (topK max 20)

queryById (V2 only): Search using existing vector as query.

await env.VECTORIZE.queryById("doc-123", { topK: 5 });

Insert/Upsert

// Insert: ignores duplicates (keeps first)
await env.VECTORIZE.insert([{ id, values, metadata }]);

// Upsert: overwrites duplicates (keeps last)
await env.VECTORIZE.upsert([{ id, values, metadata }]);

Max 500 vectors per call. Queryable after 5-10 seconds.

Other Operations

// Get by IDs
const vectors = await env.VECTORIZE.getByIds(["id1", "id2"]);

// Delete (max 1000 IDs per call)
await env.VECTORIZE.deleteByIds(["id1", "id2"]);

// Index info
const info = await env.VECTORIZE.describe();
// { dimensions, metric, vectorCount }

Filtering

Requires metadata index. Filter operators:

Operator	Example
`$eq` (implicit)	`{ category: "docs" }`
`$ne`	`{ status: { $ne: "deleted" } }`
`$in` / `$nin`	`{ tag: { $in: ["sale"] } }`
`$lt`, `$lte`, `$gt`, `$gte`	`{ price: { $lt: 100 } }`

Constraints: Max 2048 bytes, no dots/$ in keys, values: string/number/boolean/null.

Performance

Configuration	topK Limit	Speed
No metadata	100	Fastest
`returnMetadata: "indexed"`	100	Fast
`returnMetadata: "all"`	20	Slower
`returnValues: true`	20	Slower

Batch operations: Always batch (500/call) for optimal throughput.

for (let i = 0; i < vectors.length; i += 500) {
  await env.VECTORIZE.upsert(vectors.slice(i, i + 500));
}

2.3 KiB Raw Blame History