Query translator

Neo4j query translator for converting FilterClause / QueryFilter to Cypher WHERE clauses.

This module defines :class:Neo4jQueryTranslator, which converts the portable QueryFilter DSL into a Cypher boolean expression plus a parameter dict suitable for use with session.run(query, **params).

Neo4jQueryComponents(where_clause=None, params=dict()) dataclass

Components of a translated Cypher filter.

Attributes:

Name	Type	Description
where_clause	str | None	Boolean Cypher expression to place after a WHERE keyword, or None when the filter resolves to no constraints.
params	dict[str, Any]	Bind parameters referenced by where_clause. Keys match the placeholders ($p0, $p1 ...) used in the clause.

has_filters property

Return True when the components carry an actual constraint.

Neo4jQueryTranslator(alias='n')

Translate QueryFilter / FilterClause into Cypher (WHERE clause + params).

The translator targets a single graph entity referenced by alias (default "n"). Filter keys are interpreted as follows:

• label — node label. Supports EQ, NE, IN, NIN. Translated via labels(<alias>) so it works in both MATCH and WHERE contexts.
• properties.<name> or <name> — node property. Property names must be valid Cypher identifiers ([A-Za-z_][A-Za-z0-9_]*) — nested paths are not supported because Neo4j stores properties flat per node.

Operators that have no natural Cypher equivalent are dropped (return None) rather than raising; this matches the behaviour of the SQL/Postgres translators in this library.

Initialize the translator.

Parameters:

Name	Type	Description	Default
alias	str	Cypher variable for the entity being filtered (e.g. "n" for nodes, "r" for relationships). Must be a valid Cypher identifier. Defaults to "n".	'n'

Raises:

Type	Description
ValueError	If alias is not a valid identifier.

translate(filters)

Translate a filter into a Cypher WHERE clause + bind params.

Parameters:

Name	Type	Description	Default
filters	FilterClause | QueryFilter | None	Filter to translate. A FilterClause is wrapped in an AND QueryFilter automatically. None or an empty QueryFilter yields empty components.	required

Returns:

Name	Type	Description
Neo4jQueryComponents	Neo4jQueryComponents	where_clause is None when no constraint is produced; params is then empty.