Skip to content

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

21.3 KB
Raw Blame
//
//  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"
	"fmt"
	"ragflow/internal/common"
	"ragflow/internal/dao/transaction"
	"ragflow/internal/entity"
	"strings"

	"gorm.io/gorm"
	"gorm.io/gorm/clause"
)

// DocumentDAO document data access object
type DocumentDAO struct{}

// NewDocumentDAO create document DAO
func NewDocumentDAO() *DocumentDAO {
	return &DocumentDAO{}
}

// Create document
func (dao *DocumentDAO) Create(ctx context.Context, db *gorm.DB, document *entity.Document) error {
	return db.WithContext(ctx).Create(document).Error
}

// GetByID get document by ID
func (dao *DocumentDAO) GetByID(ctx context.Context, db *gorm.DB, id string) (*entity.Document, error) {
	var document entity.Document
	err := db.WithContext(ctx).Take(&document, "id = ?", id).Error
	if err != nil {
		return nil, err
	}
	return &document, nil
}

// GetByIDForUpdate fetches a document while holding the row lock used to
// serialize creation of its ingestion-run identity. Callers must use a short
// transaction and perform no external I/O while holding the lock.
func (dao *DocumentDAO) GetByIDForUpdate(ctx context.Context, db *gorm.DB, id string) (*entity.Document, error) {
	var document entity.Document
	err := db.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).Take(&document, "id = ?", id).Error
	if err != nil {
		return nil, err
	}
	return &document, nil
}

// GetByAuthorID get documents by author ID
func (dao *DocumentDAO) GetByAuthorID(ctx context.Context, db *gorm.DB, authorID string, offset, limit int) ([]*entity.Document, int64, error) {
	var documents []*entity.Document
	var total int64

	query := db.WithContext(ctx).Model(&entity.Document{}).Where("created_by = ?", authorID)
	if err := query.Count(&total).Error; err != nil {
		return nil, 0, err
	}

	err := query.Preload("Author").Offset(offset).Limit(limit).Find(&documents).Error
	return documents, total, err
}

// Update update document
func (dao *DocumentDAO) Update(ctx context.Context, db *gorm.DB, document *entity.Document) error {
	return db.WithContext(ctx).Save(document).Error
}

// UpdateByID updates document by ID with the given fields
func (dao *DocumentDAO) UpdateByID(ctx context.Context, db *gorm.DB, id string, updates map[string]interface{}) error {
	return db.WithContext(ctx).Model(&entity.Document{}).Where("id = ?", id).Updates(updates).Error
}

// IncrementCounts atomically increments chunk_num, token_num, and process_duration for a document
func (dao *DocumentDAO) IncrementCounts(ctx context.Context, db *gorm.DB, id string, kbID string, chunkNum int64, tokenNum int64, duration float64) error {
	return db.WithContext(ctx).Model(&entity.Document{}).
		Where("id = ? AND kb_id = ?", id, kbID).
		Updates(map[string]interface{}{
			"chunk_num":        gorm.Expr("chunk_num + ?", chunkNum),
			"token_num":        gorm.Expr("token_num + ?", tokenNum),
			"process_duration": gorm.Expr("process_duration + ?", duration),
		}).Error
}

// Delete hard-deletes document by ID. Returns rows affected.
func (dao *DocumentDAO) Delete(ctx context.Context, db *gorm.DB, id string) (int64, error) {
	result := db.WithContext(ctx).Where("id = ?", id).Delete(&entity.Document{})
	return result.RowsAffected, result.Error
}

// List documents
func (dao *DocumentDAO) List(ctx context.Context, db *gorm.DB, offset, limit int) ([]*entity.Document, int64, error) {
	var documents []*entity.Document
	var total int64

	if err := db.WithContext(ctx).Model(&entity.Document{}).Count(&total).Error; err != nil {
		return nil, 0, err
	}

	err := db.WithContext(ctx).Preload("Author").Offset(offset).Limit(limit).Find(&documents).Error
	return documents, total, err
}

// DocumentListOptions contains filters for listing documents in a dataset.
type DocumentListOptions struct {
	KbID               string
	Keywords           string
	RunStatuses        []string
	Types              []string
	Suffixes           []string
	Name               string
	DocIDs             []string
	DocIDFilterApplied bool
	CreateTimeFrom     int64
	CreateTimeTo       int64
	OrderBy            string
	Desc               bool
	Offset             int
	Limit              int
}

// ListByKBID list documents by knowledge base ID
func (dao *DocumentDAO) ListByKBID(ctx context.Context, db *gorm.DB, kbID, keywords string, offset, limit int) ([]*entity.DocumentListItem, int64, error) {
	return dao.ListByKBIDWithOptions(ctx, db, DocumentListOptions{
		KbID:     kbID,
		Keywords: keywords,
		OrderBy:  "create_time",
		Desc:     true,
		Offset:   offset,
		Limit:    limit,
	})
}

const latestIngestionTaskJoin = `LEFT JOIN ingestion_task ON ingestion_task.document_id = document.id
	AND NOT EXISTS (
		SELECT 1
		FROM ingestion_task newer_ingestion_task
		WHERE newer_ingestion_task.document_id = ingestion_task.document_id
		  AND (
			COALESCE(newer_ingestion_task.create_time, 0) > COALESCE(ingestion_task.create_time, 0)
			OR (
				COALESCE(newer_ingestion_task.create_time, 0) = COALESCE(ingestion_task.create_time, 0)
				AND newer_ingestion_task.id > ingestion_task.id
			)
		  )
	)`

func buildDocumentListIngestionStatusExpression(db *gorm.DB) string {
	const taskStatus = "COALESCE(NULLIF(ingestion_task.status, ''), 'UNSTART')"
	if !db.Migrator().HasColumn(&entity.Document{}, "run") {
		return taskStatus
	}

	return `CASE
		WHEN ingestion_task.id IS NOT NULL THEN ` + taskStatus + `
		WHEN document.run = '1' THEN 'RUNNING'
		WHEN document.run = '2' THEN 'STOPPED'
		WHEN document.run = '3' THEN 'COMPLETED'
		WHEN document.run = '4' THEN 'FAILED'
		WHEN document.run = '5' THEN 'SCHEDULED'
		ELSE 'UNSTART'
	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)

	// Historical retries can leave multiple ingestion tasks per document. Keep
	// only the newest row, with ID as a deterministic tie-breaker for equal
	// create times. This ordering must match IngestionTaskDAO's task lookups.
	listQuery := db.WithContext(ctx).Table("document").
		Select(`document.*, user_canvas.title as pipeline_name, user.nickname, ` + ingestionStatus + ` as ingestion_status, ingestion_task.pipeline_log_id as pipeline_log_id`).
		Joins("JOIN file2document ON file2document.document_id = document.id").
		Joins("JOIN file ON file.id = file2document.file_id").
		Joins("LEFT JOIN user_canvas ON document.pipeline_id = user_canvas.id").
		Joins("LEFT JOIN user ON document.created_by = user.id").
		Joins(latestIngestionTaskJoin)

	countQuery := db.WithContext(ctx).Table("document").
		Joins("JOIN file2document ON file2document.document_id = document.id").
		Joins("JOIN file ON file.id = file2document.file_id")
	if len(opts.RunStatuses) > 0 {
		countQuery = countQuery.Joins(latestIngestionTaskJoin)
	}

	listQuery = applyDocumentListFilters(listQuery, opts, true, ingestionStatus)
	countQuery = applyDocumentListFilters(countQuery, opts, true, ingestionStatus)

	if err := countQuery.Count(&total).Error; err != nil {
		return nil, 0, err
	}

	orderBy := documentListOrderColumn(opts.OrderBy, ingestionStatus)
	if opts.Desc {
		orderBy += " DESC"
	} else {
		orderBy += " ASC"
	}

	err := listQuery.
		Order(orderBy).
		Offset(opts.Offset).
		Limit(opts.Limit).
		Scan(&documents).Error
	return documents, total, err
}

// 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"`
		Suffix          string  `gorm:"column:suffix"`
	}
	ingestionStatus := buildDocumentListIngestionStatusExpression(db)

	query := db.WithContext(ctx).Table("document").
		Select("document.id, " + ingestionStatus + " as ingestion_status, document.suffix").
		Joins("JOIN file2document ON file2document.document_id = document.id").
		Joins("JOIN file ON file.id = file2document.file_id").
		Joins(latestIngestionTaskJoin)
	query = applyDocumentListFilters(query, opts, true, ingestionStatus)

	if err := query.Scan(&rows).Error; err != nil {
		return nil, 0, err
	}

	suffixCounter := map[string]int64{}
	statusCounter := map[string]int64{}
	for _, row := range rows {
		if row.Suffix != "" {
			suffixCounter[row.Suffix]++
		}
		status := "UNSTART"
		if row.IngestionStatus != nil && *row.IngestionStatus != "" {
			status = *row.IngestionStatus
		}
		statusCounter[status]++
	}

	return map[string]interface{}{
		"suffix":           suffixCounter,
		"ingestion_status": statusCounter,
		"metadata":         map[string]interface{}{},
	}, int64(len(rows)), nil
}

// 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").
		Select("document.id").
		Joins("JOIN file2document ON file2document.document_id = document.id").
		Joins("JOIN file ON file.id = file2document.file_id")
	if len(opts.RunStatuses) > 0 {
		ingestionStatus = buildDocumentListIngestionStatusExpression(db)
		query = query.Joins(latestIngestionTaskJoin)
	}
	query = applyDocumentListFilters(query, opts, true, ingestionStatus)
	if err := query.Scan(&ids).Error; err != nil {
		return nil, err
	}
	return ids, nil
}

func applyDocumentListFilters(query *gorm.DB, opts DocumentListOptions, qualified bool, ingestionStatus string) *gorm.DB {
	column := func(name string) string {
		if qualified {
			return "document." + name
		}
		return name
	}

	query = query.Where(column("kb_id")+" = ?", opts.KbID)
	if strings.TrimSpace(opts.Keywords) != "" {
		query = query.Where("LOWER("+column("name")+") LIKE ?", "%"+strings.ToLower(strings.TrimSpace(opts.Keywords))+"%")
	}
	if len(opts.RunStatuses) > 0 {
		query = query.Where("("+ingestionStatus+") IN ?", opts.RunStatuses)
	}
	if len(opts.Types) > 0 {
		query = query.Where(column("type")+" IN ?", opts.Types)
	}
	if len(opts.Suffixes) > 0 {
		query = query.Where(column("suffix")+" IN ?", opts.Suffixes)
	}
	if opts.Name != "" {
		query = query.Where(column("name")+" = ?", opts.Name)
	}
	// The document ID clause is not gated on DocIDFilterApplied here: with the
	// flag false and IDs present, applying them narrows the query instead of
	// silently widening it, which is the safe direction to fail in.
	if len(opts.DocIDs) > 0 {
		query = query.Where(column("id")+" IN ?", opts.DocIDs)
	}
	// Note: create_time_from / create_time_to are NOT applied at DB level.
	// They are filtered post-query in the handler so total reflects the
	// unfiltered count, matching the Python API contract.
	return query
}

func documentListOrderColumn(orderBy, ingestionStatus string) string {
	switch orderBy {
	case "update_time":
		return "document.update_time"
	case "name":
		return "document.name"
	case "size":
		return "document.size"
	case "type":
		return "document.type"
	case "run", "ingestion_status":
		return ingestionStatus
	default:
		return "document.create_time"
	}
}

// GetByKBID retrieves all documents in a knowledge base ordered by create time.
func (dao *DocumentDAO) GetByKBID(ctx context.Context, db *gorm.DB, kbID string) ([]*entity.Document, int64, error) {
	var documents []*entity.Document
	var total int64

	query := db.WithContext(ctx).Model(&entity.Document{}).Where("kb_id = ?", kbID)
	if err := query.Count(&total).Error; err != nil {
		return nil, 0, err
	}

	err := query.Order("create_time ASC").Find(&documents).Error
	return documents, total, err
}

// GetChunkingConfig returns the document, dataset, and tenant fields used to
// build a parsing task digest, mirroring DocumentService.get_chunking_config.
func (dao *DocumentDAO) GetChunkingConfig(ctx context.Context, db *gorm.DB, docID string) (map[string]interface{}, error) {
	var row struct {
		ID           string         `gorm:"column:id"`
		KbID         string         `gorm:"column:kb_id"`
		ParserID     string         `gorm:"column:parser_id"`
		ParserConfig entity.JSONMap `gorm:"column:parser_config;type:longtext"`
		Size         int64          `gorm:"column:size"`
		ContentHash  *string        `gorm:"column:content_hash"`
		Language     *string        `gorm:"column:language"`
		EmbdID       string         `gorm:"column:embd_id"`
		TenantID     string         `gorm:"column:tenant_id"`
		Img2TxtID    string         `gorm:"column:img2txt_id"`
		ASRID        string         `gorm:"column:asr_id"`
		LLMID        string         `gorm:"column:llm_id"`
	}

	err := db.WithContext(ctx).Table("document").
		Select(`
			document.id,
			document.kb_id,
			document.parser_id,
			document.parser_config,
			document.size,
			document.content_hash,
			knowledgebase.language,
			knowledgebase.embd_id,
			tenant.id AS tenant_id,
			user_tenant.img2txt_id,
			user_tenant.asr_id,
			user_tenant.llm_id
		`).
		Joins("JOIN knowledgebase ON document.kb_id = knowledgebase.id").
		Joins("JOIN tenant ON knowledgebase.tenant_id = tenant.id").
		Joins("LEFT JOIN user_tenant ON user_tenant.id = (SELECT id FROM user_tenant WHERE tenant_id = tenant.id AND status = '1' AND (role = 'owner' OR user_id = tenant.id) ORDER BY CASE WHEN role = 'owner' THEN 0 ELSE 1 END LIMIT 1)").
		Where("document.id = ?", docID).
		Take(&row).Error
	if err != nil {
		return nil, err
	}

	config := map[string]interface{}{
		"id":            row.ID,
		"kb_id":         row.KbID,
		"parser_id":     row.ParserID,
		"parser_config": row.ParserConfig,
		"size":          row.Size,
		"embd_id":       row.EmbdID,
		"tenant_id":     row.TenantID,
		"img2txt_id":    row.Img2TxtID,
		"asr_id":        row.ASRID,
		"llm_id":        row.LLMID,
	}
	if row.ContentHash != nil {
		config["content_hash"] = *row.ContentHash
	} else {
		config["content_hash"] = nil
	}
	if row.Language != nil {
		config["language"] = *row.Language
	} else {
		config["language"] = nil
	}
	return config, nil
}

// GetAllDocIDsByKBIDs gets all document IDs by knowledge base IDs
func (dao *DocumentDAO) GetAllDocIDsByKBIDs(ctx context.Context, db *gorm.DB, kbIDs []string) ([]map[string]string, error) {
	var docs []struct {
		ID   string `gorm:"column:id"`
		KbID string `gorm:"column:kb_id"`
	}
	err := db.WithContext(ctx).Model(&entity.Document{}).Select("id, kb_id").Where("kb_id IN ?", kbIDs).Find(&docs).Error
	if err != nil {
		return nil, err
	}

	result := make([]map[string]string, len(docs))
	for i, doc := range docs {
		result[i] = map[string]string{"id": doc.ID, "kb_id": doc.KbID}
	}
	return result, nil
}

// ListParserConfigsByKBIDs returns each dataset's distinct document
// parser_config that declares a tag source file, keyed by dataset ID.
//
// Because parser_config is a LONGTEXT column and also carries per-document
// state such as page ranges, an unconstrained DISTINCT across all documents
// forces disk temporary tables and filesort over large JSON blobs. Filtering
// by `parser_config LIKE '%tag_file_id%'` drops the vast majority of
// documents that carry no tag configuration before distinct deduplication,
// avoiding OOM and slow queries on large datasets.
func (dao *DocumentDAO) ListParserConfigsByKBIDs(ctx context.Context, db *gorm.DB, kbIDs []string) (map[string][]entity.JSONMap, error) {
	if len(kbIDs) == 0 {
		return nil, nil
	}
	var rows []struct {
		KbID         string         `gorm:"column:kb_id"`
		ParserConfig entity.JSONMap `gorm:"column:parser_config;type:longtext"`
	}
	query := db.WithContext(ctx).Table("document").
		Distinct("kb_id", "parser_config").
		Where("kb_id IN ?", kbIDs)
	if db.Dialector.Name() == "sqlite" {
		query = query.Where("CAST(parser_config AS TEXT) LIKE '%tag_file_id%'")
	} else {
		query = query.Where("parser_config LIKE '%tag_file_id%'")
	}
	if err := query.Find(&rows).Error; err != nil {
		return nil, err
	}

	result := make(map[string][]entity.JSONMap, len(kbIDs))
	for _, row := range rows {
		if len(row.ParserConfig) == 0 {
			continue
		}
		result[row.KbID] = append(result[row.KbID], row.ParserConfig)
	}
	return result, nil
}

// GetByIDs retrieves documents by multiple IDs
func (dao *DocumentDAO) GetByIDs(ctx context.Context, db *gorm.DB, ids []string) ([]*entity.Document, error) {
	if len(ids) == 0 {
		return nil, nil
	}
	var documents []*entity.Document
	err := db.WithContext(ctx).Model(&entity.Document{}).Where("id IN ?", ids).Find(&documents).Error
	if err != nil {
		return nil, err
	}
	return documents, nil
}

// GetByDocumentIDAndDatasetID retrieves a document by document ID and dataset/KB ID.
func (dao *DocumentDAO) GetByDocumentIDAndDatasetID(ctx context.Context, db *gorm.DB, documentID, datasetID string) (*entity.Document, error) {
	var document entity.Document
	err := db.WithContext(ctx).Where("id = ? AND kb_id = ?", documentID, datasetID).First(&document).Error
	return &document, err
}

// CountByTenantID counts documents belonging to datasets owned by a tenant.
func (dao *DocumentDAO) CountByTenantID(ctx context.Context, db *gorm.DB, tenantID string) (int64, error) {
	var count int64
	err := db.WithContext(ctx).Model(&entity.Document{}).
		Joins("JOIN knowledgebase ON knowledgebase.id = document.kb_id").
		Where("knowledgebase.tenant_id = ?", tenantID).
		Count(&count).Error
	return count, err
}

// CountByUserID counts documents attributed to a user. created_by may contain
// either a user ID or a tenant ID, so it is not a reliable user scope.
func (dao *DocumentDAO) CountByUserID(ctx context.Context, db *gorm.DB, userID string) (int64, error) {
	var count int64
	err := db.WithContext(ctx).Model(&entity.Document{}).
		Where("user_id = ?", userID).
		Count(&count).Error
	return count, err
}

// CountByKBAndSourceTypes counts documents from the selected sources in one dataset.
func (dao *DocumentDAO) CountByKBAndSourceTypes(ctx context.Context, db *gorm.DB, kbID string, sourceTypes []string) (int64, error) {
	if len(sourceTypes) == 0 {
		return 0, nil
	}

	var count int64
	err := db.WithContext(ctx).Model(&entity.Document{}).
		Where("kb_id = ? AND source_type IN ?", kbID, sourceTypes).
		Count(&count).Error
	return count, err
}

// SumSizeByDatasetID returns the total document size for a dataset.
func (dao *DocumentDAO) SumSizeByDatasetID(ctx context.Context, db *gorm.DB, datasetID string) (int64, error) {
	var total int64
	err := db.WithContext(ctx).Model(&entity.Document{}).
		Select("COALESCE(SUM(size), 0)").
		Where("kb_id = ?", datasetID).
		Scan(&total).Error
	return total, err
}

// GetParsingStatusByKBID aggregates document parsing status counts for a
// dataset, mirroring DocumentService.get_parsing_status_by_kb_ids in Python.
func (dao *DocumentDAO) GetParsingStatusByKBID(ctx context.Context, db *gorm.DB, kbID string) (map[string]int64, error) {
	result := map[string]int64{
		"unstart_count": 0,
		"running_count": 0,
		"cancel_count":  0,
		"done_count":    0,
		"fail_count":    0,
	}

	var rows []struct {
		Status *string `gorm:"column:status"`
		Cnt    int64   `gorm:"column:cnt"`
	}
	err := db.WithContext(ctx).Table("document").
		Select("ingestion_task.status, COUNT(document.id) as cnt").
		Joins(latestIngestionTaskJoin).
		Where("document.kb_id = ?", kbID).
		Group("ingestion_task.status").
		Scan(&rows).Error
	if err != nil {
		return nil, err
	}

	for _, row := range rows {
		if row.Status == nil || *row.Status == "" {
			result["unstart_count"] += row.Cnt
			continue
		}
		switch *row.Status {
		case common.CREATED, common.SCHEDULED:
			result["unstart_count"] += row.Cnt
		case common.RUNNING, common.STOPPING:
			result["running_count"] += row.Cnt
		case common.STOPPED:
			result["cancel_count"] += row.Cnt
		case common.COMPLETED:
			result["done_count"] += row.Cnt
		case common.FAILED:
			result["fail_count"] += row.Cnt
		default:
			common.Warn(fmt.Sprintf("GetParsingStatusByKBID: unrecognized task status %q for dataset %s (count: %d)", *row.Status, kbID, row.Cnt))
		}
	}
	return result, nil
}

// NameExistsInKB reports whether a document with the given name already
// exists in the dataset, comparing names case-insensitively.
func (dao *DocumentDAO) NameExistsInKB(ctx context.Context, db *gorm.DB, kbID, name string) (bool, error) {
	var count int64
	err := db.WithContext(ctx).Model(&entity.Document{}).
		Where("LOWER(name) = LOWER(?) AND kb_id = ?", name, kbID).
		Count(&count).Error
	return count > 0, err
}