LanceDB search metric must match the index metric or the index is skipped

TL;DR

Build the index and query with the same metric: l2, cosine, or dot (hamming is IVF_FLAT only). If you omit the metric, current SDKs inherit the index metric, but on older SDK versions set it explicitly to match. If a Cloud search gets rejected by the KNN safety limit, check for a metric mismatch before anything else.

Fix

Build the index and query with the same metric: l2, cosine, or dot (hamming is IVF_FLAT only). If you omit the metric, current SDKs inherit the index metric, but on older SDK versions set it explicitly to match. If a Cloud search gets rejected by the KNN safety limit, check for a metric mismatch before anything else.

Context: Official docs (vector search): documents the gotcha that a LanceDB vector search must use the same distance metric the index was built with. Request a different metric and LanceDB cannot use the index, falling back to an exhaustive brute-force search. On LanceDB Cloud the brute-force KNN safety limit can reject that search outright on a large table. Older SDKs also sent l2 when the metric was omitted, silently mismatching non-l2 indexes.

Matched source

Source: Published skill Original query: "LanceDB search metric must match the index metric or the index is skipped" Key terms: index, lancedb, match, metric, must, search, skipped

When to use this

• Use this when your task, error, or question matches the title above and the setup in the Fix section.

When not to use this

• Skip it when the error text, tool, or situation is different. Forcing a mismatched fix usually costs more time than searching again.

Compatibility

The original write-up does not pin tool versions. Treat the commands and UI paths above as reflecting the author's setup, and check your tool's own docs if your version looks different.

Source: Official docs (vector search): documents the gotcha that a LanceDB vector search must use the same distance metric the index was built with. Request a different metric and LanceDB cannot use the index, falling back to an exhaustive brute-force search. On LanceDB Cloud the brute-force KNN safety limit can reject that search outright on a large table. Older SDKs also sent l2 when the metric was omitted, silently mismatching non-l2 indexes.

Verified resolution: Build the index and query with the same metric: l2, cosine, or dot (hamming is IVF_FLAT only). If you omit the metric, current SDKs inherit the index metric, but on older SDK versions set it explicitly to match. If a Cloud search gets rejected by the KNN safety limit, check for a metric mismatch before anything else.

Source URL: https://github.com/lancedb/docs/blob/HEAD/docs/search/vector-search.mdx