Skip to content

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

fix(vikingdb): make legacy collections compatible with grep schema upgrade (#2835)

ByteDanceLiuYang0ee3a7ca8ee7
diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.py
index 57976ea67..bb01b9227 100644
--- a/openviking/storage/collection_schemas.py
+++ b/openviking/storage/collection_schemas.py
@@ -43,28 +43,7 @@ EMBEDDING_META_MARKER = "\n\n[openviking.embedding]\n"
# Minimum OV version that supports content field + FullText config for grep bm25
_FULLTEXT_MIN_VERSION = "0.3.18"
-
-
-def _parse_version(v: str) -> tuple:
- """Parse a semver-like string into a comparable tuple of ints.
-
- Only the first 3 numeric segments are used (e.g. "0.3.18.dev23" → (0, 3, 18)).
- Non-numeric suffixes like ".dev23", ".rc1", "+local" are ignored.
- """
- try:
- parts = v.split(".")
- numeric = []
- for p in parts:
- # Stop at first non-numeric segment (e.g. "dev23", "rc1")
- try:
- numeric.append(int(p))
- except ValueError:
- break
- if len(numeric) == 3:
- break
- return tuple(numeric) if numeric else (0, 0, 0)
- except (ValueError, AttributeError):
- return (0, 0, 0)
+_EMBEDDING_COMPATIBILITY_KEYS = ("provider", "model", "dimension", "model_identity")
@dataclass
@@ -222,6 +201,35 @@ def _build_embedding_metadata(config: "OpenVikingConfig") -> Dict[str, Any]:
}
+def _embedding_metadata_compatible(
+ existing_meta: Optional[Dict[str, Any]],
+ current_meta: Dict[str, Any],
+) -> bool:
+ if existing_meta is None:
+ return False
+ return all(
+ existing_meta.get(key) == current_meta.get(key)
+ for key in _EMBEDDING_COMPATIBILITY_KEYS
+ )
+
+
+def _collection_has_content_fulltext(meta: Dict[str, Any]) -> bool:
+ fields = meta.get("Fields", [])
+ has_content = any(
+ f.get("FieldName") == "content" and f.get("FieldType") == "text" for f in fields
+ )
+ fulltext = meta.get("FullText") or []
+ if isinstance(fulltext, str):
+ try:
+ fulltext = json.loads(fulltext)
+ except json.JSONDecodeError:
+ fulltext = []
+ has_content_fulltext = any(
+ isinstance(ft, dict) and ft.get("Field") == "content" for ft in fulltext
+ )
+ return has_content and has_content_fulltext
+
+
def _encode_collection_description(
base_description: str,
embedding_meta: Dict[str, Any],
@@ -299,27 +307,26 @@ async def init_context_collection(storage) -> bool:
existing_meta.get("Description")
)
- # Schema compatibility check: warn if collection was created by older OV version
- if existing_embedding_meta:
- existing_schema_version = existing_embedding_meta.get("schema_version", "0.0.0")
- if _parse_version(existing_schema_version) < _parse_version(_FULLTEXT_MIN_VERSION):
- fields = existing_meta.get("Fields", [])
- has_content = any(
- f.get("FieldName") == "content" and f.get("FieldType") == "text" for f in fields
- )
- fulltext = existing_meta.get("FullText") or []
- has_content_fulltext = any(ft.get("Field") == "content" for ft in fulltext)
- if not (has_content and has_content_fulltext):
- logger.warning(
- "Collection schema is outdated (created by OV %s, requires >= %s). "
- "Missing 'content' field or FullText config. "
- "grep engine=auto will fall back to fs. "
- "Recreate the collection to enable vikingdb-based grep.",
- existing_schema_version,
- _FULLTEXT_MIN_VERSION,
- )
+ # Schema compatibility check: actual collection schema controls whether
+ # VikingDB full-text grep can be used. Missing content/FullText should only
+ # disable the vikingdb grep path, not block server startup.
+ if (
+ "Fields" in existing_meta or "FullText" in existing_meta
+ ) and not _collection_has_content_fulltext(existing_meta):
+ existing_schema_version = "unknown"
+ if existing_embedding_meta:
+ existing_schema_version = existing_embedding_meta.get("schema_version", "0.0.0")
+ logger.warning(
+ "Collection schema does not support VikingDB full-text grep "
+ "(created by OV %s, feature requires >= %s). "
+ "Missing 'content' field or FullText config. "
+ "grep engine=auto will fall back to fs. "
+ "Recreate the collection to enable vikingdb-based grep.",
+ existing_schema_version,
+ _FULLTEXT_MIN_VERSION,
+ )
- if existing_embedding_meta == embedding_meta:
+ if _embedding_metadata_compatible(existing_embedding_meta, embedding_meta):
return False
existing_count = await storage.count() if hasattr(storage, "count") else 0
diff --git a/tests/storage/test_collection_schemas.py b/tests/storage/test_collection_schemas.py
index 3023231dd..daef696b8 100644
--- a/tests/storage/test_collection_schemas.py
+++ b/tests/storage/test_collection_schemas.py
@@ -18,6 +18,7 @@ from openviking.storage.collection_schemas import (
_build_embedding_metadata,
init_context_collection,
)
+from openviking.storage.errors import EmbeddingRebuildRequiredError
from openviking.storage.expr import Eq
from openviking.storage.queuefs.embedding_msg import EmbeddingMsg
from openviking.storage.vectordb import engine as vectordb_engine
@@ -203,9 +204,10 @@ async def test_init_context_collection_backfills_metadata_for_empty_legacy_colle
@pytest.mark.asyncio
-async def test_init_context_collection_warns_on_mismatched_nonempty_collection(monkeypatch):
- """When embedding metadata mismatches for a non-empty collection, the function
- logs a warning and returns False (does not raise)."""
+async def test_init_context_collection_rejects_mismatched_nonempty_collection(monkeypatch):
+ """When embedding dimension mismatches for a non-empty collection, vectors are
+ incompatible and the function requires a rebuild.
+ """
class _FakeStorage:
async def create_collection(self, name, schema):
@@ -234,8 +236,8 @@ async def test_init_context_collection_warns_on_mismatched_nonempty_collection(m
lambda: config,
)
- result = await init_context_collection(_FakeStorage())
- assert result is False
+ with pytest.raises(EmbeddingRebuildRequiredError, match="embedding dimension"):
+ await init_context_collection(_FakeStorage())
def test_build_embedding_metadata_hashes_resolved_local_model_path(tmp_path):