Skip to content

Build and run agents you can see, understand and trust.

fix(rag): enforce knowledge base scope during document deletion (#3222)

dafyy321-pixelb2a084799bf8
diff --git a/src/agentscope/rag/_knowledge.py b/src/agentscope/rag/_knowledge.py
index 8534fadb7..b83338777 100644
--- a/src/agentscope/rag/_knowledge.py
+++ b/src/agentscope/rag/_knowledge.py
@@ -26,7 +26,7 @@ deployment.
co-locating multiple logical knowledge bases inside the same physical
collection — typically multi-tenant deployments where every record
carries a ``{"tenant_id": "..."}`` payload. It is set once at
-construction time and **always** applied: search/list never escape
+construction time and **always** applied: search/list/delete never escape
it, and insert forces it onto every chunk's metadata so a malicious or
buggy parser cannot rebind a record into another scope.
"""
@@ -113,6 +113,8 @@ class KnowledgeBase:
- :meth:`insert_document` forces these keys onto every
inserted chunk's metadata, overriding caller-supplied
values, so records cannot leak into another scope.
+ - :meth:`delete_document` removes only records matching
+ both the document id and every filter pair.
``None`` disables filtering — the default for
deployments where every knowledge base owns its
@@ -361,17 +363,30 @@ class KnowledgeBase:
return document_id
async def delete_document(self, document_id: str) -> None:
- """Remove every record for one source document.
+ """Remove every record for one source document within this scope.
+
+ Records must also match :attr:`metadata_filter` when set.
+ Custom vector stores must support scoped deletion; an unsupported
+ filter raises an error instead of falling back to unscoped deletion.
Args:
document_id (`str`):
The source document id whose records should be removed.
"""
await self.ensure_collection()
- await self._vector_store.delete(
- self._collection,
- document_id,
- )
+ if self._metadata_filter:
+ await self._vector_store.delete(
+ self._collection,
+ document_id,
+ metadata_filter=self._metadata_filter,
+ )
+ else:
+ # Preserve compatibility with custom stores using the original
+ # delete signature when no scoping is required.
+ await self._vector_store.delete(
+ self._collection,
+ document_id,
+ )
async def list_documents(self) -> list["DocumentSummary"]:
"""List all distinct source documents in this knowledge base.
diff --git a/src/agentscope/rag/_vdb/_elasticsearch.py b/src/agentscope/rag/_vdb/_elasticsearch.py
index d9fc9b6ee..ab1225c6d 100644
--- a/src/agentscope/rag/_vdb/_elasticsearch.py
+++ b/src/agentscope/rag/_vdb/_elasticsearch.py
@@ -159,11 +159,30 @@ class ElasticsearchStore(VectorStoreBase):
"record(s)",
)
- async def delete(self, collection: str, document_id: str) -> None:
- """Delete every chunk belonging to one source document."""
+ async def delete(
+ self,
+ collection: str,
+ document_id: str,
+ metadata_filter: dict[str, Any] | None = None,
+ ) -> None:
+ """Delete every chunk belonging to one source document.
+
+ Args:
+ collection (`str`):
+ The target collection name.
+ document_id (`str`):
+ The source document ID whose records should be removed.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ Restrict deletion to records matching every metadata pair
+ in addition to the document ID. ``None`` disables filtering.
+ """
+ query: dict[str, Any] = {"term": {"document_id": document_id}}
+ if metadata_filter:
+ filters = [query, *self._metadata_filters(metadata_filter)]
+ query = {"bool": {"filter": filters}}
await self.get_client().delete_by_query(
index=collection,
- query={"term": {"document_id": document_id}},
+ query=query,
conflicts="proceed",
refresh=self._refresh is not False,
)
diff --git a/src/agentscope/rag/_vdb/_milvus_lite.py b/src/agentscope/rag/_vdb/_milvus_lite.py
index fa4170e2c..ea8bacb12 100644
--- a/src/agentscope/rag/_vdb/_milvus_lite.py
+++ b/src/agentscope/rag/_vdb/_milvus_lite.py
@@ -260,12 +260,27 @@ class MilvusLiteStore(VectorStoreBase):
self,
collection: str,
document_id: str,
+ metadata_filter: dict[str, Any] | None = None,
) -> None:
- """Delete all records belonging to one source document."""
+ """Delete all records belonging to one source document.
+
+ Args:
+ collection (`str`):
+ The target collection name.
+ document_id (`str`):
+ The source document ID whose records should be removed.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ Restrict deletion to records matching every metadata pair
+ in addition to the document ID. ``None`` disables filtering.
+ """
+ clauses = [self._build_document_filter(document_id)]
+ meta_expr = self._build_metadata_filter(metadata_filter)
+ if meta_expr:
+ clauses.append(meta_expr)
await asyncio.to_thread(
self.get_client().delete,
collection_name=collection,
- filter=self._build_document_filter(document_id),
+ filter=" and ".join(clauses),
)
# ------------------------------------------------------------------
diff --git a/src/agentscope/rag/_vdb/_mongodb.py b/src/agentscope/rag/_vdb/_mongodb.py
index f6029b8d6..450b9bc8e 100644
--- a/src/agentscope/rag/_vdb/_mongodb.py
+++ b/src/agentscope/rag/_vdb/_mongodb.py
@@ -293,6 +293,7 @@ class MongoDBStore(VectorStoreBase):
self,
collection: str,
document_id: str,
+ metadata_filter: dict[str, Any] | None = None,
) -> None:
"""Delete all records belonging to one source document.
@@ -305,8 +306,13 @@ class MongoDBStore(VectorStoreBase):
document_id (`str`):
The source document ID whose records should be
removed.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ Restrict deletion to records matching every metadata pair
+ in addition to the document ID. ``None`` disables filtering.
"""
- await self._col(collection).delete_many({"document_id": document_id})
+ query = {"document_id": document_id}
+ query.update(self._build_metadata_filter(metadata_filter) or {})
+ await self._col(collection).delete_many(query)
# ------------------------------------------------------------------
# Search
diff --git a/src/agentscope/rag/_vdb/_qdrant.py b/src/agentscope/rag/_vdb/_qdrant.py
index 09af9a69c..a4a85bcc1 100644
--- a/src/agentscope/rag/_vdb/_qdrant.py
+++ b/src/agentscope/rag/_vdb/_qdrant.py
@@ -248,6 +248,7 @@ class QdrantStore(VectorStoreBase):
self,
collection: str,
document_id: str,
+ metadata_filter: dict[str, Any] | None = None,
) -> None:
"""Delete all records belonging to one source document.
@@ -260,20 +261,25 @@ class QdrantStore(VectorStoreBase):
document_id (`str`):
The source document ID whose records should be
removed.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ Restrict deletion to records matching every metadata pair
+ in addition to the document ID. ``None`` disables filtering.
"""
from qdrant_client import models
+ conditions = [
+ models.FieldCondition(
+ key="document_id",
+ match=models.MatchValue(value=document_id),
+ ),
+ ]
+ base_filter = self._build_metadata_filter(metadata_filter)
+ if base_filter is not None:
+ conditions.extend(base_filter.must)
await self.get_client().delete(
collection_name=collection,
points_selector=models.FilterSelector(
- filter=models.Filter(
- must=[
- models.FieldCondition(
- key="document_id",
- match=models.MatchValue(value=document_id),
- ),
- ],
- ),
+ filter=models.Filter(must=conditions),
),
)
diff --git a/src/agentscope/rag/_vdb/_vector_store.py b/src/agentscope/rag/_vdb/_vector_store.py
index 060f9507b..ec621a2c3 100644
--- a/src/agentscope/rag/_vdb/_vector_store.py
+++ b/src/agentscope/rag/_vdb/_vector_store.py
@@ -207,6 +207,7 @@ class VectorStoreBase(ABC):
self,
collection: str,
document_id: str,
+ metadata_filter: dict[str, Any] | None = None,
) -> None:
"""Delete all records belonging to one source document.
@@ -221,6 +222,11 @@ class VectorStoreBase(ABC):
document_id (`str`):
The source document ID whose records should be
removed.
+ metadata_filter (`dict[str, Any] | None`, optional):
+ Restrict deletion to records whose chunk metadata matches
+ every ``key == value`` pair in addition to the document ID.
+ ``None`` or an empty dict deletes all records of the
+ document. Backends must not ignore a non-empty filter.
"""
# ------------------------------------------------------------------
diff --git a/tests/rag_vdb_elasticsearch_test.py b/tests/rag_vdb_elasticsearch_test.py
index 883c4b693..2ffa4c275 100644
--- a/tests/rag_vdb_elasticsearch_test.py
+++ b/tests/rag_vdb_elasticsearch_test.py
@@ -145,6 +145,42 @@ class ElasticsearchStoreTest(IsolatedAsyncioTestCase):
with self.assertRaisesRegex(RuntimeError, "1 record"):
await self.store.insert("kb-1", [_record("doc-1", 0)])
+ async def test_elasticsearch_delete_filter(self) -> None:
+ """Elasticsearch uses a conjunction of exact-match filters."""
+ await self.store.delete(
+ "shared",
+ "doc",
+ metadata_filter={"tenant": "alpha", "project": 2},
+ )
+ self.client.delete_by_query.assert_awaited_once_with(
+ index="shared",
+ query={
+ "bool": {
+ "filter": [
+ {"term": {"document_id": "doc"}},
+ {"term": {"metadata.tenant": "alpha"}},
+ {"term": {"metadata.project": 2}},
+ ],
+ },
+ },
+ conflicts="proceed",
+ refresh=True,
+ )
+ for scope in (None, {}):
+ with self.subTest(scope=scope):
+ self.client.delete_by_query.reset_mock()
+ await self.store.delete(
+ "shared",
+ "doc",
+ metadata_filter=scope,
+ )
+ self.client.delete_by_query.assert_awaited_once_with(
+ index="shared",
+ query={"term": {"document_id": "doc"}},
+ conflicts="proceed",
+ refresh=True,
+ )
+
async def test_delete_by_document_id(self) -> None:
await self.store.delete("kb-1", "doc-1")
diff --git a/tests/rag_vdb_milvus_lite_test.py b/tests/rag_vdb_milvus_lite_test.py
index 31d01278d..2f15405f5 100644
--- a/tests/rag_vdb_milvus_lite_test.py
+++ b/tests/rag_vdb_milvus_lite_test.py
@@ -5,7 +5,9 @@ import unittest
from contextlib import AsyncExitStack
from importlib.util import find_spec
from pathlib import Path
+from types import SimpleNamespace
from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import Mock, patch
from utils import AnyString
@@ -582,3 +584,34 @@ class MilvusLiteStoreTest(IsolatedAsyncioTestCase):
[c.content.text for c in chunks],
["v2-chunk0", "v2-chunk1"],
)
+
+
+class MilvusDeleteFilterTest(IsolatedAsyncioTestCase):
+ """Check delete predicates without starting a Milvus service."""
+
+ async def test_milvus_delete_filter(self) -> None:
+ """Milvus keeps document escaping and ANDs both metadata fields."""
+ store = MilvusLiteStore()
+ client = SimpleNamespace(delete=Mock())
+ with patch.object(store, "get_client", return_value=client):
+ await store.delete(
+ "shared",
+ 'doc"id',
+ metadata_filter={"tenant": "alpha", "project": 2},
+ )
+ client.delete.assert_called_once_with(
+ collection_name="shared",
+ filter=(
+ 'document_id == "doc\\"id" and '
+ 'metadata["tenant"] == "alpha" and metadata["project"] == 2'
+ ),
+ )
+ for scope in (None, {}):
+ with self.subTest(scope=scope):
+ client.delete.reset_mock()
+ with patch.object(store, "get_client", return_value=client):
+ await store.delete("shared", "doc", metadata_filter=scope)
+ client.delete.assert_called_once_with(
+ collection_name="shared",
+ filter='document_id == "doc"',
+ )
diff --git a/tests/rag_vdb_mongodb_test.py b/tests/rag_vdb_mongodb_test.py
index f8b2d7a8d..904726135 100644
--- a/tests/rag_vdb_mongodb_test.py
+++ b/tests/rag_vdb_mongodb_test.py
@@ -5,9 +5,10 @@ from __future__ import annotations
import math
from contextlib import AsyncExitStack
+from types import SimpleNamespace
from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
from utils import AnyString
@@ -478,6 +479,34 @@ class MongoDBStoreTest(IsolatedAsyncioTestCase):
],
)
+ async def test_mongodb_delete_filter(self) -> None:
+ """MongoDB combines the source document with metadata equality."""
+ store = self.store
+ collection = SimpleNamespace(delete_many=AsyncMock())
+ with patch.object(store, "_col", return_value=collection):
+ await store.delete(
+ "shared",
+ "doc",
+ metadata_filter={"tenant": "alpha", "project": 2},
+ )
+ collection.delete_many.assert_awaited_once_with(
+ {
+ "document_id": "doc",
+ "$and": [
+ {"chunk.metadata.tenant": {"$eq": "alpha"}},
+ {"chunk.metadata.project": {"$eq": 2}},
+ ],
+ },
+ )
+ for scope in (None, {}):
+ with self.subTest(scope=scope):
+ collection.delete_many.reset_mock()
+ with patch.object(store, "_col", return_value=collection):
+ await store.delete("shared", "doc", metadata_filter=scope)
+ collection.delete_many.assert_awaited_once_with(
+ {"document_id": "doc"},
+ )
+
async def test_search_candidate_limits(self) -> None:
"""Search caps candidates while preserving the requested limit."""
await self.store.create_collection("kb-1", dimensions=3)
diff --git a/tests/rag_vdb_qdrant_test.py b/tests/rag_vdb_qdrant_test.py
index cc3973071..42730049f 100644
--- a/tests/rag_vdb_qdrant_test.py
+++ b/tests/rag_vdb_qdrant_test.py
@@ -1,19 +1,47 @@
# -*- coding: utf-8 -*-
"""Unit tests for the QdrantStore class."""
from contextlib import AsyncExitStack
+from importlib.util import find_spec
+from types import SimpleNamespace
+from unittest import skipUnless
from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import AsyncMock, patch
from utils import AnyString
from agentscope.message import TextBlock
from agentscope.rag import (
Chunk,
+ KnowledgeBase,
QdrantStore,
VectorRecord,
VectorSearchResult,
)
+def _knowledge_base(
+ store: QdrantStore,
+ metadata_filter: dict | None,
+) -> KnowledgeBase:
+ """Bind a handle without needing an embedding request for deletion."""
+ return KnowledgeBase(
+ name="test",
+ description="Test knowledge base",
+ embedding_model=SimpleNamespace(dimensions=3),
+ vector_store=store,
+ collection="shared",
+ metadata_filter=metadata_filter,
+ )
+
+
+class _LegacyStore(QdrantStore):
+ """Custom backend using the original, unscoped delete signature."""
+
+ async def delete(self, collection: str, document_id: str) -> None:
+ """Record deletions so a rejected scoped call cannot mutate data."""
+ await self.get_client().delete(collection, document_id)
+
+
def _dump_results(results: list[VectorSearchResult]) -> list[dict]:
"""Convert search results into plain dicts for whole-structure
comparison.
@@ -698,3 +726,115 @@ class QdrantStoreTest(IsolatedAsyncioTestCase):
[c.content.text for c in chunks],
["v2-chunk0", "v2-chunk1"],
)
+
+
+class LegacyDeleteTest(IsolatedAsyncioTestCase):
+ """Old custom backends still work without a scope and fail closed."""
+
+ async def test_legacy_backend_without_scope(self) -> None:
+ """No metadata keyword is sent when the handle has no scope."""
+ for scope in (None, {}):
+ with self.subTest(scope=scope):
+ store = _LegacyStore()
+ client = SimpleNamespace(delete=AsyncMock())
+ with (
+ patch.object(store, "has_collection", return_value=True),
+ patch.object(store, "get_client", return_value=client),
+ ):
+ await _knowledge_base(store, scope).delete_document("doc")
+ client.delete.assert_awaited_once_with("shared", "doc")
+
+ async def test_legacy_backend_with_scope(self) -> None:
+ """An unsupported scope is rejected before deleting anything."""
+ store = _LegacyStore()
+ client = SimpleNamespace(delete=AsyncMock())
+ with (
+ patch.object(store, "has_collection", return_value=True),
+ patch.object(store, "get_client", return_value=client),
+ ):
+ with self.assertRaises(TypeError):
+ await _knowledge_base(
+ store,
+ {"tenant": "alpha"},
+ ).delete_document("doc")
+ client.delete.assert_not_awaited()
+
+
+@skipUnless(find_spec("qdrant_client"), "qdrant-client is required")
+class QdrantScopedDeleteTest(IsolatedAsyncioTestCase):
+ """Verify isolation against the real, in-memory Qdrant backend."""
+
+ async def asyncSetUp(self) -> None:
+ """Insert chunks spanning documents and two independent scope keys."""
+ self._exit_stack = AsyncExitStack()
+ self.store = await self._exit_stack.enter_async_context(
+ QdrantStore(location=":memory:"),
+ )
+ await self.store.create_collection("shared", dimensions=3)
+ self.scope = {"tenant": "alpha", "project": 2}
+ records = []
+ for document_id, index, metadata in (
+ ("shared-doc", 0, self.scope),
+ ("shared-doc", 1, {"tenant": "beta", "project": 2}),
+ ("shared-doc", 2, {"tenant": "alpha", "project": 3}),
+ ("alpha-doc", 0, self.scope),
+ ("beta-doc", 0, {"tenant": "beta", "project": 2}),
+ ):
+ records.append(
+ VectorRecord(
+ vector=[1.0, 0.0, 0.0],
+ document_id=document_id,
+ chunk=Chunk(
+ content=TextBlock(text=f"{document_id}-{index}"),
+ source=f"{document_id}.txt",
+ chunk_index=index,
+ total_chunks=3,
+ metadata=metadata,
+ ),
+ ),
+ )
+ await self.store.insert("shared", records)
+
+ async def asyncTearDown(self) -> None:
+ """Release the ephemeral client."""
+ await self._exit_stack.aclose()
+
+ async def test_foreign_document_is_unchanged(self) -> None:
+ """A scoped handle cannot remove an invisible foreign document."""
+ before = await self.store.list_chunks("shared", "beta-doc")
+ await _knowledge_base(self.store, self.scope).delete_document(
+ "beta-doc",
+ )
+ after = await self.store.list_chunks("shared", "beta-doc")
+ self.assertEqual(before, after)
+ self.assertEqual(len(after), 1)
+
+ async def test_delete_requires_document_and_every_scope_field(
+ self,
+ ) -> None:
+ """Delete only chunks matching both the document and all scope keys."""
+ await _knowledge_base(self.store, self.scope).delete_document(
+ "shared-doc",
+ )
+ chunks = await self.store.list_chunks("shared", "shared-doc")
+ self.assertEqual([chunk.chunk_index for chunk in chunks], [1, 2])
+ self.assertEqual(
+ len(await self.store.list_chunks("shared", "alpha-doc")),
+ 1,
+ )
+ await _knowledge_base(self.store, self.scope).delete_document(
+ "alpha-doc",
+ )
+ self.assertEqual(
+ await self.store.list_chunks("shared", "alpha-doc"),
+ [],
+ )
+
+ async def test_unscoped_handle_deletes_all_document_chunks(self) -> None:
+ """The default handle deletes documents across the whole collection."""
+ await _knowledge_base(self.store, None).delete_document("shared-doc")
+ self.assertEqual(
+ await self.store.list_chunks("shared", "shared-doc"),
+ [],
+ )
+ self.assertEqual(len(await self.store.list_documents("shared")), 2)