Graph data store

Graph data store interface module.

This module defines the BaseGraphDataStore abstract base class, which provides an interface for graph database operations.

`BaseGraphDataStore`

Bases: ABC

Abstract base class for an async graph data store interface.

This class defines the asynchronous interface for all graph data store implementations. It provides methods for creating, updating, and querying graph data.

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 store.upsert_node(node=node)

edge = Edge(type="KNOWS", source_id="Alice", target_id="Bob",
            metadata={"since": 2020})
await store.upsert_relationship(edge=edge)

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

.. code-block:: python

await store.upsert_node("Person", "name", "Alice", {"age": 30})
await store.upsert_relationship("name", "Alice", "KNOWS", "name", "Bob")

`close()` `abstractmethod` `async`

Close the graph data store.

`delete_node(label, identifier_key, identifier_value)` `abstractmethod` `async`

Delete a node from the graph.

Parameters:

Name	Type	Description	Default
`label`	`str`	The label of the node.	required
`identifier_key`	`str`	The key of the identifier.	required
`identifier_value`	`str`	The identifier of the node.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the deletion completed successfully.

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

Delete a relationship between two nodes in the graph.

Parameters:

Name	Type	Description	Default
`node_source_key`	`str`	The key of the source node.	required
`node_source_value`	`str`	The identifier of the source node.	required
`relation`	`str`	The type of the relationship.	required
`node_target_key`	`str`	The key of the target node.	required
`node_target_value`	`str`	The identifier of the target node.	required

Returns:

Name	Type	Description
`bool`	`bool`	`True` if the deletion completed successfully.

`query(query, parameters=None)` `abstractmethod` `async`

Query the graph data store.

Parameters:

Name	Type	Description	Default
`query`	`str`	The query to be executed.	required
`parameters`	`dict[str, Any] \| None`	The parameters of the query. Defaults to None.	`None`

Returns:

Type	Description
`list[dict[str, Any]]`	list[dict[str, Any]]: The result of the query as a list of dictionaries.

`traverse_graph(node_properties, extracted_node_properties=None, extracted_relationship_properties=None, depth=3)` `abstractmethod` `async`

Traverse graph from a node with specified properties, ignoring relationship's direction, up to a given depth.

Example

nodes, relationships = await graph_data_store.traverse_graph(
    node_properties={"name": "John Doe"},
    extracted_node_properties=["name", "age"],
    extracted_relationship_properties=["since"],
    depth=1
)

Means starting from the node with property name equal to "John Doe", traverse the graph up to depth 1, extracting the name and age properties from nodes and the since property from relationships.

nodes, relationships = await graph_data_store.traverse_graph(
    node_properties={"name": "John Doe"},
    depth=2
)

Means starting from the node with property name equal to "John Doe", traverse the graph up to depth 2, extracting all properties from nodes and relationships.

Parameters:

Name	Type	Description	Default
`node_properties`	`dict[str, Any]`	The properties of the starting node.	required
`extracted_node_properties`	`list[str] \| None`	The properties to extract from nodes during traversal. If None or empty list, all node properties will be returned. Defaults to None.	`None`
`extracted_relationship_properties`	`list[str] \| None`	The properties to extract from relationships during traversal. If None or empty list, all relationship properties will be returned. Defaults to None.	`None`
`depth`	`int`	The depth of traversal. Defaults to 3.	`3`

Returns:

Type	Description
`list[dict[str, Any]]`	tuple[list[dict[str, Any]], list[dict[str, Any]]]: A tuple containing two lists: - List of nodes with their extracted properties (including the source node). - List of relationships with their extracted properties.
`list[dict[str, Any]]`	Example return value:
`tuple[list[dict[str, Any]], list[dict[str, Any]]]`	nodes = [ { "id": 1001, "labels": ["Person"], "properties": { "name": "John Doe", "age": 30, "occupation": "Engineer" } }, { "id": 2001, "labels": ["Company"], "properties": { "name": "TechCorp", "industry": "Technology", "employees": 500 } }
`tuple[list[dict[str, Any]], list[dict[str, Any]]]`	]
`tuple[list[dict[str, Any]], list[dict[str, Any]]]`	relationships = [ { "id": 5002, "type": "FRIEND_OF", "start_node": 1001, "end_node": 1002, "properties": { "since": "2018-05-20", "closeness": 8 } }
`tuple[list[dict[str, Any]], list[dict[str, Any]]]`	]

Raises:

Type	Description
`ValueError`	If node_properties is empty or depth is less than 1.

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

Upsert a node in the graph.

Preferred – pass a Node instance:

.. code-block:: python

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

Deprecated – pass raw string/dict parameters (still supported):

.. code-block:: python

result = await store.upsert_node("Person", "name", "Alice", {"age": 30})

Parameters:

Name	Type	Description	Default
`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`	Extra node properties. Deprecated – use `node` instead. Defaults to None.	`None`
`node`	`Node \| None`	A `Node` object. When provided, the positional arguments are ignored and a deprecation warning is not emitted.	`None`

Returns:

Type	Description
`Node \| None`	Node \| None: The upserted node, or `None` if the node could not be confirmed in the database. When called with a `Node` object, the same object is returned. When called with legacy parameters, a new `Node` is constructed from the resolved arguments if available.

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

Upsert a relationship between two nodes in the graph.

Preferred – pass an Edge instance:

.. code-block:: python

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

Deprecated – pass raw string/dict parameters (still supported):

.. code-block:: python

result = await store.upsert_relationship(
    "name", "Alice", "KNOWS", "name", "Bob", {"since": 2020}
)

Parameters:

Name	Type	Description	Default
`node_source_key`	`str \| None`	The key of the source node. Deprecated – use `edge` instead. Defaults to None.	`None`
`node_source_value`	`str \| None`	The value of the source node. Deprecated – use `edge` instead. Defaults to None.	`None`
`relation`	`str \| None`	The type of the relationship. Deprecated – use `edge` instead. Defaults to None.	`None`
`node_target_key`	`str \| None`	The key of the target node. Deprecated – use `edge` instead. Defaults to None.	`None`
`node_target_value`	`str \| None`	The value of the target node. Deprecated – use `edge` instead. Defaults to None.	`None`
`properties`	`dict[str, Any] \| None`	Extra relationship properties. Deprecated – use `edge` instead. Defaults to None.	`None`
`edge`	`Edge \| None`	An `Edge` object. When provided, the positional arguments are ignored and a deprecation warning is not emitted.	`None`

Returns:

Type	Description
`Edge \| None`	Edge \| None: The upserted edge, or `None` if the relationship could not be confirmed in the database. When called with an `Edge` object, the same object is returned. When called with legacy parameters, a new `Edge` is constructed from the resolved arguments if available.

Graph data store

BaseGraphDataStore

close() abstractmethod async

delete_node(label, identifier_key, identifier_value) abstractmethod async

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

query(query, parameters=None) abstractmethod async

traverse_graph(node_properties, extracted_node_properties=None, extracted_relationship_properties=None, depth=3) abstractmethod async

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

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

`BaseGraphDataStore`

`close()` `abstractmethod` `async`

`delete_node(label, identifier_key, identifier_value)` `abstractmethod` `async`

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

`query(query, parameters=None)` `abstractmethod` `async`

`traverse_graph(node_properties, extracted_node_properties=None, extracted_relationship_properties=None, depth=3)` `abstractmethod` `async`

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

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