# Pairwise similarity functions

[Wiki](../README.md) / [Graph data science](README.md)

## Data-science similarity functions

Numerical vector similarity uses equal-length lists; set similarities may use
different lengths. The `gds.similarity.*` forms return the named measure;
the `vector.similarity.*` forms return a normalised
`[0, 1]` cosine or `(0, 1]` Euclidean score (higher = more similar).

| Function | Measure |
|---|---|
| `gds.similarity.cosine(a, b)` | Cosine similarity |
| `gds.similarity.euclidean(a, b)` | `1 / (1 + Euclidean distance)` |
| `gds.similarity.euclideanDistance(a, b)` | Euclidean distance |
| `gds.similarity.pearson(a, b)` | Pearson correlation |
| `gds.similarity.jaccard(a, b)` | Jaccard similarity |
| `gds.similarity.overlap(a, b)` | Overlap coefficient |
| `gds.similarity.dotProduct(a, b)` | Dot product |
| `vector.similarity.cosine(a, b)` | `(1 + cosine) / 2`, in `[0,1]` |
| `vector.similarity.euclidean(a, b)` | `1 / (1 + distance²)`, in `(0,1]` |

## Vector norm and normalisation

| Function | Result |
|---|---|
| `vector.norm.euclidean(v)` | Euclidean (L2) length of `v` |
| `vector.normalize(v)` | `v` scaled to unit Euclidean length; a zero vector is returned unchanged |

Both return `null` for a null or non-numeric list. FastRP embeddings are not
normalised after the final weighted sum, so normalise them when a consumer
expects unit vectors:

```cypher
RETURN gds.similarity.cosine([1, 0, 1], [1, 1, 0]) AS cos;
RETURN vector.similarity.euclidean([0, 0], [3, 4]) AS score;
RETURN vector.norm.euclidean([3, 4]) AS length;            // 5.0
MATCH (n) WHERE n.embedding IS NOT NULL
SET n.embedding = vector.normalize(n.embedding);
```

These are NULL-lenient: incompatible inputs (length mismatch for numerical
vectors, non-numeric values) yield `null`. GDS ignores null members for Jaccard
and Overlap and substitutes zero for null numerical entries in cosine, Euclidean and Pearson.
`dotProduct` requires numeric entries; a null entry yields null. Vector
index functions keep their existing null handling.

`gds.util.asNode(id)` and `gds.util.asNodes(ids)` resolve live nodes.
The additional APOC `sortMaps`, `sortMulti` and `groupByMulti` functions are
documented in [APOC traversal and utilities](../apoc/traversal.md).

## Related articles

[Graph projections and catalogue](projections.md) · [GDS algorithms and execution modes](algorithms.md) · [GDS resources and cancellation](resources.md) · [Graph data science](README.md)
