Search & retrieval

KynQL query language

Gives clients a readable way to filter, project, sort and page one collection without exposing a general query language.

Available in previewEngine edition 5f8ea3af

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

  • HTTPPOST /v1/query { query }

Example

Paid orders over a threshold, largest firstbash
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_ms

Limits

  • 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.