Graph vector search

Description

The Graph vector search transform searches a vector index of a graph database for the nodes, or the relationships, nearest to the vector of every input row. It writes one output row per node or relationship found, nearest first, with the fields of the input row, the similarity score and the properties you pick.

It is the retrieval step of GraphRAG: embed the question with the Embed text transform, find the nearest nodes, then follow their relationships with a Graph query and feed the result to a language model. It works like the pgvector search transform, on a graph.

It works with graph database connections and Neo4j connections to databases with vector indexes:

Database Index What the database returns

Database	Index	What the database returns
Neo4j	By its name	A score between 0 and 1: (1 + cosine similarity) / 2 for cosine indexes, 1 / (1 + squared distance) for euclidean ones
Memgraph	By its name	A distance: 1 - cosine similarity for `cos` indexes, the squared distance for `l2sq` indexes
FalkorDB	By label and property: FalkorDB indexes have no name	A distance: 1 - cosine similarity for cosine indexes, the euclidean distance for euclidean indexes

Neo4j

By its name

A score between 0 and 1: (1 + cosine similarity) / 2 for cosine indexes, 1 / (1 + squared distance) for euclidean ones

Memgraph

By its name

A distance: 1 - cosine similarity for cos indexes, the squared distance for l2sq indexes

FalkorDB

By label and property: FalkorDB indexes have no name

A distance: 1 - cosine similarity for cosine indexes, the euclidean distance for euclidean indexes

The transform turns what the database returns into the same score on every database, with the Similarity function you set:

Similarity function Score Range

Similarity function	Score	Range
`COSINE`	The cosine similarity of the query vector and the stored vector, as in the pgvector search transform	-1 to 1: 1 for the same direction, 0 for perpendicular vectors, -1 for opposite vectors
`EUCLIDEAN`	1 / (1 + d²), where d is the euclidean distance between the query vector and the stored vector, as Neo4j scores it. pgvector search scores euclidean matches as 1 / (1 + d) instead.	0 to 1: 1 for the same vector

COSINE

The cosine similarity of the query vector and the stored vector, as in the pgvector search transform

-1 to 1: 1 for the same direction, 0 for perpendicular vectors, -1 for opposite vectors

EUCLIDEAN

1 / (1 + d²), where d is the euclidean distance between the query vector and the stored vector, as Neo4j scores it. pgvector search scores euclidean matches as 1 / (1 + d) instead.

0 to 1: 1 for the same vector

A higher score is always nearer, so a Minimum score means the same on every database. Under COSINE a minimum score of 0 drops the nodes more than 90 degrees from the query vector.

On other databases, like Amazon Neptune, Apache AGE and Gremlin servers, the transform fails when the pipeline starts.

Relationships

Set Search to RELATIONSHIP to search a vector index on relationships, for example embeddings of the text of a MENTIONS relationship. The returned properties are then read from the relationships found.

Database Index Procedure

Database	Index	Procedure
Neo4j 5.18 or later	By its name	`db.index.vector.queryRelationships`
Memgraph 3	By its name	`vector_search.search_edges`
FalkorDB	By relationship type and property, in the Node label or relationship type and Vector property options	`db.idx.vector.queryRelationships`

Neo4j 5.18 or later

By its name

db.index.vector.queryRelationships

Memgraph 3

By its name

vector_search.search_edges

FalkorDB

By relationship type and property, in the Node label or relationship type and Vector property options

db.idx.vector.queryRelationships

The scores are the same as for nodes. On a database without vector search over relationships the transform fails when the pipeline starts.

Create the vector index with the Graph index action, index type VECTOR and object type NODE or RELATIONSHIP, and write the vectors with Graph output, see Vectors and embeddings.

Options

Search tab

Option Description

Option	Description
Transform name	The name of the transform, unique in the pipeline.
Graph database connection	The connection to a database with vector indexes.
Search	`NODE` (the default) to search a vector index on nodes, `RELATIONSHIP` to search one on relationships.
Vector index name	The name of the vector index, on Neo4j and Memgraph.
Node label or relationship type	The label of the nodes, or the type of the relationships, with the vector index, on FalkorDB.
Vector property	The indexed property with the vectors, on FalkorDB.
Similarity function	The similarity function of the index, `COSINE` or `EUCLIDEAN`. Set the function the index was created with: the transform uses it to turn what the database returns into the score.
Query embedding field	The field with the vector to search for: a Vector field, or text like `[0.1,0.2,0.3]`.
Top K	The maximum number of nodes or relationships to find for every row.
Minimum score	Only return the nodes or relationships with at least this score. It is applied after the top K, so fewer than K rows can come back. Empty for no minimum.
Do not pass the row if the search finds nothing	Off by default: a row which finds nothing, or which has no vector, is passed on with empty search fields. On: the row is dropped.

Transform name

The name of the transform, unique in the pipeline.

Graph database connection

The connection to a database with vector indexes.

NODE (the default) to search a vector index on nodes, RELATIONSHIP to search one on relationships.

Vector index name

The name of the vector index, on Neo4j and Memgraph.

Node label or relationship type

The label of the nodes, or the type of the relationships, with the vector index, on FalkorDB.

Vector property

The indexed property with the vectors, on FalkorDB.

Similarity function

The similarity function of the index, COSINE or EUCLIDEAN. Set the function the index was created with: the transform uses it to turn what the database returns into the score.

Query embedding field

The field with the vector to search for: a Vector field, or text like [0.1,0.2,0.3].

Top K

The maximum number of nodes or relationships to find for every row.

Minimum score

Only return the nodes or relationships with at least this score. It is applied after the top K, so fewer than K rows can come back. Empty for no minimum.

Do not pass the row if the search finds nothing

Off by default: a row which finds nothing, or which has no vector, is passed on with empty search fields. On: the row is dropped.

Output tab

Option Description

Option	Description
Score field	The output field with the similarity score, higher for nearer nodes or relationships. Leave empty to leave the field out.
Returned properties	The properties of the nodes or relationships found to return. For every property: the property name, the output field (the property name when empty) and the Hop type of the field (String when empty). Give a property the type `Vector` to return a stored embedding as a Vector field.

Score field

The output field with the similarity score, higher for nearer nodes or relationships. Leave empty to leave the field out.

Returned properties

The properties of the nodes or relationships found to return. For every property: the property name, the output field (the property name when empty) and the Hop type of the field (String when empty). Give a property the type Vector to return a stored embedding as a Vector field.

Error handling

The transform supports error handling: a row whose search fails, for example because its vector has the wrong number of dimensions, goes to the error hop with error code GRAPHVECTORSEARCH001.