szza look code art 2026-01-06T13:10:38.776Z https://szza.github.io/ fibonaccii Hexo Milvus 搜索流程全面分析 https://szza.github.io/2025/08/10/Milvus/19_search_flow_comprehensive_analysis/ 2025-08-10T08:00:00.000Z 2026-01-06T13:10:38.776Z 目录
  1. 概述
  2. 搜索任务入口
  3. Segment 搜索执行
  4. SearchRequest 和 Plan 参数
  5. Segment Search 内部执行
  6. 结果归约（Reduce）
  7. 高级搜索（Advanced Search）
  8. 完整流程总结

概述

本文档全面分析 Milvus 的搜索流程，从 QueryNode 接收搜索请求开始，到返回最终结果为止。涵盖搜索任务的执行、segment 搜索、计划节点执行、结果归约等各个环节。

搜索流程概览

1
Proxy → QueryNode → SearchTask → SearchSegments → Segment.Search → Reduce → Result

搜索任务入口

1. SearchTask.Execute

SearchTask.Execute 是普通搜索任务的执行入口，负责在 QueryNode 上执行搜索并归约结果。

函数签名

1
func (t *SearchTask) Execute() error

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
func (t *SearchTask) Execute() error {
    // 1. 准备搜索请求
    err := t.combinePlaceHolderGroups()
    searchReq, err := segcore.NewSearchRequest(t.collection.GetCCollection(), req, t.placeholderGroup)
    
    // 2. 根据 Scope 选择搜索历史数据或流式数据
    if req.GetScope() == querypb.DataScope_Historical {
        results, searchedSegments, err = segments.SearchHistorical(...)
    } else if req.GetScope() == querypb.DataScope_Streaming {
        results, searchedSegments, err = segments.SearchStreaming(...)
    }
    
    // 3. 归约多个 segment 的结果
    reducedResult, err := segcore.ReduceSearchResultsAndFillData(...)
    
    // 4. 填充主键和目标字段
    err = segments.FillPrimaryKeys(...)
    err = segments.FillTargetEntry(...)
    
    // 5. 编码并返回结果
    t.result = EncodeSearchResults(...)
    return nil
}

关键步骤

  1. 合并 Placeholder Groups：将多个查询向量合并成一个 PlaceholderGroup
  2. 创建 SearchRequest：封装搜索计划、PlaceholderGroup、时间戳等信息
  3. 搜索 Segments：根据 Scope 搜索历史或流式 segments
  4. 归约结果：将多个 segment 的结果合并成全局 topK
  5. 填充字段：填充主键和目标字段数据
  6. 编码返回：将结果编码为 protobuf 格式

2. StreamingSearchTask.Execute

StreamingSearchTask.Execute 是流式搜索任务的执行入口，支持流式归约，可以边搜索边归约，降低内存占用。

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func (t *StreamingSearchTask) Execute() error {
    // 1. 准备搜索请求
    t.combinePlaceHolderGroups()
    searchReq, err := segcore.NewSearchRequest(...)
    
    // 2. 流式搜索和归约
    if req.GetScope() == querypb.DataScope_Historical {
        streamReduceFunc := func(result *segments.SearchResult) error {
            return t.streamReduce(t.ctx, searchReq.Plan(), result, ...)
        }
        pinnedSegments, err := segments.SearchHistoricalStreamly(
            t.ctx, t.segmentManager, searchReq, ..., streamReduceFunc)
        
        // 3. 获取流式归约结果
        t.resultBlobs, err = segcore.GetStreamReduceResult(t.ctx, t.streamReducer)
    }
    
    return nil
}

流式搜索的优势

  • 内存效率：不需要等待所有 segment 搜索完成，边搜索边归约
  • 延迟优化：可以更早返回部分结果
  • 适合大数据量：当 segment 数量很多时，流式处理可以避免内存峰值

Segment 搜索执行

1. searchSegments 函数

searchSegments 函数在多个 segment 上并发执行搜索，并收集结果。

函数签名

1
2
3
4
5
6
func searchSegments(
    ctx context.Context, 
    mgr *Manager, 
    segments []Segment, 
    segType SegmentType, 
    searchReq *SearchRequest) ([]*SearchResult, error)

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
func searchSegments(ctx context.Context, mgr *Manager, segments []Segment, 
    segType SegmentType, searchReq *SearchRequest) ([]*SearchResult, error) {
    
    // 1. 设置指标标签
    searchLabel := metrics.SealedSegmentLabel
    if segType == commonpb.SegmentState_Growing {
        searchLabel = metrics.GrowingSegmentLabel
    }
    
    // 2. 并发搜索所有 segments
    results := make([]*SearchResult, 0, len(segments))
    var wg sync.WaitGroup
    var mu sync.Mutex
    
    for _, s := range segments {
        wg.Add(1)
        go func(seg Segment) {
            defer wg.Done()
            
            // Pin segment 防止被释放
            if err := seg.PinIfNotReleased(); err != nil {
                return
            }
            defer seg.Unpin()
            
            // 检查是否需要懒加载
            if seg.IsLazyLoad() {
                mgr.DiskCache.Do(seg, func() error {
                    return seg.Load(ctx)
                })
            }
            
            // 执行搜索
            result, err := seg.Search(ctx, searchReq)
            if err != nil {
                return
            }
            
            mu.Lock()
            results = append(results, result)
            mu.Unlock()
        }(s)
    }
    
    wg.Wait()
    return results, nil
}

关键特性

  1. 并发执行：使用 goroutine 并发搜索多个 segments
  2. Segment Pin：Pin segment 防止在搜索过程中被释放
  3. 懒加载支持：如果 segment 需要懒加载，通过 DiskCache 加载
  4. 错误处理：单个 segment 搜索失败不影响其他 segments

2. SearchHistorical 和 SearchStreaming

SearchHistorical

1
2
3
4
5
6
7
8
9
10
11
12
13
func SearchHistorical(ctx context.Context, manager *Manager, searchReq *SearchRequest, 
    collID int64, partIDs []int64, segIDs []int64) ([]*SearchResult, []Segment, error) {
    
    // 验证并获取历史 segments
    segments, err := validateOnHistorical(ctx, manager, collID, partIDs, segIDs)
    if err != nil {
        return nil, nil, err
    }
    
    // 搜索 sealed segments
    searchResults, err := searchSegments(ctx, manager, segments, SegmentTypeSealed, searchReq)
    return searchResults, segments, err
}

搜索范围：

  • 如果 segIDs 未指定：搜索 partIDs 指定的所有历史 segments
  • 如果 segIDs 指定了：只搜索指定的 segments
  • 如果 partIDs 为空：搜索已加载 collection 的所有分区

SearchStreaming

1
2
3
4
5
6
7
8
9
10
11
12
13
func SearchStreaming(ctx context.Context, manager *Manager, searchReq *SearchRequest, 
    collID int64, partIDs []int64, segIDs []int64) ([]*SearchResult, []Segment, error) {
    
    // 验证并获取流式 segments
    segments, err := validateOnStream(ctx, manager, collID, partIDs, segIDs)
    if err != nil {
        return nil, nil, err
    }
    
    // 搜索 growing segments
    searchResults, err := searchSegments(ctx, manager, segments, SegmentTypeGrowing, searchReq)
    return searchResults, segments, err
}

SearchRequest 和 Plan 参数

1. SearchRequest 结构

SearchRequest 封装了搜索请求的所有信息。

结构定义

1
2
3
4
5
6
7
8
9
type SearchRequest struct {
    plan              *SearchPlan              // 搜索计划
    cPlaceholderGroup C.CPlaceholderGroup      // C++ 层的 PlaceholderGroup
    msgID             int64                    // 消息 ID
    searchFieldID     int64                    // 搜索字段 ID
    mvccTimestamp     typeutil.Timestamp       // MVCC 时间戳
    consistencyLevel  commonpb.ConsistencyLevel // 一致性级别
    collectionTTL     typeutil.Timestamp       // Collection TTL
}

创建过程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
func NewSearchRequest(collection *CCollection, req *querypb.SearchRequest, 
    placeholderGrp []byte) (*SearchRequest, error) {
    
    // 1. 从序列化的 Plan 创建 SearchPlan
    expr := req.Req.SerializedExprPlan
    plan, err := createSearchPlanByExpr(collection, expr)
    
    // 2. 解析 PlaceholderGroup
    var cPlaceholderGroup C.CPlaceholderGroup
    status := C.ParsePlaceholderGroup(plan.cSearchPlan, blobPtr, blobSize, &cPlaceholderGroup)
    
    // 3. 验证 MetricType
    metricTypeInPlan := plan.GetMetricType()
    if len(metricType) != 0 && metricType != metricTypeInPlan {
        return nil, merr.WrapErrParameterInvalid(...)
    }
    
    // 4. 获取搜索字段 ID
    var fieldID C.int64_t
    status = C.GetFieldID(plan.cSearchPlan, &fieldID)
    
    return &SearchRequest{
        plan:              plan,
        cPlaceholderGroup: cPlaceholderGroup,
        searchFieldID:     int64(fieldID),
        mvccTimestamp:     req.GetReq().GetMvccTimestamp(),
        consistencyLevel:  req.GetReq().GetConsistencyLevel(),
        collectionTTL:     req.GetReq().GetCollectionTtlTimestamps(),
    }, nil
}

2. Plan 参数的作用

Plan 参数是 segment->Search 的核心参数，包含了搜索执行所需的所有信息。

Plan 结构（C++）

1
2
3
4
5
6
7
8
struct Plan {
    SchemaPtr schema_;                                    // Schema 信息
    std::unique_ptr<VectorPlanNode> plan_node_;          // 计划节点树
    std::map<std::string, FieldId> tag2field_;          // PlaceholderName -> FieldId
    std::vector<FieldId> target_entries_;               // 需要返回的字段 ID
    std::vector<std::string> target_dynamic_fields_;    // 动态字段列表
    std::optional<ExtractedPlanInfo> extra_info_opt_;    // 额外信息（涉及的字段）
};

Plan 的核心作用

1. 搜索前验证（check_search）
1
2
3
4
5
6
7
8
9
10
void ChunkedSegmentSealedImpl::check_search(const query::Plan* plan) const {
    // 检查涉及的字段是否已加载
    auto& request_fields = plan->extra_info_opt_.value().involved_fields_;
    auto field_ready_bitset = field_data_ready_bitset_ | index_ready_bitset_ | binlog_index_bitset_;
    
    auto absent_fields = request_fields - field_ready_bitset;
    if (absent_fields.any()) {
        // 抛出 FieldNotLoaded 错误
    }
}
2. 执行计划节点树

plan->plan_node_ 是 VectorPlanNode，包含：

1
2
3
4
5
struct VectorPlanNode : PlanNode {
    SearchInfo search_info_;                              // 搜索信息（topk, metric_type, field_id 等）
    std::string placeholder_tag_;                         // Placeholder 标签
    std::shared_ptr<milvus::plan::PlanNode> plannodes_;  // 执行计划节点树
};

计划节点树通常包括：

  • MvccNode：MVCC 过滤（时间戳过滤和删除过滤）
  • VectorSearchNode：向量搜索（包含 topK）
  • FilterNode：表达式过滤
  • GroupByNode：Group by 操作（如果启用）
  • RescoresNode：重排序（如果启用）
3. 填充返回字段
1
2
3
4
5
6
7
8
9
10
void SegmentInternalInterface::FillTargetEntry(const query::Plan* plan, 
    SearchResult& results) const {
    
    // 遍历 plan->target_entries_，填充每个字段的数据
    for (auto field_id : plan->target_entries_) {
        auto& field_meta = plan->schema_->operator[](field_id);
        field_data = bulk_subscript(&op_ctx, field_id, results.seg_offsets_.data(), size);
        results.output_fields_data_[field_id] = std::move(field_data);
    }
}

Plan 的创建流程

  1. Proxy 层：解析 DSL 表达式，生成 PlanNode
  2. 设置 SearchInfo：从 search_params 中提取 topK、metric_type 等
  3. 设置 target_entries：从 output_fields 中提取需要返回的字段
  4. 序列化：序列化为 protobuf，发送到 QueryNode
  5. QueryNode：反序列化并创建 C++ Plan 对象

Segment Search 内部执行

1. segment->Search 执行流程

segment->Search 是 C++ 层的搜索执行入口，通过执行计划节点树完成搜索。

函数签名

1
2
3
4
5
6
7
8
std::unique_ptr<SearchResult>
SegmentInternalInterface::Search(
    const query::Plan* plan,
    const query::PlaceholderGroup* placeholder_group,
    Timestamp timestamp,
    const folly::CancellationToken& cancel_token,
    int32_t consistency_level,
    Timestamp collection_ttl) const

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
std::unique_ptr<SearchResult>
SegmentInternalInterface::Search(...) const {
    std::shared_lock lck(mutex_);
    
    // 1. 验证 Plan
    check_search(plan);
    
    // 2. 创建执行访问者
    query::ExecPlanNodeVisitor visitor(*this, timestamp, placeholder_group, 
                                       cancel_token, consistency_level, collection_ttl);
    
    // 3. 执行计划节点树
    auto results = std::make_unique<SearchResult>();
    *results = visitor.get_moved_result(*plan->plan_node_);
    results->segment_ = (void*)this;
    
    return results;
}

2. ExecPlanNodeVisitor 执行计划节点树

visit(VectorPlanNode& node)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
void ExecPlanNodeVisitor::visit(VectorPlanNode& node) {
    // 1. 获取活跃数据量
    auto active_count = segment->get_active_count(timestamp_);
    if (active_count == 0) {
        search_result_opt_ = empty_search_result(...);
        return;
    }
    
    // 2. 构建计划片段
    auto plan = plan::PlanFragment(node.plannodes_);
    
    // 3. 创建查询上下文
    auto query_context = std::make_shared<milvus::exec::QueryContext>(...);
    query_context->set_search_info(node.search_info_);
    query_context->set_placeholder_group(placeholder_group_);
    
    // 4. 执行任务
    auto result = ExecuteTask(plan, query_context);
    
    // 5. 获取搜索结果
    search_result_opt_ = std::move(query_context->get_search_result());
}

3. 计划节点执行顺序

MvccNode - MVCC 过滤

1
2
3
4
5
6
7
8
9
10
11
RowVectorPtr PhyMvccNode::GetOutput() {
    TargetBitmapView data(col_input->GetRawData(), col_input->size());
    
    // 时间戳过滤（MVCC）
    segment_->mask_with_timestamps(data, query_timestamp_, collection_ttl_timestamp_);
    
    // 删除标记过滤
    segment_->mask_with_delete(data, active_count_, query_timestamp_);
    
    return std::make_shared<RowVector>(std::vector<VectorPtr>{col_input});
}

作用：

  • mask_with_timestamps：过滤掉时间戳大于查询时间戳的数据
  • mask_with_delete：过滤掉已删除的数据

VectorSearchNode - 向量搜索 + TopK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
RowVectorPtr PhyVectorSearchNode::GetOutput() {
    // 执行向量搜索
    segment_->vector_search(search_info_,
                           src_data,
                           src_offsets,
                           num_queries,
                           query_timestamp_,
                           final_view,
                           op_context,
                           search_result);
    
    // 设置搜索结果（已包含 topK）
    query_context_->set_search_result(std::move(search_result));
}

作用：

  • 执行向量搜索，使用 search_info_.topk_ 作为 topK
  • 返回的结果已包含 topK 的 seg_offsets_ 和 distances_

GroupByNode - Group By 操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
RowVectorPtr PhyGroupByNode::GetOutput() {
    auto search_result = query_context_->get_search_result();
    
    // 执行 Group By
    milvus::exec::SearchGroupBy(op_context,
                                search_result.vector_iterators_.value(),
                                search_info_,
                                group_by_values,
                                *segment_,
                                search_result.seg_offsets_,
                                search_result.distances_,
                                search_result.topk_per_nq_prefix_sum_);
    
    search_result.group_by_values_ = std::move(group_by_values);
    search_result.group_size_ = search_info_.group_size_;
    
    query_context_->set_search_result(std::move(search_result));
}

作用：

  • 对搜索结果进行 group by 处理
  • 更新 search_result.group_by_values_ 和 group_size_

4. Segment Search 完成的操作总结

在 segment->Search 中，已经完成了以下操作：

✅ MVCC 过滤：通过 MvccNode 执行时间戳和删除过滤
✅ TopK 选择：通过 VectorSearchNode 执行向量搜索，结果已包含 topK
✅ Group By：通过 GroupByNode 执行（如果启用）
✅ 表达式过滤：通过 FilterNode 执行（如果有过滤表达式）
✅ 重排序：通过 RescoresNode 执行（如果启用）

关键点：每个 segment 返回的结果是局部最优的，只代表该 segment 内的 topK，不代表全局最优。

结果归约（Reduce）

1. 为什么需要 Reduce？

虽然每个 segment 已经完成了 MVCC、topK、group by 等操作，但仍然需要对多个 segment 的结果进行 Reduce，原因如下：

  1. 数据分布：数据分布在多个 segments 中
  2. 局部 vs 全局：每个 segment 返回局部 topK，用户需要全局 topK
  3. 去重需求：需要去除跨 segment 的重复 entity
  4. Group By：需要全局的 group by 处理
  5. 成本聚合：需要聚合各个 segment 的成本信息

2. ReduceSearchResults 函数

函数签名

1
2
func ReduceSearchResults(ctx context.Context, results []*internalpb.SearchResults, 
    info *reduce.ResultInfo) (*internalpb.SearchResults, error)

执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
func ReduceSearchResults(ctx context.Context, results []*internalpb.SearchResults, 
    info *reduce.ResultInfo) (*internalpb.SearchResults, error) {
    
    // 1. 过滤空结果
    results = lo.Filter(results, func(result *internalpb.SearchResults, _ int) bool {
        return result != nil && result.GetSlicedBlob() != nil
    })
    
    // 2. 短路优化：如果只有一个结果，直接返回
    if len(results) == 1 {
        return results[0], nil
    }
    
    // 3. 解码搜索结果
    searchResultData, err := DecodeSearchResults(ctx, results)
    
    // 4. 初始化归约器
    searchReduce := InitSearchReducer(info)
    
    // 5. 归约搜索结果
    reducedResultData, err := searchReduce.ReduceSearchResultData(ctx, searchResultData, info)
    
    // 6. 编码结果
    searchResults, err := EncodeSearchResultData(ctx, reducedResultData, ...)
    
    // 7. 聚合成本信息
    searchResults.CostAggregation = mergeRequestCost(requestCosts)
    
    return searchResults, nil
}

3. K-Way Merge 算法

Reduce 使用多路归并（K-Way Merge）算法，从多个已排序的结果中选择全局最优的 topK。

算法原理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
func (scr *SearchCommonReduce) ReduceSearchResultData(
    ctx context.Context, 
    searchResultData []*schemapb.SearchResultData, 
    info *reduce.ResultInfo) (*schemapb.SearchResultData, error) {
    
    // 为每个 segment 的结果维护偏移量
    offsets := make([]int64, len(searchResultData))
    idSet := make(map[interface{}]struct{})  // 用于去重
    
    for i := int64(0); i < info.GetNq(); i++ {
        var j int64
        for j = 0; j < info.GetTopK(); {
            // 从所有 segment 中选择当前最高分
            sel := SelectSearchResultData(searchResultData, resultOffsets, offsets, i)
            if sel == -1 {
                break
            }
            
            idx := resultOffsets[sel][i] + offsets[sel]
            id := typeutil.GetPK(searchResultData[sel].GetIds(), idx)
            score := searchResultData[sel].Scores[idx]
            
            // 去重：跳过已存在的 entity
            if _, ok := idSet[id]; !ok {
                // 添加到最终结果
                retSize += typeutil.AppendFieldData(ret.FieldsData, 
                    searchResultData[sel].FieldsData, idx)
                typeutil.AppendPKs(ret.Ids, id)
                ret.Scores = append(ret.Scores, score)
                idSet[id] = struct{}{}
                j++
            } else {
                skipDupCnt++  // 跳过重复的 entity
            }
            offsets[sel]++  // 移动指针
        }
        ret.Topks = append(ret.Topks, j)
    }
    return ret, nil
}

SelectSearchResultData 函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
func SelectSearchResultData(
    dataArray []*schemapb.SearchResultData, 
    resultOffsets [][]int64, 
    offsets []int64, 
    qi int64) int {
    
    var sel = -1
    var maxDistance = -float32(math.MaxFloat32)
    
    // 遍历所有 segment，找到当前最高分
    for i, offset := range offsets {
        if offset >= dataArray[i].Topks[qi] {
            continue  // 该 segment 的结果已用完
        }
        
        idx := resultOffsets[i][qi] + offset
        distance := dataArray[i].Scores[idx]
        
        if distance > maxDistance {
            sel = i
            maxDistance = distance
        }
    }
    return sel
}

4. Reduce 的其他作用

去重（Deduplication）

同一个 entity 可能同时出现在多个 segments 中：

  • Growing + Sealed：新写入的数据在 growing segment，但可能还未 flush 到 sealed segment
  • Compaction：compaction 过程中，数据可能同时存在于新旧 segments

Group By 处理

如果有 group by 需求，Reduce 阶段会进行全局的 group by 处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
func (sbr *SearchGroupByReduce) ReduceSearchResultData(...) {
    groupByValueMap := make(map[interface{}]int64)
    
    for j = 0; j < groupBound; {
        sel := SelectSearchResultData(...)
        groupByVal := groupByValIterator[sel](idx)
        
        // 检查 group 限制
        if groupCount >= groupSize {
            // 跳过：该 group 已满
        } else {
            // 添加到该 group
            groupByValueMap[groupByVal]++
        }
    }
}

成本聚合

Reduce 还会聚合各个 segment 的存储扫描成本：

1
2
3
4
5
6
storageCost := lo.Reduce(results, func(acc segcore.StorageCost, 
    result *internalpb.SearchResults, _ int) segcore.StorageCost {
    acc.ScannedRemoteBytes += result.GetScannedRemoteBytes()
    acc.ScannedTotalBytes += result.GetScannedTotalBytes()
    return acc
}, segcore.StorageCost{})

高级搜索（Advanced Search）

1. ResultInfo.isAdvance 的作用

ResultInfo.isAdvance 用于标识是否是高级搜索（Hybrid Search），决定在 QueryNode 层的结果归约策略。

核心作用

1
2
3
4
5
6
7
func ReduceSearchOnQueryNode(ctx context.Context, results []*internalpb.SearchResults, 
    info *reduce.ResultInfo) (*internalpb.SearchResults, error) {
    if info.GetIsAdvance() {
        return ReduceAdvancedSearchResults(ctx, results)
    }
    return ReduceSearchResults(ctx, results, info)
}

两种归约策略

1. 普通搜索（isAdvance = false）

使用 ReduceSearchResults：

  • 立即归约所有结果
  • 返回最终的 topK 结果
  • 适用于单一向量搜索
2. 高级搜索（isAdvance = true）

使用 ReduceAdvancedSearchResults：

  • 不立即归约，而是将子结果保存到 SubResults 中
  • 延迟到 Proxy 层进行归约
  • 适用于混合搜索（Hybrid Search），包含多个子搜索请求
  • 需要在 Proxy 层进行特殊的归约逻辑（如 rerank）

ReduceAdvancedSearchResults 实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
func ReduceAdvancedSearchResults(ctx context.Context, 
    results []*internalpb.SearchResults) (*internalpb.SearchResults, error) {
    
    searchResults := &internalpb.SearchResults{
        IsAdvanced: true,
    }
    
    // 不归约，直接追加子结果
    for index, result := range results {
        subResult := &internalpb.SubSearchResults{
            MetricType:     result.GetMetricType(),
            NumQueries:     result.GetNumQueries(),
            TopK:           result.GetTopK(),
            SlicedBlob:     result.GetSlicedBlob(),
            SlicedNumCount: result.GetSlicedNumCount(),
            SlicedOffset:   result.GetSlicedOffset(),
            ReqIndex:       int64(index),
        }
        searchResults.SubResults = append(searchResults.SubResults, subResult)
    }
    
    return searchResults, nil
}

完整流程总结

1. 搜索流程时序图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
┌─────────┐
│  Proxy  │
└────┬────┘
     │ 1. SearchRequest
     ▼
┌─────────────┐
│ QueryNode  │
└─────┬───────┘
      │ 2. SearchTask.Execute
      ▼
┌─────────────────┐
│ SearchTask      │
│ - combinePlaceHolderGroups
│ - NewSearchRequest
└─────┬───────────┘
      │ 3. SearchHistorical/SearchStreaming
      ▼
┌─────────────────┐
│ searchSegments  │
│ - 并发搜索多个 segments
└─────┬───────────┘
      │ 4. Segment.Search
      ▼
┌─────────────────┐
│ Segment.Search  │
│ - check_search
│ - ExecPlanNodeVisitor
└─────┬───────────┘
      │ 5. ExecuteTask
      ▼
┌─────────────────┐
│ Plan Nodes      │
│ - MvccNode (MVCC 过滤)
│ - VectorSearchNode (向量搜索 + TopK)
│ - FilterNode (表达式过滤)
│ - GroupByNode (Group By)
└─────┬───────────┘
      │ 6. SearchResult (局部 topK)
      ▼
┌─────────────────┐
│ ReduceSearchResults │
│ - K-Way Merge
│ - 去重
│ - Group By
│ - 成本聚合
└─────┬───────────┘
      │ 7. 全局 topK 结果
      ▼
┌─────────┐
│ Result  │
└─────────┘

2. 关键数据流

SearchRequest 创建

1
2
3
4
5
6
7
8
9
QueryRequest (protobuf)
  ↓
SerializedExprPlan (bytes)
  ↓
createSearchPlanByExpr
  ↓
SearchPlan (C++)
  ↓
SearchRequest (Go wrapper)

Segment Search 执行

1
2
3
4
5
6
7
8
9
10
11
SearchRequest
  ↓
Plan (包含 plan_node_)
  ↓
ExecPlanNodeVisitor.visit(VectorPlanNode)
  ↓
PlanFragment (执行计划节点树)
  ↓
ExecuteTask
  ↓
SearchResult (局部 topK)

Result Reduce

1
2
3
4
5
6
7
8
9
多个 SearchResult (局部 topK)
  ↓
DecodeSearchResults
  ↓
ReduceSearchResultData (K-Way Merge)
  ↓
EncodeSearchResultData
  ↓
SearchResults (全局 topK)

3. 性能考虑

时间复杂度

  • Segment Search：O(N × log K)，其中 N 是 segment 内的数据量，K 是 topK
  • Reduce：O(M × K)，其中 M 是 segment 数量，K 是 topK

由于 M（segment 数量）通常远小于 N（数据量），Reduce 的开销相对较小。

优化策略

  1. 短路优化：如果只有一个 segment 的结果，直接返回
  2. 并发搜索：多个 segments 并发搜索
  3. 流式处理：使用 StreamingSearchTask 进行流式归约
  4. 内存限制：检查结果大小，避免 OOM

4. 关键要点总结

Segment Search 层面

✅ 每个 segment 的 Search 已经完成了：

  • MVCC 过滤（时间戳和删除过滤）
  • TopK 选择（向量搜索）
  • Group By（如果启用）
  • 表达式过滤（如果有）

✅ 但返回的是局部最优结果，只代表该 segment 内的 topK

Reduce 层面

✅ Reduce 通过 K-Way Merge 算法合并多个 segment 的结果：

  • 选择全局最优的 topK
  • 去除跨 segment 的重复 entity
  • 处理全局的 group by
  • 聚合成本信息

✅ 最终得到全局最优的 topK 结果

类比理解

  • Segment Search：每个班级选出前 10 名
  • Reduce：从所有班级的前 10 名中，选出全校前 10 名

即使每个班级已经完成了排名，仍然需要全校级别的 Reduce 操作来选出最终的 topK。

参考资料

]]> <h2 id="目录"><a href="#目录" class="headerlink" title="目录"></a>目录</h2><ol> <li><a href="#%E6%A6%82%E8%BF%B0">概述</a></li> <li><a href="#%E6%90%9 Milvus 为什么需要对 Search Result 进行 Reduce https://szza.github.io/2025/08/10/Milvus/18_why_reduce_search_results/ 2025-08-10T07:00:00.000Z 2026-01-06T13:10:50.533Z 概述

在 Milvus 的搜索流程中，虽然每个 segment 在 segment->Search 中已经完成了 MVCC 过滤、topK 选择、group by 等操作，但仍然需要对多个 segment 的搜索结果进行 Reduce（归约）操作。本文档详细解释为什么需要 Reduce 以及 Reduce 的具体作用。

核心原因：数据分布与全局 TopK

核心问题：一个查询请求通常涉及多个 segments，每个 segment 只返回自己数据范围内的 topK 结果，但用户需要的是全局最优的 topK。

1. 多个 Segments 的场景

在 Milvus 中，一个 collection 的数据可能分布在：

  • 多个 Sealed Segments：历史数据被分割成多个 sealed segments
  • 多个 Growing Segments：实时写入的数据存储在 growing segments 中
  • 多个 Shards：在分布式场景中，数据分布在多个 shards 上
  • 多个 QueryNodes：在分布式部署中，不同的 segments 可能位于不同的 QueryNode 上

示例场景

假设一个 collection 有 1000 万条数据，被分割成：

  • Segment 1: 300 万条（sealed）
  • Segment 2: 300 万条（sealed）
  • Segment 3: 300 万条（sealed）
  • Segment 4: 100 万条（growing）

当用户请求 topK=10 时，每个 segment 都会返回自己的 topK=10，但我们需要的是从这 4000 万条数据中选出全局最优的 topK=10。

2. 每个 Segment 返回的是局部 TopK

Segment Search 的执行流程

每个 segment 在执行 segment->Search 时：

1
2
3
4
5
6
7
8
9
10
11
12
13
std::unique_ptr<SearchResult>
SegmentInternalInterface::Search(
    const query::Plan* plan,
    const query::PlaceholderGroup* placeholder_group,
    Timestamp timestamp,
    const folly::CancellationToken& cancel_token,
    int32_t consistency_level,
    Timestamp collection_ttl) const {
    // ... 执行搜索计划节点树
    // 包括：MVCC 过滤、向量搜索、topK 选择、group by 等
    *results = visitor.get_moved_result(*plan->plan_node_);
    return results;
}

Segment 返回的结果结构

每个 segment 的 SearchResult 包含：

  • seg_offsets_：该 segment 内的 topK 偏移量（已排序）
  • distances_：该 segment 内的 topK 距离值（已排序）
  • group_by_values_：group by 的值（如果启用）
  • topk_per_nq_prefix_sum_：每个查询的 topK 前缀和

关键点：这些结果是局部最优的，只代表该 segment 内的 topK，不代表全局最优。

3. Reduce 的作用：K-Way Merge 算法

Reduce 操作使用多路归并（K-Way Merge）算法，从多个已排序的结果中选择全局最优的 topK。

算法原理

Reduce 算法的核心思想类似于归并排序的归并阶段：

  1. 多路指针：为每个 segment 的结果维护一个指针（offset）
  2. 比较选择：每次比较所有 segment 当前指针位置的值
  3. 选择最优：选择当前最大的 score，移动对应 segment 的指针
  4. 去重处理：如果遇到重复的 entity ID，跳过
  5. 重复直到 topK：重复上述过程直到选出全局 topK 个结果

代码实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
func (scr *SearchCommonReduce) ReduceSearchResultData(
    ctx context.Context, 
    searchResultData []*schemapb.SearchResultData, 
    info *reduce.ResultInfo) (*schemapb.SearchResultData, error) {
    
    // 为每个 segment 的结果维护偏移量
    offsets := make([]int64, len(searchResultData))
    idSet := make(map[interface{}]struct{})  // 用于去重
    
    for i := int64(0); i < info.GetNq(); i++ {
        var j int64
        for j = 0; j < info.GetTopK(); {
            // 从所有 segment 中选择当前最高分
            sel := SelectSearchResultData(searchResultData, resultOffsets, offsets, i)
            if sel == -1 {
                break
            }
            
            idx := resultOffsets[sel][i] + offsets[sel]
            id := typeutil.GetPK(searchResultData[sel].GetIds(), idx)
            score := searchResultData[sel].Scores[idx]
            
            // 去重：跳过已存在的 entity
            if _, ok := idSet[id]; !ok {
                // 添加到最终结果
                retSize += typeutil.AppendFieldData(ret.FieldsData, 
                    searchResultData[sel].FieldsData, idx)
                typeutil.AppendPKs(ret.Ids, id)
                ret.Scores = append(ret.Scores, score)
                idSet[id] = struct{}{}
                j++
            } else {
                skipDupCnt++  // 跳过重复的 entity
            }
            offsets[sel]++  // 移动指针
        }
        ret.Topks = append(ret.Topks, j)
    }
    return ret, nil
}

SelectSearchResultData 函数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
func SelectSearchResultData(
    dataArray []*schemapb.SearchResultData, 
    resultOffsets [][]int64, 
    offsets []int64, 
    qi int64) int {
    
    var sel = -1
    var maxDistance = -float32(math.MaxFloat32)
    
    // 遍历所有 segment，找到当前最高分
    for i, offset := range offsets {
        if offset >= dataArray[i].Topks[qi] {
            continue  // 该 segment 的结果已用完
        }
        
        idx := resultOffsets[i][qi] + offset
        distance := dataArray[i].Scores[idx]
        
        if distance > maxDistance {
            sel = i
            maxDistance = distance
        }
    }
    return sel
}

4. 示例说明

假设有 3 个 segments，每个返回 topK=10，用户请求全局 topK=10：

Segment 结果（已排序）

1
2
3
Segment 1: [0.95, 0.90, 0.85, 0.80, 0.75, ...] (10个结果)
Segment 2: [0.92, 0.88, 0.82, 0.78, 0.73, ...] (10个结果)
Segment 3: [0.89, 0.87, 0.80, 0.76, 0.71, ...] (10个结果)

Reduce 过程

步骤Segment 1 指针Segment 2 指针Segment 3 指针选择全局结果
10 (0.95)0 (0.92)0 (0.89)Seg1[0.95]
21 (0.90)0 (0.92)0 (0.89)Seg2[0.95, 0.92]
31 (0.90)1 (0.88)0 (0.89)Seg1[0.95, 0.92, 0.90]
42 (0.85)1 (0.88)0 (0.89)Seg3[0.95, 0.92, 0.90, 0.89]
52 (0.85)1 (0.88)1 (0.87)Seg2[0.95, 0.92, 0.90, 0.89, 0.88]
………………
10…………[全局 topK=10]

结果：最终得到全局最优的 topK=10 个结果。

5. Reduce 的其他重要作用

5.1 去重（Deduplication）

同一个 entity 可能同时出现在多个 segments 中：

  • Growing + Sealed：新写入的数据在 growing segment，但可能还未 flush 到 sealed segment
  • Compaction：compaction 过程中，数据可能同时存在于新旧 segments
  • 多副本：在分布式场景中，可能存在数据副本

Reduce 通过 idSet 确保每个 entity 只出现一次：

1
2
3
4
5
6
7
idSet := make(map[interface{}]struct{})
if _, ok := idSet[id]; !ok {
    // 添加到结果
    idSet[id] = struct{}{}
} else {
    skipDupCnt++  // 跳过重复
}

5.2 Group By 处理

如果有 group by 需求，Reduce 阶段会进行全局的 group by 处理：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func (sbr *SearchGroupByReduce) ReduceSearchResultData(...) {
    // 1. 按 group by 值分组
    groupByValueMap := make(map[interface{}]int64)
    
    // 2. 为每个 group 选择 topK
    for j = 0; j < groupBound; {
        // 选择当前最高分
        sel := SelectSearchResultData(...)
        groupByVal := groupByValIterator[sel](idx)
        
        // 3. 检查 group 限制
        if groupCount >= groupSize {
            // 跳过：该 group 已满
        } else {
            // 添加到该 group
            groupByValueMap[groupByVal]++
        }
    }
}

5.3 成本聚合

Reduce 还会聚合各个 segment 的存储扫描成本：

1
2
3
4
5
6
storageCost := lo.Reduce(results, func(acc segcore.StorageCost, 
    result *internalpb.SearchResults, _ int) segcore.StorageCost {
    acc.ScannedRemoteBytes += result.GetScannedRemoteBytes()
    acc.ScannedTotalBytes += result.GetScannedTotalBytes()
    return acc
}, segcore.StorageCost{})

6. 性能考虑

时间复杂度

  • Segment Search：O(N × log K)，其中 N 是 segment 内的数据量，K 是 topK
  • Reduce：O(M × K)，其中 M 是 segment 数量，K 是 topK

由于 M（segment 数量）通常远小于 N（数据量），Reduce 的开销相对较小。

优化策略

  1. 短路优化：如果只有一个 segment 的结果，直接返回，无需 Reduce

    1
    2
    3
    if len(results) == 1 {
        return results[0], nil
    }

  2. 并行处理：对于多个查询（nq > 1），可以并行处理每个查询的 Reduce

  3. 内存限制：检查结果大小，避免 OOM

    1
    2
    3
    if retSize > maxOutputSize {
        return nil, fmt.Errorf("search results exceed the maxOutputSize Limit")
    }

7. 总结

为什么需要 Reduce？

  1. 数据分布：数据分布在多个 segments 中
  2. 局部 vs 全局：每个 segment 返回局部 topK，用户需要全局 topK
  3. 去重需求：需要去除跨 segment 的重复 entity
  4. Group By：需要全局的 group by 处理
  5. 成本聚合：需要聚合各个 segment 的成本信息

关键要点

  • ✅ 每个 segment 的 Search 已经完成了 MVCC、topK、group by 等操作
  • ✅ 但返回的是局部最优结果
  • ✅ Reduce 通过 K-Way Merge 算法合并多个 segment 的结果
  • ✅ 最终得到全局最优的 topK 结果
  • ✅ 同时处理去重、group by、成本聚合等逻辑

类比理解

可以类比为：

  • Segment Search：每个班级选出前 10 名
  • Reduce：从所有班级的前 10 名中，选出全校前 10 名

即使每个班级已经完成了排名，仍然需要全校级别的 Reduce 操作来选出最终的 topK。

参考资料

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>在 Milvus 的搜索流程中，虽然每个 segment 在 <code>segment-&gt;Search</code> 中已经完成了 Milvus organizeSubTask 函数详细分析 https://szza.github.io/2025/08/10/Milvus/17_organize_subtask_analysis/ 2025-08-10T06:00:00.000Z 2026-01-06T13:10:49.877Z 本文档深入分析 organizeSubTask 函数的实现细节，这是 QueryNode delegator 中负责组织和分发子任务的核心函数。

函数签名

1
2
3
4
5
6
7
8
9
func organizeSubTask[T any](
    ctx context.Context,
    req T,
    sealed []SnapshotItem,
    growing []SegmentEntry,
    sd *shardDelegator,
    skipEmpty bool,
    modify func(T, querypb.DataScope, []int64, int64) T,
) ([]subTask[T], error)

位置: internal/querynodev2/delegator/delegator.go:751

函数职责

organizeSubTask 是一个泛型函数，负责将查询/搜索请求组织成多个子任务，每个子任务对应一组需要在特定节点上查询的 segments。

参数说明

参数类型说明
ctxcontext.Context上下文，用于取消和超时控制
reqT (泛型)原始请求，可以是 QueryRequest、SearchRequest 或 GetStatisticsRequest
sealed[]SnapshotItemsealed segments 分布快照，按节点分组
growing[]SegmentEntrygrowing segments 列表（通常在本地节点）
sd*shardDelegatorshard delegator 实例，提供 workerManager 等资源
skipEmptybool是否跳过空的子任务（没有 segments）
modifyfunc(...)修改请求的回调函数，为每个子任务定制请求参数

返回值

  • []subTask[T]: 子任务列表，每个子任务包含请求、目标节点 ID 和 worker 客户端
  • error: 错误信息（当前实现总是返回 nil）

核心数据结构

subTask

1
2
3
4
5
type subTask[T any] struct {
    req      T              // 修改后的请求（包含特定的 segmentIDs 和 targetID）
    targetID int64          // 目标节点 ID
    worker   cluster.Worker // Worker 客户端（可能为 nil 如果节点不可用）
}

SnapshotItem

1
2
3
4
type SnapshotItem struct {
    NodeID   int64           // 节点 ID
    Segments []SegmentEntry  // 该节点上的 segments
}

说明: SnapshotItem 表示某个节点上的 sealed segments 分组。

SegmentEntry

1
2
3
4
5
6
7
8
9
type SegmentEntry struct {
    NodeID        int64                // 节点 ID
    SegmentID     UniqueID             // Segment ID
    PartitionID   UniqueID             // Partition ID
    Version       int64                // Segment 版本
    TargetVersion int64                // 目标版本
    Level         datapb.SegmentLevel  // Segment 级别（L0, L1 等）
    Offline       bool                 // 是否离线
}

执行流程详解

1. 初始化结果列表 (Line 760)

1
2
log := sd.getLogger(ctx)
result := make([]subTask[T], 0, len(sealed)+1)
  • 容量预分配: len(sealed)+1
    • len(sealed): 每个 sealed snapshot 一个任务
    • +1: growing segments 一个任务

2. 定义 packSubTask 闭包函数 (Lines 762-788)

packSubTask 是核心的任务打包函数，负责为一组 segments 创建子任务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
packSubTask := func(segments []SegmentEntry, workerID int64, scope querypb.DataScope) error {
    // 步骤 1: 提取 segment IDs
    segmentIDs := lo.Map(segments, func(item SegmentEntry, _ int) int64 {
        return item.SegmentID
    })
    
    // 步骤 2: 跳过空任务（可选）
    if skipEmpty && len(segmentIDs) == 0 {
        return nil
    }
    
    // 步骤 3: 修改请求
    req := modify(req, scope, segmentIDs, workerID)
    
    // 步骤 4: 获取 worker（容错）
    worker, err := sd.workerManager.GetWorker(ctx, workerID)
    if err != nil {
        log.Warn("failed to get worker for sub task",
            zap.Int64("nodeID", workerID),
            zap.Int64s("segments", segmentIDs),
            zap.Error(err),
        )
        // 注意：即使获取 worker 失败，仍然创建任务
    }
    
    // 步骤 5: 创建并添加子任务
    result = append(result, subTask[T]{
        req:      req,
        targetID: workerID,
        worker:   worker,  // 可能为 nil
    })
    return nil
}

packSubTask 的关键特性

  1. Segment IDs 提取: 使用 lo.Map 提取所有 segment IDs
  2. 空任务处理: 根据 skipEmpty 决定是否跳过没有 segments 的任务
  3. 请求定制: 通过 modify 函数为每个子任务定制请求参数
  4. 容错设计: 即使 worker 获取失败，仍然创建任务（worker 为 nil），留给后续的 executeSubTasks 处理

3. 处理 Sealed Segments (Lines 790-795)

1
2
3
4
5
6
for _, entry := range sealed {
    err := packSubTask(entry.Segments, entry.NodeID, querypb.DataScope_Historical)
    if err != nil {
        return nil, err
    }
}

逻辑:

  • 遍历每个 SnapshotItem（每个代表一个节点上的 sealed segments）
  • 为每个节点创建一个子任务
  • Scope: DataScope_Historical（历史数据）
  • Worker ID: entry.NodeID（远程节点）

示例:

1
2
3
4
5
6
7
8
9
10
sealed = [
    {NodeID: 1, Segments: [seg1, seg2, seg3]},
    {NodeID: 2, Segments: [seg4, seg5]},
    {NodeID: 3, Segments: [seg6]},
]

生成 3 个子任务:
- Task 1: NodeID=1, SegmentIDs=[seg1, seg2, seg3], Scope=Historical
- Task 2: NodeID=2, SegmentIDs=[seg4, seg5], Scope=Historical
- Task 3: NodeID=3, SegmentIDs=[seg6], Scope=Historical

4. 处理 Growing Segments (Line 797)

1
packSubTask(growing, paramtable.GetNodeID(), querypb.DataScope_Streaming)

逻辑:

  • 所有 growing segments 在一个子任务中
  • Scope: DataScope_Streaming（流式数据）
  • Worker ID: paramtable.GetNodeID()（本地节点）
  • Growing segments 总是在当前节点（leader）上

为什么在本地节点:

  • Growing segments 是正在写入的数据
  • 只有 shard leader（当前 delegator 所在节点）负责 growing segments
  • 不会分布到其他节点

5. 返回结果 (Line 799)

1
return result, nil

返回所有创建的子任务。

modify 函数详解

modify 函数是一个回调函数，用于为每个子任务定制请求参数。不同的操作类型有不同的实现。

Query 操作的 modify 函数

函数: shardDelegator.modifyQueryRequest (line 292)

1
2
3
4
5
6
7
8
9
10
11
12
13
func (sd *shardDelegator) modifyQueryRequest(
    req *querypb.QueryRequest, 
    scope querypb.DataScope, 
    segmentIDs []int64, 
    targetID int64,
) *querypb.QueryRequest {
    nodeReq := proto.Clone(req).(*querypb.QueryRequest)
    nodeReq.Scope = scope                      // 设置 scope
    nodeReq.Req.Base.TargetID = targetID        // 设置目标节点
    nodeReq.SegmentIDs = segmentIDs             // 设置要查询的 segments
    nodeReq.DmlChannels = []string{sd.vchannelName}
    return nodeReq
}

Search 操作的 modify 函数

函数: shardDelegator.modifySearchRequest (line 280)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
func (sd *shardDelegator) modifySearchRequest(
    req *querypb.SearchRequest, 
    scope querypb.DataScope, 
    segmentIDs []int64, 
    targetID int64,
) *querypb.SearchRequest {
    nodeReq := &querypb.SearchRequest{
        DmlChannels:     []string{sd.vchannelName},
        SegmentIDs:      segmentIDs,
        Scope:           scope,
        Req:             sd.shallowCopySearchRequest(req.GetReq(), targetID),
        FromShardLeader: req.FromShardLeader,
        TotalChannelNum: req.TotalChannelNum,
    }
    return nodeReq
}

GetStatistics 操作的 modify 函数

使用: 内联定义 (line 717)

1
2
3
4
5
6
7
8
func(req *querypb.GetStatisticsRequest, scope querypb.DataScope, segmentIDs []int64, targetID int64) *querypb.GetStatisticsRequest {
    nodeReq := proto.Clone(req).(*querypb.GetStatisticsRequest)
    nodeReq.GetReq().GetBase().TargetID = targetID
    nodeReq.Scope = scope
    nodeReq.SegmentIDs = segmentIDs
    nodeReq.FromShardLeader = true
    return nodeReq
}

Worker 获取机制

WorkerManager.GetWorker

位置: internal/querynodev2/cluster/manager.go:47

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
func (m *grpcWorkerManager) GetWorker(ctx context.Context, nodeID int64) (Worker, error) {
    // 1. 尝试从缓存获取
    worker, ok := m.workers.Get(nodeID)
    var err error
    
    // 2. 如果不存在，使用 singleflight 创建（防止重复创建）
    if !ok {
        worker, err, _ = m.sf.Do(strconv.FormatInt(nodeID, 10), func() (Worker, error) {
            // 使用 builder 创建 worker
            worker, err = m.builder(ctx, nodeID)
            if err != nil {
                return nil, err
            }
            
            // 插入缓存（如果已存在则使用已有的）
            old, exist := m.workers.GetOrInsert(nodeID, worker)
            if exist {
                worker.Stop()
                worker = old
            }
            return worker, nil
        })
        if err != nil {
            return nil, err
        }
    }
    
    // 3. 检查 worker 健康状态
    if !worker.IsHealthy() {
        return nil, fmt.Errorf("node is not healthy: %d", nodeID)
    }
    
    return worker, nil
}

特性:

  • 缓存机制: 复用已创建的 worker
  • Singleflight: 防止并发创建同一个 worker
  • 健康检查: 确保 worker 可用

Worker 类型

本地 Worker (LocalWorker)

1
2
3
4
// 当 nodeID == 当前节点 ID 时创建
if nodeID == node.GetNodeID() {
    return NewLocalWorker(node), nil
}
  • 直接调用本地 QueryNode 方法
  • 无网络开销

远程 Worker (RemoteWorker)

1
2
3
4
// 远程节点
return cluster.NewPoolingRemoteWorker(func() (types.QueryNodeClient, error) {
    return grpcquerynodeclient.NewClient(node.ctx, addr, nodeID)
})
  • 通过 gRPC 调用远程 QueryNode
  • 支持连接池（WorkerPoolingSize 配置）
  • 使用 round-robin 选择连接

Worker 接口:

1
2
3
4
5
6
7
8
9
10
11
type Worker interface {
    LoadSegments(context.Context, *querypb.LoadSegmentsRequest) error
    ReleaseSegments(context.Context, *querypb.ReleaseSegmentsRequest) error
    SearchSegments(ctx context.Context, req *querypb.SearchRequest) (*internalpb.SearchResults, error)
    QuerySegments(ctx context.Context, req *querypb.QueryRequest) (*internalpb.RetrieveResults, error)
    QueryStreamSegments(ctx context.Context, req *querypb.QueryRequest, srv streamrpc.QueryStreamServer) error
    GetStatistics(ctx context.Context, req *querypb.GetStatisticsRequest) (*internalpb.GetStatisticsResponse, error)
    // ...
    IsHealthy() bool
    Stop()
}

使用场景

1. Query 操作

1
tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, true, sd.modifyQueryRequest)
  • 用于普通查询操作
  • skipEmpty = true: 跳过没有 segments 的任务

2. QueryStream 操作

1
tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, true, sd.modifyQueryRequest)
  • 用于流式查询操作
  • 与普通查询使用相同的逻辑

3. Search 操作

1
tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, true, sd.modifySearchRequest)
  • 用于向量搜索操作
  • 使用 modifySearchRequest 定制请求

4. GetStatistics 操作

1
2
3
4
tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, true, 
    func(req *querypb.GetStatisticsRequest, scope querypb.DataScope, segmentIDs []int64, targetID int64) *querypb.GetStatisticsRequest {
        // 内联定制函数
    })
  • 用于获取统计信息
  • 使用内联函数定制请求

5. UpdateSchema 操作

1
2
3
4
5
tasks, err := organizeSubTask(ctx, &querypb.UpdateSchemaRequest{...}, 
    sealed, growing, sd, false,  // skipEmpty = false
    func(...) *querypb.UpdateSchemaRequest {
        // 定制函数
    })
  • 用于更新 schema
  • skipEmpty = false: 即使没有 segments 也创建任务（需要通知所有节点）

设计优势

1. 泛型设计

1
func organizeSubTask[T any](...)
  • 类型安全: 编译时类型检查
  • 代码复用: 同一函数支持多种请求类型
  • 灵活性: 通过 modify 函数定制不同类型的请求

2. 容错设计

1
2
3
4
5
worker, err := sd.workerManager.GetWorker(ctx, workerID)
if err != nil {
    log.Warn("failed to get worker for sub task", ...)
    // 继续创建任务，worker 为 nil
}
  • 即使 worker 不可用，仍然创建任务
  • 让后续的 executeSubTasks 决定如何处理（部分结果 vs 完全失败）

3. 关注点分离

  • organizeSubTask: 只负责组织任务，不执行
  • executeSubTasks: 负责执行任务和结果收集
  • modify 函数: 负责请求定制

4. 批量操作

  • 将同一节点上的所有 segments 组织到一个任务中
  • 减少 RPC 调用次数
  • 提高网络效率

性能考虑

1. 预分配容量

1
result := make([]subTask[T], 0, len(sealed)+1)

减少内存重新分配。

2. Worker 缓存

  • WorkerManager 缓存已创建的 worker
  • 避免重复建立 gRPC 连接

3. 连接池

1
poolSize := paramtable.Get().QueryNodeCfg.WorkerPoolingSize.GetAsInt()
  • 每个远程 worker 维护多个 gRPC 连接
  • Round-robin 选择连接，提高并发性能

4. 本地优化

1
2
3
if nodeID == node.GetNodeID() {
    return NewLocalWorker(node), nil
}
  • 本地 worker 直接调用，无网络开销

错误处理

Worker 获取失败

1
2
3
4
if err != nil {
    log.Warn("failed to get worker for sub task", ...)
    // 不返回错误，继续创建任务
}

策略: 延迟错误处理

  • 在 organizeSubTask 阶段只记录警告
  • 在 executeSubTasks 阶段根据部分结果策略决定是否失败

空 Segment 列表

1
2
3
if skipEmpty && len(segmentIDs) == 0 {
    return nil  // 跳过任务
}

场景:

  • 某个节点上没有需要查询的 segments
  • 根据 skipEmpty 参数决定是否创建任务

完整示例

输入

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
sealed = [
    {NodeID: 1, Segments: [
        {SegmentID: 101, PartitionID: 1},
        {SegmentID: 102, PartitionID: 1},
    ]},
    {NodeID: 2, Segments: [
        {SegmentID: 103, PartitionID: 2},
    ]},
]

growing = [
    {SegmentID: 201, NodeID: 0, PartitionID: 1},
    {SegmentID: 202, NodeID: 0, PartitionID: 2},
]

currentNodeID = 0

输出

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
tasks = [
    {
        req: QueryRequest{
            SegmentIDs: [101, 102],
            Scope: DataScope_Historical,
            TargetID: 1,
            DmlChannels: ["channel-1"],
        },
        targetID: 1,
        worker: RemoteWorker{nodeID: 1},
    },
    {
        req: QueryRequest{
            SegmentIDs: [103],
            Scope: DataScope_Historical,
            TargetID: 2,
            DmlChannels: ["channel-1"],
        },
        targetID: 2,
        worker: RemoteWorker{nodeID: 2},
    },
    {
        req: QueryRequest{
            SegmentIDs: [201, 202],
            Scope: DataScope_Streaming,
            TargetID: 0,
            DmlChannels: ["channel-1"],
        },
        targetID: 0,
        worker: LocalWorker{},
    },
]

总结

organizeSubTask 是一个设计精巧的泛型函数，具有以下特点：

  1. 高度抽象: 通过泛型和回调函数支持多种请求类型
  2. 容错健壮: 即使部分 worker 不可用也能创建任务
  3. 性能优化: 批量操作、连接池、本地优化
  4. 关注点分离: 只负责组织任务，不负责执行
  5. 易于扩展: 添加新的请求类型只需提供新的 modify 函数

该函数是 Milvus 查询系统中任务分发机制的核心组件，确保了查询能够高效、可靠地分发到多个节点并行执行。

]]> <p>本文档深入分析 <code>organizeSubTask</code> 函数的实现细节，这是 QueryNode delegator 中负责组织和分发子任务的核心函数。</p> <h2 id="函数签名"><a href="#函数签名" class="headerlink Milvus ShardDelegator.Query 方法详细分析 https://szza.github.io/2025/08/10/Milvus/16_shard_delegator_query_analysis/ 2025-08-10T05:00:00.000Z 2026-01-06T13:10:49.529Z 本文档深入分析 shardDelegator.Query 方法的实现细节，这是 QueryNode 中处理查询请求的核心方法。

方法签名

1
func (sd *shardDelegator) Query(ctx context.Context, req *querypb.QueryRequest) ([]*internalpb.RetrieveResults, error)

位置: internal/querynodev2/delegator/delegator.go:577

方法职责

shardDelegator.Query 负责在 shard 级别执行查询操作，它协调多个 segment 的查询，处理时间戳同步、segment 管理、任务分发和结果收集。

执行流程详解

1. 生命周期管理 (Lines 579-582)

1
2
3
4
if err := sd.lifetime.Add(sd.IsWorking); err != nil {
    return nil, err
}
defer sd.lifetime.Done()
  • 目的: 确保 delegator 处于工作状态
  • 机制: 使用 lifetime 管理器跟踪组件状态
  • 作用: 防止在 delegator 关闭或不可用时执行查询

2. Channel 验证 (Lines 584-589)

1
2
3
4
if !funcutil.SliceContain(req.GetDmlChannels(), sd.vchannelName) {
    log.Warn("delegator received query request not belongs to it", ...)
    return nil, fmt.Errorf("dml channel not match, ...")
}
  • 目的: 验证请求的 channel 是否属于当前 delegator
  • 原因: 每个 delegator 只负责一个特定的 virtual channel
  • 错误处理: 如果不匹配，立即返回错误

3. 优化 Guarantee Timestamp (Lines 591-597)

1
2
3
4
5
6
7
req.Req.GuaranteeTimestamp = sd.speedupGuranteeTS(
    ctx,
    req.Req.GetConsistencyLevel(),
    req.Req.GetGuaranteeTimestamp(),
    req.Req.GetMvccTimestamp(),
    req.Req.GetIsIterator(),
)

speedupGuranteeTS 方法 (line 918):

1
2
3
4
5
6
7
8
9
10
11
12
func (sd *shardDelegator) speedupGuranteeTS(...) uint64 {
    // 如果不是 Strong 一致性或已设置 mvccTS，直接返回原值
    if isIterator || cl != commonpb.ConsistencyLevel_Strong || mvccTS != 0 {
        return guaranteeTS
    }
    // 使用 WAL 的 MVCC timestamp 来加速 Strong 一致性查询
    if mvcc, err := streaming.WAL().Local().GetLatestMVCCTimestampIfLocal(ctx, sd.vchannelName); 
       err == nil && mvcc < guaranteeTS {
        return mvcc
    }
    return guaranteeTS
}
  • 优化原理: 对于 Strong 一致性查询，如果 WAL 的 MVCC timestamp 小于 guarantee timestamp，可以使用更小的值来加速查询
  • 适用场景:
    • 一致性级别为 Strong
    • 不是 iterator 模式
    • 未设置 mvccTS
  • 效果: 减少等待时间，提高查询性能

4. 等待 tSafe (Lines 599-621)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
partialResultRequiredDataRatio := paramtable.Get().QueryNodeCfg.PartialResultRequiredDataRatio.GetAsFloat()
waitTr := timerecord.NewTimeRecorder("wait tSafe")
var tSafe uint64
var err error
if partialResultRequiredDataRatio >= 1.0 {
    // 需要完整结果，必须等待 tSafe
    tSafe, err = sd.waitTSafe(ctx, req.Req.GuaranteeTimestamp)
    if err != nil {
        return nil, err
    }
    if req.GetReq().GetMvccTimestamp() == 0 {
        req.Req.MvccTimestamp = tSafe
    }
} else {
    // 允许部分结果，使用当前 tSafe 即可
    if req.GetReq().GetMvccTimestamp() == 0 {
        req.Req.MvccTimestamp = sd.GetTSafe()
    }
}

waitTSafe 方法 (line 939):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
func (sd *shardDelegator) waitTSafe(ctx context.Context, ts uint64) (uint64, error) {
    // 如果已经满足条件，直接返回
    latestTSafe := sd.latestTsafe.Load()
    if latestTSafe >= ts {
        return latestTSafe, nil
    }
    
    // 检查是否启用降级模式
    if paramtable.Get().QueryNodeCfg.DowngradeTsafe.GetAsBool() {
        return latestTSafe, nil
    }
    
    // 检查时间戳延迟是否过大
    lag := gt.Sub(st)
    maxLag := paramtable.Get().QueryNodeCfg.MaxTimestampLag.GetAsDuration(time.Second)
    if lag > maxLag {
        return 0, WrapErrTsLagTooLarge(lag, maxLag)
    }
    
    // 等待 tSafe 更新
    ch := make(chan struct{})
    go func() {
        sd.tsCond.L.Lock()
        defer sd.tsCond.L.Unlock()
        for sd.latestTsafe.Load() < ts && ctx.Err() == nil && sd.Serviceable() {
            sd.tsCond.Wait()
        }
        close(ch)
    }()
    
    // 监听超时或完成信号
    select {
    case <-ctx.Done():
        sd.tsCond.Broadcast()
        return 0, ctx.Err()
    case <-ch:
        return sd.latestTsafe.Load(), nil
    }
}

关键点:

  • tSafe (Time Safe): 表示数据已经安全可读的时间戳
  • 等待机制: 使用条件变量 (tsCond) 等待 tSafe 更新
  • 部分结果模式:
    • partialResultRequiredDataRatio >= 1.0: 必须等待完整数据，保证强一致性
    • partialResultRequiredDataRatio < 1.0: 允许部分结果，使用当前 tSafe，降低延迟
  • 超时处理: 检查时间戳延迟，如果超过 MaxTimestampLag 则返回错误
  • 降级模式: 如果启用 DowngradeTsafe，直接返回当前 tSafe，不等待

5. Pin Readable Segments (Lines 623-628)

1
2
3
4
5
6
7
sealed, growing, sealedRowCount, version, err := sd.distribution.PinReadableSegments(
    partialResultRequiredDataRatio, 
    req.GetReq().GetPartitionIDs()...)
if err != nil {
    return nil, err
}
defer sd.distribution.Unpin(version)

PinReadableSegments 方法 (distribution.go:162):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
func (d *distribution) PinReadableSegments(requiredLoadRatio float64, partitions ...int64) 
    (sealed []SnapshotItem, growing []SegmentEntry, sealedRowCount map[int64]int64, version int64, err error) {
    
    requireFullResult := requiredLoadRatio >= 1.0
    loadRatioSatisfy := d.queryView.GetLoadedRatio() >= requiredLoadRatio
    
    var isServiceable bool
    if requireFullResult {
        isServiceable = d.queryView.Serviceable()
    } else {
        isServiceable = loadRatioSatisfy
    }
    
    if !isServiceable {
        return nil, nil, nil, -1, merr.WrapErrChannelNotAvailable(...)
    }
    
    // 验证 partition 是否已加载
    for _, partition := range partitions {
        if !current.partitions.Contain(partition) {
            return nil, nil, nil, -1, merr.WrapErrPartitionNotLoaded(partition)
        }
    }
    
    // 获取 segments
    sealed, growing = current.Get(partitions...)
    version = current.version
    
    // 根据加载比例过滤 segments
    if d.queryView.GetLoadedRatio() == 1.0 {
        // 完全加载：使用 target version 过滤
        targetVersion := current.GetTargetVersion()
        filterReadable := d.readableFilter(targetVersion)
        sealed, growing = d.filterSegments(sealed, growing, filterReadable)
    } else {
        // 部分加载：只返回已加载的 segments
        sealed = lo.Map(sealed, func(item SnapshotItem, _ int) SnapshotItem {
            return SnapshotItem{
                NodeID: item.NodeID,
                Segments: lo.Filter(item.Segments, func(entry SegmentEntry, _ int) bool {
                    return d.queryView.sealedSegmentRowCount[entry.SegmentID] > 0
                }),
            }
        })
        // 类似处理 growing segments
    }
    
    // Pin snapshot，防止被卸载
    snapshot, _ := d.snapshots.GetOrInsert(version, func() *snapshot {
        return current.Clone()
    })
    snapshot.AddRef()
    
    return sealed, growing, sealedRowCount, version, nil
}

关键概念:

  • Pin 操作: 增加 snapshot 的引用计数，防止 segment 在查询过程中被卸载
  • Snapshot: 某个时间点的 segment 分布快照
  • Sealed Segments: 已封存的 segments，数据不再变化
  • Growing Segments: 正在增长的 segments，数据可能还在变化
  • Serviceable: 检查 channel 是否可服务（所有必需的 segments 都已加载）
  • Load Ratio: 已加载的 segments 比例，用于部分结果模式

6. 处理 IgnoreGrowing 标志 (Lines 630-632)

1
2
3
if req.Req.IgnoreGrowing {
    growing = []SegmentEntry{}
}
  • 目的: 如果请求指定忽略 growing segments，则清空 growing 列表
  • 场景: 某些查询只需要查询历史数据，不需要最新的增量数据

7. Segment 剪枝 (Lines 634-640)

1
2
3
4
5
6
7
8
9
if paramtable.Get().QueryNodeCfg.EnableSegmentPrune.GetAsBool() {
    func() {
        sd.partitionStatsMut.RLock()
        defer sd.partitionStatsMut.RUnlock()
        PruneSegments(ctx, sd.partitionStats, nil, req.GetReq(), 
            sd.collection.Schema(), sealed, 
            PruneInfo{paramtable.Get().QueryNodeCfg.DefaultSegmentFilterRatio.GetAsFloat()})
    }()
}
  • 目的: 根据统计信息剪枝不相关的 segments
  • 原理: 使用 partition 统计信息（min/max 值）判断 segment 是否可能包含查询结果
  • 效果: 减少不必要的 segment 查询，提高性能
  • 线程安全: 使用读锁保护 partitionStats

8. 组织子任务 (Lines 648-652)

1
2
3
4
tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, true, sd.modifyQueryRequest)
if err != nil {
    return nil, err
}

organizeSubTask 方法 (line 751):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
func organizeSubTask[T any](ctx context.Context,
    req T,
    sealed []SnapshotItem,
    growing []SegmentEntry,
    sd *shardDelegator,
    skipEmpty bool,
    modify func(T, querypb.DataScope, []int64, int64) T,
) ([]subTask[T], error) {
    
    result := make([]subTask[T], 0, len(sealed)+1)
    
    packSubTask := func(segments []SegmentEntry, workerID int64, scope querypb.DataScope) error {
        segmentIDs := lo.Map(segments, func(item SegmentEntry, _ int) int64 {
            return item.SegmentID
        })
        if skipEmpty && len(segmentIDs) == 0 {
            return nil
        }
        
        // 修改请求，设置 scope、segmentIDs、targetID
        req := modify(req, scope, segmentIDs, workerID)
        
        // 获取 worker
        worker, err := sd.workerManager.GetWorker(ctx, workerID)
        if err != nil {
            log.Warn("failed to get worker for sub task", ...)
        }
        
        result = append(result, subTask[T]{
            req:      req,
            targetID: workerID,
            worker:   worker,
        })
        return nil
    }
    
    // 为每个 sealed snapshot 创建任务
    for _, entry := range sealed {
        packSubTask(entry.Segments, entry.NodeID, querypb.DataScope_Historical)
    }
    
    // 为 growing segments 创建任务（本地节点）
    packSubTask(growing, paramtable.GetNodeID(), querypb.DataScope_Streaming)
    
    return result, nil
}

modifyQueryRequest 方法 (line 292):

1
2
3
4
5
6
7
8
9
func (sd *shardDelegator) modifyQueryRequest(req *querypb.QueryRequest, 
    scope querypb.DataScope, segmentIDs []int64, targetID int64) *querypb.QueryRequest {
    nodeReq := proto.Clone(req).(*querypb.QueryRequest)
    nodeReq.Scope = scope                    // Historical 或 Streaming
    nodeReq.Req.Base.TargetID = targetID      // 目标节点 ID
    nodeReq.SegmentIDs = segmentIDs           // 要查询的 segment IDs
    nodeReq.DmlChannels = []string{sd.vchannelName}
    return nodeReq
}

关键点:

  • 任务分组: 将 segments 按节点分组，每个节点一个任务
  • Scope 区分:
    • DataScope_Historical: sealed segments
    • DataScope_Streaming: growing segments
  • Worker 管理: 通过 workerManager 获取 worker 客户端
  • 容错: 如果 worker 获取失败，任务仍然创建（用于部分结果模式）

9. 执行子任务 (Lines 654-661)

1
2
3
4
5
6
7
8
9
10
11
results, err := executeSubTasks(ctx, tasks, 
    NewRowCountBasedEvaluator(sealedRowCount), 
    func(ctx context.Context, req *querypb.QueryRequest, worker cluster.Worker) (*internalpb.RetrieveResults, error) {
        resp, err := worker.QuerySegments(ctx, req)
        status, ok := status.FromError(err)
        if ok && status.Code() == codes.Unavailable {
            sd.markSegmentOffline(req.GetSegmentIDs()...)
        }
        return resp, err
    }, 
    "Query", log)

executeSubTasks 方法 (line 802):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
func executeSubTasks[T any, R interface{ GetStatus() *commonpb.Status }](
    ctx context.Context, 
    tasks []subTask[T], 
    evaluator PartialResultEvaluator, 
    execute func(context.Context, T, cluster.Worker) (R, error), 
    taskType string, 
    log *log.MLogger,
) ([]R, error) {
    
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()
    
    // 确定部分结果要求
    var partialResultRequiredDataRatio float64
    if taskType == "Query" || taskType == "Search" {
        partialResultRequiredDataRatio = paramtable.Get().QueryNodeCfg.PartialResultRequiredDataRatio.GetAsFloat()
    } else {
        partialResultRequiredDataRatio = 1.0
    }
    
    // 并发执行所有任务
    wg, ctx := errgroup.WithContext(ctx)
    resultCh := make(chan channelResult, len(tasks))
    
    for _, task := range tasks {
        task := task // capture loop variable
        wg.Go(func() error {
            var result R
            var err error
            
            if task.targetID == -1 || task.worker == nil {
                // Worker 不可用
                err = fmt.Errorf("segments not loaded in any worker: %v", ...)
            } else {
                // 执行任务
                result, err = execute(ctx, task.req, task.worker)
                if result.GetStatus().GetErrorCode() != commonpb.ErrorCode_Success {
                    err = fmt.Errorf("worker(%d) query failed: %s", task.targetID, result.GetStatus().GetReason())
                }
            }
            
            if err != nil {
                log.Warn("failed to execute sub task", ...)
                // 如果禁用部分结果，立即失败
                if partialResultRequiredDataRatio == 1 {
                    return err
                }
            }
            
            // 发送结果到 channel
            resultCh <- channelResult{
                nodeID:   task.targetID,
                result:   result,
                err:      err,
                segments: req.GetSegmentIDs(),
            }
            return nil
        })
    }
    
    // 等待所有任务完成
    if err := wg.Wait(); err != nil {
        return nil, err
    }
    close(resultCh)
    
    // 收集结果
    successSegmentList := typeutil.NewSet[int64]()
    failureSegmentList := make([]int64, 0)
    var errors []error
    results := make([]R, 0, len(tasks))
    
    for item := range resultCh {
        if item.err == nil {
            successSegmentList.Insert(item.segments...)
            results = append(results, item.result)
        } else {
            failureSegmentList = append(failureSegmentList, item.segments...)
            errors = append(errors, item.err)
        }
    }
    
    // 如果全部成功，直接返回
    if len(errors) == 0 {
        return results, nil
    }
    
    // 使用 evaluator 判断是否返回部分结果
    if evaluator != nil {
        shouldReturnPartial, accessedDataRatio := evaluator(
            taskType, successSegmentList, failureSegmentList, errors)
        if shouldReturnPartial {
            log.Info("partial result executed successfully",
                zap.Float64("accessedDataRatio", accessedDataRatio),
                zap.Int64s("failureSegmentList", failureSegmentList),
            )
            return results, nil
        }
    }
    
    return nil, merr.Combine(errors...)
}

关键机制:

  • 并发执行: 使用 errgroup 并发执行所有子任务
  • 结果收集: 使用 buffered channel 收集结果
  • 错误处理:
    • 如果 partialResultRequiredDataRatio == 1.0，任何失败都会导致整体失败
    • 否则，使用 evaluator 评估是否可以返回部分结果
  • Segment 标记: 如果 worker 不可用，标记 segment 为 offline
  • Partial Result Evaluator: 根据成功访问的数据比例决定是否返回部分结果

RowCountBasedEvaluator:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
type RowCountBasedEvaluator struct {
    sealedRowCount map[int64]int64
}

func (e *RowCountBasedEvaluator) Evaluate(
    taskType string,
    successSegments typeutil.Set[int64],
    failureSegments []int64,
    errors []error,
) (shouldReturn bool, accessedDataRatio float64) {
    // 计算成功访问的行数
    successRows := 0
    for segID := range successSegments {
        successRows += e.sealedRowCount[segID]
    }
    
    // 计算总行数
    totalRows := 0
    for _, count := range e.sealedRowCount {
        totalRows += count
    }
    
    accessedDataRatio = float64(successRows) / float64(totalRows)
    
    // 判断是否满足部分结果要求
    requiredRatio := paramtable.Get().QueryNodeCfg.PartialResultRequiredDataRatio.GetAsFloat()
    shouldReturn = accessedDataRatio >= requiredRatio
    
    return shouldReturn, accessedDataRatio
}

10. 返回结果 (Lines 667-685)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
log.Debug("Delegator Query done")
if log.Core().Enabled(zap.DebugLevel) {
    // 记录查询的 segment IDs
    sealedIDs := lo.FlatMap(sealed, func(item SnapshotItem, _ int) []int64 {
        return lo.Map(item.Segments, func(segment SegmentEntry, _ int) int64 {
            return segment.SegmentID
        })
    })
    growingIDs := lo.Map(growing, func(item SegmentEntry, _ int) int64 {
        return item.SegmentID
    })
    log.Debug("execute count on segments...",
        zap.Int64s("sealedIDs", sealedIDs),
        zap.Int64s("growingIDs", growingIDs),
    )
}

return results, nil
  • 结果: 返回所有成功的查询结果列表
  • 日志: 在 debug 模式下记录查询的 segment IDs

关键数据结构

subTask

1
2
3
4
5
type subTask[T any] struct {
    req      T              // 查询请求
    targetID int64          // 目标节点 ID
    worker   cluster.Worker // Worker 客户端
}

SnapshotItem

1
2
3
4
type SnapshotItem struct {
    NodeID   int64          // 节点 ID
    Segments []SegmentEntry // Segment 列表
}

SegmentEntry

1
2
3
4
5
6
7
8
type SegmentEntry struct {
    SegmentID   int64
    NodeID      int64
    PartitionID int64
    Version     int64
    Offline     bool
    // ...
}

性能优化点

  1. Guarantee Timestamp 优化: 使用 WAL MVCC timestamp 加速 Strong 一致性查询
  2. 部分结果模式: 允许在数据未完全加载时返回部分结果，降低延迟
  3. Segment 剪枝: 根据统计信息跳过不相关的 segments
  4. 并发执行: 多个 segment 查询并发执行
  5. Pin 机制: 防止查询过程中 segment 被卸载

错误处理

  1. Delegator 不可用: 生命周期检查失败
  2. Channel 不匹配: 请求的 channel 不属于当前 delegator
  3. tSafe 等待超时: 时间戳延迟过大
  4. Distribution 不可服务: Segments 未完全加载且不允许部分结果
  5. Worker 不可用: 节点离线，根据部分结果策略决定是否失败
  6. 查询失败: Segment 查询失败，根据 evaluator 决定是否返回部分结果

配置参数

  • QueryNodeCfg.PartialResultRequiredDataRatio: 部分结果所需数据比例（默认 1.0）
  • QueryNodeCfg.EnableSegmentPrune: 是否启用 segment 剪枝
  • QueryNodeCfg.DefaultSegmentFilterRatio: 默认 segment 过滤比例
  • QueryNodeCfg.DowngradeTsafe: 是否降级 tSafe（不等待）
  • QueryNodeCfg.MaxTimestampLag: 最大时间戳延迟

调用链

1
2
3
4
5
6
7
8
9
10
11
12
13
QueryNode.Query()
    ↓
QueryNode.queryChannel()
    ↓
shardDelegator.Query()  ← 本文档分析的方法
    ↓
organizeSubTask()
    ↓
executeSubTasks()
    ↓
worker.QuerySegments()
    ↓
实际查询 segment 数据

总结

shardDelegator.Query 是一个复杂的协调方法，它：

  1. 管理时间戳: 优化 guarantee timestamp，等待 tSafe
  2. 管理 Segments: Pin segments，防止卸载
  3. 优化查询: Segment 剪枝，跳过不相关的数据
  4. 分发任务: 将查询任务分发到不同的节点
  5. 并发执行: 并发查询多个 segments
  6. 容错处理: 支持部分结果，提高可用性

该方法的设计充分考虑了性能、一致性和可用性的平衡，是 Milvus 查询系统的核心组件之一。

]]> <p>本文档深入分析 <code>shardDelegator.Query</code> 方法的实现细节，这是 QueryNode 中处理查询请求的核心方法。</p> <h2 id="方法签名"><a href="#方法签名" class="headerlink" title=" Milvus Query Request 处理流程分析 https://szza.github.io/2025/08/10/Milvus/15_query_request_flow_analysis/ 2025-08-10T04:00:00.000Z 2026-01-06T13:10:49.203Z 本文档详细分析了 Milvus 中 Query Request 从接收到返回的完整处理流程。

1. 请求入口层

1.1 HTTP 接口入口

文件: internal/distributed/proxy/httpserver/handler_v1.go, handler_v2.go

  • V1 API: HandlersV1.query() (line 496)

    • 接收 HTTP JSON 请求
    • 解析参数：collectionName, filter, outputFields, limit, offset
    • 转换为 milvuspb.QueryRequest
    • 调用 proxy.Query()

  • V2 API: HandlersV2.query() (line 912)

    • 支持更多参数：partitionNames, consistencyLevel, exprParams
    • 处理时区转换和表达式模板

1.2 gRPC 接口入口

文件: internal/distributed/proxy/httpserver/handler.go

  • handleQuery() (line 384)
    • 直接接收 milvuspb.QueryRequest
    • 调用 proxy.Query()

2. Proxy 层处理

2.1 Query 方法入口

文件: internal/proxy/impl.go

方法: Proxy.Query() (line 3554)

主要步骤:

  1. 创建 queryTask 对象
  2. 初始化 RetrieveRequest 基础信息
  3. 记录指标（metrics）
  4. 调用 query() 方法执行实际查询
1
2
3
4
5
6
7
8
qt := &queryTask{
    ctx:       ctx,
    Condition: NewTaskCondition(ctx),
    RetrieveRequest: &internalpb.RetrieveRequest{...},
    request:   request,
    ...
}
res, storageCost, err := node.query(ctx, qt, sp)

2.2 query 方法执行

文件: internal/proxy/impl.go

方法: Proxy.query() (line 3447)

主要步骤:

  1. 健康检查
  2. 记录日志和追踪信息
  3. 将任务加入队列: node.sched.dqQueue.Enqueue(qt)
  4. 等待任务完成: qt.WaitToFinish()
  5. 记录慢查询和指标

2.3 QueryTask 执行流程

文件: internal/proxy/task_query.go

QueryTask 遵循标准的任务执行模式：PreExecute → Execute → PostExecute

2.3.1 PreExecute 阶段

方法: queryTask.PreExecute() (line 369)

主要职责:

  1. 验证和获取元数据

    • 验证 collection 名称
    • 获取 collection ID 和 schema
    • 验证 partition 名称
    • 检查 partition key 模式

  2. 解析查询参数

    • 解析 limit, offset, timezone, extractTimeFields
    • 处理 iterator 模式
    • 验证最大查询窗口

  3. 创建查询计划

    • 调用 createPlanArgs() (line 299)
    • 解析表达式：planparserv2.CreateRetrievePlanArgs()
    • 处理 count(*) 特殊逻辑
    • 转换输出字段名称为字段 ID

  4. 设置时间戳

    • 根据一致性级别计算 guaranteeTimestamp
    • 处理 mvccTimestamp
    • 处理 collection TTL
    • 设置超时时间戳

  5. 序列化查询计划

    • 将 PlanNode 序列化为 SerializedExprPlan

2.3.2 Execute 阶段

方法: queryTask.Execute() (line 587)

主要职责:

  1. 初始化结果缓冲区

    1
    t.resultBuf = typeutil.NewConcurrentSet[*internalpb.RetrieveResults]()

  2. 负载均衡执行

    • 调用 t.lb.Execute() (line 595)
    • 对每个 shard 调用 queryShard() 方法
    • 使用 shardclient.CollectionWorkLoad 管理负载

  3. queryShard 方法 (line 704)

    • 构建 querypb.QueryRequest
    • 设置目标节点 ID
    • 处理 MVCC 时间戳覆盖
    • 调用 qn.Query() 发送到 QueryNode
    • 收集结果到 resultBuf

2.3.3 PostExecute 阶段

方法: queryTask.PostExecute() (line 611)

主要职责:

  1. 收集所有结果

    • 从 resultBuf 收集所有 RetrieveResults
    • 统计总查询数量和数据大小

  2. 结果合并（Reduce）

    • 创建 reducer: createMilvusReducer()
    • 调用 reducer.Reduce() 合并多个 shard 的结果
    • 应用 limit 和 offset
    • 处理排序

  3. 结果后处理

    • 验证 geometry 字段
    • 重构 struct 字段数据
    • 时区转换（timestamp 转 ISO 字符串）
    • 提取时间字段（如果指定）

  4. 设置最终结果

    • 设置输出字段名称
    • 设置主键字段名称
    • 处理 iterator session timestamp

3. QueryNode 层处理

3.1 Query 方法入口

文件: internal/querynodev2/services.go

方法: QueryNode.Query() (line 972)

主要步骤:

  1. 健康检查

    • 检查节点生命周期状态
    • 检查 collection 是否已加载

  2. 并发处理多个 Channel

    • 为每个 DML channel 创建独立的 goroutine
    • 调用 queryChannel() 处理每个 channel
    • 使用 errgroup 管理并发

  3. 结果合并

    • 收集所有 channel 的结果
    • 使用 segments.CreateInternalReducer 合并结果
    • 返回最终结果

3.2 queryChannel 方法

文件: internal/querynodev2/handlers.go

方法: QueryNode.queryChannel() (line 218)

主要步骤:

  1. 获取 Shard Delegator

    1
    sd, ok := node.delegators.Get(channel)

  2. 调用 Delegator 查询

    1
    results, err := sd.Query(queryCtx, req)

  3. 结果合并

    • 使用 segments.ReduceRetrieveResults() 合并结果
    • 处理 collection 引用计数

3.3 Delegator Query 方法

文件: internal/querynodev2/delegator/delegator.go

方法: shardDelegator.Query() (line 577)

主要步骤:

  1. 验证请求

    • 检查 channel 是否匹配
    • 检查 delegator 是否可用

  2. 处理时间戳

    • 调用 speedupGuranteeTS() 优化 guarantee timestamp
    • 等待 tSafe（根据 partialResultRequiredDataRatio 配置）
    • 设置 MVCC timestamp

  3. 获取可读 Segment

    1
    2
    sealed, growing, sealedRowCount, version, err := 
        sd.distribution.PinReadableSegments(partialResultRequiredDataRatio, ...)
    • 获取 sealed segments 和 growing segments
    • Pin 操作防止 segment 被卸载

  4. Segment 剪枝（可选）

    • 如果启用 EnableSegmentPrune
    • 根据统计信息剪枝不相关的 segments

  5. 组织子任务

    1
    tasks, err := organizeSubTask(ctx, req, sealed, growing, sd, ...)
    • 将 segments 组织成查询任务
    • 分配任务到不同的 worker

  6. 执行子任务

    1
    2
    results, err := executeSubTasks(ctx, tasks, evaluator, 
        func(ctx, req, worker) { worker.QuerySegments(ctx, req) }, ...)
    • 并发执行所有子任务
    • 使用 RowCountBasedEvaluator 评估部分结果
    • 处理失败情况（部分结果模式）

  7. 返回结果

    • 返回所有成功的查询结果
    • Unpin segments

4. 数据流图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
Client Request (HTTP/gRPC)
    ↓
Proxy Handler (handler.go/handler_v1.go/handler_v2.go)
    ↓
Proxy.Query() [impl.go:3554]
    ↓
Proxy.query() [impl.go:3447]
    ↓
Enqueue to dqQueue
    ↓
QueryTask.PreExecute() [task_query.go:369]
    ├─ 验证请求
    ├─ 获取元数据
    ├─ 创建查询计划
    └─ 设置时间戳
    ↓
QueryTask.Execute() [task_query.go:587]
    ├─ Load Balancer 选择节点
    └─ queryShard() [task_query.go:704]
        ↓
        QueryNode.Query() [services.go:972]
            ├─ 并发处理多个 Channel
            └─ queryChannel() [handlers.go:218]
                ↓
                Delegator.Query() [delegator.go:577]
                    ├─ 等待 tSafe
                    ├─ Pin Readable Segments
                    ├─ 组织子任务
                    └─ executeSubTasks()
                        ↓
                        Worker.QuerySegments()
                            ↓
                            实际查询 Segment 数据
    ↓
QueryTask.PostExecute() [task_query.go:611]
    ├─ 收集结果
    ├─ Reduce 合并结果
    └─ 后处理（时区转换等）
    ↓
返回结果给 Client

5. 关键组件说明

5.1 Load Balancer

位置: internal/proxy/shardclient

  • 负责选择 QueryNode 节点
  • 支持多种负载均衡策略
  • 管理 shard client 连接

5.2 Query Plan Parser

位置: internal/parser/planparserv2

  • 解析查询表达式（如 id > 100）
  • 生成执行计划（PlanNode）
  • 优化查询计划

5.3 Reducer

位置: internal/util/reduce

  • 合并多个 shard 的查询结果
  • 应用 limit 和 offset
  • 处理排序和去重

5.4 Delegator

位置: internal/querynodev2/delegator

  • 管理 shard 级别的查询逻辑
  • 组织 segment 查询任务
  • 处理部分结果和容错

5.5 Segment Manager

位置: internal/querynodev2/segments

  • 管理 segment 的生命周期
  • 提供 segment 查询接口
  • 处理 segment 的加载和卸载

6. 关键配置参数

  • ProxyCfg.SlowLogSpanInSeconds: 慢查询阈值
  • QueryNodeCfg.PartialResultRequiredDataRatio: 部分结果所需数据比例
  • QueryNodeCfg.EnableSegmentPrune: 是否启用 segment 剪枝
  • QueryNodeCfg.DefaultSegmentFilterRatio: 默认 segment 过滤比例

7. 性能优化点

  1. 并发处理: 多个 channel 和 segment 并发查询
  2. Segment 剪枝: 根据统计信息跳过不相关的 segments
  3. 部分结果: 支持返回部分结果以降低延迟
  4. 负载均衡: 智能选择 QueryNode 节点
  5. 结果缓存: 某些场景下可以缓存查询结果

8. 错误处理

  • Collection 未加载: 返回 CollectionNotLoaded 错误
  • Channel 不匹配: Delegator 验证 channel 是否属于自己
  • Segment 未加载: 标记 segment 为 offline，可能触发重试
  • 部分失败: 根据 partialResultRequiredDataRatio 决定是否返回部分结果

9. 监控指标

  • ProxyReceivedNQ: Proxy 接收的查询请求数
  • ProxySQLatency: Proxy 查询延迟
  • QueryNodeSQCount: QueryNode 查询计数
  • QueryNodeSQLatencyWaitTSafe: 等待 tSafe 的延迟
  • ProxyReduceResultLatency: 结果合并延迟
]]> <p>本文档详细分析了 Milvus 中 Query Request 从接收到返回的完整处理流程。</p> <h2 id="1-请求入口层"><a href="#1-请求入口层" class="headerlink" title="1. 请求入口层"></a>1. 请求入口层</ Milvus TSO（Timestamp Oracle）生成及其作用分析 https://szza.github.io/2025/08/10/Milvus/14_tso_generation_and_usage_analysis/ 2025-08-10T03:00:00.000Z 2026-01-06T13:10:48.744Z 概述

TSO（Timestamp Oracle）是 Milvus 分布式系统中的核心组件，负责生成全局唯一、单调递增的时间戳。所有数据操作（Insert、Delete、Search 等）都需要从 TSO 获取时间戳，确保分布式环境下的事件顺序一致性。

一、TSO 的基本概念

1.1 为什么需要 TSO？

在分布式系统中，存在以下问题：

  1. 时钟不同步：不同节点的本地时钟可能不一致
  2. 网络延迟：消息在网络中传输存在延迟，可能导致乱序
  3. 事件顺序：需要保证全局事件的有序性

示例场景：

1
2
3
4
5
6
7
用户 u1 和 u2 在不同节点上操作：
- t0: u1 创建 Collection C0
- t2: u2 在 C0 上搜索（应该看到空集合）
- t5: u1 插入数据 A1
- t7: u2 在 C0 上搜索（应该看到 A1）
- t15: u1 删除 A1
- t17: u2 在 C0 上搜索（应该看不到 A1）

如果没有 TSO，由于时钟不同步和网络延迟，u2 可能看到不一致的数据状态。

1.2 TSO 的解决方案

  • 统一时间源：所有组件从 RootCoord 的 TSO 服务获取时间戳，而不是使用本地时钟
  • 全局有序：TSO 保证生成的时间戳全局唯一且单调递增
  • 时间同步：通过 TimeTick 机制确保消息流的顺序处理

二、TSO 的数据结构

2.1 混合时间戳（Hybrid Timestamp）

TSO 生成的时间戳是 uint64 类型，采用混合结构：

1
2
3
4
5
6
┌─────────────────────────────────────────────────────────┐
│                   64 bits (uint64)                       │
├──────────────────────────────┬──────────────────────────┤
│   Physical Part (46 bits)    │ Logical Part (18 bits)   │
│   UTC 时间（毫秒）              │   逻辑计数器              │
└──────────────────────────────┴──────────────────────────┘

代码实现（pkg/util/tsoutil/tso.go）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const (
    logicalBits     = 18
    logicalBitsMask = (1 << logicalBits) - 1  // 0x3FFFF
)

// ComposeTS 组合物理时间和逻辑时间
func ComposeTS(physical, logical int64) uint64 {
    return uint64((physical << logicalBits) + logical)
}

// ParseTS 解析时间戳
func ParseTS(ts uint64) (time.Time, uint64) {
    logical := ts & logicalBitsMask           // 提取逻辑部分（低 18 位）
    physical := ts >> logicalBits              // 提取物理部分（高 46 位）
    physicalTime := time.Unix(int64(physical/1000), 
        int64(physical)%1000*time.Millisecond.Nanoseconds())
    return physicalTime, logical
}

2.2 各部分的作用

部分位数作用范围
Physical Part46 bitsUTC 时间（毫秒）约 8925 年
Logical Part18 bits逻辑计数器0 ~ 262,143 (2^18-1)

优势：

  • 高精度：同一毫秒内可生成最多 262,143 个时间戳
  • 时间可读：物理部分可以直接转换为 UTC 时间
  • 全局唯一：物理时间 + 逻辑计数器保证唯一性

三、TSO 的生成流程

3.1 整体架构

1
2
3
4
5
┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Proxy     │────────▶│  RootCoord   │────────▶│    etcd      │
│             │ Request │              │ Save    │              │
│             │◀────────│  TSO Service │◀────────│              │
└─────────────┘ Response└──────────────┘ Load    └─────────────┘

3.2 RootCoord 中的 TSO 服务

文件: internal/tso/tso.go

3.2.1 timestampOracle 结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
type timestampOracle struct {
    key   string              // etcd 中的 key
    txnKV kv.TxnKV            // etcd 客户端
    
    saveInterval  time.Duration  // 保存间隔（默认 3 秒）
    maxResetTSGap func() time.Duration
    
    TSO           unsafe.Pointer  // 当前 TSO（原子指针）
    lastSavedTime atomic.Value    // 最后保存的时间
}

// atomicObject 存储当前 TSO 状态
type atomicObject struct {
    physical time.Time  // 物理时间
    logical  int64      // 逻辑计数器
}

3.2.2 初始化（InitTimestamp）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
func (t *timestampOracle) InitTimestamp() error {
    // 1. 从 etcd 加载上次保存的时间戳
    last, err := t.loadTimestamp()
    if err != nil {
        return err
    }
    
    // 2. 获取当前系统时间
    next := time.Now()
    
    // 3. 如果系统时间与 etcd 时间差距太小，使用 etcd 时间
    if typeutil.SubTimeByWallClock(next, last) < updateTimestampGuard {
        next = last.Add(updateTimestampGuard)
    }
    
    // 4. 保存未来时间窗口到 etcd（提前保存，避免频繁写 etcd）
    save := next.Add(t.saveInterval)  // saveInterval = 3 秒
    if err := t.saveTimestamp(save); err != nil {
        return err
    }
    
    // 5. 初始化内存中的 TSO
    current := &atomicObject{
        physical: next,
        logical:  0,
    }
    atomic.StorePointer(&t.TSO, unsafe.Pointer(current))
    
    return nil
}

关键点：

  • 从 etcd 恢复上次保存的时间戳
  • 提前保存未来 3 秒的时间窗口，减少 etcd 写入
  • 使用原子指针保证线程安全

3.2.3 更新时间戳（UpdateTimestamp）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
func (t *timestampOracle) UpdateTimestamp() error {
    prev := (*atomicObject)(atomic.LoadPointer(&t.TSO))
    now := time.Now()
    
    jetLag := typeutil.SubTimeByWallClock(now, prev.physical)
    
    var next time.Time
    
    // 情况 1：系统时间比物理时间大，同步到系统时间
    if jetLag > updateTimestampGuard {
        next = now
    } 
    // 情况 2：逻辑计数器快用完了，增加物理时间
    else if prevLogical > maxLogical/2 {
        next = prev.physical.Add(time.Millisecond)
    } 
    // 情况 3：时间窗口足够，不需要更新
    else {
        return nil
    }
    
    // 如果时间窗口不够，需要更新 etcd
    if typeutil.SubTimeByWallClock(t.lastSavedTime.Load().(time.Time), next) <= updateTimestampGuard {
        save := next.Add(t.saveInterval)
        if err := t.saveTimestamp(save); err != nil {
            return err
        }
    }
    
    // 更新内存中的 TSO
    current := &atomicObject{
        physical: next,
        logical:  0,  // 重置逻辑计数器
    }
    atomic.StorePointer(&t.TSO, unsafe.Pointer(current))
    
    return nil
}

更新触发条件：

  1. 系统时间比物理时间大（时钟同步）
  2. 逻辑计数器超过 maxLogical/2（131,071），需要增加物理时间
  3. 时间窗口不足，需要更新 etcd

3.3 生成时间戳（GenerateTSO）

文件: internal/tso/global_allocator.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
func (gta *GlobalTSOAllocator) GenerateTSO(count uint32) (uint64, error) {
    var physical, logical int64
    
    maxRetryCount := 10
    
    for i := 0; i < maxRetryCount; i++ {
        // 1. 获取当前 TSO 对象
        current := (*atomicObject)(atomic.LoadPointer(&gta.tso.TSO))
        if current == nil || current.physical.Equal(typeutil.ZeroTime) {
            // TSO 未初始化，等待
            time.Sleep(200 * time.Millisecond)
            continue
        }
        
        // 2. 原子增加逻辑计数器
        physical = current.physical.UnixMilli()
        logical = atomic.AddInt64(&current.logical, int64(count))
        
        // 3. 检查逻辑计数器是否溢出
        if logical >= maxLogical && gta.LimitMaxLogic {
            log.Info("logical part outside of max logical interval, please check ntp time")
            time.Sleep(UpdateTimestampStep)  // 等待 50ms，触发 UpdateTimestamp
            continue
        }
        
        // 4. 组合时间戳
        return tsoutil.ComposeTS(physical, logical), nil
    }
    
    return 0, errors.New("can not get timestamp")
}

关键点：

  • 使用原子操作增加逻辑计数器，保证线程安全
  • 支持批量分配（count 个时间戳）
  • 如果逻辑计数器溢出，等待并触发 UpdateTimestamp

3.4 RootCoord 的 AllocTimestamp RPC

文件: internal/rootcoord/root_coord.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
func (c *Core) AllocTimestamp(ctx context.Context, in *rootcoordpb.AllocTimestampRequest) 
    (*rootcoordpb.AllocTimestampResponse, error) {
    
    // 1. 检查健康状态
    if err := merr.CheckHealthy(c.GetStateCode()); err != nil {
        return &rootcoordpb.AllocTimestampResponse{Status: merr.Status(err)}, nil
    }
    
    // 2. 处理阻塞时间戳（用于数据恢复等场景）
    if in.BlockTimestamp > 0 {
        blockTime, _ := tsoutil.ParseTS(in.BlockTimestamp)
        lastTime := c.tsoAllocator.GetLastSavedTime()
        deltaDuration := blockTime.Sub(lastTime)
        if deltaDuration > 0 {
            time.Sleep(deltaDuration + time.Millisecond*200)
        }
    }
    
    // 3. 生成 TSO
    ts, err := c.tsoAllocator.GenerateTSO(in.GetCount())
    if err != nil {
        return &rootcoordpb.AllocTimestampResponse{Status: merr.Status(err)}, nil
    }
    
    // 4. 返回第一个可用时间戳
    // 注意：GenerateTSO 返回的是最后一个时间戳，需要减去 count-1
    ts = ts - uint64(in.GetCount()) + 1
    
    return &rootcoordpb.AllocTimestampResponse{
        Status:    merr.Success(),
        Timestamp: ts,  // 第一个可用时间戳
        Count:     in.GetCount(),
    }, nil
}

Proto 定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
service RootCoord {
    rpc AllocTimestamp(AllocTimestampRequest) returns (AllocTimestampResponse) {}
}

message AllocTimestampRequest {
    common.MsgBase base = 1;
    uint32 count = 3;  // 请求的时间戳数量
}

message AllocTimestampResponse {
    common.Status status = 1;
    uint64 timestamp = 2;  // 第一个可用时间戳
    uint32 count = 3;      // 分配的数量
}

四、Proxy 如何使用 TSO

4.1 TimestampAllocator

文件: internal/proxy/timestamp.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
type timestampAllocator struct {
    peerID int64
    tso    types.RootCoordClient
}

func (ta *timestampAllocator) alloc(ctx context.Context, count uint32) ([]Timestamp, error) {
    // 1. 构建请求
    req := &rootcoordpb.AllocTimestampRequest{
        Base: commonpbutil.NewMsgBase(
            commonpbutil.WithMsgType(commonpb.MsgType_RequestTSO),
            commonpbutil.WithSourceID(ta.peerID),
        ),
        Count: count,
    }
    
    // 2. 调用 RootCoord 的 AllocTimestamp
    resp, err := ta.tso.AllocTimestamp(ctx, req)
    if err != nil {
        return nil, err
    }
    
    // 3. 生成时间戳数组
    start, cnt := resp.GetTimestamp(), resp.GetCount()
    ret := make([]Timestamp, cnt)
    for i := uint32(0); i < cnt; i++ {
        ret[i] = start + uint64(i)  // 连续的时间戳
    }
    
    return ret, nil
}

// AllocOne 分配单个时间戳
func (ta *timestampAllocator) AllocOne(ctx context.Context) (Timestamp, error) {
    ret, err := ta.alloc(ctx, 1)
    if err != nil {
        return 0, err
    }
    return ret[0], nil
}

4.2 Insert 操作中的 TSO 使用

文件: internal/proxy/task_insert.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
func (it *insertTask) insertPreExecute(ctx context.Context) error {
    // 1. 分配主键 ID
    rowNums := uint32(it.insertMsg.NRows())
    rowIDBegin, rowIDEnd, _ := common.AllocAutoID(it.idAllocator.Alloc, rowNums, clusterID)
    
    // 2. 为每行分配时间戳
    rowNum := it.insertMsg.NRows()
    it.insertMsg.Timestamps = make([]uint64, rowNum)
    
    // 3. 批量分配时间戳（性能优化）
    timestamps, err := it.timestampAllocator.AllocTimestamp(ctx, uint32(rowNum))
    if err != nil {
        return err
    }
    
    // 4. 为每行设置时间戳
    for index := range it.insertMsg.Timestamps {
        it.insertMsg.Timestamps[index] = timestamps[index]
    }
    
    return nil
}

4.3 Delete 操作中的 TSO 使用

文件: internal/proxy/task_delete.go

1
2
3
4
5
6
7
8
9
10
11
12
13
func (dr *deleteRunner) Run(ctx context.Context) error {
    // 1. 分配时间戳
    ts, err := dr.tsoAllocatorIns.AllocOne(ctx)
    if err != nil {
        return err
    }
    
    // 2. 设置删除消息的时间戳
    dr.deleteMsg.Timestamps = []uint64{ts}
    
    // 3. 发送删除消息到消息流
    // ...
}

五、TSO 的作用

5.1 保证全局事件顺序

场景：多个 Proxy 同时写入数据

1
2
3
4
Proxy1: Insert A (ts=100)
Proxy2: Insert B (ts=150)
Proxy1: Insert C (ts=200)
Proxy2: Delete A (ts=250)

所有操作都从同一个 TSO 获取时间戳，保证全局顺序：

  • A 在 B 之前插入（100 < 150）
  • C 在 B 之后插入（200 > 150）
  • Delete A 在 Insert C 之后（250 > 200）

5.2 时间同步（Time Synchronization）

问题：如何确保消息流中所有小于某个时间戳的消息都已处理？

解决方案：TimeTick 机制

  1. Proxy 上报时间戳：

    • 每个 Proxy 定期（默认 200ms）向 RootCoord 上报每个消息流的最新时间戳

  2. RootCoord 计算最小时间戳：

    • 对于每个消息流，RootCoord 计算所有 Proxy 上报的最小时间戳

  3. 插入 TimeTick 消息：

    • RootCoord 将最小时间戳作为 TimeTick 消息插入到消息流中

  4. 消费者处理：

    • 当消费者读取到 TimeTick 消息时，表示所有小于该时间戳的消息都已处理完成

代码（internal/rootcoord/root_coord.go）：

1
2
3
4
5
6
func (c *Core) UpdateChannelTimeTick(ctx context.Context, in *internalpb.ChannelTimeTickMsg) 
    (*commonpb.Status, error) {
    // 更新每个 Channel 的时间戳
    err := c.chanTimeTick.updateTimeTick(in, "gRPC")
    return merr.Status(err), nil
}

5.3 数据一致性保证

场景：查询操作需要看到一致的数据快照

1
2
3
4
5
t1: Insert A (ts=100)
t2: Insert B (ts=200)
t3: Search (ts=150)  // 应该只看到 A，看不到 B
t4: Delete A (ts=250)
t5: Search (ts=300)   // 应该只看到 B

通过 TSO 时间戳：

  • 查询操作获取时间戳 ts_query
  • 只处理时间戳 <= ts_query 的数据
  • 保证查询结果的一致性

5.4 故障恢复

场景：系统重启后恢复时间戳

  1. 持久化到 etcd：

    • RootCoord 定期将时间戳保存到 etcd

  2. 恢复时间戳：

    • 重启后，从 etcd 加载上次保存的时间戳
    • 确保新生成的时间戳大于已保存的时间戳

  3. 防止时间回退：

    • 如果系统时间回退，使用 etcd 中的时间戳
    • 保证时间戳单调递增

六、TSO 的性能优化

6.1 批量分配

  • 减少 RPC 调用：Proxy 可以一次请求多个时间戳
  • 提高吞吐量：减少网络往返次数
1
2
// 一次分配 100 个时间戳
timestamps, err := tsoAllocator.AllocTimestamp(ctx, 100)

6.2 时间窗口预分配

  • 减少 etcd 写入：提前保存未来 3 秒的时间窗口
  • 提高性能：避免频繁写 etcd
1
saveInterval = 3 * time.Second  // 提前保存 3 秒

6.3 内存分配

  • 原子操作：使用原子操作更新逻辑计数器，无锁
  • 高性能：避免锁竞争
1
logical = atomic.AddInt64(&current.logical, int64(count))

6.4 逻辑计数器溢出处理

  • 自动增加物理时间：当逻辑计数器超过 maxLogical/2 时，自动增加物理时间
  • 保证可用性：不会因为逻辑计数器用完而阻塞

七、TSO 的限制和注意事项

7.1 时钟同步要求

  • NTP 同步：建议所有节点使用 NTP 同步时钟
  • 时钟偏移检测：如果时钟偏移超过 3 倍 UpdateTimestampStep（150ms），会记录警告日志

7.2 逻辑计数器限制

  • 最大逻辑值：maxLogical = 2^18 = 262,143
  • 同一毫秒内最多生成：262,143 个时间戳
  • 如果超过：需要等待下一毫秒

7.3 单点故障

  • RootCoord 是单点：如果 RootCoord 故障，无法分配时间戳
  • 高可用方案：通过 etcd 的 Leader 选举实现高可用

7.4 时间戳范围

  • 物理时间范围：
    • 最小值：1546300800000（2019-01-01 00:00:00 UTC）
    • 最大值：253402300799000（9999-12-31 23:59:59 UTC）

八、总结

8.1 TSO 的核心价值

  1. ✅ 全局唯一时间戳：保证分布式环境下事件顺序
  2. ✅ 时间同步：解决时钟不同步和网络延迟问题
  3. ✅ 数据一致性：支持基于时间戳的快照查询
  4. ✅ 高性能：批量分配、时间窗口预分配等优化

8.2 关键设计

  • 混合时间戳：物理时间（46 bits）+ 逻辑计数器（18 bits）
  • 持久化：定期保存到 etcd，支持故障恢复
  • 原子操作：使用原子操作保证线程安全
  • 批量分配：支持一次分配多个时间戳

8.3 使用场景

  • Insert/Delete 操作：为每行数据分配时间戳
  • 查询操作：获取查询时间戳，保证一致性
  • 消息流处理：通过 TimeTick 确保消息顺序
  • 故障恢复：从 etcd 恢复时间戳状态

TSO 是 Milvus 分布式系统的核心基础设施，为整个系统提供了全局有序的时间基准，确保了数据一致性和系统可靠性。

九、GenerateTSO 失败处理机制

9.1 GenerateTSO 内部重试机制

GenerateTSO 方法内部实现了重试机制，不会立即失败：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
func (gta *GlobalTSOAllocator) GenerateTSO(count uint32) (uint64, error) {
    maxRetryCount := 10  // 最多重试 10 次
    
    for i := 0; i < maxRetryCount; i++ {
        current := (*atomicObject)(atomic.LoadPointer(&gta.tso.TSO))
        
        // 情况 1：TSO 未初始化，等待 200ms 后重试
        if current == nil || current.physical.Equal(typeutil.ZeroTime) {
            log.Info("sync hasn't completed yet, wait for a while")
            time.Sleep(200 * time.Millisecond)
            continue
        }
        
        // 情况 2：逻辑计数器溢出，等待 50ms 后重试
        logical = atomic.AddInt64(&current.logical, int64(count))
        if logical >= maxLogical && gta.LimitMaxLogic {
            log.Info("logical part outside of max logical interval")
            time.Sleep(UpdateTimestampStep)  // 50ms
            continue
        }
        
        return tsoutil.ComposeTS(physical, logical), nil
    }
    
    // 所有重试都失败，返回错误
    return 0, errors.New("can not get timestamp")
}

重试场景：

  1. TSO 未初始化：等待 200ms 后重试（最多 10 次，总等待时间约 2 秒）
  2. 逻辑计数器溢出：等待 50ms 后重试（等待 UpdateTimestamp 更新物理时间）

9.2 Proxy 层的超时和重试

Proxy 调用 TSO 时有多层保护：

9.2.1 Context 超时

1
2
3
4
5
6
7
8
func (ta *timestampAllocator) alloc(ctx context.Context, count uint32) ([]Timestamp, error) {
    // 设置 10 秒超时
    ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
    defer cancel()
    
    resp, err := ta.tso.AllocTimestamp(ctx, req)
    // ...
}

超时保护：如果 RootCoord 无响应，10 秒后自动超时，不会永久阻塞。

9.2.2 gRPC 客户端重试

Proxy 的 gRPC 客户端有自动重试机制：

1
2
3
4
5
6
7
8
9
10
// internal/util/grpcclient/client.go
retry.Handle(ctx, func() (bool, error) {
    // 执行 RPC 调用
    ret, err = caller(wrapper.client)
    // 检查错误，决定是否重试
    return needRetry, err
}, 
    retry.Attempts(10),                    // 最多重试 10 次
    retry.Sleep(200*time.Millisecond),     // 初始退避 200ms
    retry.MaxSleepTime(10*time.Second))    // 最大退避 10 秒

重试策略：

  • 最多重试 10 次
  • 初始退避：200ms
  • 最大退避：10 秒
  • 总耗时：最多约 52.8 秒（如果所有重试都失败）

9.3 任务入队失败处理

当 TSO 分配失败时，任务无法入队，会立即返回错误：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
func (queue *baseTaskQueue) Enqueue(t task) error {
    // ...
    if t.CanSkipAllocTimestamp() {
        // 某些任务可以跳过 TSO 分配
        ts = tsoutil.ComposeTS(time.Now().UnixMilli(), 0)
    } else {
        // 必须分配 TSO 的任务
        ts, err = queue.tsoAllocatorIns.AllocOne(t.TraceCtx())
        if err != nil {
            return err  // 直接返回错误，任务不入队
        }
    }
    // ...
}

关键点：

  • ✅ 不会阻塞：任务入队失败会立即返回错误，不会阻塞其他任务
  • ✅ 错误传播：错误会返回给调用者（如 Insert/Delete 请求）
  • ✅ 用户可见：用户会收到明确的错误响应

9.4 失败场景分析

场景 1：RootCoord 未启动或不可用

1
2
3
4
5
6
7
GenerateTSO 内部重试（10次 × 200ms = 2秒）
    ↓
Proxy gRPC 重试（10次，最多 52.8 秒）
    ↓
Context 超时（10 秒）
    ↓
任务入队失败，返回错误给用户

结果：用户请求会在约 10 秒后收到错误响应，不会永久阻塞。

场景 2：TSO 未初始化（RootCoord 刚启动）

1
2
3
4
5
6
7
8
9
GenerateTSO 检测到 TSO 未初始化
    ↓
等待 200ms
    ↓
重试（最多 10 次，总等待约 2 秒）
    ↓
如果初始化完成，成功返回
    ↓
如果仍未初始化，返回错误

结果：正常情况下，RootCoord 初始化很快（< 1 秒），不会失败。

场景 3：逻辑计数器溢出

1
2
3
4
5
6
7
8
9
GenerateTSO 检测到逻辑计数器溢出
    ↓
等待 50ms（等待 UpdateTimestamp 更新）
    ↓
重试（最多 10 次，总等待约 0.5 秒）
    ↓
如果 UpdateTimestamp 成功，继续分配
    ↓
如果仍然溢出，返回错误

结果：正常情况下，UpdateTimestamp 会在 50ms 内完成，不会失败。

9.5 总结

GenerateTSO 失败不会永久阻塞处理：

  1. ✅ 多层重试机制：

    • GenerateTSO 内部重试（10 次）
    • gRPC 客户端重试（10 次）
    • 总重试次数可达 100 次

  2. ✅ 超时保护：

    • Context 超时（10 秒）
    • 确保不会无限等待

  3. ✅ 快速失败：

    • 任务入队失败立即返回错误
    • 不会阻塞其他任务的处理
    • 用户会收到明确的错误响应

  4. ✅ 正常情况下的性能：

    • TSO 分配通常在毫秒级完成
    • 重试机制只在异常情况下触发
    • 不会影响正常请求的延迟

最佳实践：

  • 确保 RootCoord 高可用（通过 etcd Leader 选举）
  • 监控 TSO 分配失败率
  • 如果频繁失败，检查 RootCoord 健康状态和网络连接
]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>TSO（Timestamp Oracle）是 Milvus 分布式系统中的核心组件，负责生成全局唯一、单调递增的时间戳。所有数据操作（Ins Milvus C++ 功能通过 CGO 集成分析 https://szza.github.io/2025/08/10/Milvus/13_cgo_cpp_integration_analysis/ 2025-08-10T02:00:00.000Z 2026-01-06T13:10:48.425Z 概述

Milvus 采用混合架构设计，核心性能关键路径使用 C++ 实现，通过 CGO（C Go）提供给 Go 代码调用。这种设计既保证了性能，又保持了 Go 代码的简洁性和可维护性。

一、CGO 集成架构

1.1 基本结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌─────────────────────────────────────────┐
│         Go 代码层                        │
│  (Proxy, QueryNode, DataNode, etc.)     │
└──────────────┬──────────────────────────┘
               │ CGO 调用
               ↓
┌─────────────────────────────────────────┐
│      C 接口层 (_c.h, _c.cpp)            │
│  封装 C++ 实现，提供 C 兼容接口          │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│      C++ 实现层                         │
│  (高性能核心逻辑)                        │
└─────────────────────────────────────────┘

1.2 CGO 使用方式

典型示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
package segcore

/*
#cgo pkg-config: milvus_core

#include "segcore/collection_c.h"
#include "segcore/segment_c.h"
#include "common/type_c.h"
*/
import "C"

// Go 代码调用 C 函数
func CreateCCollection(req *CreateCCollectionRequest) (*CCollection, error) {
    var ptr C.CCollection
    status := C.NewCollection(
        unsafe.Pointer(&schemaBlob[0]), 
        (C.int64_t)(len(schemaBlob)), 
        &ptr)
    // ...
}

二、主要 C++ 功能模块

2.1 索引构建（Index Building）

位置：internal/core/src/indexbuilder/

CGO 接口：indexbuilder/index_c.h

Go 包装：internal/util/indexcgowrapper/

功能：

  • ✅ 向量索引构建（IVF、HNSW、FLAT 等）
  • ✅ 标量索引构建（倒排索引、B+树等）
  • ✅ 文本索引构建（BM25、N-gram 等）
  • ✅ 索引序列化和反序列化
  • ✅ 索引文件管理

关键代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
// internal/util/indexcgowrapper/index.go
type CgoIndex struct {
    indexPtr C.CIndex
    close    bool
}

func CreateIndex(ctx context.Context, buildIndexInfo *indexcgopb.BuildIndexInfo) (CodecIndex, error) {
    var indexPtr C.CIndex
    status := C.CreateIndex(&indexPtr, 
        (*C.uint8_t)(unsafe.Pointer(&buildIndexInfoBlob[0])), 
        (C.uint64_t)(len(buildIndexInfoBlob)))
    // ...
}

C++ 实现文件：

  • index_c.cpp - 索引创建和管理
  • VecIndexCreator.cpp - 向量索引创建
  • ScalarIndexCreator.cpp - 标量索引创建

2.2 段核心（Segcore）

位置：internal/core/src/segcore/

CGO 接口：多个 *_c.h 文件

Go 包装：internal/util/segcore/

功能模块：

2.2.1 Collection 管理

CGO 接口：segcore/collection_c.h

功能：

  • ✅ Collection 创建和销毁
  • ✅ Schema 管理
  • ✅ Index Meta 管理
  • ✅ 字段加载配置

关键代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// internal/util/segcore/collection.go
type CCollection struct {
    ptr          C.CCollection
    collectionID int64
    schema       *schemapb.CollectionSchema
    indexMeta    *segcorepb.CollectionIndexMeta
}

func CreateCCollection(req *CreateCCollectionRequest) (*CCollection, error) {
    var ptr C.CCollection
    status := C.NewCollection(
        unsafe.Pointer(&schemaBlob[0]), 
        (C.int64_t)(len(schemaBlob)), 
        &ptr)
    // ...
}

2.2.2 Segment 操作

CGO 接口：segcore/segment_c.h

功能：

  • ✅ Segment 创建（Growing/Sealed）
  • ✅ 数据插入（Insert）
  • ✅ 数据删除（Delete）
  • ✅ 字段数据加载（LoadFieldData）
  • ✅ 索引加载（LoadIndex）
  • ✅ 内存使用统计

关键代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// internal/util/segcore/segment.go
type cSegmentImpl struct {
    id  int64
    ptr C.CSegmentInterface
}

func (s *cSegmentImpl) Insert(ctx context.Context, request *InsertRequest) (*InsertResult, error) {
    status := C.Insert(s.ptr,
        (*C.uint8_t)(unsafe.Pointer(&insertBlob[0])),
        (C.int64_t)(len(insertBlob)),
        C.int64_t(request.NumRows),
        C.int64_t(request.Timestamp))
    // ...
}

C++ 实现文件：

  • segment_c.cpp - Segment C 接口
  • SegmentGrowingImpl.cpp - Growing Segment 实现
  • ChunkedSegmentSealedImpl.cpp - Sealed Segment 实现

2.2.3 查询计划（Query Plan）

CGO 接口：segcore/plan_c.h

功能：

  • ✅ 查询计划生成
  • ✅ 表达式解析
  • ✅ 查询优化

关键代码：

1
2
3
4
5
6
7
8
9
// internal/util/segcore/plan.go
func CreatePlan(collection *CCollection, planBlob []byte) (CPlan, error) {
    var planPtr C.CPlan
    status := C.CreatePlan(collection.rawPointer(),
        (*C.uint8_t)(unsafe.Pointer(&planBlob[0])),
        (C.int64_t)(len(planBlob)),
        &planPtr)
    // ...
}

2.2.4 结果归并（Reduce）

CGO 接口：segcore/reduce_c.h

功能：

  • ✅ 多段查询结果归并
  • ✅ TopK 结果合并
  • ✅ 聚合操作

关键代码：

1
2
3
4
5
6
7
8
// internal/util/segcore/reduce.go
func ReduceSearchResults(ctx context.Context, 
    plan CPlan, 
    searchResults []*SearchResult, 
    numSegments int64) (*SearchResult, error) {
    // 调用 C++ reduce 函数
    // ...
}

C++ 实现文件：

  • reduce_c.cpp - Reduce C 接口
  • reduce/Reduce.cpp - Reduce 实现
  • reduce/GroupReduce.cpp - 分组 Reduce

2.2.5 向量索引操作

CGO 接口：segcore/vector_index_c.h

功能：

  • ✅ 向量索引加载
  • ✅ 向量搜索
  • ✅ 索引管理

关键代码：

1
2
3
4
5
6
7
// internal/util/vecindexmgr/vector_index_mgr.go
func LoadVectorIndex(ctx context.Context, 
    indexBlob []byte, 
    indexParams map[string]string) (C.CVectorIndex, error) {
    // 调用 C++ 加载向量索引
    // ...
}

2.2.6 字段数据加载

CGO 接口：segcore/load_field_data_c.h

功能：

  • ✅ 从存储加载字段数据
  • ✅ 数据格式转换
  • ✅ 内存管理

C++ 实现文件：

  • load_field_data_c.cpp - 字段数据加载 C 接口

2.2.7 索引加载

CGO 接口：segcore/load_index_c.h

功能：

  • ✅ 索引文件加载
  • ✅ 索引内存映射
  • ✅ 索引验证

C++ 实现文件：

  • load_index_c.cpp - 索引加载 C 接口

2.3 存储（Storage）

位置：internal/core/src/storage/

CGO 接口：storage/storage_c.h, segcore/packed_writer_c.h, segcore/packed_reader_c.h

Go 包装：internal/storagev2/packed/

功能：

2.3.1 Parquet 读写

功能：

  • ✅ Arrow RecordBatch → Parquet 文件写入
  • ✅ Parquet 文件 → Arrow RecordBatch 读取
  • ✅ 列组（Column Group）管理
  • ✅ 压缩和编码

关键代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// internal/storagev2/packed/packed_writer.go
func (pw *PackedWriter) WriteRecordBatch(recordBatch arrow.Record) error {
    // 导出 Arrow 数据到 C 结构
    cArrays := make([]CArrowArray, recordBatch.NumCols())
    cSchemas := make([]CArrowSchema, recordBatch.NumCols())
    
    for i := range recordBatch.NumCols() {
        var caa cdata.CArrowArray
        var cas cdata.CArrowSchema
        cdata.ExportArrowArray(recordBatch.Column(int(i)), &caa, &cas)
        cArrays[i] = *(*CArrowArray)(unsafe.Pointer(&caa))
        cSchemas[i] = *(*CArrowSchema)(unsafe.Pointer(&cas))
    }
    
    // 调用 C++ 写入 Parquet
    status := C.WriteRecordBatch(pw.cPackedWriter, 
        &cArrays[0], 
        &cSchemas[0], 
        cSchema)
    // ...
}

C++ 实现文件：

  • packed_writer_c.cpp - Parquet 写入 C 接口
  • packed_reader_c.cpp - Parquet 读取 C 接口
  • loon_ffi/ffi_writer_c.cpp - FFI 写入接口
  • loon_ffi/ffi_reader_c.cpp - FFI 读取接口

2.3.2 存储抽象

功能：

  • ✅ 文件系统抽象
  • ✅ 对象存储支持（S3、MinIO 等）
  • ✅ 本地文件系统支持

C++ 实现文件：

  • storage_c.cpp - 存储 C 接口

2.4 表达式执行（Expression Execution）

位置：internal/core/src/exec/expression/

功能：

  • ✅ 表达式解析和编译
  • ✅ 标量函数执行
  • ✅ 向量函数执行
  • ✅ JSON 表达式处理
  • ✅ 过滤条件评估

C++ 实现文件：

  • function/init_c.cpp - 表达式函数初始化

2.5 聚类分析（Clustering）

位置：internal/core/src/clustering/

CGO 接口：clustering/analyze_c.h

Go 包装：internal/util/analyzecgowrapper/

功能：

  • ✅ K-means 聚类
  • ✅ 数据分析和统计

关键代码：

1
2
3
4
5
6
// internal/util/analyzecgowrapper/helper.go
func Analyze(ctx context.Context, 
    analyzeInfo *indexcgopb.AnalyzeInfo) error {
    // 调用 C++ 聚类分析
    // ...
}

C++ 实现文件：

  • analyze_c.cpp - 聚类分析 C 接口
  • KmeansClustering.cpp - K-means 实现

2.6 监控（Monitor）

位置：internal/core/src/monitor/

CGO 接口：monitor/monitor_c.h

功能：

  • ✅ 性能指标收集
  • ✅ 资源使用监控
  • ✅ 指标导出

C++ 实现文件：

  • monitor_c.cpp - 监控 C 接口
  • Monitor.cpp - 监控实现

2.7 Tokenizer

位置：internal/core/src/segcore/

CGO 接口：segcore/tokenizer_c.h, segcore/token_stream_c.h

功能：

  • ✅ 文本分词
  • ✅ Token 流处理
  • ✅ 支持多种分词器

C++ 实现文件：

  • tokenizer_c.cpp - Tokenizer C 接口
  • token_stream_c.cpp - Token Stream C 接口

2.8 Future（异步操作）

位置：internal/core/src/futures/

CGO 接口：futures/future_c.h

Go 包装：internal/util/cgo/futures.go

功能：

  • ✅ 异步操作支持
  • ✅ Future/Promise 模式
  • ✅ 异步查询和检索

关键代码：

1
2
3
4
5
6
7
// internal/util/cgo/futures.go
type CFuturePtr = C.CFuturePtr

func WaitForFuture(future CFuturePtr) (*C.CProto, error) {
    result := C.WaitAndGetFuture(future)
    // ...
}

C++ 实现文件：

  • future_c.cpp - Future C 接口
  • Future.cpp - Future 实现

2.9 向量索引检查

位置：internal/core/src/segcore/

CGO 接口：segcore/check_vec_index_c.h

Go 包装：internal/proxy/cgo_util.go

功能：

  • ✅ 向量索引存在性检查
  • ✅ 索引类型验证

关键代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// internal/proxy/cgo_util.go
func CheckVecIndexWithDataTypeExist(name string, 
    dataType schemapb.DataType, 
    indexType string) (bool, error) {
    cName := C.CString(name)
    defer C.free(unsafe.Pointer(cName))
    
    cIndexType := C.CString(indexType)
    defer C.free(unsafe.Pointer(cIndexType))
    
    ret := C.CheckVecIndexWithDataTypeExist(cName, 
        C.int32_t(int32(dataType)), 
        cIndexType)
    // ...
}

三、CGO 接口设计模式

3.1 错误处理

C 结构：

1
2
3
4
typedef struct CStatus {
    int32_t error_code;
    char* error_msg;
} CStatus;

Go 处理：

1
2
3
4
5
6
7
8
9
func ConsumeCStatusIntoError(status *C.CStatus) error {
    if status.error_code == 0 {
        return nil
    }
    errorCode := status.error_code
    errorMsg := C.GoString(status.error_msg)
    C.free(unsafe.Pointer(status.error_msg))
    return merr.SegcoreError(int32(errorCode), errorMsg)
}

3.2 内存管理

原则：

  • C 分配的内存由 C 释放
  • Go 传递的字符串需要转换为 C 字符串
  • 使用 defer C.free() 确保内存释放

示例：

1
2
3
4
5
cStr := C.CString(goString)
defer C.free(unsafe.Pointer(cStr))

// 调用 C 函数
C.SomeFunction(cStr)

3.3 数据转换

Protobuf 转换：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Go Protobuf → C 内存
schemaBlob, err := proto.Marshal(req.Schema)
status := C.NewCollection(
    unsafe.Pointer(&schemaBlob[0]), 
    (C.int64_t)(len(schemaBlob)), 
    &ptr)

// C 内存 → Go Protobuf
func UnmarshalProtoLayout(protoLayout any, msg proto.Message) error {
    layout := unsafe.Pointer(reflect.ValueOf(protoLayout).Pointer())
    cProtoLayout := (*C.ProtoLayout)(layout)
    blob := (*(*[math.MaxInt32]byte)(cProtoLayout.blob))[:int(cProtoLayout.size)]
    return proto.Unmarshal(blob, msg)
}

Arrow 数据转换：

1
2
3
4
5
// Arrow RecordBatch → C Arrow Array
var caa cdata.CArrowArray
var cas cdata.CArrowSchema
cdata.ExportArrowArray(recordBatch.Column(i), &caa, &cas)
cArray := (*CArrowArray)(unsafe.Pointer(&caa))

四、性能优化考虑

4.1 CGO 调用开销

问题：

  • CGO 调用有固定开销（约 50-100ns）
  • 跨语言边界数据拷贝
  • 线程切换开销

优化策略：

  1. 批量操作：减少 CGO 调用次数
  2. 零拷贝：使用 Arrow C Data Interface
  3. 异步操作：使用 Future 模式
  4. 线程池：复用 CGO 线程

4.2 线程管理

CGO 线程绑定：

1
2
3
4
5
6
7
// internal/proxy/cgo_util.go
func initDynamicPool() {
    pool := conc.NewPool[any](
        hardware.GetCPUNum(),
        conc.WithPreHandler(runtime.LockOSThread), // 锁定 OS 线程
    )
}

原因：

  • CGO 调用需要在同一线程
  • 避免线程切换开销
  • 保证线程安全

4.3 内存管理优化

策略：

  • 使用对象池减少分配
  • 预分配缓冲区
  • 及时释放 C 内存

五、主要使用场景

5.1 QueryNode 中的使用

场景：

  • Segment 加载和管理
  • 查询执行（Search/Retrieve）
  • 结果归并
  • 索引加载

关键文件：

  • internal/querynodev2/segments/segment.go
  • internal/util/segcore/

5.2 DataNode 中的使用

场景：

  • 索引构建
  • 字段数据加载
  • 存储读写

关键文件：

  • internal/util/indexcgowrapper/
  • internal/datanode/index/

5.3 Proxy 中的使用

场景：

  • 向量索引检查
  • 参数验证

关键文件：

  • internal/proxy/cgo_util.go

5.4 StorageV2 写入流程

场景：

  • Arrow Record → Parquet 文件
  • 列组管理
  • 压缩和编码

关键文件：

  • internal/storagev2/packed/packed_writer.go
  • internal/core/src/segcore/packed_writer_c.cpp

六、C++ 核心模块总结

模块CGO 接口Go 包装主要功能
索引构建indexbuilder/index_c.hinternal/util/indexcgowrapper/向量/标量/文本索引构建
Collectionsegcore/collection_c.hinternal/util/segcore/collection.goCollection 管理
Segmentsegcore/segment_c.hinternal/util/segcore/segment.goSegment 操作（Insert/Delete/Load）
查询计划segcore/plan_c.hinternal/util/segcore/plan.go查询计划生成
结果归并segcore/reduce_c.hinternal/util/segcore/reduce.go多段结果归并
向量索引segcore/vector_index_c.hinternal/util/vecindexmgr/向量索引操作
存储storage/storage_c.hinternal/storagev2/packed/Parquet 读写
Parquet 写入segcore/packed_writer_c.hinternal/storagev2/packed/packed_writer.goArrow → Parquet
Parquet 读取segcore/packed_reader_c.hinternal/storagev2/packed/packed_reader.goParquet → Arrow
聚类分析clustering/analyze_c.hinternal/util/analyzecgowrapper/K-means 聚类
监控monitor/monitor_c.h-性能监控
Tokenizersegcore/tokenizer_c.h-文本分词
Futurefutures/future_c.hinternal/util/cgo/futures.go异步操作

七、总结

7.1 设计优势

  1. ✅ 性能：核心路径使用 C++，充分利用硬件优化
  2. ✅ 可维护性：Go 代码简洁，易于维护
  3. ✅ 生态：利用 C++ 生态（Arrow、Parquet、Knowhere 等）
  4. ✅ 灵活性：可以逐步迁移功能到 C++

7.2 关键设计原则

  1. 清晰的接口边界：C 接口封装 C++ 实现
  2. 统一错误处理：CStatus 统一错误格式
  3. 内存安全：明确的内存管理责任
  4. 性能优化：减少 CGO 调用，使用零拷贝

7.3 未来方向

  • 继续优化 CGO 调用开销
  • 更多功能迁移到 C++
  • 更好的异步支持
  • 改进内存管理策略

Milvus 的 C++/CGO 集成设计为系统提供了高性能和可维护性的良好平衡，是混合语言架构的优秀实践。

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>Milvus 采用混合架构设计，核心性能关键路径使用 C++ 实现，通过 CGO（C Go）提供给 Go 代码调用。这种设计既保证了性能，又 Milvus StorageV2 写入流程分析 https://szza.github.io/2025/08/09/Milvus/12_storagev2_write_flow_analysis/ 2025-08-09T15:00:00.000Z 2026-01-06T13:10:48.068Z 概述

StorageV2 是 Milvus 的新一代存储格式，使用 Apache Arrow + Parquet 技术栈，相比 StorageV1（Binlog 格式）具有更高的压缩率和查询性能。本文档详细分析 StorageV2 的完整写入流程。

一、整体架构

1.1 数据流向

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
用户 Insert/Delete 请求
    ↓
WriteBuffer.BufferData()        // 缓存数据到内存
    ↓
triggerSync()                   // 触发同步
    ↓
getSyncTask()                   // 创建 SyncTask
    ├─ yieldBuffer()            // 从 buffer 获取数据
    └─ NewSyncTask()            // 创建同步任务
    ↓
SyncTask.Run()
    ↓
BulkPackWriterV2.Write()        // StorageV2 写入
    ├─ serializeBinlog()        // InsertData → Arrow Record
    ├─ writeInserts()           // Arrow Record → Parquet
    ├─ writeStats()             // 写入统计信息
    ├─ writeDelta()             // 写入删除数据
    └─ writeBM25Stasts()        // 写入 BM25 统计
    ↓
PackedRecordWriter.Write()      // 写入 Parquet 文件
    ↓
对象存储 (MinIO/S3/Local)

1.2 关键组件

组件职责位置
WriteBuffer内存缓冲区，缓存写入数据internal/flushcommon/writebuffer/
SyncTask同步任务，负责将数据写入存储internal/flushcommon/syncmgr/task.go
BulkPackWriterV2StorageV2 写入器internal/flushcommon/syncmgr/pack_writer_v2.go
PackedRecordWriterArrow Record → Parquet 转换器internal/storage/record_writer.go
PackedWriter底层 Parquet 写入器（C++ FFI）internal/storagev2/packed/

二、详细流程分析

2.1 数据准备阶段（WriteBuffer → SyncPack）

文件: internal/flushcommon/writebuffer/write_buffer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func (wb *writeBufferBase) getSyncTask(ctx context.Context, segmentID int64) (syncmgr.Task, error) {
    // 1. 从 WriteBuffer 中提取数据
    insert, bm25, delta, schema, timeRange, startPos := wb.yieldBuffer(segmentID)
    
    // 2. 构建 SyncPack
    pack := &syncmgr.SyncPack{}
    pack.WithInsertData(insert).      // InsertData 数组
        WithDeleteData(delta).         // DeleteData
        WithBM25Stats(bm25).           // BM25 统计
        WithCollectionID(wb.collectionID).
        WithPartitionID(segmentInfo.PartitionID()).
        WithSegmentID(segmentID).
        WithTimeRange(tsFrom, tsTo).   // Timestamp 范围
        WithBatchRows(batchSize)
    
    // 3. 创建 SyncTask
    task := syncmgr.NewSyncTask(...)
    return task, nil
}

关键数据结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// InsertData 包含所有字段的数据
type InsertData struct {
    Data map[FieldID]FieldData  // map[fieldID]FieldData
    RowNum() int
    GetMemorySize() int64
}

// SyncPack 包含一次同步的所有数据
type SyncPack struct {
    insertData []*storage.InsertData  // 插入数据
    deltaData  *storage.DeleteData     // 删除数据
    bm25Stats  map[int64]*storage.BM25Stats
    tsFrom, tsTo typeutil.Timestamp   // Timestamp 范围
    collectionID, partitionID, segmentID int64
    // ...
}

2.2 SyncTask 执行阶段

文件: internal/flushcommon/syncmgr/task.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
func (t *SyncTask) Run(ctx context.Context) (err error) {
    // 1. 获取段信息和列组配置
    segmentInfo, has := t.metacache.GetSegmentByID(t.segmentID)
    columnGroups := t.getColumnGroups(segmentInfo)
    
    // 2. 根据 StorageVersion 选择写入器
    switch segmentInfo.GetStorageVersion() {
    case storage.StorageV2:
        writer := NewBulkPackWriterV2(
            t.metacache, t.schema, t.chunkManager, t.allocator,
            0, packed.DefaultMultiPartUploadSize,
            t.storageConfig, columnGroups, t.writeRetryOpts...)
        
        // 3. 执行写入
        t.insertBinlogs, t.deltaBinlog, t.statsBinlogs, 
        t.bm25Binlogs, t.manifestPath, t.flushedSize, err = 
            writer.Write(ctx, t.pack)
    }
    
    return err
}

2.3 BulkPackWriterV2 写入阶段

文件: internal/flushcommon/syncmgr/pack_writer_v2.go

2.3.1 Write 方法主流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
func (bw *BulkPackWriterV2) Write(ctx context.Context, pack *SyncPack) (
    inserts map[int64]*datapb.FieldBinlog,
    deltas *datapb.FieldBinlog,
    stats map[int64]*datapb.FieldBinlog,
    bm25Stats map[int64]*datapb.FieldBinlog,
    manifest string,
    size int64,
    err error,
) {
    // 1. 预分配 ID
    err = bw.prefetchIDs(pack)
    
    // 2. 写入插入数据（核心步骤）
    if inserts, manifest, err = bw.writeInserts(ctx, pack); err != nil {
        return
    }
    
    // 3. 写入统计信息
    if stats, err = bw.writeStats(ctx, pack); err != nil {
        return
    }
    
    // 4. 写入删除数据
    if deltas, err = bw.writeDelta(ctx, pack); err != nil {
        return
    }
    
    // 5. 写入 BM25 统计
    if bm25Stats, err = bw.writeBM25Stasts(ctx, pack); err != nil {
        return
    }
    
    size = bw.sizeWritten
    return
}

2.3.2 serializeBinlog：InsertData → Arrow Record

关键步骤：将内存中的 InsertData 转换为 Arrow Record

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
func (bw *BulkPackWriterV2) serializeBinlog(_ context.Context, pack *SyncPack) (storage.Record, error) {
    if len(pack.insertData) == 0 {
        return nil, nil
    }
    
    // 1. 将 Milvus Schema 转换为 Arrow Schema
    arrowSchema, err := storage.ConvertToArrowSchema(bw.schema, true)
    if err != nil {
        return nil, err
    }
    
    // 2. 创建 Arrow RecordBuilder
    builder := array.NewRecordBuilder(memory.DefaultAllocator, arrowSchema)
    defer builder.Release()
    
    // 3. 遍历所有 InsertData chunk，构建 Arrow Record
    for _, chunk := range pack.insertData {
        if err := storage.BuildRecord(builder, chunk, bw.schema); err != nil {
            return nil, err
        }
    }
    
    // 4. 创建 Arrow Record
    rec := builder.NewRecord()
    
    // 5. 构建 FieldID 到列索引的映射
    allFields := typeutil.GetAllFieldSchemas(bw.schema)
    field2Col := make(map[storage.FieldID]int, len(allFields))
    for c, field := range allFields {
        field2Col[field.FieldID] = c
    }
    
    // 6. 返回 SimpleArrowRecord（包含 FieldID 映射）
    return storage.NewSimpleArrowRecord(rec, field2Col), nil
}

BuildRecord 详细过程（internal/storage/serde.go）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
func BuildRecord(b *array.RecordBuilder, data *InsertData, schema *schemapb.CollectionSchema) error {
    idx := 0
    
    serializeField := func(field *schemapb.FieldSchema) error {
        fBuilder := b.Field(idx)  // 获取对应字段的 Builder
        idx++
        
        // 获取字段数据
        fieldData, exists := data.Data[field.FieldID]
        if !exists {
            return merr.WrapErrFieldNotFound(field.FieldID, ...)
        }
        
        // 根据字段类型获取序列化函数
        typeEntry := serdeMap[field.DataType]
        
        // 逐行序列化数据到 Arrow Builder
        for j := 0; j < fieldData.RowNum(); j++ {
            ok = typeEntry.serialize(fBuilder, fieldData.GetRow(j), elementType)
            if !ok {
                return merr.WrapErrServiceInternal(...)
            }
        }
        return nil
    }
    
    // 序列化所有字段（包括 timestamp field）
    for _, field := range schema.GetFields() {
        if err := serializeField(field); err != nil {
            return err
        }
    }
    
    // 序列化结构体数组字段
    for _, structField := range schema.GetStructArrayFields() {
        for _, field := range structField.GetFields() {
            if err := serializeField(field); err != nil {
                return err
            }
        }
    }
    
    return nil
}

类型映射示例：

Milvus 类型Arrow 类型说明
DataType_Int64arrow.Int64Type64 位整数
DataType_FloatVectorarrow.FixedSizeBinaryType{ByteWidth: dim * 4}固定大小二进制（向量）
DataType_Timestamparrow.Int64TypeTimestamp 作为 Int64 存储
DataType_JSONarrow.BinaryTypeJSON 作为二进制存储

2.3.3 writeInserts：Arrow Record → Parquet 文件

核心流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
func (bw *BulkPackWriterV2) writeInserts(ctx context.Context, pack *SyncPack) (
    map[int64]*datapb.FieldBinlog, string, error) {
    
    // 1. 序列化为 Arrow Record
    rec, err := bw.serializeBinlog(ctx, pack)
    if err != nil {
        return nil, "", err
    }
    
    // 2. 提取 Timestamp 列并计算范围
    tsArray := rec.Column(common.TimeStampField).(*array.Int64)
    rows := rec.Len()
    var tsFrom uint64 = math.MaxUint64
    var tsTo uint64 = 0
    for i := 0; i < rows; i++ {
        ts := typeutil.Timestamp(tsArray.Value(i))
        if ts < tsFrom {
            tsFrom = ts
        }
        if ts > tsTo {
            tsTo = ts
        }
    }
    
    // 3. 准备写入函数
    doWrite := func(w storage.RecordWriter) error {
        if err = w.Write(rec); err != nil {  // 写入 Arrow Record
            return err
        }
        return w.Close()  // 关闭并刷新到磁盘
    }
    
    // 4. 根据配置选择写入模式
    if paramtable.Get().CommonCfg.UseLoonFFI.GetAsBool() {
        // Manifest 模式：使用 FFI 写入器
        basePath := path.Join(bw.getRootPath(), common.SegmentInsertLogPath, k)
        w, err := storage.NewPackedRecordManifestWriter(
            bucketName, basePath, bw.schema, 
            bw.bufferSize, bw.multiPartUploadSize, 
            columnGroups, bw.storageConfig, pluginContextPtr)
        if err = doWrite(w); err != nil {
            return nil, "", err
        }
        manifestPath = w.GetWrittenManifest()
    } else {
        // 普通模式：每个列组一个文件
        paths := make([]string, 0)
        for _, columnGroup := range columnGroups {
            path := metautil.BuildInsertLogPath(
                bw.getRootPath(), pack.collectionID, 
                pack.partitionID, pack.segmentID, 
                columnGroup.GroupID, bw.nextID())
            paths = append(paths, path)
        }
        
        w, err := storage.NewPackedRecordWriter(
            bucketName, paths, bw.schema, 
            bw.bufferSize, bw.multiPartUploadSize, 
            columnGroups, bw.storageConfig, pluginContextPtr)
        if err = doWrite(w); err != nil {
            return nil, "", err
        }
    }
    
    // 5. 构建 Binlog 元数据
    logs := make(map[int64]*datapb.FieldBinlog)
    for _, columnGroup := range columnGroups {
        logs[columnGroupID] = &datapb.FieldBinlog{
            FieldID:     columnGroupID,
            ChildFields: columnGroup.Fields,
            Binlogs: []*datapb.Binlog{
                {
                    LogSize:       int64(w.GetColumnGroupWrittenCompressed(columnGroup.GroupID)),
                    MemorySize:    int64(w.GetColumnGroupWrittenUncompressed(columnGroup.GroupID)),
                    LogPath:       w.GetWrittenPaths(columnGroupID),
                    EntriesNum:    w.GetWrittenRowNum(),
                    TimestampFrom: tsFrom,
                    TimestampTo:   tsTo,
                },
            },
        }
    }
    
    return logs, manifestPath, nil
}

2.4 PackedRecordWriter：Arrow → Parquet 转换

文件: internal/storage/record_writer.go

2.4.1 Write 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
func (pw *packedRecordWriter) Write(r Record) error {
    // 1. 将 Record 转换为 Arrow Record
    var rec arrow.Record
    if sar, ok := r.(*simpleArrowRecord); ok {
        rec = sar.r  // 直接使用 Arrow Record
    } else {
        // 从 Record 接口构建 Arrow Record
        allFields := typeutil.GetAllFieldSchemas(pw.schema)
        arrays := make([]arrow.Array, len(allFields))
        for i, field := range allFields {
            arrays[i] = r.Column(field.FieldID)
        }
        rec = array.NewRecord(pw.arrowSchema, arrays, int64(r.Len()))
    }
    
    // 2. 统计写入大小（按列组）
    pw.rowNum += int64(r.Len())
    for col, arr := range rec.Columns() {
        size := calculateActualDataSize(arr)
        pw.writtenUncompressed += size
        for _, columnGroup := range pw.columnGroups {
            if lo.Contains(columnGroup.Columns, col) {
                pw.columnGroupUncompressed[columnGroup.GroupID] += size
                break
            }
        }
    }
    
    // 3. 调用底层 PackedWriter 写入
    defer rec.Release()
    return pw.writer.WriteRecordBatch(rec)  // 写入 Arrow RecordBatch
}

2.4.2 PackedWriter（C++ FFI）

文件: internal/storagev2/packed/packed_writer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
func (pw *PackedWriter) WriteRecordBatch(recordBatch arrow.Record) error {
    // 1. 导出 Arrow Array 和 Schema 到 C 结构
    cArrays := make([]CArrowArray, recordBatch.NumCols())
    cSchemas := make([]CArrowSchema, recordBatch.NumCols())
    
    for i := range recordBatch.NumCols() {
        var caa cdata.CArrowArray
        var cas cdata.CArrowSchema
        cdata.ExportArrowArray(recordBatch.Column(int(i)), &caa, &cas)
        cArrays[i] = *(*CArrowArray)(unsafe.Pointer(&caa))
        cSchemas[i] = *(*CArrowSchema)(unsafe.Pointer(&cas))
    }
    
    // 2. 导出 Arrow Schema
    var cas cdata.CArrowSchema
    cdata.ExportArrowSchema(recordBatch.Schema(), &cas)
    cSchema := (*C.struct_ArrowSchema)(unsafe.Pointer(&cas))
    
    // 3. 调用 C++ 函数写入 Parquet
    status := C.WriteRecordBatch(pw.cPackedWriter, &cArrays[0], &cSchemas[0], cSchema)
    if err := ConsumeCStatusIntoError(&status); err != nil {
        return err
    }
    
    return nil
}

底层 C++ 实现（internal/core/src/segcore/packed_writer_c.cpp）：

1
2
3
4
5
6
7
8
9
10
11
// C++ 端接收 Arrow RecordBatch，写入 Parquet 文件
Status WriteRecordBatch(PackedWriter* writer, 
                        ArrowArray* arrays, 
                        ArrowSchema* schemas, 
                        ArrowSchema* schema) {
    // 1. 导入 Arrow 数据到 C++ Arrow 对象
    auto record_batch = ImportRecordBatch(arrays, schemas, schema);
    
    // 2. 调用 PackedRecordBatchWriter 写入 Parquet
    return writer->packed_writer_->Write(record_batch);
}

三、列组（Column Group）机制

3.1 列组概念

列组是 StorageV2 的重要优化机制，将相关字段组织在一起，减少文件数量，提高查询效率。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 列组配置示例
columnGroups := []storagecommon.ColumnGroup{
    {
        GroupID: 100,  // 主键组
        Fields:  []int64{0},  // 主键字段
        Columns: []int{0},    // Arrow 列索引
    },
    {
        GroupID: 101,  // 向量组
        Fields:  []int64{100},  // 向量字段
        Columns: []int{1},      // Arrow 列索引
    },
    {
        GroupID: 102,  // 标量字段组
        Fields:  []int64{1, 2, 3},  // 多个标量字段
        Columns: []int{2, 3, 4},     // Arrow 列索引
    },
}

3.2 列组的作用

  1. 减少文件数量：多个字段可以写入同一个 Parquet 文件
  2. 优化查询：相关字段在一起，减少 I/O
  3. 支持列剪枝：查询时只读取需要的列组

3.3 文件路径结构

普通模式：

1
2
3
4
5
{rootPath}/{collectionID}/{partitionID}/{segmentID}/
├── insert_log/
│   ├── {columnGroupID1}/{logID}.parquet
│   ├── {columnGroupID2}/{logID}.parquet
│   └── {columnGroupID3}/{logID}.parquet

Manifest 模式：

1
2
3
4
5
6
7
{rootPath}/{collectionID}/{partitionID}/{segmentID}/
├── insert_log/
│   ├── {columnGroupID1}/
│   │   └── {logID}.parquet
│   ├── {columnGroupID2}/
│   │   └── {logID}.parquet
│   └── manifest.json  # 统一元数据清单

四、关键优化点

4.1 零拷贝转换

  • Arrow Record 在内存中直接使用，无需序列化
  • Go → C++ 通过 FFI 传递 Arrow C Data Interface，零拷贝
  • Arrow → Parquet 使用 Arrow 的 Parquet 写入器，高效转换

4.2 批量写入

  • 使用 RecordBatch 批量写入，减少 I/O 次数
  • 支持缓冲写入，提高吞吐量

4.3 压缩优化

  • Parquet 使用列式压缩，压缩率高
  • 支持多种压缩算法（Zstd, Snappy, Gzip 等）
  • 在 Milvus 中默认使用 Zstd 压缩

4.4 元数据管理

  • Timestamp 范围：在写入时计算并记录
  • 统计信息：记录压缩前后大小、行数等
  • Manifest：统一管理文件元数据（Manifest 模式）

五、与 StorageV1 的对比

特性StorageV1 (Binlog)StorageV2 (Parquet)
文件格式Protobuf + 自定义编码Apache Parquet
文件组织每个字段一个文件按列组组织，多个字段一个文件
压缩率中等高（3-10倍）
查询性能需要读取多个文件列式访问，更高效
元数据每个文件独立元数据统一 Manifest 管理
Timestamp 存储独立 binlog 文件Arrow Record 的一列
类型支持基础类型支持复杂类型（JSON、嵌套结构等）

六、总结

6.1 核心流程

  1. 数据准备：WriteBuffer → SyncPack
  2. 数据转换：InsertData → Arrow Record（serializeBinlog）
  3. 数据写入：Arrow Record → Parquet 文件（writeInserts）
  4. 底层存储：通过 C++ FFI 调用 Parquet 写入器

6.2 关键技术

  • ✅ Apache Arrow：内存中的列式数据格式
  • ✅ Apache Parquet：持久化的列式存储格式
  • ✅ 列组机制：优化文件组织和查询性能
  • ✅ 零拷贝转换：Arrow → Parquet 高效转换
  • ✅ FFI 集成：Go 和 C++ 无缝协作

6.3 优势

  1. 高压缩率：节省 50-80% 存储空间
  2. 高性能：列式访问减少 60-90% I/O
  3. 灵活性：支持复杂数据类型和 Schema Evolution
  4. 兼容性：与其他大数据工具无缝集成

StorageV2 通过 Arrow + Parquet 技术栈，为 Milvus 提供了高效、灵活、可扩展的存储解决方案。

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>StorageV2 是 Milvus 的新一代存储格式，使用 Apache Arrow + Parquet 技术栈，相比 StorageV1 Arrow 和 Parquet 优势分析 https://szza.github.io/2025/08/09/Milvus/12_arrow_parquet_advantages_analysis/ 2025-08-09T14:00:00.000Z 2026-01-06T13:10:47.525Z 概述

在 Milvus 中，Apache Arrow 和 Apache Parquet 被广泛用于数据存储和处理。两者结合使用，形成了高效的数据处理链路：

  • Arrow：作为内存中的列式数据格式，用于数据构建和处理
  • Parquet：作为持久化存储格式，用于数据序列化和磁盘存储

一、Apache Arrow 的优势

1.1 零拷贝（Zero-Copy）内存布局

优势：

  • Arrow 使用列式内存布局，数据在内存中以连续的方式存储
  • 支持零拷贝操作，多个进程或组件可以共享同一块内存，无需数据复制
  • 减少内存占用和 CPU 开销

在 Milvus 中的应用：

1
2
3
4
// internal/storage/payload_writer.go
// Arrow Builder 直接构建列式数据结构
builder := array.NewBuilder(mem, arrowType)
// 数据可以直接在内存中操作，无需序列化/反序列化

1.2 跨语言互操作性

优势：

  • Arrow 定义了标准的内存格式规范，支持多种编程语言（C++, Go, Python, Java, Rust 等）
  • 不同语言编写的组件可以直接共享 Arrow 数据，无需序列化转换
  • 在 Milvus 中，Go 和 C++ 组件可以无缝交换数据

在 Milvus 中的应用：

1
2
3
4
// internal/core/src/storage/PayloadReader.cpp
// C++ 代码可以直接读取 Arrow 格式的数据
auto input = std::make_shared<arrow::io::BufferReader>(data, length);
parquet::arrow::FileReaderBuilder reader_builder;

1.3 高效的列式操作

优势：

  • 列式存储使得按列访问数据非常高效
  • 支持向量化操作（SIMD），可以批量处理数据
  • 适合分析型查询，只需要读取相关列

在 Milvus 中的应用：

1
2
3
4
// internal/storage/schema.go
// Arrow Schema 定义了列式结构
func ConvertToArrowSchema(schema *schemapb.CollectionSchema, useFieldID bool) (*arrow.Schema, error)
// 每个字段对应一个 Arrow Field，支持高效的列式访问

1.4 丰富的数据类型支持

优势：

  • Arrow 支持丰富的数据类型，包括基本类型、嵌套类型、向量类型等
  • 支持 Nullable 类型，可以高效处理缺失值
  • 支持固定大小和可变大小的二进制类型（适合向量数据）

在 Milvus 中的应用：

1
2
3
4
5
6
7
8
9
10
// internal/storage/payload_writer.go
func MilvusDataTypeToArrowType(dataType schemapb.DataType, dim int) arrow.DataType {
    switch dataType {
    case schemapb.DataType_FloatVector:
        return &arrow.FixedSizeBinaryType{ByteWidth: dim * 4}
    case schemapb.DataType_BinaryVector:
        return &arrow.FixedSizeBinaryType{ByteWidth: dim / 8}
    // ... 支持多种向量类型
    }
}

1.5 内存管理优化

优势：

  • Arrow 使用引用计数管理内存，自动释放不需要的数据
  • 支持内存池（Memory Pool），减少内存分配开销
  • 可以预分配内存，提高写入性能

在 Milvus 中的应用：

1
2
3
4
5
6
7
8
9
10
// internal/storage/payload_writer.go
func (w *NativePayloadWriter) Reserve(size int) {
    w.builder.Reserve(size)  // 预分配内存
}

func (w *NativePayloadWriter) ReleasePayloadWriter() {
    w.releaseOnce.Do(func() {
        w.builder.Release()  // 释放内存
    })
}

二、Apache Parquet 的优势

2.1 高压缩率

优势：

  • Parquet 使用列式存储，相同类型的数据聚集在一起，压缩效果更好
  • 支持多种压缩算法（Snappy, Gzip, Zstd, LZ4 等）
  • 在 Milvus 中，压缩率通常比行式存储高 3-10 倍

在 Milvus 中的应用：

1
2
3
4
5
// internal/storage/payload_writer.go
writerProps := parquet.NewWriterProperties(
    parquet.WithCompression(compress.Codecs.Zstd),  // 使用 Zstd 压缩
    parquet.WithCompressionLevel(3),
)

2.2 列式存储优化

优势：

  • 列式存储使得查询只需要读取相关列，大幅减少 I/O
  • 支持列剪枝（Column Pruning），只读取需要的列
  • 适合 OLAP 场景，特别是聚合查询

在 Milvus 中的应用：

1
2
3
// docs/developer_guides/milvus_timestamp_write_flow.md
// StorageV2 使用 Parquet 格式，支持列式访问
// 查询时只需要读取相关字段，不需要读取整个文件

2.3 丰富的元数据

优势：

  • Parquet 文件包含丰富的元数据信息（Schema、统计信息、索引等）
  • 支持 Predicate Pushdown，可以在读取前过滤数据
  • 元数据存储在文件末尾，支持快速扫描

在 Milvus 中的应用：

1
2
3
4
5
// internal/core/src/storage/PayloadReader.cpp
auto file_meta = arrow_reader->parquet_reader()->metadata();
// 可以从元数据中获取维度信息，无需读取完整数据
dim_ = GetDimensionFromFileMetaData(
    file_meta->schema()->Column(column_index), column_type_)

2.4 支持嵌套数据结构

优势：

  • Parquet 支持复杂的嵌套数据结构（Struct, List, Map）
  • 可以高效存储 JSON、数组等复杂类型
  • 支持 Schema Evolution，可以向后兼容地修改 Schema

在 Milvus 中的应用：

1
2
3
// docs/design_docs/json_storage.md
// Parquet 支持存储 JSON 数据，使用列式存储优化查询性能
// Dense 字段存储为独立列，Sparse 字段存储为 BSON 二进制列

2.5 跨平台兼容性

优势：

  • Parquet 是开放标准，被广泛支持（Hadoop, Spark, Presto, Pandas 等）
  • 可以与其他大数据工具无缝集成
  • 支持多种编程语言的读写库

在 Milvus 中的应用：

1
2
3
// internal/util/importutilv2/parquet/reader.go
// Milvus 支持从 Parquet 文件导入数据
// 可以与其他系统（如 Spark）生成的数据文件兼容

三、Arrow + Parquet 组合优势

3.1 无缝转换

优势：

  • Arrow 和 Parquet 可以无缝转换，无需中间格式
  • Arrow RecordBatch 可以直接写入 Parquet 文件
  • Parquet 文件可以直接读取为 Arrow RecordBatch

在 Milvus 中的应用：

1
2
3
4
5
6
7
8
9
10
11
12
// internal/storage/payload_writer.go
// Arrow Table -> Parquet 文件
return pqarrow.WriteTable(table,
    w.output,
    1024*1024*1024,
    w.writerProps,
    arrowWriterProps,
)

// internal/storage/payload_reader.go
// Parquet 文件 -> Arrow RecordBatch
arrowReader, err := pqarrow.NewFileReader(parquetReader, ...)

3.2 高效的数据处理流程

优势：

  • 内存中使用 Arrow 格式，处理速度快
  • 持久化使用 Parquet 格式，存储效率高
  • 整个流程零拷贝或最小化拷贝

在 Milvus 中的应用：

1
2
3
4
BulkPackWriterV2.Write()
  └─> serializeBinlog() -> Arrow Record  (内存处理)
      └─> PackedRecordWriter.Write()
          └─> Parquet Writer (持久化存储)

3.3 统一的 Schema 管理

优势：

  • Arrow Schema 和 Parquet Schema 可以相互转换
  • 统一的类型系统，减少类型转换开销
  • 支持 Schema 验证，确保数据一致性

在 Milvus 中的应用：

1
2
3
// internal/storage/schema.go
// Milvus Schema -> Arrow Schema -> Parquet Schema
func ConvertToArrowSchema(schema *schemapb.CollectionSchema, useFieldID bool) (*arrow.Schema, error)

四、在 Milvus 中的实际效果

4.1 StorageV1 vs StorageV2 对比

根据 docs/developer_guides/milvus_timestamp_write_flow.md 的对比：

特性StorageV1 (Binlog)StorageV2 (Parquet)
文件格式Protobuf + 自定义编码Apache Parquet
文件数量多个（每个 field 一个）少量（按列组组织）
压缩率中等高
查询性能需要读取多个文件列式访问更高效
元数据每个 binlog 独立元数据统一 manifest 管理

4.2 性能提升

  1. 存储空间：Parquet 的高压缩率可以节省 50-80% 的存储空间
  2. 查询速度：列式访问可以减少 60-90% 的 I/O 操作
  3. 内存效率：Arrow 的零拷贝机制可以减少 30-50% 的内存使用

4.3 功能增强

  1. 支持复杂类型：Arrow + Parquet 支持向量数组、JSON、嵌套结构等
  2. 更好的兼容性：可以与其他大数据工具无缝集成
  3. 更灵活的查询：支持列剪枝、谓词下推等优化

五、总结

Arrow 的核心优势

  1. ✅ 零拷贝内存布局：高效的内存操作
  2. ✅ 跨语言互操作：无缝的数据交换
  3. ✅ 列式操作优化：适合分析型查询
  4. ✅ 丰富的数据类型：支持复杂数据结构
  5. ✅ 内存管理优化：自动内存管理

Parquet 的核心优势

  1. ✅ 高压缩率：节省存储空间
  2. ✅ 列式存储：优化查询性能
  3. ✅ 丰富元数据：支持查询优化
  4. ✅ 嵌套数据支持：处理复杂结构
  5. ✅ 跨平台兼容：广泛的支持

组合使用的优势

  1. ✅ 无缝转换：Arrow ↔ Parquet 零开销转换
  2. ✅ 高效流程：内存处理 + 持久化存储
  3. ✅ 统一 Schema：一致的类型系统

在 Milvus 中，Arrow + Parquet 的组合为向量数据库提供了高效、灵活、兼容的数据存储和处理能力，是 StorageV2 架构的核心技术基础。

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>在 Milvus 中，Apache Arrow 和 Apache Parquet 被广泛用于数据存储和处理。两者结合使用，形成了高效的数据处 Milvus 数据写入流程中的 MVCC Timestamp 处理 https://szza.github.io/2025/08/09/Milvus/11_milvus_timestamp_write_flow/ 2025-08-09T13:00:00.000Z 2026-01-06T13:10:47.195Z 本文档详细介绍 Milvus 中 MVCC timestamp 信息在数据写入 Segment 过程中的处理机制，包括正常 Flush 流程和 Compaction 流程。

目录

1. 概述

1.1 核心结论

是的，MVCC timestamp 信息会完整写入到 Segment 中。

Timestamp 作为系统预留字段（FieldID=1），在数据写入过程中会像其他用户字段一样被序列化并持久化到存储中。主要有两个写入路径：

  1. Flush 流程（主要路径）：正常数据写入时的持久化
  2. Compaction 流程：Segment 合并优化时的重新写入

1.2 Timestamp 的用途

  • MVCC 版本控制：支持时间旅行查询（Time Travel Query）
  • 数据可见性判断：根据 timestamp 过滤不可见的数据
  • 数据过期处理：基于 TTL 和 timestamp 清理过期数据
  • 查询优化：通过 timestamp 范围快速过滤 Segment

2. Timestamp 字段定义

2.1 系统预留字段

1
2
3
4
5
6
7
8
9
10
11
12
// pkg/common/common.go

const (
    // TimeStampField is the ID of the Timestamp field reserved by the system
    TimeStampField = 1
    
    // RowIDField is the ID of the RowID field reserved by the system
    RowIDField = 0

    // TimeStampFieldName defines the name of the Timestamp field
    TimeStampFieldName = "Timestamp"
)

2.2 数据类型

Timestamp 是 int64 类型，在 C++ 和 Go 代码中都被定义为 uint64：

1
2
3
4
// internal/core/src/common/Types.h

using Timestamp = uint64_t;
constexpr auto MAX_TIMESTAMP = std::numeric_limits<Timestamp>::max();

3. Flush 写入流程（主流程）

3.1 整体流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
用户 Insert/Delete 请求
    ↓
WriteBuffer.BufferData()        // 缓存数据到内存
    ↓
triggerSync()                   // 根据策略触发同步
    ↓
getSegmentsToSync()             // 选择需要 sync 的 segments
    ↓
syncSegments()
    ↓
getSyncTask()                   // 创建 SyncTask
    ├─ yieldBuffer()            // 从 buffer 获取数据
    └─ NewSyncTask()            // 创建同步任务
    ↓
SyncManager.SyncData()
    ↓
SyncTask.Run()
    ↓
    ├─ [StorageV1] BulkPackWriter.Write()
    │   ├─ writeInserts()
    │   │   └─ storageV1Serializer.serializeBinlog()
    │   │       └─ InsertCodec.Serialize()        ★ 序列化所有字段（包括 timestamp）
    │   │           └─ 为每个 field 创建独立的 binlog 文件
    │   │
    │   ├─ writeStats()                           ★ 写入统计信息（含 timestamp 范围）
    │   └─ writeBM25Stats()
    │
    └─ [StorageV2] BulkPackWriterV2.Write()
        ├─ writeInserts()
        │   ├─ serializeBinlog()                  // 转换为 Arrow Record
        │   ├─ 提取 timestamp 列计算范围
        │   └─ PackedRecordWriter.Write()         ★ 写入 Parquet 格式
        │
        └─ writeStats()

3.2 关键代码位置

3.2.1 WriteBuffer 创建 SyncTask

文件: internal/flushcommon/writebuffer/write_buffer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
func (wb *writeBufferBase) getSyncTask(ctx context.Context, segmentID int64) (syncmgr.Task, error) {
    segmentInfo, ok := wb.metaCache.GetSegmentByID(segmentID)
    if !ok {
        return nil, merr.WrapErrSegmentNotFound(segmentID)
    }
    
    var batchSize int64
    var tsFrom, tsTo uint64

    // 从 buffer 中获取数据，包括 insert data 和 timestamp 范围
    insert, bm25, delta, schema, timeRange, startPos := wb.yieldBuffer(segmentID)
    if timeRange != nil {
        tsFrom, tsTo = timeRange.timestampMin, timeRange.timestampMax
    }

    for _, chunk := range insert {
        batchSize += int64(chunk.GetRowNum())
    }

    // 创建 SyncPack，包含所有需要持久化的数据
    pack := &syncmgr.SyncPack{}
    pack.WithInsertData(insert).        // ★ InsertData 包含 timestamp 字段
        WithDeleteData(delta).
        WithCollectionID(wb.collectionID).
        WithPartitionID(segmentInfo.PartitionID()).
        WithSegmentID(segmentID).
        WithTimeRange(tsFrom, tsTo).    // ★ Timestamp 范围
        WithBatchRows(batchSize)

    task := syncmgr.NewSyncTask().
        WithMetaCache(wb.metaCache).
        WithSchema(schema).
        WithSyncPack(pack)
    return task, nil
}

3.2.2 SyncTask 执行写入

文件: internal/flushcommon/syncmgr/task.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
func (t *SyncTask) Run(ctx context.Context) (err error) {
    segmentInfo, has := t.metacache.GetSegmentByID(t.segmentID)
    if !has {
        return nil
    }

    columnGroups := t.getColumnGroups(segmentInfo)

    // 根据 StorageVersion 选择不同的写入方式
    switch segmentInfo.GetStorageVersion() {
    case storage.StorageV2:
        writer := NewBulkPackWriterV2(t.metacache, t.schema, t.chunkManager, 
            t.allocator, 0, packed.DefaultMultiPartUploadSize, 
            t.storageConfig, columnGroups, t.writeRetryOpts...)
        t.insertBinlogs, t.deltaBinlog, t.statsBinlogs, t.bm25Binlogs, 
            t.manifestPath, t.flushedSize, err = writer.Write(ctx, t.pack)
        
    default:  // StorageV1
        writer := NewBulkPackWriter(t.metacache, t.schema, 
            t.chunkManager, t.allocator, t.writeRetryOpts...)
        t.insertBinlogs, t.deltaBinlog, t.statsBinlogs, t.bm25Binlogs, 
            t.flushedSize, err = writer.Write(ctx, t.pack)
    }
    
    return err
}

3.2.3 StorageV1 序列化 Binlog

文件: internal/flushcommon/syncmgr/storage_serializer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
func (s *storageV1Serializer) serializeBinlog(ctx context.Context, pack *SyncPack) (map[int64]*storage.Blob, error) {
    if len(pack.insertData) == 0 {
        return make(map[int64]*storage.Blob), nil
    }
    
    // 调用 InsertCodec 序列化所有字段
    blobs, err := s.inCodec.Serialize(pack.partitionID, pack.segmentID, pack.insertData...)
    if err != nil {
        return nil, err
    }

    // 返回 map[fieldID]*Blob，包括 timestamp field (fieldID=1)
    result := make(map[int64]*storage.Blob)
    for _, blob := range blobs {
        fieldID, err := strconv.ParseInt(blob.GetKey(), 10, 64)
        if err != nil {
            return nil, err
        }
        result[fieldID] = blob
    }
    return result, nil
}

文件: internal/storage/data_codec.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
func (insertCodec *InsertCodec) Serialize(partitionID UniqueID, segmentID UniqueID, data ...*InsertData) ([]*Blob, error) {
    blobs := make([]*Blob, 0)
    
    var rowNum int64
    var startTs, endTs Timestamp
    startTs, endTs = math.MaxUint64, 0

    // 1. 首先从 timestamp 字段提取时间范围
    for _, block := range data {
        timeFieldData, ok := block.Data[common.TimeStampField]
        if !ok {
            return nil, errors.New("data doesn't contains timestamp field")
        }

        rowNum += int64(timeFieldData.RowNum())
        ts := timeFieldData.(*Int64FieldData).Data

        for _, t := range ts {
            if uint64(t) > endTs {
                endTs = uint64(t)
            }
            if uint64(t) < startTs {
                startTs = uint64(t)
            }
        }
    }

    // 2. 为每个字段创建 binlog writer（包括 timestamp）
    serializeField := func(field *schemapb.FieldSchema) error {
        // 创建字段对应的 binlog writer
        writer = NewInsertBinlogWriter(field.DataType, insertCodec.Schema.ID, 
            partitionID, segmentID, field.FieldID, field.GetNullable())

        eventWriter, err := writer.NextInsertEventWriter()
        if err != nil {
            return err
        }
        
        // 设置 timestamp 范围到 binlog 元数据
        eventWriter.SetEventTimestamp(startTs, endTs)
        
        // 将字段数据写入 payload
        for _, block := range data {
            singleData := block.Data[field.FieldID]
            if err = AddFieldDataToPayload(eventWriter, field.DataType, singleData); err != nil {
                return err
            }
        }

        // 完成并获取 blob
        buffer, err := writer.GetBuffer()
        blobs = append(blobs, &Blob{
            Key:        fmt.Sprintf("%d", field.FieldID),
            Value:      buffer,
            RowNum:     rowNum,
        })
        return nil
    }
    
    // 3. 遍历所有字段进行序列化（包括 timestamp field）
    for _, field := range insertCodec.Schema.Schema.Fields {
        if err := serializeField(field); err != nil {
            return nil, err
        }
    }

    return blobs, nil
}

3.2.4 StorageV2 写入 Parquet

文件: internal/flushcommon/syncmgr/pack_writer_v2.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
func (bw *BulkPackWriterV2) writeInserts(ctx context.Context, pack *SyncPack) (map[int64]*datapb.FieldBinlog, string, error) {
    if len(pack.insertData) == 0 {
        return make(map[int64]*datapb.FieldBinlog), "", nil
    }

    // 1. 序列化为 Arrow Record
    rec, err := bw.serializeBinlog(ctx, pack)
    if err != nil {
        return nil, "", err
    }

    logs := make(map[int64]*datapb.FieldBinlog)

    // 2. 从 Record 中提取 timestamp 列并计算范围
    tsArray := rec.Column(common.TimeStampField).(*array.Int64)
    rows := rec.Len()
    var tsFrom uint64 = math.MaxUint64
    var tsTo uint64 = 0
    for i := 0; i < rows; i++ {
        ts := typeutil.Timestamp(tsArray.Value(i))
        if ts < tsFrom {
            tsFrom = ts
        }
        if ts > tsTo {
            tsTo = ts
        }
    }

    // 3. 写入 Parquet 文件（包含所有字段，含 timestamp）
    doWrite := func(w storage.RecordWriter) error {
        if err = w.Write(rec); err != nil {  // ★ Arrow Record 包含 timestamp 列
            return err
        }
        return w.Close()
    }

    // 4. 创建 PackedRecordWriter 并写入
    if paramtable.Get().CommonCfg.UseLoonFFI.GetAsBool() {
        // Manifest 模式
        w, err := storage.NewPackedRecordManifestWriter(...)
        if err = doWrite(w); err != nil {
            return nil, "", err
        }
        manifestPath = w.GetWrittenManifest()
    } else {
        // 普通模式
        w, err := storage.NewPackedRecordWriter(...)
        if err = doWrite(w); err != nil {
            return nil, "", err
        }
    }

    // 5. 记录 binlog 信息（含 timestamp 范围）
    for _, columnGroup := range columnGroups {
        logs[columnGroup.GroupID] = &datapb.FieldBinlog{
            FieldID:     columnGroup.GroupID,
            ChildFields: columnGroup.Fields,
            Binlogs: []*datapb.Binlog{
                {
                    LogPath:       path,
                    EntriesNum:    rowNum,
                    TimestampFrom: tsFrom,  // ★ Timestamp 范围
                    TimestampTo:   tsTo,
                },
            },
        }
    }

    return logs, manifestPath, nil
}

// 序列化为 Arrow Record
func (bw *BulkPackWriterV2) serializeBinlog(_ context.Context, pack *SyncPack) (storage.Record, error) {
    // 转换 schema 为 Arrow Schema
    arrowSchema, err := storage.ConvertToArrowSchema(bw.schema, true)
    if err != nil {
        return nil, err
    }
    
    builder := array.NewRecordBuilder(memory.DefaultAllocator, arrowSchema)
    defer builder.Release()

    // 构建 Arrow Record（包含所有字段）
    for _, chunk := range pack.insertData {
        if err := storage.BuildRecord(builder, chunk, bw.schema); err != nil {
            return nil, err
        }
    }

    rec := builder.NewRecord()
    return storage.NewSimpleArrowRecord(rec, field2Col), nil
}

4. Compaction 写入流程

Compaction 是对已有 Segment 的合并和优化，也会重新写入 timestamp 信息。

4.1 整体流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Compaction Task 创建
    ↓
mixCompactionTask.Compact()
    ↓
mixCompactionTask.mergeSplit()
    ↓
NewMultiSegmentWriter()                    // 创建多 segment 写入器
    ↓
对每个源 Segment:
    ├─ storage.NewBinlogRecordReader()     // 读取原始数据
    └─ mixCompactionTask.writeSegment()
        └─ [循环读取 Record]
            ├─ reader.Next()               // 读取 Arrow Record（含 timestamp）
            ├─ 过滤已删除/过期数据
            └─ mWriter.Write(rec)          ★ 写入合并后的数据
                └─ MultiSegmentWriter.Write()
                    └─ BinlogValueWriter.Write()
                        └─ BinlogRecordWriter.Write()
                            ├─ [V1] CompositeBinlogRecordWriter.Write()
                            │   ├─ 提取 timestamp 范围
                            │   └─ 序列化为 binlog
                            │
                            └─ [V2] PackedBinlogRecordWriter.Write()
                                ├─ 提取 timestamp 范围
                                └─ 写入 Parquet

4.2 关键代码位置

4.2.1 Mix Compaction 主流程

文件: internal/datanode/compactor/mix_compactor.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
func (t *mixCompactionTask) mergeSplit(ctx context.Context) ([]*datapb.CompactionSegment, error) {
    // 创建 ID 分配器
    segIDAlloc := allocator.NewLocalAllocator(
        t.plan.GetPreAllocatedSegmentIDs().GetBegin(), 
        t.plan.GetPreAllocatedSegmentIDs().GetEnd())
    logIDAlloc := allocator.NewLocalAllocator(
        t.plan.GetPreAllocatedLogIDs().GetBegin(), 
        t.plan.GetPreAllocatedLogIDs().GetEnd())
    compAlloc := NewCompactionAllocator(segIDAlloc, logIDAlloc)
    
    // 创建 MultiSegmentWriter
    mWriter, err := NewMultiSegmentWriter(ctx, t.binlogIO, compAlloc, 
        t.plan.GetMaxSize(), t.plan.GetSchema(), t.compactionParams, 
        t.maxRows, t.partitionID, t.collectionID, t.GetChannelName(), 4096)
    if err != nil {
        return nil, err
    }

    deletedRowCount := int64(0)
    expiredRowCount := int64(0)

    // 处理每个源 segment
    for _, seg := range t.plan.GetSegmentBinlogs() {
        del, exp, err := t.writeSegment(ctx, seg, mWriter, pkField)
        if err != nil {
            return nil, err
        }
        deletedRowCount += del
        expiredRowCount += exp
    }
    
    // 关闭 writer 完成写入
    if err := mWriter.Close(); err != nil {
        return nil, err
    }
    
    return mWriter.GetCompactionSegments(), nil
}

4.2.2 写入单个 Segment

文件: internal/datanode/compactor/mix_compactor.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
func (t *mixCompactionTask) writeSegment(ctx context.Context,
    seg *datapb.CompactionSegmentBinlogs,
    mWriter *MultiSegmentWriter, 
    pkField *schemapb.FieldSchema) (deletedRowCount, expiredRowCount int64, err error) {
    
    // 1. 读取 delta log（删除记录）
    deltaPaths := make([]string, 0)
    for _, fieldBinlog := range seg.GetDeltalogs() {
        for _, binlog := range fieldBinlog.GetBinlogs() {
            deltaPaths = append(deltaPaths, binlog.GetLogPath())
        }
    }
    delta, err := compaction.ComposeDeleteFromDeltalogs(ctx, t.binlogIO, deltaPaths)
    if err != nil {
        return
    }
    entityFilter := compaction.NewEntityFilter(delta, t.plan.GetCollectionTtl(), t.currentTime)

    // 2. 创建 RecordReader 读取原始数据
    var reader storage.RecordReader
    if seg.GetManifest() != "" {
        reader, err = storage.NewManifestRecordReader(ctx, seg.GetManifest(), 
            t.plan.GetSchema(), ...)
    } else {
        reader, err = storage.NewBinlogRecordReader(ctx, seg.GetFieldBinlogs(), 
            t.plan.GetSchema(), ...)
    }
    if err != nil {
        return
    }
    defer reader.Close()

    // 3. 循环读取并写入数据
    for {
        var r storage.Record
        r, err = reader.Next()
        if err != nil {
            if err == sio.EOF {
                err = nil
                break
            }
            return
        }

        // 4. 过滤删除和过期的数据
        var (
            pkArray    = r.Column(pkField.FieldID)
            tsArray    = r.Column(common.TimeStampField).(*array.Int64)  // ★ 读取 timestamp
            sliceStart = -1
            rb         *storage.RecordBuilder
        )

        for i := range r.Len() {
            // 获取 PK 和 Timestamp
            var pk any
            switch pkField.DataType {
            case schemapb.DataType_Int64:
                pk = pkArray.(*array.Int64).Value(i)
            case schemapb.DataType_VarChar:
                pk = pkArray.(*array.String).Value(i)
            }
            ts := typeutil.Timestamp(tsArray.Value(i))
            
            // 根据 timestamp 和删除记录过滤
            if entityFilter.Filtered(pk, ts) {
                if rb == nil {
                    rb = storage.NewRecordBuilder(t.plan.GetSchema())
                }
                if sliceStart != -1 {
                    rb.Append(r, sliceStart, i)
                }
                sliceStart = -1
                continue
            }

            if sliceStart == -1 {
                sliceStart = i
            }
        }

        // 5. 写入过滤后的数据
        if rb != nil {
            if sliceStart != -1 {
                rb.Append(r, sliceStart, r.Len())
            }
            if rb.GetRowNum() > 0 {
                rec := rb.Build()
                defer rec.Release()
                err := mWriter.Write(rec)  // ★ 写入 Record（包含 timestamp）
                if err != nil {
                    return 0, 0, err
                }
            }
        } else {
            err := mWriter.Write(r)
            if err != nil {
                return 0, 0, err
            }
        }
    }

    return
}

4.2.3 MultiSegmentWriter 写入

文件: internal/datanode/compactor/segment_writer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
type MultiSegmentWriter struct {
    ctx       context.Context
    binlogIO  io.BinlogIO
    allocator *compactionAlloactor

    writer           *storage.BinlogValueWriter  // 底层 writer
    currentSegmentID typeutil.UniqueID

    maxRows     int64
    segmentSize int64
    
    schema        *schemapb.CollectionSchema
    partitionID   int64
    collectionID  int64
    
    res []*datapb.CompactionSegment
}

func (w *MultiSegmentWriter) Write(r storage.Record) error {
    // 检查是否需要轮转到新 segment
    if w.writer == nil || w.writer.GetWrittenUncompressed() >= uint64(w.segmentSize) {
        if err := w.rotateWriter(); err != nil {
            return err
        }
    }
    
    // 调用底层 writer 写入 Record
    return w.writer.Write(r)  // ★ Record 包含所有字段（含 timestamp）
}

func (w *MultiSegmentWriter) rotateWriter() error {
    // 关闭当前 writer
    if err := w.closeWriter(); err != nil {
        return err
    }

    // 分配新的 segment ID
    newSegmentID, err := w.allocator.allocSegmentID()
    if err != nil {
        return err
    }
    w.currentSegmentID = newSegmentID

    // 创建新的 BinlogRecordWriter
    rw, err := storage.NewBinlogRecordWriter(w.ctx, w.collectionID, 
        w.partitionID, newSegmentID, w.schema, w.allocator.logIDAlloc, 
        chunkSize, w.maxRows, w.rwOption...)
    if err != nil {
        return err
    }

    // 包装为 BinlogValueWriter
    w.writer = storage.NewBinlogValueWriter(rw, w.batchSize)
    return nil
}

4.2.4 底层 Record Writer

文件: internal/storage/binlog_record_writer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
func (pw *PackedBinlogRecordWriter) Write(r Record) error {
    if err := pw.initWriters(r); err != nil {
        return err
    }

    // 1. 提取 timestamp 范围
    tsArray := r.Column(common.TimeStampField).(*array.Int64)
    rows := r.Len()
    for i := 0; i < rows; i++ {
        ts := typeutil.Timestamp(tsArray.Value(i))
        if ts < pw.tsFrom {
            pw.tsFrom = ts
        }
        if ts > pw.tsTo {
            pw.tsTo = ts
        }
    }

    // 2. 收集统计信息
    if err := pw.pkCollector.Collect(r); err != nil {
        return err
    }
    if err := pw.bm25Collector.Collect(r); err != nil {
        return err
    }

    // 3. 写入数据（包含所有字段）
    err := pw.writer.Write(r)  // ★ 完整的 Arrow Record
    if err != nil {
        return err
    }
    
    pw.writtenUncompressed = pw.writer.GetWrittenUncompressed()
    return nil
}

5. Storage 层的 Timestamp 处理

5.1 Growing Segment 中的 Timestamp

文件: internal/core/src/segcore/SegmentGrowingImpl.cpp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
void SegmentGrowingImpl::load_field_data_common(
    FieldId field_id,
    size_t reserved_offset,
    const std::vector<FieldDataPtr>& field_data,
    FieldId primary_field_id,
    size_t num_rows) {
    
    // 特殊处理 timestamp 字段
    if (field_id == TimestampFieldID) {
        // query node already guarantees that the timestamp is ordered
        // fill into Segment.ConcurrentVector
        insert_record_.timestamps_.set_data_raw(reserved_offset, field_data);
        return;
    }

    // 处理其他字段...
}

5.2 Segment Writer 中的 Timestamp 追踪

文件: internal/datanode/compactor/segment_writer.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
func (w *SegmentWriter) WriteRecord(r storage.Record) error {
    // 1. 提取 timestamp 并更新范围
    tsArray := r.Column(common.TimeStampField).(*array.Int64)
    rows := r.Len()
    for i := 0; i < rows; i++ {
        ts := typeutil.Timestamp(tsArray.Value(i))
        if ts < w.tsFrom {
            w.tsFrom = ts
        }
        if ts > w.tsTo {
            w.tsTo = ts
        }

        // 2. 更新 PK 统计信息
        switch schemapb.DataType(w.pkstats.PkType) {
        case schemapb.DataType_Int64:
            pkArray := r.Column(w.GetPkID()).(*array.Int64)
            pk := &storage.Int64PrimaryKey{Value: pkArray.Value(i)}
            w.pkstats.Update(pk)
        case schemapb.DataType_VarChar:
            pkArray := r.Column(w.GetPkID()).(*array.String)
            pk := &storage.VarCharPrimaryKey{Value: pkArray.Value(i)}
            w.pkstats.Update(pk)
        }

        w.rowCount.Inc()
    }
    
    // 3. 写入完整的 Record（包含 timestamp）
    return w.writer.Write(r)
}

func (w *SegmentWriter) GetTimeRange() *writebuffer.TimeRange {
    return writebuffer.NewTimeRange(w.tsFrom, w.tsTo)
}

6. 两种存储版本对比

6.1 StorageV1 (Binlog 格式)

特点：

  • 每个字段一个独立的 binlog 文件
  • Timestamp 字段对应文件：{segmentID}/insert_log/1/{logID}
  • 使用 InsertCodec 序列化
  • Protobuf 格式存储

文件结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{collectionID}/{partitionID}/{segmentID}/
├── insert_log/
│   ├── 0/          # RowID field
│   │   └── {logID}
│   ├── 1/          # Timestamp field ★
│   │   └── {logID}
│   ├── 100/        # User field 1
│   │   └── {logID}
│   └── 101/        # User field 2
│       └── {logID}
├── delta_log/
│   └── {logID}
└── stats_log/
    └── {logID}

代码路径：

1
2
3
4
BulkPackWriter.Write()
  └─> storageV1Serializer.serializeBinlog()
      └─> InsertCodec.Serialize()
          └─> 为每个 field 创建 binlog

6.2 StorageV2 (Parquet 格式)

特点：

  • 列式存储，使用 Apache Arrow + Parquet
  • Timestamp 作为 Arrow Record 的一列
  • 支持列组（Column Group）优化
  • 更高的压缩率和查询性能

文件结构：

1
2
3
4
5
6
7
8
9
{collectionID}/{partitionID}/{segmentID}/
├── insert_log/
│   ├── {columnGroupID}/
│   │   └── {logID}.parquet  # 包含多个字段（含 timestamp）
│   └── manifest.json         # 元数据清单
├── delta_log/
│   └── {logID}
└── stats_log/
    └── {logID}

代码路径：

1
2
3
4
BulkPackWriterV2.Write()
  └─> serializeBinlog() -> Arrow Record
      └─> PackedRecordWriter.Write()
          └─> Parquet Writer (通过 FFI 调用 C++)

6.3 对比表

特性StorageV1 (Binlog)StorageV2 (Parquet)
文件格式Protobuf + 自定义编码Apache Parquet
Timestamp 存储独立 binlog 文件（FieldID=1）Arrow Record 的一列
文件数量多个（每个 field 一个）少量（按列组组织）
压缩率中等高
查询性能需要读取多个文件列式访问更高效
元数据每个 binlog 独立元数据统一 manifest 管理
序列化类InsertCodecArrow Builder
写入类BulkPackWriterBulkPackWriterV2

7. 总结

7.1 核心要点

  1. Timestamp 完整存储

    • Timestamp 作为 FieldID=1 的系统字段，在所有写入路径中都会完整持久化
    • 无论是 Flush 还是 Compaction，都会保留完整的 timestamp 信息

  2. 两种主要写入路径

    • Flush：正常数据写入的主流程，从 WriteBuffer 触发
    • Compaction：Segment 合并优化流程，读取旧数据重新写入

  3. 存储格式演进

    • StorageV1：每个字段独立 binlog 文件
    • StorageV2：列式 Parquet 格式，更高效

  4. Timestamp 的多重用途

    • MVCC 版本控制和可见性判断
    • TTL 过期数据清理
    • 查询优化（通过 timestamp 范围过滤）
    • Binlog 元数据（TimestampFrom/TimestampTo）

7.2 数据流向图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
用户数据 Insert/Delete
    ↓
[内存] WriteBuffer
    ↓ (Buffer Full / Time Trigger)
[Flush] SyncTask
    ↓
[序列化] InsertCodec / Arrow Builder
    ↓
[持久化] Binlog / Parquet 文件
    ↓ (多个小 Segment)
[Compaction] Mix/Clustering/L0 Compactor
    ↓
[合并] MultiSegmentWriter
    ↓
[持久化] 新的 Segment 文件

7.3 相关文件索引

Flush 流程：

  • internal/flushcommon/writebuffer/write_buffer.go - WriteBuffer 管理
  • internal/flushcommon/syncmgr/task.go - SyncTask 执行
  • internal/flushcommon/syncmgr/pack_writer.go - StorageV1 写入
  • internal/flushcommon/syncmgr/pack_writer_v2.go - StorageV2 写入
  • internal/flushcommon/syncmgr/storage_serializer.go - 序列化器

Compaction 流程：

  • internal/datanode/compactor/mix_compactor.go - Mix Compaction
  • internal/datanode/compactor/segment_writer.go - Segment Writer
  • internal/datanode/compactor/clustering_compactor.go - Clustering Compaction

Storage 层：

  • internal/storage/data_codec.go - InsertCodec 序列化
  • internal/storage/binlog_record_writer.go - Binlog 写入
  • internal/storage/record_writer.go - Parquet 写入
  • internal/storage/serde_events.go - 事件序列化

C++ 核心：

  • internal/core/src/segcore/SegmentGrowingImpl.cpp - Growing Segment
  • internal/core/src/segcore/ChunkedSegmentSealedImpl.cpp - Sealed Segment

7.4 扩展阅读

相关设计文档：

  • docs/developer_guides/flush_pipeline_write_buffer_manager.md
  • docs/developer_guides/flush_pipeline_flush_checkpoint.md
  • docs/design_docs/segcore/segment_sealed.md

附录：术语表

术语说明
MVCCMulti-Version Concurrency Control，多版本并发控制
Timestamp系统预留字段（FieldID=1），用于 MVCC 版本控制
Flush将内存中的数据持久化到存储的过程
CompactionSegment 合并优化，将多个小 Segment 合并为大 Segment
WriteBuffer数据写入的内存缓冲区
SyncTask数据同步任务，负责将 buffer 数据持久化
BinlogBinary Log，二进制日志，Milvus 的数据文件格式之一
ParquetApache Parquet，列式存储格式，StorageV2 使用
Arrow RecordApache Arrow 的数据记录格式，内存中的列式数据表示
Growing Segment增长中的 Segment，正在接收写入
Sealed Segment已封存的 Segment，不再接收新数据
InsertCodecInsert 数据的编解码器，用于 StorageV1
TTLTime To Live，数据存活时间

文档版本: v1.1
最后更新: 2025-01-24
适用 Milvus 版本: 2.5.x

附录 A：Segment 内部 Layout

A.1 Segment 类型概述

Milvus 中有两种主要的 Segment 类型：

Growing Segment (增长中的 Segment)

  • 状态: SegmentState_Growing
  • 特点: 正在接收写入操作
  • 实现类: SegmentGrowingImpl
  • 数据结构: 使用 ConcurrentVector 存储，支持并发写入
  • 索引: 可选的 interim index（临时索引）

Sealed Segment (封存的 Segment)

  • 状态: SegmentState_Sealed / SegmentState_Flushing / SegmentState_Flushed
  • 特点: 不再接收写入，数据已持久化
  • 实现类: ChunkedSegmentSealedImpl
  • 数据结构: 使用 ChunkedColumnInterface 存储，支持 mmap 和延迟加载
  • 索引: 可以加载永久索引

A.2 Growing Segment 内部结构

A.2.1 核心组件

文件: internal/core/src/segcore/SegmentGrowingImpl.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class SegmentGrowingImpl : public SegmentGrowing {
private:
    // 1. Schema 和元数据
    SchemaPtr schema_;                    // Collection schema
    IndexMetaPtr index_meta_;             // Index metadata
    SegcoreConfig segcore_config_;        // Segment 配置
    int64_t id_;                          // Segment ID

    // 2. 插入数据记录 ★ 核心数据结构
    InsertRecord<false> insert_record_;
    
    // 3. 索引记录 (Growing Index)
    IndexingRecord indexing_record_;
    
    // 4. 删除记录
    DeletedRecord<false> deleted_record_;
    
    // 5. 统计信息
    SegmentStats stats_{};
    
    // 6. 并发控制
    mutable std::shared_mutex chunk_mutex_;
    
    // 7. mmap 管理
    storage::MmapChunkDescriptorPtr mmap_descriptor_;
};

A.2.2 InsertRecord 数据布局

文件: internal/core/src/segcore/InsertRecord.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class InsertRecordGrowing {
public:
    // ★ Timestamp 列 (系统字段)
    ConcurrentVector<Timestamp> timestamps_;
    
    // ★ Timestamp 索引（用于时间旅行查询）
    TimestampIndex timestamp_index_;
    
    // ★ PK 到 Offset 的映射（用于快速查找）
    std::unique_ptr<OffsetMap> pk2offset_;
    
    // ★ 预分配的空间
    std::atomic<int64_t> reserved = 0;
    
    // ★ 响应器（用于并发控制）
    AckResponder ack_responder_;

private:
    // ★ 字段数据存储 (map[FieldID] -> Vector)
    std::unordered_map<FieldId, std::unique_ptr<VectorBase>> data_{};
    
    // ★ Nullable 字段的 valid 数据
    std::unordered_map<FieldId, ThreadSafeValidDataPtr> valid_data_{};
    
    // 并发保护
    mutable std::shared_mutex shared_mutex_{};
};

A.2.3 数据组织方式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Growing Segment Memory Layout:
┌─────────────────────────────────────────────────┐
│  SegmentGrowingImpl                              │
├─────────────────────────────────────────────────┤
│  insert_record_ (InsertRecordGrowing)           │
│  ├─ timestamps_: ConcurrentVector<Timestamp>    │  ★ Timestamp 列
│  ├─ timestamp_index_: TimestampIndex           │  ★ Timestamp 索引
│  ├─ pk2offset_: OffsetMap                       │  ★ PK 索引
│  └─ data_: map<FieldId, VectorBase>            │  ★ 字段数据
│      ├─ FieldID=100: ConcurrentVector<int64>   │     (用户字段1)
│      ├─ FieldID=101: ConcurrentVector<float>   │     (用户字段2)
│      ├─ FieldID=102: ConcurrentVector<vector>  │     (向量字段)
│      └─ ...                                     │
├─────────────────────────────────────────────────┤
│  indexing_record_ (IndexingRecord)              │
│  ├─ Chunk-level indexes                        │  ★ 分块索引
│  └─ Interim vector indexes                     │  ★ 临时向量索引
├─────────────────────────────────────────────────┤
│  deleted_record_ (DeletedRecord)                │
│  └─ Deleted PKs with timestamps                │  ★ 删除记录
└─────────────────────────────────────────────────┘

A.2.4 Chunk 机制

Growing Segment 使用 Chunk 机制组织数据：

  • Chunk Size: 默认 32768 行（可配置）
  • 目的: 支持大规模数据的高效存储和查询
  • 索引: 每个 chunk 可以独立建立索引
1
2
3
4
// 代码示例
int64_t chunk_rows = segcore_config_.get_chunk_rows();  // 默认 32768
auto chunk_id = offset / chunk_rows;
auto offset_in_chunk = offset % chunk_rows;

A.3 Sealed Segment 内部结构

A.3.1 核心组件

文件: internal/core/src/segcore/ChunkedSegmentSealedImpl.h

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class ChunkedSegmentSealedImpl : public SegmentSealed {
private:
    // 1. Schema 和元数据
    SchemaPtr schema_;
    IndexMetaPtr col_index_meta_;
    int64_t id_;
    SegcoreConfig segcore_config_;
    
    // 2. 行数
    std::optional<int64_t> num_rows_;
    
    // 3. 加载状态
    BitsetType field_data_ready_bitset_;     // 字段数据是否已加载
    BitsetType index_ready_bitset_;          // 索引是否已加载
    BitsetType binlog_index_bitset_;         // Binlog 索引标记
    std::atomic<int> system_ready_count_;    // 系统字段计数器
    
    // 4. ★ 字段数据存储（列式存储）
    folly::Synchronized<std::unordered_map<
        FieldId, 
        std::shared_ptr<ChunkedColumnInterface>
    >> fields_;
    
    // 5. ★ 索引存储
    // 5.1 Scalar 索引
    folly::Synchronized<std::unordered_map<
        FieldId, 
        index::CacheIndexBasePtr
    >> scalar_indexings_;
    
    // 5.2 Vector 索引
    SealedIndexingRecord vector_indexings_;
    
    // 5.3 N-gram 索引（用于文本）
    folly::Synchronized<std::unordered_map<
        FieldId,
        std::unordered_map<std::string, index::CacheIndexBasePtr>
    >> ngram_indexings_;
    
    // 6. ★ InsertRecord (仅包含系统字段和 PK)
    InsertRecord<true> insert_record_;
    
    // 7. 删除记录
    DeletedRecord<true> deleted_record_;
    
    // 8. Mmap 字段
    std::unordered_set<FieldId> mmap_field_ids_;
    
    // 9. 统计信息
    SegmentStats stats_{};
    
    // 10. PK 排序标记
    bool is_sorted_by_pk_ = false;
    
    // 11. Storage V2 Reader
    std::unique_ptr<milvus_storage::api::Reader> reader_;
};

A.3.2 数据布局

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Sealed Segment Memory Layout:
┌────────────────────────────────────────────────┐
│  ChunkedSegmentSealedImpl                      │
├────────────────────────────────────────────────┤
│  insert_record_ (InsertRecordSealed)           │
│  ├─ timestamps_: ConcurrentVector<Timestamp>   │  ★ 仅系统字段
│  ├─ timestamp_index_: TimestampIndex          │
│  └─ pk2offset_: OffsetOrderedArray            │  ★ PK 索引（已排序）
├────────────────────────────────────────────────┤
│  fields_: map<FieldId, ChunkedColumnInterface>│  ★ 列数据
│  ├─ FieldID=100: ChunkedColumn<int64>         │     (Scalar 字段)
│  │   ├─ Chunk 0: [data...]                    │
│  │   ├─ Chunk 1: [data...]                    │
│  │   └─ ...                                    │
│  ├─ FieldID=102: ChunkedColumn<vector>        │     (向量字段)
│  │   └─ 可能被索引替代                          │
│  └─ ...                                        │
├────────────────────────────────────────────────┤
│  scalar_indexings_: map<FieldId, Index>       │  ★ Scalar 索引
│  └─ FieldID=100: ScalarIndex                  │
├────────────────────────────────────────────────┤
│  vector_indexings_: SealedIndexingRecord       │  ★ Vector 索引
│  ├─ FieldID=102: VectorIndex (HNSW/IVF/...)  │
│  └─ index_has_raw_data_: bool                 │     (是否保留原始数据)
├────────────────────────────────────────────────┤
│  deleted_record_: DeletedRecord                │  ★ 删除记录
└────────────────────────────────────────────────┘

A.3.3 ChunkedColumn 结构

Sealed Segment 使用分块列存储：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 列接口
class ChunkedColumnInterface {
public:
    virtual size_t num_chunks() const = 0;
    virtual size_t chunk_size(size_t chunk_id) const = 0;
    virtual SpanBase chunk_data(size_t chunk_id) const = 0;
    
    // 支持 mmap
    virtual bool is_mmaped() const = 0;
};

// 使用示例
auto column = fields_[field_id];
for (size_t chunk_id = 0; chunk_id < column->num_chunks(); ++chunk_id) {
    auto data = column->chunk_data(chunk_id);
    // 处理 chunk 数据
}

A.4 文件系统中的 Layout

A.4.1 StorageV1 (Binlog) 布局

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{root_path}/{collectionID}/{partitionID}/{segmentID}/
├── insert_log/              # 插入数据
│   ├── 0/                   # RowID field
│   │   └── {logID}          # Binlog 文件
│   ├── 1/                   # ★ Timestamp field
│   │   └── {logID}
│   ├── 100/                 # User field 1
│   │   └── {logID}
│   ├── 101/                 # User field 2
│   │   └── {logID}
│   └── 102/                 # Vector field
│       └── {logID}
│
├── delta_log/               # 删除数据
│   └── {logID}
│
├── stats_log/               # 统计数据（PK stats）
│   └── {logID}
│
└── index/                   # 索引文件
    └── {fieldID}/
        ├── {indexBuildID}/
        │   ├── index_params
        │   ├── index_info
        │   └── index_data_*
        └── ...

A.4.2 StorageV2 (Parquet) 布局

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{root_path}/{collectionID}/{partitionID}/{segmentID}/
├── insert_log/
│   ├── {columnGroupID}/
│   │   └── {logID}.parquet    # Parquet 文件（包含多个字段）
│   │                           # ★ Timestamp 作为其中一列
│   ├── manifest.json           # 元数据清单
│   │   ├── schema
│   │   ├── column_groups
│   │   │   ├─ group_id: 1
│   │   │   │  └─ fields: [0, 1, 100]  # RowID, Timestamp, Field1
│   │   │   └─ group_id: 2
│   │   │      └─ fields: [101, 102]   # Field2, VectorField
│   │   └── files
│   └── ...
│
├── delta_log/
│   └── {logID}
│
├── stats_log/
│   └── {logID}
│
└── index/
    └── ... (同 V1)

A.4.3 Binlog 文件内部结构

每个 binlog 文件包含：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Binlog File Structure:
┌─────────────────────────────┐
│  Magic Number               │  4 bytes
├─────────────────────────────┤
│  Descriptor Event           │
│  ├─ CollectionID            │
│  ├─ PartitionID             │
│  ├─ SegmentID               │
│  ├─ FieldID                 │
│  ├─ StartTimestamp          │  ★ Min timestamp
│  ├─ EndTimestamp            │  ★ Max timestamp
│  └─ PayloadDataType         │
├─────────────────────────────┤
│  Insert Event 1             │
│  ├─ StartTimestamp          │
│  ├─ EndTimestamp            │
│  └─ Payload (field data)    │  ★ 实际字段数据
├─────────────────────────────┤
│  Insert Event 2             │
│  └─ ...                     │
├─────────────────────────────┤
│  ...                        │
└─────────────────────────────┘

A.5 查询时的数据访问

A.5.1 访问路径

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Query Request
    ↓
Plan Node
    ↓
Segment Interface
    ↓
    ├─ [Growing Segment]
    │   └─> InsertRecord.data_[fieldID]
    │       └─> ConcurrentVector::get(offset)
    │
    └─ [Sealed Segment]
        ├─> [Has Index?]
        │   ├─ Yes → vector_indexings_[fieldID]
        │   │         └─> Index Search
        │   └─ No  → fields_[fieldID]
        │             └─> ChunkedColumn::chunk_data(chunk_id)
        │
        └─> [Filter by Timestamp]
            └─> insert_record_.timestamps_
                └─> TimestampIndex (Binary Search)

A.5.2 Timestamp 过滤示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// 文件: internal/core/src/segcore/SegmentGrowingImpl.cpp

void SegmentGrowingImpl::mask_with_timestamps(
    BitsetTypeView& bitset_chunk,
    Timestamp timestamp,
    Timestamp ttl) const {
    
    auto timestamps_data_ptr = insert_record_.timestamps_.data();
    auto size = insert_record_.size();
    
    // 使用 timestamp 过滤数据
    for (int64_t i = 0; i < size; ++i) {
        auto ts = timestamps_data_ptr[i];
        
        // 过滤未来的数据（ts > query_timestamp）
        if (ts > timestamp) {
            bitset_chunk[i] = true;  // mask out
        }
        
        // 过滤过期的数据（根据 TTL）
        if (ttl > 0 && timestamp - ts > ttl) {
            bitset_chunk[i] = true;  // mask out
        }
    }
}

A.6 内存管理

A.6.1 Growing Segment 内存管理

  1. 动态增长: ConcurrentVector 按需分配内存
  2. Chunk 管理: 数据按 chunk 组织，支持增量加载
  3. Mmap 支持: 可选地使用 mmap 减少内存占用
1
2
3
4
5
6
// Chunk 大小配置
int64_t chunk_rows = segcore_config_.get_chunk_rows();  // 默认 32768

// 估算内存使用
size_t memory_per_row = EstimateRowSize(schema);
size_t total_memory = num_rows * memory_per_row;

A.6.2 Sealed Segment 内存管理

  1. 延迟加载: 字段和索引按需加载
  2. Mmap: 支持 mmap 模式，减少内存拷贝
  3. 缓存管理: 使用 LRU 缓存管理索引和字段数据
1
2
3
4
5
6
// 加载状态检查
bool CanQuery() {
    return system_ready_count_ == 2  // RowID & Timestamp loaded
        && AllRequiredFieldsReady()   // Query fields loaded
        && (HasIndex() || HasRawData()); // Index or raw data available
}

A.7 关键数据结构总结

组件Growing SegmentSealed Segment说明
TimestampConcurrentVector<Timestamp>ConcurrentVector<Timestamp>两者都存储完整 timestamp
TimestampIndexTimestampIndexTimestampIndex用于时间旅行查询
PK IndexOffsetOrderedMapOffsetOrderedArrayGrowing 用 Map，Sealed 用 Array
Field Datamap<FieldId, ConcurrentVector>map<FieldId, ChunkedColumn>列式存储
Vector IndexIndexingRecord (interim)SealedIndexingRecord (permanent)索引类型不同
Scalar Index可选map<FieldId, Index>Sealed 支持更多索引
Delete RecordDeletedRecord<false>DeletedRecord<true>删除记录
并发控制std::shared_mutexfolly::Synchronized不同的同步机制

文档版本: v1.1
最后更新: 2025-01-24
适用 Milvus 版本: 2.5.x

]]> <p>本文档详细介绍 Milvus 中 MVCC timestamp 信息在数据写入 Segment 过程中的处理机制，包括正常 Flush 流程和 Compaction 流程。</p> <h2 id="目录"><a href="#目录" class="headerlink" t Milvus 数据写入过程中索引同步流程分析 https://szza.github.io/2025/08/09/Milvus/11_index_sync_flow_analysis/ 2025-08-09T12:00:00.000Z 2026-01-06T13:10:46.794Z 本文档详细分析了 Milvus 中数据写入后如何同步构建索引的完整流程。

1. 概述

Milvus 采用异步索引构建机制：数据写入后不会立即构建索引，而是在 Segment 完成 Flush 操作后，触发索引构建任务。这种设计可以：

  • 提高写入性能：避免每次写入都构建索引
  • 批量优化：对完整 Segment 构建索引更高效
  • 资源管理：通过任务调度器控制索引构建的资源使用

2. 数据写入和 Flush 流程

2.1 数据写入

文件: internal/datanode/ (DataNode 组件)

数据写入流程：

  1. 客户端通过 Proxy 发送 Insert 请求
  2. DataNode 接收数据并写入内存 Buffer
  3. 当满足条件时（如达到大小阈值、时间阈值），触发 Flush 操作

2.2 Flush 完成通知

文件: internal/datacoord/services.go

方法: Server.SaveBinlogPaths() (line 700-738)

当 DataNode 完成 Segment 的 Flush 操作后，会调用 DataCoord 的 SaveBinlogPaths 方法：

1
2
3
4
5
6
7
8
// notify building index and compaction for "flushing/flushed" level one segment
if req.GetFlushed() {
    // notify building index
    s.flushCh <- req.SegmentID
    
    // notify compaction
    s.compactionTrigger.TriggerCompaction(ctx, ...)
}

关键点：

  • 只有当 req.GetFlushed() == true 时才会触发索引构建
  • 通过 flushCh channel 发送 SegmentID
  • 同时也会触发 Compaction 任务

2.3 Flush Channel 转发

文件: internal/datacoord/server.go

方法: Server.postFlush() (line 960-976)

flushCh 中的消息会被转发到全局的 getBuildIndexChSingleton() channel：

1
2
3
4
5
6
7
8
9
10
11
if enableSortCompaction() {
    select {
    case getStatsTaskChSingleton() <- segmentID:
    default:
    }
} else {
    select {
    case getBuildIndexChSingleton() <- segmentID:
    default:
    }
}

关键点：

  • 如果启用了排序压缩（Sort Compaction），先发送到统计任务 channel
  • 否则直接发送到索引构建 channel
  • 使用 select 的非阻塞方式，避免阻塞

3. 索引构建任务创建

3.1 Index Inspector 监听

文件: internal/datacoord/index_inspector.go

方法: indexInspector.createIndexForSegmentLoop() (line 87-132)

Index Inspector 是一个后台守护进程，持续监听以下事件：

  1. 定时检查 (ticker.C)：

    • 定期检查是否有未构建索引的 Flushed Segment
    • 调用 getUnIndexTaskSegments() 获取需要构建索引的 Segment

  2. Collection 索引通知 (notifyIndexChan)：

    • 当 Collection 创建新索引时触发
    • 为所有已 Flush 的 Segment 创建索引任务

  3. Flush 完成通知 (getBuildIndexChSingleton())：

    • 接收新 Flush 完成的 SegmentID
    • 立即为该 Segment 创建索引任务
1
2
3
4
5
6
7
8
9
10
11
case segID := <-getBuildIndexChSingleton():
    log.Info("receive new flushed segment", zap.Int64("segmentID", segID))
    segment := i.meta.GetSegment(ctx, segID)
    if segment == nil {
        log.Warn("segment is not exist, no need to build index", zap.Int64("segmentID", segID))
        continue
    }
    if err := i.createIndexesForSegment(ctx, segment); err != nil {
        log.Warn("create index for segment fail, wait for retry", zap.Int64("segmentID", segID))
        continue
    }

3.2 创建索引任务

方法: indexInspector.createIndexesForSegment() (line 148-170)

为 Segment 创建索引任务的主要步骤：

  1. 检查 Segment 状态：

    • 如果启用了排序压缩，需要等待 Segment 排序完成
    • L0 级别的 Segment 不构建索引

  2. 获取 Collection 的所有索引：

    1
    indexes := i.meta.indexMeta.GetIndexesForCollection(segment.CollectionID, "")

  3. 检查哪些索引还未构建：

    1
    2
    3
    4
    5
    6
    7
    indexIDToSegIndexes := i.meta.indexMeta.GetSegmentIndexes(segment.CollectionID, segment.ID)
    for _, index := range indexes {
        if _, ok := indexIDToSegIndexes[index.IndexID]; !ok {
            // 为这个索引创建任务
            i.createIndexForSegment(ctx, segment, index.IndexID)
        }
    }

3.3 创建 SegmentIndex 元数据

方法: indexInspector.createIndexForSegment() (line 172-225)

为每个索引创建 SegmentIndex 元数据并加入调度队列：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// 1. 分配 BuildID
buildID, err := i.allocator.AllocID(context.Background())

// 2. 获取索引参数
indexParams := i.meta.indexMeta.GetIndexParams(segment.CollectionID, indexID)
indexType := GetIndexType(indexParams)

// 3. 计算任务槽位（用于资源调度）
isVectorIndex := vecindexmgr.GetVecIndexMgrInstance().IsVecIndex(indexType)
segSize := segment.getSegmentSize()
taskSlot := calculateIndexTaskSlot(segSize, isVectorIndex)

// 4. 创建 SegmentIndex 元数据
segIndex := &model.SegmentIndex{
    SegmentID:      segment.ID,
    CollectionID:   segment.CollectionID,
    PartitionID:    segment.PartitionID,
    NumRows:        segment.NumOfRows,
    IndexID:        indexID,
    BuildID:        buildID,
    CreatedUTCTime: uint64(time.Now().Unix()),
    WriteHandoff:   false,
    IndexType:      indexType,
}

// 5. 保存到元数据存储
if err = i.meta.indexMeta.AddSegmentIndex(ctx, segIndex); err != nil {
    return err
}

// 6. 加入调度器队列
i.scheduler.Enqueue(newIndexBuildTask(...))

关键点：

  • BuildID 是索引构建任务的唯一标识
  • IndexState 初始为 Unissued
  • 任务槽位（TaskSlot）用于控制并发度，根据 Segment 大小和索引类型计算

4. 索引任务调度和执行

4.1 DataCoord 任务调度

文件: internal/datacoord/task_index.go

方法: indexBuildTask.CreateTaskOnWorker() (line 148-206)

DataCoord 的调度器会选择合适的 DataNode 节点执行索引构建任务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 1. 验证任务和 Segment 状态
segIndex, exist := it.meta.indexMeta.GetIndexJob(it.BuildID)
segment := it.meta.GetSegment(ctx, segIndex.SegmentID)

// 2. 检查是否需要构建索引
// - 某些索引类型不需要训练（如 FLAT）
// - 小 Segment 可能不需要索引
if isNoTrainIndex(indexType) || segIndex.NumRows < MinSegmentNumRowsToEnableIndex {
    // 标记为已完成（假完成）
    it.UpdateStateWithMeta(indexpb.JobState_JobStateFinished, "fake finished")
    return
}

// 3. 准备任务请求
req, err := it.prepareJobRequest(ctx, segment, segIndex, indexParams, indexType)

// 4. 选择 DataNode 并发送请求
if err = cluster.CreateIndex(nodeID, req); err != nil {
    log.Warn("failed to send job to worker", zap.Error(err))
    return
}

// 5. 更新任务状态为 InProgress
it.UpdateStateWithMeta(indexpb.JobState_JobStateInProgress, ...)

4.2 DataNode 接收任务

文件: internal/datanode/index_services.go

方法: DataNode.CreateJob() (line 44-120)

DataNode 接收索引构建请求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 1. 创建任务上下文
taskCtx, taskCancel := context.WithCancel(node.ctx)

// 2. 检查任务是否已存在（防止重复）
if oldInfo := node.taskManager.LoadOrStoreIndexTask(...); oldInfo != nil {
    return merr.WrapErrIndexDuplicate(...)
}

// 3. 创建存储管理器
cm, err := node.storageFactory.NewChunkManager(node.ctx, req.GetStorageConfig())

// 4. 创建索引构建任务
task := index.NewIndexBuildTask(taskCtx, taskCancel, req, cm, node.taskManager, pluginContext)

// 5. 加入任务队列
if err := node.taskScheduler.TaskQueue.Enqueue(task); err != nil {
    return merr.Status(err)
}

4.3 索引构建执行

文件: internal/datanode/index/task_index.go

索引构建任务遵循标准的任务执行模式：PreExecute → Execute → PostExecute

4.3.1 PreExecute 阶段

方法: indexBuildTask.PreExecute() (line 146-221)

准备阶段的主要工作：

  1. 构建数据路径：

    1
    2
    3
    4
    5
    6
    if len(it.req.DataPaths) == 0 {
        for _, id := range it.req.GetDataIds() {
            path := metautil.BuildInsertLogPath(...)
            it.req.DataPaths = append(it.req.DataPaths, path)
        }
    }

  2. 解析索引参数：

    • 从请求中提取 typeParams 和 indexParams
    • 处理特殊参数（如 mmap_enabled）

  3. 填充字段元数据：

    • 如果请求中缺少字段信息，从 Binlog 中解析

  4. 设置索引版本：

    1
    2
    it.req.CurrentIndexVersion = getCurrentIndexVersion(...)
    it.req.CurrentScalarIndexVersion = getCurrentScalarIndexVersion(...)

4.3.2 Execute 阶段

方法: indexBuildTask.Execute() (line 223-330)

执行阶段的核心工作：

  1. 准备构建参数：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    buildIndexParams := &indexcgopb.BuildIndexInfo{
        ClusterID:                 it.req.GetClusterID(),
        BuildID:                   it.req.GetBuildID(),
        CollectionID:              it.req.GetCollectionID(),
        SegmentID:                 it.req.GetSegmentID(),
        NumRows:                   it.req.GetNumRows(),
        Dim:                       it.req.GetDim(),
        InsertFiles:               it.req.GetDataPaths(),
        FieldSchema:               it.req.GetField(),
        IndexParams:               mapToKVPairs(it.newIndexParams),
        StorageConfig:             storageConfig,
        // ...
    }

  2. 调用 CGO 接口构建索引：

    1
    it.index, err = indexcgowrapper.CreateIndex(ctx, buildIndexParams)

    这一步会：

    • 从存储中加载 Segment 数据
    • 调用 Knowhere 库构建索引
    • 索引构建完成后序列化

  3. 记录构建指标：

    1
    metrics.DataNodeKnowhereBuildIndexLatency.Observe(buildIndexLatency.Seconds())

4.3.3 PostExecute 阶段

方法: indexBuildTask.PostExecute() (line 333-375)

后处理阶段的主要工作：

  1. 上传索引文件到存储：

    1
    indexStats, err := it.index.UpLoad()

    上传过程会：

    • 序列化索引数据
    • 分片上传到对象存储（MinIO/S3 等）
    • 返回索引文件路径和大小信息

  2. 清理本地索引数据：

    1
    2
    3
    4
    5
    6
    gcIndex := func() {
        if err := it.index.Delete(); err != nil {
            log.Warn("indexBuildTask Execute CIndexDelete failed", zap.Error(err))
        }
    }
    gcIndex() // 早期释放，节省内存

  3. 保存索引元数据：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    it.manager.StoreIndexFilesAndStatistic(
        it.req.GetClusterID(),
        it.req.GetBuildID(),
        saveFileKeys,        // 索引文件路径列表
        serializedSize,      // 序列化后的大小
        uint64(indexStats.MemSize),  // 内存大小
        it.req.GetCurrentIndexVersion(),
        it.req.GetCurrentScalarIndexVersion(),
    )

  4. 更新任务状态：

    • 通过 SetState() 更新任务状态为 Finished
    • 记录完成时间

4.4 索引元数据更新

文件: internal/datacoord/index_meta.go

方法: indexMeta.FinishTask() (line 885-920)

当 DataNode 完成索引构建后，会通知 DataCoord 更新元数据：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
func (m *indexMeta) FinishTask(taskInfo *workerpb.IndexTaskInfo) error {
    // 1. 获取 SegmentIndex
    segIdx, ok := m.segmentBuildInfo.Get(taskInfo.GetBuildID())
    
    // 2. 更新索引状态和文件信息
    segIdx.IndexState = taskInfo.GetState()
    segIdx.IndexFileKeys = common.CloneStringList(taskInfo.GetIndexFileKeys())
    segIdx.IndexSerializedSize = taskInfo.GetSerializedSize()
    segIdx.IndexMemSize = taskInfo.GetMemSize()
    segIdx.FinishedUTCTime = uint64(time.Now().Unix())
    
    // 3. 持久化到元数据存储
    return m.alterSegmentIndexes([]*model.SegmentIndex{segIdx})
}

关键点：

  • IndexState 更新为 Finished
  • 保存索引文件路径列表（IndexFileKeys）
  • 记录索引大小信息，用于查询时加载

5. 完整流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
数据写入流程
    ↓
DataNode 接收数据 → 写入内存 Buffer
    ↓
触发 Flush（达到阈值或手动触发）
    ↓
DataNode 完成 Flush → 保存 Binlog 到存储
    ↓
调用 DataCoord.SaveBinlogPaths()
    ↓
if req.GetFlushed() == true:
    s.flushCh <- segmentID
    ↓
DataCoord.postFlush() 转发
    ↓
getBuildIndexChSingleton() <- segmentID
    ↓
Index Inspector 监听
    ↓
indexInspector.createIndexesForSegment()
    ├─ 获取 Collection 的所有索引
    ├─ 检查哪些索引未构建
    └─ 为每个索引创建 SegmentIndex
        ├─ 分配 BuildID
        ├─ 创建元数据（状态：Unissued）
        └─ 加入调度器队列
            ↓
DataCoord 调度器选择 DataNode
    ↓
发送 CreateIndex 请求到 DataNode
    ↓
DataNode 接收请求
    ├─ 创建索引构建任务
    └─ 加入任务队列
        ↓
任务执行（PreExecute → Execute → PostExecute）
    ├─ PreExecute: 准备参数和路径
    ├─ Execute: 调用 Knowhere 构建索引
    └─ PostExecute: 上传索引文件
        ├─ 上传到对象存储
        ├─ 保存文件路径到元数据
        └─ 通知 DataCoord 更新状态
            ↓
DataCoord 更新索引元数据
    ├─ IndexState: Finished
    ├─ IndexFileKeys: [文件路径列表]
    └─ 持久化到元数据存储
        ↓
索引构建完成，可用于查询

6. 关键组件说明

6.1 Index Inspector

位置: internal/datacoord/index_inspector.go

  • 职责：监听 Flush 完成事件，创建索引构建任务
  • 触发方式：
    • 定时检查（默认间隔由 TaskCheckInterval 配置）
    • Flush 完成通知（通过 channel）
    • Collection 索引创建通知

6.2 Index Scheduler

位置: internal/datacoord/task/

  • 职责：调度索引构建任务到合适的 DataNode
  • 调度策略：
    • 根据任务槽位（TaskSlot）控制并发度
    • 选择负载较低的 DataNode
    • 支持任务重试和失败处理

6.3 Index Task Manager

位置: internal/datanode/index/

  • 职责：管理 DataNode 上的索引构建任务
  • 功能：
    • 任务队列管理
    • 任务状态跟踪
    • 资源清理

6.4 Index Meta

位置: internal/datacoord/index_meta.go

  • 职责：管理索引元数据
  • 存储内容：
    • SegmentIndex 信息（BuildID, SegmentID, IndexID）
    • 索引状态（Unissued, InProgress, Finished, Failed）
    • 索引文件路径和大小

7. 关键配置参数

  • DataCoordCfg.TaskCheckInterval: Index Inspector 定时检查间隔（默认 1 秒）
  • DataCoordCfg.MinSegmentNumRowsToEnableIndex: 启用索引的最小行数阈值
  • KnowhereConfig.Enable: 是否启用 Knowhere 索引库
  • 索引参数：index_type, metric_type, nlist, nprobe 等

8. 索引状态流转

1
2
3
Unissued → InProgress → Finished
              ↓
           Failed (可重试)
  • Unissued: 任务已创建，等待调度
  • InProgress: 任务正在执行
  • Finished: 索引构建完成
  • Failed: 构建失败，可重试

9. 性能优化点

  1. 异步构建：索引构建不影响数据写入性能
  2. 批量处理：对完整 Segment 构建索引，效率更高
  3. 资源控制：通过 TaskSlot 控制并发度，避免资源耗尽
  4. 早期释放：索引构建完成后立即释放内存
  5. 分片上传：大索引文件分片上传，提高可靠性

10. 错误处理

  • Segment 不存在：忽略该任务
  • 索引构建失败：任务状态标记为 Failed，可重试
  • 上传失败：清理本地数据，标记失败
  • 元数据更新失败：记录日志，等待重试

11. 监控指标

  • DataNodeBuildIndexTaskCounter: 索引构建任务计数
  • DataNodeKnowhereBuildIndexLatency: 索引构建延迟
  • DataNodeEncodeIndexFileLatency: 索引文件编码和上传延迟
  • DataNodeSaveIndexFileLatency: 保存索引文件元数据延迟
  • DataCoordStoredIndexFilesSize: 存储的索引文件总大小

12. 注意事项

  1. 索引构建是异步的：数据写入后不会立即有索引，需要等待 Flush 和索引构建完成
  2. 小 Segment 可能不构建索引：如果 Segment 行数小于阈值，可能跳过索引构建
  3. L0 Segment 不构建索引：L0 级别的 Segment 用于实时查询，不构建持久化索引
  4. 排序压缩模式：如果启用了排序压缩，需要等待 Segment 排序完成后再构建索引
]]> <p>本文档详细分析了 Milvus 中数据写入后如何同步构建索引的完整流程。</p> <h2 id="1-概述"><a href="#1-概述" class="headerlink" title="1. 概述"></a>1. 概述</h2><p>Milvus 采用<strong Milvus TTNode（时间戳节点）详解 https://szza.github.io/2025/08/09/Milvus/10_flush_pipeline_tt_node/ 2025-08-09T11:00:00.000Z 2026-01-06T13:10:46.358Z 概述

ttNode（TimeTick Node）是 FlowGraph 中的最后一个节点，负责管理和更新通道检查点（Checkpoint）。它定期或基于触发条件将检查点异步更新到 DataCoord，确保数据消费位置的持久化。

架构设计

核心结构

1
2
3
4
5
6
7
8
9
10
11
type ttNode struct {
    BaseNode
    
    vChannelName       string
    metacache          metacache.MetaCache
    writeBufferManager writebuffer.BufferManager
    lastUpdateTime     *atomic.Time
    cpUpdater          *util.ChannelCheckpointUpdater
    dropMode           *atomic.Bool
    dropCallback       func()
}

关键字段说明：

  • writeBufferManager: WriteBuffer 管理器，用于获取检查点
  • lastUpdateTime: 上次更新时间，用于控制更新频率
  • cpUpdater: 检查点更新器，异步更新检查点
  • dropMode: 删除模式标志

消息处理流程

Operate 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
func (ttn *ttNode) Operate(in []Msg) []Msg {
    fgMsg := in[0].(*FlowGraphMsg)
    
    // 1. 处理删除集合消息
    if fgMsg.dropCollection {
        ttn.dropMode.Store(true)
        if ttn.dropCallback != nil {
            defer ttn.dropCallback()
        }
    }
    
    // 2. 删除模式下跳过检查点更新
    if ttn.dropMode.Load() {
        return []Msg{}
    }
    
    // 3. 处理关闭消息
    if fgMsg.IsCloseMsg() {
        if ttn.dropMode.Load() {
            return in
        }
        // 强制更新检查点
        if len(fgMsg.EndPositions) > 0 {
            channelPos, _, err := ttn.writeBufferManager.GetCheckpoint(ttn.vChannelName)
            if err != nil {
                return []Msg{}
            }
            ttn.updateChannelCP(channelPos, curTs, false)
        }
        return in
    }
    
    curTs, _ := tsoutil.ParseTS(fgMsg.TimeRange.TimestampMax)
    
    // 4. 获取检查点
    channelPos, needUpdate, err := ttn.writeBufferManager.GetCheckpoint(ttn.vChannelName)
    if err != nil {
        return []Msg{}
    }
    
    // 5. 定期更新（基于时间间隔）
    if curTs.Sub(ttn.lastUpdateTime.Load()) >= paramtable.Get().DataNodeCfg.UpdateChannelCheckpointInterval.GetAsDuration(time.Second) {
        ttn.updateChannelCP(channelPos, curTs, false)
        return []Msg{}
    }
    
    // 6. 触发更新（基于 flushTs 条件）
    if needUpdate {
        ttn.updateChannelCP(channelPos, curTs, true)
    }
    
    return []Msg{}
}

检查点更新机制

updateChannelCP 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
func (ttn *ttNode) updateChannelCP(channelPos *msgpb.MsgPosition, curTs time.Time, flush bool) {
    callBack := func() {
        channelCPTs, _ := tsoutil.ParseTS(channelPos.GetTimestamp())
        // 重置 flushTs，防止频繁刷新
        ttn.writeBufferManager.NotifyCheckpointUpdated(ttn.vChannelName, channelPos.GetTimestamp())
        log.Debug("UpdateChannelCheckpoint success",
            zap.String("channel", ttn.vChannelName),
            zap.Uint64("cpTs", channelPos.GetTimestamp()),
            zap.Time("cpTime", channelCPTs))
    }
    
    // 添加到更新器
    ttn.cpUpdater.AddTask(channelPos, flush, callBack)
    ttn.lastUpdateTime.Store(curTs)
}

关键逻辑：

  • flush 参数：标记是否由刷新操作触发
  • callBack：更新成功后的回调，用于重置 flushTs

ChannelCheckpointUpdater 详解

核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
type ChannelCheckpointUpdater struct {
    broker broker.Broker
    
    mu         sync.RWMutex
    tasks      map[string]*channelCPUpdateTask
    notifyChan chan struct{}
    
    closeCh            chan struct{}
    closeOnce          sync.Once
    updateDoneCallback func(*msgpb.MsgPosition)
}

type channelCPUpdateTask struct {
    pos      *msgpb.MsgPosition
    callback func()
    flush    bool  // 是否由刷新触发
}

启动循环

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
func (ccu *ChannelCheckpointUpdater) Start() {
    ticker := time.NewTicker(paramtable.Get().DataNodeCfg.ChannelCheckpointUpdateTickInSeconds.GetAsDuration(time.Second))
    defer ticker.Stop()
    
    for {
        select {
        case <-ccu.closeCh:
            return
        case <-ccu.notifyChan:
            // 处理刷新触发的更新
            var tasks []*channelCPUpdateTask
            ccu.mu.Lock()
            for _, task := range ccu.tasks {
                if task.flush {
                    task.flush = false  // 重置标志
                    tasks = append(tasks, task)
                }
            }
            ccu.mu.Unlock()
            if len(tasks) > 0 {
                ccu.updateCheckpoints(tasks)
            }
        case <-ticker.C:
            // 定期执行更新
            ccu.execute()
        }
    }
}

添加任务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
func (ccu *ChannelCheckpointUpdater) AddTask(channelPos *msgpb.MsgPosition, flush bool, callback func()) {
    if flush {
        // 刷新触发时，立即触发更新尝试
        defer ccu.trigger()
    }
    
    channel := channelPos.GetChannelName()
    task, ok := ccu.getTask(channel)
    
    if !ok {
        // 新任务
        ccu.mu.Lock()
        defer ccu.mu.Unlock()
        ccu.tasks[channel] = &channelCPUpdateTask{
            pos:      channelPos,
            callback: callback,
            flush:    flush,
        }
        return
    }
    
    // 合并任务
    max := func(a, b *msgpb.MsgPosition) *msgpb.MsgPosition {
        if a.GetTimestamp() > b.GetTimestamp() {
            return a
        }
        return b
    }
    
    // 更新条件：
    // 1. 位置更新了（时间戳更大）
    // 2. 刷新触发但任务未标记为刷新
    if task.pos.GetTimestamp() < channelPos.GetTimestamp() || (flush && !task.flush) {
        ccu.mu.Lock()
        defer ccu.mu.Unlock()
        ccu.tasks[channel] = &channelCPUpdateTask{
            pos:      max(channelPos, task.pos),  // 取最大时间戳
            callback: callback,
            flush:    flush || task.flush,  // 保留刷新标志
        }
    }
}

更新检查点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
func (ccu *ChannelCheckpointUpdater) updateCheckpoints(tasks []*channelCPUpdateTask) {
    // 1. 分批处理（每批最大数量限制）
    taskGroups := lo.Chunk(tasks, paramtable.Get().DataNodeCfg.MaxChannelCheckpointsPerRPC.GetAsInt())
    
    // 2. 并行处理（最大并行数限制）
    updateChanCPMaxParallel := paramtable.Get().DataNodeCfg.UpdateChannelCheckpointMaxParallel.GetAsInt()
    rpcGroups := lo.Chunk(taskGroups, updateChanCPMaxParallel)
    
    finished := typeutil.NewConcurrentMap[string, *channelCPUpdateTask]()
    
    for _, groups := range rpcGroups {
        wg := &sync.WaitGroup{}
        for _, tasks := range groups {
            wg.Add(1)
            go func(tasks []*channelCPUpdateTask) {
                defer wg.Done()
                
                // 3. 构建 RPC 请求
                timeout := paramtable.Get().DataNodeCfg.UpdateChannelCheckpointRPCTimeout.GetAsDuration(time.Second)
                ctx, cancel := context.WithTimeout(context.Background(), timeout)
                defer cancel()
                
                channelCPs := lo.Map(tasks, func(t *channelCPUpdateTask, _ int) *msgpb.MsgPosition {
                    return t.pos
                })
                
                // 4. 发送 RPC
                err := ccu.broker.UpdateChannelCheckpoint(ctx, channelCPs)
                if err != nil {
                    log.Warn("update channel checkpoint failed", zap.Error(err))
                    return  // 失败时不删除任务，等待重试
                }
                
                // 5. 执行回调
                for _, task := range tasks {
                    task.callback()
                    finished.Insert(task.pos.GetChannelName(), task)
                    if ccu.updateDoneCallback != nil {
                        ccu.updateDoneCallback(task.pos)
                    }
                }
            }(tasks)
        }
        wg.Wait()
    }
    
    // 6. 清理已完成的任务
    ccu.mu.Lock()
    defer ccu.mu.Unlock()
    finished.Range(func(_ string, task *channelCPUpdateTask) bool {
        channel := task.pos.GetChannelName()
        // 只有当任务位置 >= 当前任务位置时才删除（避免删除更新的任务）
        if ccu.tasks[channel].pos.GetTimestamp() <= task.pos.GetTimestamp() {
            delete(ccu.tasks, channel)
        }
        return true
    })
}

检查点更新触发条件

1. 定期更新

1
2
3
if curTs.Sub(ttn.lastUpdateTime.Load()) >= UpdateChannelCheckpointInterval {
    ttn.updateChannelCP(channelPos, curTs, false)
}

触发条件： 距离上次更新时间超过配置的间隔

2. 刷新触发

1
2
3
4
channelPos, needUpdate, err := ttn.writeBufferManager.GetCheckpoint(ttn.vChannelName)
if needUpdate {
    ttn.updateChannelCP(channelPos, curTs, true)
}

触发条件： GetCheckpoint 返回 needUpdate = true

needUpdate 的计算：

1
2
flushTs := buf.GetFlushTimestamp()
return cp, flushTs != nonFlushTS && cp.GetTimestamp() >= flushTs, nil

含义： 当检查点时间戳 >= flushTs 时，需要更新检查点

检查点失败处理

失败重试机制

1
2
3
4
5
err := ccu.broker.UpdateChannelCheckpoint(ctx, channelCPs)
if err != nil {
    log.Warn("update channel checkpoint failed", zap.Error(err))
    return  // 不删除任务，等待下次重试
}

特点：

  • 失败时不删除任务
  • 任务保留在 ccu.tasks 中
  • 下次 execute() 或 notifyChan 触发时会重试

任务合并

1
2
3
4
5
6
// 合并逻辑：取最大时间戳，保留刷新标志
ccu.tasks[channel] = &channelCPUpdateTask{
    pos:      max(channelPos, task.pos),
    callback: callback,
    flush:    flush || task.flush,
}

优势：

  • 避免重复更新
  • 确保使用最新的检查点
  • 保留刷新触发标志

设计特点

1. 异步更新

通过 ChannelCheckpointUpdater 实现异步更新，不阻塞 FlowGraph。

2. 批量处理

支持批量更新多个通道的检查点，提高效率。

3. 并行执行

支持并行处理多个批次，充分利用系统资源。

4. 失败重试

失败的任务保留在队列中，自动重试。

5. 刷新加速

刷新触发的更新会立即尝试，不等待定时器。

配置参数

  • UpdateChannelCheckpointInterval: 定期更新间隔
  • ChannelCheckpointUpdateTickInSeconds: 更新器定时器间隔
  • MaxChannelCheckpointsPerRPC: 每次 RPC 最大检查点数
  • UpdateChannelCheckpointMaxParallel: 最大并行数
  • UpdateChannelCheckpointRPCTimeout: RPC 超时时间

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>ttNode</code>（TimeTick Node）是 FlowGraph 中的最后一个节点，负责管理和更新通道检查点（Ch Milvus SyncManager 与 SyncTask 详解 https://szza.github.io/2025/08/09/Milvus/9_flush_pipeline_sync_manager/ 2025-08-09T10:00:00.000Z 2026-01-06T13:10:45.842Z 概述

SyncManager 是 Milvus DataNode 中管理异步数据同步的核心组件，负责将内存中的数据持久化到对象存储。SyncTask 是执行同步的具体任务单元，封装了数据写入、元数据更新等完整流程。

SyncManager 架构

核心结构

1
2
3
4
5
6
7
8
type syncManager struct {
    *keyLockDispatcher[int64]
    chunkManager storage.ChunkManager
    
    tasks     *typeutil.ConcurrentMap[string, Task]
    taskStats *expirable.LRU[string, Task]
    handler   config.EventHandler
}

关键字段说明：

  • keyLockDispatcher: 基于段 ID 的任务分发器，确保同一段的任务串行执行
  • chunkManager: 对象存储管理器
  • tasks: 当前执行中的任务映射
  • taskStats: 任务统计信息（LRU 缓存，15分钟过期）

接口定义

1
2
3
4
5
6
type SyncManager interface {
    SyncData(ctx context.Context, task Task, callbacks ...func(error) error) (*conc.Future[struct{}], error)
    SyncDataWithChunkManager(ctx context.Context, task Task, chunkManager storage.ChunkManager, callbacks ...func(error) error) (*conc.Future[struct{}], error)
    Close() error
    TaskStatsJSON() string
}

SyncManager 初始化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
func NewSyncManager(chunkManager storage.ChunkManager) SyncManager {
    params := paramtable.Get()
    cpuNum := hardware.GetCPUNum()
    
    // 初始化工作池大小：CPU 核心数 × 每核心任务数
    initPoolSize := cpuNum * params.DataNodeCfg.MaxParallelSyncMgrTasksPerCPUCore.GetAsInt()
    dispatcher := newKeyLockDispatcher[int64](initPoolSize)
    
    syncMgr := &syncManager{
        keyLockDispatcher: dispatcher,
        chunkManager:      chunkManager,
        tasks:             typeutil.NewConcurrentMap[string, Task](),
        taskStats:         expirable.NewLRU[string, Task](64, nil, time.Minute*15),
    }
    
    // 监听配置变更，动态调整工作池大小
    handler := config.NewHandler("datanode.syncmgr.poolsize", syncMgr.resizeHandler)
    syncMgr.handler = handler
    params.Watch(params.DataNodeCfg.MaxParallelSyncMgrTasksPerCPUCore.Key, handler)
    
    return syncMgr
}

任务提交流程

SyncData 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
func (mgr *syncManager) SyncData(ctx context.Context, task Task, callbacks ...func(error) error) (*conc.Future[struct{}], error) {
    if mgr.workerPool.IsClosed() {
        return nil, errors.New("sync manager is closed")
    }
    
    // 为 SyncTask 设置 ChunkManager
    switch t := task.(type) {
    case *SyncTask:
        t.WithChunkManager(mgr.chunkManager)
    }
    
    return mgr.safeSubmitTask(ctx, task, callbacks...), nil
}

safeSubmitTask 方法

1
2
3
4
5
6
7
8
9
10
11
12
func (mgr *syncManager) safeSubmitTask(ctx context.Context, task Task, callbacks ...func(error) error) *conc.Future[struct{}] {
    // 生成任务键：segmentID-timestamp
    taskKey := fmt.Sprintf("%d-%d", task.SegmentID(), task.Checkpoint().GetTimestamp())
    
    // 记录任务
    mgr.tasks.Insert(taskKey, task)
    mgr.taskStats.Add(taskKey, task)
    
    // 使用段 ID 作为分发键，确保同一段的任务串行执行
    key := task.SegmentID()
    return mgr.submit(ctx, key, task, callbacks...)
}

submit 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
func (mgr *syncManager) submit(ctx context.Context, key int64, task Task, callbacks ...func(error) error) *conc.Future[struct{}] {
    handler := func(err error) error {
        taskKey := fmt.Sprintf("%d-%d", task.SegmentID(), task.Checkpoint().GetTimestamp())
        defer func() {
            mgr.tasks.Remove(taskKey)  // 任务完成后移除
        }()
        
        if err == nil {
            return nil
        }
        
        task.HandleError(err)  // 处理错误
        return err
    }
    
    callbacks = append([]func(error) error{handler}, callbacks...)
    return mgr.Submit(ctx, key, task, callbacks...)
}

SyncTask 详解

核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
type SyncTask struct {
    chunkManager storage.ChunkManager
    allocator    allocator.Interface
    
    collectionID  int64
    partitionID   int64
    segmentID     int64
    channelName   string
    startPosition *msgpb.MsgPosition
    checkpoint    *msgpb.MsgPosition
    dataSource    string
    batchRows     int64
    level         datapb.SegmentLevel
    
    tsFrom typeutil.Timestamp
    tsTo   typeutil.Timestamp
    
    metacache  metacache.MetaCache
    metaWriter MetaWriter
    schema     *schemapb.CollectionSchema
    
    pack *SyncPack
    
    insertBinlogs map[int64]*datapb.FieldBinlog
    statsBinlogs  map[int64]*datapb.FieldBinlog
    bm25Binlogs   map[int64]*datapb.FieldBinlog
    deltaBinlog   *datapb.FieldBinlog
    
    manifestPath string
    
    writeRetryOpts []retry.Option
    failureCallback func(err error)
    
    tr *timerecord.TimeRecorder
    
    flushedSize int64
    execTime    time.Duration
    
    storageConfig *indexpb.StorageConfig
}

SyncPack（数据包）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
type SyncPack struct {
    metacache  metacache.MetaCache
    metawriter MetaWriter
    
    // 数据
    insertData []*storage.InsertData
    deltaData  *storage.DeleteData
    bm25Stats  map[int64]*storage.BM25Stats
    
    // 统计信息
    tsFrom        typeutil.Timestamp
    tsTo          typeutil.Timestamp
    startPosition *msgpb.MsgPosition
    checkpoint    *msgpb.MsgPosition
    batchRows     int64
    dataSource    string
    
    // 标志
    isFlush bool
    isDrop  bool
    
    // 元数据
    collectionID int64
    partitionID  int64
    segmentID    int64
    channelName  string
    level        datapb.SegmentLevel
    
    errHandler func(err error)
}

SyncTask 执行流程

Run 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
func (t *SyncTask) Run(ctx context.Context) (err error) {
    t.tr = timerecord.NewTimeRecorder("syncTask")
    log := t.getLogger()
    
    defer func() {
        if err != nil {
            t.HandleError(err)
        }
    }()
    
    // 1. 检查段是否存在
    segmentInfo, has := t.metacache.GetSegmentByID(t.segmentID)
    if !has {
        if t.pack.isDrop {
            log.Info("segment dropped, discard sync task")
            return nil
        }
        log.Warn("segment not found in metacache, may be already synced")
        return nil
    }
    
    // 2. 获取列分组信息（StorageV2）
    columnGroups := t.getColumnGroups(segmentInfo)
    
    // 3. 写入数据到对象存储
    switch segmentInfo.GetStorageVersion() {
    case storage.StorageV2:
        writer := NewBulkPackWriterV2(...)
        t.insertBinlogs, t.deltaBinlog, t.statsBinlogs, t.bm25Binlogs, 
            t.manifestPath, t.flushedSize, err = writer.Write(ctx, t.pack)
    default:
        writer := NewBulkPackWriter(...)
        t.insertBinlogs, t.deltaBinlog, t.statsBinlogs, t.bm25Binlogs, 
            t.flushedSize, err = writer.Write(ctx, t.pack)
    }
    
    if err != nil {
        return err
    }
    
    // 4. 记录监控指标
    metrics.DataNodeWriteDataCount.Add(float64(t.batchRows))
    metrics.DataNodeFlushedSize.Add(float64(t.flushedSize))
    metrics.DataNodeSave2StorageLatency.Observe(float64(t.tr.RecordSpan().Milliseconds()))
    
    // 5. 更新元数据
    if t.metaWriter != nil {
        err = t.writeMeta(ctx)
        if err != nil {
            return err
        }
    }
    
    // 6. 释放数据
    t.pack.ReleaseData()
    
    // 7. 更新 MetaCache
    actions := []metacache.SegmentAction{metacache.FinishSyncing(t.batchRows)}
    if columnGroups != nil {
        actions = append(actions, metacache.UpdateCurrentSplit(columnGroups))
    }
    if t.pack.isFlush {
        actions = append(actions, metacache.UpdateState(commonpb.SegmentState_Flushed))
    }
    t.metacache.UpdateSegments(metacache.MergeSegmentAction(actions...), 
        metacache.WithSegmentIDs(t.segmentID))
    
    // 8. 处理删除段
    if t.pack.isDrop {
        t.metacache.RemoveSegments(metacache.WithSegmentIDs(t.segmentID))
    }
    
    t.execTime = t.tr.ElapseSpan()
    log.Info("task done", zap.Int64("flushedSize", t.flushedSize), 
        zap.Duration("timeTaken", t.execTime))
    
    return nil
}

执行流程图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
┌─────────────────────────────────────────┐
│         SyncTask.Run()                  │
└──────────────┬──────────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 检查段是否存在        │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 获取列分组信息        │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 写入数据到对象存储    │
    │ (BulkPackWriter)     │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 记录监控指标         │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 更新元数据到 DataCoord│
    │ (MetaWriter)        │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 释放数据包           │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 更新本地 MetaCache    │
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │ 任务完成             │
    └──────────────────────┘

元数据更新（writeMeta）

1
2
3
func (t *SyncTask) writeMeta(ctx context.Context) error {
    return t.metaWriter.UpdateSync(ctx, t)
}

MetaWriter 实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
func (b *brokerMetaWriter) UpdateSync(ctx context.Context, pack *SyncTask) error {
    // 1. 构建 SaveBinlogPathsRequest
    req := &datapb.SaveBinlogPathsRequest{
        Base: &commonpb.MsgBase{
            MsgType: commonpb.MsgType_SaveBinlogPaths,
        },
        SegmentID:     pack.segmentID,
        CollectionID:  pack.collectionID,
        Field2BinlogPaths: pack.insertBinlogs,
        Field2StatslogPaths: pack.statsBinlogs,
        Field2BM25StatslogPaths: pack.bm25Binlogs,
        Deltalogs:     []*datapb.FieldBinlog{pack.deltaBinlog},
        CheckPoints:   checkPoints,
        Flushed:       pack.pack.isFlush,  // 刷新标志
        Dropped:       pack.pack.isDrop,    // 删除标志
        // ...
    }
    
    // 2. 重试机制发送 RPC
    err := retry.Handle(ctx, func() (bool, error) {
        err := b.broker.SaveBinlogPaths(ctx, req)
        return err != nil, err
    })
    
    return err
}

错误处理

HandleError 方法

1
2
3
4
5
6
7
8
9
10
11
12
func (t *SyncTask) HandleError(err error) {
    // 调用失败回调
    if t.failureCallback != nil {
        t.failureCallback(err)
    }
    
    // 记录失败指标
    metrics.DataNodeFlushBufferCount.WithLabelValues(metrics.FailLabel, t.level.String()).Inc()
    if !t.pack.isFlush {
        metrics.DataNodeAutoFlushBufferCount.WithLabelValues(metrics.FailLabel, t.level.String()).Inc()
    }
}

Builder 模式创建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 创建 SyncPack
pack := &syncmgr.SyncPack{}
pack.WithInsertData(insertData).
    WithDeleteData(deltaData).
    WithCollectionID(collectionID).
    WithSegmentID(segmentID).
    WithCheckpoint(checkpoint).
    WithFlush()  // 标记为刷新

// 创建 SyncTask
task := syncmgr.NewSyncTask().
    WithSyncPack(pack).
    WithAllocator(allocator).
    WithMetaWriter(metaWriter).
    WithMetaCache(metaCache).
    WithSchema(schema)

// 提交到 SyncManager
future, err := syncMgr.SyncData(ctx, task, callback)

设计特点

1. 异步执行

通过工作池实现异步任务执行，不阻塞主流程。

2. 串行保证

使用 keyLockDispatcher 确保同一段的任务串行执行，避免并发冲突。

3. 存储版本支持

支持 StorageV1 和 StorageV2 两种存储格式。

4. 列分组优化（StorageV2）

根据列统计信息动态分组，优化查询性能。

5. 完善的监控

记录详细的执行指标和性能数据。

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>SyncManager</code> 是 Milvus DataNode 中管理异步数据同步的核心组件，负责将内存中的数据持久化 Milvus Flush 与 Checkpoint 机制详解 https://szza.github.io/2025/08/09/Milvus/8_flush_pipeline_flush_checkpoint/ 2025-08-09T09:00:00.000Z 2026-01-06T13:10:45.427Z 概述

Flush（刷新）和 Checkpoint（检查点）是 Milvus DataNode 中确保数据可靠性和一致性的两个核心机制。它们协同工作，实现数据从内存到持久化存储的完整流程，并保证故障恢复时的数据一致性。

Flush 操作全链路影响

Flush 触发方式

1. 手动刷新（Manual Flush）

1
2
3
4
// 通过 DDL 消息触发
case commonpb.MsgType_ManualFlush:
    manualFlushMsg := msg.(*adaptor.ManualFlushMessageBody)
    ddn.msgHandler.HandleManualFlush(manualFlushMsg.ManualFlushMessage)

流程：

1
DataCoord → ManualFlush 消息 → ddNode → MsgHandler → WriteBufferManager.FlushChannel

2. 自动刷新（Auto Flush）

触发条件：

  • 内存超过阈值（MemoryForceSyncWatermark）
  • 缓冲区满（GetFullBufferPolicy）
  • 时间策略（GetSyncStaleBufferPolicy）
  • 刷新时间戳（GetFlushTsPolicy）

Flush 执行流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
┌─────────────────────────────────────────────────────────────┐
│ 1. FlushChannel 设置 flushTs                                 │
│    WriteBufferManager.FlushChannel(channel, flushTs)        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. WriteBuffer 应用刷新策略                                  │
│    GetFlushTsPolicy: ts >= flushTs 时选择段                 │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 创建 SyncTask（isFlush = true）                           │
│    SyncPack.WithFlush()                                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. SyncTask.Run() 执行                                       │
│    - 写入数据到对象存储                                       │
│    - 更新元数据到 DataCoord                                   │
│    - 更新本地 MetaCache（状态 → Flushed）                    │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 从 MetaCache 移除段                                        │
│    metaCache.RemoveSegments(segmentID)                      │
└─────────────────────────────────────────────────────────────┘

Flush 对系统的影响

1. 数据持久化

  • 对象存储: 数据写入到对象存储（S3/MinIO 等）
  • Binlog 生成: 生成 InsertLogs、StatsLogs、DeltaLogs
  • Manifest: StorageV2 模式下生成 Manifest 文件

2. 元数据更新

  • DataCoord: 通过 SaveBinlogPaths RPC 更新段元数据
  • MetaCache: 更新段状态为 Flushed，并移除段

3. 内存释放

  • WriteBuffer: 释放段缓冲区内存
  • MetaCache: 移除段元数据

4. 监控指标

  • DataNodeFlushBufferCount: 刷新计数
  • DataNodeFlushedSize: 刷新数据大小
  • DataNodeFlushedRows: 刷新行数
  • DataNodeSave2StorageLatency: 存储延迟

Checkpoint 机制

Checkpoint 的作用

  1. 数据消费位置: 记录通道的数据消费位置
  2. 故障恢复: 节点重启后从检查点恢复
  3. 数据一致性: 确保数据不丢失、不重复

Checkpoint 更新流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
┌─────────────────────────────────────────────────────────────┐
│ 1. ttNode 获取检查点                                         │
│    channelPos, needUpdate := GetCheckpoint(channel)         │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 判断是否需要更新                                         │
│    needUpdate = (flushTs != 0 && cp.Timestamp >= flushTs)   │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 添加到 CheckpointUpdater                                  │
│    cpUpdater.AddTask(channelPos, flush=true, callback)      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 异步更新到 DataCoord                                       │
│    broker.UpdateChannelCheckpoint(ctx, channelCPs)          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 更新成功回调                                              │
│    NotifyCheckpointUpdated(channel, ts)                     │
│    if ts > flushTs: reset flushTs                            │
└─────────────────────────────────────────────────────────────┘

Checkpoint 获取逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
func (wb *writeBufferBase) GetCheckpoint() *msgpb.MsgPosition {
    // 1. 如果有非空缓冲区，返回最早的起始位置
    var earliest *checkpointCandidate
    for _, buf := range wb.segmentBuffers {
        if buf.insertBuffer.rows > 0 || buf.deltaBuffer.Size() > 0 {
            if earliest == nil || buf.startPosition.GetTimestamp() < earliest.position.GetTimestamp() {
                earliest = &checkpointCandidate{
                    segmentID: buf.segmentID,
                    position:  buf.startPosition,
                }
            }
        }
    }
    
    // 2. 否则返回最新检查点
    if earliest != nil {
        return earliest.position
    }
    return wb.checkpoint
}

设计原理：

  • 有未同步数据时，检查点不能超过最早未同步数据的起始位置
  • 确保故障恢复时不会丢失数据

Flush 与 Checkpoint 的关系

协同工作流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
┌─────────────────────────────────────────────────────────────┐
│                    Flush 操作                                │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. 设置 flushTs = T1                                         │
│    FlushChannel(channel, flushTs=T1)                        │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 触发数据同步                                              │
│    SyncTask 执行，数据写入对象存储                           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 检查点推进到 T2 (T2 >= T1)                                │
│    GetCheckpoint() 返回 checkpoint = T2                     │
│    needUpdate = (T2 >= T1) = true                            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 更新检查点到 DataCoord                                    │
│    UpdateChannelCheckpoint(T2)                                │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 重置 flushTs                                              │
│    NotifyCheckpointUpdated(channel, T2)                     │
│    if T2 > T1: flushTs = 0                                  │
└─────────────────────────────────────────────────────────────┘

关键条件：ts > flushTs

1
2
3
4
5
6
7
8
9
10
11
12
func (m *bufferManager) NotifyCheckpointUpdated(channel string, ts uint64) {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return
    }
    flushTs := buf.GetFlushTimestamp()
    
    // 关键条件：严格大于
    if flushTs != nonFlushTS && ts > flushTs {
        buf.SetFlushTimestamp(nonFlushTS)
    }
}

为什么需要 ts > flushTs（严格大于）？

1. 异步操作的时序问题

1
2
3
4
5
6
时间线：
T1: FlushChannel(flushTs=T1) 设置刷新时间戳
T2: SyncTask 开始执行（异步）
T3: SyncTask 完成，数据已写入
T4: Checkpoint 更新到 T1（刚好等于 flushTs）
T5: Checkpoint 更新到 T2（大于 flushTs）

如果使用 ts >= flushTs：

  • 在 T4 时刻，T1 >= T1 为真，会重置 flushTs
  • 但此时 SyncTask 可能还未完成，导致数据不一致

使用 ts > flushTs：

  • 在 T4 时刻，T1 > T1 为假，不会重置
  • 在 T5 时刻，T2 > T1 为真，此时 SyncTask 已完成，安全重置

2. 边界情况处理

场景：检查点时间戳等于 flushTs

1
2
flushTs = 1000
checkpoint = 1000  // 刚好等于

问题： 此时数据可能还在同步中，不能确定刷新已完成

解决： 等待检查点超过 flushTs，确保刷新已完成

3. 数据一致性保证

使用严格大于的好处：

  • 确保刷新操作完全完成
  • 避免过早重置 flushTs
  • 保证数据一致性

对比：

  • GetFlushTsPolicy 使用 ts >= flushTs：触发刷新（包含边界）
  • NotifyCheckpointUpdated 使用 ts > flushTs：确认完成（排除边界）

Checkpoint 失败处理

失败场景

  1. 网络故障: RPC 调用失败
  2. DataCoord 不可用: 服务暂时不可用
  3. 超时: RPC 超时

处理机制

1
2
3
4
5
err := ccu.broker.UpdateChannelCheckpoint(ctx, channelCPs)
if err != nil {
    log.Warn("update channel checkpoint failed", zap.Error(err))
    return  // 不删除任务，等待重试
}

特点：

  • 失败时不删除任务
  • 任务保留在 ccu.tasks 中
  • 下次 execute() 或 notifyChan 触发时自动重试

任务合并

1
2
3
4
5
6
7
8
// 合并逻辑：取最大时间戳，保留刷新标志
if task.pos.GetTimestamp() < channelPos.GetTimestamp() || (flush && !task.flush) {
    ccu.tasks[channel] = &channelCPUpdateTask{
        pos:      max(channelPos, task.pos),
        callback: callback,
        flush:    flush || task.flush,
    }
}

优势：

  • 避免重复更新
  • 确保使用最新的检查点
  • 保留刷新触发标志

数据一致性保证

1. 刷新完成确认

1
2
3
4
5
6
7
8
9
FlushChannel(flushTs=T1)
    ↓
SyncTask 执行（异步）
    ↓
Checkpoint 更新到 T2 (T2 > T1)
    ↓
NotifyCheckpointUpdated(T2)
    ↓
重置 flushTs（确认刷新完成）

2. 故障恢复

1
2
3
4
5
6
7
节点重启
    ↓
从 DataCoord 获取检查点
    ↓
从检查点位置恢复数据消费
    ↓
确保数据不丢失、不重复

3. 检查点推进规则

  • 有未同步数据: 检查点不能超过最早未同步数据的起始位置
  • 无未同步数据: 检查点推进到最新位置

监控与调试

关键指标

  • DataNodeFlushBufferCount: 刷新计数
  • DataNodeFlushedSize: 刷新数据大小
  • DataNodeSave2StorageLatency: 存储延迟
  • UpdateChannelCheckpoint: 检查点更新次数

日志关键点

1
2
3
4
5
6
7
8
// Flush 触发
log.Info("receive manual flush message", zap.Uint64("flushTs", flushTs))

// 检查点更新
log.Info("reset channel flushTs", zap.String("channel", channel))

// 检查点更新成功
log.Debug("UpdateChannelCheckpoint success", zap.Uint64("cpTs", ts))

最佳实践

1. Flush 时机

  • 手动刷新: 数据导入完成后
  • 自动刷新: 基于内存阈值和时间策略

2. Checkpoint 更新频率

  • 定期更新: 避免过于频繁的 RPC
  • 刷新触发: 立即更新，加速刷新完成确认

3. 故障处理

  • 重试机制: 自动重试失败的检查点更新
  • 任务合并: 避免重复更新

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p>Flush（刷新）和 Checkpoint（检查点）是 Milvus DataNode 中确保数据可靠性和一致性的两个核心机制。它们协同工作 Milvus WriteBuffer 实现详解 https://szza.github.io/2025/08/09/Milvus/7_flush_pipeline_write_buffer/ 2025-08-09T08:00:00.000Z 2026-01-06T13:10:45.056Z 概述

WriteBuffer 是 Milvus DataNode 中管理单个通道数据缓冲的核心组件。它负责接收和缓冲插入/删除数据，根据同步策略触发数据同步，并管理段的生命周期。

接口定义

1
2
3
4
5
6
7
8
9
10
11
12
13
type WriteBuffer interface {
    HasSegment(segmentID int64) bool
    CreateNewGrowingSegment(partitionID int64, segmentID int64, startPos *msgpb.MsgPosition)
    BufferData(insertMsgs []*InsertData, deleteMsgs []*msgstream.DeleteMsg, startPos, endPos *msgpb.MsgPosition) error
    SetFlushTimestamp(flushTs uint64)
    GetFlushTimestamp() uint64
    SealSegments(ctx context.Context, segmentIDs []int64) error
    DropPartitions(partitionIDs []int64)
    GetCheckpoint() *msgpb.MsgPosition
    MemorySize() int64
    EvictBuffer(policies ...SyncPolicy)
    Close(ctx context.Context, drop bool)
}

基础实现（writeBufferBase）

核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
type writeBufferBase struct {
    channelName string
    collectionID int64
    
    mut sync.RWMutex
    
    segmentBuffers map[int64]*segmentBuffer
    checkpoint     *msgpb.MsgPosition
    flushTimestamp *atomic.Uint64
    
    syncMgr   syncmgr.SyncManager
    metaCache metacache.MetaCache
    
    syncPolicies []SyncPolicy
    // ... 其他字段
}

段缓冲（segmentBuffer）

1
2
3
4
5
6
7
8
9
type segmentBuffer struct {
    segmentID int64
    
    insertBuffer *InsertBuffer
    deltaBuffer  *DeltaBuffer
    
    startPosition *msgpb.MsgPosition
    checkpoint    *msgpb.MsgPosition
}

功能：

  • insertBuffer: 存储插入数据
  • deltaBuffer: 存储删除数据
  • 维护段的起始位置和检查点

L0 WriteBuffer 特殊实现

为什么需要 L0 WriteBuffer？

在流式服务模式下，已刷新的段不再维护 Bloom Filter。为了高效处理删除操作，Milvus 引入了 L0 段（Level-0 Segment）专门用于存储删除数据。

核心结构

1
2
3
4
5
6
7
8
9
type l0WriteBuffer struct {
    *writeBufferBase
    
    l0Segments  map[int64]int64  // partitionID => l0 segment ID
    l0partition map[int64]int64  // l0 segment id => partition id
    
    syncMgr     syncmgr.SyncManager
    idAllocator allocator.Interface
}

关键差异

1. 删除消息分发（不使用 Bloom Filter）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
func (wb *l0WriteBuffer) dispatchDeleteMsgsWithoutFilter(deleteMsgs []*msgstream.DeleteMsg, 
    startPos, endPos *msgpb.MsgPosition) {
    
    for _, msg := range deleteMsgs {
        // 获取或创建 L0 段 ID
        l0SegmentID := wb.getL0SegmentID(msg.GetPartitionID(), startPos)
        
        // 解析主键和时间戳
        pks := storage.ParseIDs2PrimaryKeys(msg.GetPrimaryKeys())
        pkTss := msg.GetTimestamps()
        
        if len(pks) > 0 {
            // 直接缓冲删除数据，不使用 Bloom Filter 过滤
            wb.bufferDelete(l0SegmentID, pks, pkTss, startPos, endPos)
        }
    }
}

特点：

  • 不进行 Bloom Filter 过滤
  • 所有删除消息都写入 L0 段
  • 简化了删除处理逻辑

2. L0 段管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
func (wb *l0WriteBuffer) getL0SegmentID(partitionID int64, startPos *msgpb.MsgPosition) int64 {
    segmentID, ok := wb.l0Segments[partitionID]
    if !ok {
        // 分配新的 L0 段 ID
        err := retry.Do(context.Background(), func() error {
            var err error
            segmentID, err = wb.idAllocator.AllocOne()
            return err
        })
        
        wb.l0Segments[partitionID] = segmentID
        wb.l0partition[segmentID] = partitionID
        
        // 添加到 MetaCache，标记为 L0 Growing
        wb.metaCache.AddSegment(&datapb.SegmentInfo{
            ID:            segmentID,
            PartitionID:   partitionID,
            CollectionID:  wb.collectionID,
            InsertChannel: wb.channelName,
            StartPosition: startPos,
            State:         commonpb.SegmentState_Growing,
            Level:         datapb.SegmentLevel_L0,  // L0 级别
        }, ...)
    }
    return segmentID
}

特点：

  • 每个分区对应一个 L0 段
  • L0 段始终标记为 Growing 状态
  • L0 段总是需要刷新（isFlush = true）

数据缓冲流程

BufferData 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
func (wb *l0WriteBuffer) BufferData(insertData []*InsertData, deleteMsgs []*msgstream.DeleteMsg, 
    startPos, endPos *msgpb.MsgPosition) error {
    
    wb.mut.Lock()
    defer wb.mut.Unlock()
    
    // 1. 缓冲插入数据
    for _, inData := range insertData {
        err := wb.bufferInsert(inData, startPos, endPos)
        if err != nil {
            return err
        }
    }
    
    // 2. 分发删除消息（不使用 Bloom Filter）
    wb.dispatchDeleteMsgsWithoutFilter(deleteMsgs, startPos, endPos)
    
    // 3. 更新检查点
    wb.checkpoint = endPos
    
    // 4. 触发同步
    segmentsSync := wb.triggerSync()
    
    // 5. 清理已同步的 L0 段映射
    for _, segment := range segmentsSync {
        partition, ok := wb.l0partition[segment]
        if ok {
            delete(wb.l0partition, segment)
            delete(wb.l0Segments, partition)
        }
    }
    
    return nil
}

同步策略（SyncPolicy）

策略接口

1
2
3
4
type SyncPolicy interface {
    SelectSegments(buffers []*segmentBuffer, ts typeutil.Timestamp) []int64
    Reason() string
}

常用策略

1. 满缓冲区策略

1
2
3
4
5
6
7
8
9
10
11
func GetFullBufferPolicy() SyncPolicy {
    return wrapSelectSegmentFuncPolicy(func(buffers []*segmentBuffer, ts typeutil.Timestamp) []int64 {
        var result []int64
        for _, buf := range buffers {
            if buf.insertBuffer.IsFull() {
                result = append(result, buf.segmentID)
            }
        }
        return result
    }, "full buffer")
}

2. 刷新时间戳策略

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
func GetFlushTsPolicy(flushTimestamp *atomic.Uint64, meta metacache.MetaCache) SyncPolicy {
    return wrapSelectSegmentFuncPolicy(func(buffers []*segmentBuffer, ts typeutil.Timestamp) []int64 {
        flushTs := flushTimestamp.Load()
        if flushTs != nonFlushTS && ts >= flushTs {
            var result []int64
            for _, buf := range buffers {
                if buf.insertBuffer.MinTimestamp() < flushTs {
                    result = append(result, buf.segmentID)
                }
            }
            return result
        }
        return nil
    }, "flush ts")
}

触发条件： 当前时间戳 >= flushTs

3. 最老缓冲区策略

1
2
3
4
5
6
func GetOldestBufferPolicy(maxNum int) SyncPolicy {
    return wrapSelectSegmentFuncPolicy(func(buffers []*segmentBuffer, ts typeutil.Timestamp) []int64 {
        // 按时间戳排序，选择最老的 N 个
        // ...
    }, "oldest buffer")
}

同步触发机制

EvictBuffer 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
func (wb *writeBufferBase) EvictBuffer(policies ...SyncPolicy) {
    wb.mut.RLock()
    buffers := make([]*segmentBuffer, 0, len(wb.segmentBuffers))
    for _, buf := range wb.segmentBuffers {
        buffers = append(buffers, buf)
    }
    currentTs := wb.checkpoint.GetTimestamp()
    wb.mut.RUnlock()
    
    // 合并所有策略
    allPolicies := append(wb.syncPolicies, policies...)
    
    // 收集需要同步的段
    segmentIDs := typeutil.NewUniqueSet()
    for _, policy := range allPolicies {
        selected := policy.SelectSegments(buffers, currentTs)
        for _, id := range selected {
            segmentIDs.Insert(id)
        }
    }
    
    // 执行同步
    if segmentIDs.Len() > 0 {
        wb.syncSegments(context.Background(), segmentIDs.Collect())
    }
}

syncSegments 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
func (wb *writeBufferBase) syncSegments(ctx context.Context, segmentIDs []int64) []*conc.Future[struct{}] {
    var futures []*conc.Future[struct{}]
    
    for _, segmentID := range segmentIDs {
        // 创建同步任务
        task, err := wb.getSyncTask(ctx, segmentID)
        if err != nil {
            continue
        }
        
        // 提交到 SyncManager
        future, err := wb.syncMgr.SyncData(ctx, task, func(err error) error {
            if err == nil && task.IsFlush() {
                // 刷新成功后，从 MetaCache 移除段
                wb.metaCache.RemoveSegments(metacache.WithSegmentIDs(segmentID))
            }
            return err
        })
        
        futures = append(futures, future)
    }
    
    return futures
}

检查点管理

GetCheckpoint

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
func (wb *writeBufferBase) GetCheckpoint() *msgpb.MsgPosition {
    wb.mut.RLock()
    defer wb.mut.RUnlock()
    
    // 如果有非空缓冲区，返回最早的起始位置
    var earliest *checkpointCandidate
    for _, buf := range wb.segmentBuffers {
        if buf.insertBuffer.rows > 0 || buf.deltaBuffer.Size() > 0 {
            candidate := &checkpointCandidate{
                segmentID: buf.segmentID,
                position:  buf.startPosition,
            }
            if earliest == nil || candidate.position.GetTimestamp() < earliest.position.GetTimestamp() {
                earliest = candidate
            }
        }
    }
    
    // 否则返回最新检查点
    if earliest != nil {
        return earliest.position
    }
    return wb.checkpoint
}

段生命周期管理

SealSegments

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
func (wb *writeBufferBase) SealSegments(ctx context.Context, segmentIDs []int64) error {
    wb.mut.Lock()
    defer wb.mut.Unlock()
    
    // 更新 MetaCache：Growing -> Sealed
    wb.metaCache.UpdateSegments(
        metacache.UpdateState(commonpb.SegmentState_Sealed),
        metacache.WithSegmentIDs(segmentIDs...),
    )
    
    // 触发同步
    wb.syncSegments(ctx, segmentIDs)
    
    return nil
}

默认实现选择

1
2
3
4
5
6
func NewWriteBuffer(channel string, metacache metacache.MetaCache, 
    syncMgr syncmgr.SyncManager, opts ...WriteBufferOption) (WriteBuffer, error) {
    
    // 默认使用 L0WriteBuffer
    return NewL0WriteBuffer(channel, metacache, syncMgr, option)
}

原因：

  • L0WriteBuffer 适配流式服务模式
  • 简化删除处理逻辑
  • 提高删除操作性能

设计特点

1. 分层设计

  • WriteBuffer 接口：定义抽象
  • writeBufferBase：基础实现
  • l0WriteBuffer：特殊实现

2. 策略模式

通过 SyncPolicy 实现灵活的同步策略。

3. 线程安全

使用 RWMutex 保护共享状态。

4. 异步同步

通过 SyncManager 实现异步数据同步。

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>WriteBuffer</code> 是 Milvus DataNode 中管理单个通道数据缓冲的核心组件。它负责接收和缓冲插入 Milvus WriteBuffer 管理器（bufferManager）详解 https://szza.github.io/2025/08/09/Milvus/6_flush_pipeline_write_buffer_manager/ 2025-08-09T07:00:00.000Z 2026-01-06T13:10:44.620Z 概述

bufferManager 是 Milvus DataNode 中管理多个 WriteBuffer 实例的核心组件。它负责按通道组织和管理数据缓冲，实现内存监控、自动驱逐和刷新策略。

架构设计

核心结构

1
2
3
4
5
6
7
type bufferManager struct {
    syncMgr syncmgr.SyncManager
    buffers *typeutil.ConcurrentMap[string, WriteBuffer]
    
    wg sync.WaitGroup
    ch lifetime.SafeChan
}

关键字段说明：

  • syncMgr: 同步管理器，用于提交同步任务
  • buffers: 线程安全的映射表，key 为通道名，value 为对应的 WriteBuffer
  • wg: WaitGroup，用于等待后台 goroutine 退出
  • ch: 安全通道，用于控制后台检查的启停

接口定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
type BufferManager interface {
    Register(channel string, metacache metacache.MetaCache, opts ...WriteBufferOption) error
    CreateNewGrowingSegment(ctx context.Context, channel string, partition int64, segmentID int64) error
    SealSegments(ctx context.Context, channel string, segmentIDs []int64) error
    FlushChannel(ctx context.Context, channel string, flushTs uint64) error
    RemoveChannel(channel string)
    DropChannel(channel string)
    DropPartitions(channel string, partitionIDs []int64)
    BufferData(channel string, insertData []*InsertData, deleteMsgs []*msgstream.DeleteMsg, startPos, endPos *msgpb.MsgPosition) error
    GetCheckpoint(channel string) (*msgpb.MsgPosition, bool, error)
    NotifyCheckpointUpdated(channel string, ts uint64)
    
    Start()
    Stop()
}

核心功能

1. 通道注册

1
2
3
4
5
6
7
8
9
10
11
12
13
func (m *bufferManager) Register(channel string, metacache metacache.MetaCache, opts ...WriteBufferOption) error {
    buf, err := NewWriteBuffer(channel, metacache, m.syncMgr, opts...)
    if err != nil {
        return err
    }
    
    _, loaded := m.buffers.GetOrInsert(channel, buf)
    if loaded {
        buf.Close(context.Background(), false)
        return merr.WrapErrChannelReduplicate(channel)
    }
    return nil
}

功能：

  • 创建新的 WriteBuffer 实例
  • 注册到管理器
  • 防止重复注册

2. 数据缓冲

1
2
3
4
5
6
7
8
9
10
func (m *bufferManager) BufferData(channel string, insertData []*InsertData, 
    deleteMsgs []*msgstream.DeleteMsg, startPos, endPos *msgpb.MsgPosition) error {
    
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return merr.WrapErrChannelNotFound(channel)
    }
    
    return buf.BufferData(insertData, deleteMsgs, startPos, endPos)
}

3. 段管理

创建 Growing 段

1
2
3
4
5
6
7
8
9
10
func (m *bufferManager) CreateNewGrowingSegment(ctx context.Context, channel string, 
    partitionID int64, segmentID int64) error {
    
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return merr.WrapErrChannelNotFound(channel)
    }
    buf.CreateNewGrowingSegment(partitionID, segmentID, nil)
    return nil
}

封装段

1
2
3
4
5
6
7
8
func (m *bufferManager) SealSegments(ctx context.Context, channel string, segmentIDs []int64) error {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return merr.WrapErrChannelNotFound(channel)
    }
    
    return buf.SealSegments(ctx, segmentIDs)
}

功能：

  • 将段状态从 Growing 变为 Sealed
  • 触发段的同步操作

4. 刷新通道

1
2
3
4
5
6
7
8
func (m *bufferManager) FlushChannel(ctx context.Context, channel string, flushTs uint64) error {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return merr.WrapErrChannelNotFound(channel)
    }
    buf.SetFlushTimestamp(flushTs)
    return nil
}

功能：

  • 设置通道的刷新时间戳（flushTs）
  • 触发基于时间戳的刷新策略

5. 检查点管理

获取检查点

1
2
3
4
5
6
7
8
9
10
11
func (m *bufferManager) GetCheckpoint(channel string) (*msgpb.MsgPosition, bool, error) {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return nil, false, merr.WrapErrChannelNotFound(channel)
    }
    cp := buf.GetCheckpoint()
    flushTs := buf.GetFlushTimestamp()
    
    // 返回检查点和是否需要更新的标志
    return cp, flushTs != nonFlushTS && cp.GetTimestamp() >= flushTs, nil
}

返回值说明：

  • *msgpb.MsgPosition: 通道检查点
  • bool: 是否需要更新（当检查点时间戳 >= flushTs 时返回 true）
  • error: 错误信息

通知检查点更新

1
2
3
4
5
6
7
8
9
10
11
12
13
func (m *bufferManager) NotifyCheckpointUpdated(channel string, ts uint64) {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return
    }
    flushTs := buf.GetFlushTimestamp()
    
    // 关键条件：ts > flushTs
    if flushTs != nonFlushTS && ts > flushTs {
        log.Info("reset channel flushTs", zap.String("channel", channel))
        buf.SetFlushTimestamp(nonFlushTS)
    }
}

关键逻辑：

  • 当检查点时间戳严格大于 flushTs 时，重置 flushTs
  • 这确保了刷新操作已完成，可以安全重置

内存管理

后台检查机制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
func (m *bufferManager) Start() {
    m.wg.Add(1)
    go func() {
        defer m.wg.Done()
        m.check()
    }()
}

func (m *bufferManager) check() {
    timer := time.NewTimer(paramtable.Get().DataNodeCfg.MemoryCheckInterval.GetAsDuration(time.Millisecond))
    defer timer.Stop()
    
    for {
        select {
        case <-timer.C:
            m.memoryCheck()
            timer.Reset(paramtable.Get().DataNodeCfg.MemoryCheckInterval.GetAsDuration(time.Millisecond))
        case <-m.ch.CloseCh():
            log.Info("buffer manager memory check stopped")
            return
        }
    }
}

内存检查逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
func (m *bufferManager) memoryCheck() {
    if !paramtable.Get().DataNodeCfg.MemoryForceSyncEnable.GetAsBool() {
        return
    }
    
    for {
        var total int64
        var candidate WriteBuffer
        var candiSize int64
        var candiChan string
        
        // 遍历所有缓冲区，找到最大的
        m.buffers.Range(func(chanName string, buf WriteBuffer) bool {
            size := buf.MemorySize()
            total += size
            if size > candiSize {
                candiSize = size
                candidate = buf
                candiChan = chanName
            }
            return true
        })
        
        // 检查是否超过水位线
        totalMemory := hardware.GetMemoryCount()
        memoryWatermark := float64(totalMemory) * paramtable.Get().DataNodeCfg.MemoryForceSyncWatermark.GetAsFloat()
        
        if float64(total) < memoryWatermark {
            return  // 未超过水位线，退出
        }
        
        // 触发同步
        if candidate != nil {
            candidate.EvictBuffer(GetOldestBufferPolicy(
                paramtable.Get().DataNodeCfg.MemoryForceSyncSegmentNum.GetAsInt()))
            log.Info("notify writebuffer to sync",
                zap.String("channel", candiChan), 
                zap.Float64("bufferSize(MB)", logutil.ToMB(float64(candiSize))))
        }
    }
}

内存管理策略：

  1. 定期检查: 按配置的时间间隔检查内存使用
  2. 水位线机制: 当总内存超过水位线时触发同步
  3. 选择策略: 选择内存使用最大的缓冲区进行同步
  4. 驱逐策略: 使用 GetOldestBufferPolicy 选择最老的段进行同步

通道生命周期管理

移除通道

1
2
3
4
5
6
7
8
9
func (m *bufferManager) RemoveChannel(channel string) {
    buf, loaded := m.buffers.GetAndRemove(channel)
    if !loaded {
        return
    }
    
    // 丢弃所有缓冲数据
    buf.Close(context.Background(), false)
}

用途： 通道迁移时，丢弃本地缓冲数据

删除通道

1
2
3
4
5
6
7
8
9
func (m *bufferManager) DropChannel(channel string) {
    buf, loaded := m.buffers.GetAndRemove(channel)
    if !loaded {
        return
    }
    
    // 保存所有缓冲数据
    buf.Close(context.Background(), true)
}

用途： 删除集合时，保存所有缓冲数据

删除分区

1
2
3
4
5
6
7
8
func (m *bufferManager) DropPartitions(channel string, partitionIDs []int64) {
    buf, loaded := m.buffers.Get(channel)
    if !loaded {
        return
    }
    
    buf.DropPartitions(partitionIDs)
}

设计特点

1. 线程安全

使用 ConcurrentMap 实现线程安全的并发访问。

2. 内存保护

通过后台检查机制，防止内存溢出。

3. 灵活的策略

支持多种同步策略（内存、时间、手动刷新等）。

4. 优雅关闭

通过 SafeChan 和 WaitGroup 实现优雅关闭。

与其他组件的关系

1
2
3
4
5
6
7
8
9
10
11
12
bufferManager
    │
    ├── WriteBuffer (按通道组织)
    │       │
    │       ├── segmentBuffer (按段组织)
    │       │       ├── InsertBuffer
    │       │       └── DeltaBuffer
    │       │
    │       └── SyncPolicy (同步策略)
    │
    └── SyncManager
            └── SyncTask

配置参数

  • MemoryCheckInterval: 内存检查间隔
  • MemoryForceSyncEnable: 是否启用强制同步
  • MemoryForceSyncWatermark: 内存强制同步水位线
  • MemoryForceSyncSegmentNum: 每次强制同步的段数量

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>bufferManager</code> 是 Milvus DataNode 中管理多个 <code>WriteBuffer</ Milvus DDNode（数据分发节点）详解 https://szza.github.io/2025/08/09/Milvus/5_flush_pipeline_dd_node/ 2025-08-09T06:00:00.000Z 2026-01-06T13:10:44.131Z 概述

ddNode（Data Distribution Node）是 FlowGraph 中的第一个处理节点，负责从消息流中过滤和分发消息。它处理插入消息、删除消息以及 DDL 消息（如 CreateSegment、Flush、DropCollection），确保只有有效的数据消息传递到后续节点。

架构设计

核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
type ddNode struct {
    BaseNode
    
    ctx          context.Context
    collectionID typeutil.UniqueID
    vChannelName  string
    
    dropMode   atomic.Value
    msgHandler util.MsgHandler
    
    // 段信息缓存（用于过滤）
    growingSegInfo    map[typeutil.UniqueID]*datapb.SegmentInfo
    sealedSegInfo     map[typeutil.UniqueID]*datapb.SegmentInfo
    droppedSegmentIDs []int64
}

关键字段说明：

  • dropMode: 原子值，标记是否处于删除模式
  • msgHandler: DDL 消息处理器
  • growingSegInfo: Growing 段信息映射
  • sealedSegInfo: Sealed 段信息映射
  • droppedSegmentIDs: 已删除段 ID 列表

消息处理流程

Operate 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
func (ddn *ddNode) Operate(in []Msg) []Msg {
    msMsg, ok := in[0].(*MsgStreamMsg)
    if !ok {
        return []Msg{}
    }
    
    // 1. 处理关闭消息
    if msMsg.IsCloseMsg() {
        return []Msg{&FlowGraphMsg{...}}
    }
    
    // 2. 检查删除模式
    if load := ddn.dropMode.Load(); load != nil && load.(bool) {
        return []Msg{}
    }
    
    // 3. 处理消息流中的每条消息
    fgMsg := FlowGraphMsg{...}
    for _, msg := range msMsg.TsMessages() {
        switch msg.Type() {
        case commonpb.MsgType_DropCollection:
            // 处理删除集合消息
        case commonpb.MsgType_DropPartition:
            // 处理删除分区消息
        case commonpb.MsgType_Insert:
            // 处理插入消息
        case commonpb.MsgType_Delete:
            // 处理删除消息
        case commonpb.MsgType_CreateSegment:
            // 处理创建段消息
        case commonpb.MsgType_FlushSegment:
            // 处理刷新段消息
        case commonpb.MsgType_ManualFlush:
            // 处理手动刷新消息
        case commonpb.MsgType_AddCollectionField:
            // 处理 Schema 变更消息
        case commonpb.MsgType_AlterCollection:
            // 处理修改集合消息
        }
    }
    
    return []Msg{&fgMsg}
}

消息类型处理

1. Insert 消息处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
case commonpb.MsgType_Insert:
    imsg := msg.(*msgstream.InsertMsg)
    
    // 检查集合 ID 匹配
    if imsg.CollectionID != ddn.collectionID {
        continue
    }
    
    // 过滤段消息
    if ddn.tryToFilterSegmentInsertMessages(imsg) {
        continue
    }
    
    // 记录指标
    metrics.DataNodeConsumeMsgCount.Inc()
    metrics.DataNodeConsumeMsgRowsCount.Add(float64(imsg.GetNumRows()))
    
    // 添加到输出消息
    fgMsg.InsertMessages = append(fgMsg.InsertMessages, imsg)

2. Delete 消息处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
case commonpb.MsgType_Delete:
    dmsg := msg.(*msgstream.DeleteMsg)
    
    // 检查集合 ID 匹配
    if dmsg.CollectionID != ddn.collectionID {
        continue
    }
    
    // 记录指标
    metrics.DataNodeConsumeMsgCount.Inc()
    metrics.DataNodeConsumeMsgRowsCount.Add(float64(dmsg.GetNumRows()))
    
    // 添加到输出消息
    fgMsg.DeleteMessages = append(fgMsg.DeleteMessages, dmsg)

3. DDL 消息处理

CreateSegment

1
2
3
4
5
case commonpb.MsgType_CreateSegment:
    createSegment := msg.(*adaptor.CreateSegmentMessageBody)
    if err := ddn.msgHandler.HandleCreateSegment(ddn.ctx, createSegment.CreateSegmentMessage); err != nil {
        log.Warn("handle create segment message failed", zap.Error(err))
    }

FlushSegment

1
2
3
4
5
case commonpb.MsgType_FlushSegment:
    flushMsg := msg.(*adaptor.FlushMessageBody)
    if err := ddn.msgHandler.HandleFlush(flushMsg.FlushMessage); err != nil {
        log.Warn("handle flush message failed", zap.Error(err))
    }

ManualFlush

1
2
3
4
5
case commonpb.MsgType_ManualFlush:
    manualFlushMsg := msg.(*adaptor.ManualFlushMessageBody)
    if err := ddn.msgHandler.HandleManualFlush(manualFlushMsg.ManualFlushMessage); err != nil {
        log.Warn("handle manual flush message failed", zap.Error(err))
    }

消息过滤机制

tryToFilterSegmentInsertMessages

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
func (ddn *ddNode) tryToFilterSegmentInsertMessages(msg *msgstream.InsertMsg) bool {
    // 1. 检查 Shard 名称匹配
    if msg.GetShardName() != ddn.vChannelName {
        return true
    }
    
    // 2. 过滤已删除的段
    if ddn.isDropped(msg.GetSegmentID()) {
        return true
    }
    
    // 3. 过滤 Sealed 段（直到当前时间戳超过段的检查点）
    for segID, segInfo := range ddn.sealedSegInfo {
        if msg.EndTs() > segInfo.GetDmlPosition().GetTimestamp() {
            delete(ddn.sealedSegInfo, segID)
        }
    }
    if _, ok := ddn.sealedSegInfo[msg.GetSegmentID()]; ok {
        return true
    }
    
    // 4. 过滤 Growing 段（直到当前时间戳超过段的 DML 位置）
    if si, ok := ddn.growingSegInfo[msg.GetSegmentID()]; ok {
        if msg.EndTs() <= si.GetDmlPosition().GetTimestamp() {
            return true
        }
        delete(ddn.growingSegInfo, msg.GetSegmentID())
    }
    
    return false
}

过滤逻辑说明：

  1. Shard 名称检查: 确保消息属于当前通道
  2. 删除段过滤: 过滤掉已删除段的消息
  3. Sealed 段过滤: 过滤已封装的段，直到消息时间戳超过段的检查点
  4. Growing 段过滤: 过滤 Growing 段中已处理的消息

消息类型（MsgType）赋值流程

消息创建时的赋值

消息的 MsgType 在创建时通过 commonpbutil.WithMsgType 设置：

1
2
3
4
5
6
7
8
9
10
11
// 在消息创建时
msg := &msgstream.InsertMsg{
    BaseMsg: msgstream.BaseMsg{
        Base: commonpbutil.NewMsgBase(
            commonpbutil.WithMsgType(commonpb.MsgType_Insert),
            commonpbutil.WithMsgID(...),
            commonpbutil.WithTimeStamp(...),
        ),
    },
    InsertRequest: &msgpb.InsertRequest{...},
}

消息类型获取

1
2
3
4
// InsertMsg 实现
func (it *InsertMsg) Type() MsgType {
    return it.Base.MsgType  // 返回 Base 中的 MsgType
}

消息流中的传递

1
消息创建 → 序列化 → 消息流 → MsgStreamMsg 包装 → ddNode.Operate → msg.Type()

初始化流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
func newDDNode(ctx context.Context, collID typeutil.UniqueID, vChannelName string,
    droppedSegmentIDs []typeutil.UniqueID,
    sealedSegments []*datapb.SegmentInfo, 
    growingSegments []*datapb.SegmentInfo, 
    handler util.MsgHandler) *ddNode {
    
    dd := &ddNode{
        ctx:               ctx,
        collectionID:      collID,
        sealedSegInfo:     make(map[typeutil.UniqueID]*datapb.SegmentInfo, len(sealedSegments)),
        growingSegInfo:    make(map[typeutil.UniqueID]*datapb.SegmentInfo, len(growingSegments)),
        droppedSegmentIDs: droppedSegmentIDs,
        vChannelName:      vChannelName,
        msgHandler:        handler,
    }
    
    // 初始化段信息
    for _, s := range sealedSegments {
        dd.sealedSegInfo[s.GetID()] = s
    }
    
    for _, s := range growingSegments {
        dd.growingSegInfo[s.GetID()] = s
    }
    
    dd.dropMode.Store(false)
    return dd
}

监控指标

消费指标

  • DataNodeConsumeMsgCount: 消费消息数量
  • DataNodeConsumeMsgRowsCount: 消费行数
  • DataNodeConsumeBytesCount: 消费字节数

速率指标

  • InsertConsumeThroughput: 插入消息吞吐量
  • DeleteConsumeThroughput: 删除消息吞吐量

设计特点

1. 早期过滤

在 FlowGraph 的第一个节点就进行过滤，减少无效消息的传递和处理。

2. 状态管理

维护段的 Growing/Sealed/Dropped 状态，实现精确的消息过滤。

3. DDL 委托

将 DDL 消息处理委托给 MsgHandler，实现关注点分离。

4. 线程安全

使用原子操作管理 dropMode，支持并发访问。

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>ddNode</code>（Data Distribution Node）是 FlowGraph 中的第一个处理节点，负责从消息 Milvus 数据消费 DataSyncService 详解 https://szza.github.io/2025/08/09/Milvus/4_flush_pipeline_data_sync_service/ 2025-08-09T05:00:00.000Z 2026-01-06T13:10:43.773Z 概述

DataSyncService 是 Milvus DataNode 中控制单个通道（Channel）数据同步的核心服务。它负责组装和管理 FlowGraph，协调各个组件完成数据从消息流到持久化存储的完整流程。

架构设计

核心结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
type DataSyncService struct {
    ctx          context.Context
    cancelFn     context.CancelFunc
    metacache    metacache.MetaCache
    opID         int64
    collectionID typeutil.UniqueID
    vchannelName string
    serverID     typeutil.UniqueID
    
    fg *flowgraph.TimeTickedFlowGraph  // 内部 FlowGraph
    
    broker         broker.Broker
    timetickSender util.StatsUpdater
    dispClient     msgdispatcher.Client
    chunkManager   storage.ChunkManager
    
    stopOnce sync.Once
}

关键字段说明：

  • fg: TimeTickedFlowGraph，消息处理管道
  • metacache: 段元数据缓存
  • broker: 与 DataCoord 通信的代理
  • timetickSender: 时间戳发送器
  • dispClient: 消息分发客户端
  • chunkManager: 对象存储管理器

FlowGraph 组装流程

节点配置

1
2
3
4
5
6
7
8
type nodeConfig struct {
    msFactory    msgstream.Factory
    collectionID typeutil.UniqueID
    vChannelName string
    metacache    metacache.MetaCache
    serverID     typeutil.UniqueID
    dropCallback func()
}

节点创建与组装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
func getServiceWithChannel(...) (*DataSyncService, error) {
    // 1. 创建 FlowGraph
    fg := flowgraph.NewTimeTickedFlowGraph(params.Ctx)
    nodeList := []flowgraph.Node{}
    
    // 2. 创建输入节点
    dmStreamNode := newDmInputNode(config, input)
    nodeList = append(nodeList, dmStreamNode)
    
    // 3. 创建 DD Node（数据分发节点）
    ddNode := newDDNode(
        params.Ctx,
        collectionID,
        channelName,
        info.GetVchan().GetDroppedSegmentIds(),
        flushed,
        unflushed,
        params.MsgHandler,
    )
    nodeList = append(nodeList, ddNode)
    
    // 4. 创建 Embedding Node（如果启用）
    if len(info.GetSchema().GetFunctions()) > 0 {
        emNode, err := newEmbeddingNode(channelName, config.metacache)
        if err != nil {
            return nil, err
        }
        nodeList = append(nodeList, emNode)
    }
    
    // 5. 创建 Write Node
    writeNode, err := newWriteNode(params.Ctx, params.WriteBufferManager, ds.timetickSender, config)
    if err != nil {
        return nil, err
    }
    nodeList = append(nodeList, writeNode)
    
    // 6. 创建 TT Node（时间戳节点）
    ttNode := newTTNode(config, params.WriteBufferManager, params.CheckpointUpdater)
    nodeList = append(nodeList, ttNode)
    
    // 7. 组装节点
    if err := fg.AssembleNodes(nodeList...); err != nil {
        return nil, err
    }
    ds.fg = fg
    
    // 8. 注册通道到 WriteBufferManager
    err = params.WriteBufferManager.Register(channelName, metacache,
        writebuffer.WithMetaWriter(syncmgr.BrokerMetaWriter(params.Broker, config.serverID)),
        writebuffer.WithIDAllocator(params.Allocator),
        writebuffer.WithTaskObserverCallback(wbTaskObserverCallback))
    
    return ds, nil
}

FlowGraph 节点链路

1
2
3
4
5
6
7
8
9
输入节点 (dmStreamNode)
    ↓
DD Node (ddNode) - 消息过滤和 DDL 处理
    ↓
Embedding Node (emNode) - 可选，向量嵌入处理
    ↓
Write Node (writeNode) - 数据缓冲
    ↓
TT Node (ttNode) - Checkpoint 更新

MetaCache 初始化

从 Checkpoint 恢复

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
func initMetaCache(...) (metacache.MetaCache, error) {
    // 1. 加载段统计信息（Bloom Filter）
    loadSegmentStats := func(segType string, segments []*datapb.SegmentInfo) {
        for _, item := range segments {
            future := io.GetOrCreateStatsPool().Submit(func() (any, error) {
                stats, err := compaction.LoadStats(initCtx, chunkManager, info.GetSchema(), 
                    segment.GetID(), segment.GetStatslogs())
                if err != nil {
                    return nil, err
                }
                segmentPks.Insert(segment.GetID(), pkoracle.NewBloomFilterSet(stats...))
                
                // 加载 BM25 统计（仅 Growing 段）
                if segType == "growing" && len(segment.GetBm25Statslogs()) > 0 {
                    bm25stats, err := compaction.LoadBM25Stats(...)
                    segmentBm25.Insert(segment.GetID(), bm25stats)
                }
                return struct{}{}, nil
            })
            futures = append(futures, future)
        }
    }
    
    // 2. 加载 Growing 和 Sealed 段的统计
    loadSegmentStats("growing", unflushed)
    if !streamingutil.IsStreamingServiceEnabled() {
        loadSegmentStats("sealed", flushed)
    }
    
    // 3. 等待所有统计加载完成
    if err := conc.AwaitAll(futures...); err != nil {
        return nil, err
    }
    
    // 4. 创建 MetaCache
    pkStatsFactory := func(segment *datapb.SegmentInfo) pkoracle.PkStat {
        pkStat, _ := segmentPks.Get(segment.GetID())
        return pkStat
    }
    
    metacache := metacache.NewMetaCache(info, pkStatsFactory, bm25StatsFactor, schemaManager)
    return metacache, nil
}

生命周期管理

启动 FlowGraph

1
2
3
4
5
6
7
8
func (dsService *DataSyncService) Start() {
    if dsService.fg != nil {
        log.Info("dataSyncService starting flow graph", 
            zap.Int64("collectionID", dsService.collectionID),
            zap.String("vChanName", dsService.vchannelName))
        dsService.fg.Start()
    }
}

优雅关闭

1
2
3
4
5
6
7
func (dsService *DataSyncService) GracefullyClose() {
    if dsService.fg != nil {
        log.Info("dataSyncService gracefully closing flowgraph")
        dsService.fg.SetCloseMethod(flowgraph.CloseGracefully)
        dsService.close()
    }
}

关闭流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
func (dsService *DataSyncService) close() {
    dsService.stopOnce.Do(func() {
        // 1. 注销消息分发客户端
        if dsService.dispClient != nil {
            dsService.dispClient.Deregister(dsService.vchannelName)
        }
        
        // 2. 关闭 FlowGraph
        if dsService.fg != nil {
            dsService.fg.Close()
        }
        
        // 3. 取消上下文
        dsService.cancelFn()
        
        // 4. 清理监控指标
        pChan := funcutil.ToPhysicalChannel(dsService.vchannelName)
        metrics.CleanupDataNodeCollectionMetrics(paramtable.GetNodeID(), 
            dsService.collectionID, pChan)
    })
}

创建方式

标准 DataNode 模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
func NewDataSyncService(initCtx context.Context, pipelineParams *util.PipelineParams, 
    info *datapb.ChannelWatchInfo, tickler *util.Tickler) (*DataSyncService, error) {
    
    // 1. 获取段信息
    unflushedSegmentInfos, err := pipelineParams.Broker.GetSegmentInfo(...)
    flushedSegmentInfos, err := pipelineParams.Broker.GetSegmentInfo(...)
    
    // 2. 初始化 MetaCache
    metaCache, err := getMetaCacheWithTickler(initCtx, pipelineParams, info, 
        tickler, unflushedSegmentInfos, flushedSegmentInfos)
    
    // 3. 创建消息输入
    input, err := createNewInputFromDispatcher(initCtx, pipelineParams.DispClient, ...)
    
    // 4. 创建服务
    ds, err := getServiceWithChannel(initCtx, pipelineParams, info, metaCache, 
        unflushedSegmentInfos, flushedSegmentInfos, input, nil, nil)
    
    return ds, nil
}

Streaming Node 模式

1
2
3
4
5
6
func NewStreamingNodeDataSyncService(...) (*DataSyncService, error) {
    // 使用简化的 MetaCache 初始化（不加载 Sealed 段的统计）
    metaCache, err := getMetaCacheForStreaming(...)
    
    return getServiceWithChannel(..., input, wbTaskObserverCallback, dropCallback)
}

组件依赖关系

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
DataSyncService
    │
    ├── FlowGraph
    │   ├── dmStreamNode (输入)
    │   ├── ddNode (过滤)
    │   ├── emNode (可选，嵌入)
    │   ├── writeNode (缓冲)
    │   └── ttNode (检查点)
    │
    ├── MetaCache
    │   ├── Segment 元数据
    │   ├── Bloom Filter
    │   └── BM25 统计
    │
    ├── Broker
    │   ├── 与 DataCoord 通信
    │   └── 元数据更新
    │
    ├── WriteBufferManager
    │   └── 数据缓冲管理
    │
    └── ChunkManager
        └── 对象存储访问

关键设计点

  1. 单通道单服务

每个 channel 对应一个独立的 DataSyncService，实现隔离和并发处理。

  1. 组件聚合

    DataSyncService 聚合了 FlowGraph、MetaCache、Broker 等核心组件，作为统一入口。

  2. 优雅关闭

    使用 sync.Once 确保关闭操作只执行一次，避免资源泄漏。

  3. 监控集成

    自动清理通道相关的监控指标，避免指标泄漏。

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>DataSyncService</code> 是 Milvus DataNode 中控制单个通道（Channel）数据同步的核心 Milvus FlowGraph 管理器（fgManagerImpl） https://szza.github.io/2025/08/09/Milvus/3_flush_pipeline_flowgraph_manager/ 2025-08-09T04:00:00.000Z 2026-01-06T13:10:43.368Z 概述

fgManagerImpl 是 Milvus DataNode 中管理多个数据同步服务（DataSyncService）的核心组件。它负责按 Channel 组织和管理 FlowGraph 实例，实现多通道并发数据处理。

架构设计

核心结构

1
2
3
4
5
type fgManagerImpl struct {
    ctx        context.Context
    cancelFunc context.CancelFunc
    flowgraphs *typeutil.ConcurrentMap[string, *DataSyncService]
}

关键字段说明：

  • ctx: 上下文，用于控制生命周期
  • cancelFunc: 取消函数，用于优雅关闭
  • flowgraphs: 线程安全的映射表，key 为通道名，value 为对应的 DataSyncService

接口定义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
type FlowgraphManager interface {
    AddFlowgraph(ds *DataSyncService)
    RemoveFlowgraph(channel string)
    ClearFlowgraphs()
    
    GetFlowgraphService(channel string) (*DataSyncService, bool)
    HasFlowgraph(channel string) bool
    HasFlowgraphWithOpID(channel string, opID int64) bool
    GetFlowgraphCount() int
    GetCollectionIDs() []int64
    
    GetChannelsJSON(collectionID int64) string
    GetSegmentsJSON(collectionID int64) string
    Close()
}

核心功能

1. FlowGraph 生命周期管理

添加 FlowGraph

1
2
3
4
func (fm *fgManagerImpl) AddFlowgraph(ds *DataSyncService) {
    fm.flowgraphs.Insert(ds.vchannelName, ds)
    metrics.DataNodeNumFlowGraphs.WithLabelValues(fmt.Sprint(paramtable.GetNodeID())).Inc()
}

功能：

  • 将 DataSyncService 注册到管理器
  • 更新监控指标

移除 FlowGraph

1
2
3
4
5
6
7
8
9
func (fm *fgManagerImpl) RemoveFlowgraph(channel string) {
    if fg, loaded := fm.flowgraphs.Get(channel); loaded {
        fg.close()
        fm.flowgraphs.Remove(channel)
        
        metrics.DataNodeNumFlowGraphs.WithLabelValues(fmt.Sprint(paramtable.GetNodeID())).Dec()
        util.GetRateCollector().RemoveFlowGraphChannel(channel)
    }
}

功能：

  • 关闭 DataSyncService
  • 从管理器中移除
  • 清理相关资源（指标、速率收集器）

清空所有 FlowGraph

1
2
3
4
5
6
7
8
9
10
func (fm *fgManagerImpl) ClearFlowgraphs() {
    log.Info("start drop all flowgraph resources in DataNode")
    fm.flowgraphs.Range(func(key string, value *DataSyncService) bool {
        value.GracefullyClose()
        fm.flowgraphs.GetAndRemove(key)
        
        log.Info("successfully dropped flowgraph", zap.String("vChannelName", key))
        return true
    })
}

功能：

  • 优雅关闭所有 FlowGraph
  • 清理所有资源

2. 查询功能

获取 FlowGraph 服务

1
2
3
func (fm *fgManagerImpl) GetFlowgraphService(channel string) (*DataSyncService, bool) {
    return fm.flowgraphs.Get(channel)
}

检查 FlowGraph 是否存在

1
2
3
4
func (fm *fgManagerImpl) HasFlowgraph(channel string) bool {
    _, exist := fm.flowgraphs.Get(channel)
    return exist
}

按操作 ID 检查

1
2
3
4
func (fm *fgManagerImpl) HasFlowgraphWithOpID(channel string, opID typeutil.UniqueID) bool {
    ds, exist := fm.flowgraphs.Get(channel)
    return exist && ds.opID == opID
}

用途： 确保 FlowGraph 的操作 ID 匹配，避免使用过期的 FlowGraph

3. 统计信息

获取集合 ID 列表

1
2
3
4
5
6
7
8
func (fm *fgManagerImpl) GetCollectionIDs() []int64 {
    collectionSet := typeutil.UniqueSet{}
    fm.flowgraphs.Range(func(key string, value *DataSyncService) bool {
        collectionSet.Insert(value.metacache.Collection())
        return true
    })
    return collectionSet.Collect()
}

获取通道 JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
func (fm *fgManagerImpl) GetChannelsJSON(collectionID int64) string {
    var channels []*metricsinfo.Channel
    fm.flowgraphs.Range(func(ch string, ds *DataSyncService) bool {
        if collectionID > 0 && ds.metacache.Collection() != collectionID {
            return true
        }
        latestTimeTick := ds.timetickSender.GetLatestTimestamp(ch)
        channels = append(channels, &metricsinfo.Channel{
            Name:           ch,
            WatchState:     ds.fg.Status(),
            LatestTimeTick: tsoutil.PhysicalTimeFormat(latestTimeTick),
            NodeID:         paramtable.GetNodeID(),
            CollectionID:   ds.metacache.Collection(),
        })
        return true
    })
    // ... 序列化为 JSON
}

返回信息：

  • 通道名称
  • FlowGraph 状态
  • 最新时间戳
  • 节点 ID
  • 集合 ID

获取段 JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
func (fm *fgManagerImpl) GetSegmentsJSON(collectionID int64) string {
    var segments []*metricsinfo.Segment
    fm.flowgraphs.Range(func(ch string, ds *DataSyncService) bool {
        if collectionID > 0 && ds.metacache.Collection() != collectionID {
            return true
        }
        
        meta := ds.metacache
        for _, segment := range meta.GetSegmentsBy() {
            segments = append(segments, &metricsinfo.Segment{
                SegmentID:      segment.SegmentID(),
                CollectionID:   meta.Collection(),
                PartitionID:    segment.PartitionID(),
                Channel:        ch,
                State:          segment.State().String(),
                Level:          segment.Level().String(),
                NodeID:         paramtable.GetNodeID(),
                NumOfRows:      segment.NumOfRows(),
                FlushedRows:    segment.FlushedRows(),
                SyncBufferRows: segment.BufferRows(),
                SyncingRows:    segment.SyncingRows(),
            })
        }
        return true
    })
    // ... 序列化为 JSON
}

设计特点

1. 线程安全

使用 typeutil.ConcurrentMap 实现线程安全的并发访问，支持多 goroutine 同时操作。

2. 资源管理

  • 通过 context.Context 统一管理生命周期
  • 提供优雅关闭机制（GracefullyClose）
  • 自动清理监控指标和资源

3. 监控集成

  • 集成 Prometheus 指标
  • 提供 JSON 格式的统计信息
  • 支持按集合过滤

使用场景

场景 1: 通道注册

当 DataCoord 分配新通道给 DataNode 时：

1
2
3
4
5
6
7
8
// 创建 DataSyncService
ds, err := NewDataSyncService(ctx, params, watchInfo, tickler)

// 注册到管理器
fgManager.AddFlowgraph(ds)

// 启动 FlowGraph
ds.Start()

场景 2: 通道释放

当通道需要迁移到其他节点时：

1
2
// 移除 FlowGraph
fgManager.RemoveFlowgraph(channelName)

场景 3: 节点关闭

当 DataNode 关闭时：

1
2
3
4
5
// 清空所有 FlowGraph
fgManager.ClearFlowgraphs()

// 关闭管理器
fgManager.Close()

与其他组件的关系

1
2
3
4
5
6
7
8
9
10
fgManagerImpl
    │
    ├── DataSyncService (按通道组织)
    │       │
    │       ├── FlowGraph (消息处理管道)
    │       ├── MetaCache (段元数据缓存)
    │       ├── WriteBufferManager (数据缓冲管理器)
    │       └── Broker (与 DataCoord 通信)
    │
    └── Metrics (监控指标)

相关文档

]]> <h2 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h2><p><code>fgManagerImpl</code> 是 Milvus DataNode 中管理多个数据同步服务（DataSyncServi Milvus DataNode Overview https://szza.github.io/2025/08/09/Milvus/2_flush_pipeline_overview/ 2025-08-09T03:00:00.000Z 2026-01-06T13:10:42.896Z 文档索引

本文档系列详细介绍了 Milvus DataNode 中数据刷新（Flush）管道的核心组件和机制。文档按组件和功能模块组织，便于深入理解系统设计。

📚 核心组件文档

  1. FlowGraph 管理器

    • fgManagerImpl 的设计与职责
    • FlowGraph 生命周期管理
    • 多通道并发管理

  2. DataSyncService

    • DataSyncService 架构
    • FlowGraph 组装流程
    • 节点初始化与启动

  3. DD Node（数据分发节点）

    • ddNode 的消息过滤机制
    • DDL 消息处理
    • 消息类型（MsgType）赋值流程

  4. WriteBuffer 管理器

    • bufferManager 的设计与实现
    • 内存管理与驱逐策略
    • 通道注册与生命周期

  5. WriteBuffer 实现

    • WriteBuffer 接口与基础实现
    • l0WriteBuffer 特殊设计
    • 段缓冲（segmentBuffer）管理

  6. SyncManager 与 SyncTask

    • SyncManager 异步同步机制
    • SyncTask 执行流程
    • 数据持久化与元数据更新

  7. TT Node（时间戳节点）

    • ttNode 的检查点更新机制
    • ChannelCheckpointUpdater 异步更新
    • 检查点失败处理

  8. Flush 与 Checkpoint 机制

    • Flush 操作的全链路影响
    • Checkpoint 更新流程
    • flushTs 的作用与重置条件
    • 数据一致性保障

🔗 组件关系图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
┌─────────────────────────────────────────────────────────────┐
│                    fgManagerImpl                            │
│         (管理多个 DataSyncService，按通道组织)                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                 DataSyncService                             │
│             (控制一个通道的 FlowGraph)                        │
└──────┬──────────────┬──────────────┬─────────────-──────────┘
       │              │              │
       ▼              ▼              ▼
┌──────────┐   ┌──────────┐   ┌──────────┐
│  ddNode  │──▶│writeNode │──▶│  ttNode  │
│(消息过滤)│    │(数据缓冲)  │   │(检查点更新)│
└────┬─────┘   └────┬─────┘   └─────┬─────┘
     │              │               │
     │              ▼               │
     │      ┌──────────────┐        │
     │      │WriteBufferMgr│        │
     │      └──────┬───────┘        │
     │             │                │
     │             ▼                │
     │      ┌──────────────┐        │
     │      │ WriteBuffer  │        │
     │      └──────┬───────┘        │
     │             │                │
     │             ▼                │
     │      ┌──────────────┐        │
     │      │ SyncManager  │        │
     │      └──────┬───────┘        │
     │             │                │
     │             ▼                │
     │      ┌──────────────┐        │
     │      │  SyncTask    │        │
     │      └──────────────┘        │
     │                              │
     └──────────────┬───────────────┘
                    │
                    ▼
          ┌──────────────────┐
          │ ChannelCheckpoint│
          │    Updater       │
          └──────────────────┘

📖 关键概念

消息流（Message Stream）

  • InsertMsg: 插入数据消息
  • DeleteMsg: 删除数据消息
  • DDL 消息: CreateSegment、Flush、DropCollection 等控制消息

数据缓冲（WriteBuffer）

  • Growing Segment: 正在接收数据的段
  • Sealed Segment: 已封装的段，准备刷新
  • L0 Segment: 流式模式下的删除数据专用段

同步机制（Sync）

  • 自动同步: 基于内存阈值、时间策略触发
  • 手动刷新: 通过 Flush 消息触发
  • SyncTask: 执行数据持久化的任务单元

检查点（Checkpoint）

  • Channel Checkpoint: 通道级别的数据消费位置
  • flushTs: 刷新目标时间戳
  • 检查点更新: 异步更新到 DataCoord

🎯 数据流程

1
2
3
4
5
消息流 → ddNode（过滤） → writeNode（缓冲） → WriteBuffer → SyncManager → SyncTask → 对象存储
                                                                    ↓
                                                              MetaCache 更新
                                                                    ↓
                                                              ttNode → CheckpointUpdater → DataCoord

📝 相关代码路径

  • FlowGraph 管理: internal/flushcommon/pipeline/flow_graph_manager.go
  • DataSyncService: internal/flushcommon/pipeline/data_sync_service.go
  • DD Node: internal/flushcommon/pipeline/flow_graph_dd_node.go
  • WriteBuffer 管理器: internal/flushcommon/writebuffer/manager.go
  • WriteBuffer 实现: internal/flushcommon/writebuffer/write_buffer.go
  • L0 WriteBuffer: internal/flushcommon/writebuffer/l0_write_buffer.go
  • SyncManager: internal/flushcommon/syncmgr/sync_manager.go
  • SyncTask: internal/flushcommon/syncmgr/task.go
  • TT Node: internal/flushcommon/pipeline/flow_graph_time_tick_node.go
  • CheckpointUpdater: internal/flushcommon/util/checkpoint_updater.go

下一步: 从 FlowGraph 管理器 开始深入了解各个组件。

]]> <h2 id="文档索引"><a href="#文档索引" class="headerlink" title="文档索引"></a>文档索引</h2><p>本文档系列详细介绍了 Milvus DataNode 中数据刷新（Flush）管道的核心组件和机制。文档按组件和功能模块组织