Skip to main content
Version: latest

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_fulltext_index​

ensure_fulltext_index(*, label:str, properties:Sequence[str]) -> None

Create a full-text index over node properties if it does not exist.

The index is built from the node text of the given properties. Its name is derived from the label and the properties, so a repeated call with the same arguments does nothing.

Parameters:

  • label (str) – The node label to index.
  • properties (Sequence[str]) – The property names to index. Each must be a safe identifier.

Raises:

  • ValueError – properties is empty, or a name is not a safe identifier.

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.