qql-runtime (crate name qql)
Execute QQL: parse → prepare/embed → plan → batch → REST or gRPC or edge.
Proposition
One executor API. Backends implement QdrantOps. Plan IR is shared; gRPC is
not a second-class path — execute_grpc_route converts typed plan structs
to protobuf (query vectors / IDs without a JSON detour).
Stmt
→ prepare (schema USING kinds + embeddings)
→ plan() → PlannedOperation
→ REST: to_rest_route → JSON
→ gRPC: PlannedOperation → protobuf
→ Edge: in-process HNSW (qql-edge)
Quick start
use Arc;
use ;
use RestQdrant;
use HttpEmbedder;
let ops = Boxnew;
let embedder = new;
let exec = with_embedder;
exec.execute.await?;
Convenience: Executor::rest(url, api_key) / Executor::grpc(url, api_key).
Local sparse (BM25) tuning
HttpEmbedder serves dense/multi/image/rerank over HTTP but always encodes
sparse documents locally (wire-compatible qdrant/bm25). Tune the document
encoder via HttpEmbedderOptions { bm25_k1, …, bm25_language, bm25_tokenizer, … } (or
QqlConfig.bm25_* for config-file hosts). Thirty languages, three local
tokenizers, folding, and length limits mirror Qdrant's Bm25Config; measure a
corpus-true avg_len with Executor::estimate_bm25_avg_len. Client-side and write-path only:
query weights stay unit, server-side inference is untouched, and vectors
already written keep their weights — re-ingest to apply. Unset = Qdrant
defaults (1.2 / 0.75 / 256); invalid values fail closed with
QQL-VALIDATION-CONFIG. Full host-surface table: qql-embed README.
QdrantOps
Unified backend trait (collections, indexes, execute_planned, query/update
batches). Implementations: RestQdrant, GrpcQdrant, EdgeQdrant (other crate).
| Backend | Port (typical) | Notes |
|---|---|---|
| REST | 6333 | OpenAPI 1.19.0 JSON body (openapi.json) |
| gRPC | 6334 | tonic + public protos in proto/ (1.19.0 pin) |
| Edge | n/a | qdrant-edge 0.8 (IDF + ACORN + GROUP BY yes; quotas / SHARD / LOOKUP FROM no) |
API key: REST header api-key; gRPC ApiKeyInterceptor.
Route affinity (client API, Qdrant ≥ 1.19)
Not part of QQL grammar — transport metadata only. Pins reads to a stable replica:
use RestQdrant;
// use qql::grpc::GrpcQdrant;
let ops = Boxnew;
// GrpcQdrant::with_route_affinity sends gRPC metadata x-qdrant-route-affinity
Empty strings are treated as unset. Host bindings expose the same option:
pyqql.Client(..., route_affinity=...), nqql new Client({ routeAffinity }),
and the WASM client.setRouteAffinity(key).
Quotas (REST only)
SHOW QUOTAS;
SET QUOTA (enabled = true, max_resident_memory_percent = 80,
max_disk_usage_percent = 90, release_margin_percent = 5) WAIT true;
| Backend | Result |
|---|---|
| REST | `GET |
| gRPC | QQL-GRPC-QUOTA — no public gRPC quota service |
| Edge | QQL-EDGE-UNSUPPORTED-QUOTA |
SET QUOTA is a full replace of the cluster config (omitted/null keys clear
limits in the replacement body).
Other 1.19 body features (memory, MATCH PREFIX, SLICE, idf, turbo4,
keyword prefix) flow through the shared plan IR on all backends that support
the corresponding Qdrant capability.
Prepare order
- Schema topology → fill
USINGdense/sparse/multi - Embeddings (
qql-embed) — fail closed on unknown kind (QQL-VECTOR-KIND) - Upsert collection prep when needed
Multitenancy at execute time
-- Isolation in language + routing
QUERY TEXT 'q' FROM t USING dense
WHERE tenant_id = 'acme' SHARD 'acme' LIMIT 10;
Hosts should still inject_filter untrusted QQL. Routing is request-level
shard_key / ShardKeySelector on both transports.
Features
default = ["grpc", "rest"] — either can be disabled.
Docs
Test
# live Qdrant: