GraphSnapshot

GraphSnapshot is a read-only copy of graph state. It supports lookup and compute methods without mutating the original graph or carrying a persistence handle.

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
subgraph, compute_batch	Batch compute and snapshots
query, query_schema	Structured path-pattern query DSL
schema, stats	Graph introspection for frozen views
fulltext_indexes, search_text	Full-text search
vector_indexes, get_vector, search_vector, search_vectors	Vector search
cypher	Cypher compatibility

Reference

tonggraph.GraphSnapshot

Read-only snapshot of graph state.

A snapshot copies the current in-memory state and has no persistence handle. It supports retrieval and compute methods but not mutation methods.

fulltext_indexes

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

Return named full-text index definitions ordered by name.

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.

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.

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 read-only Cypher query against the snapshot.