use std::collections::HashMap;
use std::sync::Arc;
use qql_core::ast::{self, Stmt, Value};
use qql_core::error::QqlError;
use qql_core::parser;
use crate::backend::CollectionInfo;
use crate::client::QdrantOps;
use crate::config::QqlConfig;
use crate::embedder::Embedder;
pub mod analyze;
pub(crate) mod batch;
pub mod ddl;
pub(crate) mod dispatch;
pub(crate) mod dml;
pub mod estimate;
pub(crate) mod normalize;
pub(crate) mod prepared;
pub(crate) mod response;
pub mod telemetry;
pub use prepared::PreparedStatement;
pub use qql_embed::resolve::{DENSE_VECTOR_NAME, SPARSE_VECTOR_NAME};
pub use response::{
AnalyzeReport, BackendResponse, ExecData, ExecResponse, ExecutionReport, FacetHit,
GroupedSearchResult, OnError, SearchHit, score_f64,
};
pub use telemetry::{
HardwareUsage, InferenceUsage, ModelUsage, PhaseTimings, ServerTelemetry, ServerUsage,
};
pub const RERANK_VECTOR_NAME: &str = "colbert";
pub const DENSE_MODEL_DEFAULT: &str = "sentence-transformers/all-minilm-l6-v2";
pub const SPARSE_MODEL_DEFAULT: &str = "qdrant/bm25";
pub const RERANK_MODEL_DEFAULT: &str = "answerdotai/answerai-colbert-small-v1";
pub const DENSE_VECTOR_SIZE: u64 = 384;
pub const RERANK_VECTOR_SIZE: u64 = 96;
pub const INFERENCE_MODE_DEFAULT: &str = "local";
pub(crate) type SchemaCacheEntry = (Arc<CollectionInfo>, Arc<qql_embed::TopologyNames>);
pub struct Executor {
pub(crate) client: Box<dyn QdrantOps>,
pub(crate) config: Option<QqlConfig>,
pub(crate) embedder: Option<Arc<dyn Embedder>>,
pub(crate) schema_cache: tokio::sync::RwLock<HashMap<String, SchemaCacheEntry>>,
closed: std::sync::atomic::AtomicBool,
close_lock: tokio::sync::Mutex<()>,
}
impl Executor {
#[cfg(feature = "rest")]
pub fn rest(url: impl Into<String>, api_key: Option<String>) -> Result<Self, QqlError> {
Ok(Self::new(
Box::new(crate::rest::RestQdrant::new(url, api_key)),
None,
))
}
#[cfg(feature = "grpc")]
pub fn grpc(url: impl Into<String>, api_key: Option<String>) -> Result<Self, QqlError> {
let url = url.into();
Ok(Self::new(
Box::new(crate::grpc::GrpcQdrant::from_url(&url, api_key)?),
None,
))
}
pub fn new(client: Box<dyn QdrantOps>, config: Option<QqlConfig>) -> Self {
Self {
client,
config,
embedder: None,
schema_cache: tokio::sync::RwLock::new(HashMap::new()),
closed: std::sync::atomic::AtomicBool::new(false),
close_lock: tokio::sync::Mutex::new(()),
}
}
pub fn with_embedder(
client: Box<dyn QdrantOps>,
config: Option<QqlConfig>,
embedder: Option<Arc<dyn Embedder>>,
) -> Self {
Self {
client,
config,
embedder,
schema_cache: tokio::sync::RwLock::new(HashMap::new()),
closed: std::sync::atomic::AtomicBool::new(false),
close_lock: tokio::sync::Mutex::new(()),
}
}
pub fn ops(&self) -> &dyn QdrantOps {
self.client.as_ref()
}
pub fn explain(query: &str) -> Result<String, QqlError> {
qql_core::explain::explain(query)
}
pub fn explain_all(query: &str) -> Result<String, QqlError> {
qql_core::explain::explain_all(query)
}
pub fn explain_node(stmt: &Stmt) -> Result<String, QqlError> {
Ok(qql_core::explain::explain_node(stmt))
}
pub fn client(&self) -> &dyn QdrantOps {
self.client.as_ref()
}
pub async fn close(&self) -> Result<(), QqlError> {
let _guard = self.close_lock.lock().await;
if self.closed.swap(true, std::sync::atomic::Ordering::SeqCst) {
return Ok(());
}
self.schema_cache.write().await.clear();
self.client.close().await
}
pub fn is_closed(&self) -> bool {
self.closed.load(std::sync::atomic::Ordering::SeqCst)
}
pub(crate) fn ensure_open(&self) -> Result<(), QqlError> {
if self.is_closed() {
Err(QqlError::execution(
"QQL-CLIENT-CLOSED",
"cannot execute query on a closed executor",
None,
))
} else {
Ok(())
}
}
pub fn embedder(&self) -> Option<&Arc<dyn Embedder>> {
self.embedder.as_ref()
}
pub fn config(&self) -> Option<&QqlConfig> {
self.config.as_ref()
}
pub fn request_timeout(&self) -> Option<u64> {
self.config.as_ref().and_then(|c| {
if c.request_timeout > 0 {
Some(c.request_timeout)
} else {
None
}
})
}
pub async fn execute(
&self,
query: &str,
on_error: OnError,
) -> Result<ExecutionReport, QqlError> {
self.ensure_open()?;
let statements = match parser::Parser::parse_all(query) {
Ok(statements) => statements,
Err(error) if matches!(on_error, OnError::Stop) => return Err(error),
Err(error) => {
return Ok(ExecutionReport::from_results(vec![ExecResponse {
ok: false,
operation: "PARSE".to_string(),
message: error.to_string(),
data: None,
telemetry: None,
}]));
}
};
if statements.is_empty() {
return Err(QqlError::validation(
"QQL-VALIDATION-EMPTY-SCRIPT",
"no statements to execute; the query string is empty or contains only comments",
None,
));
}
let results = self.execute_batch_nodes(statements, on_error).await?;
Ok(ExecutionReport::from_results(results))
}
pub async fn execute_with_params(
&self,
query: &str,
params: &HashMap<String, Value>,
on_error: OnError,
) -> Result<ExecutionReport, QqlError> {
self.ensure_open()?;
let mut statements = parser::Parser::parse_all(query)?;
for stmt in &mut statements {
qql_core::params::bind_stmt(stmt, |k| params.get(k).cloned(), &[])?;
}
let results = self.execute_batch_nodes(statements, on_error).await?;
Ok(ExecutionReport::from_results(results))
}
pub async fn execute_with_named_params<K: AsRef<str>>(
&self,
query: &str,
params: &[(K, Value)],
on_error: OnError,
) -> Result<ExecutionReport, QqlError> {
self.ensure_open()?;
let mut statements = parser::Parser::parse_all(query)?;
let lookup_map: HashMap<&str, &Value> = params
.iter()
.map(|(name, value)| (name.as_ref(), value))
.collect();
for stmt in &mut statements {
qql_core::params::bind_stmt(stmt, |k| lookup_map.get(k).map(|v| (*v).clone()), &[])?;
}
let results = self.execute_batch_nodes(statements, on_error).await?;
Ok(ExecutionReport::from_results(results))
}
pub async fn execute_with_positional_params(
&self,
query: &str,
params: &[Value],
on_error: OnError,
) -> Result<ExecutionReport, QqlError> {
self.ensure_open()?;
let mut statements = parser::Parser::parse_all(query)?;
for stmt in &mut statements {
qql_core::params::bind_stmt(stmt, |_| None, params)?;
}
let results = self.execute_batch_nodes(statements, on_error).await?;
Ok(ExecutionReport::from_results(results))
}
pub(crate) async fn prepare_statement(&self, mut stmt: Stmt) -> Result<Stmt, QqlError> {
let upsert_schema = match &mut stmt {
Stmt::Query(query) => {
if let ast::QueryCollection::Explicit(collection) = &query.collection {
let collection = collection.clone();
self.configure_query_vectors(&collection, query).await?;
}
None
}
Stmt::Upsert(upsert) => self.configure_upsert_embeddings(upsert).await?,
_ => None,
};
if let Some(ref embedder) = self.embedder {
self.resolve_embeddings(&mut stmt, embedder.as_ref())
.await?;
}
if let Stmt::CreateCollection(create) = &mut stmt {
self.prepare_create_collection(create).await?;
}
if let Stmt::AlterCollection(alter) = &stmt {
self.configure_alter_collection(alter).await?;
}
if let Stmt::Upsert(u) = &stmt {
if let Some(ref emb) = u.embedding {
type SpecTuple<'a> = (
Option<&'a str>,
bool,
bool,
Option<&'a str>,
Option<&'a str>,
);
fn collect_specs(spec: &ast::EmbeddingSpec) -> Vec<SpecTuple<'_>> {
match spec {
ast::EmbeddingSpec::Dense { model, vector, .. } => {
vec![(model.as_deref(), true, false, vector.as_deref(), None)]
}
ast::EmbeddingSpec::Sparse { model, vector, .. } => {
vec![(model.as_deref(), false, true, None, vector.as_deref())]
}
ast::EmbeddingSpec::MultiVector { .. }
| ast::EmbeddingSpec::Image { .. } => Vec::new(),
ast::EmbeddingSpec::Hybrid {
dense_model,
dense_vector,
sparse_vector,
..
} => vec![(
dense_model.as_deref(),
true,
true,
dense_vector.as_deref(),
sparse_vector.as_deref(),
)],
ast::EmbeddingSpec::Multi(specs) => {
specs.iter().flat_map(collect_specs).collect()
}
}
}
let specs = collect_specs(emb);
if !specs.is_empty() {
let mut aggregated_dense = false;
let mut aggregated_sparse = false;
let mut main_model = None;
let mut main_dense_vec = None;
let mut main_sparse_vec = None;
for (model, has_dense, has_sparse, dense_vec, sparse_vec) in specs {
if has_dense {
aggregated_dense = true;
match (main_dense_vec, dense_vec) {
(None, name) => main_dense_vec = name,
(Some(first), Some(name)) if first != name => {
return Err(QqlError::execution(
"QQL-EMBEDDING-TOPOLOGY",
format!(
"cannot auto-create collection '{}': conflicting dense vector names '{first}' vs '{name}'; create the collection explicitly",
u.collection
),
None,
));
}
_ => {}
}
}
if has_sparse {
aggregated_sparse = true;
match (main_sparse_vec, sparse_vec) {
(None, name) => main_sparse_vec = name,
(Some(first), Some(name)) if first != name => {
return Err(QqlError::execution(
"QQL-EMBEDDING-TOPOLOGY",
format!(
"cannot auto-create collection '{}': conflicting sparse vector names '{first}' vs '{name}'; create the collection explicitly",
u.collection
),
None,
));
}
_ => {}
}
}
if let Some(model) = model {
match main_model {
None => main_model = Some(model),
Some(first) if first != model => {
return Err(QqlError::execution(
"QQL-EMBEDDING-TOPOLOGY",
format!(
"cannot auto-create collection '{}': conflicting embedding models '{first}' vs '{model}'; create the collection explicitly",
u.collection
),
None,
));
}
_ => {}
}
}
}
self.ensure_collection_for_upsert(
&u.collection,
main_model,
aggregated_dense,
aggregated_sparse,
main_dense_vec,
main_sparse_vec,
)
.await?;
}
}
if let Some(info) = upsert_schema.as_ref() {
self.validate_embedded_upsert(u, info)?;
}
}
Ok(stmt)
}
}