Graph

Graph is the mutable embedded graph database. Graph() creates an in-memory graph; Graph(path) or Graph.open(path) opens a SQLite-backed graph.

Method Guides

Methods	Design reference
neighbors, k_hop, frontier	Neighbor expansion and k-hop traversal
bfs	Breadth-first search
shortest_path	Weighted shortest path
connected_components	Connected components
pagerank	PageRank
random_walk	Random walk
propagate, local_propagate	Sparse probability transfer
compute_batch	Batch compute
query, query_schema	Structured path-pattern query DSL
schema, stats	Graph introspection for Text2Query, GraphRAG planning, and local diagnostics
retrieve_context	GraphRAG retrieval
import_nodes_csv, import_edges_csv, import_nodes_jsonl, import_edges_jsonl, export_nodes_jsonl, export_edges_jsonl, export_query_rows_jsonl	Local CSV/JSONL import and export helpers
create_fulltext_index, drop_fulltext_index, fulltext_indexes, rebuild_fulltext_index, search_text	Full-text search
create_vector_index, drop_vector_index, vector_indexes, upsert_vector, upsert_vectors, get_vector, delete_vector, delete_vectors, search_vector, search_vectors	Vector search
update_node, update_edge, delete_node, delete_edge	Persistence and graph mutations
cypher, transaction	Cypher compatibility
add_variable, add_factor_table, add_cpd, add_evidence, compile_active_subgraph, belief_propagation, posterior	Belief propagation
compact, open	Persistence

Reference

tonggraph.Graph

Graph(path: str | None = None)

Mutable embedded graph database.

Graph() creates an in-memory graph. Graph(path) or Graph.open(path) opens a SQLite-backed graph at path and persists metadata, properties, probabilistic records, and compacted compute segments.

Create an in-memory graph or open a SQLite-backed graph.

open staticmethod

open(path: str) -> Graph

Open a SQLite-backed graph from path.

add_node

add_node(external_id: str | None = None, labels: Sequence[str] | None = None, properties: Properties | None = None) -> int

Add a node and return its internal ID.

add_edge

add_edge(source: int, target: int, edge_type: str, properties: Properties | None = None) -> int

Add a directed edge and return its internal ID.

add_nodes

add_nodes(records: Sequence[Mapping[str, Any]]) -> list[int]

Atomically add node records and return their internal IDs.

add_edges

add_edges(records: Sequence[Mapping[str, Any]]) -> list[int]

Atomically add directed edge records and return their internal IDs.

update_node

update_node(node_id: int, *, external_id: str | None = None, add_labels: Sequence[str] | None = None, remove_labels: Sequence[str] | None = None, set_properties: Properties | None = None, remove_properties: Sequence[str] | None = None) -> Node

Update a node and return its new record.

update_edge

update_edge(edge_id: int, *, set_properties: Properties | None = None, remove_properties: Sequence[str] | None = None) -> Edge

Update an edge and return its new record.

delete_node

delete_node(node_id: int, *, detach: bool = False) -> None

Delete a node, optionally deleting incident edges.

delete_edge

delete_edge(edge_id: int) -> None

Delete an edge.

create_fulltext_index

create_fulltext_index(name: str, properties: Sequence[str], target: str = 'node', tokenizer: str = 'unicode61') -> None

Create a named node or edge full-text index.

drop_fulltext_index

drop_fulltext_index(name: str) -> None

Drop a full-text index and its derived rows.

fulltext_indexes

fulltext_indexes() -> list[dict[str, Any]]

Return named full-text index definitions ordered by name.

rebuild_fulltext_index

rebuild_fulltext_index(name: str | None = None) -> None

Rebuild one full-text index or every index.

search_text

search_text(index_name: str, query: str, mode: str = 'all', labels: Sequence[str] | None = None, edge_type: str | None = None, properties: Properties | None = None, limit: int = 20, offset: int = 0) -> list[dict[str, Any]]

Search a named full-text index.

create_vector_index

create_vector_index(name: str, dimensions: int, target: str = 'node', metric: str = 'cosine', model: str | None = None, model_version: str | None = None) -> None

Create a named node or edge vector index.

drop_vector_index

drop_vector_index(name: str) -> None

Drop a vector index and all vectors stored in it.

upsert_vector

upsert_vector(index_name: str, entity_id: int, vector: Sequence[float]) -> None

Insert or replace one entity vector.

upsert_vectors

upsert_vectors(index_name: str, vectors: Mapping[int, Sequence[float]]) -> None

Atomically insert or replace multiple entity vectors.

delete_vector

delete_vector(index_name: str, entity_id: int) -> None

Idempotently delete one entity vector.

delete_vectors

delete_vectors(index_name: str, entity_ids: Sequence[int]) -> None

Idempotently delete multiple entity vectors atomically.

compact

compact() -> None

Compact the mutable adjacency overlay into a persisted compute segment.

refresh

refresh() -> None

Reload a SQLite-backed graph from disk after another handle writes.

retrieve_context

retrieve_context(*, text_query: str | None = None, text_index: str | None = None, vector_query: Sequence[float] | None = None, vector_index: str | None = None, labels: Sequence[str] | None = None, edge_type: str | None = None, properties: Properties | None = None, radius: int = 1, direction: str = 'both', limit: int = 20, text_weight: float = 1.0, vector_weight: float = 1.0, graph_weight: float = 0.1) -> list[dict[str, Any]]

Return ranked context rows from text/vector candidates plus graph expansion.

import_nodes_csv

import_nodes_csv(path: str) -> list[int]

Import nodes from CSV and return created node IDs.

import_edges_csv

import_edges_csv(path: str) -> list[int]

Import edges from CSV and return created edge IDs.

import_nodes_jsonl

import_nodes_jsonl(path: str) -> list[int]

Import nodes from JSONL and return created node IDs.

import_edges_jsonl

import_edges_jsonl(path: str) -> list[int]

Import edges from JSONL and return created edge IDs.

export_nodes_jsonl

export_nodes_jsonl(path: str, nodes: Sequence[int] | None = None) -> None

Export nodes to JSONL.

export_edges_jsonl

export_edges_jsonl(path: str, edges: Sequence[int] | None = None) -> None

Export edges to JSONL.

export_query_rows_jsonl

export_query_rows_jsonl(path: str, rows: Sequence[Mapping[str, Any]]) -> None

Export query or Cypher rows to JSONL.

cypher

cypher(query: str, parameters: Mapping[str, Any] | None = None, profile: bool = False) -> CypherResult

Run a Cypher query in an autocommit transaction.

transaction

transaction(write: bool = True) -> GraphTransaction

Create an explicit staged Cypher transaction.

snapshot

snapshot() -> GraphSnapshot

Return a read-only snapshot of the current graph state.

propagate

propagate(seeds: Mapping[int, float], steps: int, edge_property: str = 'probability', damping: float = 1.0, edge_type: str | None = None) -> dict[int, float]

Transfer probability mass over outgoing edges for a fixed number of steps.

local_propagate

local_propagate(seeds: Mapping[int, float], radius: int = 2, query_nodes: Sequence[int] | None = None, edge_type: str | None = None, edge_property: str = 'probability', damping: float = 1.0) -> dict[int, float]

Transfer probability only inside a radius-limited active graph neighborhood.

add_variable

add_variable(domain: str, owner_id: int | None = None, prior: Properties | None = None, posterior: Properties | None = None, states: Sequence[str] | None = None) -> int

Add a finite discrete variable and return its ID.

add_factor

add_factor(input_variables: Sequence[int], output_variables: Sequence[int], function: str, parameters: Properties | None = None) -> int

Add factor metadata and return its ID.

add_factor_table

add_factor_table(variables: Sequence[int], values: Sequence[float]) -> int

Add a dense factor table for ordered variables and return its factor ID.

add_cpd

add_cpd(variable_id: int, parent_variables: Sequence[int], values: Sequence[float]) -> int

Add a conditional probability table for variable_id and parents.

add_evidence

add_evidence(variable_id: int, payload: Properties | None = None) -> int

Persist evidence metadata for a variable and return the evidence ID.

add_trace

add_trace(payload: Properties | None = None) -> int

Persist an inference trace metadata record and return its ID.

compile_active_subgraph

compile_active_subgraph(query_variables: Sequence[int], evidence: Mapping[int, str] | None = None, radius: int = 2, max_nodes: int = 10000, max_factors: int = 50000) -> dict[str, Any]

Compile a radius-limited inference subgraph around queries and evidence.

belief_propagation

belief_propagation(query_variables: Sequence[int] | None = None, evidence: Mapping[int, str] | None = None, radius: int = 2, max_iters: int = 1000, tolerance: float = 1e-06, damping: float = 0.2, persist: bool = False) -> dict[str, Any]

Run residual asynchronous sum-product belief propagation.

posterior

posterior(variable_id: int) -> Distribution

Return the current posterior distribution for a variable.

vector_indexes

vector_indexes() -> list[dict[str, Any]]

Return named vector index definitions ordered by name.

get_vector

get_vector(index_name: str, entity_id: int) -> list[float]

Return an entity vector, raising KeyError when it is absent.

search_vector

search_vector(index_name: str, query_vector: Sequence[float], labels: Sequence[str] | None = None, edge_type: str | None = None, properties: Properties | None = None, min_score: float | None = None, limit: int = 20, offset: int = 0) -> list[dict[str, Any]]

Search a named vector index by exact similarity.

search_vectors

search_vectors(index_name: str, query_vectors: Sequence[Sequence[float]], labels: Sequence[str] | None = None, edge_type: str | None = None, properties: Properties | None = None, min_score: float | None = None, limit: int = 20, offset: int = 0) -> list[list[dict[str, Any]]]

Search a named vector index for multiple query vectors.

node_count

node_count() -> int

Return the number of live nodes.

edge_count

edge_count() -> int

Return the number of live edges.

variable_count

variable_count() -> int

Return the number of probabilistic variables.

factor_count

factor_count() -> int

Return the number of factors.

evidence_count

evidence_count() -> int

Return the number of evidence records.

trace_count

trace_count() -> int

Return the number of trace records.

schema

schema() -> dict[str, Any]

Return graph schema metadata for Text2Query and retrieval planning.

stats

stats() -> dict[str, Any]

Return local graph, index, segment, and persistence statistics.

node_ids

node_ids() -> list[int]

Return live node IDs ordered by internal ID.

edge_ids

edge_ids() -> list[int]

Return live edge IDs ordered by internal ID.

nodes

nodes() -> list[Node]

Return node records ordered by internal ID.

edges

edges() -> list[Edge]

Return edge records ordered by internal ID.

get_node

get_node(node_id: int) -> Node

Return a node record by ID.

Raises:

Type	Description
KeyError	If the node does not exist.

get_edge

get_edge(edge_id: int) -> Edge

Return an edge record by ID.

Raises:

Type	Description
KeyError	If the edge does not exist.

get_variable

get_variable(variable_id: int) -> Variable

Return a variable record by ID.

Raises:

Type	Description
KeyError	If the variable does not exist.

get_factor

get_factor(factor_id: int) -> Factor

Return a factor record by ID.

Raises:

Type	Description
KeyError	If the factor does not exist.

get_evidence

get_evidence(evidence_id: int) -> Evidence

Return an evidence record by ID.

Raises:

Type	Description
KeyError	If the evidence record does not exist.

get_trace

get_trace(trace_id: int) -> Trace

Return a trace record by ID.

Raises:

Type	Description
KeyError	If the trace record does not exist.

get_node_id

get_node_id(external_id: str) -> int | None

Look up an internal node ID by external ID.

nodes_with_label

nodes_with_label(label: str) -> list[int]

Return node IDs that have a label.

edges_by_type

edges_by_type(edge_type: str) -> list[int]

Return edge IDs for an edge type.

nodes_with_property

nodes_with_property(key: str, value: PropertyValue | None = None) -> list[int]

Return node IDs that contain a property key, optionally filtered by value.

edges_with_property

edges_with_property(key: str, value: PropertyValue | None = None) -> list[int]

Return edge IDs that contain a property key, optionally filtered by value.

neighbors

neighbors(node_id: int, direction: str = 'out', edge_type: str | None = None) -> list[int]

Return adjacent node IDs.

Parameters:

Name	Type	Description	Default
node_id	int	Node to expand.	required
direction	str	"out", "in", or "both".	'out'
edge_type	str | None	Optional edge-type filter.	None

k_hop

k_hop(start: int, hops: int, direction: str = 'out', edge_type: str | None = None) -> list[int]

Return nodes reached within hops traversal steps, excluding start.

frontier

frontier(starts: Sequence[int], steps: int, direction: str = 'out', edge_type: str | None = None) -> list[int]

Return only the nodes reached at the final traversal step.

bfs

bfs(start: int, direction: str = 'out', edge_type: str | None = None, max_depth: int | None = None) -> list[int]

Run breadth-first search and return visited nodes in traversal order.

shortest_path

shortest_path(start: int, target: int, direction: str = 'out', edge_type: str | None = None, weight_property: str | None = None) -> dict[str, Any] | None

Return the shortest path and distance, or None when unreachable.

connected_components

connected_components(edge_type: str | None = None) -> list[list[int]]

Return weakly connected components using both incoming and outgoing edges.

pagerank

pagerank(iterations: int = 20, damping: float = 0.85, tolerance: float | None = None, edge_type: str | None = None) -> dict[int, float]

Return PageRank scores keyed by node ID.

random_walk

random_walk(start: int, steps: int, direction: str = 'out', edge_type: str | None = None, seed: int | None = None) -> list[int]

Run a random walk and return the path, including the start node.

subgraph

subgraph(nodes: Sequence[int], edge_type: str | None = None) -> GraphSnapshot

Return a snapshot containing selected nodes and internal edges.

compute_batch

compute_batch(jobs: Sequence[Mapping[str, Any]]) -> list[Any]

Run multiple compute jobs and return results in input order.

query

query(spec: Mapping[str, Any], profile: bool = False) -> Any

Run a structured path-pattern query and return alias-to-ID row bindings.

query_schema

query_schema() -> dict[str, Any]

Return the structured query DSL schema.