Find similar vector directions

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

Cosine similarity compares vector direction rather than magnitude. Use it when the embedding model recommends this metric.

Before you run it: The query metric must match the table metric. Compare scores within the same model and metric.

Complete store one embedding first. Reuse its collection, 768 dimensions and cosine metric. The displayed array is shortened; supply the complete query vector. With only one stored item, expect at most that one ID—not the larger illustrative result list below.

Rank matching vector directionsScores compare vectors from the same model and metric; a higher cosine score is closer.

Use a cosine collectionStore full vectors with the model's expected preprocessing.
Create the matching queryKeep the model, dimensions and cosine metric consistent.
Read up to k matchesInspect IDs in descending score order.

Follow the example

Store vectors in a cosine table.
Create a query embedding with matching model and dimensions.
Choose k, the maximum result count.
Read scores from highest to lowest.

Run the request

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

Check the result

Scores range from -1 to 1; higher means a closer direction.

[
  { "id": "sku-9281", "score": 0.9421 },
  { "id": "sku-1144", "score": 0.9187 },
  { "id": "sku-5520", "score": 0.8903 }
]

The HTTP response is a JSON array of hits, with no hits wrapper. The IDs and scores above illustrate the shape; your stored data determines the results.

score is cosine similarity in [-1, 1]. Higher = closer. 1.0 is identical direction, 0 is orthogonal, -1 is opposite.

Request options

Field	Required	Notes
query	yes	Array of floats. Length must equal the table's locked `dim`.
k	yes	How many hits to return. Typical: 5 - 50.
dim	yes	Must match the table's locked dim.
metric	no	Default `"cosine"`. Must match the metric the table was put with.

Important limits and checks

Cosine similarity vs cosine distance. Some libraries return 1 - similarity (a distance, lower = closer). OriginChainDB returns similarity directly - higher = closer. Don't sort the wrong way.
Metric mismatch. Query with the collection's configured metric. A stored-index mismatch returns 409 vector_metric_mismatch; a contradiction with declared schema metadata can be rejected earlier with 400. Inspect the error body before changing a request.
Query from a different model. Embeddings from text-embedding-3 are not comparable to embeddings from all-MiniLM. The same dim does not mean the same vector space.

Continue

Continue to search within matching metadata.

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