In Weaviate, how do the distance and certainty thresholds on near_text differ?

## Two dials on the same search Every Weaviate vector query returns objects ordered from closest to furthest. `limit` cuts that ordered list at a fixed position; a threshold cuts it wherever quality falls off. They answer different questions — "how many do I want?" versus "how bad am I willing to accept?" — and production queries usually need both. ## distance: a maximum, lower is better ```python response = collection.query.near_text( query="noise cancelling headphones", limit=10, distance=0.25, return_metadata=MetadataQuery(distance=True), ) ``` `distance` is an upper bound. Anything whose distance from the query vector exceeds the value is excluded, no matter how few results survive. The scale is defined by the distance metric the collection was created with, and this is where people get burned: 0.25 is a tight cutoff under cosine distance and a meaningless one under squared-L2, where distances are unbounded and scale with vector magnitude and dimensionality. There is no universal good value. The only honest way to pick one is to run representative queries with `return_metadata=MetadataQuery(distance=True)`, look at the distances of results you judge good and bad, and set the cutoff between them. ## certainty: a minimum, higher is better, cosine only `certainty` presents the same underlying similarity on a friendlier scale: 0 to 1, higher is closer, and it reads like a confidence. It is derived from cosine distance, so it exists only for collections using the cosine metric. Ask for certainty on a dot-product or L2 collection and the server rejects the request rather than inventing a normalisation. Because the two express the same quantity, specifying both in one query is contradictory and is not allowed. Pick the scale your team reasons about more naturally and stick to it. Teams that display a "match score" in a UI tend to prefer certainty; teams that tune retrieval offline tend to prefer distance because it is the raw number the index works with. ## Thresholds and limit compose The two are applied together, and the tighter one wins: - `limit=10, distance=0.25` → up to ten results, all within 0.25. Could be ten, could be three, could be none. - `limit=100, distance=0.9` (cosine) → probably a hundred results, most of them poor, because the cutoff is loose. - `limit=10` with no threshold → always ten results if the collection holds ten objects, however irrelevant they are. That last line is the failure mode a threshold exists to prevent. A bare `limit` on a nearest-neighbour search *always* returns something. Ask a question your corpus has no answer to and you still get the ten least-bad vectors, ranked confidently. Downstream that becomes a language model summarising documents that were never relevant. A distance cutoff is how you let a search legitimately return nothing. ## Empty results are a feature, not a bug The most common reaction to a threshold is alarm when a query returns zero rows. Before loosening the cutoff, check what the distances actually were. If the closest object sits at 0.4 and your cutoff is 0.25, the search worked correctly and told you something true: the corpus has no good answer. Loosening the cutoff does not create a good answer, it hides the absence of one. ## Practical tuning loop 1. Collect twenty or thirty realistic queries, including some that should have no answer. 2. Run them with a generous `limit`, no threshold, and `return_metadata=MetadataQuery(distance=True)`. 3. Hand-label which returned objects are actually relevant. 4. Plot or eyeball the distances: relevant hits cluster low, irrelevant hits cluster higher, and there is usually a visible gap. 5. Put the cutoff in the gap, then re-run the no-answer queries to confirm they now come back empty. Re-run that loop whenever the embedding model changes. Distances are a property of the vector space, so a new model invalidates every threshold you tuned against the old one — a migration cost that is easy to forget precisely because nothing errors. ## When a fixed threshold is the wrong tool A fixed cutoff assumes distances are comparable across queries. For heterogeneous corpora that assumption is shaky: short queries, rare terms and unusual phrasings all shift the whole distance distribution. When per-query distributions vary that much, a relative cut based on where the results drop off is a better fit than any single absolute number, and Weaviate offers that as a separate option on the same query.