examples · vector · 4 / 7

4. Top-k - L2 distance

what this does

Rank results by L2 distance - the straight-line (Euclidean) distance between two vectors. Unlike cosine, L2 cares about magnitude: a long vector and a short one pointing the same way are not close. Use L2 when the length of the vector carries real signal, such as raw image-feature embeddings.

when to use it

Image-feature embeddings from un-normalised CNN backbones.
Audio or sensor embeddings where amplitude is meaningful.
Any model whose authors specify L2 as the recommended metric.

the request

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

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

hits = db.vector.topk(
    "shop.products",
    query=query_768d,
    k=10,
    metric="l2",
)

const hits = await db.vectorTopk("shop.products", {
  query:  query768d,
  k:      10,
  dim:    768,
  metric: "l2",
});

hits, err := db.VectorTopK(ctx, "shop.products", originchain.VectorTopKRequest{
    Query:  query768d,
    K:      10,
    Dim:    768,
    Metric: "l2",
})

what you get back

{
  "hits": [
    { "id": "img-0421", "score": 0.1832 },
    { "id": "img-9912", "score": 0.2417 },
    { "id": "img-3308", "score": 0.3009 }
    /* ... up to k entries ... */
  ]
}

score is the L2 distance. Lower = closer. 0.0 means identical vectors. This is the reverse of cosine, so don't reuse a "sort descending" assumption from elsewhere in your code.

request fields

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.

common mistakes

Assuming higher score = closer. For L2 the order is reversed. The first hit has the lowest score. If you wrap results in your own UI, double-check the sort direction.
L2 on already-normalised vectors. If every vector has length 1, L2 and cosine give the same ranking but L2 is slightly more expensive. Pick cosine and move on.
Metric mismatch. The metric is locked at table creation. Switching from "cosine" to "l2" means creating a fresh table.