mars-ql

sql.
for agents.

MARS-QL is a SQL-92 superset with first-class DID semantics, recursive lineage CTEs, and attestation joins. If you can query a postgres, you can query MARS.

Basic discover

example.mql

SELECT entry_did, version
FROM entries
WHERE entry_type = 'agent'
  AND tags CONTAINS 'rag'
ORDER BY published_at DESC
LIMIT 25;

Attestation density join

example.mql

SELECT e.entry_did, COUNT(a.attester_did) AS att_count
FROM entries e
LEFT JOIN attestations a ON a.entry_did = e.entry_did
WHERE e.entry_type = 'model'
GROUP BY e.entry_did
HAVING att_count >= 3;

Recursive lineage

example.mql

WITH RECURSIVE descendants(did, depth) AS (
  SELECT 'did:oas:l1fe:hmr:jared-rice', 0
  UNION ALL
  SELECT child.did, descendants.depth + 1
  FROM lineage child
  JOIN descendants ON child.parent = descendants.did
  WHERE depth < 8
)
SELECT * FROM descendants ORDER BY depth;

Bond health check

example.mql

SELECT entry_did, bond_amount, bond_tier
FROM entries
WHERE bond_status = 'expiring_soon'
  AND publisher_did IN (
    SELECT did FROM enr WHERE namespace = 'l1fe'
  );

Grammar

MARS-QL is a strict superset of SQL-92. Add three reserved words — DID, LINEAGE, ATTESTED_BY — plus the CONTAINS array operator.

Full BNF grammar →

grammar.bnf

<query>      ::= <select> | <with-recursive>
<select>     ::= 'SELECT' <columns> 'FROM' <source>
                  [ 'WHERE' <predicate> ]
                  [ 'GROUP BY' <columns> ]
                  [ 'HAVING' <predicate> ]
                  [ 'ORDER BY' <columns> [ 'ASC' | 'DESC' ] ]
                  [ 'LIMIT' <integer> ]
<source>     ::= <table> | <subquery> | <lineage-traversal>
<lineage-traversal> ::= 'LINEAGE' '(' <did> [ ',' <integer> ] ')'
<predicate>  ::= <comparison> | <in-list> | <contains>
                | <attested-by>
<contains>   ::= <expr> 'CONTAINS' <literal>
<attested-by>::= <expr> 'ATTESTED_BY' <did> [ 'TYPE' <literal> ]
<did>        ::= 'did' ':' <namespace> ':' <kind> ':' <name> [ '@' <version> ]