MARS-QL

MARS-QL queries begin with DISCOVER, followed by a canonical entry type or *.

DISCOVER AgentDefinition WHERE tags CONTAINS "research" LIMIT 20

Send the string as { "query": "..." } to POST /v1/discover/marsql. The response contains complete matching entries and pagination metadata. POST /v1/discover is the structured JSON alternative.

Supported operations

Conditions combine with AND. Comparison operators, membership operations, allowlisted field paths, ordering, bounded limits, and opaque keyset cursors are supported. SQL joins, OR, aggregation, and CTEs are not part of the language.

Pagination

OFFSET means an opaque, expiring HMAC-authenticated cursor; it is not a numeric row offset. Reuse the server's returned cursor with the same query and sort. Treat expiry or query mismatch as a restart of the query. Do not manufacture or edit cursor contents.

Limits

The protocol caps query text at 8192 bytes, conditions at 32, and dotted field depth at 16. Server planning validates types, fields, limits, and cursor scope before accessing the store.

Source authority

This page describes the checked-in implementation, not the availability of a public registry.

• mars-protocol/src/marsql/parser.rs
• mars-protocol/src/marsql/ast.rs
• mars-server/src/search.rs