Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

add Qdrant vectordb support (#2350)

Dechao Sunc1cf1c3d06fe
diff --git a/openviking/storage/vectordb/collection/qdrant_collection.py b/openviking/storage/vectordb/collection/qdrant_collection.py
new file mode 100644
index 000000000..7651cf3ad
--- /dev/null
+++ b/openviking/storage/vectordb/collection/qdrant_collection.py
@@ -0,0 +1,1191 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Qdrant-backed ICollection implementation for OpenViking."""
+
+from __future__ import annotations
+
+import datetime as dt
+import uuid
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import xxhash
+
+from openviking.storage.vectordb.collection.collection import ICollection
+from openviking.storage.vectordb.collection.qdrant_meta_store import QdrantMetaStore
+from openviking.storage.vectordb.collection.qdrant_rest import QdrantRestClient, QdrantRestError
+from openviking.storage.vectordb.collection.result import (
+ AggregateResult,
+ DataItem,
+ FetchDataInCollectionResult,
+ SearchItemResult,
+ SearchResult,
+)
+from openviking.storage.vectordb.index.index import IIndex
+from openviking.storage.vectordb.store.data import DeltaRecord
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+QDRANT_SPARSE_INDEX_MAX = 2**31 - 1
+QDRANT_UINT64_MAX = 2**64 - 1
+OPENVIKING_QDRANT_ID_NAMESPACE = uuid.UUID("4b6bb5a8-7f1f-5b1a-9d4c-b93f29b1d67c")
+ORIGINAL_ID_FIELD = "_openviking_original_id"
+
+
+def _coerce_iso_datetime(value: Any) -> Any:
+ if isinstance(value, dt.datetime):
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=dt.timezone.utc)
+ return value.isoformat()
+ return value
+
+
+def _normalize_distance(distance: str) -> str:
+ distance_value = (distance or "cosine").strip().lower()
+ mapping = {
+ "cosine": "Cosine",
+ "ip": "Dot",
+ "dot": "Dot",
+ "l2": "Euclid",
+ "euclid": "Euclid",
+ "manhattan": "Manhattan",
+ }
+ return mapping.get(distance_value, "Cosine")
+
+
+def _payload_selector(output_fields: Optional[List[str]]) -> bool | Dict[str, List[str]]:
+ if not output_fields:
+ return True
+ include_fields = [field for field in output_fields if field != "id"]
+ if ORIGINAL_ID_FIELD not in include_fields:
+ include_fields.append(ORIGINAL_ID_FIELD)
+ return {"include": include_fields} if include_fields else True
+
+
+def _parse_point_id(value: Any) -> Any:
+ if value is None:
+ return ""
+ if isinstance(value, int) and not isinstance(value, bool):
+ return value
+ return str(value)
+
+
+def _to_qdrant_point_id(value: Any) -> int | str:
+ if isinstance(value, int) and not isinstance(value, bool) and 0 <= value <= QDRANT_UINT64_MAX:
+ return value
+ value_str = str(value)
+ try:
+ return str(uuid.UUID(value_str))
+ except (ValueError, AttributeError, TypeError):
+ return str(uuid.uuid5(OPENVIKING_QDRANT_ID_NAMESPACE, value_str))
+
+
+def _extract_points(response: Dict[str, Any]) -> List[Dict[str, Any]]:
+ result = response.get("result", response)
+ if isinstance(result, list):
+ return result
+ if isinstance(result, dict):
+ if isinstance(result.get("points"), list):
+ return result.get("points", [])
+ if isinstance(result.get("result"), list):
+ return result.get("result", [])
+ return []
+
+
+def _hash_sparse_term(term: str) -> int:
+ # Keep sparse indices in the positive signed 32-bit integer range expected
+ # by Qdrant sparse vectors.
+ return xxhash.xxh64_intdigest(str(term)) % QDRANT_SPARSE_INDEX_MAX
+
+
+def _sparse_to_qdrant(sparse_vector: Optional[Dict[str, float]]) -> Optional[Dict[str, List[Any]]]:
+ if not sparse_vector:
+ return None
+ merged: Dict[int, float] = {}
+ hashed_terms: Dict[int, str] = {}
+ collisions: List[tuple[str, str, int]] = []
+ for raw_term, raw_weight in sparse_vector.items():
+ try:
+ weight = float(raw_weight)
+ except (TypeError, ValueError):
+ continue
+ idx = _hash_sparse_term(str(raw_term))
+ previous_term = hashed_terms.get(idx)
+ if previous_term is not None and previous_term != str(raw_term):
+ collisions.append((previous_term, str(raw_term), idx))
+ else:
+ hashed_terms[idx] = str(raw_term)
+ merged[idx] = merged.get(idx, 0.0) + weight
+ if collisions:
+ sample = ", ".join(
+ f"{left!r}<->{right!r}@{idx}" for left, right, idx in collisions[:3]
+ )
+ logger.warning(
+ "Qdrant sparse term hash collision detected; colliding terms are merged into the same sparse index bucket. count=%s sample=%s",
+ len(collisions),
+ sample,
+ )
+ if not merged:
+ return None
+ indices = sorted(merged.keys())
+ values = [merged[idx] for idx in indices]
+ return {"indices": indices, "values": values}
+
+
+class QdrantIndex(IIndex):
+ """Lightweight logical index facade backed by Qdrant payload/vector config."""
+
+ def __init__(self, collection: "QdrantCollection", index_name: str, meta: Dict[str, Any]) -> None:
+ super().__init__(meta=meta)
+ self._collection = collection
+ self._index_name = index_name
+ self._meta = dict(meta)
+
+ def upsert_data(self, delta_list: List[DeltaRecord]):
+ raise NotImplementedError("QdrantIndex.upsert_data is managed at collection level")
+
+ def delete_data(self, delta_list: List[DeltaRecord]):
+ raise NotImplementedError("QdrantIndex.delete_data is managed at collection level")
+
+ def search(
+ self,
+ query_vector: Optional[List[float]],
+ limit: int = 10,
+ filters: Optional[Dict[str, Any]] = None,
+ sparse_raw_terms: Optional[List[str]] = None,
+ sparse_values: Optional[List[float]] = None,
+ ) -> Tuple[List[int], List[float]]:
+ raise NotImplementedError("QdrantIndex.search is not exposed via raw index interface")
+
+ def aggregate(self, filters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+ raise NotImplementedError("QdrantIndex.aggregate is not exposed via raw index interface")
+
+ def update(self, scalar_index: Optional[Dict[str, Any]] = None, description: Optional[str] = None):
+ self._collection.update_index(
+ index_name=self._index_name,
+ scalar_index=scalar_index,
+ description=description,
+ )
+ self._meta = self._collection.get_index_meta_data(self._index_name) or self._meta
+
+ def get_meta_data(self):
+ return dict(self._meta)
+
+ def close(self):
+ return None
+
+ def drop(self):
+ self._collection.drop_index(self._index_name)
+
+
+class QdrantCollection(ICollection):
+ """Qdrant-backed collection implementation."""
+
+ DEFAULT_SCROLL_PAGE_SIZE = 256
+ DEFAULT_DELETE_BATCH_SIZE = 1_000
+ DEFAULT_HYBRID_PREFETCH_LIMIT = 32
+ MAX_HYBRID_PREFETCH_LIMIT = 256
+ MAX_SCROLL_ITERATIONS = 10_000
+ CLIENT_SIDE_SCAN_WARNING_THRESHOLD = 10_000
+ TEXT_INDEX_FIELDS = {"name", "description", "abstract", "tags"}
+
+ def __init__(
+ self,
+ *,
+ url: str,
+ api_key: str | None,
+ timeout_seconds: int,
+ project_name: str,
+ logical_collection_name: str,
+ physical_collection_name: str,
+ dense_vector_name: str,
+ sparse_vector_name: str,
+ meta_collection_name: str,
+ distance_metric: str,
+ enable_text_index: bool = False,
+ ) -> None:
+ super().__init__()
+ self._client = QdrantRestClient(
+ url=url,
+ api_key=api_key,
+ timeout_seconds=timeout_seconds,
+ )
+ self._project_name = project_name
+ self._logical_collection_name = logical_collection_name
+ self._physical_collection_name = physical_collection_name
+ self._dense_vector_name = dense_vector_name
+ self._sparse_vector_name = sparse_vector_name
+ self._distance_metric = distance_metric
+ self._enable_text_index = enable_text_index
+ self._meta_store = QdrantMetaStore(
+ client=self._client,
+ meta_collection_name=meta_collection_name,
+ )
+ self._vector_dim = 0
+ self._path_payload_fields: set[str] = {"parent_uri", "scope_roots"}
+ self._refresh_vector_dim_from_meta()
+
+ # ---------------------------------------------------------------------
+ # Helpers
+ # ---------------------------------------------------------------------
+ @property
+ def collection_key(self) -> str:
+ return self._physical_collection_name
+
+ def collection_exists(self) -> bool:
+ return self._client.collection_exists(self._physical_collection_name)
+
+ def _apply_meta_schema(self, meta: Dict[str, Any]) -> None:
+ path_payload_fields = {"parent_uri", "scope_roots"}
+ for field in meta.get("Fields", []):
+ if field.get("FieldType") == "path":
+ field_name = field.get("FieldName")
+ if field_name:
+ path_payload_fields.add(str(field_name))
+ if field.get("FieldType") == "vector":
+ try:
+ self._vector_dim = int(field.get("Dim") or 0)
+ except (TypeError, ValueError):
+ self._vector_dim = 0
+ self._path_payload_fields = path_payload_fields
+
+ def _refresh_vector_dim_from_meta(self) -> None:
+ meta = self._meta_store.get_collection_meta(collection_key=self.collection_key)
+ if not meta:
+ return
+ self._apply_meta_schema(meta)
+
+ @staticmethod
+ def _decode_path_value(value: Any) -> Any:
+ if isinstance(value, list):
+ return [QdrantCollection._decode_path_value(item) for item in value]
+ if not isinstance(value, str):
+ return value
+ stripped = value.strip()
+ if stripped.startswith("viking://") or not stripped.startswith("/"):
+ return value
+ suffix = stripped.strip("/")
+ return f"viking://{suffix}" if suffix else "viking://"
+
+ def _normalize_payload_for_read(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+ if not payload:
+ return {}
+ normalized = dict(payload)
+ for field_name in self._path_payload_fields:
+ if field_name in normalized:
+ normalized[field_name] = self._decode_path_value(normalized[field_name])
+ return normalized
+
+ def _build_vector_config(self, meta_data: Dict[str, Any]) -> Dict[str, Any]:
+ dense_dim = 0
+ has_sparse = False
+ for field in meta_data.get("Fields", []):
+ field_type = field.get("FieldType")
+ if field_type == "vector":
+ dense_dim = int(field.get("Dim") or 0)
+ elif field_type == "sparse_vector":
+ has_sparse = True
+
+ if dense_dim <= 0:
+ raise ValueError("Qdrant collection requires a positive dense vector dimension")
+
+ self._vector_dim = dense_dim
+ body: Dict[str, Any] = {
+ "vectors": {
+ self._dense_vector_name: {
+ "size": dense_dim,
+ "distance": _normalize_distance(self._distance_metric),
+ }
+ }
+ }
+ if has_sparse:
+ body["sparse_vectors"] = {self._sparse_vector_name: {}}
+ return body
+
+ def create_remote_collection(self, meta_data: Dict[str, Any]) -> None:
+ body = self._build_vector_config(meta_data)
+ self._client.request(
+ "PUT",
+ f"/collections/{self._physical_collection_name}",
+ json_body=body,
+ expected_statuses=(200, 201),
+ )
+ try:
+ self._meta_store.save_collection_meta(
+ collection_key=self.collection_key,
+ logical_collection_name=self._logical_collection_name,
+ project_name=self._project_name,
+ meta=meta_data,
+ )
+ except Exception:
+ try:
+ self._client.request(
+ "DELETE",
+ f"/collections/{self._physical_collection_name}",
+ expected_statuses=(200, 202, 404),
+ )
+ except Exception as cleanup_error:
+ logger.warning(
+ "Failed to rollback Qdrant collection after metadata write failure: collection=%s error=%s",
+ self._physical_collection_name,
+ cleanup_error,
+ )
+ raise
+ self._apply_meta_schema(meta_data)
+
+ def _make_point(self, record: Dict[str, Any]) -> Dict[str, Any]:
+ original_id = record.get("id")
+ if original_id is None or original_id == "":
+ raise ValueError("Qdrant point requires id")
+
+ dense_vector = record.get(self._dense_vector_name)
+ sparse_vector = record.get(self._sparse_vector_name)
+ payload = {
+ key: _coerce_iso_datetime(value)
+ for key, value in record.items()
+ if key not in {"id", self._dense_vector_name, self._sparse_vector_name}
+ }
+ payload[ORIGINAL_ID_FIELD] = _parse_point_id(original_id)
+
+ vector_payload: Dict[str, Any] = {}
+ if isinstance(dense_vector, list) and dense_vector:
+ vector_payload[self._dense_vector_name] = dense_vector
+
+ sparse_payload = _sparse_to_qdrant(sparse_vector)
+ if sparse_payload:
+ vector_payload[self._sparse_vector_name] = sparse_payload
+
+ if not vector_payload:
+ raise ValueError("Qdrant point requires at least one dense or sparse vector")
+
+ return {
+ "id": _to_qdrant_point_id(original_id),
+ "vector": vector_payload,
+ "payload": payload,
+ }
+
+ def _point_payload_for_read(self, point: Dict[str, Any]) -> Tuple[Any, Dict[str, Any]]:
+ raw_payload = dict(point.get("payload", {}) or {})
+ original_id = raw_payload.pop(ORIGINAL_ID_FIELD, None)
+ if original_id is None:
+ original_id = _parse_point_id(point.get("id"))
+ return original_id, self._normalize_payload_for_read(raw_payload)
+
+ def _parse_search_result(
+ self,
+ response: Dict[str, Any],
+ *,
+ offset: int,
+ limit: int,
+ ) -> SearchResult:
+ items: List[SearchItemResult] = []
+ for point in _extract_points(response):
+ if not isinstance(point, dict):
+ continue
+ original_id, payload = self._point_payload_for_read(point)
+ score = point.get("score") if isinstance(point, dict) else None
+ items.append(
+ SearchItemResult(
+ id=original_id,
+ fields=payload,
+ score=score,
+ )
+ )
+ if offset > 0:
+ items = items[offset:]
+ if len(items) > limit:
+ items = items[:limit]
+ return SearchResult(data=items)
+
+ def _parse_points_as_search_result(
+ self,
+ points: Sequence[Dict[str, Any]],
+ *,
+ score: Optional[float] = 1.0,
+ ) -> SearchResult:
+ data: List[SearchItemResult] = []
+ for point in points:
+ original_id, payload = self._point_payload_for_read(point)
+ data.append(
+ SearchItemResult(
+ id=original_id,
+ fields=payload,
+ score=score,
+ )
+ )
+ return SearchResult(data=data)
+
+ def _extract_named_vectors(
+ self,
+ point: Dict[str, Any],
+ ) -> Tuple[Optional[List[float]], Optional[Dict[str, List[Any]]]]:
+ vectors = point.get("vector")
+ if not isinstance(vectors, dict):
+ return None, None
+
+ dense_vector = vectors.get(self._dense_vector_name)
+ sparse_vector = vectors.get(self._sparse_vector_name)
+ if not isinstance(dense_vector, list):
+ dense_vector = None
+ if not isinstance(sparse_vector, dict):
+ sparse_vector = None
+ return dense_vector, sparse_vector
+
+ def _scroll_points(
+ self,
+ *,
+ filters: Optional[Dict[str, Any]] = None,
+ with_payload: bool | Dict[str, List[str]] = True,
+ limit: Optional[int] = None,
+ order_by: Optional[str] = None,
+ order_desc: bool = False,
+ ) -> List[Dict[str, Any]]:
+ points: List[Dict[str, Any]] = []
+ next_offset: Any = None
+ seen_offsets: set[str] = set()
+ iterations = 0
+
+ while iterations < self.MAX_SCROLL_ITERATIONS:
+ iterations += 1
+ remaining = None if limit is None else max(limit - len(points), 0)
+ if remaining == 0:
+ break
+
+ body: Dict[str, Any] = {
+ "limit": min(
+ self.DEFAULT_SCROLL_PAGE_SIZE,
+ remaining if remaining is not None else self.DEFAULT_SCROLL_PAGE_SIZE,
+ ),
+ "with_payload": with_payload,
+ "with_vector": False,
+ }
+ if filters:
+ body["filter"] = filters
+ if next_offset is not None:
+ body["offset"] = next_offset
+ if order_by:
+ body["order_by"] = {
+ "key": order_by,
+ "direction": "desc" if order_desc else "asc",
+ }
+
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/scroll",
+ json_body=body,
+ )
+ result = response.get("result", {})
+ page_points = result.get("points", []) if isinstance(result, dict) else []
+ if not page_points:
+ break
+
+ points.extend(page_points)
+ next_offset = result.get("next_page_offset") if isinstance(result, dict) else None
+ if next_offset is None:
+ break
+ offset_key = repr(next_offset)
+ if offset_key in seen_offsets:
+ logger.warning(
+ "Stopping Qdrant scroll early because next_page_offset repeated for collection=%s offset=%s",
+ self._physical_collection_name,
+ next_offset,
+ )
+ break
+ seen_offsets.add(offset_key)
+ else:
+ logger.warning(
+ "Stopping Qdrant scroll after reaching MAX_SCROLL_ITERATIONS=%s for collection=%s",
+ self.MAX_SCROLL_ITERATIONS,
+ self._physical_collection_name,
+ )
+ return points
+
+ def _scan_points_with_warning(
+ self,
+ *,
+ purpose: str,
+ filters: Optional[Dict[str, Any]],
+ with_payload: bool | Dict[str, List[str]],
+ limit: Optional[int] = None,
+ order_by: Optional[str] = None,
+ order_desc: bool = False,
+ ) -> List[Dict[str, Any]]:
+ if limit is None:
+ logger.warning(
+ "Qdrant %s uses client-side full scan/scroll. This may be expensive for large collections.",
+ purpose,
+ )
+ elif limit >= self.CLIENT_SIDE_SCAN_WARNING_THRESHOLD:
+ logger.warning(
+ "Qdrant %s will scan up to %s points client-side. This may be expensive for large collections.",
+ purpose,
+ limit,
+ )
+ return self._scroll_points(
+ filters=filters,
+ with_payload=with_payload,
+ limit=limit,
+ order_by=order_by,
+ order_desc=order_desc,
+ )
+
+ def _delete_field_index(self, field_name: str) -> None:
+ try:
+ self._client.request(
+ "DELETE",
+ f"/collections/{self._physical_collection_name}/index/{field_name}",
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+ except QdrantRestError as exc:
+ logger.warning("Failed to delete Qdrant field index %s: %s", field_name, exc)
+
+ def _field_type_map(self) -> Dict[str, str]:
+ meta = self.get_meta_data() or {}
+ fields = meta.get("Fields", [])
+ mapping = {field.get("FieldName"): field.get("FieldType") for field in fields}
+ mapping.setdefault("parent_uri", "string")
+ mapping.setdefault("scope_roots", "string")
+ mapping.setdefault("uri_depth", "int64")
+ return {str(k): str(v) for k, v in mapping.items() if k}
+
+ def _payload_field_schema(self, field_name: str, field_type: str) -> Optional[str]:
+ normalized_type = (field_type or "").lower()
+ if normalized_type in {"string", "path"}:
+ if self._enable_text_index and field_name in self.TEXT_INDEX_FIELDS:
+ return "text"
+ return "keyword"
+ if normalized_type in {"int64", "int32"}:
+ return "integer"
+ if normalized_type in {"float", "double"}:
+ return "float"
+ if normalized_type in {"bool", "boolean"}:
+ return "bool"
+ if normalized_type == "date_time":
+ return "datetime"
+ return None
+
+ def _count_points(self, filters: Optional[Dict[str, Any]] = None) -> int:
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/count",
+ json_body={
+ "filter": filters or {},
+ "exact": True,
+ },
+ )
+ result = response.get("result", {})
+ try:
+ return int(result.get("count", 0)) if isinstance(result, dict) else 0
+ except (TypeError, ValueError):
+ return 0
+
+ def _delete_points(self, point_ids: Sequence[Any]) -> None:
+ if not point_ids:
+ return
+ self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/delete",
+ json_body={"points": list(point_ids)},
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+
+ # ---------------------------------------------------------------------
+ # ICollection
+ # ---------------------------------------------------------------------
+ def update(self, fields: Optional[Dict[str, Any]] = None, description: Optional[str] = None):
+ meta = self._meta_store.update_collection_meta(
+ collection_key=self.collection_key,
+ logical_collection_name=self._logical_collection_name,
+ project_name=self._project_name,
+ fields=fields,
+ description=description,
+ )
+ if isinstance(meta, dict):
+ self._apply_meta_schema(meta)
+ return meta
+
+ def get_meta_data(self):
+ return self._meta_store.get_collection_meta(collection_key=self.collection_key) or {}
+
+ def has_openviking_metadata(self) -> bool:
+ return bool(self._meta_store.get_collection_meta(collection_key=self.collection_key))
+
+ def close(self):
+ self._client.close()
+
+ def drop(self):
+ try:
+ self._client.request(
+ "DELETE",
+ f"/collections/{self._physical_collection_name}",
+ expected_statuses=(200, 202, 404),
+ )
+ finally:
+ self._meta_store.delete_collection_meta(collection_key=self.collection_key)
+
+ def create_index(self, index_name: str, meta_data: Dict[str, Any]):
+ field_type_map = self._field_type_map()
+ scalar_fields = list(meta_data.get("ScalarIndex", []) or [])
+ for field_name in scalar_fields:
+ field_schema = self._payload_field_schema(field_name, field_type_map.get(field_name, ""))
+ if not field_schema:
+ continue
+ self._client.request(
+ "PUT",
+ f"/collections/{self._physical_collection_name}/index",
+ json_body={
+ "field_name": field_name,
+ "field_schema": field_schema,
+ },
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+ self._meta_store.save_index_meta(
+ collection_key=self.collection_key,
+ logical_collection_name=self._logical_collection_name,
+ index_name=index_name,
+ meta=meta_data,
+ )
+ return QdrantIndex(self, index_name, meta_data)
+
+ def has_index(self, index_name: str) -> bool:
+ return index_name in self.list_indexes()
+
+ def get_index(self, index_name: str) -> Optional[IIndex]:
+ meta = self.get_index_meta_data(index_name)
+ if not meta:
+ return None
+ return QdrantIndex(self, index_name, meta)
+
+ def search_by_vector(
+ self,
+ index_name: str,
+ dense_vector: Optional[List[float]] = None,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ sparse_vector: Optional[Dict[str, float]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ if dense_vector is None and sparse_vector is None:
+ return SearchResult()
+
+ fetch_limit = max(limit + offset, limit)
+ body: Dict[str, Any] = {
+ "limit": fetch_limit,
+ "with_payload": _payload_selector(output_fields),
+ }
+ if filters:
+ body["filter"] = filters
+
+ try:
+ if dense_vector is not None and sparse_vector:
+ sparse_payload = _sparse_to_qdrant(sparse_vector)
+ if not sparse_payload:
+ sparse_vector = None
+ else:
+ hybrid_prefetch_limit = min(
+ max(fetch_limit * 4, fetch_limit + 8, self.DEFAULT_HYBRID_PREFETCH_LIMIT),
+ self.MAX_HYBRID_PREFETCH_LIMIT,
+ )
+ body.update(
+ {
+ "prefetch": [
+ {
+ "query": dense_vector,
+ "using": self._dense_vector_name,
+ "limit": hybrid_prefetch_limit,
+ },
+ {
+ "query": sparse_payload,
+ "using": self._sparse_vector_name,
+ "limit": hybrid_prefetch_limit,
+ },
+ ],
+ "query": {"fusion": "rrf"},
+ }
+ )
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/query",
+ json_body=body,
+ expected_statuses=(200, 202),
+ )
+ return self._parse_search_result(response, offset=offset, limit=limit)
+
+ if sparse_vector and dense_vector is None:
+ sparse_payload = _sparse_to_qdrant(sparse_vector)
+ if not sparse_payload:
+ return SearchResult()
+ body.update(
+ {
+ "query": sparse_payload,
+ "using": self._sparse_vector_name,
+ }
+ )
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/query",
+ json_body=body,
+ expected_statuses=(200, 202),
+ )
+ return self._parse_search_result(response, offset=offset, limit=limit)
+
+ if dense_vector is None:
+ return SearchResult()
+
+ body.update(
+ {
+ "query": dense_vector,
+ "using": self._dense_vector_name,
+ }
+ )
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/query",
+ json_body=body,
+ expected_statuses=(200, 202),
+ )
+ return self._parse_search_result(response, offset=offset, limit=limit)
+ except QdrantRestError as exc:
+ if dense_vector is None:
+ raise
+ logger.warning(
+ "Falling back to Qdrant /points/search for dense-only query because /points/query failed: %s",
+ exc,
+ )
+ fallback_body: Dict[str, Any] = {
+ "vector": {
+ "name": self._dense_vector_name,
+ "vector": dense_vector,
+ },
+ "limit": fetch_limit,
+ "with_payload": _payload_selector(output_fields),
+ }
+ if filters:
+ fallback_body["filter"] = filters
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/search",
+ json_body=fallback_body,
+ expected_statuses=(200, 202),
+ )
+ return self._parse_search_result(response, offset=offset, limit=limit)
+
+ def search_by_keywords(
+ self,
+ index_name: str,
+ keywords: Optional[List[str]] = None,
+ query: Optional[str] = None,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ query_text = query or " ".join(keywords or [])
+ if not query_text.strip():
+ return SearchResult()
+
+ text_filter = {
+ "should": [
+ {"must": [{"key": field_name, "match": {"text": query_text}}]}
+ for field_name in sorted(self.TEXT_INDEX_FIELDS)
+ ]
+ }
+ compound_filter = {"must": [filters, text_filter]} if filters else text_filter
+ points = self._scroll_points(
+ filters=compound_filter,
+ with_payload=_payload_selector(output_fields),
+ limit=limit + offset,
+ )
+ if offset > 0:
+ points = points[offset:]
+ if len(points) > limit:
+ points = points[:limit]
+ return SearchResult(
+ data=self._parse_points_as_search_result(points, score=1.0).data
+ )
+
+ def search_by_id(
+ self,
+ index_name: str,
+ id: Any,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ point_id = _to_qdrant_point_id(id)
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points",
+ json_body={
+ "ids": [point_id],
+ "with_payload": _payload_selector([ORIGINAL_ID_FIELD]),
+ "with_vector": True,
+ },
+ )
+ points = _extract_points(response)
+ if not points:
+ return SearchResult()
+
+ dense_vector, sparse_payload = self._extract_named_vectors(points[0])
+ if dense_vector is None and sparse_payload is None:
+ return SearchResult()
+
+ fetch_limit = max(limit + offset + 1, limit + 1)
+ body: Dict[str, Any] = {
+ "limit": fetch_limit,
+ "with_payload": _payload_selector(output_fields),
+ }
+ if filters:
+ body["filter"] = filters
+
+ try:
+ if dense_vector is not None and sparse_payload is not None:
+ hybrid_prefetch_limit = min(
+ max(fetch_limit * 4, fetch_limit + 8, self.DEFAULT_HYBRID_PREFETCH_LIMIT),
+ self.MAX_HYBRID_PREFETCH_LIMIT,
+ )
+ body.update(
+ {
+ "prefetch": [
+ {
+ "query": dense_vector,
+ "using": self._dense_vector_name,
+ "limit": hybrid_prefetch_limit,
+ },
+ {
+ "query": sparse_payload,
+ "using": self._sparse_vector_name,
+ "limit": hybrid_prefetch_limit,
+ },
+ ],
+ "query": {"fusion": "rrf"},
+ }
+ )
+ elif sparse_payload is not None:
+ body.update({"query": sparse_payload, "using": self._sparse_vector_name})
+ else:
+ body.update({"query": dense_vector, "using": self._dense_vector_name})
+
+ search_response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/query",
+ json_body=body,
+ expected_statuses=(200, 202),
+ )
+ except QdrantRestError as exc:
+ if dense_vector is None:
+ raise
+ logger.warning(
+ "Falling back to Qdrant /points/search for search_by_id because /points/query failed: %s",
+ exc,
+ )
+ fallback_body: Dict[str, Any] = {
+ "vector": {
+ "name": self._dense_vector_name,
+ "vector": dense_vector,
+ },
+ "limit": fetch_limit,
+ "with_payload": _payload_selector(output_fields),
+ }
+ if filters:
+ fallback_body["filter"] = filters
+ search_response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/search",
+ json_body=fallback_body,
+ expected_statuses=(200, 202),
+ )
+
+ data = []
+ for item in self._parse_search_result(search_response, offset=0, limit=fetch_limit).data:
+ if item.id == id or str(item.id) == str(id):
+ continue
+ data.append(item)
+ return SearchResult(data=data[offset : offset + limit])
+
+ def search_by_multimodal(
+ self,
+ index_name: str,
+ text: Optional[str],
+ image: Optional[Any],
+ video: Optional[Any],
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ raise NotImplementedError("QdrantCollection.search_by_multimodal is not supported")
+
+ def search_by_random(
+ self,
+ index_name: str,
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ points = self._scroll_points(
+ filters=filters,
+ with_payload=_payload_selector(output_fields),
+ limit=limit + offset,
+ )
+ if offset > 0:
+ points = points[offset:]
+ if len(points) > limit:
+ points = points[:limit]
+ return SearchResult(
+ data=self._parse_points_as_search_result(points, score=1.0).data
+ )
+
+ def search_by_scalar(
+ self,
+ index_name: str,
+ field: str,
+ order: Optional[str] = "desc",
+ limit: int = 10,
+ offset: int = 0,
+ filters: Optional[Dict[str, Any]] = None,
+ output_fields: Optional[List[str]] = None,
+ ) -> SearchResult:
+ need_cleanup = False
+ with_payload = list(output_fields or [])
+ if field not in with_payload:
+ with_payload.append(field)
+ need_cleanup = True
+
+ reverse = (order or "desc").lower() == "desc"
+ try:
+ points = self._scan_points_with_warning(
+ purpose="scalar sort",
+ filters=filters,
+ with_payload=_payload_selector(with_payload),
+ limit=limit + offset,
+ order_by=field,
+ order_desc=reverse,
+ )
+ except QdrantRestError as exc:
+ logger.warning(
+ "Falling back to client-side scalar sort because Qdrant order_by is unavailable for field=%s: %s",
+ field,
+ exc,
+ )
+ points = self._scan_points_with_warning(
+ purpose="scalar sort fallback",
+ filters=filters,
+ with_payload=_payload_selector(with_payload),
+ limit=None,
+ )
+ points.sort(
+ key=lambda point: (
+ point.get("payload", {}).get(field) is None,
+ point.get("payload", {}).get(field),
+ ),
+ reverse=reverse,
+ )
+ points = points[offset : offset + limit]
+ data: List[SearchItemResult] = []
+ for point in points:
+ original_id, payload = self._point_payload_for_read(point)
+ score = payload.get(field)
+ if need_cleanup:
+ payload.pop(field, None)
+ data.append(
+ SearchItemResult(
+ id=original_id,
+ fields=payload,
+ score=score if isinstance(score, (int, float)) else None,
+ )
+ )
+ return SearchResult(data=data)
+
+ def update_index(
+ self,
+ index_name: str,
+ scalar_index: Optional[Dict[str, Any]] = None,
+ description: Optional[str] = None,
+ ):
+ current_meta = self.get_index_meta_data(index_name) or {"IndexName": index_name}
+ old_scalar_fields = set(current_meta.get("ScalarIndex", []) or [])
+
+ if scalar_index is not None:
+ if isinstance(scalar_index, dict):
+ new_scalar_fields = list(scalar_index.keys())
+ else:
+ new_scalar_fields = list(scalar_index)
+ current_meta["ScalarIndex"] = new_scalar_fields
+ else:
+ new_scalar_fields = list(current_meta.get("ScalarIndex", []) or [])
+
+ if description is not None:
+ current_meta["Description"] = description
+
+ field_type_map = self._field_type_map()
+ for field_name in new_scalar_fields:
+ if field_name in old_scalar_fields:
+ continue
+ field_schema = self._payload_field_schema(field_name, field_type_map.get(field_name, ""))
+ if not field_schema:
+ continue
+ self._client.request(
+ "PUT",
+ f"/collections/{self._physical_collection_name}/index",
+ json_body={
+ "field_name": field_name,
+ "field_schema": field_schema,
+ },
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+
+ for field_name in sorted(old_scalar_fields - set(new_scalar_fields)):
+ self._delete_field_index(field_name)
+
+ self._meta_store.save_index_meta(
+ collection_key=self.collection_key,
+ logical_collection_name=self._logical_collection_name,
+ index_name=index_name,
+ meta=current_meta,
+ )
+ return current_meta
+
+ def get_index_meta_data(self, index_name: str):
+ return self._meta_store.get_index_meta(collection_key=self.collection_key, index_name=index_name)
+
+ def list_indexes(self):
+ return self._meta_store.list_indexes(collection_key=self.collection_key)
+
+ def drop_index(self, index_name: str):
+ index_meta = self.get_index_meta_data(index_name) or {}
+ for field_name in index_meta.get("ScalarIndex", []) or []:
+ self._delete_field_index(field_name)
+ self._meta_store.delete_index_meta(collection_key=self.collection_key, index_name=index_name)
+
+ def upsert_data(self, data_list: List[Dict[str, Any]], ttl=0):
+ # Qdrant does not provide a collection-level per-point TTL primitive that
+ # matches the existing ICollection contract, so ttl is accepted only for
+ # interface compatibility and intentionally ignored here.
+ points = [self._make_point(data) for data in data_list]
+ self._client.request(
+ "PUT",
+ f"/collections/{self._physical_collection_name}/points",
+ json_body={"points": points},
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+ return [data.get("id") for data in data_list]
+
+ def fetch_data(self, primary_keys: List[Any]):
+ if not primary_keys:
+ return FetchDataInCollectionResult()
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points",
+ json_body={
+ "ids": [_to_qdrant_point_id(pk) for pk in primary_keys],
+ "with_payload": True,
+ "with_vector": False,
+ },
+ )
+ points = _extract_points(response)
+ items: List[DataItem] = []
+ found_ids: set[str] = set()
+ for point in points:
+ if not isinstance(point, dict):
+ continue
+ original_id, payload = self._point_payload_for_read(point)
+ found_ids.add(str(original_id))
+ items.append(DataItem(id=original_id, fields=payload))
+ return FetchDataInCollectionResult(
+ items=items,
+ ids_not_exist=[pk for pk in primary_keys if str(pk) not in found_ids],
+ )
+
+ def delete_data(self, primary_keys: List[Any]):
+ self._delete_points([_to_qdrant_point_id(pk) for pk in primary_keys])
+
+ def delete_all_data(self):
+ try:
+ self._client.request(
+ "POST",
+ f"/collections/{self._physical_collection_name}/points/delete",
+ json_body={"filter": {}},
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+ except QdrantRestError as exc:
+ logger.warning(
+ "Falling back to batched delete_all_data for collection=%s because filter delete failed: %s",
+ self._physical_collection_name,
+ exc,
+ )
+ points = self._scan_points_with_warning(
+ purpose="delete_all_data fallback",
+ filters=None,
+ with_payload=False,
+ limit=None,
+ )
+ batch_ids: List[str] = []
+ for point in points:
+ batch_ids.append(_parse_point_id(point.get("id")))
+ if len(batch_ids) >= self.DEFAULT_DELETE_BATCH_SIZE:
+ self._delete_points(batch_ids)
+ batch_ids = []
+ if batch_ids:
+ self._delete_points(batch_ids)
+
+ def aggregate_data(
+ self,
+ index_name: str,
+ op: str = "count",
+ field: Optional[str] = None,
+ filters: Optional[Dict[str, Any]] = None,
+ cond: Optional[Dict[str, Any]] = None,
+ ) -> AggregateResult:
+ if op != "count":
+ return AggregateResult(agg={}, op=op, field=field)
+
+ if not field:
+ return AggregateResult(
+ agg={"_total": self._count_points(filters)},
+ op="count",
+ field=None,
+ )
+
+ grouped: Dict[Any, int] = {}
+ points = self._scan_points_with_warning(
+ purpose=f"aggregate(count by {field})",
+ filters=filters,
+ with_payload=_payload_selector([field]),
+ limit=None,
+ )
+ for point in points:
+ payload = point.get("payload", {})
+ value = payload.get(field)
+ if value is None:
+ continue
+ if field in self._path_payload_fields:
+ value = self._decode_path_value(value)
+ grouped[value] = grouped.get(value, 0) + 1
+
+ if cond:
+ filtered_grouped: Dict[Any, int] = {}
+ for key, value in grouped.items():
+ include = True
+ if cond.get("gt") is not None:
+ include = include and value > cond["gt"]
+ if cond.get("gte") is not None:
+ include = include and value >= cond["gte"]
+ if cond.get("lt") is not None:
+ include = include and value < cond["lt"]
+ if cond.get("lte") is not None:
+ include = include and value <= cond["lte"]
+ if include:
+ filtered_grouped[key] = value
+ grouped = filtered_grouped
+
+ return AggregateResult(agg=grouped, op="count", field=field)
diff --git a/openviking/storage/vectordb/collection/qdrant_meta_store.py b/openviking/storage/vectordb/collection/qdrant_meta_store.py
new file mode 100644
index 000000000..4d344d6ef
--- /dev/null
+++ b/openviking/storage/vectordb/collection/qdrant_meta_store.py
@@ -0,0 +1,291 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Sidecar metadata persistence for Qdrant-backed OpenViking collections."""
+
+from __future__ import annotations
+
+import datetime as dt
+import uuid
+from typing import Any, Dict, List, Optional
+
+from .qdrant_rest import QdrantRestClient, QdrantRestError
+
+
+def _utcnow_iso() -> str:
+ return dt.datetime.now(dt.timezone.utc).isoformat()
+
+
+class QdrantMetaStore:
+ """Store OpenViking collection/index metadata in a dedicated Qdrant collection."""
+
+ COLLECTION_KIND = "collection"
+ INDEX_KIND = "index"
+
+ def __init__(
+ self,
+ *,
+ client: QdrantRestClient,
+ meta_collection_name: str,
+ ) -> None:
+ self._client = client
+ self._meta_collection_name = meta_collection_name
+ self._meta_collection_ensured = False
+
+ @property
+ def meta_collection_name(self) -> str:
+ return self._meta_collection_name
+
+ def _ensure_meta_collection(self) -> None:
+ if self._meta_collection_ensured:
+ return
+ if self._client.collection_exists(self._meta_collection_name):
+ self._meta_collection_ensured = True
+ return
+ self._client.request(
+ "PUT",
+ f"/collections/{self._meta_collection_name}",
+ json_body={
+ # Keep metadata in a tiny dedicated collection. Some Qdrant
+ # deployments still require vector configuration, so we use a
+ # 1D dummy vector payload for sidecar metadata documents.
+ "vectors": {
+ "size": 1,
+ "distance": "Cosine",
+ }
+ },
+ expected_statuses=(200, 201),
+ )
+ self._meta_collection_ensured = True
+
+ @staticmethod
+ def _collection_doc_id(collection_key: str) -> str:
+ return str(uuid.uuid5(uuid.NAMESPACE_URL, f"openviking:qdrant:collection:{collection_key}"))
+
+ @staticmethod
+ def _index_doc_id(collection_key: str, index_name: str) -> str:
+ return str(
+ uuid.uuid5(
+ uuid.NAMESPACE_URL,
+ f"openviking:qdrant:index:{collection_key}:{index_name}",
+ )
+ )
+
+ def _upsert_meta_doc(self, *, point_id: str, payload: Dict[str, Any]) -> None:
+ self._ensure_meta_collection()
+ self._client.request(
+ "PUT",
+ f"/collections/{self._meta_collection_name}/points",
+ json_body={
+ "points": [
+ {
+ "id": point_id,
+ "vector": [0.0],
+ "payload": payload,
+ }
+ ]
+ },
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+
+ def _get_point(self, point_id: str) -> Optional[Dict[str, Any]]:
+ if not self._meta_collection_ensured and not self._client.collection_exists(
+ self._meta_collection_name
+ ):
+ return None
+ self._meta_collection_ensured = True
+ try:
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._meta_collection_name}/points",
+ json_body={
+ "ids": [point_id],
+ "with_payload": True,
+ "with_vector": False,
+ },
+ )
+ except QdrantRestError as exc:
+ if exc.status_code == 404:
+ return None
+ raise
+
+ result = response.get("result", {})
+ if isinstance(result, list):
+ points = result
+ elif isinstance(result, dict):
+ points = result.get("points", [])
+ else:
+ points = []
+ return points[0] if points else None
+
+ def _scroll_index_docs(self, collection_key: str) -> List[Dict[str, Any]]:
+ if not self._meta_collection_ensured and not self._client.collection_exists(
+ self._meta_collection_name
+ ):
+ return []
+ self._meta_collection_ensured = True
+ points: List[Dict[str, Any]] = []
+ next_offset: Optional[Any] = None
+
+ while True:
+ request_body: Dict[str, Any] = {
+ "limit": 128,
+ "with_payload": True,
+ "with_vector": False,
+ "filter": {
+ "must": [
+ {"key": "kind", "match": {"value": self.INDEX_KIND}},
+ {"key": "collection_key", "match": {"value": collection_key}},
+ ]
+ },
+ }
+ if next_offset is not None:
+ request_body["offset"] = next_offset
+
+ response = self._client.request(
+ "POST",
+ f"/collections/{self._meta_collection_name}/points/scroll",
+ json_body=request_body,
+ )
+ result = response.get("result", {})
+ if not isinstance(result, dict):
+ break
+
+ batch = result.get("points", [])
+ if isinstance(batch, list):
+ points.extend(batch)
+
+ next_offset = result.get("next_page_offset")
+ if next_offset is None:
+ break
+
+ return points
+
+ def save_collection_meta(
+ self,
+ *,
+ collection_key: str,
+ logical_collection_name: str,
+ project_name: str,
+ meta: Dict[str, Any],
+ ) -> None:
+ now = _utcnow_iso()
+ payload = {
+ "kind": self.COLLECTION_KIND,
+ "collection_key": collection_key,
+ "logical_collection_name": logical_collection_name,
+ "project_name": project_name,
+ "meta": meta,
+ "updated_at": now,
+ }
+ self._upsert_meta_doc(
+ point_id=self._collection_doc_id(collection_key),
+ payload=payload,
+ )
+
+ def get_collection_meta(self, *, collection_key: str) -> Optional[Dict[str, Any]]:
+ point = self._get_point(self._collection_doc_id(collection_key))
+ if not point:
+ return None
+ payload = point.get("payload", {})
+ meta = payload.get("meta")
+ return meta if isinstance(meta, dict) else None
+
+ def update_collection_meta(
+ self,
+ *,
+ collection_key: str,
+ logical_collection_name: str,
+ project_name: str,
+ fields: Optional[Dict[str, Any]] = None,
+ description: Optional[str] = None,
+ ) -> Dict[str, Any]:
+ meta = self.get_collection_meta(collection_key=collection_key) or {
+ "CollectionName": logical_collection_name
+ }
+ if fields is not None:
+ meta["Fields"] = fields
+ if description is not None:
+ meta["Description"] = description
+ self.save_collection_meta(
+ collection_key=collection_key,
+ logical_collection_name=logical_collection_name,
+ project_name=project_name,
+ meta=meta,
+ )
+ return meta
+
+ def save_index_meta(
+ self,
+ *,
+ collection_key: str,
+ logical_collection_name: str,
+ index_name: str,
+ meta: Dict[str, Any],
+ ) -> None:
+ now = _utcnow_iso()
+ payload = {
+ "kind": self.INDEX_KIND,
+ "collection_key": collection_key,
+ "logical_collection_name": logical_collection_name,
+ "index_name": index_name,
+ "meta": meta,
+ "updated_at": now,
+ }
+ self._upsert_meta_doc(
+ point_id=self._index_doc_id(collection_key, index_name),
+ payload=payload,
+ )
+
+ def get_index_meta(self, *, collection_key: str, index_name: str) -> Optional[Dict[str, Any]]:
+ point = self._get_point(self._index_doc_id(collection_key, index_name))
+ if not point:
+ return None
+ payload = point.get("payload", {})
+ meta = payload.get("meta")
+ return meta if isinstance(meta, dict) else None
+
+ def list_indexes(self, *, collection_key: str) -> List[str]:
+ docs = self._scroll_index_docs(collection_key)
+ index_names: List[str] = []
+ for doc in docs:
+ payload = doc.get("payload", {})
+ index_name = payload.get("index_name")
+ if isinstance(index_name, str):
+ index_names.append(index_name)
+ return index_names
+
+ def delete_index_meta(self, *, collection_key: str, index_name: str) -> None:
+ if not self._meta_collection_ensured and not self._client.collection_exists(
+ self._meta_collection_name
+ ):
+ return
+ self._meta_collection_ensured = True
+ self._client.request(
+ "POST",
+ f"/collections/{self._meta_collection_name}/points/delete",
+ json_body={"points": [self._index_doc_id(collection_key, index_name)]},
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
+
+ def delete_collection_meta(self, *, collection_key: str) -> None:
+ if not self._meta_collection_ensured and not self._client.collection_exists(
+ self._meta_collection_name
+ ):
+ return
+ self._meta_collection_ensured = True
+ point_ids = [self._collection_doc_id(collection_key)]
+ point_ids.extend(
+ self._index_doc_id(collection_key, index_name)
+ for index_name in self.list_indexes(collection_key=collection_key)
+ )
+ if not point_ids:
+ return
+ self._client.request(
+ "POST",
+ f"/collections/{self._meta_collection_name}/points/delete",
+ json_body={"points": point_ids},
+ params={"wait": "true"},
+ expected_statuses=(200, 202),
+ )
diff --git a/openviking/storage/vectordb/collection/qdrant_rest.py b/openviking/storage/vectordb/collection/qdrant_rest.py
new file mode 100644
index 000000000..0dce339f9
--- /dev/null
+++ b/openviking/storage/vectordb/collection/qdrant_rest.py
@@ -0,0 +1,239 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Lightweight Qdrant REST client helpers used by the adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Dict, Optional
+
+import httpx
+import requests
+
+
+class QdrantRestError(RuntimeError):
+ """Raised when a Qdrant REST request fails."""
+
+ def __init__(
+ self,
+ message: str,
+ *,
+ status_code: int | None = None,
+ response_text: str | None = None,
+ ) -> None:
+ super().__init__(message)
+ self.status_code = status_code
+ self.response_text = response_text
+
+
+class QdrantRestClient:
+ """Minimal REST client for Qdrant.
+
+ The implementation intentionally uses REST instead of `qdrant-client` so the
+ adapter can be developed and unit-tested without introducing a hard runtime
+ dependency on the Python SDK.
+
+ This client is intentionally synchronous because the current ICollection
+ contract is synchronous across backends. Async OpenViking code paths must
+ either:
+
+ 1. use the async backend façade (`_AsyncVectorAdapter`) that wraps adapter
+ calls with `asyncio.to_thread`, or
+ 2. use `request_async()` / `collection_exists_async()` directly.
+ """
+
+ def __init__(
+ self,
+ *,
+ url: str,
+ api_key: str | None = None,
+ timeout_seconds: int = 10,
+ ) -> None:
+ normalized = url.strip()
+ if normalized and not normalized.startswith(("http://", "https://")):
+ normalized = f"http://{normalized}"
+ self._base_url = normalized.rstrip("/")
+ self._timeout_seconds = timeout_seconds
+ self._session = requests.Session()
+ self._headers: Dict[str, str] = {"Content-Type": "application/json"}
+ if api_key:
+ self._headers["api-key"] = api_key
+
+ @property
+ def base_url(self) -> str:
+ return self._base_url
+
+ def close(self) -> None:
+ self._session.close()
+
+ def request(
+ self,
+ method: str,
+ path: str,
+ *,
+ json_body: Optional[Dict[str, Any]] = None,
+ params: Optional[Dict[str, Any]] = None,
+ expected_statuses: tuple[int, ...] = (200,),
+ ) -> Dict[str, Any]:
+ response = self._session.request(
+ method=method.upper(),
+ url=f"{self._base_url}{path}",
+ headers=self._headers,
+ json=json_body,
+ params=params,
+ timeout=self._timeout_seconds,
+ )
+ if response.status_code not in expected_statuses:
+ raise QdrantRestError(
+ f"Qdrant request failed: {method.upper()} {path} -> {response.status_code}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+
+ if not response.text:
+ return {}
+
+ try:
+ data = response.json()
+ except json.JSONDecodeError as exc:
+ raise QdrantRestError(
+ f"Qdrant returned non-JSON response for {method.upper()} {path}",
+ status_code=response.status_code,
+ response_text=response.text,
+ ) from exc
+
+ if isinstance(data, dict) and data.get("status") == "error":
+ raise QdrantRestError(
+ f"Qdrant reported error for {method.upper()} {path}: {data.get('result') or data}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+ return data if isinstance(data, dict) else {"result": data}
+
+ async def request_async(
+ self,
+ method: str,
+ path: str,
+ *,
+ json_body: Optional[Dict[str, Any]] = None,
+ params: Optional[Dict[str, Any]] = None,
+ expected_statuses: tuple[int, ...] = (200,),
+ ) -> Dict[str, Any]:
+ return await asyncio.to_thread(
+ self.request,
+ method,
+ path,
+ json_body=json_body,
+ params=params,
+ expected_statuses=expected_statuses,
+ )
+
+ def collection_exists(self, collection_name: str) -> bool:
+ response = self._session.get(
+ f"{self._base_url}/collections/{collection_name}",
+ headers=self._headers,
+ timeout=self._timeout_seconds,
+ )
+ if response.status_code == 404:
+ return False
+ if response.status_code != 200:
+ raise QdrantRestError(
+ f"Failed to check Qdrant collection existence: {collection_name}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+ return True
+
+ async def collection_exists_async(self, collection_name: str) -> bool:
+ return await asyncio.to_thread(self.collection_exists, collection_name)
+
+
+class AsyncQdrantRestClient:
+ """Async REST client for Qdrant based on httpx.AsyncClient.
+
+ This is provided for async-only call sites that should not rely on
+ `asyncio.to_thread`. The current Qdrant ICollection implementation remains
+ synchronous because it follows the shared ICollection interface.
+ """
+
+ def __init__(
+ self,
+ *,
+ url: str,
+ api_key: str | None = None,
+ timeout_seconds: int = 10,
+ ) -> None:
+ normalized = url.strip()
+ if normalized and not normalized.startswith(("http://", "https://")):
+ normalized = f"http://{normalized}"
+ self._base_url = normalized.rstrip("/")
+ headers: Dict[str, str] = {"Content-Type": "application/json"}
+ if api_key:
+ headers["api-key"] = api_key
+ self._client = httpx.AsyncClient(
+ base_url=self._base_url,
+ headers=headers,
+ timeout=timeout_seconds,
+ )
+
+ @property
+ def base_url(self) -> str:
+ return self._base_url
+
+ async def close(self) -> None:
+ await self._client.aclose()
+
+ async def request(
+ self,
+ method: str,
+ path: str,
+ *,
+ json_body: Optional[Dict[str, Any]] = None,
+ params: Optional[Dict[str, Any]] = None,
+ expected_statuses: tuple[int, ...] = (200,),
+ ) -> Dict[str, Any]:
+ response = await self._client.request(
+ method=method.upper(),
+ url=path,
+ json=json_body,
+ params=params,
+ )
+ if response.status_code not in expected_statuses:
+ raise QdrantRestError(
+ f"Qdrant request failed: {method.upper()} {path} -> {response.status_code}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+
+ if not response.text:
+ return {}
+
+ try:
+ data = response.json()
+ except json.JSONDecodeError as exc:
+ raise QdrantRestError(
+ f"Qdrant returned non-JSON response for {method.upper()} {path}",
+ status_code=response.status_code,
+ response_text=response.text,
+ ) from exc
+
+ if isinstance(data, dict) and data.get("status") == "error":
+ raise QdrantRestError(
+ f"Qdrant reported error for {method.upper()} {path}: {data.get('result') or data}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+ return data if isinstance(data, dict) else {"result": data}
+
+ async def collection_exists(self, collection_name: str) -> bool:
+ response = await self._client.get(f"/collections/{collection_name}")
+ if response.status_code == 404:
+ return False
+ if response.status_code != 200:
+ raise QdrantRestError(
+ f"Failed to check Qdrant collection existence: {collection_name}",
+ status_code=response.status_code,
+ response_text=response.text,
+ )
+ return True
diff --git a/openviking/storage/vectordb_adapters/factory.py b/openviking/storage/vectordb_adapters/factory.py
index f86b733b2..3629240d5 100644
--- a/openviking/storage/vectordb_adapters/factory.py
+++ b/openviking/storage/vectordb_adapters/factory.py
@@ -4,15 +4,19 @@
from __future__ import annotations
+import importlib
+
from .base import CollectionAdapter
from .http_adapter import HttpCollectionAdapter
from .local_adapter import LocalCollectionAdapter
+from .qdrant_adapter import QdrantCollectionAdapter
from .vikingdb_private_adapter import VikingDBPrivateCollectionAdapter
from .volcengine_adapter import VolcengineCollectionAdapter
_ADAPTER_REGISTRY: dict[str, type[CollectionAdapter]] = {
"local": LocalCollectionAdapter,
"http": HttpCollectionAdapter,
+ "qdrant": QdrantCollectionAdapter,
"volcengine": VolcengineCollectionAdapter,
"vikingdb": VikingDBPrivateCollectionAdapter,
}
@@ -26,8 +30,6 @@ def create_collection_adapter(config) -> CollectionAdapter:
# If not in registry, try to load dynamically as a class path
if adapter_cls is None and "." in backend:
try:
- import importlib
-
module_name, class_name = backend.rsplit(".", 1)
module = importlib.import_module(module_name)
potential_cls = getattr(module, class_name)
diff --git a/openviking/storage/vectordb_adapters/qdrant_adapter.py b/openviking/storage/vectordb_adapters/qdrant_adapter.py
new file mode 100644
index 000000000..40ee4fff4
--- /dev/null
+++ b/openviking/storage/vectordb_adapters/qdrant_adapter.py
@@ -0,0 +1,376 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Qdrant backend collection adapter."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+from openviking.storage.expr import (
+ And,
+ Contains,
+ Eq,
+ FilterExpr,
+ In,
+ Or,
+ PathScope,
+ Range,
+ RawDSL,
+ TimeRange,
+)
+from openviking.storage.vectordb.collection.collection import Collection
+from openviking.storage.vectordb.collection.qdrant_collection import QdrantCollection
+
+from .base import CollectionAdapter
+
+
+class QdrantCollectionAdapter(CollectionAdapter):
+ """Adapter for Qdrant-backed vector collections."""
+
+ INTERNAL_PATH_FIELDS = ["parent_uri", "scope_roots", "uri_depth"]
+ DEFAULT_TEXT_INDEX_FIELDS = ["name", "description", "abstract", "tags"]
+
+ def __init__(
+ self,
+ *,
+ url: str,
+ api_key: str | None,
+ timeout_seconds: int,
+ project_name: str,
+ collection_name: str,
+ index_name: str,
+ distance_metric: str,
+ dense_vector_name: str,
+ sparse_vector_name: str,
+ meta_collection_name: str,
+ enable_text_index: bool,
+ ) -> None:
+ super().__init__(collection_name=collection_name, index_name=index_name)
+ self.mode = "qdrant"
+ self._url = url
+ self._api_key = api_key
+ self._timeout_seconds = timeout_seconds
+ self._project_name = project_name
+ self._distance_metric = distance_metric
+ self._dense_vector_name = dense_vector_name
+ self._sparse_vector_name = sparse_vector_name
+ self._meta_collection_name = meta_collection_name
+ self._enable_text_index = enable_text_index
+
+ @classmethod
+ def from_config(cls, config: Any):
+ cfg = getattr(config, "qdrant", None)
+ params = dict(getattr(config, "custom_params", {}) or {})
+ url = (
+ getattr(cfg, "url", None)
+ or getattr(config, "url", None)
+ or params.get("url")
+ )
+ if not url:
+ raise ValueError("Qdrant backend requires qdrant.url or url")
+ return cls(
+ url=str(url).strip().rstrip("/"),
+ api_key=getattr(cfg, "api_key", None) or params.get("api_key"),
+ timeout_seconds=int(getattr(cfg, "timeout_seconds", None) or params.get("timeout_seconds") or 10),
+ project_name=config.project_name or "default",
+ collection_name=config.name or "context",
+ index_name=config.index_name or "default",
+ distance_metric=config.distance_metric or "cosine",
+ dense_vector_name=getattr(cfg, "dense_vector_name", "vector"),
+ sparse_vector_name=getattr(cfg, "sparse_vector_name", "sparse_vector"),
+ meta_collection_name=getattr(cfg, "meta_collection_name", "__openviking_meta"),
+ enable_text_index=bool(getattr(cfg, "enable_text_index", True)),
+ )
+
+ @property
+ def physical_collection_name(self) -> str:
+ return f"{self._project_name}__{self._collection_name}"
+
+ def _new_qdrant_collection(self) -> QdrantCollection:
+ return QdrantCollection(
+ url=self._url,
+ api_key=self._api_key,
+ timeout_seconds=self._timeout_seconds,
+ project_name=self._project_name,
+ logical_collection_name=self._collection_name,
+ physical_collection_name=self.physical_collection_name,
+ dense_vector_name=self._dense_vector_name,
+ sparse_vector_name=self._sparse_vector_name,
+ meta_collection_name=self._meta_collection_name,
+ distance_metric=self._distance_metric,
+ enable_text_index=self._enable_text_index,
+ )
+
+ def _load_existing_collection_if_needed(self) -> None:
+ if self._collection is not None:
+ return
+ candidate = self._new_qdrant_collection()
+ try:
+ if not candidate.collection_exists():
+ return
+ if not candidate.has_openviking_metadata():
+ raise RuntimeError(
+ "Qdrant collection exists but OpenViking metadata is missing: "
+ f"{self.physical_collection_name}. "
+ "Use a different project/name, restore metadata, or drop the stale Qdrant collection."
+ )
+ self._collection = Collection(candidate)
+ candidate = None
+ finally:
+ if candidate is not None:
+ candidate.close()
+
+ def _create_backend_collection(self, meta: Dict[str, Any]) -> Collection:
+ raw_collection = self._new_qdrant_collection()
+ raw_collection.create_remote_collection(meta)
+ return Collection(raw_collection)
+
+ def _sanitize_scalar_index_fields(
+ self,
+ scalar_index_fields: list[str],
+ fields_meta: list[dict[str, Any]],
+ ) -> list[str]:
+ text_fields = self.DEFAULT_TEXT_INDEX_FIELDS if self._enable_text_index else []
+ merged = list(dict.fromkeys(list(scalar_index_fields) + self.INTERNAL_PATH_FIELDS + text_fields))
+ return merged
+
+ def _build_default_index_meta(
+ self,
+ *,
+ index_name: str,
+ distance: str,
+ use_sparse: bool,
+ sparse_weight: float,
+ scalar_index_fields: list[str],
+ ) -> Dict[str, Any]:
+ index_type = "hnsw_hybrid" if use_sparse else "hnsw"
+ index_meta: Dict[str, Any] = {
+ "IndexName": index_name,
+ "VectorIndex": {
+ "IndexType": index_type,
+ "Distance": distance,
+ "Quant": "int8",
+ },
+ "ScalarIndex": scalar_index_fields,
+ }
+ if use_sparse:
+ index_meta["VectorIndex"]["EnableSparse"] = True
+ index_meta["VectorIndex"]["SearchWithSparseLogitAlpha"] = sparse_weight
+ return index_meta
+
+ @staticmethod
+ def _normalize_path(path: str) -> str:
+ stripped = (path or "").strip()
+ if not stripped:
+ return "/"
+ if not stripped.startswith("/"):
+ stripped = f"/{stripped}"
+ if len(stripped) > 1:
+ stripped = stripped.rstrip("/")
+ return stripped or "/"
+
+ @classmethod
+ def _compute_parent_uri(cls, uri: str) -> str:
+ normalized = cls._normalize_path(uri)
+ if normalized == "/":
+ return "/"
+ parts = normalized.strip("/").split("/")
+ if len(parts) <= 1:
+ return "/"
+ return "/" + "/".join(parts[:-1])
+
+ @classmethod
+ def _compute_scope_roots(cls, uri: str) -> List[str]:
+ normalized = cls._normalize_path(uri)
+ if normalized == "/":
+ return ["/"]
+ parts = normalized.strip("/").split("/")
+ roots = ["/"]
+ current_parts: List[str] = []
+ for part in parts[:-1]:
+ current_parts.append(part)
+ roots.append("/" + "/".join(current_parts))
+ return roots
+
+ def _normalize_record_for_write(self, record: Dict[str, Any]) -> Dict[str, Any]:
+ normalized = dict(super()._normalize_record_for_write(record))
+ raw_uri = normalized.get("uri")
+ if isinstance(raw_uri, str):
+ normalized_uri = self._normalize_path(raw_uri)
+ normalized["uri"] = normalized_uri
+ normalized["parent_uri"] = self._compute_parent_uri(normalized_uri)
+ normalized["scope_roots"] = self._compute_scope_roots(normalized_uri)
+ normalized["uri_depth"] = len([part for part in normalized_uri.strip("/").split("/") if part])
+ return normalized
+
+ def _normalize_record_for_read(self, record: Dict[str, Any]) -> Dict[str, Any]:
+ normalized = super()._normalize_record_for_read(record)
+ for field_name in self.INTERNAL_PATH_FIELDS:
+ normalized.pop(field_name, None)
+ return normalized
+
+ def _coerce_datetime_value(self, value: Any) -> Any:
+ if isinstance(value, datetime):
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.isoformat()
+ return value
+
+ def _must_clause(self, *conds: Dict[str, Any]) -> Dict[str, Any]:
+ items = [cond for cond in conds if cond]
+ if not items:
+ return {}
+ if len(items) == 1 and set(items[0].keys()) in ({"must"}, {"should"}, {"must_not"}):
+ return items[0]
+ flattened: List[Dict[str, Any]] = []
+ for item in items:
+ if set(item.keys()) == {"must"}:
+ flattened.extend(item.get("must", []))
+ else:
+ flattened.append(item)
+ return {"must": flattened}
+
+ def _should_clause(self, *conds: Dict[str, Any]) -> Dict[str, Any]:
+ items = [cond for cond in conds if cond]
+ if not items:
+ return {}
+ flattened: List[Dict[str, Any]] = []
+ for item in items:
+ if set(item.keys()) == {"should"}:
+ flattened.extend(item.get("should", []))
+ else:
+ flattened.append(item)
+ return {"should": flattened}
+
+ @staticmethod
+ def _match_condition(field: str, value: Any) -> Dict[str, Any]:
+ return {"key": field, "match": {"value": value}}
+
+ @staticmethod
+ def _match_any_condition(field: str, values: List[Any]) -> Dict[str, Any]:
+ return {"key": field, "match": {"any": values}}
+
+ @staticmethod
+ def _range_condition(field: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+ return {"key": field, "range": payload}
+
+ @staticmethod
+ def _text_condition(field: str, text: str) -> Dict[str, Any]:
+ return {"key": field, "match": {"text": text}}
+
+ def _compile_legacy_dict_filter(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+ op = str(payload.get("op") or "").lower()
+ if not op:
+ return self._normalize_filter_payload_for_write(payload)
+
+ if op == "and":
+ return self._must_clause(
+ *(self._compile_legacy_dict_filter(cond) for cond in payload.get("conds", []) if cond)
+ )
+ if op == "or":
+ return self._should_clause(
+ *(self._compile_legacy_dict_filter(cond) for cond in payload.get("conds", []) if cond)
+ )
+ if op == "must":
+ field = payload.get("field")
+ values = payload.get("conds", []) or []
+ if field in self._URI_FIELD_NAMES:
+ values = [self._normalize_path(self._encode_uri_field_value(value)) for value in values]
+ if len(values) <= 1:
+ value = values[0] if values else None
+ return {"must": [self._match_condition(field, value)]} if value is not None else {}
+ return {"must": [self._match_any_condition(field, list(values))]}
+ if op == "must_not":
+ field = payload.get("field")
+ values = payload.get("conds", []) or []
+ if field in self._URI_FIELD_NAMES:
+ values = [self._normalize_path(self._encode_uri_field_value(value)) for value in values]
+ condition = (
+ self._match_any_condition(field, list(values))
+ if len(values) > 1
+ else self._match_condition(field, values[0] if values else None)
+ )
+ return {"must_not": [condition]} if condition else {}
+ if op in {"range", "time_range"}:
+ range_payload: Dict[str, Any] = {}
+ for key in ("gte", "gt", "lte", "lt"):
+ if payload.get(key) is not None:
+ range_payload[key] = self._coerce_datetime_value(payload[key])
+ return {"must": [self._range_condition(payload.get("field"), range_payload)]}
+ if op == "range_out":
+ field = payload.get("field")
+ branches: List[Dict[str, Any]] = []
+ if payload.get("gte") is not None:
+ branches.append({"must": [self._range_condition(field, {"lt": payload["gte"]})]})
+ if payload.get("lte") is not None:
+ branches.append({"must": [self._range_condition(field, {"gt": payload["lte"]})]})
+ return self._should_clause(*branches)
+ if op == "contains":
+ return {"must": [self._text_condition(payload.get("field"), payload.get("substring", ""))]}
+ if op == "prefix":
+ field = payload.get("field")
+ prefix = payload.get("prefix", "")
+ if field in self._URI_FIELD_NAMES:
+ return self._compile_filter(PathScope(field, prefix, depth=-1))
+ return {"must": [self._text_condition(field, prefix)]}
+ return self._normalize_filter_payload_for_write(payload)
+
+ def _compile_filter(self, expr: FilterExpr | Dict[str, Any] | None) -> Dict[str, Any]:
+ if expr is None:
+ return {}
+ if isinstance(expr, dict):
+ if "op" in expr:
+ return self._compile_legacy_dict_filter(expr)
+ return self._normalize_filter_payload_for_write(expr)
+ if isinstance(expr, RawDSL):
+ payload = expr.payload
+ if isinstance(payload, dict) and "op" in payload:
+ return self._compile_legacy_dict_filter(payload)
+ return self._normalize_filter_payload_for_write(payload)
+ if isinstance(expr, And):
+ return self._must_clause(*(self._compile_filter(cond) for cond in expr.conds if cond))
+ if isinstance(expr, Or):
+ return self._should_clause(*(self._compile_filter(cond) for cond in expr.conds if cond))
+ if isinstance(expr, Eq):
+ value = expr.value
+ if expr.field in self._URI_FIELD_NAMES:
+ value = self._normalize_path(self._encode_uri_field_value(value))
+ return {"must": [self._match_condition(expr.field, value)]}
+ if isinstance(expr, In):
+ values = list(expr.values)
+ if expr.field in self._URI_FIELD_NAMES:
+ values = [self._normalize_path(self._encode_uri_field_value(value)) for value in values]
+ if len(values) == 1:
+ return {"must": [self._match_condition(expr.field, values[0])]}
+ return {"must": [self._match_any_condition(expr.field, values)]}
+ if isinstance(expr, Range):
+ numeric_range_payload: Dict[str, Any] = {}
+ for key in ("gte", "gt", "lte", "lt"):
+ value = getattr(expr, key)
+ if value is not None:
+ numeric_range_payload[key] = value
+ return {"must": [self._range_condition(expr.field, numeric_range_payload)]}
+ if isinstance(expr, TimeRange):
+ time_range_payload: Dict[str, Any] = {}
+ if expr.start is not None:
+ time_range_payload["gte"] = self._coerce_datetime_value(expr.start)
+ if expr.end is not None:
+ time_range_payload["lt"] = self._coerce_datetime_value(expr.end)
+ return {"must": [self._range_condition(expr.field, time_range_payload)]}
+ if isinstance(expr, Contains):
+ return {"must": [self._text_condition(expr.field, expr.substring)]}
+ if isinstance(expr, PathScope):
+ encoded_path = (
+ self._normalize_path(self._encode_uri_field_value(expr.path))
+ if expr.field in self._URI_FIELD_NAMES
+ else expr.path
+ )
+ if expr.depth == 0:
+ return {"must": [self._match_condition(expr.field, encoded_path)]}
+ if expr.depth == 1:
+ return {"must": [self._match_condition("parent_uri", encoded_path)]}
+ if expr.depth == -1:
+ return {"must": [self._match_condition("scope_roots", encoded_path)]}
+ raise ValueError(f"Qdrant adapter only supports PathScope depth 0/1/-1, got {expr.depth}")
+ raise TypeError(f"Unsupported filter expr type: {type(expr)!r}")
diff --git a/openviking_cli/utils/config/vectordb_config.py b/openviking_cli/utils/config/vectordb_config.py
index 0683ab09f..b38cd4ba5 100644
--- a/openviking_cli/utils/config/vectordb_config.py
+++ b/openviking_cli/utils/config/vectordb_config.py
@@ -50,6 +50,32 @@ class VikingDBConfig(BaseModel):
model_config = {"extra": "forbid"}
+class QdrantConfig(BaseModel):
+ """Configuration for Qdrant backend."""
+
+ url: Optional[str] = Field(default=None, description="Qdrant service URL")
+ api_key: Optional[str] = Field(default=None, description="Optional Qdrant API key")
+ timeout_seconds: int = Field(default=10, description="HTTP timeout for Qdrant requests")
+ dense_vector_name: str = Field(
+ default="vector",
+ description="Named dense vector field in Qdrant collection.",
+ )
+ sparse_vector_name: str = Field(
+ default="sparse_vector",
+ description="Named sparse vector field in Qdrant collection.",
+ )
+ meta_collection_name: str = Field(
+ default="__openviking_meta",
+ description="Sidecar collection name for OpenViking metadata in Qdrant.",
+ )
+ enable_text_index: bool = Field(
+ default=True,
+ description="Whether to create text payload indexes for supported text fields.",
+ )
+
+ model_config = {"extra": "forbid"}
+
+
class VectorDBBackendConfig(BaseModel):
"""
Configuration for VectorDB backend.
@@ -63,7 +89,7 @@ class VectorDBBackendConfig(BaseModel):
description=(
"VectorDB backend type: 'local', 'http', "
"'volcengine' (AK/SK signed or API key data-plane only), "
- "or 'vikingdb' (private deployment)"
+ "'vikingdb' (private deployment), or 'qdrant'"
),
)
@@ -117,6 +143,11 @@ class VectorDBBackendConfig(BaseModel):
description="VikingDB private deployment configuration for 'vikingdb' type",
)
+ qdrant: Optional[QdrantConfig] = Field(
+ default_factory=QdrantConfig,
+ description="Qdrant configuration for 'qdrant' type",
+ )
+
custom_params: Dict[str, Any] = Field(
default_factory=dict,
description="Custom parameters for custom backend adapters",
@@ -127,7 +158,7 @@ class VectorDBBackendConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
"""Validate configuration completeness and consistency"""
- standard_backends = ["local", "http", "volcengine", "vikingdb"]
+ standard_backends = ["local", "http", "volcengine", "vikingdb", "qdrant"]
# Allow custom backend classes (containing dot) without standard validation
if "." in self.backend:
@@ -176,4 +207,18 @@ class VectorDBBackendConfig(BaseModel):
if not self.vikingdb or not self.vikingdb.host:
raise ValueError("VectorDB vikingdb backend requires 'host' to be set")
+ elif self.backend == "qdrant":
+ qdrant_url = (
+ (self.qdrant.url if self.qdrant else None)
+ or self.url
+ or self.custom_params.get("url")
+ )
+ if not qdrant_url:
+ raise ValueError("VectorDB qdrant backend requires 'qdrant.url' or 'url' to be set")
+ if self.qdrant is None:
+ self.qdrant = QdrantConfig()
+ self.qdrant.url = str(qdrant_url).strip().rstrip("/")
+ if self.url:
+ self.url = self.url.strip().rstrip("/")
+
return self
diff --git a/tests/integration/conftest.py b/tests/integration/conftest.py
index 87572a28d..654dfc02f 100644
--- a/tests/integration/conftest.py
+++ b/tests/integration/conftest.py
@@ -14,6 +14,7 @@ import shutil
import socket
import threading
import time
+from functools import lru_cache
from pathlib import Path
import httpx
@@ -50,6 +51,39 @@ requires_volcengine_kms = pytest.mark.skipif(
reason="VOLCENGINE_ACCESS_KEY, VOLCENGINE_SECRET_KEY, or VOLCENGINE_KMS_KEY_ID not set",
)
+# ── Qdrant integration test helpers ─────────────────────────────────────────
+QDRANT_URL = os.environ.get("QDRANT_URL", "http://127.0.0.1:6333").rstrip("/")
+QDRANT_API_KEY = os.environ.get("QDRANT_API_KEY", "")
+
+
+@lru_cache(maxsize=1)
+def _qdrant_available() -> bool:
+ try:
+ headers = {"api-key": QDRANT_API_KEY} if QDRANT_API_KEY else None
+ response = httpx.get(
+ f"{QDRANT_URL}/collections",
+ headers=headers,
+ timeout=2.0,
+ )
+ return response.status_code == 200
+ except Exception:
+ return False
+
+
+requires_qdrant = pytest.mark.qdrant
+
+
+def pytest_configure(config):
+ config.addinivalue_line("markers", "qdrant: requires a reachable Qdrant instance")
+
+
[email protected](autouse=True)
+def _skip_when_qdrant_unavailable(request):
+ if request.node.get_closest_marker("qdrant") is None:
+ return
+ if not _qdrant_available():
+ pytest.skip(f"Qdrant not available at {QDRANT_URL}")
+
# (model_name, default_dimension, token_limit)
GEMINI_MODELS = [
("gemini-embedding-2-preview", 3072, 8192),
diff --git a/tests/integration/test_qdrant_integration.py b/tests/integration/test_qdrant_integration.py
new file mode 100644
index 000000000..8a23836f3
--- /dev/null
+++ b/tests/integration/test_qdrant_integration.py
@@ -0,0 +1,342 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Integration tests for the Qdrant vectordb adapter.
+
+Usage:
+
+ QDRANT_URL=http://127.0.0.1:6333 pytest tests/integration/test_qdrant_integration.py -v -s
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+
+from openviking.storage.expr import Contains, Eq, PathScope
+from openviking.storage.vectordb_adapters.factory import create_collection_adapter
+from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
+from tests.integration.conftest import QDRANT_API_KEY, QDRANT_URL, requires_qdrant
+
+pytestmark = [pytest.mark.integration, requires_qdrant]
+
+
+def _build_qdrant_config(collection_name: str) -> VectorDBBackendConfig:
+ return VectorDBBackendConfig.model_validate(
+ {
+ "backend": "qdrant",
+ "project": "it",
+ "name": collection_name,
+ "index_name": "default",
+ "distance_metric": "cosine",
+ "qdrant": {
+ "url": QDRANT_URL,
+ "api_key": QDRANT_API_KEY or None,
+ "timeout_seconds": 10,
+ "dense_vector_name": "vector",
+ "sparse_vector_name": "sparse_vector",
+ "meta_collection_name": "__openviking_meta",
+ "enable_text_index": True,
+ },
+ }
+ )
+
+
+def _build_schema(collection_name: str) -> dict:
+ return {
+ "CollectionName": collection_name,
+ "Description": "Qdrant integration test collection",
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string", "IsPrimaryKey": True},
+ {"FieldName": "uri", "FieldType": "path"},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 4},
+ {"FieldName": "sparse_vector", "FieldType": "sparse_vector"},
+ {"FieldName": "created_at", "FieldType": "date_time"},
+ {"FieldName": "updated_at", "FieldType": "date_time"},
+ {"FieldName": "active_count", "FieldType": "int64"},
+ {"FieldName": "level", "FieldType": "int64"},
+ {"FieldName": "abstract", "FieldType": "string"},
+ {"FieldName": "account_id", "FieldType": "string"},
+ ],
+ "ScalarIndex": [
+ "uri",
+ "updated_at",
+ "active_count",
+ "level",
+ "account_id",
+ "abstract",
+ ],
+ }
+
+
+def qdrant_adapter():
+ collection_name = f"qdrant_it_{uuid.uuid4().hex[:8]}"
+ adapter = create_collection_adapter(_build_qdrant_config(collection_name))
+ try:
+ yield adapter, collection_name
+ finally:
+ try:
+ if adapter.collection_exists():
+ adapter.drop_collection()
+ finally:
+ adapter.close()
+
+
+def test_qdrant_adapter_end_to_end(qdrant_adapter):
+ adapter, collection_name = qdrant_adapter
+ schema = _build_schema(collection_name)
+
+ created = adapter.create_collection(
+ collection_name,
+ schema,
+ distance="cosine",
+ sparse_weight=0.0,
+ index_name="default",
+ )
+ assert created is True
+ assert adapter.physical_collection_name == f"it__{collection_name}"
+ assert adapter.get_collection().list_indexes() == ["default"]
+
+ records = [
+ {
+ "id": "doc_1",
+ "uri": "viking://resources/acme/docs/a.md",
+ "vector": [1.0, 0.0, 0.0, 0.0],
+ "created_at": "2026-05-29T12:00:00Z",
+ "updated_at": "2026-05-29T12:00:00Z",
+ "active_count": 5,
+ "level": 2,
+ "abstract": "alpha quarterly report",
+ "account_id": "acme",
+ },
+ {
+ "id": "doc_2",
+ "uri": "viking://resources/acme/docs/b.md",
+ "vector": [0.9, 0.1, 0.0, 0.0],
+ "created_at": "2026-05-29T12:01:00Z",
+ "updated_at": "2026-05-29T12:01:00Z",
+ "active_count": 3,
+ "level": 2,
+ "abstract": "beta design note",
+ "account_id": "acme",
+ },
+ {
+ "id": "doc_3",
+ "uri": "viking://resources/beta/notes/c.md",
+ "vector": [0.0, 1.0, 0.0, 0.0],
+ "created_at": "2026-05-29T12:02:00Z",
+ "updated_at": "2026-05-29T12:02:00Z",
+ "active_count": 1,
+ "level": 2,
+ "abstract": "gamma meeting note",
+ "account_id": "beta",
+ },
+ ]
+
+ ids = adapter.upsert(records)
+ assert len(ids) == 3
+
+ fetched = adapter.get(ids[:2])
+ assert len(fetched) == 2
+ assert fetched[0]["uri"].startswith("viking://resources/")
+ assert "parent_uri" not in fetched[0]
+ assert "scope_roots" not in fetched[0]
+
+ assert adapter.count() == 3
+ assert adapter.count(Eq("account_id", "acme")) == 2
+ assert adapter.count({"op": "must", "field": "account_id", "conds": ["beta"]}) == 1
+
+ vector_hits = adapter.query(
+ query_vector=[1.0, 0.0, 0.0, 0.0],
+ filter=Eq("account_id", "acme"),
+ limit=2,
+ output_fields=["uri", "account_id", "active_count"],
+ )
+ assert len(vector_hits) >= 1
+ assert all(item["account_id"] == "acme" for item in vector_hits)
+ assert vector_hits[0]["uri"] == "viking://resources/acme/docs/a.md"
+
+ id_hits = adapter.get_collection().search_by_id(
+ index_name="default",
+ id="doc_1",
+ limit=2,
+ output_fields=["uri", "account_id"],
+ )
+ assert id_hits.data[0].id == "doc_2"
+ assert id_hits.data[0].fields["uri"] == "viking://resources/acme/docs/b.md"
+
+ path_hits = adapter.query(
+ filter=PathScope("uri", "viking://resources/acme/docs", depth=-1),
+ limit=10,
+ output_fields=["uri", "account_id"],
+ )
+ assert len(path_hits) == 2
+ assert {item["uri"] for item in path_hits} == {
+ "viking://resources/acme/docs/a.md",
+ "viking://resources/acme/docs/b.md",
+ }
+
+ parent_hits = adapter.query(
+ filter=PathScope("uri", "viking://resources/acme/docs", depth=1),
+ limit=10,
+ output_fields=["uri"],
+ )
+ assert len(parent_hits) == 2
+
+ ordered = adapter.query(
+ filter=Eq("account_id", "acme"),
+ limit=10,
+ order_by="active_count",
+ order_desc=True,
+ output_fields=["uri", "active_count"],
+ )
+ assert [item["active_count"] for item in ordered][:2] == [5, 3]
+
+ meta = adapter.get_collection_info()
+ assert meta["CollectionName"] == collection_name
+ assert meta["Description"] == "Qdrant integration test collection"
+ assert len(meta["Fields"]) == 10
+
+ deleted = adapter.delete(filter=Eq("account_id", "beta"))
+ assert deleted == 1
+ assert adapter.count() == 2
+
+
+def test_qdrant_hybrid_dense_sparse_query(qdrant_adapter):
+ adapter, collection_name = qdrant_adapter
+ schema = _build_schema(collection_name)
+
+ created = adapter.create_collection(
+ collection_name,
+ schema,
+ distance="cosine",
+ sparse_weight=0.5,
+ index_name="default",
+ )
+ assert created is True
+
+ records = [
+ {
+ "id": str(uuid.uuid4()),
+ "uri": "viking://resources/acme/hybrid/doc1.md",
+ "vector": [1.0, 0.0, 0.0, 0.0],
+ "sparse_vector": {"alpha": 1.0, "beta": 0.5},
+ "created_at": "2026-05-29T12:10:00Z",
+ "updated_at": "2026-05-29T12:10:00Z",
+ "active_count": 10,
+ "level": 2,
+ "abstract": "alpha beta anchor",
+ "account_id": "acme",
+ },
+ {
+ "id": str(uuid.uuid4()),
+ "uri": "viking://resources/acme/hybrid/doc2.md",
+ "vector": [0.98, 0.02, 0.0, 0.0],
+ "sparse_vector": {"gamma": 1.0},
+ "created_at": "2026-05-29T12:11:00Z",
+ "updated_at": "2026-05-29T12:11:00Z",
+ "active_count": 8,
+ "level": 2,
+ "abstract": "dense only neighbor",
+ "account_id": "acme",
+ },
+ {
+ "id": str(uuid.uuid4()),
+ "uri": "viking://resources/acme/hybrid/doc3.md",
+ "vector": [0.0, 1.0, 0.0, 0.0],
+ "sparse_vector": {"alpha": 1.0},
+ "created_at": "2026-05-29T12:12:00Z",
+ "updated_at": "2026-05-29T12:12:00Z",
+ "active_count": 6,
+ "level": 2,
+ "abstract": "sparse only booster",
+ "account_id": "acme",
+ },
+ ]
+ adapter.upsert(records)
+
+ dense_only = adapter.query(
+ query_vector=[1.0, 0.0, 0.0, 0.0],
+ filter=Eq("account_id", "acme"),
+ limit=2,
+ output_fields=["uri"],
+ )
+ dense_uris = [item["uri"] for item in dense_only]
+ assert dense_uris == [
+ "viking://resources/acme/hybrid/doc1.md",
+ "viking://resources/acme/hybrid/doc2.md",
+ ]
+
+ hybrid_hits = adapter.query(
+ query_vector=[1.0, 0.0, 0.0, 0.0],
+ sparse_query_vector={"alpha": 1.0},
+ filter=Eq("account_id", "acme"),
+ limit=2,
+ output_fields=["uri"],
+ )
+ hybrid_uris = [item["uri"] for item in hybrid_hits]
+
+ # doc1 should remain top because it is strong on both dense and sparse.
+ assert hybrid_uris[0] == "viking://resources/acme/hybrid/doc1.md"
+ # doc3 should be pulled up by sparse matching into top2.
+ assert "viking://resources/acme/hybrid/doc3.md" in hybrid_uris
+
+
+def test_qdrant_contains_and_keywords_search(qdrant_adapter):
+ adapter, collection_name = qdrant_adapter
+ schema = _build_schema(collection_name)
+
+ created = adapter.create_collection(
+ collection_name,
+ schema,
+ distance="cosine",
+ sparse_weight=0.0,
+ index_name="default",
+ )
+ assert created is True
+
+ records = [
+ {
+ "id": str(uuid.uuid4()),
+ "uri": "viking://resources/acme/text/report.md",
+ "vector": [1.0, 0.0, 0.0, 0.0],
+ "created_at": "2026-05-29T12:20:00Z",
+ "updated_at": "2026-05-29T12:20:00Z",
+ "active_count": 2,
+ "level": 2,
+ "abstract": "quarterly report for product alpha",
+ "account_id": "acme",
+ },
+ {
+ "id": str(uuid.uuid4()),
+ "uri": "viking://resources/acme/text/design.md",
+ "vector": [0.8, 0.2, 0.0, 0.0],
+ "created_at": "2026-05-29T12:21:00Z",
+ "updated_at": "2026-05-29T12:21:00Z",
+ "active_count": 1,
+ "level": 2,
+ "abstract": "design draft for project beta",
+ "account_id": "acme",
+ },
+ ]
+ ids = adapter.upsert(records)
+ assert len(ids) == 2
+
+ contains_hits = adapter.query(
+ filter=Contains("abstract", "quarterly"),
+ limit=10,
+ output_fields=["uri", "abstract"],
+ )
+ assert len(contains_hits) == 1
+ assert contains_hits[0]["uri"] == "viking://resources/acme/text/report.md"
+
+ collection = adapter.get_collection()
+ keyword_hits = collection.search_by_keywords(
+ index_name="default",
+ keywords=["quarterly"],
+ limit=10,
+ output_fields=["uri", "abstract"],
+ )
+ assert len(keyword_hits.data) >= 1
+ assert keyword_hits.data[0].fields["uri"] == "viking://resources/acme/text/report.md"
diff --git a/tests/storage/test_qdrant_adapter.py b/tests/storage/test_qdrant_adapter.py
new file mode 100644
index 000000000..ea7333e3d
--- /dev/null
+++ b/tests/storage/test_qdrant_adapter.py
@@ -0,0 +1,185 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from datetime import datetime, timezone
+
+import pytest
+
+from openviking.storage.expr import And, Contains, Eq, PathScope, TimeRange
+from openviking.storage.vectordb_adapters.factory import create_collection_adapter
+from openviking.storage.vectordb_adapters.qdrant_adapter import QdrantCollectionAdapter
+from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig
+
+
+def _build_config() -> VectorDBBackendConfig:
+ return VectorDBBackendConfig.model_validate(
+ {
+ "backend": "qdrant",
+ "project": "default",
+ "name": "context",
+ "index_name": "default",
+ "distance_metric": "cosine",
+ "qdrant": {
+ "url": "http://qdrant:6333/",
+ "api_key": "test-key",
+ "timeout_seconds": 7,
+ "dense_vector_name": "vector",
+ "sparse_vector_name": "sparse_vector",
+ "meta_collection_name": "__openviking_meta",
+ "enable_text_index": True,
+ },
+ }
+ )
+
+
+def test_qdrant_backend_config_validation():
+ config = _build_config()
+ assert config.backend == "qdrant"
+ assert config.qdrant is not None
+ assert config.qdrant.url == "http://qdrant:6333"
+
+
+def test_factory_creates_qdrant_adapter():
+ adapter = create_collection_adapter(_build_config())
+ assert isinstance(adapter, QdrantCollectionAdapter)
+ assert adapter.mode == "qdrant"
+ assert adapter.collection_name == "context"
+ assert adapter.index_name == "default"
+ assert adapter.physical_collection_name == "default__context"
+
+
+def test_existing_physical_collection_without_metadata_is_rejected_and_closed(monkeypatch):
+ class FakeQdrantCollection:
+ def __init__(self) -> None:
+ self.closed = False
+
+ def collection_exists(self) -> bool:
+ return True
+
+ def has_openviking_metadata(self) -> bool:
+ return False
+
+ def close(self) -> None:
+ self.closed = True
+
+ candidate = FakeQdrantCollection()
+ adapter = QdrantCollectionAdapter.from_config(_build_config())
+ monkeypatch.setattr(adapter, "_new_qdrant_collection", lambda: candidate)
+
+ with pytest.raises(RuntimeError, match="OpenViking metadata is missing"):
+ adapter.collection_exists()
+
+ assert candidate.closed is True
+
+
+def test_augments_path_fields_on_write_and_hides_them_on_read():
+ adapter = QdrantCollectionAdapter.from_config(_build_config())
+ source_record = {
+ "id": "1",
+ "uri": "viking://resources/acme/docs/a.md",
+ "vector": [0.1, 0.2],
+ }
+
+ normalized = adapter._normalize_record_for_write(source_record)
+
+ assert normalized["uri"] == "/resources/acme/docs/a.md"
+ assert normalized["parent_uri"] == "/resources/acme/docs"
+ assert normalized["scope_roots"] == [
+ "/",
+ "/resources",
+ "/resources/acme",
+ "/resources/acme/docs",
+ ]
+ assert normalized["uri_depth"] == 4
+ assert source_record["uri"] == "viking://resources/acme/docs/a.md"
+
+ public_record = adapter.normalize_record_for_read(normalized)
+ assert public_record["uri"] == "viking://resources/acme/docs/a.md"
+ assert "parent_uri" not in public_record
+ assert "scope_roots" not in public_record
+ assert "uri_depth" not in public_record
+
+
+def test_sanitizes_scalar_index_fields():
+ adapter = QdrantCollectionAdapter.from_config(_build_config())
+ result = adapter.sanitize_scalar_index_fields(
+ scalar_index_fields=["uri", "account_id"],
+ fields_meta=[],
+ )
+ assert result == [
+ "uri",
+ "account_id",
+ "parent_uri",
+ "scope_roots",
+ "uri_depth",
+ "name",
+ "description",
+ "abstract",
+ "tags",
+ ]
+
+
+def test_compiles_filter_exprs():
+ adapter = QdrantCollectionAdapter.from_config(_build_config())
+ compiled = adapter.compile_filter(
+ And(
+ [
+ Eq("account_id", "acme"),
+ PathScope("uri", "viking://resources/acme/docs", depth=-1),
+ TimeRange(
+ "updated_at",
+ start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ end=datetime(2026, 6, 1, tzinfo=timezone.utc),
+ ),
+ Contains("abstract", "quarterly report"),
+ ]
+ )
+ )
+
+ assert compiled == {
+ "must": [
+ {"key": "account_id", "match": {"value": "acme"}},
+ {"key": "scope_roots", "match": {"value": "/resources/acme/docs"}},
+ {
+ "key": "updated_at",
+ "range": {
+ "gte": "2026-05-01T00:00:00+00:00",
+ "lt": "2026-06-01T00:00:00+00:00",
+ },
+ },
+ {"key": "abstract", "match": {"text": "quarterly report"}},
+ ]
+ }
+
+
+def test_compiles_legacy_dict_filters():
+ adapter = QdrantCollectionAdapter.from_config(_build_config())
+ compiled = adapter.compile_filter(
+ {
+ "op": "and",
+ "conds": [
+ {"op": "must", "field": "account_id", "conds": ["acme"]},
+ {
+ "op": "time_range",
+ "field": "updated_at",
+ "gte": "2026-05-01T00:00:00Z",
+ "lt": "2026-06-01T00:00:00Z",
+ },
+ {"op": "prefix", "field": "uri", "prefix": "viking://resources/acme/docs"},
+ ],
+ }
+ )
+
+ assert compiled == {
+ "must": [
+ {"key": "account_id", "match": {"value": "acme"}},
+ {
+ "key": "updated_at",
+ "range": {
+ "gte": "2026-05-01T00:00:00Z",
+ "lt": "2026-06-01T00:00:00Z",
+ },
+ },
+ {"key": "scope_roots", "match": {"value": "/resources/acme/docs"}},
+ ]
+ }
diff --git a/tests/storage/test_qdrant_collection.py b/tests/storage/test_qdrant_collection.py
new file mode 100644
index 000000000..fc18c0123
--- /dev/null
+++ b/tests/storage/test_qdrant_collection.py
@@ -0,0 +1,256 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import pytest
+
+import openviking.storage.vectordb.collection.qdrant_collection as qdrant_collection_module
+from openviking.storage.vectordb.collection.qdrant_collection import (
+ ORIGINAL_ID_FIELD,
+ QdrantCollection,
+ _to_qdrant_point_id,
+ _sparse_to_qdrant,
+)
+from openviking.storage.vectordb.collection.qdrant_rest import QdrantRestError
+
+
+class _StubClient:
+ def __init__(self, responses: List[Any]) -> None:
+ self._responses = list(responses)
+ self.calls: List[Dict[str, Any]] = []
+
+ def request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+ self.calls.append({"method": method, "path": path, **kwargs})
+ if not self._responses:
+ raise AssertionError("No more stubbed Qdrant responses available")
+ response = self._responses.pop(0)
+ if isinstance(response, Exception):
+ raise response
+ return response
+
+
+def _build_collection_stub(client: _StubClient) -> QdrantCollection:
+ collection = object.__new__(QdrantCollection)
+ collection._client = client
+ collection._physical_collection_name = "proj__context"
+ collection._dense_vector_name = "vector"
+ collection._sparse_vector_name = "sparse_vector"
+ collection._vector_dim = 3
+ collection._path_payload_fields = {"parent_uri", "scope_roots"}
+ return collection
+
+
+class _FailingMetaStore:
+ def save_collection_meta(self, **_: Any) -> None:
+ raise RuntimeError("metadata write failed")
+
+
+class _RecordingMetaStore:
+ def __init__(self) -> None:
+ self.deleted_keys: List[str] = []
+
+ def delete_collection_meta(self, *, collection_key: str) -> None:
+ self.deleted_keys.append(collection_key)
+
+
+def test_sparse_to_qdrant_warns_on_hash_collision(monkeypatch, caplog):
+ monkeypatch.setattr(
+ qdrant_collection_module,
+ "_hash_sparse_term",
+ lambda term: 7 if term in {"alpha", "beta"} else 9,
+ )
+
+ payload = _sparse_to_qdrant({"alpha": 1.0, "beta": 2.5, "gamma": 4.0})
+
+ assert payload == {"indices": [7, 9], "values": [3.5, 4.0]}
+ assert "hash collision detected" in caplog.text
+
+
+def test_scroll_points_stops_on_repeated_next_page_offset(caplog):
+ client = _StubClient(
+ [
+ {"result": {"points": [{"id": "p1"}], "next_page_offset": "repeat-me"}},
+ {"result": {"points": [{"id": "p2"}], "next_page_offset": "repeat-me"}},
+ ]
+ )
+ collection = _build_collection_stub(client)
+
+ points = collection._scroll_points(limit=None)
+
+ assert [point["id"] for point in points] == ["p1", "p2"]
+ assert "next_page_offset repeated" in caplog.text
+
+
+def test_delete_all_data_prefers_filter_delete():
+ client = _StubClient([{"status": "ok", "result": {}}])
+ collection = _build_collection_stub(client)
+ collection._scan_points_with_warning = lambda **_: (_ for _ in ()).throw(
+ AssertionError("fallback scan should not be used")
+ )
+ collection._delete_points = lambda _: (_ for _ in ()).throw(
+ AssertionError("batched delete should not be used")
+ )
+
+ collection.delete_all_data()
+
+ assert len(client.calls) == 1
+ call = client.calls[0]
+ assert call["method"] == "POST"
+ assert call["path"] == "/collections/proj__context/points/delete"
+ assert call["json_body"] == {"filter": {}}
+ assert call["params"] == {"wait": "true"}
+
+
+def test_delete_all_data_falls_back_to_batched_delete(caplog):
+ client = _StubClient([QdrantRestError("delete failed")])
+ collection = _build_collection_stub(client)
+ collection._scan_points_with_warning = lambda **_: [
+ {"id": str(i)} for i in range(QdrantCollection.DEFAULT_DELETE_BATCH_SIZE * 2 + 5)
+ ]
+
+ deleted_batches: List[List[str]] = []
+ collection._delete_points = lambda ids: deleted_batches.append(list(ids))
+
+ collection.delete_all_data()
+
+ assert [len(batch) for batch in deleted_batches] == [
+ QdrantCollection.DEFAULT_DELETE_BATCH_SIZE,
+ QdrantCollection.DEFAULT_DELETE_BATCH_SIZE,
+ 5,
+ ]
+ assert "Falling back to batched delete_all_data" in caplog.text
+
+
+def test_make_point_accepts_zero_id():
+ collection = _build_collection_stub(_StubClient([]))
+
+ point = collection._make_point({"id": 0, "vector": [0.1, 0.2, 0.3], "name": "zero"})
+
+ assert point["id"] == 0
+ assert point["vector"]["vector"] == [0.1, 0.2, 0.3]
+ assert point["payload"]["name"] == "zero"
+ assert point["payload"][ORIGINAL_ID_FIELD] == 0
+
+
+def test_make_point_maps_arbitrary_string_id_and_preserves_original_id():
+ collection = _build_collection_stub(_StubClient([]))
+
+ point = collection._make_point({"id": "doc_1", "vector": [0.1, 0.2, 0.3]})
+
+ assert point["id"] == _to_qdrant_point_id("doc_1")
+ assert point["id"] != "doc_1"
+ assert point["payload"][ORIGINAL_ID_FIELD] == "doc_1"
+
+
+def test_make_point_rejects_missing_vector():
+ collection = _build_collection_stub(_StubClient([]))
+
+ with pytest.raises(ValueError, match="requires at least one dense or sparse vector"):
+ collection._make_point({"id": "doc_1", "name": "missing vector"})
+
+
+def test_create_remote_collection_rolls_back_when_metadata_write_fails():
+ client = _StubClient([{"status": "ok"}, {"status": "ok"}])
+ collection = _build_collection_stub(client)
+ collection._logical_collection_name = "context"
+ collection._project_name = "proj"
+ collection._distance_metric = "cosine"
+ collection._meta_store = _FailingMetaStore()
+
+ with pytest.raises(RuntimeError, match="metadata write failed"):
+ collection.create_remote_collection(
+ {
+ "Fields": [
+ {"FieldName": "id", "FieldType": "string"},
+ {"FieldName": "vector", "FieldType": "vector", "Dim": 3},
+ ]
+ }
+ )
+
+ assert client.calls[0]["method"] == "PUT"
+ assert client.calls[0]["path"] == "/collections/proj__context"
+ assert client.calls[1]["method"] == "DELETE"
+ assert client.calls[1]["path"] == "/collections/proj__context"
+ assert client.calls[1]["expected_statuses"] == (200, 202, 404)
+
+
+def test_drop_tolerates_missing_physical_collection_and_deletes_metadata():
+ client = _StubClient([{"status": "ok"}])
+ collection = _build_collection_stub(client)
+ meta_store = _RecordingMetaStore()
+ collection._meta_store = meta_store
+
+ collection.drop()
+
+ assert client.calls[0]["method"] == "DELETE"
+ assert client.calls[0]["expected_statuses"] == (200, 202, 404)
+ assert meta_store.deleted_keys == ["proj__context"]
+
+
+def test_fetch_data_maps_ids_and_returns_original_ids():
+ point_id = _to_qdrant_point_id("doc_1")
+ client = _StubClient(
+ [
+ {
+ "result": [
+ {
+ "id": point_id,
+ "payload": {ORIGINAL_ID_FIELD: "doc_1", "name": "Document"},
+ }
+ ]
+ }
+ ]
+ )
+ collection = _build_collection_stub(client)
+
+ result = collection.fetch_data(["doc_1", "doc_2"])
+
+ assert client.calls[0]["json_body"]["ids"] == [point_id, _to_qdrant_point_id("doc_2")]
+ assert result.items[0].id == "doc_1"
+ assert result.items[0].fields == {"name": "Document"}
+ assert result.ids_not_exist == ["doc_2"]
+
+
+def test_search_by_id_uses_stored_vector_for_similarity_query():
+ point_id = _to_qdrant_point_id("doc_1")
+ client = _StubClient(
+ [
+ {
+ "result": [
+ {
+ "id": point_id,
+ "payload": {ORIGINAL_ID_FIELD: "doc_1"},
+ "vector": {"vector": [0.1, 0.2, 0.3]},
+ }
+ ]
+ },
+ {
+ "result": {
+ "points": [
+ {
+ "id": point_id,
+ "payload": {ORIGINAL_ID_FIELD: "doc_1"},
+ "score": 1.0,
+ },
+ {
+ "id": _to_qdrant_point_id("doc_2"),
+ "payload": {ORIGINAL_ID_FIELD: "doc_2", "name": "Document 2"},
+ "score": 0.9,
+ },
+ ]
+ }
+ },
+ ]
+ )
+ collection = _build_collection_stub(client)
+
+ result = collection.search_by_id("default", "doc_1", limit=10)
+
+ assert client.calls[0]["json_body"]["with_vector"] is True
+ assert client.calls[1]["path"] == "/collections/proj__context/points/query"
+ assert client.calls[1]["json_body"]["query"] == [0.1, 0.2, 0.3]
+ assert result.data[0].id == "doc_2"
+ assert result.data[0].fields == {"name": "Document 2"}
diff --git a/tests/storage/test_qdrant_meta_store.py b/tests/storage/test_qdrant_meta_store.py
new file mode 100644
index 000000000..4b00bbf6e
--- /dev/null
+++ b/tests/storage/test_qdrant_meta_store.py
@@ -0,0 +1,62 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from openviking.storage.vectordb.collection.qdrant_meta_store import QdrantMetaStore
+from openviking.storage.vectordb.collection.qdrant_rest import QdrantRestError
+
+
+class _StubClient:
+ def __init__(self, responses: List[Any]) -> None:
+ self._responses = list(responses)
+ self.calls: List[Dict[str, Any]] = []
+
+ def collection_exists(self, name: str) -> bool:
+ self.calls.append({"method": "COLLECTION_EXISTS", "name": name})
+ return True
+
+ def request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+ self.calls.append({"method": method, "path": path, **kwargs})
+ if not self._responses:
+ raise AssertionError("No more stubbed Qdrant responses available")
+ response = self._responses.pop(0)
+ if isinstance(response, Exception):
+ raise response
+ return response
+
+
+def test_scroll_index_docs_paginates_until_exhausted():
+ client = _StubClient(
+ [
+ {"result": {"points": [{"id": "idx-1"}], "next_page_offset": "page-2"}},
+ {"result": {"points": [{"id": "idx-2"}], "next_page_offset": None}},
+ ]
+ )
+ store = QdrantMetaStore(client=client, meta_collection_name="__meta")
+
+ docs = store._scroll_index_docs("proj__context")
+
+ assert [doc["id"] for doc in docs] == ["idx-1", "idx-2"]
+ assert client.calls[2]["json_body"]["offset"] == "page-2"
+
+
+def test_get_point_returns_none_for_missing_meta_collection():
+ client = _StubClient([QdrantRestError("missing", status_code=404)])
+ store = QdrantMetaStore(client=client, meta_collection_name="__meta")
+
+ assert store._get_point("missing") is None
+
+
+def test_get_point_reraises_non_missing_qdrant_errors():
+ client = _StubClient([QdrantRestError("auth failed", status_code=401)])
+ store = QdrantMetaStore(client=client, meta_collection_name="__meta")
+
+ try:
+ store._get_point("meta-id")
+ except QdrantRestError as exc:
+ assert exc.status_code == 401
+ else:
+ raise AssertionError("Expected QdrantRestError to be reraised")