qql/lib.rs
1//! QQL executor and Qdrant transport adapters (published as the `qql` crate).
2//!
3//! One executor API over three transports:
4//!
5//! ```text
6//! source text
7//! → qql-core: parse + semantic validation
8//! → prepare: schema USING resolution + embedding inference (qql-embed)
9//! → qql-plan: plan() → PlannedOperation (transport-neutral IR)
10//! → batch classification / dispatch
11//! → REST (rest) | gRPC (grpc) | in-process edge (qql-edge)
12//! ```
13//!
14//! Backends implement the [`client::QdrantOps`] contract (11 methods); the
15//! [`executor::Executor`] drives it. DDL flows through the same planner as
16//! DML. The gRPC path converts typed plan structs directly to protobuf —
17//! query vectors, point IDs, DDL request configs, and formula expressions
18//! never take a JSON detour.
19//!
20//! # Features
21//!
22//! - `rest` (default) — HTTP transport adapter ([`rest::RestQdrant`])
23//! - `grpc` (default) — tonic-based gRPC transport ([`grpc::GrpcQdrant`])
24//! - With both disabled, custom [`client::QdrantOps`] implementations still
25//! compile against the executor with no transport dependency.
26//!
27//! # Public API re-exports
28//!
29//! Types named in this crate's signatures — [`QqlError`], [`Stmt`],
30//! [`PlannedOperation`], the batch and DDL request types — plus the policy
31//! flow ([`Parser`], [`inject_filter`], [`ComparisonOp`], [`Value`]) are
32//! re-exported here, so `QdrantOps` implementors and policy authors depend on
33//! `qql` alone. Deeper IR introspection is advanced territory; add
34//! `qql-plan` / `qql-core` directly when you need it.
35//!
36//! # Errors
37//!
38//! Execution failures are structured `QqlError` values from `qql-core` with
39//! stable codes (`QQL-EXECUTION-*`, `QQL-TRANSPORT-*`, `QQL-BACKEND`, …).
40
41pub mod backend;
42/// The `QdrantOps` backend contract plus REST/gRPC client plumbing shared by
43/// the transport adapters.
44pub mod client;
45/// Endpoint, API key, and timeout configuration ([`QqlConfig`](config::QqlConfig)).
46pub mod config;
47/// Remote embedding-server adapter ([`HttpEmbedder`](embedder::HttpEmbedder))
48/// implementing the `qql-embed` [`Embedder`](embedder::Embedder) trait.
49pub mod embedder;
50/// Reqwest `HttpEmbedder` client, split from [`embedder`].
51#[cfg(feature = "rest")]
52mod embedder_http;
53/// The executor: parse → prepare → plan → batch → dispatch.
54pub mod executor;
55/// Tonic channel client and typed protobuf conversions for the gRPC transport.
56#[cfg(feature = "grpc")]
57pub mod grpc;
58/// gRPC route execution: typed plan structs converted directly to protobuf.
59#[cfg(feature = "grpc")]
60mod grpc_route;
61/// Typify-generated REST wire types from `openapi.json` (build-time output;
62/// do not edit).
63pub mod qdrant;
64/// Tonic-generated protobuf types from `proto/` (build-time output; do not
65/// edit).
66#[cfg(feature = "grpc")]
67pub mod qdrant_grpc;
68/// REST transport adapter ([`RestQdrant`](rest::RestQdrant)) implementing
69/// `QdrantOps` over JSON HTTP.
70#[cfg(feature = "rest")]
71pub mod rest;
72/// REST client construction (`RestQdrant` constructors), split from [`rest`].
73#[cfg(feature = "rest")]
74mod rest_client;
75/// Strict per-operation REST response parsing (OpenAPI shapes only, no
76/// fallbacks). Used exclusively by the REST transport.
77#[cfg(feature = "rest")]
78mod rest_response;
79/// Remote shard-snapshot client for edge bootstrap (REST only, not part of
80/// the `QdrantOps` contract).
81#[cfg(feature = "rest")]
82pub mod snapshots;
83/// Sparse vector helpers re-exported from `qql-embed` (wire-compatible BM25).
84pub mod sparse;
85
86// Public-API re-exports (Rust API guidelines C-REEXPORT): every type named in
87// this crate's public signatures, plus the parse → inject policy flow, is
88// reachable through `qql` alone — backend and policy authors need no direct
89// `qql-core` / `qql-plan` dependency.
90pub use executor::PreparedStatement;
91pub use qql_core::ast::{ComparisonOp, Stmt, Value, VectorValue, inject_filter};
92pub use qql_core::error::{ErrorKind, QqlError, Span};
93pub use qql_core::parser::Parser;
94pub use qql_plan::{
95 CreateCollectionRequest, CreateIndexRequest, PlanFacetValue, PlanGroupId, PlanPointId,
96 PlanShardKey, PlanVectorStruct, PlanVectorValue, PlannedOperation, QueryBatchRequest,
97 QuotaConfig, UpdateBatchRequest, UpdateCollectionRequest,
98};
99
100// Sparse unit tests live in `qql-embed` (shared implementation).
101
102// Contract tests exercise the typed gRPC route converters alongside the
103// OpenAPI REST schemas; gRPC is required for the parity half.
104#[cfg(all(test, feature = "grpc"))]
105mod contract_test;
106#[cfg(test)]
107mod executor_test;