qql-plan
Typed lowering from QQL AST to transport-neutral [PlannedOperation] — the canonical
source of truth for every supported statement. REST routes are a projection
([to_rest_route]) of a PlannedOperation; gRPC converts the same typed
operation without reverse-engineering JSON shapes.
AST (qql-core::ast::Stmt)
│
└─plan()─→ PlannedOperation (canonical; BatchFamily, collection, shard_key)
│
├─to_rest_route()─→ Route { method, path, query, body } (REST projection)
├─gRPC: match PlannedOperation → protobuf via grpc_route (direct typed → proto)
└─mutation batch: lower_update_operation() → UpdateOperation
Architecture
plan() — the single planner entry point
use Parser;
use ;
let stmt = parse?;
let op = plan?; // → PlannedOperation::Query { .. }
let route = to_rest_route; // → Route (REST projection)
The [plan] function returns a [PlannedOperation] enum with 21 variants
covering all query, mutation, and DDL operations. Each variant carries typed
request parameters (not raw JSON).
PlannedOperation variants
| Variant | Statement | Transport | Batch family |
|---|---|---|---|
Query / QueryGroups / GetPoints |
QUERY | POST /collections/{c}/points/query[/groups] | Query (when batchable) |
Scroll |
SCROLL | POST /collections/{c}/points/scroll | Single |
Count |
COUNT | POST /collections/{c}/points/count | Single |
Upsert |
UPSERT | PUT /collections/{c}/points | Mutation |
Delete |
DELETE | POST /collections/{c}/points/delete | Mutation |
ClearPayload |
CLEAR PAYLOAD | POST /collections/{c}/points/payload/clear | Mutation |
UpdateVectors |
UPDATE SET VECTOR | PUT /collections/{c}/points/vectors | Mutation |
DeleteVectors |
DELETE VECTOR | POST /collections/{c}/points/vectors/delete | Mutation |
UpdatePayload |
UPDATE SET PAYLOAD | POST /collections/{c}/points/payload | Mutation |
CreateCollection |
CREATE COLLECTION | PUT /collections/{c} | Single |
UpdateCollection |
ALTER COLLECTION | PATCH /collections/{c} | Single |
DropCollection |
DROP COLLECTION | DELETE /collections/{c} | Single |
CreateIndex |
CREATE INDEX | PUT /collections/{c}/index | Single |
DropIndex |
DROP INDEX | DELETE /collections/{c}/index/{field} | Single |
CreateShardKey / DropShardKey |
CREATE/DROP SHARD KEY | PUT /collections/{c}/shards | Single |
ListShardKeys |
SHOW SHARD KEYS | GET /collections/{c}/shards | Single |
ListCollections |
SHOW COLLECTIONS | GET /collections | Single |
GetCollection |
SHOW COLLECTION | GET /collections/{c} | Single |
Route — REST projection
Route is a transport-agnostic HTTP descriptor { method, path, query, body }.
The body is an untagged RequestBody enum whose #[serde(untagged)]
serialization matches Qdrant's OpenAPI wire format exactly.
REST routes are produced by to_rest_route(). New code should use
plan() + to_rest_route() or try_route() (fallible combination).
gRPC conversion
gRPC routes bypass Route entirely. The runtime's grpc_route::execute_grpc_route
reads Route.body (which carries the same typed request data produced by the planner)
and maps directly to protobuf. All 21 operation variants are supported.
Batch compatibility
PlannedOperation::batch_family() determines adjacency-based batching:
- Query: contiguous same-collection
Query→QueryBatchRequest - Mutation: contiguous same-collection Upsert/Delete/ClearPayload/DeleteVectors/UpdateVectors/UpdatePayload →
UpdateBatchRequest - Single: everything else (DDL, Scroll, Count) — never batched
Key types
All typed request types live in [crate::types]:
| Type | Purpose |
|---|---|
QueryRequest / QueryGroupsRequest |
Search with variant, filters, params |
PointsRequest |
Point ID lookup (QUERY POINTS) |
ScrollRequest |
Scrolling with optional filter |
UpsertRequest / UpsertPointRequest |
Point insertion with optional vectors |
DeleteRequest |
By ID list or filter |
UpdateVectorRequest / UpdatePayloadRequest |
Point-level vector/payload mutation |
ClearPayloadRequest / DeleteVectorRequest |
Payload/vector removal |
CountRequest |
Count with filter and shard key |
CreateCollectionRequest |
Collection configuration |
CreateIndexRequest |
Field index with per-schema params |
CreateShardKeyRequest / DropShardKeyRequest |
Shard key management |
QueryBatchRequest / UpdateBatchRequest |
Batch wire formats |
UpdateOperation |
Single mutation in an UpdateBatchRequest |
FilterExpression / FilterClause |
Lowered filter AST |
SearchParamsRequest / AcornSearchParams |
Search parameters |
QueryVariant |
Typed query expression (nearest/recommend/context/fusion/…) |
Semantic types (typed until transport)
These types preserve semantic distinctions that JSON shape inference cannot recover:
PlanPointId:Number(u64)orString— serialized as bare number or stringPlanVectorValue:Dense,Sparse { indices, values }, orMultiDensePlanQueryInput:Point,Vector, orDocument { text, model }PlanPointVectors:Unnamed(PlanVectorValue)orNamed(Vec<(String, PlanVectorValue)>)PlanFormula: typed formula tree — REST uses snake_case OpenAPI keys via custom serialization
Plan lowering modules
| Module | Lowers |
|---|---|
ddl |
CreateCollection, AlterCollection, CreateIndex |
mutation |
Upsert, Delete, Scroll, ClearPayload, DeleteVector, UpdateVector, UpdatePayload |
query |
Query expressions, prefetch, formula, search params |
filter |
Filter expressions: comparison, range, match, geo, nested, has_id, has_vector |
embedding |
Embedding job extraction for embedder dispatch |
Features
serde(default): JSON serialization for all request/response typesstd(default):std::error::Errorimplsalloc(always): used forVec,String
Verification