Python Quickstart

This guide walks you through the core HyperMesh DB operations using the Python SDK.

1. Connect

import hypermeshdb

# Open (or create) a database at the given directory
db = hypermeshdb.connect("/tmp/demo_db")

2. Create a table

db.execute("CREATE HYPEREDGE TABLE CoProximity (Drone)")

This creates a new hyperedge table named CoProximity with Drone as the member node type.

Optional DDL parameters:

db.execute("""
    CREATE HYPEREDGE TABLE CoProximity (Drone)
    BUCKET_SECONDS 10
    COMPACT_THRESHOLD 1000
""")

3. Insert hyperedges

# Single insert via the convenience method
db.insert(event_ts=1000, members=[1, 2, 3], weight=0.95, formation="delta")

# Or via Cypher INSERT
db.execute(
    "INSERT INTO CoProximity (event_ts, members, weight) "
    "VALUES (1001, [2, 3, 4], 0.88)"
)

event_ts — integer timestamp (Unix epoch seconds, or any monotonic counter)
members — list of integer node IDs (1 to 64 nodes)
weight — optional float property
mean_dist_m, formation — optional properties

4. Flush WAL to index

db.execute("COMPACT")

Records are first written to the WAL. The COMPACT command merges them into the TPI (Temporal Property Index) and FMI (Forward Member Index) for fast queries.

5. Query by time range

result = db.execute("""
    MATCH HYPEREDGE (he:CoProximity)
    WHERE he.event_ts >= 1000 AND he.event_ts <= 1010
    RETURN *
""")

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

print(result.query_plan.strategy)  # TPI_BUCKET_PUSHDOWN

6. Look up a node

result = db.execute("""
    MATCH HYPEREDGE (he:CoProximity)
    WHERE MEMBER(he, 2)
    RETURN *
""")

This uses the FMI (Forward Member Index) for O(log N) lookup — it does not scan all records.

7. Property index (PSI)

db.execute("CREATE INDEX ON CoProximity (weight)")

result = db.execute("""
    MATCH HYPEREDGE (he:CoProximity)
    WHERE he.weight > 0.9
    RETURN *
""")

8. Transactions

with db.transaction():
    db.insert(event_ts=2000, members=[1, 2])
    db.insert(event_ts=2001, members=[2, 3])
    # If an exception is raised here, both inserts are rolled back

Or programmatic control:

db.begin()
try:
    db.insert(event_ts=2002, members=[4, 5])
    db.commit()
except Exception:
    db.rollback()
    raise

9. Analytics

analytics = db.analytics("CoProximity")

print(analytics.density())
print(analytics.pagerank())
print(analytics.spectral_gap())
print(analytics.temporal_burstiness())

See the Analytics guide for all 25 measures.

10. Query plan (EXPLAIN / ANALYZE)

# EXPLAIN — returns query plan only (no data)
plan = db.execute("EXPLAIN MATCH HYPEREDGE (he:CoProximity) "
                  "WHERE he.event_ts >= 1000 RETURN *")
print(plan.rows[0]["strategy"])
print(plan.rows[0]["speedup_factor"])

# ANALYZE — returns data + plan
result = db.execute("ANALYZE MATCH HYPEREDGE (he:CoProximity) RETURN *")
print(result.query_plan)

11. Schema evolution

db.execute("ALTER TABLE CoProximity ADD COLUMN altitude REAL DEFAULT 0.0")
db.execute("ALTER TABLE CoProximity DROP COLUMN altitude")
db.execute("ALTER TABLE CoProximity RENAME TO CoProximityV2")