Maintenance Operations
The maintenance endpoints allow you to delete items, rebuild indexes, and optimize graphs to maintain index health over time.Delete Items
Remove items from an index by their external IDs.Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
index_name | string | Yes | — | Name of the index |
external_ids | string[] | Yes | — | List of external IDs to delete |
return_not_found | boolean | No | false | Whether to return IDs not found in the index |
Response
| Field | Type | Description |
|---|---|---|
deleted_count | integer | Number of items successfully deleted |
not_found | string[] | null | IDs that were not found (only if return_not_found=true) |
Errors
| Status | Condition |
|---|---|
| 400 | Empty external_ids list or deletion failed |
| 404 | Index not found |
Rebuild Index
Perform a compact rebuild of an index. This creates a new HNSW graph from scratch using only the live (non-deleted) vectors, merging the main and delta segments.Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
index_name | string | Yes | — | Name of the index |
params | object | No | existing | Optional HNSW parameters for the rebuild |
Response
When to Rebuild
Rebuild the index when:- You’ve deleted a significant number of items and the graph is fragmented
- The delta segment has grown large after many insert/upsert operations
- You want to change HNSW parameters for better recall or performance
needs_rebuildreturnstruefrom the status endpoint
Errors
| Status | Condition |
|---|---|
| 400 | Rebuild failed |
| 404 | Index not found |
Optimize Graph
Optimize the HNSW graph in place. This is a lighter-weight alternative to a full rebuild that can restore some search performance.Request Body
Response
Optimize vs. Rebuild
| Aspect | Optimize | Rebuild |
|---|---|---|
| Speed | Fast | Slow |
| Quality improvement | Moderate | Maximum |
| Merges delta segment | No | Yes |
| Can change HNSW params | No | Yes |
| Recommended for | Light maintenance | Heavy modifications |
Errors
| Status | Condition |
|---|---|
| 400 | Optimization failed |
| 404 | Index not found |