[BUG]: VectorCypherRetriever: filtered vector search fails because _node_embedding_property is never populated

[mhmgad]

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.17

Python version

3.14.5

Operating System

macOs

Dependencies

neo4j-graphrag==1.17.0
neo4j==6.1.0
pydantic==2.13.x

Reproducible example

import neo4j
from neo4j_graphrag.retrievers import VectorCypherRetriever

URI = "neo4j://localhost:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "my-vector-index"  # existing vector index in Neo4j

driver = neo4j.GraphDatabase.driver(URI, auth=AUTH)

retriever = VectorCypherRetriever(
    driver=driver,
    index_name=INDEX_NAME,
    retrieval_query="RETURN node, score",
    neo4j_database="neo4j",
)

# Use query_vector to avoid needing an embedder; length must match index dimensions.
query_vector = [0.1] * 1024

retriever.search(
    query_vector=query_vector,
    top_k=5,
    filters={"organization": {"$eq": "organization"}},
)

Relevant Log Output

File "neo4j_graphrag/retrievers/base.py", line 154, in search
    raw_result = self.get_search_results(*args, **kwargs)
File "neo4j_graphrag/retrievers/vector.py", line 502, in get_search_results
    search_query, search_params = get_search_query(
File "neo4j_graphrag/neo4j_queries.py", line 370, in get_search_query
    raise Exception(
        "Vector Search with filters requires: node_label, embedding_node_property, embedding_dimension"
    )

Exception: Vector Search with filters requires: node_label, embedding_node_property, embedding_dimension

Expected Result

VectorCypherRetriever.search(..., filters={...}) should run filtered vector search when the index exists and SHOW VECTOR INDEXES returns label, embedding property, and dimensions

What happened instead?

Search fails immediately with the exception above, even though the index exists and _fetch_index_infos() runs successfully during retriever initialization.

Root cause: attribute naming mismatch between the base Retriever and VectorCypherRetriever:

Retriever._fetch_index_infos() (neo4j_graphrag/retrievers/base.py) sets:

self._node_label = result["labels"][0]
self._embedding_node_property = result["properties"][0]
self._embedding_dimension = result["dimensions"]

VectorCypherRetriever (neo4j_graphrag/retrievers/vector.py) initializes and reads a different attribute:

# __init__
self._node_embedding_property = None

# get_search_results (procedure-based fallback path)
embedding_node_property=self._node_embedding_property,  # which is always None only with VectorCypherRetriever

VectorRetriever uses _embedding_node_property consistently and is not affected. Only VectorCypherRetriever is broken when filters is provided (including when falling back from the SEARCH clause path).

Additional Info

Workaround that worked:

class FixedVectorCypherRetriever(VectorCypherRetriever):
    def _fetch_index_infos(self, vector_index_name: str) -> None:
        super()._fetch_index_infos(vector_index_name)
        self._node_embedding_property = self._embedding_node_property

Note: opus 4.8 was used for tracing the internals of the library

[mhmgad]

#335 seems the same issue but it is closed without answer