Database endpoints
Insert or replace vector records
Insert or replace up to 1,000 vector records. A missing namespace is created.
POST /v1/tenants/{tenant}/vector-indexes/{index}/records/upsert
- Prepare up to 1,000 recordsSupply IDs and their configured vector or text fields.
- Insert or replace by IDWrite records into the selected namespace.
- Review the per-record receiptKeep revision tokens for later conditional changes.
Before you start
Use your database bearer token.
Create the vector index first. The example uses three-dimensional values in demo-search; the vector field is values, not embedding.
Path parameters
| Field | Type | Required |
|---|---|---|
tenant | string | Required |
index | string | Required |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
x-oc-db-user | string | Optional | Acting database user (role, grant and row-policy checks). Send with x-oc-db-key. |
x-oc-db-key | string | Optional | API key of the x-oc-db-user user. |
Request body
application/json
Limits and accepted values
- records: 1-1,000 with distinct ids;
- any invalid record refuses the whole batch with per-item errors.
- expected_generation is refused with 400 (use if_revision_token);
- dry_run: true is refused with 400.
| Field | Type | Required |
|---|---|---|
dry_run | boolean | Optional |
expected_generation | integer | Optional |
namespace | string | Required |
records | object[] | Required |
Fields in records
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Required | — |
if_revision_token | string | Optional | — |
metadata | object | Optional | — |
sparse_values | object | Optional | Unique indices in any order, with one value per index. |
Fields in sparse_values
| Field | Type | Required |
|---|---|---|
indices | integer[] | Required |
Fields in indices
| Field | Type | Required |
|---|---|---|
indices | integer | Optional |
| Field | Type | Required |
|---|---|---|
values | number[] | Required |
Fields in values
| Field | Type | Required |
|---|---|---|
values | number | Optional |
| Field | Type | Required |
|---|---|---|
text | object | Optional |
values | number[] | Optional |
Fields in values
| Field | Type | Required |
|---|---|---|
values | number | Optional |
Read the result
upserted_count reports accepted records and namespace_created shows whether the request created the namespace. Inspect per-record state and revision tokens in the receipt before planning conditional updates.
Response statuses
HTTP status reference
| Status | What to do |
|---|---|
| 200 | OK |
| 400 | Correct the request before retrying. |
| 401 | Check the credential and Authorization header. |
| 402 | Check feature access or available credits. |
| 403 | Check tenant access, roles and permissions. |
| 404 | Check the resource ID and API route. |
| 409 | Resolve the conflict before retrying. |
| 413 | Split or reduce the request body. |
| 415 | Send the required Content-Type. |
| 422 | Correct the values or unsupported combination. |
| 429 | Honor Retry-After when present; back off. |
| 500 | Check the outcome before retrying a write. |
| 501 | Check deployment support for this operation. |
| 503 | Honor Retry-After when present; check write outcomes. |