Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion configs/milvus.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -621,7 +621,8 @@ queryNode:
scalarIndex: disable
vectorField: disable # cache warmup for vector field raw data is by default disabled.
vectorIndex: disable
lazyManifestReaderEnabled: false # Defer the Storage V3 projected ChunkReader/translator/cache tree for warmup=disable fields without load-time side effects.
lazyManifestReaderEnabled: false # Defer Storage V3 manifest readers for warmup=disable fields until first access.
lazyJsonStatsEnabled: true # Defer eligible Storage V3 JSON stats metadata until first access.
# If evictionEnabled is true, a background thread will run every evictionIntervalMs to determine if an
# eviction is necessary and the amount of data to evict from memory/disk.
# - If the current memory/disk usage exceeds the high watermark, an eviction will be triggered to evict data from memory/disk
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Storage V3 Manifest Task 延迟物化设计
# Storage V3 Manifest Task 与 JSON Stats 延迟物化设计

## 1. 目标

Expand All @@ -12,13 +12,17 @@
- `ChunkedColumnGroup`;
- 真实 `ProxyChunkColumn`。

独立的 `lazyJsonStatsEnabled` 开关允许将 JSON key stats 顶层对象的远端 `meta.json`、
Parquet metadata、projected reader 和 cache tree 初始化延迟到首个可使用 stats 的表达式。
Ready 阶段只发布绑定当前 generation 的 `LazyJsonStats` facade。

设计边界如下:

- 保持 `SegmentLoadInfo` 已有 Task、projection 和 eager/lazy fallback 粒度;
- 不因开启本功能而按字段重新拆分 Column Group;
- 支持普通字段、RowID、Timestamp、INT64 PK 和 VARCHAR PK;
- Ready 阶段保持 manifest Task 延迟,查询期需要数据时允许正常物化;
- 正确性优先,不增加 JSON、Tantivy、PK 或 MVCC 专用的“保冷”执行路径;
- 正确性优先,不增加 Tantivy、PK 或 MVCC 专用的“保冷”执行路径;
- 保持 Storage V1/V2、external collection 和配置关闭时的行为不变。

## 2. 生效条件
Expand All @@ -36,6 +40,11 @@ Task 仅在以下条件同时满足时进入延迟物化:
Task,避免同一 generation 内出现部分 eager、部分 lazy 的混合状态。已发布 Task 不随
动态配置变化而改变。

JSON stats 不依赖 `lazyManifestReaderEnabled`。它在
`queryNode.segcore.tieredStorage.lazyJsonStatsEnabled=true`、上述第 2 至第 4 个条件成立,
且 effective scalar-field warmup policy 为 `disable` 时延迟物化。`sync`、`async`、
JSON stats 配置关闭以及非 Storage V3 segment 继续在 Load 阶段初始化,保持既有行为。

## 3. Task 不变量

Lazy 开关不参与 Task 分组。每个 Task 保持 `SegmentLoadInfo` 已确定的字段集合和
Expand All @@ -55,15 +64,21 @@ Ready 阶段的对象关系如下:
```text
RuntimeResourceState
├── generation runtime Reader
└── fields
└── LazyManifestProxyColumn
└── Task-scoped LazyManifestColumnGroup
└── ManifestColumnGroupBuildContext
├── generation Reader 强引用
├── 原始 column-group index
├── Task projection
├── FieldMeta 快照
└── mmap、priority、cache key 等 Translator 输入
├── fields
│ └── LazyManifestProxyColumn
│ └── Task-scoped LazyManifestColumnGroup
│ └── ManifestColumnGroupBuildContext
│ ├── generation Reader 强引用
│ ├── 原始 column-group index
│ ├── Task projection
│ ├── FieldMeta 快照
│ └── mmap、priority、cache key 等 Translator 输入
└── json_stats
└── LazyJsonStats
└── JsonStatsBuildContext
├── generation FileManagerContext
├── files、base path、mmap 与 priority
└── generation insert channel 与 resolved warmup policy
```

每个 Load/Reopen generation 创建并发布自己的 runtime Reader。Lazy Task 直接强引用
Expand Down Expand Up @@ -101,6 +116,9 @@ Materialize(op_ctx)
- 失败时不发布半成品 group;
- 成功后所有 facade 复用同一 group。

`LazyJsonStats` 使用相同的 single-flight、独立取消和失败重试语义。成功前不发布
`JsonKeyStats`;原有 `internal_json_stats_latency_load` 只记录真正发生的物化耗时。

## 6. Facade 接口语义

`LazyManifestProxyColumn` 保存共享 Task、FieldId、FieldMeta 和行数。
Expand All @@ -125,6 +143,9 @@ Materialize(op_ctx)
`CellsLoaded()` 仅表示对应 cache cell 是否已经加载。真实 group 已创建但 cell 尚未加载
时仍可返回 false,因此它可以作为非物化状态探针。

JSON stats facade 的存在性检查只在表达式已满足开关、非空 path 且 path 不含数组下标后
触发物化。首个符合条件的表达式加载 stats,之后同 generation 的查询复用同一实例。

## 7. Lazy 资格

Task 内任一字段具有以下 Load 阶段副作用时,整个 Task 使用原 eager 路径:
Expand Down Expand Up @@ -187,6 +208,7 @@ Column Group identity 包含:

- 旧 snapshot 可以继续读取旧 generation;
- 新 facade 不捕获 committer、可变 runtime 或当前 PublishedState;
- JSON stats facade 捕获本 generation 的 FileManagerContext、insert channel 与配置;
- Reopen 失败不发布 staged state;
- 同一 generation 内全部新 Task 使用同一个配置快照。

Expand All @@ -210,19 +232,20 @@ queryNode:
segcore:
tieredStorage:
lazyManifestReaderEnabled: false
lazyJsonStatsEnabled: true
```

配置默认关闭并支持动态刷新。Go paramtable 通过 C bridge 更新 `SegcoreConfig` 中的原子
布尔值
Manifest reader 延迟加载默认关闭,JSON stats 延迟加载默认开启;两个开关相互独立且均
支持动态刷新。Go paramtable 通过 C bridge 更新 `SegcoreConfig` 中各自的原子布尔值

## 12. 兼容性

- 配置关闭时走原 eager 路径;
- 对应配置关闭时各自走原 eager 路径;
- Storage V1/V2 和无 ManifestPath segment 不进入本路径;
- external collection 保持既有加载方式;
- 不修改 milvus-storage API;
- 不改变既有 Task/projection 划分;
- 不为 JSON、Tantivy 或其他索引增加专用的“不物化”执行分支
- JSON stats 仅延迟顶层初始化,查询执行逻辑与 raw-data fallback 选择不变
- 查询链路需要 chunk 布局、大小或原始数据时正常物化。

## 13. 验证
Expand All @@ -233,6 +256,8 @@ queryNode:
- Ready 阶段 facade 与未缓存的 PK/Timestamp slot;
- 多字段 Task 的 sibling 共享和并发 single-flight;
- cancellation 与非取消失败后的重试;
- JSON stats 的 Ready 冷态、并发首访 single-flight、取消和失败重试;
- JSON stats 的 `disable`、`sync`、配置关闭与非 Storage V3 边界;
- `DataByteSize()`、布局接口和真实读取的按需物化;
- RowID、INT64/VARCHAR PK、Timestamp 与 commit timestamp;
- Reopen generation 重绑和 schema-only drop;
Expand Down
8 changes: 4 additions & 4 deletions internal/core/src/exec/expression/Expr.h
Original file line number Diff line number Diff line change
Expand Up @@ -2745,12 +2745,12 @@ class SegmentExpr : public Expr {
return false;
}

// Check whether this expression can use JsonStats without pinning.
// All conditions are available before execution path determination.
// Check cheap expression constraints before the presence check, which may
// materialize lazy JsonStats on the first eligible query.
bool
CanUseJsonStatsAtInit() const {
return plan_options_.expr_use_json_stats && HasJsonStats(field_id_) &&
!nested_path_.empty() && !PathContainsInteger(nested_path_);
return plan_options_.expr_use_json_stats && !nested_path_.empty() &&
!PathContainsInteger(nested_path_) && HasJsonStats(field_id_);
}

virtual bool
Expand Down
Loading
Loading