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
feat(search): allow find without a query when a filter is given (#4694)
yangxinxin-792ccb0f57a37
diff --git a/openviking/service/search_service.py b/openviking/service/search_service.pyindex 9a3992284..944899bef 100644--- a/openviking/service/search_service.py+++ b/openviking/service/search_service.py@@ -25,9 +25,23 @@ if TYPE_CHECKING:logger = get_logger(__name__)-def _ensure_non_empty_query(query: str, image_url: Optional[str] = None) -> None:- if not query.strip() and not image_url:- raise InvalidArgumentError("Search query or image_url must not be empty.")+def _ensure_non_empty_query(+ query: str,+ image_url: Optional[str] = None,+ filter: Optional[Dict] = None,+) -> None:+ """Reject a request that gives the search nothing to work with.++ A filter is an acceptable substitute for a query: the result set is then+ fully determined by the filter, which is exactly what an exact-match lookup+ (e.g. by a tag carrying an external id) needs. Without either one the call+ would return an arbitrary slice of the whole store.+ """+ if query.strip() or image_url or filter:+ return+ raise InvalidArgumentError(+ "Search query or image_url must not be empty unless a filter is provided."+ )class SearchService:@@ -147,7 +161,7 @@ class SearchService:FindResult"""resolved_image_url = await self._resolve_image_url(image_url, ctx)- _ensure_non_empty_query(query, resolved_image_url)+ _ensure_non_empty_query(query, resolved_image_url, filter)viking_fs = self._ensure_initialized()result = await viking_fs.find(query=query,diff --git a/openviking/storage/viking_fs/_base.py b/openviking/storage/viking_fs/_base.pyindex 47b2f1071..fd987a135 100644--- a/openviking/storage/viking_fs/_base.py+++ b/openviking/storage/viking_fs/_base.py@@ -3,7 +3,7 @@"""Shared constants, helpers, and singleton management for VikingFS."""import os-from typing import TYPE_CHECKING, Any, Optional, TypeVar+from typing import TYPE_CHECKING, Any, Dict, Optional, TypeVarfrom openviking_cli.exceptions import (InvalidArgumentError,@@ -91,6 +91,56 @@ def _ensure_non_empty_search_query(query: str, image_url: Optional[str] = None)raise InvalidArgumentError("Search query or image_url must not be empty.")+def is_filter_only_query(query: str, image_url: Optional[str] = None) -> bool:+ """Return True when the caller supplied no query and no image."""+ return not query.strip() and not image_url+++def _ensure_filter_present(filter: Optional[Dict[str, Any]]) -> None:+ """Reject a query-less request that also carries no filter.++ Without either one there is nothing to narrow the search by, and returning+ an arbitrary slice of the whole store would be worse than an error.+ """+ if not filter:+ raise InvalidArgumentError(+ "Search query or image_url must not be empty unless a filter is provided."+ )+++def build_matched_context_from_record(record: Dict[str, Any]) -> Any:+ """Turn a raw vector-store record into a MatchedContext.++ ``score`` is left at 0: a filter-only lookup has no similarity ranking, and+ fabricating a score would let callers sort on a meaningless number.+ """+ from openviking.utils.tags import normalize_search_tags+ from openviking_cli.retrieve import ContextType, MatchedContext++ uri = record.get("uri")+ if not uri or not isinstance(uri, str):+ return None+ raw_type = record.get("context_type")+ try:+ context_type = ContextType(raw_type) if raw_type else ContextType.RESOURCE+ except ValueError:+ context_type = ContextType.RESOURCE+ raw_level = record.get("level")+ # Not `or 2`: level 0 is a valid value (a directory abstract record) and+ # would otherwise be silently reported as 2.+ level = int(raw_level) if raw_level is not None else 2+ return MatchedContext(+ uri=uri,+ context_type=context_type,+ level=level,+ abstract=record.get("abstract", "") or "",+ category=record.get("category", "") or "",+ score=0.0,+ match_reason="filter",+ search_tags=normalize_search_tags(record.get("search_tags"), discard_invalid=True),+ )++def _is_directory_not_empty_error(message: str) -> bool:"""Check if an error message indicates a directory not empty error.diff --git a/openviking/storage/viking_fs/_semantic.py b/openviking/storage/viking_fs/_semantic.pyindex f361f6c3e..ee4aab40c 100644--- a/openviking/storage/viking_fs/_semantic.py+++ b/openviking/storage/viking_fs/_semantic.py@@ -3,7 +3,7 @@"""Semantic retrieval mixin for VikingFS."""import asyncio-from typing import Dict, List, Optional, Union+from typing import Any, Dict, List, Optional, Unionfrom openviking.core.context import ContextLevelfrom openviking.core.retrieval_targets import resolve_retrieval_targets@@ -12,7 +12,10 @@ from openviking.server.identity import RequestContextfrom openviking.storage.abstract_overview import body_for_preview, render_abstract_overviewfrom openviking.storage.acl import AclActionfrom openviking.storage.viking_fs._base import (+ _ensure_filter_present,_ensure_non_empty_search_query,+ build_matched_context_from_record,+ is_filter_only_query,logger,)from openviking.telemetry import get_current_telemetry@@ -204,7 +207,20 @@ class _SemanticMixin:Returns:FindResult"""- _ensure_non_empty_search_query(query, image_url)+ # Validate before touching any state: callers rely on a bad request+ # being rejected even when the instance has not been initialized yet.+ #+ # An empty query is allowed only when a metadata filter narrows the+ # search: the result is then fully determined by that filter, so there+ # is nothing to embed or rank. Callers that look records up by an exact+ # tag (e.g. a legacy id carried on the record) would otherwise be forced+ # to invent a meaningless query string whose similarity score is noise.+ filter_only = is_filter_only_query(query, image_url)+ if filter_only:+ _ensure_filter_present(filter)+ else:+ _ensure_non_empty_search_query(query, image_url)+telemetry = get_current_telemetry()from openviking.retrieve.hierarchical_retriever import (HierarchicalRetriever,@@ -219,6 +235,15 @@ class _SemanticMixin:real_ctx = self._ctx_or_default(ctx)retrieval_targets = resolve_retrieval_targets(target_uri, real_ctx)+ if filter_only:+ return await self._find_by_filter(+ filter=filter,+ ctx=real_ctx,+ target_directories=retrieval_targets.target_directories,+ limit=limit,+ level=level,+ )+for target_dir in retrieval_targets.target_directories:await self._ensure_retrieval_scope(target_dir, ctx)@@ -281,6 +306,66 @@ class _SemanticMixin:telemetry.set("vector.returned", find_result.total)return find_result+ async def _find_by_filter(+ self,+ filter: Optional[Dict],+ ctx: Any,+ target_directories: Any,+ limit: int,+ level: Optional[List[int]] = None,+ ) -> Any:+ """Resolve a query-less find purely from the metadata filter.++ Scoping is delegated to filter_in_tenant, which builds the same scope+ filter the vector path uses — tenant isolation and target-directory+ limits therefore stay identical between the two. Hand-building the+ filter here would be one refactor away from silently losing them.++ Records come back in whatever order the store yields; there is no+ similarity ranking, so ``score`` stays 0 rather than a fabricated value+ callers might try to sort on.+ """+ from openviking.storage.vikingdb_manager import VikingDBManagerProxy+ from openviking_cli.retrieve import ContextType, FindResult++ telemetry = get_current_telemetry()+ store = self._get_vector_store()+ if not store:+ raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")++ for target_dir in target_directories:+ await self._ensure_retrieval_scope(target_dir, ctx)++ proxy = VikingDBManagerProxy(store, ctx)+ records = await proxy.filter_in_tenant(+ target_directories=list(target_directories or []),+ extra_filter=filter,+ level=level,+ limit=limit,+ )++ memories, resources, skills = [], [], []+ # Deduplicate by URI, mirroring what the vector path does: tags live on+ # per-level records, so a directory carrying one matches on both its L0+ # and L1 record and would otherwise be returned twice — inflating the+ # total and eating two of the caller's limit slots for one result.+ seen_uris: set = set()+ for record in records:+ matched = build_matched_context_from_record(record)+ if matched is None or matched.uri in seen_uris:+ continue+ seen_uris.add(matched.uri)+ if matched.context_type == ContextType.MEMORY:+ memories.append(matched)+ elif matched.context_type == ContextType.RESOURCE:+ resources.append(matched)+ elif matched.context_type == ContextType.SKILL:+ skills.append(matched)++ find_result = FindResult(memories=memories, resources=resources, skills=skills)+ telemetry.set("vector.returned", find_result.total)+ return find_result+async def search(self,query: str,diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.pyindex 6956d449c..2769b25be 100644--- a/openviking/storage/viking_vector_index_backend.py+++ b/openviking/storage/viking_vector_index_backend.py@@ -30,7 +30,7 @@ from openviking.storage.vectordb.utils.logging_init import init_cpp_loggingfrom openviking.storage.vectordb_adapters import create_collection_adapterfrom openviking.utils.tags import merge_search_tagsfrom openviking.utils.time_utils import get_current_timestamp-from openviking_cli.exceptions import ConflictError+from openviking_cli.exceptions import ConflictError, InvalidArgumentErrorfrom openviking_cli.utils import get_loggerfrom openviking_cli.utils.config.vectordb_config import DEFAULT_INDEX_NAME, VectorDBBackendConfigfrom openviking_cli.utils.uri import VikingURI@@ -1476,6 +1476,43 @@ class VikingVectorIndexBackend:ctx=ctx,)+ async def filter_in_tenant(+ self,+ ctx: RequestContext,+ context_type: Optional[str] = None,+ target_directories: Optional[List[str]] = None,+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,+ level: Optional[List[int]] = None,+ limit: int = 10,+ offset: int = 0,+ ) -> List[Dict[str, Any]]:+ """Metadata-only lookup scoped exactly like search_in_tenant.++ Used when a caller supplies a filter but no query, so there is no vector+ to search by. Scoping goes through the same _build_scope_filter as the+ vector path, which keeps tenant isolation and target-directory limits+ identical between the two — a separately hand-built filter would be one+ refactor away from silently losing them.+ """+ scope_filter = self._build_scope_filter(+ ctx=ctx,+ context_type=context_type,+ target_directories=target_directories,+ extra_filter=extra_filter,+ level=level,+ )+ if scope_filter is None:+ raise InvalidArgumentError(+ "A query-less lookup needs a filter or a target directory to scope by."+ )+ return await self.filter(+ filter=scope_filter,+ limit=limit,+ offset=offset,+ output_fields=RETRIEVAL_OUTPUT_FIELDS,+ ctx=ctx,+ )+async def search_children_in_tenant(self,ctx: RequestContext,diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.pyindex 4e099034d..cb9c1145c 100644--- a/openviking/storage/vikingdb_manager.py+++ b/openviking/storage/vikingdb_manager.py@@ -458,6 +458,25 @@ class VikingDBManagerProxy:offset=offset,)+ async def filter_in_tenant(+ self,+ context_type: Optional[str] = None,+ target_directories: Optional[List[str]] = None,+ extra_filter: Optional[FilterExpr | Dict[str, Any]] = None,+ level: Optional[List[int]] = None,+ limit: int = 10,+ offset: int = 0,+ ) -> List[Dict[str, Any]]:+ return await self._manager.filter_in_tenant(+ self._ctx,+ context_type=context_type,+ target_directories=target_directories,+ extra_filter=extra_filter,+ level=level,+ limit=limit,+ offset=offset,+ )+async def search_children_in_tenant(self,parent_uri: str,diff --git a/tests/unit/test_search_filter_only_query.py b/tests/unit/test_search_filter_only_query.pynew file mode 100644index 000000000..01dccb011--- /dev/null+++ b/tests/unit/test_search_filter_only_query.py@@ -0,0 +1,112 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""A find() carrying a filter but no query resolves from the filter alone.++Looking a record up by an exact tag (an external id carried on the record, say)+has no meaningful query text. Forcing callers to invent one makes the similarity+score noise, and leaves them at the mercy of whatever recall the made-up query+happens to produce.+"""++import pytest++from openviking.service.search_service import _ensure_non_empty_query+from openviking.storage.viking_fs._base import (+ _ensure_filter_present,+ build_matched_context_from_record,+ is_filter_only_query,+)+from openviking_cli.exceptions import InvalidArgumentError+from openviking_cli.retrieve import ContextType++TAG_FILTER = {"op": "must", "field": "search_tags", "conds": ["legacy_memory_id=mem-1"]}+++def test_empty_query_with_filter_is_accepted():+ _ensure_non_empty_query("", None, TAG_FILTER)+ _ensure_non_empty_query(" ", None, TAG_FILTER)+++def test_empty_query_without_filter_is_still_rejected():+ with pytest.raises(InvalidArgumentError):+ _ensure_non_empty_query("", None, None)+ with pytest.raises(InvalidArgumentError):+ _ensure_non_empty_query(" ", None, {})+++def test_non_empty_query_is_always_accepted():+ _ensure_non_empty_query("hello", None, None)+++def test_image_only_query_is_still_accepted():+ _ensure_non_empty_query("", "https://example.com/a.png", None)+++ ("query", "image_url", "expected"),+ [+ ("", None, True),+ (" ", None, True),+ ("\n\t", None, True),+ ("hello", None, False),+ ("", "https://example.com/a.png", False),+ ],+)+def test_is_filter_only_query(query, image_url, expected):+ assert is_filter_only_query(query, image_url) is expected+++def test_ensure_filter_present_rejects_missing_filter():+ with pytest.raises(InvalidArgumentError):+ _ensure_filter_present(None)+ with pytest.raises(InvalidArgumentError):+ _ensure_filter_present({})+++def test_ensure_filter_present_accepts_filter():+ _ensure_filter_present(TAG_FILTER)+++def test_matched_context_from_record_keeps_tags_and_zero_score():+ matched = build_matched_context_from_record(+ {+ "uri": "viking://user/default/memories/s/a.md",+ "context_type": "memory",+ "level": 2,+ "abstract": "an abstract",+ "category": "note",+ "search_tags": ["legacy_memory_id=mem-1"],+ }+ )+ assert matched.uri == "viking://user/default/memories/s/a.md"+ assert matched.context_type == ContextType.MEMORY+ assert matched.search_tags == ["legacy_memory_id=mem-1"]+ # No similarity ranking took place, so the score must not be fabricated.+ assert matched.score == 0.0+ assert matched.match_reason == "filter"+++def test_matched_context_from_record_without_uri_is_dropped():+ assert build_matched_context_from_record({"context_type": "memory"}) is None+++def test_matched_context_from_record_falls_back_on_unknown_type():+ matched = build_matched_context_from_record(+ {"uri": "viking://user/default/resources/a.md", "context_type": "not-a-type"}+ )+ assert matched.context_type == ContextType.RESOURCE+++def test_matched_context_keeps_level_zero():+ """Level 0 (a directory abstract) must survive, not collapse to the default."""+ matched = build_matched_context_from_record(+ {"uri": "viking://user/default/memories/s", "context_type": "memory", "level": 0}+ )+ assert matched.level == 0+++def test_matched_context_defaults_level_when_absent():+ matched = build_matched_context_from_record(+ {"uri": "viking://user/default/memories/s/a.md", "context_type": "memory"}+ )+ assert matched.level == 2