What it does
KynQL is a short pipeline for reading one collection: from, where, select, sort, limit and offset, separated by a pipe or a newline. POST /v1/query parses it into a typed plan and runs it under the caller collection permissions and row-level policies. It has no write verbs, and the parser enforces limits on query size, nesting depth and page size.
How it works
A query is a sequence of clauses split on | or on newlines, and each clause may appear once. from names the collection. where holds predicates joined by and and or, with parentheses; a predicate is a field path, one of ==, !=, >, >=, <, <= or contains, and a string, number, true, false or null. select lists dotted field paths or *. sort takes one field and an optional asc or desc. limit runs from 1 to 500 and defaults to 50; offset is a non-negative integer. Lines that start with # are comments. A write verb such as delete, an unknown clause, a duplicate clause or an oversized limit is refused at parse time.
The parser rejects queries larger than 64 KiB and expressions nested deeper than 32 levels. The parse result is a typed plan that is echoed in the response, so a client can see exactly what was understood.
Execution authorises before it reads. The caller must be allowed to list the collection, and a where, select or sort that names a field hidden from the caller role is refused as forbidden instead of being evaluated, which closes the side channel a hidden field would otherwise offer. The server then loads the collection records for the caller project, applies the where expression in memory, evaluates row-level security per row for non-service callers, sorts (newest update first when no sort is given; numbers compare numerically and everything else as text) and slices the page. total is the number of matches before paging.
Unlike the raw entity routes, this route runs for end-user tokens as well as service keys, within the collection rules, so a browser or mobile client can call it directly when the collection permits listing.
While the engine is fenced for recovery, the route returns the typed 503 refusal. A failed schema read or a failed row scan is reported as a schema error, never as an unknown collection or an empty result.
Where you reach it
- HTTP
POST /v1/query { query }
Example
curl -s "$KYNETRA_URL/v1/query" \
-H "Authorization: Bearer $KYNETRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "from orders | where status == \"paid\" and total >= 1000 | select id, customer, total | sort total desc | limit 100" }'
# response: ok, language, version, plan, columns, rows, total, returned, elapsed_msLimits
- A query reads the whole collection and filters in memory, so cost is linear in collection size whatever the where clause says. Indexes declared on a collection are not consulted.
- There is no not operator, no membership test, no join, no grouping or aggregate and no text-search predicate. Use the search routes for text and vectors.
- A page holds at most 500 rows.
- KynQL is not exposed through the MCP tools or the client SDKs; the HTTP route is the surface.
Evidence
- On this siteHTTP API reference
- Tests12 test functions cover parsing and precedence, refusal of writes and oversized or deeply nested queries, project scoping, hidden-field side channels, and typed errors for schema faults, scan faults and recovery fences; the route is also in the recovery-refusal HTTP battery
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.