Store one embedding

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

An embedding is a list of numbers that represents an item for similarity search. Give it the source record’s ID so results can be matched back to the record.

Before you run it: Later vectors must match the dimension count. A separate source row is not updated automatically.

Choose an unused collection for a first trial. The array below is shortened: replace the comment and ellipsis with all 768 numeric values, or change dim to the length of a real test vector consistently in both write and query. JSON comments are not valid request data. This call stores an embedding you provide; it does not call an embedding model.

Store a supplied embedding under its source IDThis write does not call an embedding model or update a separate source row.

Generate the full vectorUse your chosen embedding model outside this request.
Choose ID and dimensionsUse the source ID and the vector's actual length.
Write the embeddingKeep the collection's first dimension and metric settings consistent.
Query in the same spaceUse a query from the same model and preprocessing.

Follow the example

Generate an embedding with your chosen model.
Choose its table, ID and distance metric.
Send the write.
Query with an embedding from the same model.

For a first API check without an embedding model, run the complete three-value example. The longer example below shows how the same request is shaped for model-generated embeddings.

Run the request

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"
  }'

Check the result

The first write establishes dimensions and metric. Writing the same ID replaces that vector.

{ "ok": true }

Re-putting the same id overwrites the previous vector.

Request options

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.

Important limits and checks

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.

Continue

Continue to find similar vector directions.

Follow the exampleCopy Anchor Link

Run the requestCopy Anchor Link

Check the resultCopy Anchor Link

Request optionsCopy Anchor Link

Important limits and checksCopy Anchor Link