[BUG]: VectorCypherRetriever uses deprecated db.index.vector.queryNodes on Aura 5.27 even though SEARCH works

[martinohanlon]

Before You Report a Bug, Please Confirm You Have Done The Following...

• I have updated to the latest version of the packages.
• I have searched for both existing issues and closed issues and found none that matched my issue.

neo4j-graphrag-python's version

1.18.0

Python version

3.13.12

Operating System

Windows

Dependencies

annotated-types==0.8.0
anyio==4.14.2
certifi==2026.7.22
charset-normalizer==3.4.9
colorama==0.4.6
distro==1.9.0
fsspec==2026.7.0
h11==0.16.0
httpcore==1.0.9
httpcore2==2.10.0
httpx==0.28.1
httpx2==2.10.0
idna==3.18
jiter==0.16.0
json_repair==0.63.0
jsonpatch==1.33
jsonpointer==3.1.1
langchain==1.3.15
langchain-core==1.5.4
langchain-openai==1.4.3
langchain-protocol==0.0.18
langgraph==1.2.11
langgraph-checkpoint==4.2.0
langgraph-prebuilt==1.1.0
langgraph-sdk==0.4.2
langsmith==0.10.18
markdown-it-py==4.2.0
mdurl==0.1.2
neo4j==6.2.0
neo4j-graphrag==1.18.0
numpy==2.5.2
openai==2.54.0
orjson==3.11.9
ormsgpack==1.12.2
packaging==26.3
pydantic==2.13.4
pydantic_core==2.46.4
Pygments==2.20.0
pypdf==6.15.0
python-dotenv==1.2.2
pytz==2026.3.post1
PyYAML==6.0.3
regex==2026.7.19
requests==2.34.2
requests-toolbelt==1.0.0
rich==15.0.0
scipy==1.18.0
sniffio==1.3.1
tenacity==9.1.4
tiktoken==0.13.0
tqdm==4.70.0
truststore==0.10.4
types-PyYAML==6.0.12.20260724
typing-inspection==0.4.3
typing_extensions==4.16.0
urllib3==2.7.0
uuid_utils==0.17.0
websockets==15.0.1
xxhash==3.8.1
zstandard==0.25.0

Reproducible example

// Create graph

DROP INDEX chunkEmbedding IF EXISTS;
MATCH (c:Chunk) DETACH DELETE c;

CREATE (c:Chunk {
text: "minimal repro chunk",
embedding: [0.1, 0.2, 0.3]
});

CALL db.index.vector.createNodeIndex(
"chunkEmbedding",
"Chunk",
"embedding",
3,
"cosine"
);

# Python code
import os
from dotenv import load_dotenv
from neo4j import GraphDatabase
from neo4j_graphrag.retrievers import VectorCypherRetriever

load_dotenv()

driver = GraphDatabase.driver(
    os.getenv("NEO4J_URI"),
    auth=(os.getenv("NEO4J_USERNAME"), os.getenv("NEO4J_PASSWORD")),
)

retriever = VectorCypherRetriever(
    driver=driver,
    index_name="chunkEmbedding",
    retrieval_query="RETURN node.text AS text, score",
    neo4j_database=os.getenv("NEO4J_DATABASE"),
)

result = retriever.search(
    query_vector=[0.1, 0.2, 0.3],
    top_k=1,
)

Relevant Log Output

Runtime warning from server:

Received notification from DBMS server: warn: feature deprecated with replacement.
db.index.vector.queryNodes is deprecated. It is replaced by SEARCH.

Generated query starts with:

CALL db.index.vector.queryNodes($vector_index_name, $top_k * $effective_search_ratio, $query_vector)

Expected Result

When SEARCH is available on the connected database, VectorCypherRetriever should use SEARCH instead of db.index.vector.queryNodes, or at least avoid triggering a deprecation warning on normal retrieval paths.

What happened instead?

The retriever uses db.index.vector.queryNodes and Aura returns a deprecation warning on each retrieval query.

Additional Info

Connected DB reports:

• Neo4j Kernel
• 5.27-aura
• enterprise

This suggests the fallback/version gating used by the retriever may be too strict for Aura 5.27, or not aligned with actual SEARCH availability on Aura.

[Aryan-Pardeshi]

Thanks for the report. Root cause confirmed: supports_search_clause compared every server against (2026, 1, 0), but Aura kept the 5.x version scheme after self-managed servers moved to year-based versions, so 5.27-aura never passed the gate even though the Aura March release line GA'd the Cypher 25 SEARCH clause.

Opened #605: Aura 5.27+ is now treated as SEARCH-capable, self-managed 5.x keeps the procedure path, and the existing ClientError fallback still covers any wrong guess.

[jexp]

There was a released in between that fixed it: #550
please test 1.19.0

thank you

[samvallad33]

VectorCypherRetriever still using deprecated db.index.vector.queryNodes on Aura 5.27 when SEARCH works risks checkpointed recall breaking on newer clusters. Sessions then fail retrieval on platforms that already moved on. Are you switching to SEARCH and gating the deprecated path behind a version check?