Skip to content

Neo4j version 5 compatibility#20805

Open
Hannibal0319 wants to merge 5 commits intorun-llama:mainfrom
Hannibal0319:neo4j-version-5-compatibility
Open

Neo4j version 5 compatibility#20805
Hannibal0319 wants to merge 5 commits intorun-llama:mainfrom
Hannibal0319:neo4j-version-5-compatibility

Conversation

@Hannibal0319
Copy link

Description

This PR fixes Neo4j 5 compatibility issues in the llama-index-graph-stores-neo4j integration.
Specifically, Neo4j 5 removed support for the legacy subquery syntax:

CALL (e, row) { ... }

and introduced stricter rules for subquery variable importing (e.g., WITH inside CALL {} must only contain simple references).
This change updates all affected Cypher templates to use Neo4j 5–compatible syntax:

Replaces CALL (vars) {} with CALL { WITH vars ... }
Splits importing WITH and filtering WHERE clauses into separate WITH statements to satisfy Neo4j 5 parser constraints

This ensures compatibility with:

neo4j >= 5.16
llama-index-core >= 0.14.x
llama-index-graph-stores-neo4j 0.5.x

Motivation

Users running modern Neo4j 5 installations encountered CypherSyntaxError due to deprecated subquery syntax and stricter scoping rules. Since the package requires Neo4j 5, updating the Cypher templates is necessary for correct operation.

This change resolves runtime failures when:

Inserting nodes with embeddings
Expanding entity relations
Executing subgraph retrieval queries

Issue: #17227

Checklist

Did I fill in the tool.llamahub section in the pyproject.toml and provide a detailed README.md for my new integration or package?

  • Yes
  • No

Version Bump?

Did I bump the version in the pyproject.toml file of the package I am updating? (Except for the llama-index-core package)

  • Yes
  • No

Type of Change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

Your pull-request will likely not be merged unless it is covered by some form of impactful unit testing.

  • I added new unit tests to cover this change
  • I believe this change is already covered by existing unit tests

Suggested Checklist:

  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • I have added Google Colab support for the newly added notebooks.
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I ran uv run make format; uv run make lint to appease the lint gods

@dosubot dosubot bot added the size:M This PR changes 30-99 lines, ignoring generated files. label Feb 26, 2026
Copy link
Member

@AstraBert AstraBert left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A migration to Neo4J 5 would require:

  • Putting Neo4J 5.x as the minimum required version for this integration
  • Bumping the integration version (minor or major)
  • Making sure there are no other patterns that are no longer supported in Neo4J 5, besides the one addressed in this PR

CALL (e, row) {{
CALL {{
WITH e, row
WITH e, row
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the duplication?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because the scope of the CALL and the following WHERE asks for it.
Neo4j 5 minimum is already enforced via dependencies in the integration packages.
All others i will fix

Comment on lines +498 to 500
CALL {{
WITH e
WITH e
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also here it is duplicated

@dosubot dosubot bot added the lgtm This PR has been approved by a maintainer label Mar 2, 2026
@AstraBert
Copy link
Member

Tests are failing, we should fix them before merging

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lgtm This PR has been approved by a maintainer size:M This PR changes 30-99 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants