Skip to content

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

fix(sdk-documents): restore document API contracts (#21741)

Sbaaoui Idriss96ab55dfc945
diff --git a/internal/service/document/document_crud.go b/internal/service/document/document_crud.go
index 3550fbbeaf..3db512b3a2 100644
--- a/internal/service/document/document_crud.go
+++ b/internal/service/document/document_crud.go
@@ -81,9 +81,6 @@ func (s *DocumentService) DownloadDocument(ctx context.Context, datasetID, docID
if err != nil {
return nil, err
}
- if len(data) == 0 {
- return nil, fmt.Errorf("this document is empty")
- }
fileName := ""
if doc.Name != nil {
diff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.go
index 88790f3f5e..653f71f662 100644
--- a/internal/service/document/document_dataset_update.go
+++ b/internal/service/document/document_dataset_update.go
@@ -13,6 +13,7 @@ import (
"ragflow/internal/common"
"ragflow/internal/dao"
+ "ragflow/internal/engine"
"ragflow/internal/entity"
componentpkg "ragflow/internal/ingestion/component"
pipelinepkg "ragflow/internal/ingestion/pipeline"
@@ -584,6 +585,15 @@ func (s *DocumentService) updateDocumentNameOnly(ctx context.Context, doc *entit
titleTks, _ := tok.Tokenize(newName)
titleSmTks, _ := tok.FineGrainedTokenize(titleTks)
indexName := fmt.Sprintf("ragflow_%s", kb.TenantID)
+ if doc.ChunkNum == 0 && engine.Type(s.docEngine) == engine.EngineElasticsearch {
+ exists, err := s.docEngine.ChunkStoreExists(ctx, indexName, doc.KbID)
+ if err != nil {
+ return err
+ }
+ if !exists {
+ return nil
+ }
+ }
return s.docEngine.UpdateChunks(
ctx,
map[string]interface{}{"doc_id": doc.ID},
diff --git a/internal/service/document/document_test.go b/internal/service/document/document_test.go
index 1db5fd3ca1..040af5f923 100644
--- a/internal/service/document/document_test.go
+++ b/internal/service/document/document_test.go
@@ -5407,3 +5407,74 @@ func TestFileDeleteRemovesLinkedDocument(t *testing.T) {
t.Fatal("document should have been deleted but still exists")
}
}
+
+func TestDownloadEmptyDocumentAndMissingBlob(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ store := useFakeStorage(t)
+ insertTestPreviewDoc(t, db, store, "empty-doc", "kb-empty", "")
+ svc := testDocumentService(t)
+ got, err := svc.DownloadDocument(t.Context(), "kb-empty", "empty-doc")
+ if err != nil || got == nil || len(got.Data) != 0 {
+ t.Fatalf("empty download = %#v, %v", got, err)
+ }
+ clear(store.objects)
+ if _, err := svc.DownloadDocument(t.Context(), "kb-empty", "empty-doc"); err == nil {
+ t.Fatal("missing blob must fail")
+ }
+}
+
+type renameStoreEngine struct {
+ fakeChatDocEngine
+ exists bool
+ storeErr error
+ err error
+ updates int
+}
+
+func (e *renameStoreEngine) GetType() string { return "elasticsearch" }
+func (e *renameStoreEngine) ChunkStoreExists(context.Context, string, string) (bool, error) {
+ return e.exists, e.storeErr
+}
+func (e *renameStoreEngine) UpdateChunks(context.Context, map[string]interface{}, map[string]interface{}, string, string) error {
+ e.updates++
+ return e.err
+}
+func TestRenameDocumentChunkStore(t *testing.T) {
+ for _, tc := range []struct {
+ chunks int64
+ exists bool
+ storeErr error
+ name string
+ err error
+ updates int
+ }{
+ {name: "unparsed"}, {name: "zero count indexed", exists: true, updates: 1}, {name: "store error", storeErr: errors.New("store unavailable")}, {name: "parsed", chunks: 1, updates: 1}, {name: "engine error", chunks: 1, err: errors.New("unavailable"), updates: 1},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ db := setupServiceTestDB(t)
+ pushServiceDB(t, db)
+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)
+ insertNamedTestDoc(t, "doc-1", "kb-1", "old.txt", 0, tc.chunks)
+ svc := testDocumentService(t)
+ engine := &renameStoreEngine{err: tc.err, exists: tc.exists, storeErr: tc.storeErr}
+ svc.docEngine = engine
+ doc, err := svc.documentDAO.GetByID(t.Context(), db, "doc-1")
+ if err != nil {
+ t.Fatal(err)
+ }
+ kb, err := dao.NewKnowledgebaseDAO().GetByID(t.Context(), db, "kb-1")
+ if err != nil {
+ t.Fatal(err)
+ }
+ err = svc.updateDocumentNameOnly(t.Context(), doc, kb, "new.txt")
+ wantErr := tc.err
+ if tc.storeErr != nil {
+ wantErr = tc.storeErr
+ }
+ if !errors.Is(err, wantErr) || engine.updates != tc.updates {
+ t.Fatalf("rename error=%v updates=%d", err, engine.updates)
+ }
+ })
+ }
+}
diff --git a/sdk/python/ragflow_sdk/modules/dataset.py b/sdk/python/ragflow_sdk/modules/dataset.py
index e54427cf37..8b8f750d5d 100644
--- a/sdk/python/ragflow_sdk/modules/dataset.py
+++ b/sdk/python/ragflow_sdk/modules/dataset.py
@@ -1,5 +1,5 @@
#
-# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.
+# 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.
@@ -127,6 +127,7 @@ class DataSet(Base):
import time
terminal_states = {"DONE", "FAIL", "CANCEL"}
+ ingestion_terminal_states = {"COMPLETED": "DONE", "FAILED": "FAIL", "STOPPED": "CANCEL"}
interval_sec = 1
pending = set(document_ids)
finished = []
@@ -136,7 +137,11 @@ class DataSet(Base):
if not docs:
raise RuntimeError(f"Document {doc_id} not found while waiting for parsing to finish")
doc = docs[0]
- if isinstance(doc.run, str) and doc.run.upper() in terminal_states:
+ status = ingestion_terminal_states.get(doc.ingestion_status)
+ if status:
+ finished.append((doc_id, status, doc.chunk_count, doc.token_count))
+ pending.discard(doc_id)
+ elif isinstance(doc.run, str) and doc.run.upper() in terminal_states:
finished.append((doc_id, doc.run, doc.chunk_count, doc.token_count))
pending.discard(doc_id)
elif float(doc.progress or 0.0) >= 1.0:
diff --git a/sdk/python/ragflow_sdk/modules/document.py b/sdk/python/ragflow_sdk/modules/document.py
index c5141f5b49..d52cba6386 100644
--- a/sdk/python/ragflow_sdk/modules/document.py
+++ b/sdk/python/ragflow_sdk/modules/document.py
@@ -1,5 +1,5 @@
#
-# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.
+# 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.
@@ -44,6 +44,7 @@ class Document(Base):
self.progress_msg = ""
self.process_begin_at = None
self.process_duration = 0.0
+ self.ingestion_status = ""
self.run = "0"
self.status = "1"
self.meta_fields = {}
diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py
index 13b5ecd39d..088390c98b 100644
--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py
+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py
@@ -141,13 +141,6 @@ def test_file_type_validation(add_dataset_func, generate_test_files, request):
@pytest.mark.integration
class TestDocumentDownload:
@pytest.mark.p3
- @pytest.mark.skip(
- reason=(
- "Go DocumentService.DownloadDocument rejects zero-byte blobs in "
- "internal/service/document/document_crud.go; upload is supported "
- "by test/api/document_api_test.go::TestRESTDocumentUploadPersistenceAndNames."
- )
- )
def test_download_empty_uploaded_file(self, add_dataset_func):
dataset = add_dataset_func
documents = dataset.upload_documents([{"display_name": "empty.txt", "blob": b""}])
diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py
index 01eb0ed9a5..3013c482e5 100644
--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py
+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py
@@ -322,30 +322,8 @@ def test_terminal_status_from_previous_parse_run_is_not_reused(monkeypatch):
"ingestion_status, progress, expected_status",
[
("COMPLETED", 1.0, "DONE"),
- pytest.param(
- "FAILED",
- -1.0,
- "FAIL",
- marks=pytest.mark.skip(
- reason=(
- "Go document-list handler internal/handler/document.go:mapDocumentListItem "
- "returns ingestion_status, which sdk/python/ragflow_sdk/modules/document.py:Document.__init__ "
- "drops; DataSet._get_documents_status then polls forever for failed tasks."
- )
- ),
- ),
- pytest.param(
- "STOPPED",
- 0.0,
- "CANCEL",
- marks=pytest.mark.skip(
- reason=(
- "Go document-list handler internal/handler/document.go:mapDocumentListItem "
- "returns ingestion_status, which sdk/python/ragflow_sdk/modules/document.py:Document.__init__ "
- "drops; DataSet._get_documents_status then polls forever for cancelled tasks."
- )
- ),
- ),
+ ("FAILED", -1.0, "FAIL"),
+ ("STOPPED", 0.0, "CANCEL"),
],
)
def test_parse_documents_returns_documented_terminal_status(monkeypatch, ingestion_status, progress, expected_status):
diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py
index fe9be941c5..8134ff2287 100644
--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py
+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py
@@ -14,34 +14,27 @@
# limitations under the License.
#
-import os
from unittest.mock import Mock
import pytest
from ragflow_sdk import Document
-_unindexed_rename = pytest.mark.skipif(
- os.getenv("RAGFLOW_SDK_DOC_ENGINE", os.getenv("DOC_ENGINE")) == "elasticsearch",
- reason="Go updateDocumentNameOnly updates chunks for an unparsed document without an Elasticsearch index (document_dataset_update.go:587; elasticsearch/chunk.go:353)",
-)
-
-
@pytest.mark.integration
class TestDocumentsUpdated:
@pytest.mark.p1
@pytest.mark.parametrize(
"name, expected_message",
[
- pytest.param("new_name.txt", "", marks=_unindexed_rename),
- pytest.param(f"{'a' * 251}.txt", "", marks=_unindexed_rename),
+ ("new_name.txt", ""),
+ (f"{'a' * 251}.txt", ""),
(0, "Field: <name> - Message: <Input should be a valid string> - Value: <0>"),
(None, "Field: <name> - Message: <Input should be a valid string> - Value: <None>"),
("", "the extension of file can't be changed"),
("ragflow_test_upload_0", "the extension of file can't be changed"),
("ragflow_test_upload_1.txt", "duplicated document name in the same dataset"),
("RAGFLOW_TEST_UPLOAD_1.TXT", "duplicated document name in the same dataset"),
- pytest.param("RAGFLOW_TEST_UPLOAD_0.TXT", "", marks=_unindexed_rename),
+ ("RAGFLOW_TEST_UPLOAD_0.TXT", ""),
],
)
def test_name(self, add_documents, name, expected_message):