DISTANCE

A nearest-neighbour sphere around a single anchor — the "close to this" clause.

DISTANCE defines a sphere in embedding space around one anchor. A message matches when its similarity to that anchor is at least within, or when it is among the top_k nearest.

MATCH DISTANCE("payment reconciliation failure") WITHIN 0.82
NAMESPACE "org:acme-corp"
LIMIT 20

{
  "match": { "distance": { "anchor": "payment reconciliation failure", "within": 0.82 } },
  "namespace": { "include": ["org:acme-corp"] },
  "limit": 20
}

Fields

within is a floor, not a radius

within is a minimum cosine similarity. A higher value is stricter, not looser.

This trips people up because the clause is named DISTANCE, and a distance threshold would work the other way round. It does not: WITHIN 0.9 is a tight match and WITHIN 0.2 is a very loose one. 0 means no floor at all.

Values outside [0, 1] are rejected.

The published specification's examples use values like WITHIN 0.3 in contexts that read as narrow matches. Read those as deliberately loose. The reference parser is the authority here, and it treats the field as a floor.

within and top_k are mutually exclusive

Setting both is an error — they are two different ways of deciding how much to return, and there is no sensible meaning for their combination:

distance: cannot specify both within and top_k

Setting neither is allowed. The clause then contributes a score with no hard threshold, which is useful when another clause in the query does the filtering.

metric has no text form

metric exists only in the JSON form. There is no METRIC keyword in the text syntax, so a query using "euclidean" or "dot" cannot be written as text, and converting such a query to text and back silently returns it to "cosine".

If you need a non-default metric, keep the query in its JSON form. See the wire format for the full picture.

Grammar

distance_clause = "DISTANCE" "(" anchor ")" [ distance_opts ] ;
distance_opts   = "WITHIN" number
                | "TOP" integer ;

Errors