# Distance metrics

## Available distance metrics

If not specified explicitly, the default distance metric in Weaviate is
`cosine`. It can be [set in the vectorIndexConfig](indexing-vector-index.md#hnsw-index) field as part of the schema ([example](../how-to-manage-collections/vector-config.md#specify-a-distance-metric)) to any of the following types:

:::callout{intent="tip" title="Comparing distances"}
In all cases, larger distance values indicate lower similarity. Conversely, smaller distance values indicate higher similarity.
:::

<!-- TODO: Consider removing  -->

| Name         | Description                                                                                                              | Definition                    | Range           | Examples                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------- | --------------- | --------------------------------------------------------------- |
| `cosine`     | Cosine (angular) distance. <br>:sub[See note 1 below]                                                                    | `1 - cosine_sim(a,b)`         | `0 <= d <= 2`   | `0`: identical vectors<br><br> `2`: Opposing vectors.           |
| `dot`        | A dot product-based indication of distance. <br><br>More precisely, the negative dot product. <br>:sub[See note 2 below] | `-dot(a,b)`                   | `-∞ < d < ∞`    | `-3`: more similar than `-2` <br><br>`2`: more similar than `5` |
| `l2-squared` | The squared euclidean distance between two vectors.                                                                      | `sum((a_i - b_i)^2)`          | `0 <= d < ∞`    | `0`: identical vectors                                          |
| `hamming`    | Number of differences between vectors at each dimensions.                                                                | `sum(&#124;a_i != b_i&#124;)` | `0 <= d < dims` | `0`: identical vectors                                          |
| `manhattan`  | The distance between two vector dimensions measured along axes at right angles.                                          | `sum(&#124;a_i - b_i&#124;)`  | `0 <= d < ∞`    | `0`: identical vectors                                          |

If you're missing your favorite distance type and would like to contribute it to Weaviate, we'd be happy to review your [PR](https://github.com/weaviate/weaviate).

:::callout{intent="note" title="Additional notes"}
1. If `cosine` is chosen, all vectors are normalized to length 1 at read time and dot product is used to calculate the distance for computational efficiency.
2. Dot Product on its own is a similarity metric, not a distance metric. As a result, Weaviate returns the negative dot product to stick with the intuition that a smaller value of a distance indicates a more similar result and a higher distance value indicates a less similar result.
3. The [HFresh index](indexing-vector-index.md#hfresh-index) only supports `cosine` and `l2-squared` distance metrics.
:::

## Distance implementations and optimizations

On a typical Weaviate use case the largest portion of CPU time is spent calculating vector distances. Even with an approximate nearest neighbor index - which leads to far fewer calculations - the efficiency of distance calculations has a major impact on [overall performance](../benchmarks/ann.md).

Weaviate uses SIMD (Single Instruction, Multiple Data) instructions for the following distance metrics and architectures. The available optimizations are resolved in the shown order (e.g. SVE -> Neon).

| Distance                      | `arm64`     | `amd64`                                       |
| ----------------------------- | ----------- | --------------------------------------------- |
| `cosine`, `dot`, `l2-squared` | SVE or Neon | Sapphire Rapids with AVX512, or Any with AVX2 |
| `hamming`, `manhattan`        | No SIMD     | No SIMD                                       |

If you like dealing with Assembly programming, SIMD, and vector instruction sets we would love to receive your contribution for one of the combinations that have not yet received an SIMD-specific optimization.

## Distance fields in the APIs

The `distance` is exposed in the APIs in two ways:

- Whenever a [vector search](../how-to-query-search/similarity.md#set-a-similarity-threshold) is involved, the distance can be displayed as part of the results, for example using `_additional { distance }`
- Whenever a [vector search](../how-to-query-search/similarity.md#set-a-similarity-threshold) is involved, the distance can be specified as a limiting criterion, for example using `nearVector({distance: 1.5, vector: ... })`

## Distance vs Certainty

Prior to version `v1.14` only `certainty` was available in the APIs. The
original ideas behind certainty was to normalize the distance score into a
value between `0 <= certainty <= 1`, where 1 would represent identical vectors
and 0 would represent opposite vectors.

This concept is however unique to `cosine` distance. With other distance
metrics, scores may be unbounded. As a result the preferred way is to use
`distance` in favor of `certainty`.

For backward compatibility, `certainty` can still be used when the distance is
`cosine`. If any other distance is selected `certainty` cannot be used.

See also [Search API: Additional properties (metadata)](../apis/graphql-additional-properties.md).

## Further resources

- [How-to: Manage collections](../how-to-manage-collections/index.md)
- [REST API: Collection definition (schema)](/weaviate/api/rest#tag/schema)
- [Concepts: Data structure](../concepts/data.md)

## Questions and feedback

Have a question or feedback? Here's how to reach us.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.