examples · vector

Vector examples — copy-paste JSON.

Twelve copy-paste JSON examples for the managed vector database. HNSW with f32 SIMD distance kernels. Default high_recall mode hits recall@10 = 0.96 at 100k vectors with p99 109 ms; fast mode runs p99 37 ms at recall 0.69. For the architecture explanation, see /docs/vector.

Indexing (vector_put)

vector_put — minimal (id + embedding)

Write a single embedding under the table's vector domain. The HNSW graph is updated synchronously inside the same WAL frame.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "id": "sku-9281",
  "embedding": [0.0124, -0.0883, 0.0451, 0.0192, 0.0772, -0.0341, 0.0118, -0.0204]
}
JSON

Response

{
  "id": "sku-9281",
  "dim": 8,
  "lsn": 41827301,
  "elapsed_ms": 3
}

vector_put — with metadata

Attach metadata for later filtering. Metadata is stored alongside the vector and read in the topk filter pass.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "id": "sku-9281",
  "embedding": [0.0124, -0.0883, 0.0451, 0.0192, 0.0772, -0.0341, 0.0118, -0.0204],
  "metadata": {
    "category": "running-shoes",
    "price": 129.0,
    "in_stock": true
  }
}
JSON

Response

{
  "id": "sku-9281",
  "dim": 8,
  "lsn": 41827305,
  "elapsed_ms": 3
}

vector_put — explicit dim (768d embedding)

The dim is locked to whatever the first put declared for the table. Subsequent puts must match.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/articles/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "id": "doc-001",
  "embedding": [/* 768 f32 values */]
}
JSON

Response

{
  "id": "doc-001",
  "dim": 768,
  "lsn": 41827310,
  "elapsed_ms": 5
}

Search modes

vector_topk — fast mode

Lower-recall, lower-latency mode. recall@10 = 0.69, p99 = 37 ms at 100k vectors. Pair with a re-ranker for RAG when latency dominates.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      10,
  "metric": "cosine",
  "mode":   "fast"
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": 0.0124, "metadata": { "category": "running-shoes", "price": 129.0 } },
    { "id": "sku-3711", "score": 0.0188, "metadata": { "category": "running-shoes", "price":  99.0 } },
    { "id": "sku-5520", "score": 0.0241, "metadata": { "category": "trail-shoes",   "price": 159.0 } }
  ],
  "count": 3,
  "elapsed_ms": 31
}

vector_topk — high_recall mode (default)

Default. recall@10 = 0.96, p99 = 109 ms at 100k vectors. Use for first-pass retrieval where correctness matters.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      10,
  "metric": "cosine",
  "mode":   "high_recall"
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": 0.0124, "metadata": { "category": "running-shoes", "price": 129.0 } },
    { "id": "sku-3711", "score": 0.0188, "metadata": { "category": "running-shoes", "price":  99.0 } },
    { "id": "sku-7104", "score": 0.0212, "metadata": { "category": "running-shoes", "price": 149.0 } }
  ],
  "count": 3,
  "elapsed_ms": 98
}

Filters

vector_topk — with metadata filter

Equality predicates over metadata applied during the topk walk. Hits that fail the predicate are skipped before scoring is finalised.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      10,
  "metric": "cosine",
  "mode":   "high_recall",
  "filter": { "category": "running-shoes", "in_stock": true }
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": 0.0124, "metadata": { "category": "running-shoes", "price": 129.0, "in_stock": true } },
    { "id": "sku-3711", "score": 0.0188, "metadata": { "category": "running-shoes", "price":  99.0, "in_stock": true } }
  ],
  "count": 2,
  "elapsed_ms": 104
}

Distance metrics

vector_topk — cosine metric

Default metric. The L2 norm of every stored vector is precomputed at write time, so cosine costs one dot plus two scalar muls and one div.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      5,
  "metric": "cosine"
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": 0.0124 },
    { "id": "sku-3711", "score": 0.0188 }
  ],
  "count": 2,
  "elapsed_ms": 96
}

vector_topk — dot metric

Cheapest metric. Use when embeddings are pre-normalised to unit length.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      5,
  "metric": "dot"
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": -0.0182 },
    { "id": "sku-3711", "score": -0.0151 }
  ],
  "count": 2,
  "elapsed_ms": 88
}

vector_topk — L2 metric

Squared Euclidean distance. Use when magnitude carries signal, for example image-pixel embeddings.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/topk" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "query":  [0.011, -0.082, 0.046, 0.019, 0.078, -0.033, 0.012, -0.021],
  "k":      5,
  "metric": "l2"
}
JSON

Response

{
  "hits": [
    { "id": "sku-9281", "score": 0.00041 },
    { "id": "sku-3711", "score": 0.00098 }
  ],
  "count": 2,
  "elapsed_ms": 92
}

Bulk + delete

Bulk put — multiple vectors in one batch

Use multiple put calls inside a single batch frame against /v1/rows/:t/_batch when the table has both row and vector shapes. For pure vector loads, repeat /vector/:t/put under HTTP keep-alive.

Request

curl -X POST "$ENGINE/v1/tenants/$T/rows/products/_batch" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "rows": [
    { "id": "sku-9281", "name": "Trailblazer 2",  "embedding": [/* 768 f32 */], "category": "running-shoes" },
    { "id": "sku-3711", "name": "Pacer Lite",     "embedding": [/* 768 f32 */], "category": "running-shoes" },
    { "id": "sku-5520", "name": "Summit Grip",    "embedding": [/* 768 f32 */], "category": "trail-shoes"   }
  ]
}
JSON

Response

{
  "inserted": 3,
  "lsn": 41827418,
  "elapsed_ms": 9
}

vector_delete — remove a vector

Removes the embedding and unlinks it from the HNSW graph. Subsequent topk calls will not return the deleted id.

Request

curl -X POST "$ENGINE/v1/tenants/$T/vector/products/delete" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "id": "sku-9281"
}
JSON

Response

{
  "deleted": 1,
  "lsn": 41827511,
  "elapsed_ms": 3
}