qql 0.5.0

QQL runtime and executor for Qdrant REST and gRPC
Documentation
#[cfg(any(feature = "rest", feature = "grpc"))]
use std::sync::atomic::{AtomicU64, Ordering};
#[cfg(any(feature = "rest", feature = "grpc"))]
use std::time::{SystemTime, UNIX_EPOCH};

use async_trait::async_trait;
use qql_core::error::QqlError;
use qql_plan::types::ReadConsistencyParam;
use qql_plan::{QueryBatchRequest, UpdateBatchRequest};

use crate::executor::response::BackendResponse;

pub use crate::backend::CollectionInfo;

/// HTTP header / gRPC metadata key Qdrant echoes into its logs for request
/// correlation (`x-request-id`). QQL generates one per request so a
/// misbehaving server response can be traced in Qdrant's own log lines.
pub const REQUEST_ID_HEADER: &str = "x-request-id";

// Error-code prefix → owning crate registry.
//
// Codes are `QQL-<AREA>-<DETAIL>` (kebab, uppercase); SDK exception classes
// key off [`ErrorKind`](qql_core::error::ErrorKind), never the code string,
// so renames stay behavior-compatible. Bare (unsuffixed) codes are retired —
// transports, backend reads, script splitting, and file IO now use suffixed
// codes (`QQL-TRANSPORT-BUILD` / `QQL-TRANSPORT-REQUEST`, `QQL-BACKEND-READ`,
// `QQL-PARSE-DELIMITER`, `QQL-CLI-IO`).
//
// - `QQL-LEX-*`, `QQL-PARSE-*` (grammar), `QQL-BIND-*`, `QQL-VALIDATION-*` →
//   `qql-core` (parser, params, validation).
// - `QQL-PLAN-*`, `QQL-REST-*` → `qql-plan` (planner, REST projection).
// - `QQL-EMBEDDING-*`, `QQL-VECTOR-KIND`, `QQL-MISSING-USING`,
//   `QQL-RERANK-*`, `QQL-UNKNOWN-VECTOR` → `qql-embed` (resolution);
//   the runtime `HttpEmbedder` reuses `QQL-EMBEDDING` for endpoint failures.
// - `QQL-TRANSPORT-*`, `QQL-TIMEOUT` → `qql-runtime` transports (`rest.rs`,
//   `snapshots.rs`).
// - `QQL-BACKEND-*` → `qql-runtime` backend adapters (REST/gRPC envelopes).
// - `QQL-GRPC-*` → `qql-runtime` proto conversion (`grpc_route`).
// - `QQL-EDGE-*` → `qql-edge` engine only, except `QQL-EDGE-CONFIG`
//   (sanctioned: the CLI's `qql config edge` surface in
//   `qql-cli/src/config.rs`) — never constructed elsewhere.
// - `QQL-CLI-*`, `QQL-PARSE-DELIMITER` (script splitting) → `qql-cli`.
// - `QQL-CONFIG` (runtime `config.rs`, load and save paths) is grandfathered:
//   renaming a stable user-facing code buys nothing. The bare execution code
//   exists only in test doubles (outside the `check-error-codes.sh` scan
//   roots) and stays out of the contract.

#[cfg(any(feature = "rest", feature = "grpc"))]
static REQUEST_SEQ: AtomicU64 = AtomicU64::new(0);

/// Generate a process-unique request id: `qql-<nanos><seq>` — no external
/// uuid dependency, globally unique and monotonic for log correlation.
#[cfg(any(feature = "rest", feature = "grpc"))]
pub(crate) fn next_request_id() -> String {
    let seq = REQUEST_SEQ.fetch_add(1, Ordering::Relaxed);
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_nanos() as u64)
        .unwrap_or(0);
    format!("qql-{nanos:016x}{seq:04x}")
}

/// Named vectors a collection exposes for dense, sparse, and rerank usage.
#[derive(Debug, Clone)]
pub struct VectorTopology {
    /// Default dense vector name, when the collection has named dense vectors.
    pub dense_vector: Option<String>,
    /// Sparse vector name, when the collection defines sparse vectors.
    pub sparse_vector: Option<String>,
    /// Multivector (ColBERT) vector name used for rerank, when present.
    pub rerank_vector: Option<String>,
}

#[cfg(not(target_arch = "wasm32"))]
/// Send/Sync bound helper for `QdrantOps` backends on native targets.
///
/// WASM builds are single-threaded, so the `wasm32` twin below drops the
/// bounds (via `async_trait(?Send)` on the trait); native targets keep
/// `Send + Sync` so backends move across threads. Mirrors the
/// `EmbedderBound` twin in `qql-embed` for the same reason — one shim per
/// trait, no shared abstraction (each documents its own target split).
pub trait QdrantOpsBound: Send + Sync {}
#[cfg(not(target_arch = "wasm32"))]
impl<T: Send + Sync> QdrantOpsBound for T {}

#[cfg(target_arch = "wasm32")]
/// Single-threaded bound helper for `QdrantOps` backends on wasm32.
pub trait QdrantOpsBound {}
#[cfg(target_arch = "wasm32")]
impl<T> QdrantOpsBound for T {}

/// Backend contract every transport adapter implements: DDL and metadata
/// methods, single planned-operation dispatch, and the two batch entry points.
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait QdrantOps: QdrantOpsBound {
    /// Flush and release backend resources. Network backends may use the
    /// default no-op; embedded backends should override this method.
    async fn close(&self) -> Result<(), QqlError> {
        Ok(())
    }

    /// List all collection names on the backend.
    async fn list_collections(&self) -> Result<Vec<String>, QqlError>;
    /// Whether a collection with this name exists.
    async fn collection_exists(&self, name: &str) -> Result<bool, QqlError>;
    /// Fetch typed collection metadata, including the vector/index schema.
    async fn get_collection_info(&self, name: &str) -> Result<CollectionInfo, QqlError>;
    /// Create a collection from a planned DDL request.
    async fn create_collection(
        &self,
        collection_name: &str,
        req: &qql_plan::CreateCollectionRequest,
    ) -> Result<(), QqlError>;
    /// Update collection parameters from a planned DDL request.
    async fn update_collection(
        &self,
        collection_name: &str,
        req: &qql_plan::UpdateCollectionRequest,
    ) -> Result<(), QqlError>;
    /// Drop a collection and all of its points.
    async fn delete_collection(&self, name: &str) -> Result<(), QqlError>;
    /// Create a payload field index on a collection.
    async fn create_field_index(
        &self,
        collection_name: &str,
        req: &qql_plan::CreateIndexRequest,
    ) -> Result<(), QqlError>;
    /// Drop a payload field index from a collection.
    async fn delete_field_index(
        &self,
        collection_name: &str,
        field_name: &str,
    ) -> Result<(), QqlError>;

    /// Execute a pre-planned operation and return its typed payload.
    ///
    /// REST backends project `PlannedOperation` → `to_rest_route` → HTTP and
    /// strictly parse the per-operation OpenAPI shape at the transport
    /// boundary. gRPC/edge convert proto / `qdrant-edge` values straight into
    /// [`BackendResponse`].
    async fn execute_planned(
        &self,
        op: &qql_plan::PlannedOperation,
    ) -> Result<BackendResponse, QqlError>;

    /// Send multiple `QueryRequest`s to the same collection in one network call
    /// via Qdrant's `/points/query/batch` (REST) or `QueryBatch` (gRPC) endpoint.
    /// Returns one typed response per search, in order.
    ///
    /// `timeout` / `consistency` are the batch-level query params (one pair
    /// per batch RPC — members cannot carry their own). Ambient statement
    /// groups pass the group's shared opts (differing members never co-group);
    /// explicit `BATCH` blocks pass their header opts.
    async fn execute_query_batch(
        &self,
        collection: &str,
        batch: &QueryBatchRequest,
        timeout: Option<u64>,
        consistency: Option<ReadConsistencyParam>,
    ) -> Result<Vec<BackendResponse>, QqlError>;

    /// Apply a series of point mutations in one network call via Qdrant's
    /// `POST /points/batch` (REST) or `UpdateBatch` (gRPC) endpoint.
    /// Returns one typed response per operation, in order.
    ///
    /// Explicit `BATCH` blocks pass their header `WAIT` (default `true`);
    /// ambient statement groups pass the group's effective `wait` (members
    /// with differing `wait` never co-group, so no member's semantics change
    /// by being batched).
    async fn execute_update_batch(
        &self,
        collection: &str,
        batch: &UpdateBatchRequest,
        wait: bool,
    ) -> Result<Vec<BackendResponse>, QqlError>;

    /// Atomically update collection aliases (`POST /collections/aliases`).
    ///
    /// Default rejects: edge and custom backends have no alias table.
    async fn change_aliases(&self, _actions: &[AliasAction]) -> Result<(), QqlError> {
        Err(QqlError::validation(
            "QQL-VALIDATION-ALIASES",
            "collection aliases are not supported on this backend",
            None,
        ))
    }

    /// Run backend storage optimizers (segment merge / index build). Default:
    /// unsupported — only an in-process backend has an optimizer to run.
    async fn optimize_collection(&self, _collection: &str) -> Result<bool, QqlError> {
        Err(QqlError::validation(
            "QQL-BACKEND-OPTIMIZE",
            "optimize is not supported by this backend",
            None,
        ))
    }
}

/// One action in a Qdrant alias batch (`ChangeAliasesOperation`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AliasAction {
    /// Remove an alias name.
    Delete {
        /// Alias to delete.
        alias: String,
    },
    /// Point an alias at a collection.
    Create {
        /// Collection the alias should resolve to.
        collection: String,
        /// Alias name.
        alias: String,
    },
}