Encrypted Index
Train Index
POST
Train Index
Train an index for efficient querying. Required before optimal performance.
When RBAC is not enabled (
Training Failed:
Explicit
Authentication
Required - admin (root) API key viaX-API-Key header. Per-user (cdbk_) keys are rejected with 403 — a per-user credential operates on data, not index lifecycle:
CYBORGDB_SERVICE_ROOT_KEY unset), no header is required.
Request Body
Response
Training Completed:This endpoint blocks until training completes. It will return
"success" when training finishes normally, or "error" if the training job fails — both as HTTP 200, never an HTTP error status. The "error" message is generic; the underlying cause is written to the service logs, not the response. HTTP error codes below only cover failures before the job runs (auth, unknown index, malformed request).Too few vectors is not reported as an error. When the index holds fewer vectors than the training minimums (see Training Requirements), the job skips training silently and still returns "status": "success" — the only trace is a warning in the service logs. Check your vector count before training.Exceptions
403 Forbidden
403 Forbidden
Authenticated with a per-user (
cdbk_) key — this operation requires the admin (root) API key404 Not Found
404 Not Found
Index not found
422 Unprocessable Entity
422 Unprocessable Entity
Request body failed validation (missing/mistyped fields)
500 Internal Server Error
500 Internal Server Error
Internal server error
Example Usage
Basic Training:n_lists:
Training Requirements
- Minimum vectors: At least 10,000 vectors must be present in the index, and at least
2 × n_listswhenn_listsis set explicitly (the auto-computedn_listsalways satisfies this). Below either floor the job skips training silently and still returns200with"status": "success"— the skip is only visible as a warning in the service logs - Memory: Training may require significant memory depending on dataset size
- Time: Training duration varies based on dataset size and convergence parameters
Use Cases
- Performance optimization: Enable fast approximate nearest neighbor search
- Production preparation: Train indexes before deploying to production
- Batch processing: Train indexes after bulk data ingestion
- Index maintenance: Retrain indexes after significant data updates