Find the nearest points

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

L2 is Euclidean distance: the straight-line distance between vectors. It includes differences in magnitude.

Before you run it: This API returns the negative L2 distance. Higher scores are closer, just as with cosine; scores are not on the same numerical scale.

Use the vector-write pattern in a fresh collection with metric: "l2". Use the same dimension and preprocessing for stored vectors and the query. The array below is shortened and must be replaced with real values before sending it.

Find nearby points using L2 distanceThe API returns negative distance, so a score closer to zero ranks higher.

Use a fresh L2 collectionStore vectors with the l2 metric.
Query with matching dimensionsUse the same model and preprocessing as the stored vectors.
Keep descending score orderFor example, -0.18 is closer than -0.30.

Follow the example

Store embeddings in an L2 table.
Create a query of matching dimensions.
Choose k and run the search.
Read scores from highest to lowest: zero is an identical vector; more negative values are farther away.

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

Check the result

Zero means identical vectors. Returned scores are negative distances, so -0.18 is closer than -0.30.

[
  { "id": "img-0421", "score": -0.1832 },
  { "id": "img-9912", "score": -0.2417 },
  { "id": "img-3308", "score": -0.3009 }
]

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 the negative L2 distance. Higher = closer. Keep the API's descending order. Negate the score only if your UI needs to display a positive distance.

Request options

Field	Required	Notes
query	yes	Array of floats. Length must equal the table's locked `dim`.
k	yes	Number of hits to return.
dim	yes	Must match the table's locked dim.
metric	yes	Set to `"l2"`. Must match the metric the table was put with.

Important limits and checks

Sorting by the smallest score. That would put more distant vectors first. Keep descending score order; convert to a positive distance only for display.
Choosing a metric without checking the model. Unit-length vectors have equivalent cosine and L2 rankings, but score values differ. Use the metric recommended by the embedding model.
Metric mismatch. The metric is locked at table creation. Switching from "cosine" to "l2" means creating a fresh table.

Continue

Continue to compare speed and retrieval quality.

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