1# Vectorize API Reference
2 
3## Types
4 
5```typescript
6interface VectorizeVector {
7  id: string;                    // Max 64 bytes
8  values: number[];              // Must match index dimensions
9  namespace?: string;            // Optional partition (max 64 bytes)
10  metadata?: Record<string, any>; // Max 10 KiB
11}
12```
13 
14## Query
15 
16```typescript
17const matches = await env.VECTORIZE.query(queryVector, {
18  topK: 10,                        // Max 100 (or 20 with returnValues/returnMetadata:"all")
19  returnMetadata: "indexed",       // "none" | "indexed" | "all"
20  returnValues: false,
21  namespace: "tenant-123",
22  filter: { category: "docs" }
23});
24// matches.matches[0] = { id, score, metadata? }
25```
26 
27**returnMetadata:** `"none"` (fastest) → `"indexed"` (recommended) → `"all"` (topK max 20)
28 
29**queryById (V2 only):** Search using existing vector as query.
30```typescript
31await env.VECTORIZE.queryById("doc-123", { topK: 5 });
32```
33 
34## Insert/Upsert
35 
36```typescript
37// Insert: ignores duplicates (keeps first)
38await env.VECTORIZE.insert([{ id, values, metadata }]);
39 
40// Upsert: overwrites duplicates (keeps last)
41await env.VECTORIZE.upsert([{ id, values, metadata }]);
42```
43 
44**Max 1,000 vectors per call (Workers) / 5,000 (HTTP API).** Queryable after 5-10 seconds.
45 
46## Other Operations
47 
48```typescript
49// Get by IDs
50const vectors = await env.VECTORIZE.getByIds(["id1", "id2"]);
51 
52// Delete (max 1000 IDs per call)
53await env.VECTORIZE.deleteByIds(["id1", "id2"]);
54 
55// Index info
56const info = await env.VECTORIZE.describe();
57// { dimensions, metric, vectorCount }
58```
59 
60## Filtering
61 
62Requires metadata index. Filter operators:
63 
64| Operator | Example |
65|----------|---------|
66| `$eq` (implicit) | `{ category: "docs" }` |
67| `$ne` | `{ status: { $ne: "deleted" } }` |
68| `$in` / `$nin` | `{ tag: { $in: ["sale"] } }` |
69| `$lt`, `$lte`, `$gt`, `$gte` | `{ price: { $lt: 100 } }` |
70 
71**Constraints:** Max 2048 bytes, no dots/`$` in keys, values: string/number/boolean/null.
72 
73## Performance
74 
75| Configuration | topK Limit | Speed |
76|--------------|------------|-------|
77| No metadata | 100 | Fastest |
78| `returnMetadata: "indexed"` | 100 | Fast |
79| `returnMetadata: "all"` | 20 | Slower |
80| `returnValues: true` | 20 | Slower |
81 
82**Batch operations:** Always batch (1,000/call via Workers, 5,000 via HTTP API) for optimal throughput.
83 
84```typescript
85for (let i = 0; i < vectors.length; i += 1000) {
86  await env.VECTORIZE.upsert(vectors.slice(i, i + 1000));
87}
88```
89