Graph capability

Base class definition for graph database operations.

This module defines BaseGraphCapability that all datastores supporting graph operations should implement. It provides operations for nodes, relationships, and graph queries.

BaseGraphCapability

Bases: ABC

Base class for graph database operations.

This base class defines the interface for datastores that support graph-based data operations. This includes node and relationship management as well as graph queries.

The upsert methods accept two calling conventions:

New-style (preferred) -- pass a Node or Edge object directly:

.. code-block:: python

node = Node(type="Person", metadata={"name": "Alice", "age": 30})
await capability.upsert_node(node=node)

edge = Edge(type="KNOWS", source_id="alice-id", target_id="bob-id",
            metadata={"since": 2020})
await capability.upsert_relationship(edge=edge)

Old-style (deprecated) -- pass individual string/dict arguments by keyword. These still work but emit a DeprecationWarning at call time:

.. code-block:: python

await capability.upsert_node(
    label="Person", identifier_key="name", identifier_value="Alice",
    properties={"age": 30},
)
await capability.upsert_relationship(
    node_source_key="name", node_source_value="Alice", relation="KNOWS",
    node_target_key="name", node_target_value="Bob",
)

agent property

Return the agentic exploration sub-capability.

Override this in concrete graph capability implementations that support agentic exploration.

Returns:

Name	Type	Description
BaseAgenticGraphCapability	BaseAgenticGraphCapability	The agentic sub-capability.

Raises:

Type	Description
NotImplementedError	If this datastore does not support agentic capability.

delete_node(label, identifier_key, identifier_value) abstractmethod async

Delete a node and its relationships.

Parameters:

Name	Type	Description	Default
label	str	Node label/type.	required
identifier_key	str	Node identifier key.	required
identifier_value	str	Node identifier value.	required

Returns:

Name	Type	Description
Any	Any	Deletion result information.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.

delete_nodes(properties, label=None) abstractmethod async

Delete all nodes matching the given properties, together with their relationships.

Unlike :meth:delete_node, which targets a single node by a known identifier, this method bulk-deletes every node whose properties match all key-value pairs in properties, optionally filtered by label.

Parameters:

Name	Type	Description	Default
properties	dict[str, Any]	Property key-value pairs that a node must match (e.g. {"chunk_id": "c1"} or {"file_id": "f1", "index_name": "reg"}).	required
label	str | None	Node label to restrict deletion. When None, matches nodes of any label. Defaults to None.	None

Returns:

Name	Type	Description
int	int	Number of nodes deleted.

Raises:

Type	Description
ValueError	If properties is None or empty.
NotImplementedError	If the subclass has not implemented this method, or if the backend does not support label-less bulk deletion.

delete_relationship(node_source_key, node_source_value, relation, node_target_key, node_target_value) abstractmethod async

Delete a relationship between nodes.

Parameters:

Name	Type	Description	Default
node_source_key	str	Source node identifier key.	required
node_source_value	str	Source node identifier value.	required
relation	str	Relationship type.	required
node_target_key	str	Target node identifier key.	required
node_target_value	str	Target node identifier value.	required

Returns:

Name	Type	Description
Any	Any	Deletion result information.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.

query(query, parameters=None) abstractmethod async

Run a read-write query against the graph and return rows.

Use this for statements that mutate the graph (MERGE, CREATE, DELETE, SET, INSERT, etc.) or for mixed read-write transactions. For pure reads, prefer :meth:retrieve so the driver can route to a read replica when available.

Parameters:

Name	Type	Description	Default
query	str	Graph query that may mutate state.	required
parameters	dict[str, Any] | None	Query parameters. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Query results as list of dictionaries.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.

retrieve(query, parameters=None) abstractmethod async

Run a read-only query against the graph and return rows.

Implementations must execute query in a read-only context (e.g. Neo4j execute_read). Use :meth:query for read-write statements such as MERGE, CREATE or DELETE.

Parameters:

Name	Type	Description	Default
query	str	Read-only graph query.	required
parameters	dict[str, Any] | None	Query parameters. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: Query results as list of dictionaries.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.

upsert_node(node=None, label=None, identifier_key=None, identifier_value=None, properties=None) abstractmethod async

Create or update a node in the graph.

Parameters:

Name	Type	Description	Default
node	Node | None	A Node object. When provided, the legacy arguments are ignored. Defaults to None.	None
label	str | None	The label of the node. Deprecated -- use node instead. Defaults to None.	None
identifier_key	str | None	The key of the identifier. Deprecated -- use node instead. Defaults to None.	None
identifier_value	str | None	The value of the identifier. Deprecated -- use node instead. Defaults to None.	None
properties	dict[str, Any] | None	Additional node properties. Deprecated -- use node instead. Defaults to None.	None

Returns:

Type	Description
Node | None	Node | None: The upserted node, or None if it could not be confirmed.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.

upsert_relationship(edge=None, node_source_key=None, node_source_value=None, relation=None, node_target_key=None, node_target_value=None, properties=None) abstractmethod async

Create or update a relationship between nodes.

Parameters:

Name	Type	Description	Default
edge	Edge | None	An Edge object. When provided, the legacy arguments are ignored. Defaults to None.	None
node_source_key	str | None	Source node identifier key. Deprecated -- use edge instead. Defaults to None.	None
node_source_value	str | None	Source node identifier value. Deprecated -- use edge instead. Defaults to None.	None
relation	str | None	Relationship type. Deprecated -- use edge instead. Defaults to None.	None
node_target_key	str | None	Target node identifier key. Deprecated -- use edge instead. Defaults to None.	None
node_target_value	str | None	Target node identifier value. Deprecated -- use edge instead. Defaults to None.	None
properties	dict[str, Any] | None	Relationship properties. Deprecated -- use edge instead. Defaults to None.	None

Returns:

Type	Description
Edge | None	Edge | None: The upserted edge, or None if it could not be confirmed.

Raises:

Type	Description
NotImplementedError	This method is not implemented in the subclass.