qql-convert
Qdrant REST JSON to QQL statement converter.
Proposition
Migrate REST code to QQL without hand-translation. The converter is contract-driven and AST-based:
OpenAPI request JSON -> qql_core::ast::Stmt -> qql_core::fmt::format_stmt
Every emitted string comes from the canonical QQL formatter (the same emitter
behind qql fmt), so it re-parses and is byte-stable under
format_stmt(parse(emit)). Decoding fails closed: shapes the QQL AST cannot
express return a typed ConvertError instead of a placeholder or a silently
dropped field.
Install
CLI entry point (no library code needed for one-off migration):
# ... or from a local checkout:
# cargo build --release -p qql-cli
Quick start
let stmts = convert.unwrap;
assert_eq!;
Bare bodies without a collection return ConvertError::MissingCollection.
# Wrapped request (method + path + body) — collection derived from the path
|
# Bare body — caller supplies the collection
|
# JSONL capture from `qql record` — one request per line
Pair with the recorder for zero-code-change capture (see the
qql-cli recorder):
# ... run the app ...
Input shapes
- Wrapped request —
{"method", "path", "query"?, "body"?}; the collection is derived from the path.queryrecoverswait/timeout/consistency(also accepted as a?…suffix onpath). - Bare body — raw Qdrant REST JSON without path context; the caller must
supply the collection. Ambiguous shapes fail with
UndecodableBody. - JSONL capture — one wrapped request or bare body per line (
qql record --out). Selected when the buffer is not a single JSON value. - HTTP snippet — a
METHOD /pathline plus a JSON body, exactly as docs and blogs print it. Full URLs and anHTTP/xsuffix are accepted, and several snippets may follow each other (blank lines optional):POST /collections/docs/points/query {"query": {"nearest": [0.1, 0.2]}, "using": "dense", "limit": 5} curlcommand — a pasted invocation, including multi-line\-continuations,-X/--request,-d/--data*/--json,--header, and several commands separated by newlines or;:
A missing|-Xinfers the method (--dataimplies POST, else GET).
Markdown fences around any of the above are stripped as paste noise.
Paste shapes reuse the same lowering as wrapped requests, so they cannot
drift. Anything shell-dynamic fails closed instead of guessing: $VAR /
$(…) / backticks, --data @file (paste the JSON inline), | / & /
subshells, and --data-urlencode / --config / -T file flags. Collection
segments that look like placeholders (<your-collection>,
{collection_name}, $COLLECTION) are rejected with InvalidField on every
path — including --collection — rather than emitting QQL that cannot
re-parse.
Errors
convert / convert_stmts return ConvertError — never a placeholder string:
| Variant | Meaning |
|---|---|
InvalidJson |
Input is not valid JSON (holds the parse message) |
UnsupportedEndpoint |
Wrapped request targets an endpoint with no QQL mapping (holds "METHOD path") |
MissingCollection |
Bare body without a collection name (--collection) |
UndecodableBody |
Body absent or structurally undecodable for the endpoint (holds a reason) |
InvalidField |
Recognized body with an invalid/unrepresentable field (holds path + reason) |
InvalidLine |
A JSONL line failed (holds the 1-based line number + source error) |
Contract sources
crates/qql-runtime/openapi.json— request schemas per path (the input contract; asserted bytests/contract.rs).crates/qql-plan— the inverse lowering.tests/route_parity.rsplans a corpus (everyQueryExprvariant, mutations, DDL, andbench/queries.json), converts its REST body and query string back to QQL, re-plans, and asserts the two routes are identical.
Docs
Test