overgraph 0.9.0

# OverGraph API Reference

Complete reference for OverGraph's public API across **Rust**, **Node.js**, and **Python**. Every method, parameter, type, and return value is documented.

> **Conventions used in this document:**
>
> - Parameters marked **required** must always be provided. Parameters marked **optional** may be omitted and will use documented defaults.
> - `u32` / `u64` / `i64` / `f32` / `f64` refer to fixed-width numeric types. In Node.js these map to `number`; in Python to `int` or `float`.
> - All timestamps are **milliseconds since Unix epoch** (January 1, 1970 00:00:00 UTC).
> - All IDs (`node_id`, `edge_id`) are unsigned 64-bit integers. In Node.js they are represented as `number` (safe up to 2^53 - 1). In Python they are `int` (unlimited precision).
> - Code examples show all three languages. Rust examples assume `use overgraph::*;` is in scope.

---

## Table of Contents

- [Installation](#installation)
- [Database Lifecycle](#database-lifecycle)
  - [open](#open)
  - [close](#close)
  - [close_fast](#close_fast)
  - [stats](#stats)
- [Configuration](#configuration)
  - [DbOptions](#dboptions)
  - [WalSyncMode](#walsyncmode)
  - [DenseVectorConfig](#densevectorconfig)
- [Data Model](#data-model)
  - [Node Records](#node-records)
  - [Edge Records](#edge-records)
  - [PropValue](#propvalue)
  - [IntoNodeLabels](#intonodelabels-rust-only)
  - [Direction](#direction)
  - [NodeLabelFilter / LabelMatchMode](#nodelabelfilter--labelmatchmode)
- [Catalog APIs](#catalog-apis)
  - [ensure_node_label / ensure_edge_label](#ensure_node_label--ensure_edge_label)
  - [get_node_label_id / get_edge_label_id](#get_node_label_id--get_edge_label_id)
  - [get_node_label / get_edge_label](#get_node_label--get_edge_label)
  - [list_node_labels / list_edge_labels](#list_node_labels--list_edge_labels)
- [Node Operations](#node-operations)
  - [upsert_node](#upsert_node)
  - [get_node](#get_node)
  - [get_node_by_key](#get_node_by_key)
  - [add_node_label / remove_node_label](#add_node_label--remove_node_label)
  - [delete_node](#delete_node)
  - [batch_upsert_nodes](#batch_upsert_nodes)
  - [get_nodes](#get_nodes)
  - [get_nodes_by_keys](#get_nodes_by_keys)
- [Edge Operations](#edge-operations)
  - [upsert_edge](#upsert_edge)
  - [get_edge](#get_edge)
  - [get_edge_by_triple](#get_edge_by_triple)
  - [delete_edge](#delete_edge)
  - [invalidate_edge](#invalidate_edge)
  - [batch_upsert_edges](#batch_upsert_edges)
  - [get_edges](#get_edges)
- [Atomic Operations](#atomic-operations)
  - [graph_patch](#graph_patch)
  - [write transactions](#write-transactions)
- [Label and Edge-Label Queries](#label-and-edge-label-queries)
  - [nodes_by_labels](#nodes_by_labels)
  - [edges_by_label](#edges_by_label)
  - [get_nodes_by_labels](#get_nodes_by_labels)
  - [get_edges_by_label](#get_edges_by_label)
  - [count_nodes_by_labels](#count_nodes_by_labels)
  - [count_edges_by_label](#count_edges_by_label)
- [Property Index Management](#property-index-management)
  - [ensure_node_property_index](#ensure_node_property_index)
  - [drop_node_property_index](#drop_node_property_index)
  - [list_node_property_indexes](#list_node_property_indexes)
  - [NodePropertyIndexInfo](#nodepropertyindexinfo)
  - [ensure_edge_property_index](#ensure_edge_property_index)
  - [drop_edge_property_index](#drop_edge_property_index)
  - [list_edge_property_indexes](#list_edge_property_indexes)
  - [EdgePropertyIndexInfo](#edgepropertyindexinfo)
  - [PropertyRangeBound](#propertyrangebound)
  - [PropertyRangeCursor](#propertyrangecursor)
  - [PropertyRangePageRequest](#propertyrangepagerequest-rust-only)
  - [PropertyRangePageResult](#propertyrangepageresult)
- [Property & Time Queries](#property--time-queries)
  - [find_nodes](#find_nodes)
  - [find_nodes_range](#find_nodes_range)
  - [find_nodes_by_time_range](#find_nodes_by_time_range)
- [Queries](#queries)
  - [Node Queries](#node-queries)
    - [query_node_ids](#query_node_ids)
    - [query_nodes](#query_nodes)
    - [explain_node_query](#explain_node_query)
  - [Direct Edge Queries](#direct-edge-queries)
    - [query_edge_ids](#query_edge_ids)
    - [query_edges](#query_edges)
    - [explain_edge_query](#explain_edge_query)
  - [Graph Row Queries](#graph-row-queries)
    - [query_graph_rows](#query_graph_rows)
    - [explain_graph_rows](#explain_graph_rows)
  - [GQL Beta](#gql-beta)
    - [Overview](#overview)
    - [Supported Syntax](#supported-syntax)
    - [Method Reference](#method-reference)
    - [Parameters and Options](#parameters-and-options)
    - [Results and Row Formats](#results-and-row-formats)
    - [Nodes, Edges, Values, and Vectors](#nodes-edges-values-and-vectors)
    - [Params](#params)
    - [Explain, Profile, and Stats](#explain-profile-and-stats)
    - [Examples](#examples)
    - [Not Yet Supported In GQL Beta](#not-yet-supported-in-gql-beta)
  - [Query Request Types and Plans](#query-request-types-and-plans)
    - [NodeQuery](#nodequery)
    - [NodeFilter / QueryNodeFilter](#nodefilter--querynodefilter)
    - [EdgeQuery](#edgequery)
    - [EdgeFilter / QueryEdgeFilter](#edgefilter--queryedgefilter)
    - [GraphRowQuery](#graphrowquery)
    - [QueryPlan](#queryplan)
    - [Validation notes](#validation-notes)
- [Pagination](#pagination)
  - [nodes_by_labels_paged](#nodes_by_labels_paged)
  - [edges_by_label_paged](#edges_by_label_paged)
  - [get_nodes_by_labels_paged](#get_nodes_by_labels_paged)
  - [get_edges_by_label_paged](#get_edges_by_label_paged)
  - [find_nodes_paged](#find_nodes_paged)
  - [find_nodes_range_paged](#find_nodes_range_paged)
  - [find_nodes_by_time_range_paged](#find_nodes_by_time_range_paged)
- [Traversal](#traversal)
  - [neighbors](#neighbors)
  - [neighbors_paged](#neighbors_paged)
  - [neighbors_batch](#neighbors_batch)
  - [top_k_neighbors](#top_k_neighbors)
  - [traverse](#traverse)
  - [extract_subgraph](#extract_subgraph)
  - [shortest_path](#shortest_path)
  - [all_shortest_paths](#all_shortest_paths)
  - [is_connected](#is_connected)
- [Degree & Weight Aggregation](#degree--weight-aggregation)
  - [degree](#degree)
  - [degrees](#degrees)
  - [sum_edge_weights](#sum_edge_weights)
  - [avg_edge_weight](#avg_edge_weight)
- [Graph Analytics](#graph-analytics)
  - [connected_components](#connected_components)
  - [component_of](#component_of)
  - [personalized_pagerank](#personalized_pagerank)
  - [export_adjacency](#export_adjacency)
- [Vector Search](#vector-search)
  - [vector_search](#vector_search)
- [Retention & Pruning](#retention--pruning)
  - [prune](#prune)
  - [set_prune_policy](#set_prune_policy)
  - [remove_prune_policy](#remove_prune_policy)
  - [list_prune_policies](#list_prune_policies)
- [Maintenance](#maintenance)
  - [sync](#sync)
  - [flush](#flush)
  - [compact](#compact)
  - [compact_with_progress](#compact_with_progress)
  - [ingest_mode](#ingest_mode)
  - [end_ingest](#end_ingest)
  - [scrub](#scrub)
- [Introspection](#introspection)
  - [node_count](#node_count)
  - [edge_count](#edge_count)
  - [next_node_id](#next_node_id)
  - [next_edge_id](#next_edge_id)
  - [segment_count](#segment_count)
  - [segment_tombstone_node_count](#segment_tombstone_node_count)
  - [segment_tombstone_edge_count](#segment_tombstone_edge_count)
  - [path](#path)
  - [manifest](#manifest)
  - [manifest::load_manifest_readonly](#manifestload_manifest_readonly-rust-only)
- [Binary Batch Ingestion](#binary-batch-ingestion)
  - [batch_upsert_nodes_binary](#batch_upsert_nodes_binary)
  - [batch_upsert_edges_binary](#batch_upsert_edges_binary)
- [Error Handling](#error-handling)
- [Async API](#async-api)

---

## Installation

**Rust** - add to `Cargo.toml`:
```toml
[dependencies]
overgraph = "0.7"
```

**Node.js**:
```bash
npm install overgraph
```

**Python**:
```bash
pip install overgraph
```

Prebuilt binaries are published for Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), and Windows (x86_64). If no prebuilt binary exists for your platform, install a Rust toolchain and the package will compile from source.

---

## Database Lifecycle

### open

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

**Rust**
```rust
let mut db = DatabaseEngine::open(Path::new("./my-graph"), &DbOptions::default())?;
```

**Node.js**
```javascript
const db = OverGraph.open('./my-graph', { /* options */ });
```

**Python**
```python
db = OverGraph.open("./my-graph", **options)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| path | `&Path` | `string` | `str` | Yes | — | Directory path for the database. Created if it doesn't exist (when `create_if_missing` is true). Must be a valid filesystem path. |
| options | `&DbOptions` | `object` | `**kwargs` | No | See [DbOptions](#dboptions) | Database configuration. See the full options reference below. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<DatabaseEngine, EngineError>` | `OverGraph` | `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 doesn't exist and `create_if_missing` is true (the default), the directory is created.
- 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.

#### Example

```rust
// Rust - open with custom options
let opts = DbOptions {
    wal_sync_mode: WalSyncMode::GroupCommit {
        interval_ms: 50,
        soft_trigger_bytes: 2 * 1024 * 1024,
        hard_cap_bytes: 16 * 1024 * 1024,
    },
    edge_uniqueness: true,
    dense_vector: Some(DenseVectorConfig {
        dimension: 384,
        metric: DenseMetric::Cosine,
        hnsw: HnswConfig::default(),
    }),
    ..Default::default()
};
let mut db = DatabaseEngine::open(Path::new("./my-graph"), &opts)?;
```

```javascript
// Node.js - open with custom options
const db = OverGraph.open('./my-graph', {
  walSyncMode: 'group-commit',
  groupCommitIntervalMs: 50,
  edgeUniqueness: true,
  denseVector: { dimension: 384, metric: 'cosine' },
  compactAfterNFlushes: 4,
});
```

```python
# Python - open with custom options
db = OverGraph.open(
    "./my-graph",
    wal_sync_mode="group_commit",
    group_commit_interval_ms=50,
    edge_uniqueness=True,
    dense_vector_dimension=384,
    dense_vector_metric="cosine",
    compact_after_n_flushes=4,
)
```

---

### close

Shuts down the database cleanly.

**Rust**
```rust
db.close()?;
```

**Node.js**
```javascript
db.close();            // sync, waits for compaction
db.close({ force: true }); // sync, cancels compaction
await db.closeAsync(); // async
```

**Python**
```python
db.close()           # waits for compaction
db.close(force=True) # cancels compaction
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| force | Use `close_fast()` instead | `boolean` | `bool` | No | `false` | If `true`, cancels any in-progress background compaction instead of waiting for it to finish. Pending WAL data is still synced. |

#### Behavior

**Normal close** (`force=false`):
1. Freezes the active memtable.
2. Flushes all pending immutable memtables to segments.
3. Waits for any in-progress background compaction to finish.
4. Writes the final manifest.
5. After close, no immutable memtables or retained WAL generations remain.

**Fast close** (`force=true` / `close_fast()` in Rust):
1. Cancels in-progress background compaction (safe because no state is modified until the atomic swap).
2. Syncs the active WAL.
3. Persists the manifest with retained WAL generations (so WAL replay recovers state on next open).

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<(), EngineError>` | `void` / `Promise<void>` | `None` |

#### Context Manager / Destructor

**Python** supports context manager syntax:
```python
with OverGraph.open("./my-graph") as db:
    # Also accepts multiple labels: ["User", "Admin"]
    db.upsert_node("User", "alice")
# db.close() called automatically on exit
```

**Node.js** has no built-in equivalent; call `close()` or `closeAsync()` explicitly in a `finally` block.

---

### close_fast

Rust-only fast close. This is the same behavior exposed by `close({ force: true })` in Node.js and `close(force=True)` in Python.

```rust
db.close_fast()?;
```

It cancels any in-progress background compaction, syncs the active WAL, and persists a manifest that retains the WAL generations needed for replay on the next open.

---

### stats

Returns a read-only snapshot of current database statistics.

**Rust**
```rust
let s = db.stats()?;
println!("segments: {}, WAL bytes: {}", s.segment_count, s.pending_wal_bytes);
```

**Node.js**
```javascript
const s = db.stats();
console.log(`segments: ${s.segmentCount}, WAL bytes: ${s.pendingWalBytes}`);
```

**Python**
```python
s = db.stats()
print(f"segments: {s.segment_count}, WAL bytes: {s.pending_wal_bytes}")
```

#### Parameters

None.

#### Returns: DbStats

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| pending_wal_bytes | `usize` | `number` | `int` | Bytes buffered in the WAL not yet fsynced to disk. |
| segment_count | `usize` | `number` | `int` | Number of immutable segments on disk. |
| node_tombstone_count | `usize` | `number` | `int` | Soft-deleted nodes in the active memtable (reclaimed at compaction). |
| edge_tombstone_count | `usize` | `number` | `int` | Soft-deleted edges in the active memtable. |
| last_compaction_ms | `Option<i64>` | `number \| null` | `int \| None` | Unix timestamp (ms) of the last completed compaction, or null if none. |
| wal_sync_mode | `String` | `string` | `str` | `"immediate"` or `"group_commit"`. |
| active_memtable_bytes | `usize` | `number` | `int` | Estimated byte size of the active (writable) memtable. |
| immutable_memtable_bytes | `usize` | `number` | `int` | Estimated byte size of all sealed memtables waiting to flush. |
| immutable_memtable_count | `usize` | `number` | `int` | Count of sealed memtables waiting to flush. |
| pending_flush_count | `usize` | `number` | `int` | Flush operations currently in flight. |
| active_wal_generation_id | `u64` | `number` | `int` | Generation ID of the WAL file currently being written. |
| oldest_retained_wal_generation_id | `u64` | `number` | `int` | Oldest WAL generation kept on disk (needed for crash recovery). |

---

## Configuration

### DbOptions

Options passed to [`open()`](#open). All fields are optional with sensible defaults.

| Option | Rust type | Node.js key | Python kwarg | Default | Description |
|--------|-----------|-------------|--------------|---------|-------------|
| create_if_missing | `bool` | `createIfMissing` | `create_if_missing` | `true` | Create the database directory if it doesn't exist. If `false` and the directory is missing, `open()` returns an error. |
| wal_sync_mode | `WalSyncMode` | `walSyncMode` | `wal_sync_mode` | `GroupCommit` | Controls WAL durability. See [WalSyncMode](#walsyncmode). |
| group_commit_interval_ms | — (part of enum) | `groupCommitIntervalMs` | `group_commit_interval_ms` | `50` | Milliseconds between group-commit fsyncs. Only applies when `wal_sync_mode` is `group_commit`. |
| memtable_flush_threshold | `usize` | `memtableFlushThreshold` | `memtable_flush_threshold` | `134217728` (128 MB) | When the active memtable exceeds this size in bytes, it is sealed and queued for flush to a segment. |
| memtable_hard_cap_bytes | `usize` | `memtableHardCapBytes` | `memtable_hard_cap_bytes` | `536870912` (512 MB) | Writes block when the active memtable exceeds this size and the flush queue is full. Prevents unbounded memory growth under heavy write load. Set to `0` to disable. |
| max_immutable_memtables | `usize` | `maxImmutableMemtables` | `max_immutable_memtables` | `4` | Maximum number of sealed memtables allowed before the flush thread must drain one. Controls memory usage under write bursts. |
| edge_uniqueness | `bool` | `edgeUniqueness` | `edge_uniqueness` | `false` | When `true`, `upsert_edge` enforces at most one edge per `(from, to, label)` triple. An upsert with the same triple updates the existing edge. When `false`, every `upsert_edge` call creates a new edge. |
| compact_after_n_flushes | `u32` | `compactAfterNFlushes` | `compact_after_n_flushes` | `4` | Trigger background compaction after this many flushes. Set to `0` to disable auto-compaction. |
| dense_vector | `Option<DenseVectorConfig>` | `denseVector` | See below | `None` | Enable dense vector search. See [DenseVectorConfig](#densevectorconfig). In Python, use separate kwargs: `dense_vector_dimension` and `dense_vector_metric`. |

### WalSyncMode

Controls the trade-off between durability and write throughput.

| Mode | Rust | Node.js | Python | Behavior |
|------|------|---------|--------|----------|
| Immediate | `WalSyncMode::Immediate` | `"immediate"` | `"immediate"` | Every write triggers an `fsync`. Maximum crash safety. Data is durable before the write call returns. Lower throughput (~4ms per write on typical SSDs). |
| GroupCommit | `WalSyncMode::GroupCommit { .. }` | `"group-commit"` | `"group_commit"` | Writes are buffered and fsynced on a timer or when the buffer fills. Higher throughput (batched fsync amortizes the cost across many writes). A crash can lose at most one group-commit interval of writes. |

Current Node.js connector parsing treats unknown `walSyncMode` strings as group commit. Python validates `wal_sync_mode` and rejects unknown strings.

**GroupCommit parameters** (Node.js/Python expose these as top-level options):

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| interval_ms | `u32` | `50` | Maximum time between fsyncs. |
| soft_trigger_bytes | `usize` | `2097152` (2 MB) | Trigger an fsync when buffered bytes reach this threshold, even before the interval fires. |
| hard_cap_bytes | `usize` | `16777216` (16 MB) | Maximum WAL buffer size. Writes block if the buffer reaches this limit before the background syncer drains it. |

### DenseVectorConfig

Configures the HNSW index for dense vector search. Set once at database creation; cannot be changed later.

| Parameter | Rust | Node.js | Python | Default | Description |
|-----------|------|---------|--------|---------|-------------|
| dimension | `u32` | `dimension: number` | `dense_vector_dimension: int` | — (required if enabling vectors) | Dimensionality of dense vectors. Every node's `dense_vector` must have exactly this many elements. |
| metric | `DenseMetric` | `metric: string` | `dense_vector_metric: str` | `Cosine` | Distance metric for similarity. Rust uses enum variants. Node.js and Python use lower-case strings. |

**DenseMetric values:**

| Metric | Rust | Node.js / Python | Score semantics |
|--------|------|------------------|-----------------|
| Cosine | `DenseMetric::Cosine` | `"cosine"` | Higher = more similar (range: -1 to 1). |
| Euclidean | `DenseMetric::Euclidean` | `"euclidean"` | Lower distance is more similar. Results are returned as negative distance so higher scores remain "better." |
| Dot product | `DenseMetric::DotProduct` | `"dot_product"` | Higher = more similar. |

Current Node.js and Python connector parsers fall back to cosine for unknown metric strings.

**HNSW parameters** (Node.js/Python use defaults):

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| m | `usize` | `16` | Maximum number of bi-directional links per node per layer. Higher values improve recall at the cost of memory and build time. |
| ef_construction | `usize` | `200` | Size of the dynamic candidate list during index construction. Higher values improve recall at the cost of slower inserts. |

---

## Data Model

### Node Records

A public, hydrated node record returned by read operations.

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| id | `u64` | `number` | `int` | Unique, auto-assigned node ID. Monotonically increasing. |
| labels | `Vec<String>` | `string[]` | `list[str]` | Complete node label set. |
| key | `String` | `string` | `str` | Unique key within the node's label identity. Do not repeat the label in the key unless it is part of an external source ID. |
| props | `BTreeMap<String, PropValue>` | `Record<string, any>` | `dict[str, Any]` | User-defined properties. See [PropValue](#propvalue) for supported types. Lazily deserialized from MessagePack on first access. |
| weight | `f32` | `number` | `float` | Numeric weight. Default `1.0`. Used by pruning policies and scoring algorithms. |
| created_at | `i64` | `number` | `int` | Timestamp (ms) when the node was first created. |
| updated_at | `i64` | `number` | `int` | Timestamp (ms) of the most recent upsert. |
| dense_vector / denseVector | `Option<DenseVector>` | `number[] \| null` | `list[float] \| None` | Dense vector stored on the node. |
| sparse_vector / sparseVector | `Option<SparseVector>` | `SparseEntry[] \| null` | `list[tuple[int, float]] \| None` | Sparse vector stored on the node. |

Rust returns `NodeView`; Node.js returns `NodeView`; Python returns `NodeView`.

### Edge Records

A public, hydrated edge record returned by read operations.

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| id | `u64` | `number` | `int` | Unique, auto-assigned edge ID. |
| from / from_id | `u64` | `from: number` | `from_id: int` | Source node ID. |
| to / to_id | `u64` | `to: number` | `to_id: int` | Destination node ID. |
| label | `String` | `label: string` | `label: str` | Public edge label. |
| props | `BTreeMap<String, PropValue>` | `Record<string, any>` | `dict[str, Any]` | User-defined properties. |
| weight | `f32` | `number` | `float` | Edge weight. Default `1.0`. |
| valid_from | `i64` | `number` | `int` | Start of the edge's validity window (ms). If omitted when writing, OverGraph uses the edge's `created_at` timestamp. |
| valid_to | `i64` | `number` | `int` | End of the edge's validity window (ms). If omitted when writing, OverGraph uses `i64::MAX` / no expiration. |
| created_at | `i64` | `number` | `int` | Creation timestamp (ms). |
| updated_at | `i64` | `number` | `int` | Last update timestamp (ms). |

Rust returns `EdgeView`; Node.js returns `EdgeView`; Python returns `EdgeView`.

### PropValue

Property values are strongly typed in the Rust core. Connector inputs use their host-language conversion rules and do not expose every Rust variant as a distinct writable type.

| Type | Rust | Node.js | Python | Notes |
|------|------|---------|--------|-------|
| Null | `PropValue::Null` | `null` | `None` | |
| Boolean | `PropValue::Bool(bool)` | `boolean` | `bool` | |
| Integer | `PropValue::Int(i64)` | `number` | `int` | Node.js and normal Python integer inputs write signed integers. |
| Unsigned | `PropValue::UInt(u64)` | Readable as `number` | Readable as `int` | Rust can construct this directly. Connector property inputs do not provide a separate unsigned marker. |
| Float | `PropValue::Float(f64)` | `number` | `float` | 64-bit IEEE 754. |
| String | `PropValue::String(String)` | `string` | `str` | UTF-8. |
| Bytes | `PropValue::Bytes(Vec<u8>)` | Readable as JSON array | `bytes` | Python can write `bytes`. Node.js property input is JSON-like and does not currently convert `Buffer` to `PropValue::Bytes`. |
| Array | `PropValue::Array(Vec<PropValue>)` | `any[]` | `list` | Heterogeneous array. |
| Map | `PropValue::Map(BTreeMap<String, PropValue>)` | `object` | `dict` | Nested properties. |

Properties are encoded with [MessagePack](https://msgpack.org) internally and converted lazily when accessed from Node.js or Python.

Connector property conversion is intentionally host-language shaped. Node.js writes JSON-like values (`null`, booleans, numbers, strings, arrays, and objects); it does not currently use `Buffer` as a bytes marker or expose a separate unsigned-integer marker. Python writes the same common values plus `bytes`; normal Python `int` inputs write signed integers. Rust callers can construct every `PropValue` variant directly.

Property storage keeps these variants intact. Predicate semantics are numeric-aware only for finite scalar numbers: signed integers, unsigned integers, and finite floats compare by exact numeric value for equality and range filters. Strings, bytes, booleans, nulls, arrays, maps, and non-finite floats keep exact non-numeric equality behavior and are excluded from numeric range indexes.

### IntoNodeLabels (Rust only)

Rust node-label APIs accept `impl IntoNodeLabels` for single-label and multi-label calls. Accepted input forms are `&str`, `String`, `&String`, `&[&str]`, `&[String]`, `Vec<String>`, `&[&str; N]`, and `&[String; N]`.

### Direction

Controls edge traversal direction. Used across traversal and graph analytics APIs.

| Value | Rust | Node.js | Python | Meaning |
|-------|------|---------|--------|---------|
| Outgoing | `Direction::Outgoing` | `"outgoing"` | `"outgoing"` | Follow edges in the `from → to` direction. |
| Incoming | `Direction::Incoming` | `"incoming"` | `"incoming"` | Follow edges in the `to → from` direction. |
| Both | `Direction::Both` | `"both"` | `"both"` | Follow edges in both directions (treat graph as undirected). |

### NodeLabelFilter / LabelMatchMode

Use `NodeLabelFilter` when callers need explicit `Any` or `All` semantics over node labels.

```rust
let any_user_or_admin = NodeLabelFilter {
    labels: vec!["User".into(), "Admin".into()],
    mode: LabelMatchMode::Any,
};

let both_user_and_admin = NodeLabelFilter {
    labels: vec!["User".into(), "Admin".into()],
    mode: LabelMatchMode::All,
};
```

```python
any_user_or_admin = {"labels": ["User", "Admin"], "mode": "any"}
both_user_and_admin = {"labels": ["User", "Admin"], "mode": "all"}
```

```javascript
const anyUserOrAdmin = { labels: ['User', 'Admin'], mode: 'any' };
const bothUserAndAdmin = { labels: ['User', 'Admin'], mode: 'all' };
```

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| labels | `Vec<String>` | `labels: string[]` | `"labels": list[str]` | Public node labels to match. Must be non-empty and contain no duplicates. |
| mode | `LabelMatchMode` | `mode: "any" \| "all"` | `"mode": "any" \| "all"` | `Any`/`"any"` matches nodes with at least one listed label. `All`/`"all"` matches nodes with every listed label. |

---

## Catalog APIs

Catalog APIs explicitly manage or inspect the node-label and edge-label token catalog. Ordinary graph APIs accept and return names; catalog diagnostics are the only public surface that exposes numeric token IDs.

### ensure_node_label / ensure_edge_label

Ensure a catalog token exists for a public node label or edge label and return its diagnostic token ID.

```rust
let user_label_id = db.ensure_node_label("User")?;
let created_label_id = db.ensure_edge_label("CREATED")?;
```

```javascript
const userLabelId = db.ensureNodeLabel('User');
const createdLabelId = db.ensureEdgeLabel('CREATED');
```

```python
user_label_id = db.ensure_node_label("User")
created_label_id = db.ensure_edge_label("CREATED")
```

These methods are optional for normal writes: `upsert_node`, `upsert_edge`, batch writes, graph patch, and write transactions auto-create missing names durably. Use explicit ensures when you want catalog IDs for diagnostics or want to prepare names before writes.

### get_node_label_id / get_edge_label_id

Read-only lookup from public name to diagnostic token ID.

```rust
let id = db.get_node_label_id("User")?;
let edge_id = db.get_edge_label_id("CREATED")?;
```

```javascript
const id = db.getNodeLabelId('User');
const edgeId = db.getEdgeLabelId('CREATED');
```

```python
id = db.get_node_label_id("User")
edge_id = db.get_edge_label_id("CREATED")
```

Returns `None`/`null` when the name is unknown.

### get_node_label / get_edge_label

Diagnostic reverse lookup from token ID to public name.

```rust
let label = db.get_node_label(label_id)?;
let edge_label = db.get_edge_label(label_id)?;
```

```javascript
const label = db.getNodeLabel(labelId);
const edgeLabel = db.getEdgeLabel(labelId);
```

```python
label = db.get_node_label(label_id)
edge_label = db.get_edge_label(label_id)
```

The node and edge `label_id` / `labelId` arguments are catalog token IDs, not normal graph API inputs.

### list_node_labels / list_edge_labels

List published catalog entries.

```rust
let labels = db.list_node_labels()?;
let edge_labels = db.list_edge_labels()?;
```

```javascript
const labels = db.listNodeLabels();
const edgeLabels = db.listEdgeLabels();
```

```python
labels = db.list_node_labels()
edge_labels = db.list_edge_labels()
```

| Entry | Rust fields | Node.js fields | Python fields |
|-------|-------------|----------------|---------------|
| Node label | `label`, `label_id` | `label`, `labelId` | `label`, `label_id` |
| Edge label | `label`, `label_id` | `label`, `labelId` | `label`, `label_id` |

`label_id` and `labelId` in these entries are diagnostic catalog metadata. Do not use them as input to ordinary node, edge, query, traversal, or vector APIs.

---

## Node Operations

### upsert_node

Creates a new node or updates an existing one. If the key already resolves to the same node through any supplied label, the node is updated in place; if the same key resolves to different nodes across supplied labels, the write is rejected as a conflict.

**Rust**
```rust
// Also accepts multiple labels: &["User", "Admin"]
let id = db.upsert_node("User", "alice", UpsertNodeOptions {
    props: BTreeMap::from([("role".into(), PropValue::String("admin".into()))]),
    weight: 1.0,
    ..Default::default()
})?;
```

**Node.js**
```javascript
// Also accepts multiple labels: ['User', 'Admin']
const id = db.upsertNode('User', 'alice', {
  props: { role: 'admin' },
  weight: 1.0,
});
```

**Python**
```python
# Also accepts multiple labels: ["User", "Admin"]
id = db.upsert_node("User", "alice", props={"role": "admin"}, weight=1.0)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| labels | `impl IntoNodeLabels` | `string \| string[]` | `str \| list[str]` | Yes | — | One or more public node labels. |
| key | `&str` | `string` | `str` | Yes | — | Unique key scoped by node labels. If the supplied label set and key resolve to an existing node, it is updated. |
| props | `BTreeMap<String, PropValue>` | `Record<string, any>` | `dict[str, Any]` | No | `{}` | Arbitrary key-value properties. On update, the entire props map is replaced (not merged). |
| weight | `f32` | `number` | `float` | No | `1.0` | Numeric weight. Used by pruning policies (`max_weight`) and scoring algorithms. |
| dense_vector | `Option<Vec<f32>>` | `number[]` | `list[float]` | No | `None` | Dense vector for similarity search. Length must match the `dimension` configured at `open()`. Requires `dense_vector` to be enabled in DbOptions. |
| sparse_vector | `Option<Vec<(u32, f32)>>` | `SparseEntry[]` | `list[tuple[int, float]]` | No | `None` | Sparse vector as `(dimension_index, value)` pairs. Dimension indices must be unique. No upfront dimension configuration required. |

**SparseEntry** (Node.js):
```typescript
{ dimension: number, value: number }
```

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<u64, EngineError>` | `number` | `int` |

The node's ID. If the node was newly created, this is a fresh ID. If the node already existed, this is the existing ID.

#### Behavior

- **Upsert semantics**: On insert, allocates a new ID, sets `created_at` and `updated_at` to the current time. On update, keeps the original `created_at`, refreshes `updated_at`, and replaces labels, props, weight, and vectors.
- **Atomicity**: The write is applied to the WAL and memtable in a single operation.
- **Performance**: ~4ms per call in `Immediate` sync mode (dominated by `fsync`). Use [`batch_upsert_nodes`](#batch_upsert_nodes) for bulk operations where a single fsync is shared across the batch.

---

### get_node

Retrieves a node by its ID.

**Rust**
```rust
if let Some(node) = db.get_node(id)? {
    println!("labels={:?}, key={}", node.labels, node.key);
}
```

**Node.js**
```javascript
const node = db.getNode(id);
if (node) console.log(node.labels, node.key);
```

**Python**
```python
node = db.get_node(id)
if node:
    print(node.labels, node.key)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Node ID to retrieve. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Option<NodeView>, EngineError>` | `NodeView \| null` | `NodeView \| None` |

Returns `None`/`null` if the node does not exist or has been deleted.

#### Performance

~38ns per lookup (memtable hot path). Segment reads require I/O but are mmap-accelerated.

---

### get_node_by_key

Looks up a node by its `(label, key)` pair. Uses the label-scoped key lookup/index for fast lookup.

**Rust**
```rust
let node = db.get_node_by_key("User", "alice")?;
```

**Node.js**
```javascript
const node = db.getNodeByKey('User', 'alice');
```

**Python**
```python
node = db.get_node_by_key("User", "alice")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Node label. |
| key | `&str` | `string` | `str` | Yes | Node key within the label. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Option<NodeView>, EngineError>` | `NodeView \| null` | `NodeView \| None` |

Returns `None`/`null` if no node with that `(label, key)` exists.

---

### add_node_label / remove_node_label

Node label-set mutation helpers. These update a node's label set without changing its ID, key, properties, weight, or vectors.

```rust
let added = db.add_node_label(node_id, "Admin")?;
let removed = db.remove_node_label(node_id, "Trial")?;
```

```javascript
const added = db.addNodeLabel(nodeId, 'Admin');
const removed = db.removeNodeLabel(nodeId, 'Trial');
```

```python
added = db.add_node_label(node_id, "Admin")
removed = db.remove_node_label(node_id, "Trial")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Node ID to mutate. |
| label | `&str` | `string` | `str` | Yes | Public node label to add or remove. |

#### Returns

| Rust | Node.js | Python | Description |
|------|---------|--------|-------------|
| `Result<bool, EngineError>` | `boolean` | `bool` | `true` when the node's label set changed, `false` when the requested label was already present for add or absent for remove. |

#### Behavior

- Adding a label auto-creates the label token when needed.
- Adding a label fails if another node already owns the same `(label, key)` identity.
- Removing an unknown or absent label returns `false`.
- Removing the last remaining node label returns an error.

---

### delete_node

Deletes a node by ID. **Cascade-deletes all incident edges** (both incoming and outgoing) in the same WAL batch.

**Rust**
```rust
db.delete_node(id)?;
```

**Node.js**
```javascript
db.deleteNode(id);
```

**Python**
```python
db.delete_node(id)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Node ID to delete. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<(), EngineError>` | `void` | `None` |

#### Behavior

- Writes tombstones for the node and all its incident edges (memtable + segments scanned) in a single WAL batch for atomicity.
- Tombstoned records are excluded from all subsequent reads.
- Tombstones are physically removed during [compaction](#compact).
- Deleting a nonexistent or already-deleted node is a no-op (idempotent).

---

### batch_upsert_nodes

Upserts multiple nodes in a single batch with one WAL fsync. Significantly faster than calling `upsert_node` in a loop.

**Rust**
```rust
let inputs = vec![
    NodeInput {
        labels: vec!["User".into()],
        key: "alice".into(),
        props: BTreeMap::new(),
        weight: 1.0,
        dense_vector: None,
        sparse_vector: None,
    },
    NodeInput {
        labels: vec!["User".into(), "Admin".into()],
        key: "bob".into(),
        props: BTreeMap::from([("role".into(), PropValue::String("viewer".into()))]),
        weight: 0.8,
        dense_vector: None,
        sparse_vector: None,
    },
];
let ids = db.batch_upsert_nodes(inputs)?;
```

**Node.js**
```javascript
const ids = db.batchUpsertNodes([
  { labels: ['User'], key: 'alice', weight: 1.0 },
  { labels: ['User', 'Admin'], key: 'bob', weight: 0.8, props: { role: 'viewer' } },
]);
// ids is a Float64Array
```

**Python**
```python
ids = db.batch_upsert_nodes([
    {"labels": ["User"], "key": "alice", "weight": 1.0},
    {"labels": ["User", "Admin"], "key": "bob", "weight": 0.8, "props": {"role": "viewer"}},
])
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| nodes | `Vec<NodeInput>` | `NodeInput[]` | `list[dict]` | Yes | Array of node inputs. Each element has the same fields as [`upsert_node`](#upsert_node) parameters. |

**NodeInput fields:**

| Field | Rust | Node.js | Python dict key | Required | Default | Description |
|-------|------|---------|-----------------|----------|---------|-------------|
| labels | `labels: Vec<String>` | `labels: string \| string[]` | `"labels"` | Yes | — | One or more node labels. Node.js accepts a single string or a non-empty string array for dict-based node inputs. |
| key | `String` | `key: string` | `"key"` | Yes | — | Node key. |
| props | `BTreeMap<String, PropValue>` | `props: object` | `"props"` | No | `{}` | Properties. |
| weight | `f32` | `weight: number` | `"weight"` | No | `1.0` | Weight. |
| dense_vector | `Option<Vec<f32>>` | `denseVector: number[]` | `"dense_vector"` | No | `None` | Dense vector. |
| sparse_vector | `Option<Vec<(u32, f32)>>` | `sparseVector: SparseEntry[]` | `"sparse_vector"` | No | `None` | Sparse vector. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `list[int]` |

An array of node IDs in the same order as the input array.

#### Performance

A single fsync is performed for the entire batch. At 100 nodes, this achieves ~46μs per node amortized (vs. ~4ms per node for individual calls). Use this for all bulk operations.

---

### get_nodes

Batch-retrieves multiple nodes by ID. Uses a sorted merge-walk across all data sources, **much faster than calling `get_node` in a loop**.

**Rust**
```rust
let nodes = db.get_nodes(&[1, 2, 3])?;
// nodes[0] is Option<NodeView> for ID 1, etc.
```

**Node.js**
```javascript
const nodes = db.getNodes([1, 2, 3]);
// nodes[0] is NodeView | null for ID 1, etc.
```

**Python**
```python
nodes = db.get_nodes([1, 2, 3])
# nodes[0] is NodeView | None for ID 1, etc.
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| ids | `&[u64]` | `number[]` | `list[int]` | Yes | Array of node IDs to fetch. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<Option<NodeView>>, EngineError>` | `(NodeView \| null)[]` | `list[NodeView \| None]` |

An array the same length as the input, where each element is the node record or `None`/`null` if that ID doesn't exist.

---

### get_nodes_by_keys

Batch-retrieves multiple nodes by `(label, key)` pairs.

**Rust**
```rust
let nodes = db.get_nodes_by_keys(&[
    NodeKeyQuery { label: "User".into(), key: "alice".into() },
    NodeKeyQuery { label: "User".into(), key: "bob".into() },
])?;
```

**Node.js**
```javascript
const nodes = db.getNodesByKeys([
  { label: 'User', key: 'alice' },
  { label: 'User', key: 'bob' },
]);
```

**Python**
```python
nodes = db.get_nodes_by_keys([
    {"labels": ["User"], "key": "alice"},
    {"labels": ["User"], "key": "bob"},
])
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| keys | `&[NodeKeyQuery]` | `KeyQuery[]` | `list[dict]` | Yes | Array of key lookups. Python uses `{"labels": "User" \| ["User"], "key": ...}` and requires exactly one label because keys are label-scoped. |

**KeyQuery** (Node.js):
```typescript
{ label: string, key: string }
```

#### Returns

Same shape as [`get_nodes`](#get_nodes): an array of node records or `None`/`null` in input order.

---

## Edge Operations

### upsert_edge

Creates a new edge or updates an existing one. When `edge_uniqueness` is enabled, edges are identified by the `(from, to, label)` triple.

**Rust**
```rust
let id = db.upsert_edge(alice_id, project_id, "WORKS_ON", UpsertEdgeOptions {
    props: BTreeMap::from([("since".into(), PropValue::String("2024".into()))]),
    weight: 1.0,
    ..Default::default()
})?;
```

**Node.js**
```javascript
const id = db.upsertEdge(aliceId, projectId, 'WORKS_ON', {
  props: { since: '2024' },
  weight: 1.0,
});
```

**Python**
```python
id = db.upsert_edge(alice_id, project_id, "WORKS_ON",
    props={"since": "2024"}, weight=1.0)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| from | `u64` | `number` | `int` | Yes | — | Source node ID. |
| to | `u64` | `number` | `int` | Yes | — | Destination node ID. |
| label | `&str` | `string` | `str` | Yes | — | Public edge label such as `"WORKS_ON"` or `"KNOWS"`. |
| props | `BTreeMap<String, PropValue>` | `Record<string, any>` | `dict[str, Any]` | No | `{}` | Edge properties. Replaced entirely on update. |
| weight | `f32` | `number` | `float` | No | `1.0` | Edge weight. Used by shortest path (as cost), top-k scoring, and pruning. |
| valid_from | `Option<i64>` | `number` | `int` | No | edge `created_at` | Start of the edge's temporal validity window (ms). Edges with `valid_from > at_epoch` are excluded from temporal queries. |
| valid_to | `Option<i64>` | `number` | `int` | No | `i64::MAX` (no expiration) | End of the validity window (ms). Edges with `valid_to <= at_epoch` are excluded from temporal queries. See [`invalidate_edge`](#invalidate_edge). |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<u64, EngineError>` | `number` | `int` |

The edge ID.

#### Behavior

- **With `edge_uniqueness` enabled**: If an edge with the same `(from, to, label)` exists, it is updated and the existing ID is returned. Otherwise a new edge is created.
- **With `edge_uniqueness` disabled** (default): Every call creates a new edge (parallel edges are allowed).

---

### get_edge

Retrieves an edge by ID.

**Rust**
```rust
let edge = db.get_edge(edge_id)?;
```

**Node.js**
```javascript
const edge = db.getEdge(edgeId);
```

**Python**
```python
edge = db.get_edge(edge_id)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Edge ID. |

#### Returns

`EdgeView` / `EdgeView` / `EdgeView`, or `None`/`null` if the edge doesn't exist or has been deleted.

---

### get_edge_by_triple

Looks up an edge by its `(from, to, label)` triple. Only meaningful when `edge_uniqueness` is enabled.

**Rust**
```rust
let edge = db.get_edge_by_triple(alice_id, project_id, "WORKS_ON")?;
```

**Node.js**
```javascript
const edge = db.getEdgeByTriple(aliceId, projectId, 'WORKS_ON');
```

**Python**
```python
edge = db.get_edge_by_triple(alice_id, project_id, "WORKS_ON")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| from | `u64` | `number` | `int` | Yes | Source node ID. |
| to | `u64` | `number` | `int` | Yes | Destination node ID. |
| label | `&str` | `string` | `str` | Yes | Edge label. |

#### Returns

`EdgeView` / `EdgeView` / `EdgeView`, or `None`/`null`.

---

### delete_edge

Deletes an edge by ID.

**Rust**
```rust
db.delete_edge(edge_id)?;
```

**Node.js**
```javascript
db.deleteEdge(edgeId);
```

**Python**
```python
db.delete_edge(edge_id)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Edge ID to delete. |

#### Behavior

- Writes a tombstone. Idempotent: deleting a nonexistent or already-deleted edge is a no-op.
- Tombstones are reclaimed during [compaction](#compact).

---

### invalidate_edge

Closes an edge's validity window by setting its `valid_to` timestamp. The edge remains in the database (not tombstoned) but is excluded from queries that use temporal filtering (`at_epoch`).

**Rust**
```rust
let updated = db.invalidate_edge(edge_id, now_ms)?;
```

**Node.js**
```javascript
const updated = db.invalidateEdge(edgeId, Date.now());
```

**Python**
```python
updated = db.invalidate_edge(edge_id, int(time.time() * 1000))
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| id | `u64` | `number` | `int` | Yes | Edge ID. |
| valid_to | `i64` | `number` | `int` | Yes | New end-of-validity timestamp (ms). The edge is considered expired for any `at_epoch >= valid_to`. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Option<EdgeView>, EngineError>` | `EdgeView \| null` | `EdgeView \| None` |

The updated edge record, or `None`/`null` if the edge doesn't exist.

#### Use Case

Temporal graphs: rather than hard-deleting edges, close their validity window. This preserves historical data while excluding expired edges from current queries:

```javascript
// Only returns edges valid at the given timestamp
const neighbors = db.neighbors(nodeId, { atEpoch: Date.now() });
```

---

### batch_upsert_edges

Upserts multiple edges in a single batch with one WAL fsync.

**Rust**
```rust
let inputs = vec![
    EdgeInput {
        from: 1,
        to: 2,
        label: "WORKS_ON".into(),
        props: BTreeMap::new(),
        weight: 1.0,
        valid_from: None,
        valid_to: None,
    },
    EdgeInput {
        from: 1,
        to: 3,
        label: "WORKS_ON".into(),
        props: BTreeMap::new(),
        weight: 0.5,
        valid_from: None,
        valid_to: None,
    },
];
let ids = db.batch_upsert_edges(inputs)?;
```

**Node.js**
```javascript
const ids = db.batchUpsertEdges([
  { from: 1, to: 2, label: 'WORKS_ON', weight: 1.0 },
  { from: 1, to: 3, label: 'WORKS_ON', weight: 0.5 },
]);
```

**Python**
```python
ids = db.batch_upsert_edges([
    {"from_id": 1, "to_id": 2, "label": "WORKS_ON", "weight": 1.0},
    {"from_id": 1, "to_id": 3, "label": "WORKS_ON", "weight": 0.5},
])
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| edges | `Vec<EdgeInput>` | `EdgeInput[]` | `list[dict]` | Yes | Array of edge inputs. |

**EdgeInput fields:**

| Field | Rust | Node.js | Python dict key | Required | Default | Description |
|-------|------|---------|-----------------|----------|---------|-------------|
| from | `u64` | `from: number` | `"from_id"` | Yes | — | Source node ID. |
| to | `u64` | `to: number` | `"to_id"` | Yes | — | Destination node ID. |
| label | `String` | `label: string` | `"label"` | Yes | — | Edge label. |
| props | `BTreeMap<String, PropValue>` | `props: object` | `"props"` | No | `{}` | Properties. |
| weight | `f32` | `weight: number` | `"weight"` | No | `1.0` | Weight. |
| valid_from | `Option<i64>` | `validFrom: number` | `"valid_from"` | No | edge `created_at` | Validity start. |
| valid_to | `Option<i64>` | `validTo: number` | `"valid_to"` | No | `i64::MAX` | Validity end. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `list[int]` |

Edge IDs in input order.

---

### get_edges

Batch-retrieves multiple edges by ID using a sorted merge-walk.

**Rust**
```rust
let edges = db.get_edges(&[10, 20, 30])?;
```

**Node.js**
```javascript
const edges = db.getEdges([10, 20, 30]);
```

**Python**
```python
edges = db.get_edges([10, 20, 30])
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| ids | `&[u64]` | `number[]` | `list[int]` | Yes | Edge IDs to fetch. |

#### Returns

Array of edge records or `None`/`null` in input order.

---

## Atomic Operations

### graph_patch

Applies multiple operations atomically in a single WAL batch: node upserts, edge upserts, edge invalidations, and deletes.

**Rust**
```rust
let result = db.graph_patch(GraphPatch {
    upsert_nodes: vec![NodeInput {
        labels: vec!["User".into(), "Admin".into()],
        key: "carol".into(),
        props: BTreeMap::new(),
        weight: 1.0,
        dense_vector: None,
        sparse_vector: None,
    }],
    upsert_edges: vec![EdgeInput {
        from: 1,
        to: 2,
        label: "WORKS_ON".into(),
        props: BTreeMap::new(),
        weight: 1.0,
        valid_from: None,
        valid_to: None,
    }],
    invalidate_edges: vec![(edge_id, now_ms)],
    delete_node_ids: vec![old_node_id],
    delete_edge_ids: vec![old_edge_id],
})?;
```

**Node.js**
```javascript
const result = db.graphPatch({
  upsertNodes: [{ labels: ['User'], key: 'carol' }],
  upsertEdges: [{ from: 1, to: 2, label: 'WORKS_ON' }],
  invalidateEdges: [{ edgeId: 5, validTo: Date.now() }],
  deleteNodeIds: [oldNodeId],
  deleteEdgeIds: [oldEdgeId],
});
```

**Python**
```python
result = db.graph_patch({
    "upsert_nodes": [{"labels": ["User"], "key": "carol"}],
    "upsert_edges": [{"from_id": 1, "to_id": 2, "label": "WORKS_ON"}],
    "invalidate_edges": [{"edge_id": 5, "valid_to": int(time.time() * 1000)}],
    "delete_node_ids": [old_node_id],
    "delete_edge_ids": [old_edge_id],
})
```

#### Parameters

All fields in the patch object are optional. Omit any you don't need.

| Field | Rust | Node.js | Python dict key | Description |
|-------|------|---------|-----------------|-------------|
| upsert_nodes | `Vec<NodeInput>` | `upsertNodes: NodeInput[]` | `"upsert_nodes"` | Nodes to create or update. Same format as [`batch_upsert_nodes`](#batch_upsert_nodes). |
| upsert_edges | `Vec<EdgeInput>` | `upsertEdges: EdgeInput[]` | `"upsert_edges"` | Edges to create or update. Same format as [`batch_upsert_edges`](#batch_upsert_edges). |
| invalidate_edges | `Vec<(u64, i64)>` | `invalidateEdges: {edgeId, validTo}[]` | `"invalidate_edges"` | Edges to invalidate. Each entry specifies an edge ID and a `valid_to` timestamp. |
| delete_node_ids | `Vec<u64>` | `deleteNodeIds: number[]` | `"delete_node_ids"` | Node IDs to delete. **Cascade**: incident edges are automatically deleted. |
| delete_edge_ids | `Vec<u64>` | `deleteEdgeIds: number[]` | `"delete_edge_ids"` | Edge IDs to delete. |

#### Execution Order

Operations within a patch are applied in a deterministic order:

1. **Node upserts** - create/update nodes (so new nodes can be referenced by edge upserts)
2. **Edge upserts** - create/update edges
3. **Edge invalidations** - set `valid_to` on edges
4. **Edge deletes** - tombstone edges
5. **Node deletes** - tombstone nodes and cascade-delete all incident edges

#### Returns: PatchResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| node_ids | `Vec<u64>` | `Float64Array` | `list[int]` | IDs of all upserted nodes, in input order. |
| edge_ids | `Vec<u64>` | `Float64Array` | `list[int]` | IDs of all upserted edges, in input order. |

---

### write transactions

Explicit write transactions stage ordered graph mutations locally, support bounded read-own-writes point lookups, and commit as one atomic WAL batch. Conflict detection is optimistic and write-target based: if a staged target changed after the transaction began, `commit` fails with a transaction conflict and no partial state is published.

Use transactions when later operations need local aliases from earlier staged upserts, or when a caller needs rollback before durability. Use `graph_patch` for simpler grouped atomic batches that do not need ordered local references.

Transaction reads are intentionally bounded. A transaction can read committed state from its begin snapshot plus its own staged writes for point/dedup lookups only: `get_node`, `get_edge`, `get_node_by_key`, and `get_edge_by_triple`. Traversal, vector search, property queries, pagination, export, analytics, prune-policy mutation, and maintenance APIs are not exposed on `WriteTxn`.

**Rust**
```rust
let mut txn = db.begin_write_txn()?;
let alice = txn.upsert_node_as("alice", &["User", "Admin"], "alice", UpsertNodeOptions::default())?;
let bob = txn.upsert_node_as("bob", "User", "bob", UpsertNodeOptions::default())?;
txn.upsert_edge_as("knows", alice.clone(), bob.clone(), "KNOWS", UpsertEdgeOptions::default())?;
assert!(txn.add_node_label(alice.clone(), "Manager")?);
assert!(txn.remove_node_label(alice.clone(), "Admin")?);
let staged = txn.get_node_by_key("User", "alice")?;
if let Some(view) = &staged {
    println!("staged labels: {:?}", view.labels);
}
let result = txn.commit()?;
```

**Node.js**
```javascript
const txn = db.beginWriteTxn();
txn.stage([
  { op: 'upsertNode', alias: 'alice', labels: ['User', 'Admin'], key: 'alice' },
  { op: 'upsertNode', alias: 'bob', labels: ['User'], key: 'bob' },
  { op: 'upsertEdge', alias: 'knows', from: { local: 'alice' }, to: { local: 'bob' }, label: 'KNOWS' },
]);
txn.addNodeLabel({ local: 'bob' }, 'Trial');
const staged = txn.getNode({ local: 'alice' });
const result = txn.commit();
```

**Python**
```python
txn = db.begin_write_txn()
txn.stage([
    {"op": "upsert_node", "alias": "alice", "labels": ["User", "Admin"], "key": "alice"},
    {"op": "upsert_node", "alias": "bob", "labels": ["User"], "key": "bob"},
    {"op": "upsert_edge", "alias": "knows", "from": {"local": "alice"}, "to": {"local": "bob"}, "label": "KNOWS"},
])
txn.add_node_label({"local": "bob"}, "Trial")
staged = txn.get_node({"local": "alice"})
result = txn.commit()
```

#### Transaction Surface

| Operation | Rust | Node.js | Python |
|-----------|------|---------|--------|
| Begin | `begin_write_txn()` | `beginWriteTxn()` | `begin_write_txn()` |
| Stage node | `upsert_node`, `upsert_node_as` | `upsertNode`, `upsertNodeAs` | `upsert_node`, `upsert_node_as` |
| Mutate node labels | `add_node_label`, `remove_node_label` | `addNodeLabel`, `removeNodeLabel` | `add_node_label`, `remove_node_label` |
| Stage edge | `upsert_edge`, `upsert_edge_as` | `upsertEdge`, `upsertEdgeAs` | `upsert_edge`, `upsert_edge_as` |
| Bulk ordered stage | `stage_intents(Vec<TxnIntent>)` | `stage(operations)` | `stage(operations)` |
| Reads | `get_node`, `get_edge`, `get_node_by_key`, `get_edge_by_triple` | same camelCase names | same snake_case names |
| Finish | `commit`, `rollback` | `commit`, `rollback` | `commit`, `rollback` |

#### Rust Transaction DTOs

Rust exposes the transaction reference and intent objects directly:

| Object | Variants / fields | Description |
|--------|-------------------|-------------|
| `TxnNodeRef` | `Id(u64)`, `Key { label, key }`, `Local(TxnLocalRef)` | Node target for transaction writes and bounded transaction reads. `Key` is single-label scoped. |
| `TxnEdgeRef` | `Id(u64)`, `Triple { from, to, label }`, `Local(TxnLocalRef)` | Edge target by ID, by endpoint refs plus edge label, or by local transaction ref. |
| `TxnIntent::UpsertNode` | `alias`, `labels`, `key`, `options` | Ordered staged node upsert. `labels` is the complete node-label set for the write. |
| `TxnIntent::UpsertEdge` | `alias`, `from`, `to`, `label`, `options` | Ordered staged edge upsert using transaction node refs. |
| `TxnIntent::DeleteNode` | `target` | Ordered staged node delete. |
| `TxnIntent::DeleteEdge` | `target` | Ordered staged edge delete. |
| `TxnIntent::InvalidateEdge` | `target`, `valid_to` | Ordered staged temporal edge invalidation. |

#### Builder Methods

| Method | Required inputs | Optional inputs | Returns |
|--------|-----------------|-----------------|---------|
| `upsert_node` / `upsertNode` | `labels`, `key` | node upsert options: `props`, `weight`, `dense_vector` / `denseVector`, `sparse_vector` / `sparseVector` | node ref addressable by key |
| `upsert_node_as` / `upsertNodeAs` | `alias`, `labels`, `key` | node upsert options | local node ref `{ local: alias }` |
| `add_node_label` / `remove_node_label` | node ref, `label` | — | `bool` changed flag |
| `upsert_edge` / `upsertEdge` | `from`, `to`, `label` | edge upsert options: `props`, `weight`, `valid_from` / `validFrom`, `valid_to` / `validTo` | edge ref addressable by triple |
| `upsert_edge_as` / `upsertEdgeAs` | `alias`, `from`, `to`, `label` | edge upsert options | local edge ref `{ local: alias }` |
| `delete_node` / `deleteNode` | node ref | — | `void` / `None` |
| `delete_edge` / `deleteEdge` | edge ref | — | `void` / `None` |
| `invalidate_edge` / `invalidateEdge` | edge ref, `valid_to` / `validTo` | — | `void` / `None` |
| `stage` / `stage_intents` | ordered operation payloads | — | `void` / `None` |

#### Ordered Operation Payloads

Node.js uses camelCase fields and op names: `upsertNode`, `upsertEdge`, `deleteNode`, `deleteEdge`, `invalidateEdge`.

Python uses snake_case fields and op names: `upsert_node`, `upsert_edge`, `delete_node`, `delete_edge`, `invalidate_edge`.

References are one of:

| Ref kind | Node.js | Python |
|----------|---------|--------|
| Node by ID | `{ id }` | `{"id": id}` |
| Node by key | `{ labels, key }` | `{"labels": label_or_single_label_list, "key": key}` |
| Node local alias | `{ local }` | `{"local": local}` |
| Edge by ID | `{ id }` | `{"id": id}` |
| Edge by triple | `{ from, to, label }` | `{"from": from, "to": to, "label": label}` |
| Edge local alias | `{ local }` | `{"local": local}` |

Node-by-key transaction refs use `labels` and `key` but are still single-label scoped:
`labels` may be a string or a one-item list/array.

Aliases are optional, process-local, and never persisted. When present, aliases must be unique within the transaction across node aliases and unique across edge aliases.

#### Transaction Read Views

`get_node` and `get_node_by_key` on a transaction return a transaction node view:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| id | `Option<u64>` | `id?: number` | `"id": int \| None` | Committed node ID when already known; `None`/omitted for staged creates that allocate an ID at commit. |
| local | `Option<TxnLocalRef>` | `local?: string` | `"local": str \| None` | Local alias for aliased staged records. Internal unaliased slots are not exposed as strings. |
| labels | `Vec<String>` | `labels: string[]` | `"labels": list[str]` | Complete node label set visible inside the transaction. |
| key | `String` | `key` | `"key"` | Node key. |
| props | `BTreeMap<String, PropValue>` | `props` | `"props"` | Node properties visible inside the transaction. |
| created_at / updated_at | `Option<i64>` | `createdAt?` / `updatedAt?` | `"created_at"` / `"updated_at"` | Present for committed records; absent/`None` for staged creates before commit. |
| weight | `f32` | `weight` | `"weight"` | Node weight. |
| dense_vector / sparse_vector | `Option<DenseVector>` / `Option<SparseVector>` | `denseVector?` / `sparseVector?` | `"dense_vector"` / `"sparse_vector"` | Staged or committed vectors when present. |

`get_edge` and `get_edge_by_triple` return a transaction edge view:

| Field | Node.js | Python | Description |
|-------|---------|--------|-------------|
| id | `id?: number` | `"id": int \| None` | Committed edge ID when already known; `None`/omitted for staged creates that allocate an ID at commit. |
| local | `local?: string` | `"local": str \| None` | Local alias for aliased staged records. |
| from / to | `from` / `to` | `"from"` / `"to"` | Endpoint refs visible inside the transaction. |
| label | `label` | `"label"` | Edge label. |
| props | `props` | `"props"` | Edge properties visible inside the transaction. |
| created_at / updated_at | `createdAt?` / `updatedAt?` | `"created_at"` / `"updated_at"` | Present for committed records; absent/`None` for staged creates before commit. |
| weight | `weight` | `"weight"` | Edge weight. |
| valid_from / valid_to | `validFrom?` / `validTo?` | `"valid_from"` / `"valid_to"` | Temporal validity bounds when present. |

#### Commit Result

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| node IDs | `node_ids: Vec<u64>` | `nodeIds: Float64Array` | `node_ids: list[int]` | IDs returned by node upsert intents in input order. |
| edge IDs | `edge_ids: Vec<u64>` | `edgeIds: Float64Array` | `edge_ids: list[int]` | IDs returned by edge upsert intents in input order. |
| node aliases | `local_node_ids` | `nodeAliases` | `node_aliases` | Alias-to-node-ID map for aliased staged node upserts. |
| edge aliases | `local_edge_ids` | `edgeAliases` | `edge_aliases` | Alias-to-edge-ID map for aliased staged edge upserts. |

After `commit()` or `rollback()`, the transaction handle is closed. Further use fails with `TxnClosed` / `transaction is closed`.

#### Conflict Handling

`TxnConflict` means the transaction definitely did not commit: no WAL entry was appended and no partial state was published. The caller can retry by starting a new transaction, restaging the desired operations, re-reading any needed point records, and committing again. OverGraph does not automatically retry because conflict-safe retry policy depends on caller intent.

---

## Label and Edge-Label Queries

### nodes_by_labels

Returns all node IDs containing every supplied node label.

**Rust**
```rust
let ids: Vec<u64> = db.nodes_by_labels("User")?;
let admin_ids: Vec<u64> = db.nodes_by_labels(vec!["User".into(), "Admin".into()])?;
```

**Node.js**
```javascript
const ids = db.nodesByLabels('User'); // Float64Array
const adminIds = db.nodesByLabels(['User', 'Admin']);
```

**Python**
```python
ids = db.nodes_by_labels("User")  # IdArray (lazy)
ids_list = ids.to_list()      # materialize to list[int]
admin_ids = db.nodes_by_labels(["User", "Admin"])
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| labels | `impl IntoNodeLabels` | `string \| string[]` | `str \| list[str]` | Yes | Label or labels to match. Nodes must contain every supplied node label. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `IdArray` |

All matching node IDs. Filtered (excludes deleted/pruned nodes).

**Python `IdArray`**: A lazy wrapper that avoids copying IDs to Python memory until accessed. Supports `len()`, indexing (`arr[i]`), iteration, `in` operator, and `to_list()`.

#### Performance

Single-label input uses the direct per-label fast path. Multi-label input uses `All` semantics, drives from the best label posting, and metadata-verifies current label membership. Use [`query_node_ids`](#query_node_ids) with `NodeLabelFilter` when `Any` semantics are needed.

---

### edges_by_label

Returns all edge IDs of a given edge label.

**Rust**
```rust
let ids: Vec<u64> = db.edges_by_label("WORKS_ON")?;
```

**Node.js**
```javascript
const ids = db.edgesByLabel('WORKS_ON'); // Float64Array
```

**Python**
```python
ids = db.edges_by_label("WORKS_ON")  # IdArray (lazy)
ids_list = ids.to_list()             # materialize to list[int]
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Public edge label to match, such as `"WORKS_ON"` or `"KNOWS"`. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `IdArray` |

All matching live edge IDs. Tombstoned edges are excluded. Unknown edge labels return an empty result.

**Python `IdArray`**: A lazy wrapper that avoids copying IDs to Python memory until accessed. Supports `len()`, indexing (`arr[i]`), iteration, `in` operator, and `to_list()`.

#### Performance

Uses the edge-label posting index and does not hydrate edge records. Edges have exactly one public label, so this API accepts a single label string. Use [`query_edge_ids`](#query_edge_ids) when you need additional edge predicates.

---

### get_nodes_by_labels

Returns full node records for nodes containing every supplied node label.

```rust
let nodes: Vec<NodeView> = db.get_nodes_by_labels("User")?;
let admin_nodes: Vec<NodeView> =
    db.get_nodes_by_labels(vec!["User".into(), "Admin".into()])?;
```

```javascript
const nodes = db.getNodesByLabels('User'); // NodeView[]
const admins = db.getNodesByLabels(['User', 'Admin']);
```

```python
nodes = db.get_nodes_by_labels("User")  # list[NodeView]
admins = db.get_nodes_by_labels(["User", "Admin"])
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| labels | `impl IntoNodeLabels` / `string \| string[]` / `str \| list[str]` | Yes | Label or labels to match. Nodes must contain every supplied node label. |

#### Returns

Array of full node records. Includes all public fields (id, labels, key, props, weight, timestamps, vectors).

Multi-label input always uses `All` semantics. Use [`query_nodes`](#query_nodes) with `NodeLabelFilter` when `Any` semantics are needed.

---

### get_edges_by_label

Returns full edge records for all edges of a given edge label.

**Rust**
```rust
let edges: Vec<EdgeView> = db.get_edges_by_label("WORKS_ON")?;
```

**Node.js**
```javascript
const edges = db.getEdgesByLabel('WORKS_ON'); // EdgeView[]
```

**Python**
```python
edges = db.get_edges_by_label("WORKS_ON")  # list[EdgeView]
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Public edge label to match. |

#### Returns

Array of full edge records. Includes all public edge fields: id, endpoints (`from`/`to` in Rust and Node.js, `from_id`/`to_id` in Python), label, props, weight, timestamps, and validity window.

Unknown edge labels return an empty array. Tombstoned edges are excluded.

#### Performance

Uses the edge-label posting index to collect matching IDs, then batch-hydrates the matching records. Use [`edges_by_label`](#edges_by_label) when IDs are enough.

---

### count_nodes_by_labels

Returns the count of nodes containing every supplied node label.

```rust
let count: u64 = db.count_nodes_by_labels("User")?;
let admin_count: u64 =
    db.count_nodes_by_labels(vec!["User".into(), "Admin".into()])?;
```

```javascript
const count = db.countNodesByLabels('User');
```

```python
count = db.count_nodes_by_labels("User")
admin_count = db.count_nodes_by_labels(["User", "Admin"])
```

Count uses metadata-only verification and does not hydrate node records or allocate the final ID result vector. Multi-label input always uses `All` semantics. Use [`query_node_ids`](#query_node_ids) with `NodeLabelFilter` when `Any` semantics are needed.

---

### count_edges_by_label

Returns the count of live edges of a given edge label.

**Rust**
```rust
let count: u64 = db.count_edges_by_label("WORKS_ON")?;
```

**Node.js**
```javascript
const count = db.countEdgesByLabel('WORKS_ON');
```

**Python**
```python
count = db.count_edges_by_label("WORKS_ON")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Public edge label to count. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<u64, EngineError>` | `number` | `int` |

Unknown edge labels return `0`. Tombstoned edges are excluded.

#### Performance

Counts through the edge-label posting path without hydrating edge records.

---

## Property Index Management

Property indexes are optional declarations on node or edge properties. Public query methods stay the same whether or not you declare an index.

Lifecycle rules:
- `ensure_node_property_index` registers an equality or numeric range declaration and starts background build work when needed.
- `ensure_edge_property_index` does the same for edge properties, scoped by edge label.
- `list_node_property_indexes` exposes declaration kind, lifecycle state, and any last error from the published read snapshot, so `Ready` means new public reads can use the same ready catalog.
- `list_edge_property_indexes` exposes the same state for edge declarations.
- `find_nodes`, `find_nodes_paged`, `find_nodes_range`, and `find_nodes_range_paged` use declaration-backed execution only when a matching declaration is `Ready`.
- `query_edge_ids`, `query_edges`, and `query_graph_rows` may use ready edge-property declarations as candidate sources while still verifying final edge filters.
- If a declaration is absent, `Building`, `Failed`, or cannot be used for a specific lookup, OverGraph falls back to the same public query API for that call.

### ensure_node_property_index

Ensures an optional secondary index declaration for a node property.

**Rust**
```rust
let eq = db.ensure_node_property_index(
    "User",
    "role",
    SecondaryIndexKind::Equality,
)?;

let range = db.ensure_node_property_index(
    "User",
    "score",
    SecondaryIndexKind::Range,
)?;
```

**Node.js**
```javascript
const eq = db.ensureNodePropertyIndex('User', 'role', 'equality');

const range = db.ensureNodePropertyIndex('User', 'score', 'range');
```

**Python**
```python
eq = db.ensure_node_property_index("User", "role", "equality")

range_info = db.ensure_node_property_index(
    "User",
    "score",
    "range",
)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Restrict the declaration to this node label. |
| prop_key | `&str` | `string` | `str` | Yes | Property key to declare. |
| kind | `SecondaryIndexKind` | `string` | `str` | Yes | Equality declaration or domainless numeric range declaration. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<NodePropertyIndexInfo, EngineError>` | `NodePropertyIndexInfo` | `NodePropertyIndexInfo` |

The current declaration info.

#### Behavior

- Equality declarations use `SecondaryIndexKind::Equality` or `"equality"`. Finite scalar numeric equality is semantic across signed integers, unsigned integers, and finite floats; string equality and other non-numeric equality remain exact.
- Range declarations use `SecondaryIndexKind::Range` or `"range"`. Range indexes are domainless numeric indexes over finite scalar numeric values across signed integers, unsigned integers, and finite floats.
- Range indexes exclude non-finite floats, non-numeric values, arrays, and maps.
- Re-ensuring an existing declaration returns the existing declaration info.
- Re-ensuring a `Failed` declaration retries it by moving it back to `Building`.
- A `(label, prop_key)` pair has one range declaration shape; callers do not choose `int`, `uint`, or `float` variants.
- A declaration becoming `Ready` is what enables declaration-backed routing. Callers do not switch to a different query method.
- Ready equality and range index candidates are still verified against the latest visible records before results are returned.

---

### drop_node_property_index

Drops an optional node-property secondary index declaration.

**Rust**
```rust
let removed = db.drop_node_property_index(
    "User",
    "role",
    SecondaryIndexKind::Equality,
)?;
```

**Node.js**
```javascript
const removed = db.dropNodePropertyIndex('User', 'role', 'equality');
```

**Python**
```python
removed = db.drop_node_property_index("User", "role", "equality")
```

#### Parameters

Same parameters and kind values as [`ensure_node_property_index`](#ensure_node_property_index).

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<bool, EngineError>` | `boolean` | `bool` |

`true` if a declaration existed and was removed, `false` otherwise.

#### Behavior

- Dropping a declaration removes the optional declaration state and subsequent declaration-backed routing for that property.
- Property queries continue to work after a drop. They fall back to scan through the same public query APIs.

---

### list_node_property_indexes

Lists all optional node-property secondary index declarations.

**Rust**
```rust
let indexes = db.list_node_property_indexes()?;
```

**Node.js**
```javascript
const indexes = db.listNodePropertyIndexes();
```

**Python**
```python
indexes = db.list_node_property_indexes()
```

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Vec<NodePropertyIndexInfo>` | `Array<NodePropertyIndexInfo>` | `list[NodePropertyIndexInfo]` |

One entry per declaration.

---

### NodePropertyIndexInfo

User-facing declaration information returned by [`ensure_node_property_index`](#ensure_node_property_index) and [`list_node_property_indexes`](#list_node_property_indexes).

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| index_id | `u64` | `indexId: number` | `index_id: int` | Stable declaration ID. |
| label | `String` | `label: string` | `label: str` | Declared node label. |
| prop_key | `String` | `propKey: string` | `prop_key: str` | Declared property key. |
| kind | `SecondaryIndexKind` | `kind: string` | `kind: str` | `equality` or `range`. |
| state | `SecondaryIndexState` | `state: string` | `state: str` | `building`, `ready`, or `failed`. |
| last_error | `Option<String>` | `lastError?: string` | `last_error: str \| None` | Most recent build or validation failure, if any. |

State meanings:
- `building`: the declaration exists, but the declaration-backed path is not live yet.
- `ready`: the declaration-backed path has full live coverage and may be used by matching queries.
- `failed`: the declaration could not be built or validated. Matching queries fall back to scan until the declaration is retried or dropped.

---

### ensure_edge_property_index

Ensures an optional secondary index declaration for an edge property, scoped to one edge label.

**Rust**
```rust
let eq = db.ensure_edge_property_index(
    "WORKS_AT",
    "role",
    SecondaryIndexKind::Equality,
)?;

let range = db.ensure_edge_property_index(
    "WORKS_AT",
    "score",
    SecondaryIndexKind::Range,
)?;
```

**Node.js**
```javascript
const eq = db.ensureEdgePropertyIndex('WORKS_AT', 'role', 'equality');

const range = db.ensureEdgePropertyIndex('WORKS_AT', 'score', 'range');
```

**Python**
```python
eq = db.ensure_edge_property_index("WORKS_AT", "role", "equality")

range_info = db.ensure_edge_property_index(
    "WORKS_AT",
    "score",
    "range",
)
```

Parameters, kind values, and lifecycle states match [`ensure_node_property_index`](#ensure_node_property_index), except `label` is the edge label.

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<EdgePropertyIndexInfo, EngineError>` | `EdgePropertyIndexInfo` | `EdgePropertyIndexInfo` |

#### Behavior

- Edge property declarations are edge-label-scoped. A property filter without an edge label cannot use an edge-label-scoped edge-property declaration as a direct-query anchor.
- Ready edge declarations are candidate sources only. `query_edge_ids`, `query_edges`, and graph-row execution still verify edge metadata and edge property predicates before returning results.
- Direct `EdgeQuery` anchor legality is unchanged: edge property indexes improve planning inside legal direct edge queries, but do not make filter-only direct edge queries legal by themselves.
- Graph-row plans may choose a ready edge-property equality or range source as an edge anchor when it is cheaper than node-anchor expansion.

---

### drop_edge_property_index

Drops an optional edge-property secondary index declaration.

**Rust**
```rust
let removed = db.drop_edge_property_index(
    "WORKS_AT",
    "role",
    SecondaryIndexKind::Equality,
)?;
```

**Node.js**
```javascript
const removed = db.dropEdgePropertyIndex('WORKS_AT', 'role', 'equality');
```

**Python**
```python
removed = db.drop_edge_property_index("WORKS_AT", "role", "equality")
```

Same parameters and kind values as [`ensure_edge_property_index`](#ensure_edge_property_index). Returns `true` if a declaration existed and was removed, `false` otherwise.

---

### list_edge_property_indexes

Lists all optional edge-property secondary index declarations.

**Rust**
```rust
let indexes = db.list_edge_property_indexes()?;
```

**Node.js**
```javascript
const indexes = db.listEdgePropertyIndexes();
```

**Python**
```python
indexes = db.list_edge_property_indexes()
```

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<EdgePropertyIndexInfo>, EngineError>` | `Array<EdgePropertyIndexInfo>` | `list[EdgePropertyIndexInfo]` |

One entry per edge declaration.

---

### EdgePropertyIndexInfo

User-facing declaration information returned by [`ensure_edge_property_index`](#ensure_edge_property_index) and [`list_edge_property_indexes`](#list_edge_property_indexes).

Fields match [`NodePropertyIndexInfo`](#nodepropertyindexinfo), with the edge-label scope exposed as `label`: `index_id` / `indexId`, `label`, `prop_key` / `propKey`, `kind`, `state`, and `last_error` / `lastError`.

---

### PropertyRangeBound

Bound object for [`find_nodes_range`](#find_nodes_range) and [`find_nodes_range_paged`](#find_nodes_range_paged).

**Rust**
```rust
let lower = PropertyRangeBound::Included(PropValue::Int(10));
let upper = PropertyRangeBound::Excluded(PropValue::Float(20.0));
```

**Node.js**
```javascript
const lower = { value: 10, inclusive: true, domain: 'int' };
const upper = { value: 20, inclusive: false, domain: 'float' };
```

**Python**
```python
lower = PropertyRangeBound(10, domain="int")
upper = PropertyRangeBound(20.0, inclusive=False, domain="float")
```

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| value | `PropValue` | `value: number` | `value: int \| float` | Numeric bound value. |
| inclusive | Encoded by enum variant | `inclusive?: boolean` | `inclusive: bool` | Inclusive when `true`, exclusive when `false`. |
| domain | Inferred from `PropValue` | `domain: string` | `domain: str` | Node.js and Python value-conversion hint. One of `int`, `uint`, or `float`. |

Notes:
- Range bounds must be finite scalar numeric values. Non-finite floats, non-numeric values, arrays, and maps are invalid bounds.
- Node.js and Python `domain` fields construct the exact host value variant for a bound or cursor. They are not range index declaration domains.
- Bounds may mix `int`, `uint`, and `float` conversion hints. OverGraph compares finite numeric values by exact numeric value.
- Empty finite numeric intervals return empty results.

---

### PropertyRangeCursor

Cursor object for [`find_nodes_range_paged`](#find_nodes_range_paged). The cursor key is `(value, node_id)`.

**Rust**
```rust
PropertyRangeCursor {
    value: PropValue::Int(20),
    node_id: 42,
}
```

**Node.js**
```javascript
{ value: 20, nodeId: 42, domain: 'int' }
```

**Python**
```python
PropertyRangeCursor(20, 42, domain="int")
```

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| value | `PropValue` | `value: number` | `value: int \| float` | Last value returned on the previous page. |
| node_id | `u64` | `nodeId: number` | `node_id: int` | Last node ID returned at that value. |
| domain | Inferred from `value` | `domain: string` | `domain: str` | Node.js and Python value-conversion hint for the cursor value. |

---

### PropertyRangePageRequest (Rust only)

Rust request object for [`find_nodes_range_paged`](#find_nodes_range_paged).

```rust
PropertyRangePageRequest {
    limit: Some(100),
    after: None,
}
```

| Field | Rust | Description |
|-------|------|-------------|
| limit | `Option<usize>` | Maximum node IDs to return. `None` means no explicit page size. |
| after | `Option<PropertyRangeCursor>` | Cursor from the previous page. `None` starts at the lower bound. |

---

### PropertyRangePageResult

Result object returned by [`find_nodes_range_paged`](#find_nodes_range_paged).

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `Vec<u64>` | `Float64Array` | `IdArray` | Node IDs in range order for this page. |
| next_cursor | `Option<PropertyRangeCursor>` | `nextCursor?: PropertyRangeCursor` | `next_cursor: PropertyRangeCursor \| None` | Cursor for the next page. Omitted / `None` on the last page. |

---

## Property & Time Queries

Equality and numeric range queries are index-transparent. Callers do not choose indexed versus fallback execution. If a matching optional declaration is `Ready`, OverGraph uses it. Otherwise it scans through the same public query method.

### find_nodes

Finds all nodes with a given label where a specific property matches a given value.

**Rust**
```rust
let ids = db.find_nodes(
    "User",
    "role",
    &PropValue::String("admin".into()),
)?;
```

**Node.js**
```javascript
const ids = db.findNodes('User', 'role', 'admin'); // Float64Array
```

**Python**
```python
ids = db.find_nodes("User", "role", "admin")  # IdArray
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Restrict search to this node label. |
| prop_key | `&str` | `string` | `str` | Yes | Property key to match on. |
| prop_value | `PropValue` | `any` | `Any` | Yes | Value to match. Finite numeric scalars use semantic equality across signed integers, unsigned integers, and finite floats. Strings and other non-numeric values remain exact, so string `"1"` does not match integer `1`. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `IdArray` |

Matching node IDs. If a matching equality declaration is `Ready`, OverGraph uses the declaration-backed index path. Otherwise it scans nodes of the requested label.

---

### find_nodes_range

Finds all nodes with a given label where a numeric property falls within a range.

Results are ordered by `(property_value asc, node_id asc)`.

**Rust**
```rust
let ids = db.find_nodes_range(
    "User",
    "score",
    Some(&PropertyRangeBound::Included(PropValue::Int(10))),
    Some(&PropertyRangeBound::Excluded(PropValue::Float(20.0))),
)?;
```

**Node.js**
```javascript
const ids = db.findNodesRange(
  'User',
  'score',
  { value: 10, inclusive: true, domain: 'int' },
  { value: 20, inclusive: false, domain: 'float' },
);
```

**Python**
```python
ids = db.find_nodes_range(
    "User",
    "score",
    PropertyRangeBound(10, domain="int"),
    PropertyRangeBound(20.0, inclusive=False, domain="float"),
)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Restrict search to this node label. |
| prop_key | `&str` | `string` | `str` | Yes | Numeric property key to query. |
| lower | `Option<&PropertyRangeBound>` | `PropertyRangeBound \| null \| undefined` | `PropertyRangeBound \| None` | No | Lower bound. Omit for an unbounded start. |
| upper | `Option<&PropertyRangeBound>` | `PropertyRangeBound \| null \| undefined` | `PropertyRangeBound \| None` | No | Upper bound. Omit for an unbounded end. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `IdArray` |

Matching node IDs in range order.

#### Behavior

- At least one finite numeric bound is required.
- Bounds may mix signed integer, unsigned integer, and finite float values.
- Empty finite numeric intervals return an empty result.
- Non-finite floats, non-numeric values, arrays, and maps are invalid bounds.
- If a matching range declaration is `Ready`, OverGraph uses the declaration-backed range path.
- If no matching `Ready` declaration exists, OverGraph falls back to a scan of nodes of the requested label.
- Index-backed results remain verified against the latest visible records.
- Invalid bound combinations return an error.

---

### find_nodes_by_time_range

Finds all nodes with a given label and `updated_at` within a time range.

```rust
let ids = db.find_nodes_by_time_range("User", start_ms, end_ms)?;
```

```javascript
const ids = db.findNodesByTimeRange('User', startMs, endMs);
```

```python
ids = db.find_nodes_by_time_range("User", start_ms, end_ms)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| label | `&str` | `string` | `str` | Yes | Node label. |
| from_ms | `i64` | `number` | `int` | Yes | Start of range (inclusive), ms since epoch. |
| to_ms | `i64` | `number` | `int` | Yes | End of range (inclusive), ms since epoch. |

#### Returns

Node IDs matching the time range. Uses the timestamp index.

---

## Queries

Native query APIs combine explicit IDs, label-scoped keys, label/edge-label constraints, property filters, timestamp filters, and
row-producing graph patterns through normal function-call and object APIs. GQL Beta, documented below, adds a
read-only query-string API over the same graph-row substrate.

Native query APIs return matching IDs, hydrated records, or graph-row results with explicit columns,
rows, optional path values, cursors, stats, and explain output.

Node queries use a recursive `filter` tree.

Top-level request fields such as node `label_filter`, edge `label`, `ids`, and `keys` are not part of the
filter tree. They are top-level constraints and are ANDed with the filter. Within `ids` and
`keys`, values are OR alternatives.

Use `filter` for all node and edge predicates.

Query APIs use the same published read snapshot and visibility rules as direct read APIs.
Internally, OverGraph may use explicit IDs, key lookup, the node-label index, ready property
equality/range indexes, the timestamp index, sorted intersection, sorted union, fallback scans, or
bounded adjacency expansion. Candidate indexes are verified after candidate planning; indexes are
never trusted as final truth.

OverGraph may also use private durable planner statistics when they are available. These stats can
improve cost estimates, adaptive caps, OR/IN costing, and graph-row fanout planning, but they do
not change request shapes or result semantics. Missing, corrupt, or stale stats only degrade
planning quality; every returned result is still verified against the visible record.

### What Query APIs Are

Node queries are the API-first query surface for combining top-level constraints with a recursive
node `filter` tree. They are useful when a request needs more than one constraint, when an index may
help but should remain optional, or when the same filter should be explained.

Direct edge queries and graph-row edge constraints use the canonical edge `filter` tree for
edge metadata and property predicates. Maintained edge-property indexes are used when available;
otherwise predicates are verified over the planned edge universe.

### Choosing the Right Query API

Use [`query_node_ids`](#query_node_ids) when you need matching IDs and want OverGraph to combine
top-level constraints with a node filter tree.

Use [`query_nodes`](#query_nodes) for the same query shape when you need hydrated node records. It
shares the same plan and verifier as `query_node_ids`; only the final payload differs.

Use [`explain_node_query`](#explain_node_query) to inspect the selected physical plan and warnings
without executing the page.

Use [`query_edge_ids`](#query_edge_ids) when you need matching edge IDs from explicit edge IDs, edge-label
constraints, endpoint constraints, or an explicit full-scan opt-in.

Use [`query_edges`](#query_edges) for the same edge query shape when you need hydrated edge records.
Metadata-only filters hydrate only the final page. Property filters hydrate bounded verifier
candidates.

Use [`explain_edge_query`](#explain_edge_query) to inspect direct edge query planning.

Use direct property and time queries such as [`find_nodes`](#find_nodes),
[`find_nodes_range`](#find_nodes_range), and
[`find_nodes_by_time_range`](#find_nodes_by_time_range) when you already know you need one direct
indexed lookup or range lookup. Those APIs keep their existing shapes.

Use [`query_graph_rows`](#query_graph_rows) when the result is a row set over node, edge, and path
bindings, or when you need optional matches, bounded variable-length paths, final-row cursors, or
compact/projection output without writing a GQL string.

### Node Queries

#### query_node_ids

Runs a node query and returns matching node IDs.

**Rust**
```rust
let page = db.query_node_ids(&NodeQuery {
    label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into()],
        mode: LabelMatchMode::All,
    }),
    filter: Some(NodeFilterExpr::And(vec![
        NodeFilterExpr::PropertyEquals {
            key: "status".into(),
            value: PropValue::String("active".into()),
        },
        NodeFilterExpr::PropertyRange {
            key: "score".into(),
            lower: Some(PropertyRangeBound::Included(PropValue::Int(50))),
            upper: None,
        },
    ])),
    page: PageRequest { limit: Some(100), after: None },
    ..Default::default()
})?;
```

**Node.js**
```javascript
const page = db.queryNodeIds({
  labelFilter: { labels: ['User'], mode: 'all' },
  filter: {
    and: [
      { property: 'status', eq: 'active' },
      { property: 'score', gte: 50 },
    ],
  },
  limit: 100,
});
```

**Python**
```python
page = db.query_node_ids({
    "label_filter": {"labels": ["User"], "mode": "all"},
    "filter": {
        "and": [
            {"property": "status", "eq": "active"},
            {"property": "score", "gte": 50},
        ],
    },
    "limit": 100,
})
```

##### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| request | `&NodeQuery` | `QueryNodeRequest` | `dict \| NodeQueryRequest` | Yes | Node query request. See [NodeQuery](#nodequery). |

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<QueryNodeIdsResult, EngineError>` | `IdPageResult` | `IdPageResult` |

Result fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `items: Vec<u64>` | `items: Float64Array` | `items: IdArray` | Matching node IDs in ascending node ID order. |
| cursor | `next_cursor: Option<u64>` | `nextCursor?: number` | `next_cursor: int \| None` | Cursor for the next page. Pass it as `after`. |

---

#### query_nodes

Runs the same node query as [`query_node_ids`](#query_node_ids), then hydrates the final page of
matching nodes.

**Rust**
```rust
let page = db.query_nodes(&NodeQuery {
    label_filter: Some(NodeLabelFilter {
        labels: vec!["Document".into(), "Published".into()],
        mode: LabelMatchMode::All,
    }),
    filter: Some(NodeFilterExpr::PropertyEquals {
        key: "status".into(),
        value: PropValue::String("active".into()),
    }),
    page: PageRequest { limit: Some(25), after: None },
    ..Default::default()
})?;
```

**Node.js**
```javascript
const page = db.queryNodes({
  labelFilter: { labels: ['Document', 'Published'], mode: 'all' },
  filter: {
    and: [
      { property: 'status', in: ['active', 'trial'] },
      { not: { property: 'archivedAt', exists: true } },
      {
        or: [
          { property: 'priority', gte: 8 },
          { property: 'source', eq: 'user' },
        ],
      },
    ],
  },
  limit: 25,
});
```

**Python**
```python
page = db.query_nodes({
    "label_filter": {"labels": ["Document", "Published"], "mode": "all"},
    "filter": {
        "and": [
            {"property": "status", "in": ["active", "trial"]},
            {"not": {"property": "archived_at", "exists": True}},
            {
                "or": [
                    {"property": "priority", "gte": 8},
                    {"property": "source", "eq": "user"},
                ],
            },
        ],
    },
    "limit": 25,
})
```

##### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| request | `&NodeQuery` | `QueryNodeRequest` | `dict \| NodeQueryRequest` | Yes | Node query request. See [NodeQuery](#nodequery). |

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<QueryNodesResult, EngineError>` | `NodePageResult` | `NodePageResult` |

Result fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `items: Vec<NodeView>` | `items: NodeView[]` | `items: list[NodeView]` | Hydrated final page of matching nodes. |
| cursor | `next_cursor: Option<u64>` | `nextCursor: number \| null` | `next_cursor: int \| None` | Cursor for the next page. Pass it as `after`. |

Connector node records expose top-level fields eagerly. Property maps are converted only when the
`.props` getter is accessed.

---

#### explain_node_query

Returns the deterministic planner tree, estimates, and warnings for a node query. It applies the
same validation rules as execution.

**Rust**
```rust
let plan = db.explain_node_query(&query)?;
```

**Node.js**
```javascript
const plan = db.explainNodeQuery({
  labelFilter: { labels: ['User'], mode: 'all' },
  filter: { property: 'status', eq: 'active' },
});
```

**Python**
```python
plan = db.explain_node_query({
    "label_filter": {"labels": ["User"], "mode": "all"},
    "filter": {"property": "status", "eq": "active"},
})
```

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<QueryPlan, EngineError>` | `object` | `dict` |

See [QueryPlan](#queryplan).

---

### Direct Edge Queries

#### query_edge_ids

Runs a direct edge query and returns matching edge IDs in ascending edge ID order.

**Rust**
```rust
let page = db.query_edge_ids(&EdgeQuery {
    label: Some("WORKS_AT".into()),
    from_ids: vec![person_id],
    filter: Some(EdgeFilterExpr::And(vec![
        EdgeFilterExpr::WeightRange { lower: Some(1.0), upper: None },
        EdgeFilterExpr::ValidAt { epoch_ms },
    ])),
    page: PageRequest { limit: Some(100), after: None },
    ..Default::default()
})?;
```

**Node.js**
```javascript
const page = db.queryEdgeIds({
  label: 'WORKS_AT',
  fromIds: [personId],
  filter: {
    and: [
      { weight: { gte: 1.0 } },
      { validAt: epochMs },
    ],
  },
  limit: 100,
});
```

**Python**
```python
page = db.query_edge_ids({
    "label": "WORKS_AT",
    "from_ids": [person_id],
    "filter": {
        "and": [
            {"weight": {"gte": 1.0}},
            {"valid_at": epoch_ms},
        ],
    },
    "limit": 100,
})
```

#### query_edges

Runs the same direct edge query as [`query_edge_ids`](#query_edge_ids), then hydrates the final page
of matching edge records.

**Node.js**
```javascript
const page = db.queryEdges({
  label: 'WORKS_AT',
  endpointIds: [personId],
  filter: { property: 'role', eq: 'lead' },
  limit: 25,
});
```

**Python**
```python
page = db.query_edges({
    "label": "WORKS_AT",
    "endpoint_ids": [person_id],
    "filter": {"property": "role", "eq": "lead"},
    "limit": 25,
})
```

#### explain_edge_query

Returns the deterministic planner tree, estimates, and warnings for a direct edge query.

**Rust**
```rust
let plan = db.explain_edge_query(&query)?;
```

**Node.js**
```javascript
const plan = db.explainEdgeQuery({ label: 'WORKS_AT', fromIds: [personId] });
```

**Python**
```python
plan = db.explain_edge_query({"label": "WORKS_AT", "from_ids": [person_id]})
```

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<QueryEdgeIdsResult, EngineError>` | `IdPageResult` | `IdPageResult` |
| `Result<QueryEdgesResult, EngineError>` | `EdgePageResult` | `EdgePageResult` |
| `Result<QueryPlan, EngineError>` | `object` | `dict` |

Rust `QueryEdgeIdsResult` contains `edge_ids: Vec<u64>` and `next_cursor: Option<u64>`. Rust `QueryEdgesResult` contains `edges: Vec<EdgeView>` and `next_cursor: Option<u64>`. Node.js and Python page result objects use `items` for the returned IDs or edges.

---

### Graph Row Queries

Graph-row queries are the structured public API for row-producing graph reads. They replace the
old graph-pattern API surface. Rust no longer exports `GraphPatternQuery`, `PatternOrder`,
`QueryMatch`, `query_pattern`, or `explain_pattern_query`. Node.js no longer exposes
`queryPattern` / `explainPatternQuery`. Python keeps legacy runtime methods only to return an
unsupported error that points callers to `query_graph_rows` / `explain_graph_rows`.

Use graph-row queries when you need row bindings across nodes and edges, optional groups,
bounded variable-length paths, path values, explicit return columns, final-row cursors, compact rows,
or the same substrate used by GQL Beta.

#### query_graph_rows

Runs a graph-row request and returns explicit columns plus rows. Native graph-row execution uses the
same node/edge planners, indexes, adjacency readers, visibility rules, tombstone/shadow handling,
temporal edge checks, prune policy checks, and final verification as the direct query APIs. Row
assembly, optional semantics, path values, ordering, cursors, and projection are handled by the
graph-row executor.

**Rust**
```rust
let result = db.query_graph_rows(&GraphRowQuery {
    nodes: vec![
        GraphNodePattern {
            alias: "person".into(),
            label_filter: Some(NodeLabelFilter {
                labels: vec!["Person".into()],
                mode: LabelMatchMode::All,
            }),
            ids: vec![],
            keys: vec![],
            filter: Some(NodeFilterExpr::PropertyEquals {
                key: "status".into(),
                value: PropValue::String("active".into()),
            }),
        },
        GraphNodePattern {
            alias: "company".into(),
            label_filter: Some(NodeLabelFilter {
                labels: vec!["Company".into()],
                mode: LabelMatchMode::All,
            }),
            ids: vec![],
            keys: vec![],
            filter: None,
        },
    ],
    pieces: vec![GraphPatternPiece::Edge(GraphEdgePattern {
        alias: Some("works".into()),
        from_alias: "person".into(),
        to_alias: "company".into(),
        direction: Direction::Outgoing,
        label_filter: vec!["WORKS_AT".into()],
        filter: None,
    })],
    where_: None,
    return_items: Some(vec![
        GraphReturnItem {
            expr: GraphExpr::Property { alias: "person".into(), key: "name".into() },
            alias: Some("person".into()),
            projection: GraphReturnProjection::Auto,
        },
        GraphReturnItem {
            expr: GraphExpr::Property { alias: "company".into(), key: "name".into() },
            alias: Some("company".into()),
            projection: GraphReturnProjection::Auto,
        },
    ]),
    order_by: vec![GraphOrderItem {
        expr: GraphExpr::Property { alias: "person".into(), key: "name".into() },
        direction: GraphOrderDirection::Asc,
    }],
    page: GraphPageRequest { skip: 0, limit: 100, cursor: None },
    at_epoch: None,
    params: BTreeMap::new(),
    output: GraphOutputOptions::default(),
    options: GraphQueryOptions::default(),
})?;
```

**Node.js**
```javascript
const result = db.queryGraphRows({
  nodes: [
    { alias: 'person', labelFilter: { labels: ['Person'], mode: 'all' } },
    { alias: 'company', labelFilter: { labels: ['Company'], mode: 'all' } },
  ],
  pieces: [
    { kind: 'edge', alias: 'works', fromAlias: 'person', toAlias: 'company', labelFilter: ['WORKS_AT'] },
  ],
  where: { op: '=', left: { property: { alias: 'person', key: 'status' } }, right: { param: 'status' } },
  return: [
    { expr: { property: { alias: 'person', key: 'name' } }, as: 'person' },
    { expr: { property: { alias: 'company', key: 'name' } }, as: 'company' },
  ],
  orderBy: [{ expr: { property: { alias: 'person', key: 'name' } }, direction: 'asc' }],
  params: { status: 'active' },
  limit: 100,
});
```

**Python**
```python
result = db.query_graph_rows({
    "nodes": [
        {"alias": "person", "label_filter": {"labels": ["Person"], "mode": "all"}},
        {"alias": "company", "label_filter": {"labels": ["Company"], "mode": "all"}},
    ],
    "pieces": [
        {"kind": "edge", "alias": "works", "from": "person", "to": "company", "labels": ["WORKS_AT"]},
    ],
    "where": {"op": "=", "left": {"property": {"alias": "person", "key": "status"}}, "right": {"param": "status"}},
    "return": [
        {"expr": {"property": {"alias": "person", "key": "name"}}, "as": "person"},
        {"expr": {"property": {"alias": "company", "key": "name"}}, "as": "company"},
    ],
    "order_by": [{"expr": {"property": {"alias": "person", "key": "name"}}, "direction": "asc"}],
    "params": {"status": "active"},
    "limit": 100,
})
```

##### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| request | `&GraphRowQuery` | `GraphRowRequest` | `dict \| GraphRowRequest` | Yes | Graph-row request. See [GraphRowQuery](#graphrowquery). |

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<GraphRowResult, EngineError>` | `GraphRowResult` | `GraphRowResult` |

Result fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| columns | `columns` | `columns` | `columns` | Output column names in row order. |
| rows | `rows: Vec<GraphRow>` | `rows: object[]` or `rows: any[][]` | `rows: list[dict]` or `list[list]` | Rust rows are positional `values`. Connectors return objects by default and arrays when compact rows are enabled. |
| next cursor | `next_cursor` | `nextCursor` | `next_cursor` | Final logical row cursor for the next page, or null/None on the last page. |
| stats | `stats` | `stats` | `stats` | Row counts, peak intermediate/frontier counts, path count, db-hit counter, effective epoch, elapsed time, and warnings. |
| plan | `plan` | `plan` | `plan` | `GraphRowExplain` when `options.include_plan` / `includePlan` / `include_plan` is true; otherwise null/None. |

Optional misses produce null values. In Rust that is `GraphValue::Null`; Node.js serializes it as
`null`; Python serializes it as `None`.

Path values contain identity arrays plus optional hydrated elements:

| Path field | Rust | Node.js | Python |
|------------|------|---------|--------|
| Node IDs | `node_ids` | `nodeIds` | `node_ids` |
| Edge IDs | `edge_ids` | `edgeIds` | `edge_ids` |
| Hydrated nodes | `nodes: Option<Vec<GraphNodeValue>>` | `nodes?: GraphNodeValue[]` | `nodes?: list[dict]` |
| Hydrated edges | `edges: Option<Vec<GraphEdgeValue>>` | `edges?: GraphEdgeValue[]` | `edges?: list[dict]` |

Default graph-row output mode is ID-oriented. Returning a path binding in default mode returns
`node_ids` / `edge_ids` only. `output.mode = elements` / `mode: 'elements'` / `"mode": "elements"`
hydrates returned node, edge, and path element values. Full node element hydration omits dense and
sparse vectors unless `include_vectors` / `includeVectors` is true. Selected projections can request
specific fields, including vector fields for selected node values.

#### explain_graph_rows

Returns graph-row validation and plan/explain output without returning rows.

**Rust**
```rust
let explain = db.explain_graph_rows(&query)?;
```

**Node.js**
```javascript
const explain = db.explainGraphRows(request);
const asyncExplain = await db.explainGraphRowsAsync(request);
```

**Python**
```python
explain = db.explain_graph_rows(request)
async_explain = await async_db.explain_graph_rows(request)
```

##### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<GraphRowExplain, EngineError>` | `GraphRowExplain` | `dict` |

`GraphRowExplain` fields are:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| columns | `columns` | `columns` | `columns` | Output columns after return expansion. |
| effective epoch | `effective_at_epoch` | `effectiveAtEpoch` | `effective_at_epoch` | Temporal epoch used by planning when known. |
| fingerprint | `fingerprint` | `fingerprint` | `fingerprint` | Normalized query fingerprint used by cursors. |
| plan | `plan` | `plan` | `plan` | Graph-row explain nodes, including optional/path/runtime details. |
| row ops | `row_ops` | `rowOps` | `row_ops` | Sort, skip, limit, projection, and related row-operation notes. |
| order | `order` | `order` | `order` | Whether explicit ordering is present and whether stable logical row keys are used. |
| cursor | `cursor` | `cursor` | `cursor` | Cursor supplied/codec status and message. |
| projection | `projection` | `projection` | `projection` | Columns, output mode, vector policy, and compact-row policy. |
| caps | `caps` | `caps` | `caps` | Effective graph-row safety caps. |
| summaries | `summaries` | `summaries` | `summaries` | Validation/runtime summary counters and warnings. |
| warnings / notes | `warnings`, `notes` | `warnings`, `notes` | `warnings`, `notes` | Planner warnings and explanatory notes. |

Node.js and Python async APIs expose graph-row query and explain methods through
`queryGraphRowsAsync`, `explainGraphRowsAsync`, and `AsyncOverGraph.query_graph_rows` /
`AsyncOverGraph.explain_graph_rows`.

---

### GQL Beta

#### Overview

**GQL Beta** is OverGraph's read-only GQL/Cypher-style query-string interface. It is for application
code that is easier to read as a query string than as a native request object, while still staying
inside OverGraph's embedded Rust engine.

GQL Beta is not a second execution engine. The Rust API parses, binds, lowers, plans, and executes
each query through the same graph-row substrate as [`query_graph_rows`](#query_graph_rows). Node.js
and Python connectors call that Rust API directly; they do not reimplement parser, lowering,
planning, execution, cursor handling, optional semantics, or path value conversion.

What GQL Beta gives you:

- familiar `MATCH`, `OPTIONAL MATCH`, `WHERE`, `RETURN`, `ORDER BY`, `SKIP` / `OFFSET`, and `LIMIT` query strings
- row-shaped graph reads over required patterns, optional groups, and bounded variable-length paths
- scalar values, node values, edge values, path values, lists, maps, bytes, and nulls
- params, full-scan opt-in, caps, explain/profile, warnings, and stats
- final-row continuation cursors
- vector omission by default, with explicit opt-in when returning node values
- Rust, Node.js, and Python parity over the same Rust parser, binder, lowerer, planner, and executor

The GQL Beta supported subset is intentionally bounded. It is read-only and not full ISO GQL or
full Cypher. Unsupported features are listed in
[Not Yet Supported In GQL Beta](#not-yet-supported-in-gql-beta). A compact syntax companion is also
available in [GQL Beta](gql-subset.md).

#### Supported Syntax

Supported clause order:

```gql
MATCH <pattern> [, <pattern>...] [WHERE <predicate>]
OPTIONAL MATCH <pattern> [, <pattern>...] [WHERE <predicate>]
RETURN <items>
ORDER BY <order-expression> [ASC|DESC], ...
SKIP <integer-or-param>
OFFSET <integer-or-param>
LIMIT <integer-or-param>
```

`WHERE`, `ORDER BY`, `SKIP` / `OFFSET`, and `LIMIT` are optional. Each required or optional match
clause can have its own `WHERE`. `OPTIONAL MATCH` clauses follow an initial required `MATCH`.
`SKIP` and `OFFSET` are synonyms in this beta subset; using both in one
query is rejected. `LIMIT 0` validates the query and returns an empty result without running
graph-row execution.

Supported pattern shapes:

| Shape | Example |
|-------|---------|
| Node pattern | `MATCH (n:Person)` |
| Fixed edge pattern | `MATCH (p:Person)-[r:WORKS_AT]->(c:Company)` |
| Multiple fixed hops | `MATCH (a)-[r:KNOWS]->(b)-[s:LIKES]->(c)` |
| Undirected fixed edge | `MATCH (a)-[r:KNOWS]-(b)` |
| Optional group | `MATCH (p:Person) OPTIONAL MATCH (p)-[r:REPORTS_TO]->(m:Person)` |
| Bounded variable-length path | `MATCH p = (a)-[:KNOWS*1..3]->(b)` |
| Zero-to-N bounded path | `MATCH p = (a)-[:KNOWS*0..2]->(b)` or `MATCH p = (a)-[:KNOWS*..2]->(b)` |
| Exact-length path | `MATCH p = (a)-[:KNOWS*2]->(b)` |
| One-hop path plus edge alias | `MATCH p = (a)-[r:KNOWS*1..1]->(b)` |
| Property map predicates | `MATCH (n:Person {name: $name})` |

Relationship quantifiers must have a finite upper bound. The upper bound must fit the engine's path
hop cap. Variable-length paths are relationship-simple: one path cannot reuse the same edge ID.
Multi-hop relationship-list aliases are not supported; return the path alias and inspect
`edge_ids`.

Supported expressions:

| Expression | Example |
|------------|---------|
| Variables | `n`, `r`, `company` |
| Node ID | `id(n)` |
| Edge ID | `id(r)` |
| Node labels | `labels(n)` |
| Edge label/type | `type(r)` |
| Node metadata | `n.id`, `n.labels`, `n.key`, `n.weight`, `n.created_at`, `n.updated_at` |
| Edge metadata | `r.from`, `r.to`, `r.weight`, `r.created_at`, `r.updated_at`, `r.valid_from`, `r.valid_to` |
| Path fields | `p.node_ids`, `p.edge_ids`, `p.length` |
| Property access | `n.name`, `n.rank`, `r.since`, `r.role`, `r.id`, `r.label` |
| Literals | `null`, booleans, integers, floats, strings, lists, maps |
| Params | `$name`, `$ids`, `$minSince`, `$payload` |
| Boolean predicates | `AND`, `OR`, `NOT` |
| Comparisons | `=`, `<>`, `<`, `<=`, `>`, `>=` |
| Null checks | `IS NULL`, `IS NOT NULL` |
| Membership | `IN` |
| Return all bound aliases | `RETURN *` |

Supported functions:

| Function | Valid argument |
|----------|----------------|
| `id(n)` | node or edge alias |
| `labels(n)` | node alias |
| `type(r)` | edge alias |
| `length(p)` | path alias |
| `start_node(p)` | path alias |
| `end_node(p)` | path alias |
| `nodes(p)` | path alias |
| `relationships(p)` | path alias |
| `node_ids(p)` | path alias |
| `edge_ids(p)` | path alias |

`ORDER BY` uses graph-row order atoms. Null, bool, finite numeric, string, bytes, node, edge, and
path values are orderable. Nulls sort last. Lists, maps, and non-finite floats are rejected.

Edge ID and edge-label metadata use `id(r)` and `type(r)`. Dot access such as `r.id` and
`r.label` reads ordinary edge properties with those names when present.

#### Method Reference

| Language | Query | Explain |
|----------|-------|---------|
| Rust | `DatabaseEngine::execute_gql(query, params, options)` | `DatabaseEngine::explain_gql(query, params, options)` |
| Node.js | `db.executeGql(query, params?, options?)` | `db.explainGql(query, params?, options?)` |
| Node.js async | `db.executeGqlAsync(query, params?, options?)` | `db.explainGqlAsync(query, params?, options?)` |
| Python | `db.execute_gql(query, params=None, **options)` | `db.explain_gql(query, params=None, **options)` |
| Python async | `await db.execute_gql(query, params=None, **options)` | `await db.explain_gql(query, params=None, **options)` |

**Rust**
```rust
let result = db.execute_gql(
    "MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10",
    &GqlParams::new(),
    &GqlQueryOptions::default(),
)?;

let explain = db.explain_gql(
    "MATCH (n:Person) RETURN n.name AS name",
    &GqlParams::new(),
    &GqlQueryOptions::default(),
)?;
```

**Node.js**
```javascript
const result = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10'
);

const asyncResult = await db.executeGqlAsync(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10'
);

const explain = db.explainGql(
  'MATCH (n:Person) RETURN n.name AS name'
);
```

**Python**
```python
result = db.execute_gql(
    "MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10"
)

async_result = await async_db.execute_gql(
    "MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10"
)

explain = db.explain_gql(
    "MATCH (n:Person) RETURN n.name AS name"
)
```

#### Parameters and Options

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| query | `&str` | `string` | `str` | Yes | - | GQL query text. Must be one supported read-only statement. |
| params | `&GqlParams` | `GqlParams \| null` | `GqlParams \| None` | No | empty | Named params referenced as `$name` in the query. |
| options | `&GqlQueryOptions` | `GqlQueryOptions` | keyword options | No | default options | Execution, cap, explain/profile, row-format, and vector options. |

Option fields:

| Option | Rust | Node.js | Python | Default | Description |
|--------|------|---------|--------|---------|-------------|
| Full-scan opt-in | `allow_full_scan` | `allowFullScan` | `allow_full_scan` | `false` | Allows legal broad node/edge scans when no bounded native anchor exists. |
| Result row cap | `max_rows` | `maxRows` | `max_rows` | `10000` | Maximum returned rows after row operations. Also protects unbounded result materialization. |
| Cursor | `cursor` | `cursor` | `cursor` | `None` / `null` | Continuation token from `next_cursor` / `nextCursor`. |
| Cursor byte cap | `max_cursor_bytes` | `maxCursorBytes` | `max_cursor_bytes` | `16384` | Maximum accepted or emitted cursor token size. |
| Intermediate cap | `max_intermediate_bindings` | `maxIntermediateBindings` | `max_intermediate_bindings` | `65536` | Maximum native/intermediate row bindings held while executing the query. |
| Skip cap | `max_skip` | `maxSkip` | `max_skip` | `100000` | Maximum allowed `SKIP` / `OFFSET` value. |
| Include plan | `include_plan` | `includePlan` | `include_plan` | `false` | Attaches the same explain payload to `GqlResult.plan`. |
| Profile | `profile` | `profile` | `profile` | `false` | Adds elapsed time and best-effort work counters to stats. |
| Compact rows | `compact_rows` | `compactRows` | `compact_rows` | `false` | Rust rows are already positional. In connectors, returns row arrays instead of row objects. Does not change execution. |
| Include vectors | `include_vectors` | `includeVectors` | `include_vectors` | `false` | Includes dense/sparse vectors when returning node element values. |
| Query byte cap | `max_query_bytes` | `maxQueryBytes` | `max_query_bytes` | `1048576` | Maximum GQL source text bytes accepted by the parser. |
| Param byte cap | `max_param_bytes` | `maxParamBytes` | `max_param_bytes` | `1048576` | Maximum referenced param string/bytes/map-key bytes, both per value/key and total across referenced params. |
| AST/param depth cap | `max_ast_depth` | `maxAstDepth` | `max_ast_depth` | `256` | Maximum parser AST depth and referenced runtime list/map nesting depth. |
| Literal/param item cap | `max_literal_items` | `maxLiteralItems` | `max_literal_items` | `10000` | Maximum list/map literal items, per referenced list/map container, and total referenced list/map items. |

`compactRows` / `compact_rows` is connector serialization only. It does not change parsing, lowering,
planning, selected fields, vector policy, ordering, stats, caps, warnings, or plan truth.

#### Results and Row Formats

Rust returns positional rows:

```rust
GqlResult {
    columns: Vec<String>,
    rows: Vec<GqlRow>,          // each GqlRow has values: Vec<GqlValue>
    next_cursor: Option<String>,
    stats: GqlExecutionStats,
    plan: Option<GqlExplain>,
}
```

Node.js and Python return object rows by default:

```javascript
{
  columns: ['name', 'rank'],
  rows: [
    { name: 'Ada', rank: 2 },
    { name: 'Ben', rank: 4 },
  ],
  nextCursor: null,
  stats: {
    rowsReturned: 2,
    rowsMatched: 2,
    rowsAfterFilter: 2,
    intermediateBindings: 2,
    dbHits: 2,
    elapsedUs: null,
    truncated: false,
    warnings: [],
  },
  plan: null,
}
```

With compact rows enabled, connectors keep the same `columns` array and return positional row arrays:

```javascript
const result = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name, n.rank AS rank ORDER BY n.rank',
  null,
  { compactRows: true }
);

// result.columns: ['name', 'rank']
// result.rows: [['Ben', 1], ['Ada', 2]]
```

Duplicate output names are allowed. Object-row connectors use the duplicate column name as the object
key, so prefer aliases that are unique when using object rows. Use compact rows when duplicate column
names must be preserved positionally. Row-operation references to return aliases must be
unambiguous: if multiple `RETURN` items use the same alias, clauses such as `ORDER BY x` or
`LIMIT x` reject `x` instead of choosing one of the duplicate columns.

When a result has another page, it includes `next_cursor` / `nextCursor`. Pass that value as the
next call's `cursor` option with the same logical query and params. GQL cursors are continuation
tokens over final logical result rows and validate the normalized graph-row fingerprint. They are
not pinned storage snapshots across pages.

#### Nodes, Edges, Values, and Vectors

GQL values can be:

- `null`
- booleans
- signed integers, unsigned integers, and finite floats
- strings
- bytes
- lists
- maps with string keys
- node values
- edge values
- path values

Node.js bytes are returned as `Buffer`. Python bytes are returned as `bytes`. Rust uses
`GqlValue::Bytes(Vec<u8>)`.

Node values expose only requested fields:

| Field | Rust | Node.js | Python |
|-------|------|---------|--------|
| ID | `id` | `id` | `id` |
| Labels | `labels` | `labels` | `labels` |
| Key | `key` | `key` | `key` |
| Properties | `props` | `props` | `props` |
| Weight | `weight` | `weight` | `weight` |
| Created timestamp | `created_at` | `createdAt` | `created_at` |
| Updated timestamp | `updated_at` | `updatedAt` | `updated_at` |
| Dense vector | `dense_vector` | `denseVector` | `dense_vector` |
| Sparse vector | `sparse_vector` | `sparseVector` | `sparse_vector` |

Edge values expose only requested fields:

| Field | Rust | Node.js | Python |
|-------|------|---------|--------|
| ID | `id` | `id` | `id` |
| Source node ID | `from` | `from` | `from_id` |
| Target node ID | `to` | `to` | `to_id` |
| Label | `label` | `label` | `label` |
| Properties | `props` | `props` | `props` |
| Weight | `weight` | `weight` | `weight` |
| Created timestamp | `created_at` | `createdAt` | `created_at` |
| Updated timestamp | `updated_at` | `updatedAt` | `updated_at` |
| Valid-from timestamp | `valid_from` | `validFrom` | `valid_from` |
| Valid-to timestamp | `valid_to` | `validTo` | `valid_to` |

Returning a node element omits dense and sparse vectors by default:

```javascript
const withoutVectors = db.executeGql(
  "MATCH (n:Person {name: 'Ada'}) RETURN n"
);

// withoutVectors.rows[0].n.denseVector is undefined
```

Opt in when the query result needs vectors:

```javascript
const withVectors = db.executeGql(
  "MATCH (n:Person {name: 'Ada'}) RETURN n",
  null,
  { includeVectors: true }
);
```

Path values expose identity arrays and, when a path alias is returned as a value, hydrated node and
edge elements:

| Field | Rust | Node.js | Python |
|-------|------|---------|--------|
| Node IDs | `node_ids` | `nodeIds` | `node_ids` |
| Edge IDs | `edge_ids` | `edgeIds` | `edge_ids` |
| Nodes | `nodes` | `nodes` | `nodes` |
| Edges | `edges` | `edges` | `edges` |

Hydrated nodes inside path values follow the same vector policy as returned node values.

#### Params

Params are named and referenced with `$name` syntax. They are converted into Rust `GqlParamValue`
before planning and execution.

Only params referenced by the query are resource-validated. Referenced list/map params are bounded
by `max_ast_depth` and `max_literal_items`; referenced string, bytes, and map-key payload bytes are
bounded by `max_param_bytes`. Extra unused params are ignored by the GQL engine.

Supported param values:

| Shape | Node.js | Python | Rust |
|-------|---------|--------|------|
| Null | `null` / `undefined` value | `None` | `GqlParamValue::Null` |
| Boolean | `true` / `false` | `True` / `False` | `GqlParamValue::Bool` |
| Signed integer | negative safe integer | negative `int` | `GqlParamValue::Int` |
| Unsigned integer | non-negative safe integer | non-negative `int` / `u64` extraction | `GqlParamValue::UInt` |
| Float | finite non-integer `number` | finite `float` | `GqlParamValue::Float` |
| String | `string` | `str` | `GqlParamValue::String` |
| Bytes | `Buffer` / `ArrayBuffer` | `bytes` | `GqlParamValue::Bytes` |
| List | `Array` | `list` / `tuple` | `GqlParamValue::List` |
| Map | plain object | `dict` with string keys | `GqlParamValue::Map` |

Node.js example:

```javascript
const result = db.executeGql(
  `MATCH (p:Person {name: $name})-[r:WORKS_AT]->(c:Company)
   WHERE r.since >= $minSince AND p.status IN $statuses
   RETURN id(p) AS personId, p.name AS person, c.name AS company, $payload AS payload`,
  {
    name: 'Ada',
    minSince: 2020,
    statuses: ['active', 'trial'],
    payload: { source: 'api', bytes: Buffer.from('trace-id') },
  }
);
```

Rust typed params and options:

```rust
let params = GqlParams::from([
    ("name".to_string(), GqlParamValue::String("Ada".to_string())),
    ("minRank".to_string(), GqlParamValue::Int(2)),
]);

let options = GqlQueryOptions {
    include_plan: true,
    profile: true,
    ..GqlQueryOptions::default()
};

let result = db.execute_gql(
    "MATCH (n:Person {name: $name}) WHERE n.rank >= $minRank RETURN id(n) AS id",
    &params,
    &options,
)?;
```

#### Explain, Profile, and Stats

`explain_gql` / `explainGql` validates, binds, lowers, and plans the query without
executing rows.

Explain result fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| Columns | `columns` | `columns` | `columns` | Output column names after `RETURN` expansion and aliases. |
| Target | `target` | `target` | `target` | Current Phase 32 GQL lowering returns `graph_row_query`. |
| Native plan | `native_plan` | `nativePlan` | `native_plan` | Currently null for the graph-row target. Graph-row plan details are summarized in `projection` and warnings. |
| Pushed down | `pushed_down` | `pushedDown` | `pushed_down` | Predicates represented in the native target. |
| Residual | `residual` | `residual` | `residual` | Predicates evaluated after native execution. |
| Projection | `projection` | `projection` | `projection` | Output/runtime projection needs plus graph-row plan, row-op, order, cursor, cap, and note summaries. |
| Row ops | `row_ops` | `rowOps` | `row_ops` | `residual_filter`, `sort`, `skip`, `limit`, `projection`. |
| Caps | `caps` | `caps` | `caps` | Effective cap settings for the query. |
| Warnings | `warnings` | `warnings` | `warnings` | GQL/native planning warnings. |

`includePlan` / `include_plan` attaches that same explain payload to executed results:

```javascript
const result = db.executeGql(
  `MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
   RETURN p.name AS person, r.since AS since, c.name AS company
   ORDER BY r.since DESC
   LIMIT 10`,
  null,
  { includePlan: true, profile: true }
);

console.log(result.plan.target);       // 'graph_row_query'
console.log(result.plan.rowOps);       // e.g. ['sort', 'limit', 'projection']
console.log(result.stats.elapsedUs);   // populated when profile is true
```

Stats fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| Rows returned | `rows_returned` | `rowsReturned` | `rows_returned` | Final result row count. |
| Native rows matched | `rows_matched` | `rowsMatched` | `rows_matched` | Rows produced/observed by graph-row execution before final projection. |
| Rows after filter | `rows_after_filter` | `rowsAfterFilter` | `rows_after_filter` | Rows remaining after residual filtering before final row ops. |
| Intermediate bindings | `intermediate_bindings` | `intermediateBindings` | `intermediate_bindings` | Maximum/representative intermediate row count held by execution. |
| Work counter | `db_hits` | `dbHits` | `db_hits` | Best-effort profile work units, not a storage IO contract. |
| Elapsed time | `elapsed_us` | `elapsedUs` | `elapsed_us` | Populated only when profile is true. |
| Truncated | `truncated` | `truncated` | `truncated` | True when a safety cap or native cap truncated execution. |
| Warnings | `warnings` | `warnings` | `warnings` | Cap, ordering, full-scan, and planning warnings. |

Full scans are rejected unless explicitly allowed:

```javascript
db.executeGql('MATCH (n) RETURN id(n) AS id');
// throws: full scan / allowFullScan required

const broad = db.executeGql(
  'MATCH (n) RETURN id(n) AS id LIMIT 100',
  null,
  { allowFullScan: true }
);
```

#### Examples

Basic node rows:

```javascript
const people = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10'
);
```

Parameterized property lookup with a property map:

```javascript
const person = db.executeGql(
  'MATCH (n:Person {name: $name}) RETURN id(n) AS id, n.name AS name',
  { name: 'Ada' }
);
```

One-hop relationship pattern:

```javascript
const jobs = db.executeGql(
  `MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
   RETURN p.name AS person, r.since AS since, c.name AS company
   ORDER BY r.since DESC
   LIMIT 20`
);
```

Residual `WHERE` with params:

```javascript
const filtered = db.executeGql(
  `MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
   WHERE p.status = $status AND r.since >= $minSince
   RETURN p.name AS person, r.role AS role, c.name AS company`,
  { status: 'active', minSince: 2020 }
);
```

Direct edge query:

```javascript
const likes = db.executeGql(
  'MATCH ()-[r:LIKES]->() RETURN id(r) AS id, type(r) AS label, r.weight AS weight LIMIT 25'
);
```

Multi-hop fixed pattern:

```javascript
const paths = db.executeGql(
  `MATCH (a:Person)-[r:KNOWS]->(b:Person)-[s:WORKS_AT]->(c:Company)
   RETURN a.name AS source, b.name AS friend, c.name AS company
   LIMIT 50`
);
```

Optional match:

```javascript
const rows = db.executeGql(
  `MATCH (p:Person)
   OPTIONAL MATCH (p)-[:REPORTS_TO]->(m:Person)
   RETURN p.name AS person, m.name AS manager
   ORDER BY p.name`,
  null,
  { allowFullScan: true }
);
```

Bounded path value and path functions:

```javascript
const rows = db.executeGql(
  `MATCH p = (a:Person)-[:KNOWS*1..3]->(b:Person)
   WHERE a.name = $name
   RETURN p, length(p) AS hops, node_ids(p) AS nodeIds, edge_ids(p) AS edgeIds
   ORDER BY hops ASC
   LIMIT 10`,
  { name: 'Ada' }
);

console.log(rows.rows[0].p.nodeIds);
console.log(rows.rows[0].p.edgeIds);
```

Continuation cursor:

```javascript
const first = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10'
);

const second = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10',
  null,
  { cursor: first.nextCursor }
);
```

`RETURN *` expands user-visible bound aliases in deterministic binding order:

```javascript
const bindings = db.executeGql(
  'MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN * LIMIT 10'
);
```

Element projection returns node and edge objects:

```javascript
const rows = db.executeGql(
  'MATCH (p:Person)-[r:WORKS_AT]->(c:Company) RETURN p, r, c LIMIT 5'
);

console.log(rows.rows[0].p.labels);
console.log(rows.rows[0].r.from, rows.rows[0].r.to);
```

`SKIP` / `OFFSET` and `LIMIT`:

```javascript
const page = db.executeGql(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.rank DESC SKIP 20 LIMIT 10'
);
```

Python result shape:

```python
result = db.execute_gql(
    "MATCH (n:Person) RETURN n.name AS name, n.rank AS rank ORDER BY n.rank",
    compact_rows=True,
)

print(result["columns"])  # ["name", "rank"]
print(result["rows"])     # [["Ben", 1], ["Ada", 2]]
print(result["stats"]["rows_returned"])
```

Explain without execution:

```javascript
const explain = db.explainGql(
  `MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
   WHERE p.status = $status
   RETURN p.name AS person, c.name AS company`,
  { status: 'active' }
);

console.log(explain.target);
console.log(explain.nativePlan?.warnings);
```

Async connector calls:

```javascript
const result = await db.executeGqlAsync(
  'MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10'
);
```

```python
result = await async_db.execute_gql(
    "MATCH (n:Person) RETURN n.name AS name ORDER BY n.name LIMIT 10"
)
```

#### Not Yet Supported In GQL Beta

GQL Beta intentionally rejects features outside the supported read-only subset:

- Full ISO GQL
- Full Cypher compatibility
- Writes and mutations: `CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`, `FOREACH`, `LOAD`
- Schema operations: `CREATE INDEX`, constraints, `DROP`, `ALTER`, `SHOW`
- Aggregation
- `DISTINCT`
- `WITH`
- `UNION`
- `CALL`
- Subqueries
- Procedures
- Dynamic labels and dynamic relationship types
- Unbounded variable-length paths
- Shortest path pattern/function syntax
- Advanced path functions beyond `length`, `start_node`, `end_node`, `nodes`, `relationships`, `node_ids`, and `edge_ids`
- Multi-hop relationship-list aliases separate from path aliases
- Path assignment over multiple relationship segments
- Pattern-local predicates inside node or relationship patterns
- Plan cache
- Native multi-label edge OR in direct edge lowering
- List/map and non-finite-float `ORDER BY` domains

Use native query APIs when you need request-object construction, strongly bounded pagination by ID,
or APIs outside the GQL Beta subset. Use GQL Beta when a read-only graph query string is the
clearest way to express the read.

---

### Query Request Types and Plans

#### NodeQuery

Node query request fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| label_filter / labelFilter | `Option<NodeLabelFilter>` | `labelFilter?: { labels: string[], mode: "any" \| "all" }` | `label_filter?: {"labels": list[str], "mode": "any" \| "all"}` | Node-label constraint with explicit `Any` / `All` semantics. A one-label `All` filter uses the single-label fast path. |
| ids | `Vec<u64>` | `ids?: number[]` | `ids?: list[int]` | Explicit node ID candidates. OR within the list. |
| keys | `Vec<String>` | `keys?: string[]` | `keys?: list[str]` | Label-scoped key candidates. OR within the list. |
| filter | `Option<NodeFilterExpr>` | `filter?: QueryNodeFilter \| null` | `filter?: QueryNodeFilter \| None` | Recursive node filter tree. Omit or pass null/None for no filter. |
| limit | `page.limit` | `limit?: number` | `limit?: int` | Page size. Omit for unlimited. Connector `0` means unlimited. |
| after | `page.after` | `after?: number` | `after?: int` | Cursor from a previous page. Returns items with node IDs strictly greater than `after`. |
| allow_full_scan | `bool` | `allowFullScan?: boolean` | `allow_full_scan?: bool` | Required for unanchored full scan fallback. |

Top-level `label_filter` / `labelFilter`, `ids`, and `keys` are ANDed with `filter`.
A one-label `All` filter uses the direct node-label fast path. Key lookups require exactly one resolved node label.
Label-less verify-only filters require `allow_full_scan` / `allowFullScan` unless `ids` or `keys`
provide a legal bounded universe.

---

#### NodeFilter / QueryNodeFilter

Rust uses `NodeFilterExpr`. Node.js and Python use the canonical recursive `QueryNodeFilter`
object shape.

| Filter shape | Node.js | Python | Meaning |
|--------------|---------|--------|---------|
| Equality | `{ property: "status", eq: "active" }` | `{"property": "status", "eq": "active"}` | Property exactly equals value |
| IN | `{ property: "status", in: ["active", "trial"] }` | `{"property": "status", "in": ["active", "trial"]}` | Property equals any listed value |
| Range | `{ property: "score", gte: 50 }` | `{"property": "score", "gte": 50}` | Numeric/range comparison |
| Range with two bounds | `{ property: "score", gt: 50, lte: 100 }` | `{"property": "score", "gt": 50, "lte": 100}` | Bounded numeric/range comparison |
| Exists | `{ property: "embedding", exists: true }` | `{"property": "embedding", "exists": True}` | Property key is present |
| Missing | `{ property: "deletedAt", missing: true }` | `{"property": "deleted_at", "missing": True}` | Property key is absent |
| AND | `{ and: [filter, ...] }` | `{"and": [filter, ...]}` | All children must match |
| OR | `{ or: [filter, ...] }` | `{"or": [filter, ...]}` | Any child may match |
| NOT | `{ not: filter }` | `{"not": filter}` | Child must not match |
| Updated-at range | `{ updatedAt: { gte: ms } }` | `{"updated_at": {"gte": ms}}` | Built-in node `updated_at` timestamp range |

Property values use OverGraph's normal `PropValue` conversion rules. There is no query-only
coercion for non-numeric values. For example, string `"1"` does not match integer `1`.
Finite scalar numeric values do use semantic numeric equality and ordering, so integer `1`,
unsigned integer `1`, and float `1.0` compare equal while range comparisons can mix numeric
bound variants.

`in` is equivalent to equality OR for matching semantics. When a ready equality index exists, the
query engine may evaluate it as an indexed union, but final visible-record verification still decides
correctness.

`exists` and `missing` are key-presence predicates, not null checks. `exists` matches when the
property key is present even if its value is null. `missing` matches only when the key is absent.

`not` is verifier-first. A negative filter does not anchor a broad query by itself.

`or` can use an indexed union only when every branch is bounded. If any OR branch is verify-only or
requires fallback, the whole OR subtree is verified over the nearest legal universe rather than
planned as a partial union.

Results from node queries are ordered by node ID ascending. The `after` cursor means strictly
greater than that node ID.

##### Built-in timestamp versus same-named user property

The built-in timestamp filter is a structural field. User property names always live in the
`property` value field, so they do not collide with built-ins.

**Node.js**
```javascript
// Built-in node timestamp:
db.queryNodeIds({
  labelFilter: { labels: ['Document'], mode: 'all' },
  filter: { updatedAt: { gte: startMs, lt: endMs } },
});

// User property literally named "updatedAt":
db.queryNodeIds({
  labelFilter: { labels: ['Document'], mode: 'all' },
  filter: { property: 'updatedAt', eq: 'manual-value' },
});
```

**Python**
```python
# Built-in node timestamp:
db.query_node_ids({
    "label_filter": {"labels": ["Document"], "mode": "all"},
    "filter": {"updated_at": {"gte": start_ms, "lt": end_ms}},
})

# User property literally named "updated_at":
db.query_node_ids({
    "label_filter": {"labels": ["Document"], "mode": "all"},
    "filter": {"property": "updated_at", "eq": "manual-value"},
})
```

---

#### EdgeQuery

Direct edge query request fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| label | `Option<String>` | `label?: string` | `label?: str` | Optional edge-label constraint. |
| ids | `Vec<u64>` | `ids?: number[]` | `ids?: list[int]` | Explicit edge ID candidates. OR within the list. |
| from_ids | `Vec<u64>` | `fromIds?: number[]` | `from_ids?: list[int]` | Source endpoint candidates. OR within the list. |
| to_ids | `Vec<u64>` | `toIds?: number[]` | `to_ids?: list[int]` | Target endpoint candidates. OR within the list. |
| endpoint_ids | `Vec<u64>` | `endpointIds?: number[]` | `endpoint_ids?: list[int]` | Either-endpoint candidates. OR within the list. |
| filter | `Option<EdgeFilterExpr>` | `filter?: QueryEdgeFilter \| null` | `filter?: QueryEdgeFilter \| None` | Recursive edge filter tree. |
| limit | `page.limit` | `limit?: number` | `limit?: int` | Page size. Omit for unlimited. Connector `0` means unlimited. |
| after | `page.after` | `after?: number` | `after?: int` | Cursor from a previous page. Returns edge IDs strictly greater than `after`. |
| allow_full_scan | `bool` | `allowFullScan?: boolean` | `allow_full_scan?: bool` | Required for direct filter-only or unanchored full scans. |

Top-level edge anchors are ANDed with `filter`; values inside each list are ORed. A filter-only
direct edge query requires explicit full-scan opt-in even when metadata sidecars are available.

---

#### EdgeFilter / QueryEdgeFilter

Rust uses `EdgeFilterExpr`. Node.js and Python use the canonical recursive `QueryEdgeFilter`
object shape.

| Filter shape | Node.js | Python | Meaning |
|--------------|---------|--------|---------|
| Equality | `{ property: "role", eq: "lead" }` | `{"property": "role", "eq": "lead"}` | Edge property exactly equals value |
| IN | `{ property: "role", in: ["lead", "owner"] }` | `{"property": "role", "in": ["lead", "owner"]}` | Edge property equals any listed value |
| Range | `{ property: "score", gte: 50 }` | `{"property": "score", "gte": 50}` | Edge property range comparison |
| Exists | `{ property: "role", exists: true }` | `{"property": "role", "exists": True}` | Edge property key is present |
| Missing | `{ property: "role", missing: true }` | `{"property": "role", "missing": True}` | Edge property key is absent |
| Weight range | `{ weight: { gte: 1.0 } }` | `{"weight": {"gte": 1.0}}` | Built-in edge weight range |
| Updated-at range | `{ updatedAt: { gte: ms } }` | `{"updated_at": {"gte": ms}}` | Built-in edge update timestamp range |
| Valid-at | `{ validAt: ms }` | `{"valid_at": ms}` | Half-open validity check: `valid_from <= ms < valid_to` |
| Valid-from range | `{ validFrom: { gte: ms } }` | `{"valid_from": {"gte": ms}}` | Built-in `valid_from` range |
| Valid-to range | `{ validTo: { gt: ms } }` | `{"valid_to": {"gt": ms}}` | Built-in `valid_to` range |
| AND | `{ and: [filter, ...] }` | `{"and": [filter, ...]}` | All children must match |
| OR | `{ or: [filter, ...] }` | `{"or": [filter, ...]}` | Any child may match |
| NOT | `{ not: filter }` | `{"not": filter}` | Child must not match |

Weight ranges reject NaN. `-0.0` and `+0.0` compare as the same value. Ready edge-property
declarations may provide equality, `IN`, and range candidate sources for edge-label-scoped edge filters;
metadata filters may use private edge metadata sources when available. All edge filters still run
final verification for correctness.

---

#### GraphRowQuery

`GraphRowQuery` is the public structured row-query request. It is exported by Rust and accepted by
the Node.js and Python connectors as host-language objects/dicts.

Top-level request fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| nodes | `nodes: Vec<GraphNodePattern>` | `nodes?: GraphRowNodePattern[]` | `"nodes": list[dict]` | Node aliases and node constraints. |
| pieces | `pieces: Vec<GraphPatternPiece>` | `pieces?: GraphRowPatternPiece[]` | `"pieces": list[dict]` | Fixed edge pieces, optional groups, and bounded variable-length path pieces. |
| where | `where_: Option<GraphExpr>` | `where?: GraphExpr` | `"where": GraphExpr` | Row-level residual predicate with null semantics. |
| returns | `return_items: Option<Vec<GraphReturnItem>>` | `return?: GraphReturnItem[]` | `"return": list[dict]` | Output columns. Omitted means `RETURN *` over visible aliases. |
| order | `order_by: Vec<GraphOrderItem>` | `orderBy?: GraphOrderItem[]` | `"order_by": list[dict]` | Final-row ordering. Omitted uses stable logical row-key order. |
| page | `page: GraphPageRequest` | `skip`, `limit`, `cursor` | `skip`, `limit`, `cursor` | Final-row skip/limit/cursor. Native graph-row `limit` must be greater than zero. |
| at epoch | `at_epoch: Option<i64>` | `atEpoch?: number` | `at_epoch?: int` | Temporal edge visibility timestamp. Omitted resolves an effective epoch for the operation. |
| params | `params: BTreeMap<String, GraphParamValue>` | `params?: Record<string, GraphParamValue>` | `"params": dict` | Named values referenced by `GraphExpr::Param`. |
| output | `output: GraphOutputOptions` | `output?: GraphOutputOptions` | `"output": dict` | Output mode, compact rows, and vector inclusion. |
| options | `options: GraphQueryOptions` | `options?: GraphQueryOptions` | `"options": dict` | Validation, safety caps, plan/profile options. |

Node pattern fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| alias | `alias` | `alias` | `alias` | Unique node alias. |
| label filter | `label_filter` | `labelFilter` | `label_filter` | Optional `NodeLabelFilter` with `Any` / `All` semantics. |
| IDs | `ids` | `ids` | `ids` | Explicit node ID candidates. |
| Keys | `keys` | `keys` | `keys` | Label-scoped key candidates. Node.js accepts strings or `{ label, key }`; Python accepts strings or dicts. Node.js string shorthand requires a single-label `labelFilter`; Python string shorthand requires `label_filter` with exactly one `all`-mode label. Use explicit label/key objects or dicts otherwise. |
| filter | `filter` | `filter` | `filter` | Recursive node filter tree. |

Pattern pieces:

| Piece | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| Fixed edge | `GraphPatternPiece::Edge(GraphEdgePattern)` | `{ kind: 'edge', ... }` | `{"kind": "edge", ...}` | Binds or constrains one edge between two node aliases. |
| Optional group | `GraphPatternPiece::Optional(GraphOptionalGroup)` | `{ kind: 'optional', pieces, where? }` | `{"kind": "optional", "pieces": [...], "where": ...}` | Left-outer optional group. On miss, aliases introduced by the group are null. |
| Variable-length path | `GraphPatternPiece::VariableLength(GraphVariableLengthPattern)` | `{ kind: 'variableLength', ... }` | `{"kind": "variable_length", ...}` | Bounded path with `minHops`/`maxHops` or `min_hops`/`max_hops`. |

Fixed edge and variable-length pieces share these fields:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| edge alias | `alias` / `edge_alias` | `alias` / `edgeAlias` | `alias` / `edge_alias` | Fixed edge alias, or one-hop VLP edge alias. Multi-hop VLP edge aliases are rejected. |
| path alias | `path_alias` | `pathAlias` | `path_alias` | Optional path alias for variable-length pieces. |
| endpoints | `from_alias`, `to_alias` | `fromAlias`, `toAlias` | `from`/`from_alias`, `to`/`to_alias` | Node aliases at each end of the piece. |
| direction | `direction` | `direction` | `direction` | `outgoing`, `incoming`, or `both`; defaults to outgoing in connectors. |
| labels | `label_filter` | `labelFilter` | `labels` or `label_filter` | Edge-label list. |
| filter | `filter` | `filter` | `filter` | Recursive edge filter tree. |
| hops | `min_hops`, `max_hops` | `minHops`, `maxHops` | `min_hops`, `max_hops` | Required for variable-length pieces. Must be finite and within caps. |

Graph expressions:

| Expression | Rust | Node.js | Python |
|------------|------|---------|--------|
| Literal null/bool/number/string | `GraphExpr::Null`, etc. | `null`, booleans, numbers, strings | `None`, booleans, numbers, strings |
| Bytes | `GraphExpr::Bytes` | `{ bytes: number[] }` | `{"bytes": [0, 1]}` or Python `bytes` for params |
| List | `GraphExpr::List` | `{ list: [...] }` | `{"list": [...]}` |
| Map | `GraphExpr::Map` | `{ map: { key: expr } }` | `{"map": {"key": expr}}` |
| Param | `GraphExpr::Param("name")` | `{ param: 'name' }` | `{"param": "name"}` |
| Binding | `GraphExpr::Binding("alias")` | `{ binding: 'alias' }` | `{"binding": "alias"}` |
| Property | `GraphExpr::Property { alias, key }` | `{ property: { alias, key } }` | `{"property": {"alias": alias, "key": key}}` |
| Node field | `GraphExpr::NodeField` | `{ nodeField: { alias, field } }` | `{"node_field": {"alias": alias, "field": field}}` |
| Edge field | `GraphExpr::EdgeField` | `{ edgeField: { alias, field } }` | `{"edge_field": {"alias": alias, "field": field}}` |
| Path field | `GraphExpr::PathField` | `{ pathField: { alias, field } }` | `{"path_field": {"alias": alias, "field": field}}` |
| Function | `GraphExpr::Function` | `{ fn: 'id', args: [...] }` | `{"fn": "id", "args": [...]}` |
| Binary op | `GraphExpr::Binary` | `{ op: '=', left, right }` | `{"op": "=", "left": ..., "right": ...}` |
| Not | `GraphExpr::Unary` | `{ op: 'not', expr }` | `{"op": "not", "expr": ...}` |
| Null tests | `GraphExpr::IsNull` / `IsNotNull` | `{ isNull: expr }` / `{ isNotNull: expr }` | `{"is_null": expr}` / `{"is_not_null": expr}` |

Supported node fields are `id`, `labels`, `key`, `weight`, `created_at`/`createdAt`, and
`updated_at`/`updatedAt`. Supported edge fields are `id`, `from`, `to`, `label`/`type`, `weight`,
`created_at`/`createdAt`, `updated_at`/`updatedAt`, `valid_from`/`validFrom`, and
`valid_to`/`validTo`. Supported path fields are `node_ids`/`nodeIds`, `edge_ids`/`edgeIds`, and
`length`.

Supported native function names are `id`, `labels`, `type`, `length`, `nodes`, and
`relationships`; Rust names the path endpoint functions `start_node` and `end_node`. Node.js accepts
`startNode`/`endNode` and also accepts snake_case `start_node`/`end_node`. Python accepts
`start_node`/`end_node`.

Rust uses `GraphExpr::PathField` for `node_ids` and `edge_ids`. Node.js accepts `nodeIds`,
`node_ids`, `edgeIds`, and `edge_ids` in the `fn` tag as connector conveniences. Python accepts
`node_ids` and `edge_ids` in the `fn` tag. These conveniences parse into path-field expressions and
require a direct path binding argument.

Binary ops are `or`, `and`, equality (`=`, `==`, `eq`), inequality (`<>`, `!=`, `neq`), comparisons
(`<`, `<=`, `>`, `>=`), and `in`. Node.js also accepts comparison aliases `lt`, `lte`, `gt`, and
`gte`.

Output options:

| Field | Rust | Node.js | Python | Default | Description |
|-------|------|---------|--------|---------|-------------|
| mode | `GraphOutputMode` | `mode: 'ids' \| 'elements' \| 'projected'` | `"mode": "ids" \| "elements" \| "projected"` | `ids` | Default projection mode for `auto` return items. |
| compact rows | `compact_rows` | `compactRows` | `compact_rows` | `false` | Connector rows become arrays instead of objects. |
| include vectors | `include_vectors` | `includeVectors` | `include_vectors` | `false` | Include dense/sparse vectors in full hydrated node values. |

Graph-row caps:

| Field | Rust | Node.js | Python | Default |
|-------|------|---------|--------|---------|
| allow full scan | `allow_full_scan` | `allowFullScan` | `allow_full_scan` | `false` |
| max intermediate bindings | `max_intermediate_bindings` | `maxIntermediateBindings` | `max_intermediate_bindings` | `65536` |
| max frontier | `max_frontier` | `maxFrontier` | `max_frontier` | `65536` |
| max path hops | `max_path_hops` | `maxPathHops` | `max_path_hops` | `16` |
| max paths per start | `max_paths_per_start` | `maxPathsPerStart` | `max_paths_per_start` | `4096` |
| max page limit | `max_page_limit` | `maxPageLimit` | `max_page_limit` | `10000` |
| max order materialization | `max_order_materialization` | `maxOrderMaterialization` | `max_order_materialization` | `65536` |
| max cursor bytes | `max_cursor_bytes` | `maxCursorBytes` | `max_cursor_bytes` | `16384` |
| max query bytes | `max_query_bytes` | `maxQueryBytes` | `max_query_bytes` | `1048576` |
| include plan | `include_plan` | `includePlan` | `include_plan` | `false` |
| profile | `profile` | `profile` | `profile` | `false` |

Native graph-row cursors are final-row cursors over `(order atoms, logical row key)`. They validate
the normalized query fingerprint and are not physical frontier cursors or pinned storage snapshots.
When `at_epoch` is omitted, the engine resolves an effective epoch for the first page and stores it
in the cursor.

---

#### QueryPlan

Explain APIs return:

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| kind | `kind` | `kind` | `kind` | `node_query` or `edge_query`. Graph-row explain uses `GraphRowExplain`, not `QueryPlan`. |
| root | `root` | `root` | `root` | Recursive plan node. |
| estimated candidates | `estimated_candidates` | `estimatedCandidates` | `estimated_candidates` | Optional candidate count estimate. |
| warnings | `warnings` | `warnings` | `warnings` | Stable lower_snake warning strings. |
| notes | `notes` | `notes` | `notes` | Stable lower_snake informational planner notes. |
| public inputs | `public_inputs` | `publicInputs` | `public_inputs` | Normalized public node-label and edge-label names referenced during planning. |

Plan node kinds include:

| Plan node kind | Meaning |
|----------------|---------|
| `empty_result` | Impossible filter or empty candidate universe. |
| `explicit_ids` | Explicit ID candidate universe. |
| `key_lookup` | Label-scoped key lookup. |
| `node_label_index` | Label index candidate source. |
| `node_label_any_index` | Node-label `Any` candidate source. |
| `property_equality_index` | Ready equality property index candidate source. |
| `property_range_index` | Ready range property index candidate source. |
| `timestamp_index` | Built-in timestamp index candidate source. |
| `explicit_edge_ids` | Explicit edge ID candidate universe. |
| `edge_label_index` | Edge label index candidate source. |
| `edge_triple_index` | Exact `(from, to, label)` edge lookup source. |
| `edge_endpoint_adjacency` | Endpoint adjacency candidate source. |
| `edge_weight_index` | Optional edge weight sidecar candidate source. |
| `edge_updated_at_index` | Optional edge update-time sidecar candidate source. |
| `edge_validity_index` | Optional edge validity sidecar candidate source. |
| `edge_metadata_scan` | Edge metadata scan candidate source. |
| `edge_property_equality_index` | Ready edge-property equality declaration candidate source. |
| `edge_property_range_index` | Ready edge-property range declaration candidate source. |
| `intersect` | Sorted intersection of bounded candidate sources. |
| `union` | Sorted union of bounded OR/IN candidate sources. |
| `verify_node_filter` | Final visible-record verification of the full node filter. |
| `verify_edge_filter` | Final visible-edge metadata/property verification. |
| `adjacency_expansion` | Bounded adjacency expansion used by planner-backed edge candidates. |
| `verify_edge_predicates` | Edge post-filter verification. |
| `fallback_node_label_scan` | Label-scoped scan universe. |
| `fallback_full_node_scan` | Explicit full node scan universe. |
| `fallback_edge_label_scan` | Edge-label-scoped edge scan universe. |
| `fallback_full_edge_scan` | Explicit full edge scan universe. |

Warning strings include:

| Warning | Meaning |
|---------|---------|
| `missing_ready_index` | Needed index is absent, not ready, or unavailable. |
| `using_fallback_scan` | Query used a scan universe. |
| `full_scan_requires_opt_in` | Query would need a full scan but the caller did not opt in. |
| `full_scan_explicitly_allowed` | Full scan ran because caller opted in. |
| `edge_property_post_filter` | Edge properties were checked after bounded expansion. |
| `index_skipped_as_broad` | Ready index existed but was skipped as too broad. |
| `candidate_cap_exceeded` | Candidate cap prevented materializing a source. |
| `range_candidate_cap_exceeded` | Range candidate cap prevented bounded range materialization. |
| `timestamp_candidate_cap_exceeded` | Timestamp candidate cap prevented bounded timestamp materialization. |
| `verify_only_filter` | Some filter subtree ran only through verification. |
| `boolean_branch_fallback` | Boolean branch or OR was cheaper or safer as verifier fallback. |
| `planning_probe_budget_exceeded` | Planning probe/union budget forced fallback. |
| `unknown_node_label` | A requested node label is not present in the catalog. |
| `unknown_edge_label` | A requested edge label is not present in the catalog. |

Note strings include:

| Note | Meaning |
|------|---------|
| `node_label_any_dedupe_before_pagination` | `Any` node-label planning deduplicates candidates before pagination. |
| `node_label_any_final_verification` | `Any` node-label results are verified against final visible node records. |
| `node_label_all_superset_verification` | `All` node-label planning used a superset index source followed by final verification. |
| `stale_node_label_membership_verification` | Node-label index membership may include stale entries and is verified against visible records. |

---

#### Validation notes

Invalid filter shapes:

| Invalid shape | Why |
|---------------|-----|
| `{}` | Empty filter object is not a valid filter. |
| `{ and: [] }` | `and` must contain at least one child. |
| `{ or: [] }` | `or` must contain at least one child. |
| `{ not: null }` | `not` must contain exactly one filter object. |
| `{ AND: [...] }` | Uppercase boolean aliases are not supported. |
| `{ property: "", eq: "active" }` | Property key must be non-empty. |
| `{ eq: "active" }` | Property leaves require `property`. |
| `{ property: "status" }` | Property leaf must specify one operator family. |
| `{ property: "status", eq: "active", in: ["active"] }` | Mixed operator families are invalid. |
| `{ property: "status", in: [] }` | `in` list must be non-empty. |
| `{ property: "x", exists: false }` | `exists` only accepts true; use `missing: true` for the opposite. |
| `{ property: "x", missing: false }` | `missing` only accepts true; use `exists: true` for the opposite. |
| `{ property: "score", gt: 1, gte: 1 }` | Cannot specify both exclusive and inclusive lower bounds. |
| `{ updatedAt: { eq: 123 } }` | Updated-at filters support range bounds only. |

`filter` omitted/null/undefined/None means no node filter. `filter: {}` is invalid.

Boolean objects cannot contain sibling tags. For example, `{ and: [...], or: [...] }` and
`{ and: [...], property: "x", eq: 1 }` are invalid. No uppercase boolean or operator aliases are
accepted.

---

## Pagination

All paginated methods use **keyset (cursor-based) pagination**, not offset-based. This provides stable results even when data is inserted between pages.

The pattern is the same across all paginated methods:
- Pass `limit` for the page size and `after` as the cursor.
- Most paginated methods use an ID cursor.
- `find_nodes_range_paged` uses a structured range cursor keyed by `(value, node_id)`.
- The result includes `items` and `next_cursor` (`None`/`null` when there are no more pages).

### nodes_by_labels_paged

Paginated node-label scan. Returns IDs only.

```rust
let page = db.nodes_by_labels_paged("User", &PageRequest { limit: Some(100), after: None })?;
let admin_page = db.nodes_by_labels_paged(
    vec!["User".into(), "Admin".into()],
    &PageRequest { limit: Some(100), after: None },
)?;
// page.items: Vec<u64>, page.next_cursor: Option<u64>
```

```javascript
let page = db.nodesByLabelsPaged('User', 100); // limit=100, no cursor
let adminPage = db.nodesByLabelsPaged(['User', 'Admin'], 100);
// page = { items: Float64Array, nextCursor: number | null }

// Next page:
page = db.nodesByLabelsPaged('User', 100, page.nextCursor);
```

```python
page = db.nodes_by_labels_paged("User", limit=100)
admin_page = db.nodes_by_labels_paged(["User", "Admin"], limit=100)
# page.items: IdArray, page.next_cursor: int | None

# Next page:
page = db.nodes_by_labels_paged("User", limit=100, after=page.next_cursor)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| labels | `impl IntoNodeLabels` | `string \| string[]` | `str \| list[str]` | Yes | — | Label or labels to match. Nodes must contain every supplied node label. |
| limit | `Option<usize>` | `number` | `int` | No | Unlimited | Maximum items per page. |
| after | `Option<u64>` | `number` | `int` | No | `None` (start from beginning) | Cursor. Returns items with IDs strictly greater than this value. Use `next_cursor` from a previous result. |

#### Returns: PageResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `Vec<u64>` | `Float64Array` | `IdArray` | IDs in this page. |
| next_cursor | `Option<u64>` | `number \| null` | `int \| None` | Cursor for the next page. `None`/`null` means this is the last page. |

---

### edges_by_label_paged

Paginated edge-label scan. Returns edge IDs only.

```rust
let page = db.edges_by_label_paged(
    "WORKS_ON",
    &PageRequest { limit: Some(100), after: None },
)?;
// page.items: Vec<u64>, page.next_cursor: Option<u64>
```

```javascript
let page = db.edgesByLabelPaged('WORKS_ON', 100); // limit=100, no cursor
// page = { items: Float64Array, nextCursor: number | null }

// Next page:
page = db.edgesByLabelPaged('WORKS_ON', 100, page.nextCursor);
```

```python
page = db.edges_by_label_paged("WORKS_ON", limit=100)
# page.items: IdArray, page.next_cursor: int | None

# Next page:
page = db.edges_by_label_paged("WORKS_ON", limit=100, after=page.next_cursor)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| label | `&str` | `string` | `str` | Yes | - | Public edge label to match. |
| limit | `Option<usize>` | `number` | `int` | No | Unlimited | Maximum edge IDs per page. |
| after | `Option<u64>` | `number` | `int` | No | `None` (start from beginning) | Cursor. Returns edge IDs strictly greater than this value. Use `next_cursor` from a previous result. |

#### Returns: PageResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `Vec<u64>` | `Float64Array` | `IdArray` | Edge IDs in this page. |
| next_cursor | `Option<u64>` | `number \| null` | `int \| None` | Cursor for the next page. `None`/`null` means this is the last page. |

Unknown edge labels return an empty page. Tombstoned edges are excluded. Paged edge-label scans are ordered by edge ID.

---

### get_nodes_by_labels_paged

Paginated hydrated node-label scan. Returns full node records.

```rust
let page = db.get_nodes_by_labels_paged("User", &PageRequest { limit: Some(50), after: None })?;
let admin_page = db.get_nodes_by_labels_paged(
    vec!["User".into(), "Admin".into()],
    &PageRequest { limit: Some(50), after: None },
)?;
// page.items: Vec<NodeView>
```

```javascript
const page = db.getNodesByLabelsPaged('User', 50);
const adminPage = db.getNodesByLabelsPaged(['User', 'Admin'], 50);
// page.items: NodeView[]
```

```python
page = db.get_nodes_by_labels_paged("User", limit=50)
admin_page = db.get_nodes_by_labels_paged(["User", "Admin"], limit=50)
# page.items: list[NodeView]
```

---

### get_edges_by_label_paged

Paginated hydrated edge-label scan. Returns full edge records.

```rust
let page = db.get_edges_by_label_paged(
    "WORKS_ON",
    &PageRequest { limit: Some(50), after: None },
)?;
// page.items: Vec<EdgeView>
```

```javascript
const page = db.getEdgesByLabelPaged('WORKS_ON', 50);
// page.items: EdgeView[]
```

```python
page = db.get_edges_by_label_paged("WORKS_ON", limit=50)
# page.items: list[EdgeView]
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| label | `&str` | `string` | `str` | Yes | - | Public edge label to match. |
| limit | `Option<usize>` | `number` | `int` | No | Unlimited | Maximum edge records per page. |
| after | `Option<u64>` | `number` | `int` | No | `None` (start from beginning) | Cursor. Returns edge records with IDs strictly greater than this value. Use `next_cursor` from a previous result. |

#### Returns: PageResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `Vec<EdgeView>` | `EdgeView[]` | `list[EdgeView]` | Full edge records in this page. |
| next_cursor | `Option<u64>` | `number \| null` | `int \| None` | Cursor for the next page. `None`/`null` means this is the last page. |

Unknown edge labels return an empty page. Tombstoned edges are excluded. The implementation pages IDs first and hydrates only the requested page.

---

### find_nodes_paged

Paginated version of [`find_nodes`](#find_nodes).

```rust
let page = db.find_nodes_paged(
    "User",
    "role",
    &PropValue::String("admin".into()),
    &PageRequest { limit: Some(50), after: None },
)?;
```

```javascript
const page = db.findNodesPaged('User', 'role', 'admin', { limit: 50 });
```

```python
page = db.find_nodes_paged("User", "role", "admin", limit=50)
```

---

### find_nodes_range_paged

Paginated version of [`find_nodes_range`](#find_nodes_range).

**Rust**
```rust
let page = db.find_nodes_range_paged(
    "User",
    "score",
    Some(&PropertyRangeBound::Included(PropValue::Int(10))),
    Some(&PropertyRangeBound::Excluded(PropValue::Float(20.0))),
    &PropertyRangePageRequest {
        limit: Some(50),
        after: None,
    },
)?;
```

**Node.js**
```javascript
const page = db.findNodesRangePaged(
  'User',
  'score',
  { value: 10, inclusive: true, domain: 'int' },
  { value: 20, inclusive: false, domain: 'float' },
  { limit: 50 },
);
```

**Python**
```python
page = db.find_nodes_range_paged(
    "User",
    "score",
    PropertyRangeBound(10, domain="int"),
    PropertyRangeBound(20.0, inclusive=False, domain="float"),
    limit=50,
)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| label | `&str` | `string` | `str` | Yes | — | Restrict search to this node label. |
| prop_key | `&str` | `string` | `str` | Yes | — | Numeric property key to query. |
| lower | `Option<&PropertyRangeBound>` | `PropertyRangeBound \| null \| undefined` | `PropertyRangeBound \| None` | No | Unbounded | Lower bound. |
| upper | `Option<&PropertyRangeBound>` | `PropertyRangeBound \| null \| undefined` | `PropertyRangeBound \| None` | No | Unbounded | Upper bound. |
| limit | `Option<usize>` | `number` | `int` | No | Unlimited | Maximum items per page. |
| after | `Option<PropertyRangeCursor>` | `PropertyRangeCursor` | `PropertyRangeCursor` | No | `None` | Cursor from a previous range page. Reuse the same query arguments when resuming. |

#### Returns: PropertyRangePageResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| items | `Vec<u64>` | `Float64Array` | `IdArray` | Node IDs in range order for this page. |
| next_cursor | `Option<PropertyRangeCursor>` | `PropertyRangeCursor \| null \| undefined` | `PropertyRangeCursor \| None` | Cursor for the next page, or no cursor on the last page. |

#### Behavior

- At least one finite numeric bound is required.
- Bounds and cursors may mix signed integer, unsigned integer, and finite float values.
- Empty finite numeric intervals return an empty page.
- Non-finite floats, non-numeric values, arrays, and maps are invalid bounds or cursors.
- When resuming with `after`, keep the same `label`, `prop_key`, and bounds.
- Invalid bound or cursor combinations return an error.

---

### find_nodes_by_time_range_paged

Paginated version of [`find_nodes_by_time_range`](#find_nodes_by_time_range).

```javascript
const page = db.findNodesByTimeRangePaged('User', startMs, endMs, { limit: 50 });
```

```python
page = db.find_nodes_by_time_range_paged("User", start_ms, end_ms, limit=50)
```

---

## Traversal

### neighbors

Retrieves the immediate neighbors of a node (one hop). The most common graph traversal operation.

**Rust**
```rust
let entries = db.neighbors(node_id, &NeighborOptions {
    direction: Direction::Outgoing,
    edge_label_filter: Some(vec!["WORKS_ON".into()]),
    limit: Some(10),
    at_epoch: None,
    decay_lambda: None,
})?;

for entry in &entries {
    println!("neighbor={}, edge={}, weight={}", entry.node_id, entry.edge_id, entry.weight);
}
```

**Node.js**
```javascript
const list = db.neighbors(nodeId, {
  direction: 'outgoing',
  edgeLabelFilter: ['WORKS_ON'],
  limit: 10,
});

for (const n of list) {
  console.log(n.nodeId, n.edgeId, n.weight);
}
```

**Python**
```python
entries = db.neighbors(node_id, direction="outgoing", edge_label_filter=["WORKS_ON"], limit=10)
for entry in entries:
    print(entry.node_id, entry.edge_id, entry.weight)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| node_id | `u64` | `number` | `int` | Yes | — | Node to query neighbors for. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Traversal direction. `"outgoing"`, `"incoming"`, or `"both"`. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` (all labels) | Only return neighbors connected by edges with these labels. |
| limit | `Option<usize>` | `number` | `int` | No | `None` (unlimited) | Maximum number of neighbors to return. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` (current time) | Temporal filter. Only edges whose validity window contains this timestamp are included. `None` means the current wall-clock time. |
| decay_lambda | `Option<f32>` | `number` | `float` | No | `None` (no decay) | Exponential decay factor. When set, each neighbor's weight is multiplied by `exp(-λ × age_hours)` where `age_hours = max(at_epoch - valid_from, 0) / 3_600_000`. |

#### Returns: NeighborEntry

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| node_id | `u64` | `number` | `int` | ID of the neighboring node. |
| edge_id | `u64` | `number` | `int` | ID of the connecting edge. |
| label | `String` | `label: string` | `label: str` | Label of the connecting edge. |
| weight | `f32` | `number` | `float` | Edge weight (or decay-adjusted score if `decay_lambda` is set). |
| valid_from | `i64` | `number` | `int` | Edge validity start (ms). |
| valid_to | `i64` | `number` | `int` | Edge validity end (ms). |

**Node.js**: Returns `NeighborEntry[]` as plain objects, so you can use normal array access like `list[i].nodeId`.

#### Performance

~294ns for a node with 10 edges, ~2.1μs for 100 edges (memtable hot path).

---

### neighbors_paged

Paginated version of [`neighbors`](#neighbors).

```javascript
let page = db.neighborsPaged(nodeId, { direction: 'outgoing', limit: 20 });
// page.items: NeighborEntry[], page.nextCursor: number | null
console.log(page.items[0].nodeId);

// Next page:
page = db.neighborsPaged(nodeId, { direction: 'outgoing', limit: 20, after: page.nextCursor });
```

```python
page = db.neighbors_paged(node_id, direction="outgoing", limit=20)
# page.items: list[NeighborEntry], page.next_cursor: int | None

page = db.neighbors_paged(node_id, direction="outgoing", limit=20, after=page.next_cursor)
```

#### Additional Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| limit | `usize` / `number` / `int` | No | Unlimited | Page size. |
| after | `u64` / `number` / `int` | No | `None` | Cursor (edge ID) for the next page. |

---

### neighbors_batch

Batch-queries neighbors for multiple nodes in a single call. More efficient than calling `neighbors` in a loop.

**Rust**
```rust
let results = db.neighbors_batch(&[1, 2, 3], &NeighborOptions::default())?;
// results: NodeIdMap<Vec<NeighborEntry>> - map from node_id to its neighbors
```

**Node.js**
```javascript
const results = db.neighborsBatch([1, 2, 3], { direction: 'outgoing' });
// results: { queryNodeId: number, neighbors: NeighborEntry[] }[]
console.log(results[0].neighbors[0].nodeId);
```

**Python**
```python
results = db.neighbors_batch([1, 2, 3], direction="outgoing")
# results: dict[int, list[NeighborEntry]]
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| node_ids | `&[u64]` | `number[]` | `list[int]` | Yes | Node IDs to query neighbors for. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Traversal direction. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Edge label filter. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |
| decay_lambda | `Option<f32>` | `number` | `float` | No | `None` | Decay factor. Uses hours from `valid_from` when set. |

#### Returns

A map/array mapping each query node ID to its list of neighbors.

---

### top_k_neighbors

Returns the top K neighbors of a node ranked by a scoring criterion.

**Rust**
```rust
let top = db.top_k_neighbors(node_id, 5, &TopKOptions {
    direction: Direction::Outgoing,
    scoring: ScoringMode::DecayAdjusted { lambda: 0.01 },
    ..Default::default()
})?;
```

**Node.js**
```javascript
const top = db.topKNeighbors(nodeId, 5, {
  direction: 'outgoing',
  scoring: 'decay',
  decayLambda: 0.01,
});
console.log(top[0].nodeId, top[0].weight);
```

**Python**
```python
top = db.top_k_neighbors(
    node_id,
    5,
    direction="outgoing",
    scoring="decay",
    decay_lambda=0.01,
)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| node_id | `u64` | `number` | `int` | Yes | — | Source node. |
| k | `usize` | `number` | `int` | Yes | — | Number of top neighbors to return. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Traversal direction. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Edge label filter. |
| scoring | `ScoringMode` | `string` | `str` | No | `Weight` | Scoring criterion. Rust carries the decay lambda inside `ScoringMode::DecayAdjusted { lambda }`; connectors use `scoring: "decay"` plus `decayLambda` / `decay_lambda`. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |
| decay_lambda | — | `number` | `float` | No | `None` | Connector-only option required when `scoring = "decay"`. |

**Scoring modes:**

| Mode | Rust | Node.js / Python | Description |
|------|------|------------------|-------------|
| Weight | `ScoringMode::Weight` | `"weight"` | Rank by edge weight (descending). |
| Recency | `ScoringMode::Recency` | `"recency"` | Rank by recency. More recent edges score higher. |
| DecayAdjusted | `ScoringMode::DecayAdjusted { lambda }` | `"decay"` | Exponential decay: `weight × exp(-λ × age_hours)`, where `age_hours = max(at_epoch - valid_from, 0) / 3_600_000`. Connectors require `decay_lambda`. |

#### Returns

Array of `NeighborEntry` sorted by score descending. Length is `min(k, actual_neighbor_count)`.

---

### traverse

Breadth-first traversal from a starting node up to a maximum depth. Supports pagination, edge-label filtering, emission-only node-label filtering, temporal filtering, and decay scoring.

**Rust**
```rust
let result = db.traverse(start_id, &TraverseOptions {
    min_depth: 1,
    direction: Direction::Outgoing,
    edge_label_filter: Some(vec!["WORKS_ON".into()]),
    emit_node_label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into(), "Admin".into()],
        mode: LabelMatchMode::Any,
    }),
    at_epoch: None,
    decay_lambda: None,
    limit: Some(100),
    cursor: None,
})?;

for hit in &result.items {
    println!("node={}, depth={}", hit.node_id, hit.depth);
}
```

**Node.js**
```javascript
const result = db.traverse(startId, 3, {
  minDepth: 1,
  direction: 'outgoing',
  edgeLabelFilter: ['WORKS_ON'],
  emitNodeLabelFilter: { labels: ['User', 'Admin'], mode: 'any' },
  limit: 100,
});

for (const hit of result.items) {
  console.log(hit.nodeId, hit.depth, hit.viaEdgeId);
}

// Paginate:
if (result.nextCursor) {
  const page2 = db.traverse(startId, 3, { cursor: result.nextCursor, limit: 100 });
}
```

**Python**
```python
result = db.traverse(start_id, max_depth=3,
    min_depth=1, direction="outgoing",
    edge_label_filter=["WORKS_ON"],
    emit_node_label_filter={"labels": ["User", "Admin"], "mode": "any"},
    limit=100)

for hit in result.items:
    print(hit.node_id, hit.depth, hit.via_edge_id)

# Paginate:
if result.next_cursor:
    page2 = db.traverse(start_id, max_depth=3, cursor=result.next_cursor, limit=100)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| start_node_id | `u64` | `number` | `int` | Yes | — | Starting node for the BFS traversal. |
| max_depth | (part of TraverseOptions in Rust) | `number` | `int` | Yes | — | Maximum number of hops from the start node. `1` = immediate neighbors, `2` = neighbors of neighbors, etc. |
| min_depth | `u32` | `number` | `int` | No | `1` | Minimum depth to include in results. Set to `0` to include the start node itself. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Edge traversal direction. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` (all labels) | Only follow edges with these labels. |
| emit_node_label_filter | `Option<NodeLabelFilter>` | `emitNodeLabelFilter: { labels: string[], mode: "any" \| "all" }` | `emit_node_label_filter: dict` | No | `None` (all labels) | Node-label filter for emitted nodes. Traversal may still pass through non-emitted labels. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter for edge validity. |
| decay_lambda | `Option<f64>` | `number` | `float` | No | `None` | Depth-based traversal score. When set, each hit receives `exp(-λ × depth)`. |
| limit | `Option<usize>` | `number` | `int` | No | `None` (unlimited) | Maximum results per page. Use with `cursor` for pagination. |
| cursor | `Option<TraversalCursor>` | `TraversalCursor` | `TraversalCursor` | No | `None` | Resume traversal from a previous page. |

#### Returns: TraversalHit

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| node_id | `u64` | `number` | `int` | Node reached by the traversal. |
| depth | `u32` | `number` | `int` | Distance (hops) from the start node. |
| via_edge_id | `Option<u64>` | `number \| null` | `int \| None` | Edge ID used to reach this node. `None` for the start node (depth 0). |
| score | `Option<f64>` | `number \| null` | `float \| None` | Decay-adjusted score (only present when `decay_lambda` is set). |

Results are ordered by `(depth ASC, node_id ASC)` with deterministic tie-breaking.

---

### extract_subgraph

Extracts a complete subgraph (all reachable nodes and edges) rooted at a given node.

**Rust**
```rust
let sg = db.extract_subgraph(root_id, 3, &SubgraphOptions {
    direction: Direction::Outgoing,
    edge_label_filter: None,
    node_label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into()],
        mode: LabelMatchMode::Any,
    }),
    at_epoch: None,
})?;
println!("{} nodes, {} edges", sg.nodes.len(), sg.edges.len());
```

**Node.js**
```javascript
const sg = db.extractSubgraph(rootId, 3, {
  direction: 'outgoing',
  nodeLabelFilter: { labels: ['User'], mode: 'any' },
});
console.log(sg.nodes.length, 'nodes,', sg.edges.length, 'edges');
```

**Python**
```python
sg = db.extract_subgraph(
    root_id,
    max_depth=3,
    direction="outgoing",
    node_label_filter={"labels": ["User"], "mode": "any"},
)
print(len(sg.nodes), "nodes,", len(sg.edges), "edges")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| start_node_id | `u64` | `number` | `int` | Yes | — | Root node. |
| max_depth | `u32` | `number` | `int` | Yes | — | Maximum hops from root. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Direction. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Edge label filter. |
| node_label_filter | `Option<NodeLabelFilter>` | `nodeLabelFilter: { labels: string[], mode: "any" \| "all" }` | `node_label_filter: dict` | No | `None` | Node-label filter for nodes to include and expand through. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |

#### Returns: Subgraph

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| nodes | `Vec<NodeView>` | `NodeView[]` | `list[NodeView]` | All nodes in the subgraph (full records). |
| edges | `Vec<EdgeView>` | `EdgeView[]` | `list[EdgeView]` | All edges in the subgraph (full records). |

### shortest_path

Finds the shortest (lowest-cost) path between two nodes.

**Rust**
```rust
let path = db.shortest_path(from_id, to_id, &ShortestPathOptions {
    direction: Direction::Outgoing,
    weight_field: None, // uses edge.weight; set to Some("cost".into()) for property-based cost
    max_depth: Some(10),
    max_cost: Some(100.0),
    ..Default::default()
})?;

if let Some(p) = path {
    println!("path: {:?}, cost: {}", p.nodes, p.total_cost);
}
```

**Node.js**
```javascript
const path = db.shortestPath(fromId, toId, {
  direction: 'outgoing',
  maxDepth: 10,
  maxCost: 100.0,
});

if (path) {
  console.log('nodes:', path.nodes, 'cost:', path.totalCost);
}
```

**Python**
```python
path = db.shortest_path(from_id, to_id, direction="outgoing", max_depth=10, max_cost=100.0)
if path:
    print("nodes:", path.nodes, "cost:", path.total_cost)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| from | `u64` | `number` | `int` | Yes | — | Source node ID. |
| to | `u64` | `number` | `int` | Yes | — | Destination node ID. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Direction to follow edges. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Only traverse these edge labels. |
| weight_field | `Option<String>` | `string` | `str` | No | `None` | Property key on edges to use as cost. When `None`, uses `edge.weight`. When set, reads the named property as the edge cost (must be numeric). |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |
| max_depth | `Option<u32>` | `number` | `int` | No | `None` (unlimited) | Stop searching after this many hops. Prevents runaway searches on deep graphs. |
| max_cost | `Option<f64>` | `number` | `float` | No | `None` (unlimited) | Stop searching when accumulated cost exceeds this threshold. |

#### Algorithm

- When `weight_field` is `None` **and all edge weights are 1.0**: BFS (unweighted shortest path).
- Otherwise: Dijkstra's algorithm (weighted shortest path).

#### Returns: ShortestPath

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| nodes | `Vec<u64>` | `number[]` | `list[int]` | Ordered list of node IDs from source to destination (inclusive). |
| edges | `Vec<u64>` | `number[]` | `list[int]` | Edge IDs along the path. Length = `nodes.length - 1`. |
| cost / total_cost | `f64` | `number` | `float` | Sum of edge costs along the path. |

Returns `None`/`null` if no path exists within the given constraints.

---

### all_shortest_paths

Finds **all** shortest paths (when multiple paths have the same minimum cost).

```rust
let paths = db.all_shortest_paths(from_id, to_id, &AllShortestPathsOptions {
    max_paths: Some(10),
    ..Default::default()
})?;
```

```javascript
const paths = db.allShortestPaths(fromId, toId, { maxPaths: 10 });
```

```python
paths = db.all_shortest_paths(from_id, to_id, max_paths=10)
```

#### Additional Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| max_paths | `Option<usize>` | `number` | `int` | No | `None` (unlimited) | Stop after finding this many paths. Use to prevent combinatorial explosion on highly connected graphs. |

All other parameters are the same as [`shortest_path`](#shortest_path).

#### Returns

Array of `ShortestPath` objects. All paths have the same cost (the minimum). Can be empty if no path exists.

---

### is_connected

Fast reachability check: does any path exist between two nodes? Uses BFS with early termination.

```rust
let connected = db.is_connected(from_id, to_id, &IsConnectedOptions::default())?;
```

```javascript
const connected = db.isConnected(fromId, toId, { direction: 'both', maxDepth: 5 });
```

```python
connected = db.is_connected(from_id, to_id, direction="both", max_depth=5)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| from | `u64` | `number` | `int` | Yes | — | Source node. |
| to | `u64` | `number` | `int` | Yes | — | Destination node. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Direction. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Edge label filter. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |
| max_depth | `Option<u32>` | `number` | `int` | No | `None` | Maximum search depth. |

#### Returns

`bool`. Returns `true` if a path exists, `false` otherwise.

---

## Degree & Weight Aggregation

### degree

Counts the number of edges connected to a node.

```rust
let d = db.degree(node_id, &DegreeOptions::default())?;
```

```javascript
const d = db.degree(nodeId, { direction: 'both' });
```

```python
d = db.degree(node_id, direction="both")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| node_id | `u64` | `number` | `int` | Yes | — | Node to count edges for. |
| direction | `Direction` | `string` | `str` | No | `Outgoing` | Which edges to count. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Only count edges with these labels. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<u32, EngineError>` | `number` | `int` |

The edge count.

#### Performance

Metadata-only fast path for unfiltered, non-temporal queries when all visible segments have valid degree sidecars. O(edges) walk fallback when filtering by edge label, using a temporal epoch, running with active prune policies, reading a node with temporal incident edges, or reading through a segment whose degree sidecar is missing/corrupt.

---

### degrees

Batch degree query for multiple nodes.

```rust
let map = db.degrees(&[1, 2, 3], &DegreeOptions::default())?;
// map: NodeIdMap<u32>
```

```javascript
const entries = db.degrees([1, 2, 3], { direction: 'outgoing' });
// entries: { nodeId: number, degree: number }[]
```

```python
result = db.degrees([1, 2, 3], direction="outgoing")
# result: dict[int, int]
```

---

### sum_edge_weights

Sums the weights of all edges connected to a node.

```rust
let total = db.sum_edge_weights(node_id, &DegreeOptions::default())?;
```

```javascript
const total = db.sumEdgeWeights(nodeId, { direction: 'outgoing' });
```

```python
total = db.sum_edge_weights(node_id, direction="outgoing")
```

Same parameters as [`degree`](#degree). Returns `f64` / `number` / `float`.

---

### avg_edge_weight

Average weight of edges connected to a node.

```rust
let avg = db.avg_edge_weight(node_id, &DegreeOptions::default())?;
```

```javascript
const avg = db.avgEdgeWeight(nodeId); // number | null
```

```python
avg = db.avg_edge_weight(node_id)  # float | None
```

Same parameters as [`degree`](#degree). Returns `None`/`null` if the node has no edges.

---

## Graph Analytics

### connected_components

Computes all [weakly connected components](https://en.wikipedia.org/wiki/Connected_component_(graph_theory)) in the graph. Treats edges as undirected regardless of their actual direction.

**Rust**
```rust
let components = db.connected_components(&ComponentOptions {
    node_label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into()],
        mode: LabelMatchMode::Any,
    }),
    ..Default::default()
})?;
// components: NodeIdMap<u64> - node_id to component_id
```

**Node.js**
```javascript
const entries = db.connectedComponents({
  nodeLabelFilter: { labels: ['User'], mode: 'any' },
});
// entries: { nodeId: number, componentId: number }[]
```

**Python**
```python
components = db.connected_components(node_label_filter={"labels": ["User"], "mode": "any"})
# components: dict[int, int] - node_id to component_id
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Only consider these edge labels when determining connectivity. |
| node_label_filter | `Option<NodeLabelFilter>` | `nodeLabelFilter: { labels: string[], mode: "any" \| "all" }` | `node_label_filter: dict` | No | `None` | Node-label filter for nodes included in components. |
| at_epoch | `Option<i64>` | `number` | `int` | No | `None` | Temporal filter. |

#### Returns

A mapping from every node ID to its component ID. The component ID is the smallest node ID within each component (a canonical representative).

---

### component_of

Returns all nodes in the same connected component as a given node.

```rust
let node_ids = db.component_of(node_id, &ComponentOptions {
    node_label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into()],
        mode: LabelMatchMode::Any,
    }),
    ..Default::default()
})?;
```

```javascript
const nodeIds = db.componentOf(nodeId); // Float64Array
```

```python
node_ids = db.component_of(node_id, node_label_filter={"labels": ["User"], "mode": "any"})  # list[int]
```

#### Parameters

Same as [`connected_components`](#connected_components), plus:

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| node_id | `u64` | `number` | `int` | Yes | Node to find the component for. |

#### Returns

| Rust | Node.js | Python |
|------|---------|--------|
| `Result<Vec<u64>, EngineError>` | `Float64Array` | `list[int]` |

All three surfaces return the sorted node IDs in the same connected component as the requested node.

---

### personalized_pagerank

Computes [Personalized PageRank](https://en.wikipedia.org/wiki/PageRank#Personalized_PageRank) from one or more seed nodes. Useful for recommendation, influence scoring, and relevance ranking.

OverGraph exposes two PPR algorithms:
- `exact` / `ExactPowerIteration` (default): reference implementation using power iteration.
- `approx` / `ApproxForwardPush`: local forward-push approximation, usually much faster for seed-centric retrieval workloads.

**Rust**
```rust
let result = db.personalized_pagerank(&[seed_id], &PprOptions {
    algorithm: PprAlgorithm::ApproxForwardPush,
    approx_residual_tolerance: 1e-5,
    max_results: Some(50),
    ..Default::default()
})?;
```

**Node.js**
```javascript
const result = db.personalizedPagerank([seedId], {
  algorithm: 'approx',
  approxResidualTolerance: 1e-5,
  maxResults: 50,
});

console.log('algorithm:', result.algorithm);
for (let i = 0; i < result.nodeIds.length; i++) {
  console.log(result.nodeIds[i], result.scores[i]);
}
```

**Python**
```python
result = db.personalized_pagerank([seed_id],
    algorithm="approx",
    approx_residual_tolerance=1e-5,
    max_results=50)

print("algorithm:", result.algorithm)
for nid, score in zip(result.node_ids, result.scores):
    print(nid, score)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| seed_node_ids | `Vec<u64>` | `number[]` | `list[int]` | Yes | — | Seed nodes. The random walk teleports back to these nodes with probability `1 - damping_factor`. Multiple seeds distribute the teleport probability evenly. |
| algorithm | `PprAlgorithm` | `string` | `str` | No | `ExactPowerIteration` / `"exact"` | PPR algorithm. Rust accepts `ExactPowerIteration` or `ApproxForwardPush`. Node/Python accept `"exact"` or `"approx"`. |
| damping_factor | `f64` | `number` | `float` | No | `0.85` | Probability of following an edge (vs. teleporting back to a seed). Standard PageRank uses 0.85. Higher values explore further from seeds; lower values stay closer. |
| max_iterations | `u32` | `number` | `int` | No | `20` | Maximum power iterations for exact mode. The algorithm stops when it converges or reaches this limit. |
| epsilon | `f64` | `number` | `float` | No | `1e-6` | Convergence threshold. Iteration stops when the L1 norm of the score change vector drops below this value. |
| approx_residual_tolerance | `f64` | `number` | `float` | No | `1e-5` | Approximate-mode stopping tolerance for forward push. Smaller values improve fidelity and increase work. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Only follow these edge labels during the walk. |
| max_results | `Option<usize>` | `number` | `int` | No | `None` (all) | Return only the top N nodes by score. |

#### Returns: PprResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| scores | `Vec<(u64, f64)>` | — | — | Rust scored node pairs sorted by score descending. |
| node IDs | — | `nodeIds: Float64Array` | `node_ids: list[int]` | Connector node IDs sorted by score descending. |
| scores | — | `scores: Float64Array` | `scores: list[float]` | Connector scores corresponding to node IDs. Exact PPR sums to 1.0 (or very close); approximate PPR is optimized for ranking quality rather than strict normalization. |
| iterations | `u32` | `number` | `int` | Number of exact power iterations performed. Approximate mode returns `0`. |
| converged | `bool` | `boolean` | `bool` | Exact mode: whether the algorithm converged within `max_iterations`. Approximate mode: `true` when no node remains above the residual tolerance. |
| algorithm | `PprAlgorithm` | `string` | `str` | Which algorithm produced the result. |
| approx | `Option<PprApproxMeta>` | `PprApproxMeta \| null` | `PprApproxMeta \| None` | Approximate-mode metadata. `None`/`null` in exact mode. |

---

### export_adjacency

Exports the graph's adjacency structure as flat arrays. Useful for bulk analysis, NetworkX integration, or external graph processing.

**Rust**
```rust
let export = db.export_adjacency(&ExportOptions {
    node_label_filter: Some(NodeLabelFilter {
        labels: vec!["User".into(), "Admin".into()],
        mode: LabelMatchMode::Any,
    }),
    include_weights: true,
    ..Default::default()
})?;
println!("node label side table: {:?}", export.node_labels);
println!("per-node label indexes: {:?}", export.node_label_indexes);
```

**Node.js**
```javascript
const adj = db.exportAdjacency({
  nodeLabelFilter: { labels: ['User', 'Admin'], mode: 'any' },
  includeWeights: true,
});
// adj.nodeIds: Float64Array
// adj.edgeLabels: string[]
// adj.edgeFrom: Float64Array
// adj.edgeTo: Float64Array
// adj.edgeLabelIndexes: Uint32Array
// adj.edgeWeights: Float64Array | undefined
```

**Python**
```python
adj = db.export_adjacency(
    node_label_filter={"labels": ["User", "Admin"], "mode": "any"},
    include_weights=True,
)
# adj.node_ids: list[int]
# adj.node_labels: list[str]
# adj.node_label_indexes: list[list[int]]
# adj.edge_labels: list[str]
# adj.edges: list[ExportEdge] - each has from_id, to_id, edge_label_index, weight
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| node_label_filter | `Option<NodeLabelFilter>` | `nodeLabelFilter: { labels: string[], mode: "any" \| "all" }` | `node_label_filter: dict` | No | `None` | Node-label filter for exported nodes. |
| edge_label_filter | `Option<Vec<String>>` | `edgeLabelFilter: string[]` | `edge_label_filter: list[str]` | No | `None` | Only export edges with these labels. |
| include_weights | `bool` | `boolean` | `bool` | No | `true` | Include edge weights in the export. Set to `false` to save memory/bandwidth when weights aren't needed. |

#### Returns: AdjacencyExport

Rust:

| Field | Type | Description |
|-------|------|-------------|
| node_ids | `Vec<u64>` | Live node IDs in the exported graph. |
| node_labels | `Vec<String>` | Export-local node-label side table. |
| node_label_indexes | `Vec<Vec<u32>>` | Per-node label side-table indexes, aligned with `node_ids`. |
| edge_labels | `Vec<String>` | Export-local edge-label side table. |
| edges | `Vec<ExportEdge>` | Exported edges. Each `ExportEdge.edge_label_index` references `edge_labels`. |

Node.js:

| Field | Type | Description |
|-------|------|-------------|
| nodeIds | `Float64Array` | Live node IDs in the exported graph. |
| edgeLabels | `string[]` | Export-local edge-label side table. |
| edgeFrom | `Float64Array` | Source node IDs, aligned with `edgeTo` and `edgeLabelIndexes`. |
| edgeTo | `Float64Array` | Destination node IDs. |
| edgeLabelIndexes | `Uint32Array` | Edge-label side-table indexes, aligned with `edgeFrom` / `edgeTo`. |
| edgeWeights | `Float64Array \| undefined` | Edge weights when `includeWeights` is true. |

Python:

| Field | Type | Description |
|-------|------|-------------|
| node_ids | `list[int]` | Live node IDs in the exported graph. |
| node_labels | `list[str]` | Export-local node-label side table. |
| node_label_indexes | `list[list[int]]` | Per-node label side-table indexes, aligned with `node_ids`. |
| edge_labels | `list[str]` | Export-local edge-label side table. |
| edges | `list[ExportEdge]` | Exported edges. Each edge has `from_id`, `to_id`, `edge_label_index`, and optional `weight`. |

---

## Vector Search

### vector_search

Performs similarity search using dense vectors (HNSW approximate nearest neighbors), sparse vectors (inverted index dot product), or hybrid mode (fusion of both).

**Rust**
```rust
// Dense search
let hits = db.vector_search(&VectorSearchRequest {
    mode: VectorSearchMode::Dense,
    dense_query: Some(vec![0.1, 0.2, 0.3, /* ... 384 dims */]),
    sparse_query: None,
    k: 10,
    label_filter: None,
    ef_search: Some(100),
    scope: None,
    dense_weight: None,
    sparse_weight: None,
    fusion_mode: None,
})?;

// Sparse search
let hits = db.vector_search(&VectorSearchRequest {
    mode: VectorSearchMode::Sparse,
    dense_query: None,
    sparse_query: Some(vec![(42, 0.9), (128, 0.5)]),
    k: 10,
    label_filter: None,
    ef_search: None,
    scope: None,
    dense_weight: None,
    sparse_weight: None,
    fusion_mode: None,
})?;

// Hybrid search
let hits = db.vector_search(&VectorSearchRequest {
    mode: VectorSearchMode::Hybrid,
    dense_query: Some(embedding),
    sparse_query: Some(sparse_terms),
    k: 10,
    label_filter: Some(NodeLabelFilter {
        labels: vec!["Document".into(), "Published".into()],
        mode: LabelMatchMode::All,
    }),
    ef_search: None,
    scope: None,
    dense_weight: Some(0.7),
    sparse_weight: Some(0.3),
    fusion_mode: Some(FusionMode::WeightedScoreFusion),
})?;
```

**Node.js**
```javascript
// Dense search
const hits = db.vectorSearch('dense', {
  k: 10,
  denseQuery: [0.1, 0.2, 0.3, /* ... */],
  efSearch: 100,
});

// Sparse search
const hits = db.vectorSearch('sparse', {
  k: 10,
  sparseQuery: [{ dimension: 42, value: 0.9 }, { dimension: 128, value: 0.5 }],
});

// Hybrid search with graph scope
const hits = db.vectorSearch('hybrid', {
  k: 10,
  labelFilter: { labels: ['User', 'Project'], mode: 'any' },
  denseQuery: embedding,
  sparseQuery: sparseTerms,
  denseWeight: 0.7,
  sparseWeight: 0.3,
  fusionMode: 'weighted_score',
  scope: {
    startNodeId: rootId,
    maxDepth: 2,
    direction: 'outgoing',
  },
});
```

**Python**
```python
# Dense search
hits = db.vector_search("dense", k=10, dense_query=[0.1, 0.2, ...], ef_search=100)

# Sparse search
hits = db.vector_search("sparse", k=10, sparse_query=[(42, 0.9), (128, 0.5)])

# Hybrid with graph scope
hits = db.vector_search("hybrid", k=10,
    dense_query=embedding,
    sparse_query=sparse_terms,
    label_filter={"labels": ["Document", "Published"], "mode": "all"},
    dense_weight=0.7, sparse_weight=0.3,
    fusion_mode="weighted_score",
    scope_start_node_id=root_id,
    scope_max_depth=2,
    scope_direction="outgoing")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| mode | `VectorSearchMode` | `string` | `str` | Yes | — | `"dense"`, `"sparse"`, or `"hybrid"`. Determines which query vector(s) and index to use. |
| k | `usize` | `number` | `int` | Yes | — | Number of top results to return. |
| dense_query | `Option<Vec<f32>>` | `number[]` | `list[float]` | Required for `dense`/`hybrid` | `None` | Query vector for dense search. Must have the same dimension as configured at `open()`. |
| sparse_query | `Option<Vec<(u32, f32)>>` | `SparseEntry[]` | `list[tuple[int, float]]` | Required for `sparse`/`hybrid` | `None` | Query vector for sparse search. List of `(dimension_index, value)` pairs. |
| label_filter | `Option<NodeLabelFilter>` | `labelFilter: { labels: string[], mode: "any" \| "all" }` | `label_filter: dict` | No | `None` | Node-label filter. |
| ef_search | `Option<usize>` | `number` | `int` | No | `128` | HNSW search expansion factor. The effective dense fetch limit is at least `k` and at least `8`. Higher values improve recall at the cost of latency. Only applies to dense/hybrid modes. |

**Hybrid fusion parameters** (only used when `mode = "hybrid"`):

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| dense_weight | `Option<f32>` | `number` | `float` | No | `1.0` | Weight for dense scores in fusion. |
| sparse_weight | `Option<f32>` | `number` | `float` | No | `1.0` | Weight for sparse scores in fusion. |
| fusion_mode | `Option<FusionMode>` | `string` | `str` | No | `WeightedRankFusion` | How to combine dense and sparse results. See fusion modes below. |

**Fusion modes:**

| Mode | Rust | Node.js / Python | Description |
|------|------|------------------|-------------|
| WeightedRankFusion | `FusionMode::WeightedRankFusion` | `"weighted_rank"` | Weighted reciprocal rank fusion. Default. Combines rank positions with weights. Robust when score distributions differ. |
| ReciprocalRankFusion | `FusionMode::ReciprocalRankFusion` | `"reciprocal_rank"` | Standard RRF (unweighted). Equal contribution from both signals. |
| WeightedScoreFusion | `FusionMode::WeightedScoreFusion` | `"weighted_score"` | Min-max normalized score fusion. Directly combines normalized scores. Best when score magnitudes are meaningful. |

**Graph-scoped search** (restrict vector search to a subgraph):

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| scope.start_node_id | `u64` | `scope.startNodeId: number` | `scope_start_node_id: int` | No | `None` | Root node for scope traversal. When set, only nodes reachable from this node within `max_depth` are candidates. |
| scope.max_depth | `u32` | `scope.maxDepth: number` | `scope_max_depth: int` | Required if scope set | — | Maximum hops from the scope root. |
| scope.direction | `Direction` | `scope.direction: string` | `scope_direction: str` | No | `Outgoing` | Direction for scope traversal. |
| scope.edge_label_filter | `Option<Vec<String>>` | `scope.edgeLabelFilter: string[]` | `scope_edge_label_filter: list[str]` | No | `None` | Edge labels for scope traversal. |
| scope.at_epoch | `Option<i64>` | `scope.atEpoch: number` | `scope_at_epoch: int` | No | `None` | Temporal filter for scope. |

#### Returns: VectorHit

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| node_id | `u64` | `number` | `int` | Matching node ID. |
| score | `f32` | `number` | `float` | Similarity score. Higher is better. |

Results are sorted by score descending.

---

## Retention & Pruning

### prune

Immediately deletes nodes matching the specified criteria. Cascade-deletes all incident edges. Applied atomically in a single WAL batch.

```rust
let result = db.prune(&PrunePolicy {
    max_age_ms: Some(7 * 24 * 60 * 60 * 1000), // 7 days
    max_weight: Some(0.1),                       // weight <= 0.1
    label: Some("Conversation".into()),           // only conversations
})?;
println!("pruned {} nodes, {} edges", result.nodes_pruned, result.edges_pruned);
```

```javascript
const result = db.prune({
  maxAgeMs: 7 * 24 * 60 * 60 * 1000,
  maxWeight: 0.1,
  label: 'Conversation',
});
```

```python
result = db.prune(
    max_age_ms=7 * 24 * 60 * 60 * 1000,
    max_weight=0.1,
    label="Conversation",
)
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Default | Description |
|-----------|------|---------|--------|----------|---------|-------------|
| max_age_ms | `Option<i64>` | `number` | `int` | No* | `None` | Delete nodes older than `now - max_age_ms` milliseconds. Age is computed from `updated_at`. |
| max_weight | `Option<f32>` | `number` | `float` | No* | `None` | Delete nodes with `weight <= max_weight`. |
| label | `Option<String>` | `string` | `str` | No | `None` (all labels) | Restrict pruning to a single node label. |

\* At least one of `max_age_ms` or `max_weight` must be provided. This guards against accidental mass deletion (calling `prune({})` with no criteria is an error).

**Criteria are combined with AND logic.** A node is pruned only if it matches *all* specified criteria.

#### Returns: PruneResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| nodes_pruned | `u64` | `number` | `int` | Number of nodes deleted. |
| edges_pruned | `u64` | `number` | `int` | Number of edges cascade-deleted. |

---

### set_prune_policy

Registers a named prune policy that is automatically applied during [compaction](#compact). Multiple policies can coexist.

```rust
db.set_prune_policy("stale-conversations", PrunePolicy {
    max_age_ms: Some(30 * 24 * 60 * 60 * 1000), // 30 days
    max_weight: None,
    label: Some("Conversation".into()),
})?;
```

```javascript
db.setPrunePolicy('stale-conversations', {
  maxAgeMs: 30 * 24 * 60 * 60 * 1000,
  label: 'Conversation',
});
```

```python
db.set_prune_policy("stale-conversations",
    max_age_ms=30 * 24 * 60 * 60 * 1000,
    label="Conversation")
```

#### Parameters

| Parameter | Rust | Node.js | Python | Required | Description |
|-----------|------|---------|--------|----------|-------------|
| name | `&str` | `string` | `str` | Yes | Policy name. Used to remove or list the policy later. |
| policy | `PrunePolicy` | `object` | `**kwargs` | Yes | Pruning criteria (same fields as [`prune`](#prune)). |

#### Behavior

- Persisted in the manifest. Survives database close/reopen.
- Applied automatically during compaction: matching nodes are pruned and their edges cascade-deleted.
- Multiple policies combine with **OR logic across policies**: a node matching *any* policy is pruned. Within a single policy, criteria combine with AND logic.
- Setting a policy with the same name replaces the previous one.

---

### remove_prune_policy

Removes a named prune policy.

```rust
let existed = db.remove_prune_policy("stale-conversations")?;
```

```javascript
const existed = db.removePrunePolicy('stale-conversations');
```

```python
existed = db.remove_prune_policy("stale-conversations")
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | `&str` / `string` / `str` | Yes | Name of the policy to remove. |

#### Returns

`bool`. Returns `true` if the policy existed and was removed, `false` if no policy with that name was found.

---

### list_prune_policies

Lists all registered prune policies.

```rust
let policies = db.list_prune_policies()?;
for info in &policies {
    println!("{}: max_age_ms={:?}", info.name, info.policy.max_age_ms);
}
```

```javascript
const policies = db.listPrunePolicies();
// [{ name: string, policy: { maxAgeMs?, maxWeight?, label? } }]
```

```python
policies = db.list_prune_policies()
for p in policies:
    print(p.name, p.max_age_ms, p.max_weight, p.label)
```

#### Returns

Array of named policies. Rust and Node.js entries contain a nested policy object; Python flattens
policy fields onto each entry.

| Field path | Rust | Node.js | Python | Description |
|------------|------|---------|--------|-------------|
| name | `info.name: String` | `entry.name: string` | `p.name: str` | Policy name. |
| policy | `info.policy: PrunePolicy` | `entry.policy: PrunePolicy` | — | Nested policy object in Rust and Node.js. |
| max age | `info.policy.max_age_ms: Option<i64>` | `entry.policy.maxAgeMs?: number` | `p.max_age_ms: int \| None` | Age threshold. |
| max weight | `info.policy.max_weight: Option<f32>` | `entry.policy.maxWeight?: number` | `p.max_weight: float \| None` | Weight threshold. |
| label | `info.policy.label: Option<String>` | `entry.policy.label?: string` | `p.label: str \| None` | Node-label scope. |

---

## Maintenance

### sync

Forces an immediate WAL fsync, ensuring all buffered writes are durable on disk.

```rust
db.sync()?;
```

```javascript
db.sync();
```

```python
db.sync()
```

#### Behavior

- In **Immediate** mode: no-op (every write already triggers fsync).
- In **GroupCommit** mode: blocks until all currently buffered data is fsynced.

---

### flush

Flushes the active memtable to a new on-disk segment. Blocks until all pending immutable memtables are written.

```rust
let info = db.flush()?;
```

```javascript
db.flush();
```

```python
info = db.flush()  # SegmentInfo | None
```

#### Returns

| Rust | Node.js | Python | Description |
|------|---------|--------|-------------|
| `Result<Option<SegmentInfo>, EngineError>` | `void` | `SegmentInfo \| None` | Info about the written segment, or `None` if the memtable was empty. |

**SegmentInfo** (Rust/Python):

| Field | Rust | Python | Description |
|-------|------|--------|-------------|
| id | `u64` | `int` | Segment ID on disk. |
| node_count | `u64` | `int` | Nodes in the segment. |
| edge_count | `u64` | `int` | Edges in the segment. |
| segment_format_version | `u32` | — | Rust segment format version. |
| segment_data_id | `[u8; 32]` | — | Rust segment data identifier. |

---

### compact

Merges all segments into a single segment. Applies prune policies during the merge. Reclaims space from tombstones.

```rust
let stats = db.compact()?;
```

```javascript
const stats = db.compact();
```

```python
stats = db.compact()
```

#### Returns: CompactionStats

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| segments_merged | `usize` | `number` | `int` | Number of input segments. |
| nodes_kept | `u64` | `number` | `int` | Live nodes in the output segment. |
| nodes_removed | `u64` | `number` | `int` | Tombstoned nodes reclaimed. |
| edges_kept | `u64` | `number` | `int` | Live edges in the output. |
| edges_removed | `u64` | `number` | `int` | Tombstoned edges reclaimed. |
| duration_ms | `u64` | `number` | `int` | Wall-clock time of compaction. |
| output_segment_id | `u64` | `number` | `int` | ID of the output segment. |
| nodes_auto_pruned | `u64` | `number` | `int` | Nodes removed by prune policies. |
| edges_auto_pruned | `u64` | `number` | `int` | Edges cascade-deleted by auto-prune. |

Returns `None`/`null` if there are fewer than 2 segments (nothing to compact).

---

### compact_with_progress

Compaction with a progress callback. The callback is invoked at key phases and can cancel the compaction.

```rust
let stats = db.compact_with_progress(|progress| {
    println!("phase: {:?}, {}/{} records",
        progress.phase, progress.records_processed, progress.total_records);
    true // return false to cancel
})?;
```

```javascript
// Sync (blocks event loop):
const stats = db.compactWithProgress((progress) => {
  console.log(progress.phase, progress.recordsProcessed, '/', progress.totalRecords);
  return true; // return false to cancel
});

// Async (preferred for UIs):
const stats = await db.compactWithProgressAsync((progress) => {
  console.log(progress.phase);
  // async version cannot cancel, returns void
});
```

```python
def on_progress(progress):
    print(progress.phase, progress.records_processed, "/", progress.total_records)
    return True  # return False to cancel

stats = db.compact_with_progress(on_progress)
```

#### Progress Object

| Field | Type | Description |
|-------|------|-------------|
| phase | `string` | Current phase: `"collecting_tombstones"`, `"merging_nodes"`, `"merging_edges"`, `"writing_output"`. |
| segments_processed | `u32` / `number` / `int` | Segments completed so far. |
| total_segments | `u32` / `number` / `int` | Total segments to process. |
| records_processed | `u64` / `number` / `int` | Individual records processed. |
| total_records | `u64` / `number` / `int` | Total records to process. |

**Cancellation**: Return `false` from the callback to safely cancel compaction. No state is modified because cancellation happens before the atomic segment swap.

---

### ingest_mode

Enters bulk ingest mode. Disables auto-compaction so that rapid writes don't trigger background merges. Call [`end_ingest`](#end_ingest) when done.

```rust
db.ingest_mode();
// ... bulk writes ...
let stats = db.end_ingest()?;
```

```javascript
db.ingestMode();
// ... bulk writes ...
const stats = db.endIngest();
```

```python
db.ingest_mode()
# ... bulk writes ...
stats = db.end_ingest()
```

#### Behavior

- No compaction is triggered while in ingest mode, regardless of `compact_after_n_flushes`.
- The memtable still flushes to segments when the threshold is reached.
- Ideal for initial data loading: write millions of records, then compact once.

---

### end_ingest

Exits ingest mode and immediately compacts all segments.

```rust
let stats = db.end_ingest()?;
```

```javascript
const stats = db.endIngest(); // CompactionStats | null
```

```python
stats = db.end_ingest()  # CompactionStats | None
```

#### Returns

`CompactionStats` (same as [`compact`](#compact)), or `None`/`null` if there was nothing to compact.

---

### scrub

Runs an offline integrity check across all segments. Recomputes SHA-256 payload digests for every component and compares them to the digests recorded at write time. Reports mismatches without modifying any data.

**Rust**
```rust
let report = db.scrub()?;
println!("checked: {}, failed: {}", report.total_components_checked, report.total_components_failed);
for seg in &report.segments {
    for f in &seg.findings {
        eprintln!("segment {}: {} — {}", seg.segment_id, f.finding_type, f.detail);
    }
}
```

**Node.js**
```javascript
const report = db.scrub();
console.log(`checked: ${report.totalComponentsChecked}, failed: ${report.totalComponentsFailed}`);

// async
const report = await db.scrubAsync();
```

**Python**
```python
report = db.scrub()
print(f"checked: {report.total_components_checked}, failed: {report.total_components_failed}")

# async
report = await db.scrub()
```

#### Parameters

None.

#### Returns: ScrubReport

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| segments | `Vec<SegmentScrubResult>` | `Array<SegmentScrubResult>` | `list[SegmentScrubResult]` | Per-segment results. |
| total_components_checked | `u64` | `number` | `int` | Total components examined. |
| total_components_ok | `u64` | `number` | `int` | Components that passed all checks. |
| total_components_failed | `u64` | `number` | `int` | Components with at least one finding. |
| total_bytes_digested | `u64` | `number` | `int` | Total payload bytes hashed during the scrub. |
| duration_ms | `u64` | `number` | `int` | Wall-clock time of the scrub in milliseconds. |

#### SegmentScrubResult

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| segment_id | `u64` | `number` | `int` | Segment that was checked. |
| findings | `Vec<ComponentScrubFinding>` | `Array<ComponentScrubFinding>` | `list[ComponentScrubFinding]` | Problems found (empty if healthy). |
| components_ok | `u64` | `number` | `int` | Components that passed in this segment. |
| bytes_digested | `u64` | `number` | `int` | Payload bytes hashed in this segment. |

#### ComponentScrubFinding

| Field | Rust | Node.js | Python | Description |
|-------|------|---------|--------|-------------|
| component_kind | `String` | `string` | `str` | Which component type had the problem (e.g. `"NodeRecords"`, `"PlannerStats"`). |
| finding_type | `ScrubFindingType` | `string` | `str` | Classification: `PayloadDigestMismatch`, `ComponentIdMismatch`, `DependencyDigestMismatch`, `IdentityHeaderMismatch`, `ContainerIdMismatch`, `SegmentIdentityMismatch`, `RangeOverflow`, `RangeOverlap`, `FileMissing`, or `IoError`. |
| detail | `String` | `string` | `str` | Human-readable description of the finding. |

#### Behavior

- Scrub is **read-only** — it never modifies data on disk.
- Scrub is **offline** — it is never called automatically during open, query, flush, or compaction. You must call it explicitly.
- Segments are checked in parallel using a shared thread pool. The work is I/O-bound (streaming 64KB-buffered reads + SHA-256), not CPU-bound.
- A healthy database returns `total_components_failed == 0` and an empty `findings` array for every segment.
- If a segment directory is missing (e.g. deleted concurrently), the scrub reports a `FileMissing` finding rather than panicking.

---

## Introspection

These methods provide quick diagnostic information. They are **approximate** and counts may slightly overcount when the same ID appears in multiple memtables or segments.

### node_count

```rust
let count = db.node_count()?; // usize
```

Approximate count of live nodes across all data sources.

### edge_count

```rust
let count = db.edge_count()?; // usize
```

Approximate count of live edges.

### next_node_id

```rust
let next = db.next_node_id()?; // u64
```

Rust-only diagnostic: the next auto-assigned node ID that would be used by a new node write.

### next_edge_id

```rust
let next = db.next_edge_id()?; // u64
```

Rust-only diagnostic: the next auto-assigned edge ID that would be used by a new edge write.

### segment_count

```rust
let count = db.segment_count()?; // usize
```

Number of on-disk segments. After compaction, this is typically 0 or 1.

### segment_tombstone_node_count

```rust
let count = db.segment_tombstone_node_count()?; // usize
```

Rust-only diagnostic: deleted node records currently retained in immutable segments.

### segment_tombstone_edge_count

```rust
let count = db.segment_tombstone_edge_count()?; // usize
```

Rust-only diagnostic: deleted edge records currently retained in immutable segments.

### path

```rust
let path = db.path();
```

Returns the database directory path as `&Path`.

### manifest

Rust diagnostic API for reading the current raw manifest state.

```rust
let manifest = db.manifest()?;
println!("label token schema: {}", manifest.label_token_schema_version);
```

#### Returns: ManifestState

`ManifestState` is a raw diagnostic object. Ordinary graph APIs accept public label names, not these internal numeric IDs.

| Field | Rust | Description |
|-------|------|-------------|
| label_token_schema_version | `u32` | Node-label / edge-label catalog schema marker. |
| node_label_tokens | `BTreeMap<String, u32>` | Public node label to internal `label_id`. |
| edge_label_tokens | `BTreeMap<String, u32>` | Public edge label to internal `label_id`. |
| secondary_indexes | `Vec<SecondaryIndexManifestEntry>` | Raw optional secondary-index declarations. Node targets use `SecondaryIndexTarget::NodeProperty { label_id, prop_key }`; edge targets use `SecondaryIndexTarget::EdgeProperty { label_id, prop_key }`. |
| segments | `Vec<SegmentInfo>` | Published segment metadata. |

### manifest::load_manifest_readonly (Rust only)

Diagnostic read-only manifest loader that inspects the manifest priority chain without writing to disk.

```rust
let manifest = overgraph::manifest::load_manifest_readonly(Path::new("./my-graph"))?;
```

Returns `Result<Option<ManifestState>, EngineError>`. The returned manifest is a raw diagnostic view and may contain internal numeric token IDs.

---

## Binary Batch Ingestion

High-performance connector-only binary format for batch upserts. Avoids JSON parsing overhead. Useful when ingesting data from a custom pipeline. Rust callers use the structured `batch_upsert_nodes` and `batch_upsert_edges` APIs directly.

### batch_upsert_nodes_binary

```javascript
const buf = Buffer.alloc(/* ... */);
// Format: "OGNB", version 2, count, then per-node labels/key/props payloads.
const ids = db.batchUpsertNodesBinary(buf);
```

```python
buf = b'...'  # same binary format
ids = db.batch_upsert_nodes_binary(buf)
```

#### Binary Format (little-endian)

```
┌──────────────────────────────────────┐
│ magic: "OGNB"                        │
│ version: u16 = 2                     │
│ count: u32                           │  ← number of nodes in this batch
├──────────────────────────────────────┤
│ For each node:                       │
│   label_count: u8                    │
│   repeated label_count times:        │
│     label_len: u16                   │
│     label: [u8; label_len] (UTF-8)   │
│   weight:    f32                     │
│   key_len:   u16                     │
│   key:       [u8; key_len]  (UTF-8)  │
│   props_len: u32                     │
│   props:     [u8; props_len] (JSON)  │
└──────────────────────────────────────┘
```

#### Returns

Array of node IDs (same order as packed nodes).

Version 1 node buffers are rejected. Use version 2 for every connector so each packed node carries its full label set.

---

### batch_upsert_edges_binary

```javascript
const ids = db.batchUpsertEdgesBinary(buf);
```

```python
ids = db.batch_upsert_edges_binary(buf)
```

#### Binary Format (little-endian)

```
┌──────────────────────────────────────────┐
│ magic: "OGEB"                            │
│ version: u16 = 1                         │
│ count: u32                               │
├──────────────────────────────────────────┤
│ For each edge:                           │
│   from:       u64                        │
│   to:         u64                        │
│   label_len:  u16                       │
│   label:      [u8; label_len] (UTF-8)   │
│   weight:     f32                        │
│   valid_from: i64                        │
│   valid_to:   i64                        │
│   props_len:  u32                        │
│   props:      [u8; props_len]  (JSON)    │
└──────────────────────────────────────────┘
```

In the packed binary edge format only, `valid_from = 0` and `valid_to = 0` are sentinels for the engine defaults. `valid_from = 0` means "use the edge's `created_at` timestamp"; `valid_to = 0` means "use `i64::MAX` / no expiration." Because of these sentinels, epoch `0` cannot be represented as an explicit edge validity bound in this packed format.

---

## Error Handling

All methods can fail. Errors are returned differently across languages:

| Language | Error mechanism | Error type |
|----------|----------------|------------|
| Rust | `Result<T, EngineError>` | `EngineError` enum |
| Node.js | Thrown `Error` | Standard `Error` with message |
| Python | Raised exception | `OverGraphError(Exception)` |

### EngineError Variants (Rust)

| Variant | Description |
|---------|-------------|
| `IoError(io::Error)` | Filesystem I/O failure (disk full, permission denied, etc.). |
| `CorruptRecord(String)` | A record failed deserialization. Indicates data corruption. |
| `CorruptWal(String)` | WAL file is corrupt (truncated, bad checksum). |
| `SerializationError(String)` | Property encoding/decoding failed. |
| `ManifestError(String)` | Manifest file is corrupt or incompatible. |
| `DatabaseNotFound(String)` | Directory doesn't exist and `create_if_missing` is false. |
| `DatabaseClosed` | Operation attempted after the engine was closed. |
| `InvalidOperation(String)` | Invalid API usage (e.g., writing to a closed database). |
| `TxnConflict(String)` | Explicit write transaction conflict. No WAL entry was appended and the transaction did not commit. |
| `TxnClosed` | Explicit write transaction was already committed or rolled back. |
| `CompactionCancelled` | Compaction was cancelled via the progress callback. |
| `WalSyncFailed(String)` | WAL fsync failed. |

### Error Handling Examples

**Rust**
```rust
match db.get_node(42) {
    Ok(Some(node)) => println!("found: {}", node.key),
    Ok(None) => println!("not found"),
    Err(e) => eprintln!("error: {}", e),
}
```

**Node.js**
```javascript
try {
  const node = db.getNode(42);
} catch (e) {
  console.error('OverGraph error:', e.message);
}
```

**Python**
```python
from overgraph import OverGraph, OverGraphError

try:
    node = db.get_node(42)
except OverGraphError as e:
    print(f"OverGraph error: {e}")
```

---

## Async API

Both Node.js and Python provide async variants of all methods.

### Node.js

Every synchronous method has an async counterpart with an `Async` suffix that returns a `Promise`:

```javascript
// Sync
const node = db.getNode(42);

// Async
const node = await db.getNodeAsync(42);
```

Async methods run on the libuv thread pool. Write operations acquire an exclusive lock; read operations acquire a shared lock (allowing concurrent reads).

**Available async methods:** `closeAsync`, `ensureNodeLabelAsync`, `ensureEdgeLabelAsync`, `getNodeLabelIdAsync`, `getEdgeLabelIdAsync`, `getNodeLabelAsync`, `getEdgeLabelAsync`, `listNodeLabelsAsync`, `listEdgeLabelsAsync`, `upsertNodeAsync`, `upsertEdgeAsync`, `addNodeLabelAsync`, `removeNodeLabelAsync`, `batchUpsertNodesAsync`, `batchUpsertEdgesAsync`, `batchUpsertNodesBinaryAsync`, `batchUpsertEdgesBinaryAsync`, `getNodeAsync`, `getEdgeAsync`, `getNodeByKeyAsync`, `getEdgeByTripleAsync`, `getNodesAsync`, `getNodesByKeysAsync`, `getEdgesAsync`, `deleteNodeAsync`, `deleteEdgeAsync`, `invalidateEdgeAsync`, `graphPatchAsync`, `beginWriteTxnAsync`, `neighborsAsync`, `neighborsPagedAsync`, `neighborsBatchAsync`, `traverseAsync`, `topKNeighborsAsync`, `extractSubgraphAsync`, `shortestPathAsync`, `allShortestPathsAsync`, `isConnectedAsync`, `degreeAsync`, `degreesAsync`, `sumEdgeWeightsAsync`, `avgEdgeWeightAsync`, `findNodesAsync`, `findNodesPagedAsync`, `ensureNodePropertyIndexAsync`, `dropNodePropertyIndexAsync`, `listNodePropertyIndexesAsync`, `ensureEdgePropertyIndexAsync`, `dropEdgePropertyIndexAsync`, `listEdgePropertyIndexesAsync`, `findNodesRangeAsync`, `findNodesRangePagedAsync`, `findNodesByTimeRangeAsync`, `findNodesByTimeRangePagedAsync`, `nodesByLabelsAsync`, `edgesByLabelAsync`, `getNodesByLabelsAsync`, `getEdgesByLabelAsync`, `countNodesByLabelsAsync`, `countEdgesByLabelAsync`, `nodesByLabelsPagedAsync`, `edgesByLabelPagedAsync`, `getNodesByLabelsPagedAsync`, `getEdgesByLabelPagedAsync`, `queryNodeIdsAsync`, `queryNodesAsync`, `queryEdgeIdsAsync`, `queryEdgesAsync`, `queryGraphRowsAsync`, `explainNodeQueryAsync`, `explainEdgeQueryAsync`, `explainGraphRowsAsync`, `executeGqlAsync`, `explainGqlAsync`, `personalizedPagerankAsync`, `connectedComponentsAsync`, `componentOfAsync`, `vectorSearchAsync`, `exportAdjacencyAsync`, `pruneAsync`, `setPrunePolicyAsync`, `removePrunePolicyAsync`, `listPrunePoliciesAsync`, `syncAsync`, `flushAsync`, `compactAsync`, `compactWithProgressAsync`, `ingestModeAsync`, `endIngestAsync`.

`WriteTxn` handles expose async counterparts for the full transaction surface: `upsertNodeAsync`, `upsertNodeAsAsync`, `upsertEdgeAsync`, `upsertEdgeAsAsync`, `deleteNodeAsync`, `deleteEdgeAsync`, `invalidateEdgeAsync`, `stageAsync`, `getNodeAsync`, `getEdgeAsync`, `getNodeByKeyAsync`, `getEdgeByTripleAsync`, `commitAsync`, and `rollbackAsync`. Async transaction operations on one handle execute in call order.

### Python

The `AsyncOverGraph` class wraps every `OverGraph` method with `asyncio.to_thread()`. `begin_write_txn()` returns an `AsyncWriteTxn` whose methods mirror `WriteTxn`:

```python
from overgraph import AsyncOverGraph

async def main():
    async with await AsyncOverGraph.open("./my-graph") as db:
        # Also accepts multiple labels: ["User", "Admin"]
        node_id = await db.upsert_node("User", "alice")
        node = await db.get_node(node_id)
        neighbors = await db.neighbors(node_id)

asyncio.run(main())
```

**All methods have identical signatures and semantics** to the sync `OverGraph` class but return coroutines.
`AsyncWriteTxn` also serializes operations on each transaction handle so staged writes, reads, `commit()`, and `rollback()` run in await/call order.

**GIL behavior**: The sync `OverGraph` releases the Python GIL during all Rust operations, enabling true parallelism in multi-threaded Python. The `AsyncOverGraph` uses `asyncio.to_thread()` to run sync operations in the default thread pool executor.

---

## Appendix: Quick Reference

### All Methods at a Glance

| Category | Method | Description |
|----------|--------|-------------|
| **Lifecycle** | `open` | Open or create database |
| | `close` | Shut down database |
| | `stats` | Runtime statistics |
| **Nodes** | `upsert_node` | Create or update node |
| | `get_node` | Get node by ID |
| | `get_node_by_key` | Get node by label + key |
| | `add_node_label` | Add a node label to an existing node |
| | `remove_node_label` | Remove a node label from an existing node |
| | `delete_node` | Delete node (cascade edges) |
| | `batch_upsert_nodes` | Batch create/update nodes |
| | `get_nodes` | Batch get nodes by ID |
| | `get_nodes_by_keys` | Batch get nodes by label + key |
| **Edges** | `upsert_edge` | Create or update edge |
| | `get_edge` | Get edge by ID |
| | `get_edge_by_triple` | Get edge by from + to + edge label |
| | `delete_edge` | Delete edge |
| | `invalidate_edge` | Close validity window |
| | `batch_upsert_edges` | Batch create/update edges |
| | `get_edges` | Batch get edges by ID |
| **Atomic** | `graph_patch` | Multi-op atomic batch |
| | `begin_write_txn` / `beginWriteTxn` | Explicit ordered write transaction |
| **Catalog** | `ensure_node_label` / `ensureNodeLabel` | Ensure node label token |
| | `ensure_edge_label` / `ensureEdgeLabel` | Ensure edge label token |
| | `get_node_label_id` / `getNodeLabelId` | Diagnostic name-to-ID lookup |
| | `get_edge_label_id` / `getEdgeLabelId` | Diagnostic name-to-ID lookup |
| | `get_node_label` / `getNodeLabel` | Diagnostic ID-to-name lookup |
| | `get_edge_label` / `getEdgeLabel` | Diagnostic ID-to-name lookup |
| | `list_node_labels` / `listNodeLabels` | List node-label catalog entries |
| | `list_edge_labels` / `listEdgeLabels` | List edge-label catalog entries |
| **Label and Edge-Label Queries** | `nodes_by_labels` | Node ID convenience query |
| | `edges_by_label` | All edge IDs of an edge label |
| | `get_nodes_by_labels` | Hydrated node convenience query |
| | `get_edges_by_label` | All edge records of an edge label |
| | `count_nodes_by_labels` | Node count convenience query |
| | `count_edges_by_label` | Count edges of an edge label |
| **Property Indexes** | `ensure_node_property_index` | Declare optional node equality or range index |
| | `drop_node_property_index` | Remove optional node property index declaration |
| | `list_node_property_indexes` | Inspect node declaration state |
| | `ensure_edge_property_index` | Declare optional edge equality or range index |
| | `drop_edge_property_index` | Remove optional edge property index declaration |
| | `list_edge_property_indexes` | Inspect edge declaration state |
| **Property & Time Queries** | `find_nodes` | Property search |
| | `find_nodes_range` | Numeric property range search |
| | `find_nodes_by_time_range` | Time range search |
| **Queries** | `query_node_ids` | Node query returning IDs |
| | `query_nodes` | Node query returning hydrated nodes |
| | `explain_node_query` | Explain a node query plan |
| | `query_edge_ids` | Edge query returning IDs |
| | `query_edges` | Edge query returning hydrated edges |
| | `explain_edge_query` | Explain an edge query plan |
| | `query_graph_rows` | Structured graph-row query |
| | `explain_graph_rows` | Explain a graph-row query |
| | `execute_gql` | GQL Beta read-only query-string rows |
| | `explain_gql` | Explain a GQL Beta query |
| **Pagination** | `*_paged` | Paginated variants |
| **Traversal** | `neighbors` | Immediate neighbors |
| | `neighbors_paged` | Paginated neighbors |
| | `neighbors_batch` | Multi-node neighbors |
| | `top_k_neighbors` | Top K by score |
| | `traverse` | BFS traversal |
| | `extract_subgraph` | Subgraph extraction |
| | `shortest_path` | Shortest path |
| | `all_shortest_paths` | All shortest paths |
| | `is_connected` | Reachability check |
| **Degree & Weight** | `degree` | Edge count |
| | `degrees` | Batch edge counts |
| | `sum_edge_weights` | Sum of edge weights |
| | `avg_edge_weight` | Average edge weight |
| **Analytics** | `connected_components` | WCC decomposition |
| | `component_of` | Component membership |
| | `personalized_pagerank` | PPR scoring |
| | `export_adjacency` | Adjacency export |
| **Vectors** | `vector_search` | Dense/sparse/hybrid search |
| **Retention** | `prune` | Immediate pruning |
| | `set_prune_policy` | Register auto-prune |
| | `remove_prune_policy` | Remove auto-prune |
| | `list_prune_policies` | List policies |
| **Maintenance** | `sync` | Force WAL fsync |
| | `flush` | Memtable → segment |
| | `compact` | Merge segments |
| | `compact_with_progress` | Merge with progress |
| | `ingest_mode` | Enter bulk mode |
| | `end_ingest` | Exit bulk mode + compact |
| | `scrub` | Validate database integrity |
| **Introspection** | `path` | Database directory path |
| | `manifest` | Rust raw manifest diagnostics |
| | `next_node_id` | Rust next node ID diagnostic |
| | `next_edge_id` | Rust next edge ID diagnostic |
| | `segment_tombstone_node_count` | Rust segment node tombstone diagnostic |
| | `segment_tombstone_edge_count` | Rust segment edge tombstone diagnostic |
| | `manifest::load_manifest_readonly` | Rust read-only manifest diagnostic |
| **Binary** | `batch_upsert_nodes_binary` | Connector-only binary batch nodes |
| | `batch_upsert_edges_binary` | Connector-only binary batch edges |