Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(sdk-chunk): correct chunk API behavior (#21733)

Sbaaoui Idriss3c348bd61349
diff --git a/internal/handler/chunk.go b/internal/handler/chunk.go
index f30832a683..efa7e53c88 100644
--- a/internal/handler/chunk.go
+++ b/internal/handler/chunk.go
@@ -170,6 +170,9 @@ func (h *ChunkHandler) ListChunks(c *gin.Context) {
Size: &size,
Keywords: c.Query("keywords"),
}
+ if ids := queryStringList(c, "id"); len(ids) > 0 {
+ req.ChunkIDs = ids
+ }
available, ok, err := parseAvailableQuery(c.Query("available"))
if err != nil {
common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
@@ -481,26 +484,30 @@ func (h *ChunkHandler) UpdateChunk(c *gin.Context) {
// Build UpdateChunkRequest from rawBody
var req service.UpdateChunkRequest
- if content, ok := rawBody["content"].(string); ok {
- req.Content = &content
- }
- if importantKwd, ok := rawBody["important_keywords"].([]interface{}); ok {
- req.ImportantKwd = make([]string, len(importantKwd))
- for i, v := range importantKwd {
- if s, ok := v.(string); ok {
- req.ImportantKwd[i] = s
- }
- }
+ content, err := optionalBodyString(rawBody, "content", "`content` must be a string")
+ if err != nil {
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
+ return
}
- if questions, ok := rawBody["questions"].([]interface{}); ok {
- req.Questions = make([]string, len(questions))
- for i, v := range questions {
- if s, ok := v.(string); ok {
- req.Questions[i] = s
- }
+ req.Content = content
+ for _, field := range []string{"important_keywords", "questions"} {
+ values, err := addChunkStringListField(rawFields, field, "`"+field+"` is required to be a list", "`"+field+"` must be a list of strings")
+ if err != nil {
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeDataError, nil, err.Error())
+ return
+ }
+ if field == "important_keywords" {
+ req.ImportantKwd = values
+ } else {
+ req.Questions = values
}
}
- if available, ok := rawBody["available"].(bool); ok {
+ if raw, exists := rawBody["available"]; exists {
+ available, ok := raw.(bool)
+ if !ok {
+ common.ResponseWithHttpCodeData(c, http.StatusBadRequest, common.CodeArgumentError, nil, "`available` must be a boolean")
+ return
+ }
req.Available = &available
}
if positions, ok := rawBody["positions"].([]interface{}); ok {
diff --git a/internal/handler/chunk_sdk_contract_test.go b/internal/handler/chunk_sdk_contract_test.go
new file mode 100644
index 0000000000..52aab1b87a
--- /dev/null
+++ b/internal/handler/chunk_sdk_contract_test.go
@@ -0,0 +1,66 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package handler
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "ragflow/internal/service"
+ "strings"
+ "testing"
+)
+
+func TestChunkUpdateRejectsMalformedSDKFields(t *testing.T) {
+ for _, body := range []string{`{"content":null}`, `{"content":1}`, `{"important_keywords":[1]}`, `{"important_keywords":null}`, `{"questions":"abc"}`, `{"questions":[false]}`, `{"available":1}`, `{"available":"true"}`} {
+ t.Run(body, func(t *testing.T) {
+ mock := &mockChunkSvc{updateChunkFn: func(context.Context, *service.UpdateChunkRequest, string) error {
+ t.Error("invalid update reached service")
+ return nil
+ }}
+ r, h := setupChunkHandlerWithUser("user-1", mock)
+ r.PATCH("/datasets/:dataset_id/documents/:document_id/chunks/:chunk_id", h.UpdateChunk)
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodPatch, "/datasets/kb/documents/doc/chunks/chunk", strings.NewReader(body)))
+ var payload struct {
+ Code int `json:"code"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+ t.Fatal(err)
+ }
+ if payload.Code == 0 {
+ t.Fatal("invalid update accepted")
+ }
+ })
+ }
+}
+
+func TestChunkListAcceptsSDKID(t *testing.T) {
+ mock := &mockChunkSvc{listFn: func(_ context.Context, req *service.ListChunksRequest, _ string) (*service.ListChunksResponse, error) {
+ if len(req.ChunkIDs) != 1 || req.ChunkIDs[0] != "sdk-id" {
+ t.Errorf("filter=%v", req.ChunkIDs)
+ }
+ return &service.ListChunksResponse{}, nil
+ }}
+ r, h := setupChunkHandlerWithUser("user-1", mock)
+ r.GET("/datasets/:dataset_id/documents/:document_id/chunks", h.ListChunks)
+ w := httptest.NewRecorder()
+ r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/datasets/kb/documents/doc/chunks?id=sdk-id", nil))
+ if w.Code != 200 {
+ t.Fatal(w.Body.String())
+ }
+}
diff --git a/internal/service/chunk/chunk.go b/internal/service/chunk/chunk.go
index 4ad9518d21..ba9443459f 100644
--- a/internal/service/chunk/chunk.go
+++ b/internal/service/chunk/chunk.go
@@ -987,6 +987,12 @@ func (s *ChunkService) List(ctx context.Context, req *service.ListChunksRequest,
}
}
}
+ result["id"] = result["chunk_id"]
+ result["content"] = result["content_with_weight"]
+ utility.SetFieldArray(result, "important_keywords", result["important_kwd"])
+ utility.SetFieldArray(result, "questions", result["question_kwd"])
+ result["document_id"] = req.DocID
+ result["dataset_id"] = doc.KbID
chunks = append(chunks, result)
}
@@ -1309,7 +1315,7 @@ func (s *ChunkService) RemoveChunks(ctx context.Context, req *service.RemoveChun
// Delete all chunks for this document
condition["doc_id"] = req.DocID
default:
- return 0, fmt.Errorf("either chunk_ids or delete_all must be provided")
+ return 0, nil
}
deletedCount, err := s.docEngine.DeleteChunks(ctx, condition, indexName, doc.KbID)
diff --git a/internal/service/chunk/chunk_sdk_contract_test.go b/internal/service/chunk/chunk_sdk_contract_test.go
new file mode 100644
index 0000000000..c7027a687f
--- /dev/null
+++ b/internal/service/chunk/chunk_sdk_contract_test.go
@@ -0,0 +1,58 @@
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package chunk
+
+import (
+ "ragflow/internal/dao"
+ "ragflow/internal/service"
+ "reflect"
+ "testing"
+)
+
+func TestSDKChunkListSchemaAndEmptyDeletion(t *testing.T) {
+ db := setupChunkTestDB(t)
+ pushChunkTestDB(t, db)
+ insertChunkTestUserTenant(t, "user-1", "tenant-1")
+ insertChunkTestKB(t, "kb-1", "tenant-1")
+ insertChunkTestDoc(t, "doc-1", "kb-1")
+ engine := &listChunksSearchEngine{chunks: []map[string]interface{}{{"id": "chunk-1", "content_with_weight": "body", "important_kwd": []string{"key"}, "question_kwd": []string{"question"}}}}
+ engine.chunks = append(engine.chunks, map[string]interface{}{"id": "chunk-2", "content_with_weight": "plain"})
+ svc := &ChunkService{docEngine: engine, kbDAO: dao.NewKnowledgebaseDAO()}
+ ctx := chunkTestContext(t, "user-1", "tenant-1")
+ resp, err := svc.List(ctx, &service.ListChunksRequest{DatasetID: "kb-1", DocID: "doc-1"}, "user-1")
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, field := range []string{"id", "content", "important_keywords", "questions"} {
+ if _, ok := resp.Chunks[0][field]; !ok {
+ t.Errorf("missing public field %s: %#v", field, resp.Chunks[0])
+ }
+ }
+ for _, field := range []string{"important_keywords", "questions"} {
+ if !reflect.DeepEqual(resp.Chunks[1][field], []interface{}{}) {
+ t.Errorf("missing extraction list %s=%#v", field, resp.Chunks[1][field])
+ }
+ }
+ for _, ids := range [][]string{nil, {}} {
+ n, err := svc.RemoveChunks(ctx, &service.RemoveChunksRequest{DatasetID: "kb-1", DocID: "doc-1", ChunkIDs: ids}, "user-1")
+ if err != nil || n != 0 {
+ t.Errorf("empty selection: count=%d err=%v", n, err)
+ }
+ }
+ if engine.deleteChunksCalls != 0 {
+ t.Fatal("empty deletion reached engine")
+ }
+}
diff --git a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_delete_chunks.py b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_delete_chunks.py
index 93be5d59c0..80781a2adf 100644
--- a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_delete_chunks.py
+++ b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_delete_chunks.py
@@ -81,7 +81,6 @@ class TestChunksDeletion:
document.delete_chunks(**payload)
wait_ids(document, ids[removed:])
- @pytest.mark.skip(reason="Go RemoveChunks rejects omitted/empty IDs instead of documented safe no-op")
@pytest.mark.parametrize("payload", [{}, {"ids": None}, {"ids": []}])
def test_empty_selection_is_noop(self, add_chunks, payload):
_, document, chunks = add_chunks
diff --git a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_list_chunks.py b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_list_chunks.py
index a412537a01..559d9ef2f8 100644
--- a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_list_chunks.py
+++ b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_list_chunks.py
@@ -75,7 +75,6 @@ class TestChunksList:
_, document, _ = add_chunks
assert len(document.list_chunks(id=chunk_id)) == 4
- @pytest.mark.skip(reason="SDK sends id but Go ListChunks only reads chunk_ids; Go list also omits SDK id field")
@pytest.mark.parametrize("selection", ["existing", "unknown"])
def test_id(self, add_chunks, selection):
_, document, chunks = add_chunks
@@ -83,7 +82,6 @@ class TestChunksList:
rows = document.list_chunks(id=wanted)
assert [chunk.id for chunk in rows] == ([wanted] if selection == "existing" else [])
- @pytest.mark.skip(reason="Go List returns chunk_id/content_with_weight/important_kwd/question_kwd without SDK field mapping")
def test_list_chunk_schema(self, add_chunks):
dataset, document, chunks = add_chunks
rows = document.list_chunks(page_size=100)
diff --git a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_update_chunk.py b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_update_chunk.py
index b1b78e1abc..66df4fad69 100644
--- a/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_update_chunk.py
+++ b/test/testcases/test_sdk_api/test_chunk_management_within_dataset/test_update_chunk.py
@@ -44,8 +44,8 @@ class TestUpdatedChunk:
@pytest.mark.parametrize(
"content",
[
- pytest.param(None, marks=pytest.mark.skip(reason="Go UpdateChunk silently ignores non-string content")),
- pytest.param(1, marks=pytest.mark.skip(reason="Go UpdateChunk silently ignores non-string content")),
+ pytest.param(None),
+ pytest.param(1),
],
)
def test_content_invalid(self, add_chunks, content):
@@ -69,8 +69,8 @@ class TestUpdatedChunk:
@pytest.mark.parametrize(
"field",
[
- pytest.param("important_keywords", marks=pytest.mark.skip(reason="Go UpdateChunk ignores invalid keyword types or replaces non-string elements with empty strings")),
- pytest.param("questions", marks=pytest.mark.skip(reason="Go UpdateChunk ignores invalid question types or replaces non-string elements with empty strings")),
+ pytest.param("important_keywords"),
+ pytest.param("questions"),
"tag_kwd",
],
)
@@ -91,7 +91,6 @@ class TestUpdatedChunk:
chunks[0].update({"available": available})
assert_updated(document, chunks[0], "available", available)
- @pytest.mark.skip(reason="Go UpdateChunk only reads bool availability and silently ignores other types")
@pytest.mark.parametrize("available", ["True", "False", 1, 0])
def test_available_invalid(self, add_chunks, available):
_, _, chunks = add_chunks