Skip to main content
Version: 0.0.5 (stable)

agrag.graphdb.base.GraphStore

Bases: ABC

A graph database backend: schema, writes, and native vector search.

Functions:

blocked_candidate_keys​

blocked_candidate_keys(keys:Sequence[str]) -> set[str]

Return candidate keys with a committed non-pending record.

close​

close() -> None

Release the backend connection.

connect​

connect() -> None

Open the backend connection and verify connectivity.

ensure_vector_index​

ensure_vector_index(*, label:str, vector_property:str, dimensions:int, distance:Distance) -> None

Create a native vector index if it does not exist.

Parameters:

  • label (str) – The node label to index.
  • vector_property (str) – The embedding property name.
  • dimensions (int) – The embedding dimension. If the index already exists with a different dimension, this raises.
  • distance (Distance) – The distance metric.

Raises:

  • EmbeddingDimensionMismatchError – The index already exists with a different dimension than dimensions.

execute_read​

execute_read(query:str, parameters:Mapping[str, Any] | None = None, *, timeout:float | None = None) -> list[dict[str, Any]]

Run a read transaction.

Parameters:

  • query (str) – The Cypher query to run.
  • parameters (Mapping[str, Any] | None) – The query parameters.
  • timeout (float | None) – Server-side transaction timeout in seconds. The database terminates the transaction when it runs longer. None uses the server's default timeout. Backends that cannot enforce a timeout ignore it.

Returns:

  • list[dict[str, Any]] – The result rows as dicts.

execute_write​

execute_write(query:str, parameters:Mapping[str, Any] | None = None) -> list[dict[str, Any]]

Run a write transaction.

Parameters:

  • query (str) – The Cypher query to run.
  • parameters (Mapping[str, Any] | None) – The query parameters.

Returns:

  • list[dict[str, Any]] – The result rows as dicts.

register_labels​

register_labels(labels:Sequence[str]) -> None

Mark labels as known, without writing anything.

setup_constraints()/setup_indexes() only cover labels this instance has already written (or that already exist live in the database) — both empty on a brand-new database. register_labels lets a caller holding a GraphSchema (Graph.open()) provision a fresh database fully before its first write.

Parameters:

  • labels (Sequence[str]) – The labels to register. Each must be a safe Cypher identifier.

Raises:

  • ValueError – Any label is not a safe identifier.

register_relation_types​

register_relation_types(types:Sequence[str]) -> None

Mark relationship types as known, without writing anything.

The relationship-type counterpart to register_labels — see its docstring for why this exists.

Parameters:

  • types (Sequence[str]) – The relationship types to register. Each must be a safe Cypher identifier.

Raises:

  • ValueError – Any type is not a safe identifier.

run_in_transaction​

run_in_transaction(work:Callable[[GraphStoreTransaction], Awaitable[_T]]) -> _T

Run work with a transaction handle and return its result.

The default implementation passes this store to work and provides no atomicity across calls. Backends may provide a real transaction. A transactional backend commits when work returns and rolls back when it raises. A backend may retry transient failures, so work must return results rather than change state outside the callback.

Parameters:

  • work (Callable[[GraphStoreTransaction], Awaitable[_T]]) – The reads and writes to run together. Must be safe to retry.

Returns:

  • _T – Whatever work returns.

session​

session() -> AbstractAsyncContextManager[Any]

Open a session as an async context manager.

Returns:

  • AbstractAsyncContextManager[Any] – A context manager yielding a backend session.

setup_constraints​

setup_constraints() -> None

Create per-label and per-relation-type uniqueness constraints.

Constraints cover every node label and relationship type written through this instance or already present in the database, so a fresh instance can set up an existing database without first rewriting every record.

setup_indexes​

setup_indexes() -> None

Create per-label property indexes.

Covers every node label written through this instance or already present in the database, so a fresh instance can set up an existing database without first rewriting every record.

upsert_candidates​

upsert_candidates(candidates:Sequence[CandidateRecord], *, batch_size:int = 256, pending_job_id:UUID | None = None) -> UpsertResult

Write candidate nodes and their evidence links.

Parameters:

  • candidates (Sequence[CandidateRecord]) – Records whose chunks and optional entity endpoints should be linked.
  • batch_size (int) – Records per backend write call. Must be positive.
  • pending_job_id (UUID | None) – The job tag for nodes and edges created by this write, or None for committed data.

Returns:

  • UpsertResult – The number written and one failure for each missing chunk.

Raises:

  • ValueError – batch_size is not positive.

upsert_nodes​

upsert_nodes(label:str, nodes:Sequence[NodeRecord], *, batch_size:int = 256, pending_job_id:UUID | None = None, deferred:DeferredWrites | None = None) -> UpsertResult

Write or merge nodes, honoring each record's full label set.

Parameters:

  • label (str) – The label this batch is tracked under for constraint and index bookkeeping.
  • nodes (Sequence[NodeRecord]) – The node records to upsert. Each node's NodeRecord.labels names the full label set actually written to it, which may include labels beyond label.
  • batch_size (int) – Records per backend write call, applied within each distinct label set when nodes mixes more than one. Must be positive.
  • pending_job_id (UUID | None) – The in-flight Cutover Job's id. pending_job_id tags the rows the call creates, so retrieval skips them until the job commits. A write that reaches a row the job did not create is not applied and is added to deferred.
  • deferred (DeferredWrites | None) – Receives the records whose rows were not written. The commit transaction replays them. Required when pending_job_id is set.

Returns:

Raises:

  • ValueError – batch_size is not positive, or deferred is missing while pending_job_id is set.

upsert_relations​

upsert_relations(relations:Sequence[RelationRecord], *, batch_size:int = 256, pending_job_id:UUID | None = None, deferred:DeferredWrites | None = None) -> UpsertResult

Write or merge relationships between existing nodes.

Parameters:

  • relations (Sequence[RelationRecord]) – The relation records to upsert.
  • batch_size (int) – Records per backend write call. Must be positive.
  • pending_job_id (UUID | None) – The in-flight Cutover Job's id. pending_job_id tags the relationships the call creates, so retrieval skips them until the job commits. A write that reaches a relationship the job did not create is not applied and is added to deferred.
  • deferred (DeferredWrites | None) – Receives the records whose relationships were not written. The commit transaction replays them. Required when pending_job_id is set.

Returns:

Raises:

  • ValueError – batch_size is not positive, or deferred is missing while pending_job_id is set.
vector_search(*, label:str, vector_property:str, query_vector:Sequence[float], limit:int = 10, filters:dict[str, Any] | None = None) -> list[VectorHit]

Search nodes by dense vector.

Parameters:

  • label (str) – The node label to search.
  • vector_property (str) – The embedding property name.
  • query_vector (Sequence[float]) – The dense query embedding.
  • limit (int) – Maximum number of hits.
  • filters (dict[str, Any] | None) – An optional flat-dict filter on node properties.

Returns:

  • list[VectorHit] – The matched hits, highest score first.