Get started

MARS-QL

Find what fits.Inspect what you find.

A small, expressive language for discovering complete registry records. Start with a capability, refine the context, and keep the publisher, payload, and history within reach.

  • Typed discovery
  • Complete records
  • Bounded results
A closer lookFind the right thing in a bigger world.

A bounded query filters a catalog into useful results. Ordering and pagination keep the response inspectable.

  1. 01Define what you need
  2. 02Filter the catalog
  3. 03Inspect the results

01 / queries

A useful question is a good start.

Every query begins with DISCOVER. Use one of the fourteen entry types or the wildcard, then add only the conditions you need.

Find the right capability.

example.mql
DISCOVER AgentDefinition
WHERE tags CONTAINS "research"
ORDER BY published_at DESC
LIMIT 25

Choose an entry type, match a tag, and start with the most recently published records.

Inspect attached evidence.

example.mql
DISCOVER ModelDefinition
WHERE attestation_count >= 3
ORDER BY attestation_count DESC
LIMIT 25

Filter by attestation count, then inspect the credentials and their issuers in each returned record.

Follow one identity root.

example.mql
DISCOVER *
WHERE human_root = "did:oas:example:hmr:publisher"
ORDER BY published_at DESC
LIMIT 25

Match optional stored human-root lineage across all supported entry types.

Combine your requirements.

example.mql
DISCOVER ServiceDefinition
WHERE bond_amount >= 100
  AND status = "active"
ORDER BY bond_amount DESC
LIMIT 25

Require an active service and a registry bond amount above a chosen threshold.

Examples describe filters, not quality guarantees. Three attestations need not mean three independent issuers, and a bond amount represents the registry’s configured bond policy.

02 / language

Small enough to reason about.

Conditions combine with AND. Comparisons and set membership cover the core questions without turning a registry into an open-ended SQL engine.

Filter supported fields including tags, publisher, lifecycle, version, lineage, bond amount, and nested item metadata. Choose explicit ordering and a bounded result count.

The grammar intentionally omits SQL tables, projections, joins, CTEs, OR, aggregation, and subqueries. Each result is a complete MarsEntry, ready to inspect or resolve.

OFFSET accepts an opaque continuation cursor. It is not a numeric row offset.

grammar excerpt
<query>      ::= 'DISCOVER' <entry-type>
                  [ 'WHERE' <conditions> ]
                  [ 'ORDER BY' <ordering> ]
                  [ 'LIMIT' <integer> ]
                  [ 'OFFSET' <string> ]
<conditions> ::= <condition> { 'AND' <condition> }
<condition>  ::= <field> <operator> <value>
               | <field> 'CONTAINS' <value>
               | <field> 'CONTAINS_ALL' <value-list>
               | <field> 'CONTAINS_ANY' <value-list>
               | <field> 'IN' <value-list>
<operator>   ::= '=' | '!=' | '>' | '>=' | '<' | '<='

03 / pagination

Pick up where the query left off.

  1. 01

    Ask

    Send your MARS-QL text to POST /v1/discover/marsql in the query field.

  2. 02

    Inspect

    Read entries and totalCount. The page also reports hasMore and an optional cursor.

  3. 03

    Continue

    When hasMore is true, pass the returned cursor as the same query’s quoted OFFSET.

  4. 04

    Stay bounded

    Cursors are signed, expire, and are bound to the query. Restart the query if its cursor is no longer valid.