qql-plan
Transport-neutral lowering: AST → PlannedOperation.
Proposition
One plan for every backend. REST is a projection (to_rest_route); gRPC
maps the same typed structs to protobuf. Never invent wire shapes in
bindings — plan here once.
Stmt (qql-core)
│ plan()
▼
PlannedOperation ← source of truth
├── filter → REST filter / gRPC Filter
├── shard_key → REST shard_key / gRPC ShardKeySelector
├── to_rest_route() → Route { method, path, query, body }
└── gRPC match arm → typed protobuf (runtime)
Filter never carries shard_key. Isolation and routing are siblings on the
request (OpenAPI + proto both model it that way).
Usage
use Parser;
use ;
let stmt = parse?;
let op = plan?;
let route = to_rest_route?; // fallible REST projection
// Prefer try_route(&stmt) when you want plan + projection in one call.
PlannedOperation (selected)
| Family | Variants |
|---|---|
| Search | Query, QueryGroups, GetPoints, Scroll, Count, Facet |
| Mutations | Upsert, Delete, ClearPayload, DeletePayload, UpdateVectors, DeleteVectors, UpdatePayload |
| DDL | CreateCollection, UpdateCollection, indexes, CreateShardKey / DropShardKey / ListShardKeys |
| Quotas | GetQuotas / SetQuotas → REST `GET |
| Client-side | CrossRerank (no single Qdrant route) |
Batch families
- Query — contiguous same-collection searches →
/points/query/batch(CrossRerankis Single) - Mutation — contiguous same-collection mutations, including
DELETE PAYLOAD→/points/batch - Single — DDL, scroll, count, facet, quotas,
CrossRerank, …
Semantic primitives
PlanPointId, PlanVectorValue (Dense / Sparse / MultiDense), PlanQueryInput,
typed formula trees — stay typed until a transport boundary.
MemoryPlacement / VectorDatatype re-exported from qql-core.
Typed formula (PlanFormula → proto / edge)
qql-plan/src/formula_types.rs owns the formula tree. REST serializes the
OpenAPI Expression straight from it; gRPC converts it directly via
plan_formula_to_grpc (PlanFormula → qdrant::Expression) with no JSON
round-trip (CASE conditions and datetime TARGET inference apply on gRPC
too). Edge maps $score to the reserved score variable and fails closed on
MAX / MIN / ACOSH (QQL-EDGE-UNSUPPORTED-FORMULA-FUNCTION).
Typed DDL IR (no JSON-as-IR)
Collection / index / quantization / optimizer configs are plan-owned typed
structs (DenseVectorParams, SparseVectorParams, CollectionParams,
MaxOptimizationThreads, IndexOptions, … in ddl_types / index_types /
quantization). REST serializes them to exact OpenAPI bodies (ddl_rest);
gRPC converts them directly to protobuf. Invalid tokenizer or field-type
values fail at plan time (QQL-PLAN-INDEX-TYPE, QQL-PLAN-INDEX-OPTION);
out-of-range DDL integers fail closed on gRPC (QQL-GRPC-DDL-RANGE).
Per-vector ALTER COLLECTION … WITH VECTOR <name> / WITH SPARSE <name>
diffs lower onto typed PATCH vectors / sparse_vectors maps
(QQL-PARSE-VECTOR-DIFF / QQL-PLAN-VECTOR-DIFF for datatype and
duplicates).
Qdrant 1.19 lowering notes
| Surface | Plan behavior |
|---|---|
SET QUOTA (…) |
Full replace body (SetQuotaRequest). Omitted keys / key = null are unset in the PUT body — not a merge of the previous config. Invalid keys/ranges → QQL-PLAN-QUOTA. Optional WAIT → query ?wait=. |
PARAMS (idf = …) |
'global' or WHERE <filter>; empty lowered corpus → QQL-PLAN-IDF. |
MATCH PREFIX / SLICE |
MatchValue::Prefix / SliceCondition on the filter IR. |
memory / payload_memory / datatype / keyword prefix |
Forwarded on collection, vector, HNSW, quantization, and index REST bodies. |
let op = plan?;
let route = to_rest_route?; // PUT /quotas?wait=true
Modules
Public crate surface. REST projection lives in routing; plan re-exports
to_rest_route / try_route so existing qql_plan::plan::* paths stay valid.
| Module | Role |
|---|---|
plan |
plan / plan_template → PlannedOperation. Re-exports to_rest_route, try_route. |
routing |
Route, to_rest_route, try_route, compile_statement |
query / mutation / ddl |
Lowering (including quotas / IDF / memory) |
filter |
FilterExpression only (no routing fields) |
formula_types |
PlanFormula OpenAPI Expression tree, FormulaDefault bindings |
types |
Request IR façade (SetQuotaRequest, IdfSearchParams, …) |
batch |
BatchGrouper, BatchKey, query/update batch builders |
semantic |
PlanPointId, PlanVectorValue, PlanQueryInput |
Docs
- AGENTS.md pipeline · Syntax · Multitenancy
Test