# Data format specification

All ID columns (`node_id`, `edge_id`, `source_node`, `target_node`, `exit_edge`) are stored as **BIGINT** internally. You may supply integers directly, or pass string IDs and let the library auto-translate them (see [String IDs](data-schema.md#string-nodeedge-ids)).

## Network nodes (Parquet)

Required columns:

- `node_id` (BIGINT): Unique node identifier

Optional columns:

- `geometry` (geometry): Point geometry (needed for spatial queries)
- Any additional attributes (label, category, elevation, etc.)

## Network edges (Parquet)

Required columns:

- `edge_id` (BIGINT): Unique edge identifier
- `source_node` (BIGINT): Source node ID
- `target_node` (BIGINT): Target node ID

Optional columns:

- `geometry` (geometry): LineString geometry (needed for spatial queries)
- Any additional attributes (weight, capacity, length, etc.)

## Walks (Parquet)

Walk data follows the [superset schema](data-schema.md#superset-schema). Supports Hive-style partitioning for efficient filtering.

| Column | Type | Required | Description |
|--------|------|----------|-------------|
| `walk_id` | String/Int | Yes | Unique identifier for the walk |
| `sequence_idx` | Integer | Yes | Step order (0, 1, 2, ...) |
| `node_id` | BIGINT (Int64) | Yes | Node visited at this step |
| `exit_edge` | BIGINT (Int64) | No | Edge taken to next step |
| `timestamp` | Timestamp | No | Time when node was reached |
| `dwell_time` | Interval | No | Duration spent at node |
| `dynamic_attributes` | JSON/MAP | No | Walk/step-specific metadata |

## DuckDB storage

When using `Network.save()` or `write_duckdb()`, the following tables are created in DuckDB:

| Table | Purpose |
|-------|---------|
| `wp_nodes` | Node topology (`node_id`, `geom`, `attributes`) |
| `wp_edges` | Edge topology (`edge_id`, `source_node`, `target_node`, `geom`, `attributes`) |
| `wp_node_map` | String-to-integer mapping for node IDs (if applicable) |
| `wp_edge_map` | String-to-integer mapping for edge IDs (if applicable) |
| `wp_walks` | Walk data (only when using `write_duckdb()`) |
