1mod backend;
41mod bootstrap;
42#[cfg(feature = "fastembed-local")]
43mod embedder;
44
45pub use backend::EdgeQdrant;
46pub use bootstrap::{ShardSummary, inspect_shard, unpack_snapshot};
47#[cfg(feature = "fastembed-local")]
48pub use embedder::{
49 EmbeddingModelInfo, FastEmbedder, FastEmbedderOptions, list_embedding_models,
50 resolve_embedding_model, resolve_image_model, resolve_multi_model,
51};
52
53use qql::config::QqlConfig;
54use qql::embedder::Embedder;
55use qql::executor::Executor;
56use std::path::PathBuf;
57use std::sync::Arc;
58
59#[derive(Debug, Clone, Default)]
61pub struct LocalExecutorOptions {
62 pub on_disk_payload: bool,
66 pub wal_segment_capacity: Option<usize>,
77 #[cfg(feature = "fastembed-local")]
80 pub model: Option<String>,
81 #[cfg(feature = "fastembed-local")]
87 pub sparse_model: Option<String>,
88 #[cfg(feature = "fastembed-local")]
91 pub multi_model: Option<String>,
92 #[cfg(feature = "fastembed-local")]
95 pub image_model: Option<String>,
96 #[cfg(feature = "fastembed-local")]
98 pub reranker_model: Option<String>,
99 #[cfg(feature = "fastembed-local")]
101 pub cache_dir: Option<PathBuf>,
102 #[cfg(feature = "fastembed-local")]
104 pub show_download_progress: bool,
105 #[cfg(feature = "fastembed-local")]
110 pub bm25_k1: Option<f64>,
111 #[cfg(feature = "fastembed-local")]
114 pub bm25_b: Option<f64>,
115 #[cfg(feature = "fastembed-local")]
118 pub bm25_avg_len: Option<f64>,
119 #[cfg(feature = "fastembed-local")]
122 pub bm25_language: Option<String>,
123 #[cfg(feature = "fastembed-local")]
126 pub bm25_tokenizer: Option<String>,
127 #[cfg(feature = "fastembed-local")]
129 pub bm25_lowercase: Option<bool>,
130 #[cfg(feature = "fastembed-local")]
132 pub bm25_ascii_folding: Option<bool>,
133 #[cfg(feature = "fastembed-local")]
135 pub bm25_min_token_len: Option<usize>,
136 #[cfg(feature = "fastembed-local")]
139 pub bm25_max_token_len: Option<usize>,
140 #[cfg(feature = "fastembed-local")]
143 pub bm25_stopwords: Option<Vec<String>>,
144 #[cfg(feature = "fastembed-local")]
146 pub bm25_stemmer: Option<String>,
147 #[cfg(feature = "fastembed-local")]
149 pub bm25_stopwords_languages: Option<Vec<String>>,
150}
151
152pub fn wal_segment_capacity_bytes(
161 mb: Option<u64>,
162) -> Result<Option<usize>, qql_core::error::QqlError> {
163 match mb {
164 None => Ok(None),
165 Some(0) => Err(qql_core::error::QqlError::validation(
166 "QQL-VALIDATION-CONFIG",
167 "wal_segment_mb must be greater than zero; omit it for the qdrant-edge 32 MiB default",
168 None,
169 )),
170 Some(mb) => usize::try_from(mb)
171 .ok()
172 .and_then(|mb| mb.checked_mul(1024 * 1024))
173 .map(Some)
174 .ok_or_else(|| {
175 qql_core::error::QqlError::validation(
176 "QQL-VALIDATION-CONFIG",
177 "wal_segment_mb is too large for this platform",
178 None,
179 )
180 }),
181 }
182}
183
184#[cfg(feature = "fastembed-local")]
194pub fn local_executor(
195 data_dir: impl Into<PathBuf>,
196 on_disk_payload: bool,
197) -> Result<Executor, qql_core::error::QqlError> {
198 local_executor_with_options(
199 data_dir,
200 LocalExecutorOptions {
201 on_disk_payload,
202 ..Default::default()
203 },
204 )
205}
206
207#[cfg(feature = "fastembed-local")]
213pub fn local_executor_with_options(
214 data_dir: impl Into<PathBuf>,
215 opts: LocalExecutorOptions,
216) -> Result<Executor, qql_core::error::QqlError> {
217 let client = Box::new(
218 EdgeQdrant::new(data_dir, opts.on_disk_payload)
219 .with_wal_segment_capacity(opts.wal_segment_capacity),
220 );
221 let embedder = FastEmbedder::try_with_options(FastEmbedderOptions {
222 model: opts.model,
223 sparse_model: opts.sparse_model,
224 multi_model: opts.multi_model,
225 image_model: opts.image_model,
226 reranker_model: opts.reranker_model,
227 cache_dir: opts.cache_dir,
228 show_download_progress: opts.show_download_progress,
229 bm25_k1: opts.bm25_k1,
230 bm25_b: opts.bm25_b,
231 bm25_avg_len: opts.bm25_avg_len,
232 bm25_language: opts.bm25_language,
233 bm25_tokenizer: opts.bm25_tokenizer,
234 bm25_lowercase: opts.bm25_lowercase,
235 bm25_ascii_folding: opts.bm25_ascii_folding,
236 bm25_min_token_len: opts.bm25_min_token_len,
237 bm25_max_token_len: opts.bm25_max_token_len,
238 bm25_stopwords: opts.bm25_stopwords,
239 bm25_stemmer: opts.bm25_stemmer,
240 bm25_stopwords_languages: opts.bm25_stopwords_languages,
241 })?;
242
243 let multi_dim = embedder.multi_dimension().unwrap_or(0);
247 let image_dim = embedder.image_dimension().unwrap_or(0);
248 let config = QqlConfig {
249 inference_mode: "local".to_string(),
250 embedding_dimension: embedder.dimension(),
251 embedding_model: Some(embedder.model_name().to_string()),
252 sparse_inference_model: embedder.sparse_model_code().map(str::to_string),
253 multi_embedding_model: embedder.multi_model_code().map(str::to_string),
254 multi_embedding_dimension: multi_dim,
255 image_embedding_model: embedder.image_model_code().map(str::to_string),
256 image_embedding_dimension: image_dim,
257 rerank_model: embedder.reranker_model_code().map(str::to_string),
258 ..Default::default()
259 };
260
261 let embedder = Some(Arc::new(embedder) as Arc<dyn Embedder>);
262 Ok(Executor::with_embedder(client, Some(config), embedder))
263}
264
265#[cfg(feature = "http-embedding")]
277pub fn http_executor(
278 data_dir: impl Into<PathBuf>,
279 on_disk_payload: bool,
280 endpoint: impl Into<String>,
281 api_key: impl Into<String>,
282 model: impl Into<String>,
283 dimension: usize,
284) -> Result<Executor, qql_core::error::QqlError> {
285 http_executor_with_options(
286 data_dir,
287 on_disk_payload,
288 qql::embedder::HttpEmbedderOptions {
289 endpoint: endpoint.into(),
290 api_key: api_key.into(),
291 model: model.into(),
292 dimension,
293 ..Default::default()
294 },
295 )
296}
297
298#[cfg(feature = "http-embedding")]
300#[allow(clippy::too_many_arguments)]
301pub fn http_executor_with_multi(
302 data_dir: impl Into<PathBuf>,
303 on_disk_payload: bool,
304 endpoint: impl Into<String>,
305 api_key: impl Into<String>,
306 model: impl Into<String>,
307 dimension: usize,
308 multi_endpoint: Option<String>,
309 multi_api_key: Option<String>,
310 multi_model: Option<String>,
311 multi_dimension: usize,
312) -> Result<Executor, qql_core::error::QqlError> {
313 http_executor_with_options(
314 data_dir,
315 on_disk_payload,
316 qql::embedder::HttpEmbedderOptions {
317 endpoint: endpoint.into(),
318 api_key: api_key.into(),
319 model: model.into(),
320 dimension,
321 multi_endpoint,
322 multi_api_key,
323 multi_model,
324 multi_dimension,
325 ..Default::default()
326 },
327 )
328}
329
330#[cfg(feature = "http-embedding")]
332pub fn http_executor_with_options(
333 data_dir: impl Into<PathBuf>,
334 on_disk_payload: bool,
335 opts: qql::embedder::HttpEmbedderOptions,
336) -> Result<Executor, qql_core::error::QqlError> {
337 http_executor_with_options_and_wal(data_dir, on_disk_payload, None, opts)
338}
339
340#[cfg(feature = "http-embedding")]
345pub fn http_executor_with_options_and_wal(
346 data_dir: impl Into<PathBuf>,
347 on_disk_payload: bool,
348 wal_segment_capacity: Option<usize>,
349 opts: qql::embedder::HttpEmbedderOptions,
350) -> Result<Executor, qql_core::error::QqlError> {
351 let client = Box::new(
352 EdgeQdrant::new(data_dir, on_disk_payload).with_wal_segment_capacity(wal_segment_capacity),
353 );
354 let config = QqlConfig {
355 inference_mode: "local".to_string(),
356 embedding_dimension: opts.dimension,
357 embedding_model: Some(opts.model.clone()),
358 embedding_endpoint: None, multi_embedding_endpoint: opts.multi_endpoint.clone(),
360 multi_embedding_api_key: opts.multi_api_key.clone(),
361 multi_embedding_model: opts.multi_model.clone(),
362 multi_embedding_dimension: opts.multi_dimension,
363 image_embedding_endpoint: opts.image_endpoint.clone(),
364 image_embedding_api_key: opts.image_api_key.clone(),
365 image_embedding_model: opts.image_model.clone(),
366 image_embedding_dimension: opts.image_dimension,
367 rerank_endpoint: opts.rerank_endpoint.clone(),
368 rerank_api_key: opts.rerank_api_key.clone(),
369 rerank_model: opts.rerank_model.clone(),
370 ..Default::default()
371 };
372 let embedder = qql::embedder::HttpEmbedder::try_with_options(opts)?;
373 Ok(Executor::with_embedder(
374 client,
375 Some(config),
376 Some(Arc::new(embedder) as Arc<dyn Embedder>),
377 ))
378}
379
380pub fn custom_executor(
389 data_dir: impl Into<PathBuf>,
390 on_disk_payload: bool,
391 embedder: Arc<dyn Embedder>,
392) -> Result<Executor, qql_core::error::QqlError> {
393 custom_executor_with_dimension(data_dir, on_disk_payload, embedder, None)
394}
395
396pub fn custom_executor_with_dimension(
399 data_dir: impl Into<PathBuf>,
400 on_disk_payload: bool,
401 embedder: Arc<dyn Embedder>,
402 dimension: Option<usize>,
403) -> Result<Executor, qql_core::error::QqlError> {
404 custom_executor_with_storage(data_dir, on_disk_payload, None, embedder, dimension)
405}
406
407pub fn custom_executor_with_storage(
411 data_dir: impl Into<PathBuf>,
412 on_disk_payload: bool,
413 wal_segment_capacity: Option<usize>,
414 embedder: Arc<dyn Embedder>,
415 dimension: Option<usize>,
416) -> Result<Executor, qql_core::error::QqlError> {
417 let client = Box::new(
418 EdgeQdrant::new(data_dir, on_disk_payload).with_wal_segment_capacity(wal_segment_capacity),
419 );
420 let config = QqlConfig {
421 inference_mode: "local".to_string(),
422 embedding_dimension: embedder.dimension().or(dimension).unwrap_or(0),
423 ..Default::default()
424 };
425 Ok(Executor::with_embedder(
426 client,
427 Some(config),
428 Some(embedder),
429 ))
430}
431
432#[cfg(test)]
433mod tests {
434 use super::*;
435 use async_trait::async_trait;
436 use qql::embedder::Embedder;
437 use qql::executor::OnError;
438 use qql_core::error::QqlError;
439 use qql_embed::sparse::SparseVector;
440
441 struct TestEmbedder;
442
443 #[async_trait]
444 impl Embedder for TestEmbedder {
445 fn dimension(&self) -> Option<usize> {
446 Some(3)
447 }
448
449 async fn embed_dense(&self, _text: &str, _model: &str) -> Result<Vec<f32>, QqlError> {
450 Ok(vec![1.0, 0.0, 0.0])
451 }
452
453 async fn embed_sparse_query(
454 &self,
455 _text: &str,
456 _model: &str,
457 ) -> Result<SparseVector, QqlError> {
458 Ok(SparseVector {
459 indices: vec![1],
460 values: vec![1.0],
461 })
462 }
463
464 async fn embed_sparse_document(
465 &self,
466 _text: &str,
467 _model: &str,
468 ) -> Result<SparseVector, QqlError> {
469 Ok(SparseVector {
470 indices: vec![1],
471 values: vec![1.0],
472 })
473 }
474 }
475
476 #[test]
477 #[cfg(feature = "fastembed-local")]
478 fn local_executor_options_default_has_no_sparse_model() {
479 let opts = LocalExecutorOptions::default();
480 assert!(opts.sparse_model.is_none());
481 }
482
483 #[test]
484 #[cfg(feature = "fastembed-local")]
485 fn local_executor_options_with_sparse_model() {
486 let opts = LocalExecutorOptions {
487 sparse_model: Some("splade".into()),
488 ..Default::default()
489 };
490 assert_eq!(opts.sparse_model.as_deref(), Some("splade"));
491 }
492
493 #[test]
494 #[cfg(feature = "fastembed-local")]
495 fn local_executor_options_bm25_defaults_are_unset() {
496 let opts = LocalExecutorOptions::default();
497 assert_eq!(opts.bm25_k1, None);
498 assert_eq!(opts.bm25_b, None);
499 assert_eq!(opts.bm25_avg_len, None);
500 }
501
502 #[test]
510 #[cfg(feature = "http-embedding")]
511 fn configured_bm25_params_land_in_stored_sparse_vector() {
512 use qql::embedder::HttpEmbedderOptions;
513 use qql::executor::OnError;
514 use qql_plan::{PlanVectorStruct, PlanVectorValue};
515
516 let runtime = tokio::runtime::Builder::new_current_thread()
517 .enable_all()
518 .build()
519 .expect("test runtime");
520 runtime.block_on(async {
521 let data_dir =
522 std::env::temp_dir().join(format!("qql-edge-bm25-{}", std::process::id()));
523 let _ = std::fs::remove_dir_all(&data_dir);
524
525 let params = qql_embed::Bm25Params::new(2.0, 0.5, 4.0).expect("valid params");
526 let executor = http_executor_with_options_and_wal(
527 &data_dir,
528 false,
529 None,
530 HttpEmbedderOptions {
531 endpoint: "http://127.0.0.1:9/v1/embeddings".to_string(),
532 api_key: String::new(),
533 model: "unused-dense".to_string(),
534 dimension: 3,
535 bm25_k1: Some(params.k1()),
536 bm25_b: Some(params.b()),
537 bm25_avg_len: Some(params.avg_len()),
538 ..Default::default()
539 },
540 )
541 .expect("http edge executor");
542
543 let report = executor
544 .execute("CREATE COLLECTION bm25_docs (sparse SPARSE)", OnError::Stop)
545 .await
546 .expect("create collection");
547 assert!(report.ok, "create failed: {report:?}");
548
549 let text = "cat sat mat cat";
550 let report = executor
551 .execute(
552 &format!("UPSERT INTO bm25_docs VALUES {{id: 1, text: '{text}'}}"),
553 OnError::Stop,
554 )
555 .await
556 .expect("upsert");
557 assert!(report.ok, "upsert failed: {report:?}");
558
559 let report = executor
560 .execute(
561 "QUERY POINTS (1) FROM bm25_docs WITH VECTOR true",
562 OnError::Stop,
563 )
564 .await
565 .expect("point lookup");
566 assert!(report.ok, "lookup failed: {report:?}");
567 let hits = report.results[0].hits_ref().expect("hits");
568 let vector = hits[0].vector.as_ref().expect("stored vector");
569 let stored = match vector {
570 PlanVectorStruct::Single(v) => v,
571 PlanVectorStruct::Named(map) => map.get("sparse").expect("sparse named vector"),
572 };
573 let (indices, values) = match stored {
574 PlanVectorValue::Sparse { indices, values } => (indices, values),
575 other => panic!("expected sparse vector, got {other:?}"),
576 };
577
578 let expected = qql_embed::sparse::embed_document_with_params(text, ¶ms);
579 assert_eq!(*indices, expected.indices, "stored indices must match");
580 assert_eq!(values.len(), expected.values.len());
581 for (got, want) in values.iter().zip(&expected.values) {
582 assert!(
583 (got - want).abs() < 1e-6,
584 "stored BM25 weight {got} != configured {want}"
585 );
586 }
587
588 let default = qql_embed::sparse::embed_document(text);
590 assert_ne!(*values, default.values);
591
592 executor.close().await.expect("close edge executor");
593 let _ = std::fs::remove_dir_all(data_dir);
594 });
595 }
596
597 #[test]
598 fn wal_segment_capacity_bytes_scales_mib() {
599 assert_eq!(wal_segment_capacity_bytes(None).unwrap(), None);
600 assert_eq!(wal_segment_capacity_bytes(Some(4)).unwrap(), Some(4 << 20));
601 }
602
603 #[test]
604 fn wal_segment_capacity_bytes_rejects_zero_and_overflow() {
605 let zero = wal_segment_capacity_bytes(Some(0)).expect_err("zero must fail closed");
606 assert_eq!(zero.code, "QQL-VALIDATION-CONFIG");
607 let overflow =
608 wal_segment_capacity_bytes(Some(u64::MAX)).expect_err("overflow must fail closed");
609 assert_eq!(overflow.code, "QQL-VALIDATION-CONFIG");
610 }
611
612 #[test]
613 fn custom_edge_executor_is_schema_aware_and_rejects_shards() {
614 let runtime = tokio::runtime::Builder::new_current_thread()
615 .enable_all()
616 .build()
617 .expect("test runtime");
618 runtime.block_on(async {
619 let data_dir =
620 std::env::temp_dir().join(format!("qql-edge-test-{}", std::process::id()));
621 let _ = std::fs::remove_dir_all(&data_dir);
622 let executor =
623 custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
624
625 let report = executor
626 .execute("CREATE COLLECTION docs HYBRID", OnError::Stop)
627 .await
628 .expect("create collection");
629 assert!(report.ok);
630 let report = executor
631 .execute(
632 "UPSERT INTO docs VALUES {id: 1, text: 'hello'}",
633 OnError::Stop,
634 )
635 .await
636 .expect("schema-aware upsert");
637 assert!(report.ok);
638 let report = executor
639 .execute(
640 "QUERY 'hello' FROM docs USING dense AS DENSE LIMIT 1",
641 OnError::Stop,
642 )
643 .await
644 .expect("schema-aware query");
645 assert!(report.ok);
646 let report = executor
647 .execute(
648 "CREATE COLLECTION dense_only (dense VECTOR(3, COSINE))",
649 OnError::Stop,
650 )
651 .await
652 .expect("create dense-only collection");
653 assert!(report.ok);
654 let report = executor
655 .execute(
656 "UPSERT INTO dense_only VALUES {id: 2, body: 'dense only'}",
657 OnError::Stop,
658 )
659 .await
660 .expect("dense-only auto-embed");
661 assert!(report.ok);
662 let report = executor
663 .execute(
664 "CREATE COLLECTION sparse_only (sparse SPARSE)",
665 OnError::Stop,
666 )
667 .await
668 .expect("create sparse-only collection");
669 assert!(report.ok);
670 let report = executor
671 .execute(
672 "UPSERT INTO sparse_only VALUES {id: 3, content: 'sparse only'}",
673 OnError::Stop,
674 )
675 .await
676 .expect("sparse-only auto-embed");
677 assert!(report.ok);
678 let report = executor
679 .execute(
680 "QUERY 'hello' FROM docs USING dense AS DENSE SHARD 'tenant-a' LIMIT 1",
681 OnError::Continue,
682 )
683 .await
684 .expect("edge should report unsupported shard");
685 assert!(!report.ok);
686 assert!(report.results[0].message.contains("UNSUPPORTED-SHARD"));
687 executor.close().await.expect("close edge executor");
688 let _ = std::fs::remove_dir_all(data_dir);
689 });
690 }
691
692 #[test]
693 fn edge_reads_do_not_create_missing_collections() {
694 let runtime = tokio::runtime::Builder::new_current_thread()
698 .enable_all()
699 .build()
700 .expect("test runtime");
701 runtime.block_on(async {
702 let data_dir =
703 std::env::temp_dir().join(format!("qql-edge-readtest-{}", std::process::id()));
704 let _ = std::fs::remove_dir_all(&data_dir);
705 let executor =
706 custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
707
708 let cases = [
709 "QUERY 'hello' FROM never_queried USING dense AS DENSE LIMIT 5",
710 "SCROLL FROM never_scrolled LIMIT 5",
711 "QUERY POINTS (1, 2) FROM never_points WITH PAYLOAD true",
712 "COUNT FROM never_counted",
713 "DELETE FROM never_deleted WHERE id = 1",
714 ];
715 for query in cases {
716 let report = executor
717 .execute(query, OnError::Continue)
718 .await
719 .expect("read against missing collection must return a report");
720 assert!(
721 !report.ok,
722 "expected failure for '{query}': {:?}",
723 report.results
724 );
725 assert!(
726 report.results[0]
727 .message
728 .contains("QQL-EDGE-COLLECTION-NOT-FOUND"),
729 "expected QQL-EDGE-COLLECTION-NOT-FOUND for '{query}', got {:?}",
730 report.results[0].message
731 );
732 }
733
734 let report = executor
736 .execute("SHOW COLLECTIONS", OnError::Stop)
737 .await
738 .expect("list collections");
739 assert!(report.ok);
740 let cols = report.results[0]
741 .data
742 .as_ref()
743 .and_then(|d| d.collections())
744 .expect("collections list");
745 assert!(
746 cols.is_empty(),
747 "read operations must not create collections: {cols:?}"
748 );
749
750 executor.close().await.expect("close edge executor");
751 let _ = std::fs::remove_dir_all(data_dir);
752 });
753 }
754
755 #[test]
756 fn edge_upsert_autocreate_and_get_points_shape() {
757 let runtime = tokio::runtime::Builder::new_current_thread()
761 .enable_all()
762 .build()
763 .expect("test runtime");
764 runtime.block_on(async {
765 let data_dir =
766 std::env::temp_dir().join(format!("qql-edge-pointstest-{}", std::process::id()));
767 let _ = std::fs::remove_dir_all(&data_dir);
768 let executor =
769 custom_executor(&data_dir, false, Arc::new(TestEmbedder)).expect("custom executor");
770
771 let report = executor
773 .execute(
774 "UPSERT INTO auto_docs VALUES {id: 1, text: 'hello'}, {id: 2, text: 'world'}",
775 OnError::Stop,
776 )
777 .await
778 .expect("auto-creating upsert");
779 assert!(report.ok, "auto-creating UPSERT failed: {:?}", report);
780
781 let report = executor
782 .execute("SHOW COLLECTIONS", OnError::Stop)
783 .await
784 .expect("list collections");
785 let cols = report.results[0]
786 .data
787 .as_ref()
788 .and_then(|d| d.collections())
789 .map(<[String]>::len)
790 .unwrap_or(0);
791 assert_eq!(
792 cols, 1,
793 "UPSERT auto-create should materialise one collection"
794 );
795
796 let report = executor
799 .execute(
800 "QUERY POINTS (1, 2) FROM auto_docs WITH PAYLOAD true",
801 OnError::Stop,
802 )
803 .await
804 .expect("points lookup");
805 assert!(report.ok, "POINTS lookup failed: {:?}", report);
806 assert_eq!(
807 report.results[0].message, "Found 2 hits",
808 "POINTS lookup should report 2 hits, got {:?}",
809 report.results[0].message
810 );
811 let hits = report.results[0].hits_ref().expect("data");
812 assert_eq!(hits.len(), 2, "POINTS lookup should return 2 hits");
813
814 executor.close().await.expect("close edge executor");
815 let _ = std::fs::remove_dir_all(data_dir);
816 });
817 }
818}