API reference

Public names exported by graph_ted_db.

Note

Import these from graph_ted_db. Other modules in the package are internal and can change without a version note.

from graph_ted_db import GraphStore, init_graph

init_graph("./my-graph", name="demo", exist_ok=True)
store = GraphStore.open("./my-graph")

Name	Role
GraphStore	Open a graph folder and read or write it
init_graph	Create an empty graph folder
NodeRecord	One node version: returned by make_node / get_node / iter_nodes, accepted by put_node
EdgeRecord	One edge version: returned by make_edge / get_edge / iter_edges, accepted by put_edge
VectorRecord	An embedding for a node or edge: get_vector / put_vector
Tombstone	Deletion marker returned by delete_node / delete_edge / delete_vector
CypherError	Invalid query, or syntax outside the supported openCypher subset
__version__	Package version string (graph_ted_db.__version__)

GraphStore

Single-writer (this machine) view of a graph folder.

Primary writes are put_node, put_edge, make_node, and make_edge. add_node, add_edge, nodes, edges, has_node, has_edge, neighbors, remove_node, and remove_edge are optional NetworkX-like aliases for those operations.

alias_record_id = staticmethod(alias_record_id) class-attribute instance-attribute

root = Path(root).expanduser().resolve() instance-attribute

meta = load_graph_meta(self.root) instance-attribute

data_dir = data_dir instance-attribute

writer_id = load_or_create_writer_id(writer_path_for(self.meta.id, data_dir)) instance-attribute

paths = GraphPaths(self.root, writer=self.writer_id) instance-attribute

skipped_lines = [] instance-attribute

add_node(node_id, /, **attrs)

Insert or replace a node. label / labels are labels; other keywords are props.

Same id again replaces the whole record (labels and props). It does not merge attributes. Returns the stored NodeRecord.

add_edge(u, v, /, **attrs)

Insert a directed edge from u to v.

type is the relationship type (default RELATED) and is not a property. Both endpoints must already be live nodes. Each call inserts another edge (parallel edges are kept). Returns the stored EdgeRecord.

nodes()

Yield live node record ids. Same ids as iter_nodes, not full records.

edges()

Yield (from_id, to_id) record-id pairs for live directed edges.

A pair can repeat when several edges share those endpoints. Relationship type and edge id are on the EdgeRecord from iter_edges.

has_node(n)

True when get_node returns a live node for this key.

has_edge(u, v, *, type=None)

True when a live directed edge runs from u to v.

Optional type limits the check to that relationship type. Existence follows get_edge (a hidden or tombstoned edge does not count).

neighbors(n)

Yield outgoing neighbor record ids, once each, from the local adjacency index.

Directed: an edge n -> m yields m, and the reverse edge does not. Missing n raises KeyError.

remove_node(n)

Tombstone the node and its incident edges (delete_node).

Raises KeyError when the node is not live.

remove_edge(u, v, *, type=None)

Delete one live directed edge from u to v (delete_edge).

Optional type selects the relationship type. When several edges match, one of them is deleted. Raises KeyError when none match.

__init__(root, *, data_dir=None)

open(root, *, data_dir=None) classmethod

Open an existing graph folder.

Repairs torn lines, replays an interrupted transaction, and builds the local index before returning.

Parameters:

Name	Type	Description	Default
root	str | Path	The graph folder (created by init_graph).	required
data_dir	Path | None	Where to keep the process lock and local index. Defaults to GRAPH_TED_DB_DATA or the platform app-data directory, never inside the graph folder.	None

Returns:

Type	Description
GraphStore	An open store.

problems()

Counts of things that may hide records. All zero on a healthy store.

skipped_lines: lines that are not valid records (including an unterminated last line). unterminated_other_writers: other writers' files whose last line is incomplete, left unmodified (usually still syncing). cloud_only_files: cloud-only placeholders (OneDrive Files On-Demand). empty_record_files: zero-byte record files.

put_node(record)

Write a node record as-is (last write wins). Returns the record.

get_node(record_id)

Return the live node with this id, or None if it is missing or deleted.

delete_node(record_id, *, updated_by='')

Tombstone a node and every live incident edge (DETACH DELETE).

iter_nodes()

Yield every live node (the last-write-wins version of each id).

put_edge(record)

Write an edge record as-is (last write wins). Returns the record.

Raises:

Type	Description
ValueError	If either endpoint is not a live node.

get_edge(record_id)

Return the live edge with this id, or None if it is missing, deleted, or dangling.

delete_edge(record_id, *, updated_by='')

Tombstone one edge. Returns the tombstone that was written.

iter_edges()

Yield every live edge whose endpoints are both live nodes.

put_vector(record)

Write an embedding record (stored under vectors/<property>/). Returns the record.

get_vector(property_name, record_id)

Return the live embedding property_name for a node or edge id, or None.

Raises:

Type	Description
ValueError	If property_name is not a valid vector property name.

delete_vector(property_name, record_id, *, updated_by='')

Tombstone the embedding property_name of a node or edge. Returns the tombstone.

make_node(*, labels=(), props=None, record_id=None, updated_by='')

Create or overwrite a node and return it.

Parameters:

Name	Type	Description	Default
labels	list[str] | tuple[str, ...]	Node labels, e.g. ["Person"].	()
props	dict[str, Any] | None	JSON-compatible property values.	None
record_id	str | None	UUID to write. A new random UUID is used when omitted; an existing id is overwritten (last write wins).	None
updated_by	str	Optional author string stored on the record.	''

make_edge(*, type, from_id, to_id, props=None, record_id=None, updated_by='')

Create or overwrite an edge and return it.

Parameters:

Name	Type	Description	Default
type	str	Relationship type, e.g. "KNOWS".	required
from_id	str	Id of the live start node.	required
to_id	str	Id of the live end node.	required
props	dict[str, Any] | None	JSON-compatible property values.	None
record_id	str | None	UUID to write. A new random UUID is used when omitted.	None
updated_by	str	Optional author string stored on the record.	''

Raises:

Type	Description
ValueError	If either endpoint is not a live node.

execute(cypher, parameters=None, *, updated_by='cypher')

Run an openCypher query (the supported subset). See docs/cypher.md.

execute_many(statements, *, updated_by='cypher')

Run statements in one lock and one transaction. All commit or none.

compact()

Rewrite canonical shards to winning records. Leaves conflict copies.

Refused on a shared store (any record file this device did not write, or any conflict copy): rewriting a file another device also appends to would drop its records once the sync client picks a version.

Raises:

Type	Description
SharedStoreError	The store is shared.

doctor(*, fix=False)

Repair torn JSONL, drop leftover tmp, rebuild labels, report dangling edges.

Dangling edges (an endpoint is not a live node) are only reported unless fix is true. Reads already skip them. Tombstoning is permanent and syncs to every device, and in a shared folder an edge can arrive before its nodes, so run with fix=True only once the sync client has finished.

export(out)

Write the current state (live winners only) to one JSONL file.

The first line is a header; then one {"type": ..., "record": ...} line per live node, edge and vector. History, tombstones and conflict copies are not included. Read it back with import_export.

Returns:

Type	Description
dict[str, int]	Counts per record type.

refresh_index()

Reload the query catalog if another process wrote shards.

writers()

Writer ids registered in meta/writers/ (synced from every device).

init_graph

Create an empty graph folder. Refuses to clobber an existing graph.json.

NodeRecord

One version of a node, as stored in a nodes/ shard.

GraphStore.make_node builds these for you. Build one directly to write an exact record with GraphStore.put_node.

Attributes:

Name	Type	Description
id	str	Node UUID.
updated_at	str	UTC timestamp of this version (last write wins).
labels	tuple[str, ...]	Node labels.
props	dict[str, Any]	JSON-compatible property values.
updated_by	str	Optional author string; empty unless the writer sets one.
v	int	Record schema version.
writer	str	Random id of the device that wrote this version (format v2).
counter	int	Hybrid-logical-clock counter within updated_at (format v2).

EdgeRecord

One version of an edge (relationship), as stored in an edges/ shard.

GraphStore.make_edge builds these for you; GraphStore.put_edge writes one as-is.

Attributes:

Name	Type	Description
id	str	Edge UUID.
updated_at	str	UTC timestamp of this version (last write wins).
type	str	Relationship type, e.g. "KNOWS".
from_id	str	Start node id.
to_id	str	End node id.
props	dict[str, Any]	JSON-compatible property values.
updated_by	str	Optional author string; empty unless the writer sets one.
v	int	Record schema version.
writer	str	Random id of the device that wrote this version (format v2).
counter	int	Hybrid-logical-clock counter within updated_at (format v2).

VectorRecord

An embedding for a node or edge, stored under vectors/<property>/.

Build one with VectorRecord.from_floats and write it with GraphStore.put_vector; read the values back with floats().

Attributes:

Name	Type	Description
id	str	Id of the node or edge that owns the embedding.
updated_at	str	UTC timestamp of this version (last write wins).
dim	int	Number of dimensions.
vec_b64	str	The vector as base64 little-endian float32.
property	str	Vector property name, e.g. "name_embedding".
updated_by	str	Optional author string; empty unless the writer sets one.
v	int	Record schema version.
writer	str	Random id of the device that wrote this version (format v2).
counter	int	Hybrid-logical-clock counter within updated_at (format v2).
dtype	str	Encoding of vec_b64 ("f32le").

from_floats(*, id, property, values, updated_at, updated_by='', v=1) classmethod

Build a record from float values (stored as little-endian float32).

Parameters:

Name	Type	Description	Default
id	str	Id of the node or edge that owns the embedding.	required
property	str	Vector property name, e.g. "name_embedding".	required
values	list[float] | tuple[float, ...]	The embedding.	required
updated_at	str | datetime	Timestamp string or timezone-aware datetime, e.g. datetime.now(timezone.utc).	required
updated_by	str	Optional author string.	''
v	int	Record schema version.	1

writer: Random id of the device that wrote this version (format v2). counter: Hybrid-logical-clock counter within updated_at (format v2).

floats()

Decode the stored vector to a tuple of floats.

Tombstone

A deletion marker in meta/deleted.jsonl, returned by the delete_* methods.

A tombstone wins over a live record with the same id unless that record has a newer updated_at.

Attributes:

Name	Type	Description
id	str	Id of the deleted node, edge, or vector owner.
kind	Kind	"node", "edge", or "vector".
updated_at	str	UTC timestamp of the deletion.
updated_by	str	Optional author string; empty unless the writer sets one.
v	int	Record schema version.
writer	str	Random id of the device that wrote this version (format v2).
counter	int	Hybrid-logical-clock counter within updated_at (format v2).
property	str | None	Vector property name, for kind == "vector" only.

CypherError

Bases: ValueError

Invalid query, or syntax outside this engine's openCypher subset.

pos = pos instance-attribute

__init__(message, *, pos=None)