issues about VectorCypherRetriever

[KaitouKK]

I'm using the neo4j_graphrag Python package to build a GraphRAG knowledge base. I'm encountering an issue where my retrieval query returns multiple results even when setting top_k=1. Here's the relevant code:
INDEX_NAME = "Task" retrieval_query = f"MATCH p=(n:Task)-->(o:Operation)-->(e:Element) WHERE \"{tmp_goal}\" CONTAINS e.name RETURN score, n.id ORDER BY score DESC" retriever = VectorCypherRetriever(driver, INDEX_NAME, embedder=embedder, retrieval_query=retrieval_query) pattern = r'<Record n\.id=(\d+)>' tmp_result = retriever.search(query_text=tmp_goal, top_k=1).items print(tmp_result)
My goal is to retrieve only the most relevant Task node by setting top_k=1, but the output still contains multiple results. Could you help explain why this is happening and how to fix it?

[stellasia]

Hi @KaitouKK ,

A few points regarding your question

1. In the VectorCypherRetriever, the retrieval query is executed after the vector search query which is something like this:

CALL db.index.vector.queryNodes($vector_index_name, $top_k * $effective_search_ratio, $query_vector)
YIELD node, score
WITH node, score LIMIT $top_k

So the idea behind this retriever is to start from the vector search query, and explore the graph from the indexed nodes.

I do not know your graph structure, but I can't see any use of the node variable in your query, which is probably causing unintended behavior. You can try to run the full query in your Neo4j browser to see the result

2. As you can see from above, top_k is only applied to the vector search part of the query. Depending on the retrieval query, the number of records returned can be greater than top_k, this is expected. For instance, if you have a vector index on the movie's plot embedding, the node variable will be a Movie node, and if you use the following retrieval query:

MATCH (node)<-[:ACTED_IN]-(person)
RETURN node.title, node.plot, person.name

Then you'll get as many rows as actors in the selected movie (when using top_k=1)

Hope that helps, let me know if you have any further question.

[onestardao]

This looks like a “Semantic ≠ Embedding” edge case — the vector stage might be returning near-ties in similarity, so top_k=1 still passes multiple nodes through if they share the same score within a rounding tolerance.
You could check if the retriever or post-query filtering is normalizing scores and breaking ties as expected.

[stellasia]

so top_k=1 still passes multiple nodes through if they share the same score within a rounding tolerance.

This is not possible, for two reasons:

1. The vector index query method always return the number of specified nodes, even if multiple nodes share the same score. If you have proof of the opposite, please open an issue in the neo4j repo with reproducible example.
2. In this package, we use the effective_search_ratio feature, which consists in retrieving more nodes from the vector index and applying a LIMIT $top_k afterward, so after the similarity search, we are 100% sure there are only top_k records.

[onestardao]

thanks for the follow-up quick clarification:

we’re not claiming the vector index returns duplicate nodes. the issue we see is at the Cypher layer:
(1) LIMIT applied after expand multiplies rows, so LIMIT trims multiplied rows, not unique top-K nodes.
(2) near-tie scores wobble membership without a stable second key.

two minimal fixes:

• isolate vector query in a subquery, ORDER BY score, id(node) and LIMIT before any expand.
• over-fetch a little, then apply an epsilon threshold + stable tiebreak.

happy to provide a tiny repro if helpful.