From 480a4e436ce1cff812d57f776c4dc8ea85d70db6 Mon Sep 17 00:00:00 2001
From: WOLIKIMCHENG <35391914+WOLIKIMCHENG@users.noreply.github.com>
Date: Mon, 31 Aug 2026 17:53:25 +0800
Subject: [PATCH] fix(sdk): reject conflicting dataset ID filters (#19047)

Python SDK list_datasets now rejects both id and ids together (client-side), matching server and list_documents.

Co-authored-by: root <kinsonnee@gmail.com>
---
 sdk/python/ragflow_sdk/ragflow.py             |  3 ++
 .../test_list_datasets.py                     | 49 +++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/sdk/python/ragflow_sdk/ragflow.py b/sdk/python/ragflow_sdk/ragflow.py
index 4932e02d4d..afea036b4b 100644
--- a/sdk/python/ragflow_sdk/ragflow.py
+++ b/sdk/python/ragflow_sdk/ragflow.py
@@ -98,6 +98,9 @@ class RAGFlow:
     def list_datasets(
         self, page: int = 1, page_size: int = 30, orderby: str = "create_time", desc: bool = True, id: str | None = None, ids: list[str] | None = None, name: str | None = None
     ) -> list[DataSet]:
+        if id and ids:
+            raise ValueError("Cannot use both 'id' and 'ids' parameters at the same time.")
+
         res = self.get(
             "/datasets",
             {
diff --git a/test/testcases/test_sdk_api/test_dataset_mangement/test_list_datasets.py b/test/testcases/test_sdk_api/test_dataset_mangement/test_list_datasets.py
index a7cd14c2bd..60e7e405d3 100644
--- a/test/testcases/test_sdk_api/test_dataset_mangement/test_list_datasets.py
+++ b/test/testcases/test_sdk_api/test_dataset_mangement/test_list_datasets.py
@@ -21,6 +21,55 @@ from configs import HOST_ADDRESS, INVALID_API_TOKEN, SDK_UNAUTHORIZED_ERROR_MESS
 from ragflow_sdk import RAGFlow
 
 
+class _ListDatasetsResponse:
+    def json(self):
+        return {"code": 0, "data": []}
+
+
+class TestListDatasetsArgumentValidation:
+    @pytest.fixture(autouse=True)
+    def set_tenant_info(self):
+        return None
+
+    @pytest.mark.p2
+    @pytest.mark.parametrize(
+        "params",
+        [{"id": "dataset-id", "ids": ["dataset-id"]}, {"id": "dataset-id", "ids": [""]}],
+    )
+    def test_rejects_conflicting_id_and_ids_before_get(self, monkeypatch, params):
+        client = RAGFlow("token", HOST_ADDRESS)
+        get_calls = []
+        monkeypatch.setattr(client, "get", lambda *_args, **_kwargs: get_calls.append((_args, _kwargs)))
+
+        with pytest.raises(ValueError, match="^Cannot use both 'id' and 'ids' parameters at the same time\\.$"):
+            client.list_datasets(**params)
+
+        assert get_calls == []
+
+    @pytest.mark.p2
+    @pytest.mark.parametrize(
+        "params",
+        [{"id": "dataset-id"}, {"ids": ["dataset-id"]}, {"id": None, "ids": None}, {"id": "dataset-id", "ids": []}, {"id": "", "ids": ["dataset-id"]}],
+    )
+    def test_preserves_nonconflicting_id_and_ids(self, monkeypatch, params):
+        client = RAGFlow("token", HOST_ADDRESS)
+        get_calls = []
+
+        def _get(path, params=None, json=None):
+            get_calls.append((path, params, json))
+            return _ListDatasetsResponse()
+
+        monkeypatch.setattr(client, "get", _get)
+        assert client.list_datasets(**params) == []
+        assert get_calls == [
+            (
+                "/datasets",
+                {"page": 1, "page_size": 30, "orderby": "create_time", "desc": True, "id": params.get("id"), "ids": params.get("ids"), "name": None},
+                None,
+            )
+        ]
+
+
 class TestAuthorization:
     @pytest.mark.p2
     @pytest.mark.parametrize(