1# Vectorize Gotchas
2 
3## Critical Warnings
4 
5### Async Mutations
6Insert/upsert/delete return immediately but vectors aren't queryable for 5-10 seconds.
7 
8### Batch Size Limit
9**Workers API: 1,000 vectors max per call (HTTP API: 5,000).** Silently truncates if exceeded.
10 
11```typescript
12// ✅ Chunk into 1000 (Workers API limit; HTTP API allows 5000)
13for (let i = 0; i < vectors.length; i += 1000) {
14  await env.VECTORIZE.upsert(vectors.slice(i, i + 1000));
15}
16```
17 
18### Metadata Truncation
19`returnMetadata: "indexed"` returns only first 64 bytes of strings. Use `"all"` for complete metadata (but max topK drops to 20).
20 
21### topK Limits
22 
23| returnMetadata | returnValues | Max topK |
24|----------------|--------------|----------|
25| `"none"` / `"indexed"` | `false` | 100 |
26| `"all"` | any | **20** |
27| any | `true` | **20** |
28 
29### Metadata Indexes First
30Create BEFORE inserting - existing vectors not retroactively indexed.
31 
32```bash
33# ✅ Create index FIRST
34wrangler vectorize create-metadata-index my-index --property-name=category --type=string
35wrangler vectorize insert my-index --file=data.ndjson
36```
37 
38### Index Config Immutable
39Cannot change dimensions/metric after creation. Must create new index and migrate.
40 
41## Limits (V2)
42 
43| Resource | Limit |
44|----------|-------|
45| Vectors per index | 10,000,000 |
46| Max dimensions | 1536 |
47| Batch upsert (Workers / HTTP API) | **1,000 / 5,000** |
48| Indexed string metadata | **64 bytes** |
49| Metadata indexes | 10 |
50| Namespaces | 50,000 (paid) / 1,000 (free) |
51 
52## Common Mistakes
53 
541. **Wrong embedding shape:** Extract `result.data[0]` from Workers AI
552. **Metadata index after data:** Re-upsert all vectors
563. **Insert vs upsert:** `insert` ignores duplicates, `upsert` overwrites
574. **Not batching:** Individual inserts ~1K/min, batched ~200K+/min
58 
59## Troubleshooting
60 
61**No results?**
62- Wait 5-10s after insert
63- Check namespace spelling (case-sensitive)
64- Verify metadata index exists
65- Check dimension mismatch
66 
67**Metadata filter not working?**
68- Index must exist before data insert
69- Strings >64 bytes truncated
70- Use dot notation for nested: `"product.category"`
71 
72## Model Dimensions
73 
74- `@cf/baai/bge-small-en-v1.5`: 384
75- `@cf/baai/bge-base-en-v1.5`: 768
76- `@cf/baai/bge-large-en-v1.5`: 1024
77