qql-runtime (crate name qql)
Execution engine for QQL. Parses via qql-core, lowers via qql-plan,
resolves embeddings via qql-embed, and dispatches to Qdrant through an
abstract QdrantOps trait over REST, gRPC, or edge backends.
Canonical execution flow: prepare → plan → batch → dispatch
Statement string
│
▼ [1] Parse (qql-core Parser → Stmt)
│
▼ [2] PREPARE
│ ├─ resolve_embeddings: text → vectors (if embedder registered)
│ ├─ resolve vector targets: validate names and infer roles from collection schema
│ └─ ensure_collection_for_upsert: auto-create default schema
│
▼ [3] Plan (qql_plan::plan::plan → PlannedOperation)
│ └─ Transport: to_rest_route (REST) or match PlannedOperation → protobuf (gRPC)
│
▼ [4] Batch classify (same-collection adjacency)
│ ├─ 2+ contiguous QUERY → QueryBatch (POST /points/query/batch)
│ ├─ 2+ contiguous mutations → UpdateBatch (POST /points/batch)
│ └─ single/other → dispatch_prepared
│
▼ [5] DISPATCH
├─ REST: reqwest (Route → JSON)
├─ gRPC: tonic (PlannedOperation → protobuf)
└─ Edge: qdrant-edge (in-process HNSW)
This flow is implemented in Executor::execute_node and Executor::execute_batch_nodes.
QdrantOps Trait
The single unified backend interface:
Provided Implementations
| Backend | Crate | Transport | Connection |
|---|---|---|---|
RestQdrant |
qql (this crate) |
HTTP REST via reqwest |
http://localhost:6333 |
GrpcQdrant |
qql (this crate) |
raw gRPC via tonic 0.14 |
http://localhost:6334 |
EdgeQdrant |
qql-edge |
in-process HNSW (qdrant-edge) |
none |
API key & timeout
// REST — 30s default
let rest = new;
// REST — explicit timeout
let rest = with_timeout?;
// gRPC — default timeout (sync constructor, no .await)
let grpc = from_url?;
// gRPC — explicit timeout (sync constructor, no .await)
let grpc = from_url_with_timeout?;
API keys are sent via api-key header (REST) or ApiKeyInterceptor (gRPC tonic metadata).
Pass None or "" for unauthenticated Qdrant.
Executor
Single entry point for parsing, embedding, batching, and dispatch:
use Arc;
use ;
use RestQdrant;
use HttpEmbedder;
let rest_ops = Boxnew;
let embedder = new;
let executor = with_embedder;
// DDL
executor.execute.await?;
// Upsert with auto-embedding
executor.execute.await?;
// Query with auto-embedding
let response = executor.execute.await?;
prepare_statement — shared preparation
The prepare_statement method (called before every execute_node and in
execute_batch_nodes) performs:
resolve_embeddings: text → dense/sparse vectors (if embedder registered)- vector target resolution: validates named targets and infers dense/sparse roles from collection schema; ambiguous schemas fail closed
ensure_collection_for_upsert: for UPSERT — auto-creates collection with default dense/hybrid schema when embedding model is specified
Batch execution — strict cardinality
execute_batch_nodes groups contiguous same-collection operations into
wire-level batch calls. Response count must exactly match operation count:
3 contiguous QUERY ops → QueryBatchRequest → must return 3 results
Mismatch → QQL-BATCH-CARDINALITY error
This is a strict check — old silent padding behavior has been removed.
Single-statement execution via execute_node is unaffected.
Response envelope normalization
All backends normalize Qdrant responses to a common envelope for the executor:
The raw Qdrant envelopes are validated:
| Backend | Validation |
|---|---|
| REST | validate_success_envelope() — checks result present + status == "ok" |
| gRPC | execute_grpc_route() synthesizes { result, status: "ok", time } from protobuf |
| Edge | mutation_response() produces { result: { status: "completed" }, status: "ok", time: 0.0 } |
Embedding providers
The Embedder trait abstracts text-to-vector generation:
HttpEmbedder: OpenAI-compatible REST endpoint (/v1/embeddings). Supports Ollama, OpenAI, vLLM, Text Embeddings Inference (TEI). Includes dimension probing.SparseEmbedder: Hash-based BM25 tokenizer — pure Rust, no external dependencies.
Features
default = ["grpc", "rest"]rest: HTTP REST client viareqwestgrpc: raw gRPC client viatonic0.14 with generated Protobuf schemas
Verification
# Unit tests (no Qdrant needed)
# With Qdrant running on localhost:6333
# Contract tests (REST vs gRPC consistency)