examples · vector · 1 / 7

1. Insert a single embedding

what this does

Save one embedding under an id. The first put against a table locks in the dim and metric - every later put must match.

when to use it

You computed one embedding (e.g., from an LLM API) and want to make it searchable.
Use the row's primary key as the vector id so search results link back cleanly.
For bulk loads, use the /put_bulk endpoint instead - faster and atomic per chunk.

the request

POST /v1/tenants/:t/vector/:table/put

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/vector/shop.products/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id":        "sku-9281",
    "embedding": [0.0124, -0.0883, 0.0451, /* ... 768 floats ... */],
    "dim":       768,
    "metric":    "cosine"
  }'

db.vector.put(
    "shop.products",
    "sku-9281",
    embedding_768d,   # list[float] of length 768
)

await db.vectorPut("shop.products", {
  id:        "sku-9281",
  embedding: embedding768d,   // number[] of length 768
  dim:       768,
  metric:    "cosine",
});

err := db.VectorPut(ctx, "shop.products", originchain.VectorPutRequest{
    ID:        "sku-9281",
    Embedding: embedding768d,   // []float32 of length 768
    Dim:       768,
    Metric:    "cosine",
})

what you get back

{ "ok": true }

Re-putting the same id overwrites the previous vector.

request fields

Field	Required	Notes
id	yes	String. Usually the row's primary key.
embedding	yes	Array of floats. Length must equal `dim`.
dim	yes	Locked at the first put.
metric	no	Default `"cosine"`. Locked at the first put.

common mistakes

dim mismatch. If you switch models partway through, all puts after the first model fail with 400 dim_mismatch. Use a fresh table for the new model.
Float precision. Doubles convert to f32 on the wire. ~7 decimal digits of precision is plenty for similarity but not for exact equality.