K-Nearest Neighbors (KNN)

Overview

KNN (K-Nearest Neighbors) finds the K most similar nodes for each node based on neighborhood structure. Useful for building similarity graphs and recommendation systems. For each node, the algorithm identifies its K closest neighbors by comparing neighborhood overlap using the specified similarity metric: jaccard, cosine, or overlap.

Three metrics are supported:

• Jaccard: Intersection over union of neighbor sets. See Jaccard Similarity for details.
• Overlap: Intersection over the smaller neighbor set. See Overlap Similarity for details.
• Cosine: Cosine similarity between node property vectors. See Cosine Similarity for details.

Example Graph

GQL
INSERT (Sue:user {_id: "Sue", age: 28, score: 85}),
       (Dave:user {_id: "Dave", age: 35, score: 72}),
       (Ann:user {_id: "Ann", age: 30, score: 90}),
       (Mark:user {_id: "Mark", age: 32, score: 78}),
       (May:user {_id: "May", age: 26, score: 88}),
       (Jay:user {_id: "Jay", age: 29, score: 82}),
       (Billy:user {_id: "Billy", age: 24, score: 65}),
       (Dave)-[:know]->(Sue), (Dave)-[:know]->(Ann),
       (Mark)-[:know]->(Dave), (May)-[:know]->(Mark),
       (May)-[:know]->(Jay), (Jay)-[:know]->(Ann),
       (Ann)-[:know]->(Billy), (Mark)-[:know]->(Ann)

Parameters

Run Mode

Returns:

GQL
CALL algo.knn({
  k: 2,
  metric: "jaccard"
}) YIELD node1, node2, similarity, rank

Result:

Stream Mode

Returns the same columns as run mode, streamed for memory efficiency.

GQL
CALL algo.knn.stream({
  k: 1,
  metric: "cosine",
  node_property: ["age", "score"]
}) YIELD node1, node2, similarity, rank
RETURN node1, node2, similarity, rank

Result:

Stats Mode

Returns:

GQL
CALL algo.knn.stats({
  k: 3,
  metric: "overlap"
}) YIELD nodeCount, pairCount, minSimilarity, maxSimilarity, avgSimilarity

Result:

Write Mode

Computes results and writes them back to node properties. The write configuration is passed as a second argument map.

Write parameters:

Writable columns:

Returns:

GQL
CALL algo.knn.write({k: 5, metric: "jaccard"}, {
  db: {
    property: "sim_score"
  }
}) YIELD task_id, nodesWritten, computeTimeMs, writeTimeMs