Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

docs(vector_store): note the milvus schema assumption

Zohaib Hassnain930e7f9b71cf
diff --git a/semantica/vector_store/milvus_store.py b/semantica/vector_store/milvus_store.py
index 018484f0..ab5cf2a5 100644
--- a/semantica/vector_store/milvus_store.py
+++ b/semantica/vector_store/milvus_store.py
@@ -684,12 +684,16 @@ class MilvusStore:
"""
Iterate over every stored entity using Milvus's query iterator.
- Milvus paginates large result sets with a primary-key cursor rather
- than a row offset, so this is exposed instead of
- scan_vectors(offset, limit). Plain query(offset=...) is bounded by the
- 16384 result window, which would silently truncate any collection
- larger than that. VectorStore.iter_vectors() prefers this method when
- it is present.
+ Paginates by primary-key cursor rather than row offset, which is why
+ this exists instead of scan_vectors(offset, limit). query(offset=...)
+ is capped by the 16384 result window and would truncate anything
+ larger.
+
+ Assumes the schema create_collection() builds: a VARCHAR `id` primary
+ key plus vector and metadata fields, as get_vector() and
+ filter_by_metadata() already do. get_collection() does not validate
+ schema, so a collection with an integer key or no metadata field fails
+ here.
Args:
batch_size: Entities to request per iterator batch
@@ -699,11 +703,7 @@ class MilvusStore:
Raises:
ProcessingError: If the collection is not initialized, or the
- installed pymilvus does not expose query_iterator(). Errors are
- raised rather than swallowed because a scan that silently
- yields nothing is indistinguishable from an empty source,
- which would let a caller such as `store migrate` report
- success having copied nothing (issue #1083).
+ installed pymilvus does not expose query_iterator().
"""
if self.collection is None or not MILVUS_AVAILABLE:
raise ProcessingError(
@@ -719,12 +719,12 @@ class MilvusStore:
"silently truncate a larger collection."
)
- # Query operations require the collection to be loaded. load() is
- # idempotent, and this runs once per scan rather than per batch.
+ # Query operations need a loaded collection. Idempotent, and once per
+ # scan rather than per batch.
self.collection.load()
- # Milvus rejects an empty expression, so this is the match-everything
- # form already used by filter_by_metadata().
+ # Milvus rejects an empty expression; this match-all form is what
+ # filter_by_metadata() already uses.
iterator = query_iterator(
batch_size=batch_size,
expr="id != ''",
@@ -744,8 +744,7 @@ class MilvusStore:
"vector": np.array(vec) if vec is not None else None,
}
finally:
- # The iterator holds server-side state; release it even if the
- # consumer abandons iteration part way through.
+ # Release the server-side iterator even if the consumer stops early.
close = getattr(iterator, "close", None)
if callable(close):
close()
diff --git a/tests/vector_store/test_milvus_store.py b/tests/vector_store/test_milvus_store.py
index 780424bc..ed22ee87 100644
--- a/tests/vector_store/test_milvus_store.py
+++ b/tests/vector_store/test_milvus_store.py
@@ -17,8 +17,7 @@ from semantica.vector_store.milvus_store import MilvusStore
def _store_with_batches(*batches):
"""MilvusStore whose query_iterator yields the given batches then stops.
- Mirrors the real attribute path, which is doubled: the store holds a
- MilvusCollection wrapper, and the pymilvus Collection sits at
+ The attribute path is doubled here: the pymilvus Collection sits at
wrapper.collection.
"""
store = MilvusStore()
@@ -34,7 +33,7 @@ def _store_with_batches(*batches):
@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
def test_iter_all_yields_batches_until_exhausted():
- """The iterator signals exhaustion with an empty list, not StopIteration."""
+ """Exhaustion is an empty list, not StopIteration."""
store, _, _, iterator = _store_with_batches(
[{"id": 1, "vector": [0.1], "metadata": {}}],
[{"id": 2, "vector": [0.2], "metadata": {}}],
@@ -81,8 +80,7 @@ def test_iter_all_closes_the_iterator_on_exhaustion():
@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
def test_iter_all_closes_the_iterator_when_consumer_stops_early():
- """The iterator holds server-side state, so abandoning the generator part
- way through must still release it."""
+ """Abandoning the generator early must still release the iterator."""
store, _, _, iterator = _store_with_batches(
[{"id": 1, "vector": [0.1], "metadata": {}}],
[{"id": 2, "vector": [0.2], "metadata": {}}],
@@ -129,9 +127,8 @@ def test_iter_all_empty_collection_yields_nothing():
@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
def test_iter_all_raises_when_query_iterator_is_unavailable():
- """Older pymilvus lacks query_iterator. Falling back to query(offset=...)
- would silently truncate at the 16384 result window, so this fails loudly
- instead."""
+ """Older pymilvus lacks query_iterator; falling back to query(offset=...)
+ would truncate at the 16384 window."""
store = MilvusStore()
wrapper = MagicMock()
wrapper.collection = MagicMock(spec=["query"])
@@ -143,11 +140,7 @@ def test_iter_all_raises_when_query_iterator_is_unavailable():
@patch("semantica.vector_store.milvus_store.MILVUS_AVAILABLE", True)
def test_iter_all_raises_when_collection_not_initialized():
- """Must fail loudly, not yield nothing.
-
- An empty scan is indistinguishable from an empty source, which would let
- `store migrate` report success having copied nothing (issue #1083).
- """
+ """Must fail loudly: an empty scan reads the same as an empty source."""
store = MilvusStore()
with pytest.raises(ProcessingError, match="Collection not initialized"):