Get Started

This guide walks through the most common HyperMesh DB workflows. It assumes you have completed the Installation steps.

1 — Import your first dataset

hmdb import ./demo_db \
  --edges  server/swarm_data/hyperedges.csv \
  --nodes  server/swarm_data/nodes_drone.csv \
  --bucket-seconds 10

Expected output:

Building index in /path/to/demo_db …
Index built successfully.
  Records        : 1,774
  Buckets        : 86  (10s each)
  Unique nodes   : 20

What happened?
The import command built two binary indexes in ./demo_db/:

File	Contents
`bucket_directory.bin`	TPI bucket directory (86 × 8-byte entries)
`hyperedges.bin`	Sorted hyperedge records
`fmi_nodes.bin`	FMI node → offset table
`fmi_adjacency.bin`	FMI adjacency lists
`wal.bin`	Write-ahead log (empty at build time)
`nodes.db`	SQLite node property store
`schema.db`	SQLite schema catalog

2 — Inspect the database

hmdb info ./demo_db

  Database directory : /path/to/demo_db
  Total records      : 1,774
  Bucket count       : 86
  Bucket seconds     : 10
  Unique nodes       : 20
  WAL pending        : 0

  Hyperedge tables:
  ┌──────────────┬────────────────────┬───────────────┬───────────┐
  │ name         │ member_tables      │ bucket_seconds│ row_count │
  ├──────────────┼────────────────────┼───────────────┼───────────┤
  │ CoProximity  │ [Drone, Drone]     │ 10            │ 1774      │
  └──────────────┴────────────────────┴───────────────┴───────────┘

3 — Run your first query (CLI)

hmdb query ./demo_db \
  "MATCH HYPEREDGE (he:CoProximity) WHERE he.event_ts >= 0 AND he.event_ts <= 50 RETURN *"

┌──────────┬────────────┬──────────┬─────────────┬───────────┐
│ event_ts │ members    │ weight   │ mean_dist_m │ formation │
├──────────┼────────────┼──────────┼─────────────┼───────────┤
│ 0        │ [1, 3, 5]  │ 0.812    │ 28.3        │ WEDGE     │
│ 10       │ [2, 4]     │ 0.734    │ 31.1        │ LINE      │
│ ...      │ ...        │ ...      │ ...         │ ...       │
└──────────┴────────────┴──────────┴─────────────┴───────────┘
18 rows  [TPI_BUCKET_PUSHDOWN  5/86 buckets  17.2× speedup  412µs]

The plan summary shows that only 5 of 86 buckets were read — the TPI skipped 81 irrelevant time partitions.

4 — Interactive shell

hmdb shell ./demo_db

╔══════════════════════════════════════════════╗
║   HyperMesh DB Shell  ·  version 0.1.0       ║
╚══════════════════════════════════════════════╝
Type  HELP  for usage,  QUIT  to exit.

  Database : /path/to/demo_db
  Records  : 1,774
  Buckets  : 86  (10s each)
  Nodes    : 20
  WAL      : 0 pending entries

hmdb> CALL show_hyperedge_tables() RETURN *
  ┌──────────────┬────────────────────┬───────────────┬───────────┐
  │ name         │ member_tables      │ bucket_seconds│ row_count │
  ├──────────────┼────────────────────┼───────────────┼───────────┤
  │ CoProximity  │ [Drone, Drone]     │ 10            │ 1774      │
  └──────────────┴────────────────────┴───────────────┴───────────┘
  1 row  (0.42ms)

hmdb> MATCH HYPEREDGE (he:CoProximity) WHERE 3 IN he.members RETURN *
  (results for node 3 ...)

hmdb> QUIT
Bye.

5 — Python SDK

import hypermeshdb

# Open an existing database (no rebuild)
with hypermeshdb.connect("./demo_db") as db:

    # Temporal range query — TPI pushdown
    result = db.execute(
        "MATCH HYPEREDGE (he:CoProximity) "
        "WHERE he.event_ts >= $start AND he.event_ts <= $end RETURN *",
        parameters={"start": 0, "end": 100},
    )

    print(f"{result.num_tuples} rows  {result.query_plan}")

    for row in result:
        print(row["event_ts"], row.members, row.weight)

    # Insert a new record
    db.insert(event_ts=9999, members=[1, 2, 3], weight=0.95, formation="WEDGE")

    # Compact WAL into TPI+FMI
    db.compact()

6 — Export to CSV

hmdb export ./demo_db \
  --query "MATCH HYPEREDGE (he:CoProximity) RETURN *" \
  --output full_dump.csv

Next steps

Cypher Reference — full query language reference
Python API — complete Python SDK documentation
CLI Reference — all hmdb subcommands
Performance — benchmark methodology and results
Internals — TPI architecture deep dive