Cypher Reference

HyperMesh DB uses a dialect of the openCypher query language extended with hyperedge-aware constructs. The parser is a hand-written C recursive-descent implementation (hypermesh_core/src/cypher_parser/) with zero external dependencies.

---

Grammar overview

query ::= show_tables
        | tpi_range
        | call_range
        | fmi_lookup
        | full_scan
        | create_table
        | drop_table

show_tables  ::= "CALL" "show_hyperedge_tables" "(" ")" "RETURN" "*"

tpi_range    ::= "MATCH" "HYPEREDGE" "(" alias ":" table ")"
                 "WHERE" alias ".event_ts" ">=" integer
                 "AND"   alias ".event_ts" "<=" integer
                 "RETURN" "*"

call_range   ::= "CALL" "GET_HYPEREDGES_BY_TIME_RANGE"
                 "(" "'" table "'" "," integer "," integer ")" "RETURN" "*"

fmi_lookup   ::= "MATCH" "HYPEREDGE" "(" alias ":" table ")"
                 "WHERE" integer "IN" alias ".members" "RETURN" "*"

full_scan    ::= "MATCH" "HYPEREDGE" "(" alias ":" table ")" "RETURN" "*"

create_table ::= "CREATE" "HYPEREDGE" "TABLE" name
                 "(" member_table { "," member_table } ")"
                 ["BUCKET_SECONDS" integer ]
                 ["PROPERTIES" "(" prop_def { "," prop_def } ")" ]

drop_table   ::= "DROP" "HYPEREDGE" "TABLE" name

---

CALL show_hyperedge_tables()

List all hyperedge table definitions stored in the schema catalog.

Syntax

CALL show_hyperedge_tables() RETURN *

Result columns

Column	Type	Description
name	string	Table name (upper-case)
member_tables	list	Member node table names
bucket_seconds	int	TPI bucket granularity
row_count	int	Total records in the TPI index

Example

CALL show_hyperedge_tables() RETURN *

---

MATCH HYPEREDGE … WHERE event_ts range

Temporal range query using TPI bucket pushdown.

Syntax

MATCH HYPEREDGE (he:<Table>)
WHERE he.event_ts >= <T1> AND he.event_ts <= <T2>
RETURN *

Also accepted (procedure call form):

CALL GET_HYPEREDGES_BY_TIME_RANGE('<Table>', <T1>, <T2>) RETURN *

Parameters

Parameter	Description
<Table>	Hyperedge table name (case-insensitive)
<T1>, <T2>	Timestamp bounds in seconds (inclusive)

Result columns: event_ts, members, weight, mean_dist_m, formation

Query plan
The TPI bucket directory is binary-searched to find the first and last buckets that overlap [T1, T2]. Only those buckets are read from hyperedges.bin. The query_plan.speedup_factor reported in the result reflects how many buckets were skipped.

Example

MATCH HYPEREDGE (he:CoProximity)
WHERE he.event_ts >= 100 AND he.event_ts <= 200
RETURN *

---

MATCH HYPEREDGE … WHERE N IN members

Forward Member Index (FMI) point lookup. Returns all hyperedges that contain node N as a member.

Syntax

MATCH HYPEREDGE (he:<Table>) WHERE <N> IN he.members RETURN *

Parameters

Parameter	Description
<N>	Node ID (integer)

Result columns: same as range query

Example

MATCH HYPEREDGE (he:CoProximity) WHERE 7 IN he.members RETURN *

---

MATCH HYPEREDGE (full scan)

Return all records in a hyperedge table. No WHERE clause.

Syntax

MATCH HYPEREDGE (he:<Table>) RETURN *

Caution

A full scan reads every bucket in the TPI. Use range queries for large datasets to benefit from TPI pushdown.

---

CREATE HYPEREDGE TABLE

Define a new hyperedge table in the schema catalog.

Syntax

CREATE HYPEREDGE TABLE <Name> (<MemberTable1>, <MemberTable2> [, ...])
[BUCKET_SECONDS <n>]
[PROPERTIES (<prop> <type> [, ...])]

Parameters

Parameter	Description
<Name>	New table name
<MemberTable>	Node table names participating in this hyperedge
BUCKET_SECONDS	TPI bucket granularity (default: inherits from existing index)
PROPERTIES	Future: property schema (parsed and ignored in v0.1)

Result columns: name, member_tables, bucket_seconds, created_at

Example

CREATE HYPEREDGE TABLE SensorNet (Drone, Sensor) BUCKET_SECONDS 30

---

DROP HYPEREDGE TABLE

Remove a hyperedge table definition from the schema catalog.

Syntax

DROP HYPEREDGE TABLE <Name>

Note

Dropping a table only removes the schema entry. The underlying TPI/FMI binary files are not deleted. Run hmdb compact to rebuild indexes after structural changes.

Result columns: name, dropped

Example

DROP HYPEREDGE TABLE SensorNet

---

Parameter substitution

When using the Python SDK’s execute() method, $name placeholders are substituted before the query reaches the parser:

result = db.execute(
    "MATCH HYPEREDGE (he:CoProximity) "
    "WHERE he.event_ts >= $start AND he.event_ts <= $end RETURN *",
    parameters={"start": 100, "end": 200},
)

The substitution is simple string replacement — values must be integers or strings that produce valid token literals when inserted.