Note: IDs are strings up to 512 chars. Avoid spaces and special chars for portability.
2. Validating Vector Dimensions
Example: Validate Before Upsert
EXPECTED_DIM = 1536def validate(vec): if len(vec) != EXPECTED_DIM: raise ValueError(f"dim {len(vec)} != {EXPECTED_DIM}") if not all(isinstance(x, (int, float)) for x in vec): raise TypeError("non-numeric value")
def chunks(lst, size): for i in range(0, len(lst), size): yield lst[i:i+size]for batch in chunks(all_vectors, 100): index.upsert(vectors=batch)
Limit
Value
Max batch size
2 MB or 1000 vectors
Recommended
100 vectors @ 1536d
6. Upserting to Namespace
Example: Namespaced Upsert
index.upsert(vectors=batch, namespace="tenant-a")
Param
Behavior
namespace="name"
Creates if missing
namespace=""
Default namespace
7. Optimizing Batch Size
Dim
Recommended Batch
384
200–500
768
200
1536
100
3072
50
Note: Stay under 2 MB payload. Larger batches reduce overhead but risk timeouts.
8. Handling Upsert Failures
Example: Retry with Backoff
import timefor attempt in range(5): try: index.upsert(vectors=batch) break except Exception as e: if attempt == 4: raise time.sleep(2 ** attempt)
Error
Strategy
429 Rate limit
Exponential backoff
413 Payload too large
Reduce batch size
500/503
Retry with backoff
400 Invalid input
Fix data; don't retry
9. Using Async Upsert Operations
Example: Async Python
from concurrent.futures import ThreadPoolExecutorwith ThreadPoolExecutor(max_workers=10) as pool: futures = [pool.submit(index.upsert, vectors=b) for b in batches] for f in futures: f.result()