---
title: knn
url: https://nexyron.tech/docs/cypher/procedures/algorithms/similarity-and-embedding/knn
description: Return nearest neighbors by configured similarity.
---

# knn

## Generic Description

Return nearest neighbors by configured similarity.

Simple example:

```cypher
CALL nexyron.knn({property: 'embedding', k: 2})
```

Similarity and embedding procedures compare nodes by neighborhood overlap, random-walk context, or learned vector position. They are useful for link prediction, recommendations, deduplication, and candidate generation.

## Consumer-Level Explanation

Use `knn` when return nearest neighbors by configured similarity is the graph-analysis or operational question you actually need to answer. Keep the call explicit because its `YIELD` columns, row grain, and required runtime state determine how the rest of the Cypher pipeline can safely compose it. Structural similarity and embedding similarity are not the same: overlap metrics are explainable and local, while embeddings can capture broader context but need downstream validation.

## Conceptual Explanation

`knn` should be read as one named procedure contract in the broader Nexyron Cypher surface. The procedure call is not only a syntax hook: it defines what runtime state, projection, registry entry, or graph algorithm is being asked to operate, and it determines which output columns downstream `YIELD`, `WITH`, and `RETURN` stages can safely use.

## More Detailed Explanation

KNN differs from generic similarity output by emphasizing top-neighbor retrieval

In practical queries, start by deciding the row grain you want after the call: one row per node, one row per path, one row per registry object, one row per artifact, or one row per summary. Then keep that grain explicit with `YIELD` and named projections. That is the difference between a useful planner-facing example and a vague call that downstream tooling cannot safely compose. For contract-driven procedures, the executable examples on these pages intentionally inspect procedure metadata unless the required named artifacts are created in the same example.

## How It Differs From Nearby Algorithms

KNN differs from generic similarity output by emphasizing top-neighbor retrieval.

## Advanced Example

This example yields named columns from `knn` and returns a bounded result shape that downstream planner tooling can compose without guessing column names or row grain.

```cypher
CALL nexyron.knn({property: 'embedding', k: 2}) YIELD source, target, score
RETURN source, target, score
LIMIT 10
```

## Real Use Cases

-   recommendation candidates
-   entity neighborhood retrieval
-   graph-ML style nearest-neighbor steps
-   compare algorithm output with domain labels or time windows before operationalizing it
-   feed graph-analytic scores into ranked reports, feature contracts, or investigation queues only after checking the modeling assumptions

## Real Limitations And Tradeoffs

-   neighbor quality depends on the underlying representation and metric
-   algorithm output reflects the projected graph, not an abstract real-world network outside the data model
-   nearby algorithms can answer different questions even when their output columns look similar