OverGraph

https://overgraph.io/docs
Admin
OverGraph is a lightweight, schema-free graph database that runs locally with zero server setup,...
Tokens:55,670
Snippets:419
Trust Score:2.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install OverGraph

Source: https://overgraph.io/docs

Install the OverGraph library using pip. This is the first step to using the graph database.

```python
pip install overgraph
```

--------------------------------

### On-Disk Layout Example

Source: https://overgraph.io/docs/architecture

Illustrates the directory structure and file organization for a self-contained OverGraph database. This layout allows for easy copying and transfer.

```bash
my-graph/
  manifest.current    # atomic checkpoint (JSON)
  data.wal            # write-ahead log
  segments/
    seg_0001/
      nodes.dat
      edges.dat
      adj_out.idx / adj_in.idx
      key_index.dat
      type_index.dat
      tombstones.dat
    seg_0002/
      ...
```

--------------------------------

### Temporal Graph-Scoped Search

Source: https://overgraph.io/docs/api/vector-search

Perform a dense vector search scoped to a specific point in time. This example searches the graph as it existed last Tuesday, starting from a project node.

```python
# Temporal scoping: search the graph as it existed last Tuesday
hits = db.vector_search("dense",
    k=5,
    dense_query=query_embedding,
    scope_start_node_id=project_id,
    scope_max_depth=2,
    scope_at_epoch=last_tuesday_ms)
```

--------------------------------

### Perform Basic Breadth-First Traversal

Source: https://overgraph.io/docs/api/traversal

Execute a basic Breadth-First Search (BFS) starting from a specified node up to a maximum depth. Results include node IDs and their depths from the start node.

```python
# Basic 3-hop traversal
page = db.traverse(alice_id, 3)
for hit in page.items:
    print(f"depth={hit.depth} node={hit.node_id}")
```

--------------------------------

### Async Database Usage

Source: https://overgraph.io/docs

Utilize asynchronous operations for database interactions. This example shows async opening, node creation, neighbor querying, and shortest path calculation.

```python
from overgraph import AsyncOverGraph

async with await AsyncOverGraph.open("./my-graph") as db:
    alice = await db.upsert_node(1, "user:alice", props={"name": "Alice"})
    neighbors = await db.neighbors(alice)
    path = await db.shortest_path(alice, bob)
```

--------------------------------

### Explain Node Query Plan

Source: https://overgraph.io/docs/api/queries

Use explain_node_query to get the planner tree, cost estimates, and warnings for a node query without executing it. This is useful for understanding query performance.

```python
plan = db.explain_node_query({
    "type_id": USER,
    "filter": {"property": "status", "eq": "active"},
})
```

--------------------------------

### Explain Graph Pattern Query Plan

Source: https://overgraph.io/docs/api/queries

Use explain_pattern_query to get the plan for a graph pattern query without executing it. This reports the selected anchor alias and the physical plan used for that anchor.

```python
plan = db.explain_pattern_query(pattern)
```

--------------------------------

### Get Database Statistics

Source: https://overgraph.io/docs/api/database

Returns a read-only snapshot of current database statistics, including WAL status, segment count, and memory usage.

```python
db.stats()
```

--------------------------------

### Python Error Handling Example

Source: https://overgraph.io/docs/api/maintenance

Demonstrates how to catch and handle OverGraph-specific errors in Python, checking error codes for specific failure types.

```APIDOC
## Error Handling Examples
```python
from overgraph import OverGraph, OverGraphError

try:
    db = OverGraph.open("./my-graph")
    db.upsert_node(1, "user:alice", props={"name": "Alice"})
except OverGraphError as e:
    if e.code == "database_not_found":
        print("Database does not exist at path")
    elif e.code == "io_error":
        print(f"Disk error: {e}")
    elif e.code == "corrupt_wal":
        print("WAL corrupted -- restore from backup")
    else:
        print(f"OverGraph error [{e.code}]: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```
```

--------------------------------

### Get Nodes by Keys

Source: https://overgraph.io/docs/api/nodes-edges

Batch-retrieves multiple nodes using their `(type_id, key)` pairs. This is an efficient way to fetch nodes when you don't have their IDs readily available.

```APIDOC
## Get Nodes by Keys

### Description
Batch-retrieves multiple nodes using their `(type_id, key)` pairs. This is an efficient way to fetch nodes when you don't have their IDs readily available.

### Method
db.get_nodes_by_keys(keys)

### Parameters
#### Path Parameters
- **keys** (list[tuple]) - Required - Array of (type_id, key) pairs. Node.js uses `{ typeId: number, key: string }`.

### Returns
Array of `NodeRecord | None` in input order. Same shape as `get_nodes`.

### Example
```python
nodes = db.get_nodes_by_keys([
    (USER, "user:alice"),
    (USER, "user:bob"),
    (PROJECT, "project:atlas"),
])

for node in nodes:
    if node:
        print(f"Found: {node.key} (id={node.id})")
```
```

--------------------------------

### Batch Get Nodes by Keys

Source: https://overgraph.io/docs/api/nodes-edges

Retrieves multiple nodes using `(type_id, key)` pairs. Returns `None` for missing or deleted nodes.

```python
nodes = db.get_nodes_by_keys([
    (USER, "user:alice"),
    (USER, "user:bob"),
    (PROJECT, "project:atlas"),
])

for node in nodes:
    if node:
        print(f"Found: {node.key} (id={node.id})")
```

--------------------------------

### Constrained Traversal with Filtering and Pagination

Source: https://overgraph.io/docs/api/traversal

Perform a constrained traversal, specifying minimum depth, edge types, node types, and limiting the number of results per page. This example also demonstrates how to paginate through the results using a cursor.

```python
# Constrained: specific types, min depth, pagination
page = db.traverse(alice_id, 3,
    min_depth=2,
    edge_type_filter=[WORKS_ON],
    node_type_filter=[PROJECT],
    limit=50)

# Paginate through results
while page.next_cursor is not None:
    page = db.traverse(alice_id, 3,
        min_depth=2,
        edge_type_filter=[WORKS_ON],
        node_type_filter=[PROJECT],
        limit=50,
        cursor=page.next_cursor)
    for hit in page.items:
        print(f"depth={hit.depth} node={hit.node_id}")
```

--------------------------------

### Get Database Statistics

Source: https://overgraph.io/docs/api/database

Retrieves and prints various database statistics including segment count, pending WAL bytes, active memtable bytes, and tombstone counts. This is a lightweight read safe for monitoring loops.

```python
s = db.stats()
print(f"segments: {s.segment_count}, WAL bytes: {s.pending_wal_bytes}")
print(f"memtable: {s.active_memtable_bytes} bytes active")
print(f"tombstones: {s.node_tombstone_count} nodes, {s.edge_tombstone_count} edges")

if s.last_compaction_ms:
    print(f"last compaction: {s.last_compaction_ms}")
```

--------------------------------

### Open Database Instance

Source: https://overgraph.io/docs/api/database

Opens an existing database or creates a new one at the specified path. Configuration options are used only for initial creation and are persisted in the manifest for subsequent opens. Ensure the path is a valid filesystem path.

```python
from overgraph import OverGraph

# Minimal -- open with defaults
db = OverGraph.open("./my-graph")

# Full options
db = OverGraph.open(
    "./my-graph",
    create_if_missing=True,
    wal_sync_mode="group_commit",
    group_commit_interval_ms=50,
    memtable_flush_threshold=134_217_728,
    edge_uniqueness=False,
    compact_after_n_flushes=3,
    dense_vector_dimension=384,
    dense_vector_metric="cosine",
)
```

--------------------------------

### Get Edge by ID

Source: https://overgraph.io/docs/api/nodes-edges

Retrieves a single edge by its auto-assigned ID.

```APIDOC
## Get Edge by ID

### Description
Retrieves a single edge by its auto-assigned ID.

### Method
db.get_edge(id)

### Parameters
#### Path Parameters
- **id** (int) - Required - Edge ID to retrieve.

### Returns
`EdgeRecord | None` - `None`/`null` if the edge does not exist or has been deleted.

### Example
```python
edge = db.get_edge(edge_id)
if edge:
    print(f"{edge.from_id} -> {edge.to_id} (type={edge.type_id}, weight={edge.weight})")
```
```

--------------------------------

### Get Edge by Triple

Source: https://overgraph.io/docs/api/nodes-edges

Looks up an edge by its `(from_id, to_id, type_id)` triple. This is most meaningful when `edge_uniqueness` is enabled.

```python
edge = db.get_edge_by_triple(alice_id, atlas_id, WORKS_ON)
if edge:
    print(f"Edge {edge.id}: weight={edge.weight}, props={edge.props}")
```

--------------------------------

### OverGraph.open()

Source: https://overgraph.io/docs/api/database

Opens an existing database or creates a new one. The database is a self-contained directory on disk. Configuration values are persisted in the manifest on first open.

```APIDOC
## OverGraph.open(path, **kwargs)

### Description
Opens an existing database or creates a new one. A database is a self-contained directory on disk.

### Parameters
#### Path Parameters
- **path** (str) - Required - Directory path for the database. Created if it does not exist (when `create_if_missing` is `true`). Must be a valid filesystem path.

#### Keyword Arguments
- **options** (**kwargs) - Optional - Database configuration. See DbOptions for the full reference.

### Returns
- **OverGraph** - A new database instance. On failure, raises/returns an error if the path is inaccessible, the manifest is corrupt, or WAL replay fails.

### Behavior
- If the directory does not exist and `create_if_missing` is `true` (the default), the directory is created automatically.
- If the directory contains an existing database, OverGraph loads the manifest, opens all segments, and replays WAL generations to recover in-flight state.
- Configuration values (`wal_sync_mode`, `dense_vector`, etc.) are persisted in the manifest on first open. Subsequent opens use the persisted configuration; the values you pass are only used for the initial creation.
- Opening the same directory from multiple processes simultaneously is **not supported** and may cause data corruption.

### Examples
```python
from overgraph import OverGraph

# Minimal -- open with defaults
db = OverGraph.open("./my-graph")

# Full options
db = OverGraph.open(
    "./my-graph",
    create_if_missing=True,
    wal_sync_mode="group_commit",
    group_commit_interval_ms=50,
    memtable_flush_threshold=134_217_728,
    edge_uniqueness=False,
    compact_after_n_flushes=3,
    dense_vector_dimension=384,
    dense_vector_metric="cosine",
)
```
```

--------------------------------

### Get Node by Key

Source: https://overgraph.io/docs/api/nodes-edges

Looks up a node by its (type_id, key) pair using the type index for fast lookup.

```python
node = db.get_node_by_key(USER, "user:alice")
if node:
    print(f"Found node {node.id}: {node.props}")
```

--------------------------------

### Get Node Records by Type

Source: https://overgraph.io/docs/api/discovery

Retrieves full NodeRecord objects for all nodes of a given type, including their properties and weights.

```python
users = db.get_nodes_by_type(USER)

for user in users:
    print(f"[{user.id}] {user.key}: {user.props}")
```

--------------------------------

### Open a Database

Source: https://overgraph.io/docs

Open or create a new OverGraph database by pointing to a directory. No connection strings or config files are needed.

```python
from overgraph import OverGraph

db = OverGraph.open("./my-graph")
```

--------------------------------

### Get Edge by Triple

Source: https://overgraph.io/docs/api/nodes-edges

Looks up an edge using its `(from_id, to_id, type_id)` triple. This method is most meaningful when `edge_uniqueness` is enabled.

```APIDOC
## Get Edge by Triple

### Description
Looks up an edge using its `(from_id, to_id, type_id)` triple. This method is most meaningful when `edge_uniqueness` is enabled.

### Method
db.get_edge_by_triple(from_id, to_id, type_id)

### Parameters
#### Path Parameters
- **from_id** (int) - Required - Source node ID.
- **to_id** (int) - Required - Destination node ID.
- **type_id** (int) - Required - Edge type identifier.

### Returns
`EdgeRecord | None`.

### Example
```python
edge = db.get_edge_by_triple(alice_id, atlas_id, WORKS_ON)
if edge:
    print(f"Edge {edge.id}: weight={edge.weight}, props={edge.props}")
```
```

--------------------------------

### Open Database with Dot Product

Source: https://overgraph.io/docs/api

Initializes an OverGraph database using dot product as the dense vector metric, with a defined vector dimension. This setting is permanent for the database's lifetime.

```python
db = OverGraph.open("./my-graph",
    dense_vector_dimension=1536,
    dense_vector_metric="dot_product")
```

--------------------------------

### Get Edge by ID

Source: https://overgraph.io/docs/api/nodes-edges

Retrieves a single edge using its unique ID. Returns `None` if the edge does not exist or has been deleted.

```python
edge = db.get_edge(edge_id)
if edge:
    print(f"{edge.from_id} -> {edge.to_id} (type={edge.type_id}, weight={edge.weight})")
```

--------------------------------

### OverGraph.open()

Source: https://overgraph.io/docs/api

Opens an existing database or creates a new one at the specified path. Configuration options can be provided to customize database behavior.

```APIDOC
## OverGraph.open(path, **kwargs)

### Description
Opens an existing database or creates a new one. A database is a self-contained directory on disk.

### Parameters
#### Path Parameters
- **path** (str) - Required - Directory path for the database. Created if it does not exist (when `create_if_missing` is `true`). Must be a valid filesystem path.
- **options** (**kwargs) - Optional - Database configuration. See DbOptions for the full reference.

### Returns
- **OverGraph** - A new database instance. On failure, raises/returns an error if the path is inaccessible, the manifest is corrupt, or WAL replay fails.

### Behavior
If the directory does not exist and `create_if_missing` is `true` (the default), the directory is created automatically.
If the directory contains an existing database, OverGraph loads the manifest, opens all segments, and replays WAL generations to recover in-flight state.
Configuration values (`wal_sync_mode`, `dense_vector`, etc.) are persisted in the manifest on first open. Subsequent opens use the persisted configuration; the values you pass are only used for the initial creation.
Opening the same directory from multiple processes simultaneously is **not supported** and may cause data corruption.

### Request Example
```python
from overgraph import OverGraph

# Minimal -- open with defaults
db = OverGraph.open("./my-graph")

# Full options
db = OverGraph.open(
    "./my-graph",
    create_if_missing=True,
    wal_sync_mode="group_commit",
    group_commit_interval_ms=50,
    memtable_flush_threshold=134_217_728,
    edge_uniqueness=False,
    compact_after_n_flushes=3,
    dense_vector_dimension=384,
    dense_vector_metric="cosine",
)
```
```

--------------------------------

### Explain Pattern Query

Source: https://overgraph.io/docs/api/queries

Returns the plan for a graph pattern query without executing it. Reports the selected anchor alias and the physical plan used for that anchor.

```APIDOC
## explain_pattern_query
db.explain_pattern_query(request)

### Description
Returns the plan for a graph pattern query without executing it. Reports the selected anchor alias and the physical plan used for that anchor.

### Returns
#### Success Response
QueryPlan object.

### Request Example
```python
plan = db.explain_pattern_query(pattern)
```
```

--------------------------------

### Batch Get Nodes by IDs

Source: https://overgraph.io/docs/api/nodes-edges

Efficiently retrieves multiple nodes by their IDs. Returns `None` for missing or deleted nodes.

```python
nodes = db.get_nodes([alice_id, bob_id, missing_id])
# nodes[0] = NodeRecord for alice
# nodes[1] = NodeRecord for bob
# nodes[2] = None (not found)

for node in nodes:
    if node:
        print(f"{node.key}: {node.props}")
```

--------------------------------

### Python Async API Usage

Source: https://overgraph.io/docs/api/maintenance

Illustrates how to use the asynchronous API in Python with `AsyncOverGraph`, including context manager usage and basic operations.

```APIDOC
## Python Async
The `AsyncOverGraph` class wraps every method with `asyncio.to_thread()`. Method signatures are identical to the synchronous API. The GIL is released during the underlying Rust operations, enabling true parallelism for I/O-bound graph work.
```python
from overgraph import AsyncOverGraph

# Context manager support
async with await AsyncOverGraph.open("./my-graph") as db:
    # All methods are async -- same signatures as sync API
    alice = await db.upsert_node(1, "user:alice", props={"name": "Alice"})
    bob = await db.upsert_node(1, "user:bob", props={"name": "Bob"})

    await db.upsert_edge(alice, bob, 10)

    neighbors = await db.neighbors(alice, direction="outgoing")
    path = await db.shortest_path(alice, bob)

    await db.compact()
    # db.close() called automatically by context manager

# Without context manager
db = await AsyncOverGraph.open("./my-graph")
try:
    node = await db.get_node(node_id)
    stats = await db.compact()
finally:
    await db.close()
```
```

--------------------------------

### Remove a Retention Policy

Source: https://overgraph.io/docs/api/temporal

Delete a specific retention policy by its name using `remove_prune_policy`. This example removes the `low_signal` policy.

```python
db.remove_prune_policy("low_signal")
```

--------------------------------

### Creating a Temporal Edge

Source: https://overgraph.io/docs/api/temporal

Demonstrates how to create edges with a defined validity window using `valid_from` and `valid_to` timestamps.

```APIDOC
## Creating a Temporal Edge

Set `valid_from` and `valid_to` when upserting an edge to define its validity window.

```python
# Alice works at Acme from Jan 1 to Mar 1, 2024
db.upsert_edge(alice_id, acme_id, WORKS_AT,
    props={"title": "contractor", "department": "engineering"},
    weight=1.0,
    valid_from=1704067200000,  # Jan 1, 2024 00:00 UTC
    valid_to=1709251200000)    # Mar 1, 2024 00:00 UTC

# Open-ended: valid from a date with no end
db.upsert_edge(alice_id, acme_id, WORKS_AT,
    props={"title": "full-time"},
    weight=1.0,
    valid_from=1709251200000)  # valid_to omitted = no expiry
```
```

--------------------------------

### Get Edge Records by Type

Source: https://overgraph.io/docs/api/discovery

Retrieves full EdgeRecord objects for all edges of a given type, including their weights and connected node IDs.

```python
edges = db.get_edges_by_type(WORKS_ON)

for edge in edges:
    print(f"{edge.from_id} --[{edge.weight}]--> {edge.to_id}")
```

--------------------------------

### db.compact_with_progress(callback)

Source: https://overgraph.io/docs/api/maintenance

Similar to `compact()`, but invokes a callback function at each compaction phase to report progress or allow cancellation.

```APIDOC
## db.compact_with_progress(callback)

### Description
Same as `compact()` but invokes a callback at each compaction phase, allowing you to report progress or cancel the operation mid-flight.

### Method
`db.compact_with_progress(callback)`

### Parameters
- `callback` (function): A function that accepts a `Progress` object and returns a boolean. Return `false` to cancel the compaction safely.

### Response
- `CompactionStats` | `None` (Python/Rust), `null` (Node.js): Statistics about the compaction or null/None if no merge occurred.

### Progress Fields (passed to callback)
- `phase` (string): Current phase: `"collecting_tombstones"`, `"merging_nodes"`, `"merging_edges"`, or `"writing_output"`.
- `segments_processed` (int): Number of input segments processed so far.
- `total_segments` (int): Total input segments in this compaction run.
- `records_processed` (int): Records processed in the current phase.
- `total_records` (int): Total records to process in the current phase.

### Cancellation
Return `false` from the callback to cancel compaction safely. No database state is modified on cancellation; original segments remain intact and a `CompactionCancelled` error is returned. Note: Node.js async variant `compactWithProgressAsync` does not support cancellation.
```

--------------------------------

### Get Node by ID

Source: https://overgraph.io/docs/api/nodes-edges

Retrieves a single node by its auto-assigned ID. This operation is fast for hot paths but requires I/O for segment reads.

```python
node = db.get_node(alice_id)
if node:
    print(f"key={node.key}, type={node.type_id}, weight={node.weight}")
    print(f"props: {node.props}")
    print(f"created: {node.created_at}, updated: {node.updated_at}")
```

--------------------------------

### Compact with progress reporting

Source: https://overgraph.io/docs/api/maintenance

Employ `db.compact_with_progress(callback)` for compactions that require progress reporting or cancellation. The callback function receives progress updates and can return `false` to halt the operation safely.

```python
def on_progress(progress):
    print(f"[{progress.phase}] segments: {progress.segments_processed}/{progress.total_segments}")
    print(f"  records: {progress.records_processed}/{progress.total_records}")
    return True  # return False to cancel safely

stats = db.compact_with_progress(on_progress)  # CompactionStats | None
```

--------------------------------

### Open Database with Dense Vector Configuration

Source: https://overgraph.io/docs/api/database

Opens a database connection, configuring dense vector embeddings with different similarity metrics. The dense vector configuration is set once at database creation and cannot be changed later.

```python
# Cosine similarity (default metric)
db = OverGraph.open("./my-graph",
    dense_vector_dimension=384,
    dense_vector_metric="cosine")
```

```python
# Euclidean distance
db = OverGraph.open("./my-graph",
    dense_vector_dimension=768,
    dense_vector_metric="euclidean")
```

```python
# Dot product
db = OverGraph.open("./my-graph",
    dense_vector_dimension=1536,
    dense_vector_metric="dot_product")
```

--------------------------------

### Run Shortest Path Algorithm

Source: https://overgraph.io/docs

Find the shortest path between two nodes using the built-in algorithm. This operates directly on the live graph.

```python
path = db.shortest_path(alice, bob)
```

--------------------------------

### Get Node Degree

Source: https://overgraph.io/docs/api/traversal

Retrieve the number of edges connected to a node. Supports filtering by direction and edge type, or querying at a specific historical epoch.

```python
count = db.degree(alice_id)

# With filters
filtered = db.degree(alice_id, direction="outgoing", type_filter=[WORKS_ON])

# Temporal
count_at = db.degree(alice_id, at_epoch=1706745600000)
```

--------------------------------

### Explain Node Query

Source: https://overgraph.io/docs/api/queries

Returns the planner tree, cost estimates, and warnings for a node query without executing it. Same validation rules as execution.

```APIDOC
## explain_node_query
db.explain_node_query(request)

### Description
Returns the planner tree, cost estimates, and warnings for a node query without executing it. Same validation rules as execution.

### Returns
#### Success Response
QueryPlan object with the selected physical plan, estimated candidates, and any warnings.

### Request Example
```python
plan = db.explain_node_query({
    "type_id": USER,
    "filter": {"property": "status", "eq": "active"},
})
```
```

--------------------------------

### Update a Retention Policy

Source: https://overgraph.io/docs/api/temporal

Modify an existing retention policy by calling `set_prune_policy` with the same policy name. This example extends the `stale_sessions` policy to 2 hours.

```python
db.set_prune_policy("stale_sessions",
    max_age_ms=7_200_000,        # extend to 2 hours
    type_id=CONVERSATION)
```

--------------------------------

### Get Node Degrees in Batch

Source: https://overgraph.io/docs/api/traversal

Efficiently retrieve the edge counts for multiple nodes in a single call. Accepts the same filtering parameters as the single-node `degree` function.

```python
degrees = db.degrees([alice_id, bob_id, charlie_id])
for node_id, count in degrees.items():
    print(f"node {node_id}: {count} edges")
```

--------------------------------

### Querying at a Point in Time

Source: https://overgraph.io/docs/api/temporal

Illustrates how to query graph data as it existed at a specific historical point using the `at_epoch` parameter.

```APIDOC
## Querying at a Point in Time

Pass `at_epoch` to any neighbor or traversal query to see only edges whose validity window contains that timestamp. Without `at_epoch`, all edges are returned regardless of their temporal bounds.

```python
# Feb 1: Alice's contract is active
feb_neighbors = db.neighbors(alice_id, direction="outgoing",
    at_epoch=1706745600000)   # Feb 1, 2024
# Returns the WORKS_AT edge to Acme

# Apr 1: contract has ended
apr_neighbors = db.neighbors(alice_id, direction="outgoing",
    at_epoch=1711929600000)   # Apr 1, 2024
# WORKS_AT edge excluded (valid_to was Mar 1)

# No epoch: returns all edges regardless of temporal bounds
all_neighbors = db.neighbors(alice_id, direction="outgoing")
```
```

--------------------------------

### all_shortest_paths

Source: https://overgraph.io/docs/api/traversal

Finds all paths that share the same minimum cost. Can be capped by max_paths.

```APIDOC
## all_shortest_paths

### Description
Find all paths that share the same minimum cost. Accepts the same parameters as `shortest_path` plus `max_paths`.

### Method Signature
db.all_shortest_paths(from_id, to_id, direction?, type_filter?, weight_field?, at_epoch?, max_depth?, max_cost?, max_paths?)

### Parameters
#### Path Parameters
- **from** (node ID) - Required - Source node
- **to** (node ID) - Required - Destination node

#### Query Parameters
- **direction** (outgoing | incoming | both) - Optional - Default: `outgoing` - Edge traversal direction
- **type_filter** (edge type ID[]) - Optional - Restrict to specific edge types
- **weight_field** (string) - Optional - Use a property key to read cost from an edge property instead. `None` uses `edge.weight` (BFS when all weights are 1.0).
- **at_epoch** (u64) - Optional - Only traverse edges valid at this epoch (ms)
- **max_depth** (u32) - Optional - Maximum number of hops
- **max_cost** (f64) - Optional - Cap on total path cost (Dijkstra only)
- **max_paths** (u32) - Optional - Cap on returned paths. Prevents combinatorial explosion in dense graphs.

### Return Value
Returns an array of **ShortestPath** objects, all with the same cost. Can be empty if no path exists.

### Request Example
```python
# All equal-cost shortest paths (capped at 10)
paths = db.all_shortest_paths(alice_id, project_id, max_paths=10)
print(f"Found {len(paths)} equal-cost paths")

for i, p in enumerate(paths):
    print(f"  Path {i}: {p.nodes} (cost {p.total_cost}")

# Weighted with type filter
paths = db.all_shortest_paths(alice_id, project_id,
    weight_field="weight",
    type_filter=[WORKS_ON],
    max_paths=5)
```
```

--------------------------------

### Get Edge IDs by Type

Source: https://overgraph.io/docs/api/discovery

Retrieves all edge IDs for a given type, automatically excluding dangling edges. The returned IdArray has the same interface as node IDs.

```python
edge_ids = db.edges_by_type(WORKS_ON)
print(f"Total WORKS_ON edges: {len(edge_ids)}")

for eid in edge_ids:
    edge = db.get_edge(eid)
    print(f"{edge.from_id} -> {edge.to_id}")
```

--------------------------------

### Begin and stage operations in a write transaction

Source: https://overgraph.io/docs/api/transactions

Initiate a write transaction to stage ordered graph mutations locally. This allows for read-own-writes before commit and supports referencing staged data using local aliases. Commit fails if staged targets have changed since the transaction began.

```python
txn = db.begin_write_txn()
txn.stage([
    {"op": "upsert_node", "alias": "alice", "type_id": USER, "key": "alice"},
    {"op": "upsert_node", "alias": "bob", "type_id": USER, "key": "bob"},
    {"op": "upsert_edge", "alias": "knows",
     "from": {"local": "alice"}, "to": {"local": "bob"}, "type_id": KNOWS},
])

# Read-own-writes: see staged data before commit
staged = txn.get_node({"local": "alice"})

result = txn.commit()
alice_id = result.node_aliases["alice"]
bob_id = result.node_aliases["bob"]
```

--------------------------------

### Enter bulk ingest mode

Source: https://overgraph.io/docs/api/maintenance

Initiate bulk ingest mode with `db.ingest_mode()` to disable auto-compaction for maximum write throughput during large data loads. The memtable continues to flush normally.

```python
db.ingest_mode()

# Bulk writes here -- auto-compaction disabled, memtable still flushes
for batch in data_batches:
    db.batch_upsert_nodes(batch)
```

--------------------------------

### Retrieve Node Neighbors

Source: https://overgraph.io/docs/api/traversal

Get immediate neighbors of a node, with options to filter by direction, edge type, limit results, and apply temporal windows or decay scoring.

```python
# All outgoing neighbors (default)
neighbors = db.neighbors(alice_id)

# Filter by edge type, limit results, temporal window
filtered = db.neighbors(alice_id,
    direction="outgoing",
    type_filter=[WORKS_ON],
    limit=50,
    at_epoch=1706745600000)

for n in filtered:
    print(f"node={n.node_id} edge={n.edge_id} weight={n.weight}")

# With decay scoring
decayed = db.neighbors(alice_id, decay_lambda=0.01)
for n in decayed:
    print(f"node={n.node_id} decay_weight={n.weight}")
```

--------------------------------

### Extract Complete Subgraph

Source: https://overgraph.io/docs/api/traversal

Extract a complete subgraph reachable from a start node up to a specified depth, returning full node and edge records. This is useful for exporting local neighborhoods.

```python
# Extract 2-hop subgraph
sub = db.extract_subgraph(alice_id, 2)
print(f"{len(sub.nodes)} nodes, {len(sub.edges)} edges")

for node in sub.nodes:
    print(f"node {node.id}: type={node.type_id} key={node.key}")
for edge in sub.edges:
    print(f"edge {edge.id}: {edge.from_id} -> {edge.to_id}")
```

--------------------------------

### Run Exact Personalized PageRank

Source: https://overgraph.io/docs/api/algorithms

Executes the exact PageRank algorithm from a single seed node. Displays convergence status and iteration count.

```python
# Exact PPR from a single seed (default)
ranks = db.personalized_pagerank([alice_id])
print(f"Converged: {ranks.converged} in {ranks.iterations} iterations")

for node_id, score in zip(ranks.node_ids, ranks.scores):
    print(f"  node {node_id}: relevance {score:.4f}")
```

--------------------------------

### Get Nodes by IDs

Source: https://overgraph.io/docs/api/nodes-edges

Batch-retrieves multiple nodes by their IDs. This method uses a sorted merge-walk across all data sources, making it much faster than calling `get_node` in a loop.

```APIDOC
## Get Nodes by IDs

### Description
Batch-retrieves multiple nodes by their IDs. This method uses a sorted merge-walk across all data sources, making it much faster than calling `get_node` in a loop.

### Method
db.get_nodes(ids)

### Parameters
#### Path Parameters
- **ids** (list[int]) - Required - Array of node IDs to fetch.

### Returns
Array of `NodeRecord | None` in input order. Missing or deleted nodes appear as `None`/`null`.

### Example
```python
nodes = db.get_nodes([alice_id, bob_id, missing_id])
# nodes[0] = NodeRecord for alice
# nodes[1] = NodeRecord for bob
# nodes[2] = None (not found)

for node in nodes:
    if node:
        print(f"{node.key}: {node.props}")
```
```

--------------------------------

### Find All Equal-Cost Shortest Paths

Source: https://overgraph.io/docs/api/traversal

Retrieves all paths that share the minimum cost. Use `max_paths` to prevent excessive results in dense graphs.

```python
# All equal-cost shortest paths (capped at 10)
paths = db.all_shortest_paths(alice_id, project_id, max_paths=10)
print(f"Found {len(paths)} equal-cost paths")

for i, p in enumerate(paths):
    print(f"  Path {i}: {p.nodes} (cost {p.total_cost}")
```

```python
# Weighted with type filter
paths = db.all_shortest_paths(alice_id, project_id,
    weight_field="weight",
    type_filter=[WORKS_ON],
    max_paths=5)
```

--------------------------------

### Find Nodes by Time Range

Source: https://overgraph.io/docs/api/discovery

Use `find_nodes_by_time_range` to efficiently retrieve nodes updated within a specific time window using the timestamp index. Both start and end times are inclusive.

```python
import time

# Users updated in the last 24 hours
now = int(time.time() * 1000)
one_day_ago = now - 86_400_000

recent_ids = db.find_nodes_by_time_range(USER, one_day_ago, now)
print(f"Recently updated users: {len(recent_ids)}")

for node_id in recent_ids:
    node = db.get_node(node_id)
    print(f"  {node.key} updated at {node.updated_at}")

```

--------------------------------

### Python Async API Usage with Context Manager

Source: https://overgraph.io/docs/api/maintenance

Utilize the `AsyncOverGraph` with an async context manager for automatic resource management. All methods are awaitable and have the same signatures as their synchronous counterparts.

```python
from overgraph import AsyncOverGraph

# Context manager support
async with await AsyncOverGraph.open("./my-graph") as db:
    # All methods are async -- same signatures as sync API
    alice = await db.upsert_node(1, "user:alice", props={"name": "Alice"})
    bob = await db.upsert_node(1, "user:bob", props={"name": "Bob"})

    await db.upsert_edge(alice, bob, 10)

    neighbors = await db.neighbors(alice, direction="outgoing")
    path = await db.shortest_path(alice, bob)

    await db.compact()
    # db.close() called automatically by context manager
```

--------------------------------

### Graph-Scoped Hybrid Search

Source: https://overgraph.io/docs/api/vector-search

Conduct a hybrid vector search constrained to a specific subgraph. This example searches for conversations within Alice's team, limited by depth and edge type.

```python
# Graph-scoped hybrid search:
# "Find conversations similar to this query, but only within Alice's team"
hits = db.vector_search("hybrid",
    k=10,
    dense_query=query_embedding,
    sparse_query=sparse_terms,
    type_filter=[CONVERSATION],
    ef_search=200,
    scope_start_node_id=alice_id,
    scope_max_depth=3,
    scope_direction="outgoing",
    scope_edge_type_filter=[WORKS_ON],
    dense_weight=0.7,
    sparse_weight=0.3,
    fusion_mode="reciprocal_rank")
```

--------------------------------

### db.sync()

Source: https://overgraph.io/docs/api/maintenance

Forces a file system synchronization of the write-ahead log (WAL) to disk. In GroupCommit mode (default), this operation blocks until all buffered WAL data is fsynced, providing an explicit durability checkpoint.

```APIDOC
## db.sync()

### Description
Forces-fsyncs the write-ahead log to disk. In `Immediate` sync mode this is a no-op since every write already fsyncs. In `GroupCommit` mode (the default), `sync` blocks until all buffered WAL data is fsynced, giving you an explicit durability checkpoint.

### Method
`db.sync()`

### Parameters
None

### Response
None

### Sync Modes
- `Immediate`: No-op. Every write already calls fsync.
- `GroupCommit`: Blocks until the 10ms batch timer flushes and fsyncs pending WAL entries.
```

--------------------------------

### db.extract_subgraph

Source: https://overgraph.io/docs/api/traversal

Extracts a complete subgraph reachable from a specified start node up to a maximum depth. It returns full node and edge records, including all properties and metadata, which is useful for visualization or external processing.

```APIDOC
## db.extract_subgraph

### Description
Extracts a complete subgraph reachable from a start node, returning full node and edge records (not just IDs). Useful for exporting a local neighborhood for visualization or external processing.

### Parameters
#### Path Parameters
- **start_node_id** (int) - Required - The root node
- **max_depth** (int) - Required - Maximum hop count
#### Query Parameters
- **direction** (Direction) - Optional - Traversal direction. Can be `Outgoing`, `Incoming`, or `Both`. Defaults to `Outgoing`.
- **edge_type_filter** (list[int]) - Optional - Only follow edges of these types.
- **at_epoch** (int) - Optional - Temporal filter: only edges valid at this epoch (ms).

### Returns: Subgraph
- **nodes** (NodeRecord[]) - Full node records (id, type_id, key, props, weight, vectors, timestamps)
- **edges** (EdgeRecord[]) - Full edge records (id, from, to, type_id, props, weight, valid_from, valid_to)

Unlike `traverse`, this returns complete records with all properties and metadata, not just IDs and depth information. The result includes every node and edge within the reachable subgraph.

### Request Example
```python
# Extract 2-hop subgraph
sub = db.extract_subgraph(alice_id, 2)
print(f"{len(sub.nodes)} nodes, {len(sub.edges)} edges")

for node in sub.nodes:
    print(f"node {node.id}: type={node.type_id} key={node.key}")
for edge in sub.edges:
    print(f"edge {edge.id}: {edge.from_id} -> {edge.to_id}")

# Filtered by edge type and temporal window
sub = db.extract_subgraph(alice_id, 2,
    edge_type_filter=[WORKS_ON],
    at_epoch=1706745600000)
```
```

--------------------------------

### Get Node IDs by Type

Source: https://overgraph.io/docs/api/discovery

Retrieves all node IDs for a given type. The returned IdArray is a lazy wrapper supporting len(), indexing, iteration, and to_list(). Complexity is O(type index size).

```python
ids = db.nodes_by_type(USER)

print(f"Total users: {len(ids)}")
print(f"First user:  {ids[0]}")
print(f"Contains?    {alice_id in ids}")

# Iterate lazily -- no list materialisation
for node_id in ids:
    node = db.get_node(node_id)
    print(node.key)

# Or materialise when you need a plain list
user_list = ids.to_list()
```

--------------------------------

### Query Node IDs

Source: https://overgraph.io/docs/api/queries

Runs a node query and returns matching node IDs in ascending order. OverGraph selects the cheapest execution path using available indexes, then verifies every candidate against the visible record.

```APIDOC
## query_node_ids
db.query_node_ids(request)

### Description
Runs a node query and returns matching node IDs in ascending order. OverGraph selects the cheapest execution path using available indexes, then verifies every candidate against the visible record.

### Parameters
#### Path Parameters
- `request` (dict | NodeQueryRequest) - Required - Node query request. See NodeQuery.

### Returns
#### Success Response
- `items` (IdArray) - Matching node IDs in ascending order
- `next_cursor` (int | None) - Cursor for the next page. Pass as `after`.

### Request Example
```python
page = db.query_node_ids({
    "type_id": USER,
    "filter": {
        "and": [
            {"property": "status", "eq": "active"},
            {"property": "score", "gte": 50},
        ],
    },
    "limit": 100,
})
```
```

--------------------------------

### Get Edges by IDs

Source: https://overgraph.io/docs/api/nodes-edges

Retrieve multiple edges by their IDs in a single call using a sorted merge-walk. The function returns an array of `EdgeRecord` objects or `None` for IDs that do not exist, maintaining the input order.

```python
edges = db.get_edges([e1, e2, e3])
for edge in edges:
    if edge:
        print(f"edge {edge.id}: {edge.from_id} -> {edge.to_id} (w={edge.weight})")
```

--------------------------------

### List Node Property Indexes (Python)

Source: https://overgraph.io/docs/api/indexes

Retrieve a list of all declared optional property indexes and their current states. This is useful for monitoring index status and identifying any errors.

```python
indexes = db.list_node_property_indexes()

for idx in indexes:
    print(f"[{idx.index_id}] type={idx.type_id} "
          f"prop={idx.prop_key} kind={idx.kind} "
          f"state={idx.state}")

    if idx.last_error:
        print(f"  Error: {idx.last_error}")
```

--------------------------------

### Run Personalized PageRank

Source: https://overgraph.io/docs

Execute the Personalized PageRank algorithm directly on the live graph data. No data export or batch processing is required.

```python
ranks = db.personalized_pagerank([alice])
```

--------------------------------

### db.traverse

Source: https://overgraph.io/docs/api/traversal

Performs a Breadth-First Search (BFS) traversal from a specified start node up to a maximum depth. It returns a deduplicated set of reachable nodes along with their depth and path information. Supports various filtering and scoring options.

```APIDOC
## db.traverse

### Description
BFS traversal from a start node up to `max_depth` hops. Returns a deduplicated set of reachable nodes with depth and path information.

### Parameters
#### Path Parameters
- **start_node_id** (int) - Required - The root node to traverse from
- **max_depth** (int) - Required - Maximum hop count from start
#### Query Parameters
- **min_depth** (int) - Optional - Minimum depth to include. Set to `0` to include the start node. Defaults to `1`.
- **direction** (Direction) - Optional - Traversal direction. Can be `Outgoing`, `Incoming`, or `Both`. Defaults to `Outgoing`.
- **edge_type_filter** (list[int]) - Optional - Only follow edges of these types.
- **node_type_filter** (list[int]) - Optional - Only include nodes of these types in results (edges are still followed through non-matching nodes).
- **at_epoch** (int) - Optional - Temporal filter: only follow edges valid at this epoch (ms).
- **decay_lambda** (float) - Optional - Exponential decay factor for scoring.
- **limit** (int) - Optional - Maximum number of results per page.
- **cursor** (TraversalCursor) - Optional - Pagination cursor from a previous traversal page.

### Returns: TraversalHit[]
- **node_id** (int) - The discovered node
- **depth** (int) - Hop count from start node
- **via_edge_id** (int | None) - The edge used to reach this node (`None` for the start node when `min_depth=0`)
- **score** (float | None) - Decay-adjusted score (only present when `decay_lambda` is set)

Results are ordered by `(depth ASC, node_id ASC)`. The `node_type_filter` controls which nodes appear in results but does not prevent the traversal from following edges through non-matching node types.

### Request Example
```python
# Basic 3-hop traversal
page = db.traverse(alice_id, 3)
for hit in page.items:
    print(f"depth={hit.depth} node={hit.node_id}")

# Constrained: specific types, min depth, pagination
page = db.traverse(alice_id, 3,
    min_depth=2,
    edge_type_filter=[WORKS_ON],
    node_type_filter=[PROJECT],
    limit=50)

# Paginate through results
while page.next_cursor is not None:
    page = db.traverse(alice_id, 3,
        min_depth=2,
        edge_type_filter=[WORKS_ON],
        node_type_filter=[PROJECT],
        limit=50,
        cursor=page.next_cursor)
    for hit in page.items:
        print(f"depth={hit.depth} node={hit.node_id}")
```
```

--------------------------------

### Create Nodes

Source: https://overgraph.io/docs

Create nodes in the graph database. Nodes have a key, type, weight, and optional properties. Upsert semantics ensure safe multiple calls.

```python
# Type IDs are numbers you define: 1 = Person, 2 = Post
alice = db.upsert_node(1, "user:alice", props={"name": "Alice"})
bob = db.upsert_node(1, "user:bob")
post = db.upsert_node(2, "post:hello", weight=0.8)
```

--------------------------------

### Force WAL fsync to disk

Source: https://overgraph.io/docs/api/maintenance

Use `db.sync()` to explicitly force-fsync the write-ahead log to disk. In `GroupCommit` mode, this blocks until all buffered WAL data is synced, providing a durability checkpoint.

```python
db.sync()  # blocks until WAL fsynced (GroupCommit mode)
```
Tokens:
Raw