Skip to content

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

Fix: prevent database query when no-data (#20938)

Lynn13a9be5bd2ad
diff --git a/internal/dao/document.go b/internal/dao/document.go
index 2341eb84c1..3de86fbca9 100644
--- a/internal/dao/document.go
+++ b/internal/dao/document.go
@@ -20,6 +20,7 @@ import (
"context"
"fmt"
"ragflow/internal/common"
+ "ragflow/internal/dao/transaction"
"ragflow/internal/entity"
"strings"
@@ -177,8 +178,18 @@ func buildDocumentListIngestionStatusExpression(db *gorm.DB) string {
END`
}
+// documentCircuit projects opts onto the query circuit so every document query
+// agrees on what "this request can match nothing" means.
+func (opts DocumentListOptions) documentCircuit() transaction.DocumentQueryCircuit {
+ return transaction.NewDocumentQueryCircuit(opts.DocIDFilterApplied, opts.DocIDs)
+}
+
// ListByKBIDWithOptions lists documents by knowledge base ID with filters.
func (dao *DocumentDAO) ListByKBIDWithOptions(ctx context.Context, db *gorm.DB, opts DocumentListOptions) ([]*entity.DocumentListItem, int64, error) {
+ if opts.documentCircuit().IsCircuitOpen() {
+ return nil, 0, nil
+ }
+
var documents []*entity.DocumentListItem
var total int64
ingestionStatus := buildDocumentListIngestionStatusExpression(db)
@@ -225,6 +236,10 @@ func (dao *DocumentDAO) ListByKBIDWithOptions(ctx context.Context, db *gorm.DB,
// GetFilterByKBID returns aggregate filter counts for documents in a dataset.
func (dao *DocumentDAO) GetFilterByKBID(ctx context.Context, db *gorm.DB, opts DocumentListOptions) (map[string]interface{}, int64, error) {
+ if circuit := opts.documentCircuit(); circuit.IsCircuitOpen() {
+ return circuit.CircuitOpenFilters(), 0, nil
+ }
+
var rows []struct {
ID string `gorm:"column:id"`
IngestionStatus *string `gorm:"column:ingestion_status"`
@@ -265,6 +280,10 @@ func (dao *DocumentDAO) GetFilterByKBID(ctx context.Context, db *gorm.DB, opts D
// ListIDsByKBIDWithOptions lists matching document IDs without pagination.
func (dao *DocumentDAO) ListIDsByKBIDWithOptions(ctx context.Context, db *gorm.DB, opts DocumentListOptions) ([]string, error) {
+ if opts.documentCircuit().IsCircuitOpen() {
+ return nil, nil
+ }
+
var ids []string
var ingestionStatus string
query := db.WithContext(ctx).Table("document").
diff --git a/internal/dao/document_circuit_test.go b/internal/dao/document_circuit_test.go
new file mode 100644
index 0000000000..b59cbeb65e
--- /dev/null
+++ b/internal/dao/document_circuit_test.go
@@ -0,0 +1,87 @@
+//
+// 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 dao
+
+import (
+ "context"
+ "testing"
+
+ "github.com/glebarez/sqlite"
+ "gorm.io/gorm"
+)
+
+// openDocumentCircuitTestDB returns a handle whose tables do not exist, so any
+// query that actually reaches the database fails loudly instead of returning an
+// empty result the caller could mistake for an open circuit.
+func openDocumentCircuitTestDB(t *testing.T) *gorm.DB {
+ t.Helper()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{TranslateError: true})
+ if err != nil {
+ t.Fatalf("failed to open sqlite: %v", err)
+ }
+ return db
+}
+
+func TestDocumentQueriesResolveOpenCircuitWithoutQuery(t *testing.T) {
+ db := openDocumentCircuitTestDB(t)
+ documentDAO := NewDocumentDAO()
+ opts := DocumentListOptions{KbID: "kb-1", DocIDFilterApplied: true}
+ ctx := context.Background()
+
+ documents, total, err := documentDAO.ListByKBIDWithOptions(ctx, db, opts)
+ if err != nil {
+ t.Fatalf("ListByKBIDWithOptions queried the database: %v", err)
+ }
+ if len(documents) != 0 || total != 0 {
+ t.Fatalf("ListByKBIDWithOptions = (%v, %d), want (empty, 0)", documents, total)
+ }
+
+ filters, total, err := documentDAO.GetFilterByKBID(ctx, db, opts)
+ if err != nil {
+ t.Fatalf("GetFilterByKBID queried the database: %v", err)
+ }
+ if total != 0 {
+ t.Fatalf("GetFilterByKBID total = %d, want 0", total)
+ }
+ if _, ok := filters["suffix"].(map[string]int64); !ok {
+ t.Fatalf("GetFilterByKBID suffix bucket type = %T, want map[string]int64", filters["suffix"])
+ }
+ if _, ok := filters["ingestion_status"].(map[string]int64); !ok {
+ t.Fatalf("GetFilterByKBID ingestion_status bucket type = %T, want map[string]int64", filters["ingestion_status"])
+ }
+ if _, ok := filters["metadata"].(map[string]interface{}); !ok {
+ t.Fatalf("GetFilterByKBID metadata bucket type = %T, want map[string]interface{}", filters["metadata"])
+ }
+
+ ids, err := documentDAO.ListIDsByKBIDWithOptions(ctx, db, opts)
+ if err != nil {
+ t.Fatalf("ListIDsByKBIDWithOptions queried the database: %v", err)
+ }
+ if len(ids) != 0 {
+ t.Fatalf("ListIDsByKBIDWithOptions = %v, want empty", ids)
+ }
+}
+
+func TestDocumentQueriesStillQueryWhenCircuitClosed(t *testing.T) {
+ db := openDocumentCircuitTestDB(t)
+ documentDAO := NewDocumentDAO()
+ ctx := context.Background()
+
+ if _, _, err := documentDAO.ListByKBIDWithOptions(ctx, db, DocumentListOptions{KbID: "kb-1"}); err == nil {
+ t.Fatal("ListByKBIDWithOptions answered from a circuit that should have stayed closed")
+ }
+}
diff --git a/internal/dao/transaction/document_circuit.go b/internal/dao/transaction/document_circuit.go
new file mode 100644
index 0000000000..566db24b8d
--- /dev/null
+++ b/internal/dao/transaction/document_circuit.go
@@ -0,0 +1,61 @@
+//
+// 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 transaction holds business transactions that span DAO calls: it
+// composes several DAO reads and writes into one atomic unit of work, and owns
+// the business rules that decide what those reads and writes should be.
+//
+// Short circuits belong here too. Deciding that a request can match nothing is
+// a business rule, and resolving it before composing the query means no DAO
+// call — and therefore no transaction — is opened for work that has a known
+// answer.
+package transaction
+
+// DocumentQueryCircuit decides whether a document query leaves the process at
+// all. A document request can ask for an intersection of IDs that business
+// rules already know is empty, and no amount of database work changes that
+// answer.
+//
+// The document ID clause only participates when docIDFilterApplied is true, so
+// "no IDs" is ambiguous on its own: with it false the caller never asked for
+// the clause, with it true the caller asked for an intersection that came out
+// empty. Only the second case opens the circuit.
+type DocumentQueryCircuit struct {
+ docIDFilterApplied bool
+ docIDs []string
+}
+
+// NewDocumentQueryCircuit builds the circuit for one document query.
+func NewDocumentQueryCircuit(docIDFilterApplied bool, docIDs []string) DocumentQueryCircuit {
+ return DocumentQueryCircuit{docIDFilterApplied: docIDFilterApplied, docIDs: docIDs}
+}
+
+// IsCircuitOpen reports whether the query can match no documents, letting the
+// caller answer from business rules instead of opening a database round trip.
+func (c DocumentQueryCircuit) IsCircuitOpen() bool {
+ return c.docIDFilterApplied && len(c.docIDs) == 0
+}
+
+// CircuitOpenFilters is the aggregate breakdown a document filter query reports
+// once the circuit is open. The bucket types mirror the ones a query that ran
+// would build, because callers type-assert on them without checking.
+func (c DocumentQueryCircuit) CircuitOpenFilters() map[string]interface{} {
+ return map[string]interface{}{
+ "suffix": map[string]int64{},
+ "ingestion_status": map[string]int64{},
+ "metadata": map[string]interface{}{},
+ }
+}
diff --git a/internal/dao/transaction/document_circuit_test.go b/internal/dao/transaction/document_circuit_test.go
new file mode 100644
index 0000000000..5766613eea
--- /dev/null
+++ b/internal/dao/transaction/document_circuit_test.go
@@ -0,0 +1,78 @@
+//
+// 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 transaction
+
+import "testing"
+
+func TestDocumentQueryCircuitOpensOnlyForEmptyAppliedIDFilter(t *testing.T) {
+ tests := []struct {
+ name string
+ docIDFilterApplied bool
+ docIDs []string
+ wantCircuitOpen bool
+ }{
+ {
+ name: "filter not applied keeps every document reachable",
+ docIDs: []string{"doc-1"},
+ wantCircuitOpen: false,
+ },
+ {
+ name: "applied filter with an id selects that document",
+ docIDFilterApplied: true,
+ docIDs: []string{"doc-1"},
+ wantCircuitOpen: false,
+ },
+ {
+ name: "applied filter with an empty slice selects nothing",
+ docIDFilterApplied: true,
+ docIDs: []string{},
+ wantCircuitOpen: true,
+ },
+ {
+ name: "applied filter with no ids selects nothing",
+ docIDFilterApplied: true,
+ wantCircuitOpen: true,
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ circuit := NewDocumentQueryCircuit(tt.docIDFilterApplied, tt.docIDs)
+ if got := circuit.IsCircuitOpen(); got != tt.wantCircuitOpen {
+ t.Fatalf("IsCircuitOpen() = %v, want %v", got, tt.wantCircuitOpen)
+ }
+ })
+ }
+}
+
+func TestCircuitOpenFiltersKeepsBucketTypes(t *testing.T) {
+ circuit := NewDocumentQueryCircuit(true, nil)
+ filters := circuit.CircuitOpenFilters()
+
+ if _, ok := filters["suffix"].(map[string]int64); !ok {
+ t.Fatalf("suffix bucket type = %T, want map[string]int64", filters["suffix"])
+ }
+ if _, ok := filters["ingestion_status"].(map[string]int64); !ok {
+ t.Fatalf("ingestion_status bucket type = %T, want map[string]int64", filters["ingestion_status"])
+ }
+ if _, ok := filters["metadata"].(map[string]interface{}); !ok {
+ t.Fatalf("metadata bucket type = %T, want map[string]interface{}", filters["metadata"])
+ }
+ if len(filters) != 3 {
+ t.Fatalf("filter keys = %v, want exactly suffix/ingestion_status/metadata", filters)
+ }
+}