Data store

Implementation of BaseDataStore for Neo4j.

Neo4jDataStore(uri, user, password, max_connection_pool_size=50, database=None, retry_config=None, **kwargs)

Bases: BaseDataStore

Neo4j data store implementation.

Provides a Neo4j-backed datastore exposing graph capability. Each instance is bound to a single Neo4j database; operations like get_size are scoped to that database.

Attributes:

Name	Type	Description
driver	AsyncDriver	The Neo4j async driver instance for database connection.
retry_config	RetryConfig	Retry configuration applied to query operations.

Initialize the Neo4jDataStore instance.

Note

Constructing the driver does not open a connection. Connections are established lazily on the first session/query. To eagerly validate connectivity, call await driver.verify_connectivity() after construction.

Parameters:

Name	Type	Description	Default
uri	str	The URI of the Neo4j instance (e.g. bolt://localhost:7687).	required
user	str	Username for authentication.	required
password	str	Password for authentication.	required
max_connection_pool_size	int	The maximum size of the driver's connection pool. Defaults to 50.	50
database	str | None	Name of the Neo4j database to bind this instance to. When None, sessions use the user's home/default database as configured on the server, which from the client's perspective is opaque. Set this explicitly for deterministic routing. Defaults to None.	None
retry_config	RetryConfig | None	Retry policy for query operations. When a database operation fails with a retryable exception (e.g. neo4j.exceptions.ServiceUnavailable), the operation is retried according to this policy. Defaults to None, in which case a sensible default (3 retries, 0.5s base / 5.0s max delay) is used.	None
**kwargs	Any	Additional keyword arguments forwarded to AsyncGraphDatabase.driver (e.g. connection_timeout, encrypted).	{}

graph property

Access the graph capability handler.

This override narrows the return type for better IDE/type-checker support.

Returns:

Name	Type	Description
Neo4jGraphCapability	Neo4jGraphCapability	Graph capability handler.

Raises:

Type	Description
NotRegisteredException	If the graph capability has not been registered yet via with_graph().

query_translator_class = Neo4jQueryTranslator class-attribute instance-attribute

Class attribute used to build Cypher filter components. Override at the class level to customize translation while keeping the rest of the wiring intact.

supported_capabilities property

Return the list of capabilities supported by this data store.

Returns:

Type	Description
list[CapabilityType]	list[CapabilityType]: Supported capabilities. Neo4jDataStore supports graph only.

close() async

Close the underlying Neo4j driver and release pooled connections.

get_size(filters=None) async

Return the total number of nodes plus relationships in the bound database.

The count is scoped to self._database (or the server's home/default database when self._database is None).

When filters is provided, the filter is applied to nodes (alias n) and the relationship count is restricted to relationships whose both endpoints belong to the filtered node set. This yields the size of the subgraph induced by the filter.

Note

This performs a full scan and is O(N) on graph size. Avoid on very large graphs unless necessary.

Parameters:

Name	Type	Description	Default
filters	FilterClause | QueryFilter | None	Filters applied to nodes via :class:Neo4jQueryTranslator. FilterClause is normalized to QueryFilter. Defaults to None.	None

Returns:

Name	Type	Description
int	int	count(matching_nodes) + count(relationships_within_match) in the bound database.

Raises:

Type	Description
ValueError	If filters is provided but contains no clause that the translator can map to Cypher.
RuntimeError	If the underlying query fails.

translate_query_filter(query_filter, **kwargs) classmethod

Translate a QueryFilter / FilterClause into Cypher components.

Parameters:

Name	Type	Description	Default
query_filter	FilterClause | QueryFilter	Filter to translate. A bare FilterClause is wrapped in an AND QueryFilter automatically.	required
**kwargs	Any	Translator overrides. Supported keys: alias (str): Cypher variable for the filtered entity. Defaults to "n".	{}

Returns:

Name	Type	Description
Neo4jQueryComponents	Neo4jQueryComponents	Components containing the WHERE clause and bind params. When the filter is empty or contains only unsupported clauses, where_clause is None and params is empty.

with_graph(**kwargs)

Configure the graph capability and return the datastore instance.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional graph-capability configuration parameters.	{}

Returns:

Name	Type	Description
Neo4jDataStore	Neo4jDataStore	Self for method chaining.