Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
add Qdrant vectordb support (#2350)
Dechao Sunc1cf1c3d06fe
diff --git a/openviking/storage/vectordb/collection/qdrant_collection.py b/openviking/storage/vectordb/collection/qdrant_collection.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 Truediff --git a/openviking/storage/vectordb_adapters/factory.py b/openviking/storage/vectordb_adapters/factory.pyindex 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 CollectionAdapterfrom .http_adapter import HttpCollectionAdapterfrom .local_adapter import LocalCollectionAdapter+from .qdrant_adapter import QdrantCollectionAdapterfrom .vikingdb_private_adapter import VikingDBPrivateCollectionAdapterfrom .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 pathif 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.pynew file mode 100644index 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.pyindex 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 validationif "." 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 selfdiff --git a/tests/integration/conftest.py b/tests/integration/conftest.pyindex 87572a28d..654dfc02f 100644--- a/tests/integration/conftest.py+++ b/tests/integration/conftest.py@@ -14,6 +14,7 @@ import shutilimport socketimport threadingimport time+from functools import lru_cachefrom pathlib import Pathimport 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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")