Skip to content

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

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.py
index 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.py
index 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, TypeVar
from 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.py
index 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, Union
from openviking.core.context import ContextLevel
from openviking.core.retrieval_targets import resolve_retrieval_targets
@@ -12,7 +12,10 @@ from openviking.server.identity import RequestContext
from openviking.storage.abstract_overview import body_for_preview, render_abstract_overview
from openviking.storage.acl import AclAction
from 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.py
index 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_logging
from openviking.storage.vectordb_adapters import create_collection_adapter
from openviking.utils.tags import merge_search_tags
from openviking.utils.time_utils import get_current_timestamp
-from openviking_cli.exceptions import ConflictError
+from openviking_cli.exceptions import ConflictError, InvalidArgumentError
from openviking_cli.utils import get_logger
from openviking_cli.utils.config.vectordb_config import DEFAULT_INDEX_NAME, VectorDBBackendConfig
from 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.py
index 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.py
new file mode 100644
index 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