mod backend;
#[cfg(feature = "fastembed-local")]
mod embedder;
pub use backend::EdgeQdrant;
#[cfg(feature = "fastembed-local")]
pub use embedder::{
list_embedding_models, resolve_embedding_model, resolve_image_model, resolve_multi_model,
EmbeddingModelInfo, FastEmbedder, FastEmbedderOptions,
};
use qql::config::QqlConfig;
use qql::embedder::Embedder;
use qql::executor::Executor;
use std::path::PathBuf;
use std::sync::Arc;
#[derive(Debug, Clone, Default)]
pub struct LocalExecutorOptions {
pub on_disk_payload: bool,
#[cfg(feature = "fastembed-local")]
pub model: Option<String>,
#[cfg(feature = "fastembed-local")]
pub sparse_model: Option<String>,
#[cfg(feature = "fastembed-local")]
pub multi_model: Option<String>,
#[cfg(feature = "fastembed-local")]
pub image_model: Option<String>,
#[cfg(feature = "fastembed-local")]
pub reranker_model: Option<String>,
#[cfg(feature = "fastembed-local")]
pub cache_dir: Option<PathBuf>,
#[cfg(feature = "fastembed-local")]
pub show_download_progress: bool,
}
#[cfg(feature = "fastembed-local")]
pub fn local_executor(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
) -> Result<Executor, qql_core::error::QqlError> {
local_executor_with_options(
data_dir,
LocalExecutorOptions {
on_disk_payload,
..Default::default()
},
)
}
#[cfg(feature = "fastembed-local")]
pub fn local_executor_with_options(
data_dir: impl Into<PathBuf>,
opts: LocalExecutorOptions,
) -> Result<Executor, qql_core::error::QqlError> {
let client = Box::new(EdgeQdrant::new(data_dir, opts.on_disk_payload));
let embedder = FastEmbedder::try_with_options(FastEmbedderOptions {
model: opts.model,
sparse_model: opts.sparse_model,
multi_model: opts.multi_model,
image_model: opts.image_model,
reranker_model: opts.reranker_model,
cache_dir: opts.cache_dir,
show_download_progress: opts.show_download_progress,
})?;
let multi_dim = embedder.multi_dimension().unwrap_or(0);
let image_dim = embedder.image_dimension().unwrap_or(0);
let config = QqlConfig {
inference_mode: "local".to_string(),
embedding_dimension: embedder.dimension(),
embedding_model: Some(embedder.model_name().to_string()),
sparse_inference_model: embedder.sparse_model_code().map(str::to_string),
multi_embedding_model: embedder.multi_model_code().map(str::to_string),
multi_embedding_dimension: multi_dim,
image_embedding_model: embedder.image_model_code().map(str::to_string),
image_embedding_dimension: image_dim,
rerank_model: embedder.reranker_model_code().map(str::to_string),
..Default::default()
};
let embedder = Some(Arc::new(embedder) as Arc<dyn Embedder>);
Ok(Executor::with_embedder(client, Some(config), embedder))
}
#[cfg(feature = "http-embedding")]
pub fn http_executor(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
endpoint: impl Into<String>,
api_key: impl Into<String>,
model: impl Into<String>,
dimension: usize,
) -> Result<Executor, qql_core::error::QqlError> {
http_executor_with_options(
data_dir,
on_disk_payload,
qql::embedder::HttpEmbedderOptions {
endpoint: endpoint.into(),
api_key: api_key.into(),
model: model.into(),
dimension,
..Default::default()
},
)
}
#[cfg(feature = "http-embedding")]
#[allow(clippy::too_many_arguments)]
pub fn http_executor_with_multi(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
endpoint: impl Into<String>,
api_key: impl Into<String>,
model: impl Into<String>,
dimension: usize,
multi_endpoint: Option<String>,
multi_api_key: Option<String>,
multi_model: Option<String>,
multi_dimension: usize,
) -> Result<Executor, qql_core::error::QqlError> {
http_executor_with_options(
data_dir,
on_disk_payload,
qql::embedder::HttpEmbedderOptions {
endpoint: endpoint.into(),
api_key: api_key.into(),
model: model.into(),
dimension,
multi_endpoint,
multi_api_key,
multi_model,
multi_dimension,
..Default::default()
},
)
}
#[cfg(feature = "http-embedding")]
pub fn http_executor_with_options(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
opts: qql::embedder::HttpEmbedderOptions,
) -> Result<Executor, qql_core::error::QqlError> {
let client = Box::new(EdgeQdrant::new(data_dir, on_disk_payload));
let config = QqlConfig {
inference_mode: "local".to_string(),
embedding_dimension: opts.dimension,
embedding_model: Some(opts.model.clone()),
embedding_endpoint: None, multi_embedding_endpoint: opts.multi_endpoint.clone(),
multi_embedding_api_key: opts.multi_api_key.clone(),
multi_embedding_model: opts.multi_model.clone(),
multi_embedding_dimension: opts.multi_dimension,
image_embedding_endpoint: opts.image_endpoint.clone(),
image_embedding_api_key: opts.image_api_key.clone(),
image_embedding_model: opts.image_model.clone(),
image_embedding_dimension: opts.image_dimension,
rerank_endpoint: opts.rerank_endpoint.clone(),
rerank_api_key: opts.rerank_api_key.clone(),
rerank_model: opts.rerank_model.clone(),
..Default::default()
};
let embedder = qql::embedder::HttpEmbedder::try_with_options(opts)?;
Ok(Executor::with_embedder(
client,
Some(config),
Some(Arc::new(embedder) as Arc<dyn Embedder>),
))
}
pub fn custom_executor(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
embedder: Arc<dyn Embedder>,
) -> Result<Executor, qql_core::error::QqlError> {
custom_executor_with_dimension(data_dir, on_disk_payload, embedder, None)
}
pub fn custom_executor_with_dimension(
data_dir: impl Into<PathBuf>,
on_disk_payload: bool,
embedder: Arc<dyn Embedder>,
dimension: Option<usize>,
) -> Result<Executor, qql_core::error::QqlError> {
let client = Box::new(EdgeQdrant::new(data_dir, on_disk_payload));
let config = QqlConfig {
inference_mode: "local".to_string(),
embedding_dimension: embedder.dimension().or(dimension).unwrap_or(0),
..Default::default()
};
Ok(Executor::with_embedder(
client,
Some(config),
Some(embedder),
))
}
#[cfg(test)]
mod tests {
use super::*;
use async_trait::async_trait;
use qql::embedder::Embedder;
use qql::executor::OnError;
use qql_core::error::QqlError;
use qql_embed::sparse::SparseVector;
struct TestEmbedder;
#[async_trait]
impl Embedder for TestEmbedder {
fn dimension(&self) -> Option<usize> {
Some(3)
}
async fn embed_dense(&self, _text: &str, _model: &str) -> Result<Vec<f32>, QqlError> {
Ok(vec![1.0, 0.0, 0.0])
}
async fn embed_sparse(&self, _text: &str, _model: &str) -> Result<SparseVector, QqlError> {
Ok(SparseVector {
indices: vec![1],
values: vec![1.0],
})
}
}
#[test]
#[cfg(feature = "fastembed-local")]
fn local_executor_options_default_has_no_sparse_model() {
let opts = LocalExecutorOptions::default();
assert!(opts.sparse_model.is_none());
}
#[test]
#[cfg(feature = "fastembed-local")]
fn local_executor_options_with_sparse_model() {
let opts = LocalExecutorOptions {
sparse_model: Some("splade".into()),
..Default::default()
};
assert_eq!(opts.sparse_model.as_deref(), Some("splade"));
}
#[test]
fn custom_edge_executor_is_schema_aware_and_rejects_shards() {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("test runtime");
runtime.block_on(async {
let data_dir =
std::env::temp_dir().join(format!("qql-edge-test-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&data_dir);
let executor =
custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
let report = executor
.execute("CREATE COLLECTION docs HYBRID", OnError::Stop)
.await
.expect("create collection");
assert!(report.ok);
let report = executor
.execute(
"UPSERT INTO docs VALUES {id: 1, text: 'hello'}",
OnError::Stop,
)
.await
.expect("schema-aware upsert");
assert!(report.ok);
let report = executor
.execute(
"QUERY 'hello' FROM docs USING dense AS DENSE LIMIT 1",
OnError::Stop,
)
.await
.expect("schema-aware query");
assert!(report.ok);
let report = executor
.execute(
"CREATE COLLECTION dense_only (dense VECTOR(3, COSINE))",
OnError::Stop,
)
.await
.expect("create dense-only collection");
assert!(report.ok);
let report = executor
.execute(
"UPSERT INTO dense_only VALUES {id: 2, body: 'dense only'}",
OnError::Stop,
)
.await
.expect("dense-only auto-embed");
assert!(report.ok);
let report = executor
.execute(
"CREATE COLLECTION sparse_only (sparse SPARSE)",
OnError::Stop,
)
.await
.expect("create sparse-only collection");
assert!(report.ok);
let report = executor
.execute(
"UPSERT INTO sparse_only VALUES {id: 3, content: 'sparse only'}",
OnError::Stop,
)
.await
.expect("sparse-only auto-embed");
assert!(report.ok);
let report = executor
.execute(
"QUERY 'hello' FROM docs USING dense AS DENSE SHARD 'tenant-a' LIMIT 1",
OnError::Continue,
)
.await
.expect("edge should report unsupported shard");
assert!(!report.ok);
assert!(report.results[0].message.contains("UNSUPPORTED-SHARD"));
executor.close().await.expect("close edge executor");
let _ = std::fs::remove_dir_all(data_dir);
});
}
#[test]
fn edge_reads_do_not_create_missing_collections() {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("test runtime");
runtime.block_on(async {
let data_dir =
std::env::temp_dir().join(format!("qql-edge-readtest-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&data_dir);
let executor =
custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
let cases = [
"QUERY 'hello' FROM never_queried USING dense AS DENSE LIMIT 5",
"SCROLL FROM never_scrolled LIMIT 5",
"QUERY POINTS (1, 2) FROM never_points WITH PAYLOAD true",
"COUNT FROM never_counted",
"DELETE FROM never_deleted WHERE id = 1",
];
for query in cases {
let report = executor
.execute(query, OnError::Continue)
.await
.expect("read against missing collection must return a report");
assert!(
!report.ok,
"expected failure for '{query}': {:?}",
report.results
);
assert!(
report.results[0]
.message
.contains("QQL-EDGE-COLLECTION-NOT-FOUND"),
"expected QQL-EDGE-COLLECTION-NOT-FOUND for '{query}', got {:?}",
report.results[0].message
);
}
let report = executor
.execute("SHOW COLLECTIONS", OnError::Stop)
.await
.expect("list collections");
assert!(report.ok);
let cols = report.results[0]
.data
.as_ref()
.and_then(|d| d["result"]["collections"].as_array())
.expect("collections array");
assert!(
cols.is_empty(),
"read operations must not create collections: {cols:?}"
);
executor.close().await.expect("close edge executor");
let _ = std::fs::remove_dir_all(data_dir);
});
}
#[test]
fn edge_upsert_autocreate_and_get_points_shape() {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.expect("test runtime");
runtime.block_on(async {
let data_dir =
std::env::temp_dir().join(format!("qql-edge-pointstest-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&data_dir);
let executor =
custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
let report = executor
.execute(
"UPSERT INTO auto_docs VALUES {id: 1, text: 'hello'}, {id: 2, text: 'world'}",
OnError::Stop,
)
.await
.expect("auto-creating upsert");
assert!(report.ok, "auto-creating UPSERT failed: {:?}", report);
let report = executor
.execute("SHOW COLLECTIONS", OnError::Stop)
.await
.expect("list collections");
let cols = report.results[0]
.data
.as_ref()
.and_then(|d| d["result"]["collections"].as_array())
.map(|c| c.len())
.unwrap_or(0);
assert_eq!(
cols, 1,
"UPSERT auto-create should materialise one collection"
);
let report = executor
.execute(
"QUERY POINTS (1, 2) FROM auto_docs WITH PAYLOAD true",
OnError::Stop,
)
.await
.expect("points lookup");
assert!(report.ok, "POINTS lookup failed: {:?}", report);
assert_eq!(
report.results[0].message, "Found 2 hits",
"POINTS lookup should report 2 hits, got {:?}",
report.results[0].message
);
let data = report.results[0].data.as_ref().expect("data");
let hits = data.as_array().expect("hits array");
assert_eq!(hits.len(), 2, "POINTS lookup should return 2 hits");
executor.close().await.expect("close edge executor");
let _ = std::fs::remove_dir_all(data_dir);
});
}
}