06-EFT.WP.Core.DataSpec v1.0 | 第5章 序列化与存储布局

目录 ／ 文档-技术白皮书（V5.05） ／ 06-EFT.WP.Core.DataSpec v1.0

第5章 序列化与存储布局

I. 范围与对象

• 规定 D 在不同 fmt ∈ {"jsonl","csv","parquet","nc","tfrecord"} 下的可移植、可校验、可追溯的落盘语义与布局约束，覆盖分块、压缩、对齐、文件命名与分区目录结构。
• 与《Core.Metrology》《Core.Equations》《Core.Parameters》一致，任何参与方程的字段必须携带 unit(field_i) 与 dim(field_i)，并在序列化时保持无损（除非显式量化并建立误差上界）。
• 提供 Mx-3（布局选择与落盘流程），绑定 serialize/deserialize/stream_records 与 export_manifest。

II. 存储语义与端到端约束

• 可读性：deserialize( serialize(D) ) ≡ canon(D)（恒等，若未启用量化）。
• 可验证性：compute_checksum(blob) == manifest.files[i].hash_sha256。
• 可定位性：pk 与二级索引 idx_k 可由文件路径、分区键与行组元数据恢复。

III. 公设（P65-*)

• P65-1 行列分离公设：列式优先用于投影率低的分析负载；行式优先用于高 QPS 小记录写入。
• P65-2 对齐公设：块、行组与索引段应对齐至 align(bytes, 4 KiB) 或其倍数，以稳定 I/O。
• P65-3 指纹公设：所有发布文件必须记录 hash_sha256(blob) 与字节长度，并纳入 manifest.
• P65-4 精度公设：若启用量化，必须声明 q 并给出误差上界 |x - x_q| ≤ q/2。

IV. 格式对照与适用域

1. jsonl（逐行 JSON）
   • 优点：可流式、可读性高；缺点：冗余度高、类型弱。
   • 适用：日志、调试、轻量互操作；必须携带 schema_version 与 unit(dim) 扩展域。
2. csv
   • 优点：工具普适；缺点：类型/缺失表达不可靠。
   • 适用：与外部系统交换的最小交集；要求提供伴随 S 与缺失标记 m。
3. parquet（列式）
   • 优点：列裁剪与压缩友好，行组索引；适用宽表与分析负载。
   • 要求：声明 row_group_size_bytes、compress、dict_encoding、stats_enabled。
4. nc（NetCDF，科学栅格/张量）
   • 优点：坐标系/维度元数据丰富；适用规则栅格与时间序列张量。
   • 要求：声明 CRS、维度顺序、缺失掩码 m 与 _FillValue。
5. tfrecord（顺序二进制记录）
   • 优点：顺序写高吞吐；缺点：随机列裁剪弱。
   • 适用：训练样本流与在线推理样本池；需提供 index 与样本统计。

V. 类型到存储映射（最小规则）

• 数值：float64 为默认；若降至 float32，需记录 precision="float32" 与（如启用）量化参数 q。
• 时间：ts 编码为 int64 epoch_us（UTC）；字段名 ts 必与时区 UTC 一致。
• 空间：lon/lat/alt 使用 float64；CRS 必填。
• 字符串：UTF-8；enum 建议字典编码。
• 张量：在 nc 中声明维度名；在 parquet 使用 list<primitive> 并记录 shape 元数据。

VI. 压缩与编码策略

1. 压缩：compress ∈ {"zstd","gzip","none"}；记录 compress_level。
2. 编码：字典编码 dict_encoding ∈ {0,1}；游程编码可用于布尔与低基数字段。
3. 量化（可选）：
   • 定义：x_q = round( x / q ) * q。
   • 误差上界：|x - x_q| ≤ q/2；在 manifest.quantization 中记录 { fields, q, bound="q/2" }。
4. 缺失：统一 m ∈ {0,1}；在 parquet/nc 中同步 _FillValue 与 m 的一致性检查。

VII. 分块、行组与对齐

1. 目标：在 I/O 与压缩之间平衡，令 row_group_size_bytes ≈ target_block。
2. 建议：target_block ∈ [64 MiB, 256 MiB]；row_group_size_bytes = align( target_block, 4 KiB )。
3. 读取预算：
   • 投影列集 C_proj，投影率 alpha = |C_proj| / |Fields_total|。
   • 期望扫描量 V_scan = N * sum( size(field_i) for field_i ∈ C_proj ) / ratio_compress。
   • 若 alpha ≤ 0.25 且 V_scan 明显低于行式扫描，选择列式；否则评估行式或混合布局。

VIII. 文件命名与目录布局

1. URI 模板：scheme://bucket/prefix/dataset=DS/schema=S/version=vX.Y.Z/partition_keys/.../part-00000-of-000K.ext。
2. 分区键示例：date=YYYY-MM-DD/sid=.../pid=...。
3. 要求：
   • part-{i}-of-{K} 连续编号且零填充；
   • 每个 part 在 manifest.files[*] 中记录 { path, bytes, hash_sha256, row_count, row_group_count }；
   • 分区目录必须可从路径反推分区键字典。

IX. 时间与路径数据的布局

1. 时间序列（均匀采样）：每 part 覆盖固定窗口 Delta_t * M，并在元数据中记录 { ts_start, ts_end, fs }。
2. 时间序列（非均匀采样）：记录 non_decreasing(ts) 与 count_gap 统计。
3. 路径 gamma(ell)：
   • 每个 part 仅含单一 pid 或记录 { pid_set, ell_min, ell_max }；
   • 行组粒度优先对齐 ell 连续区间；
   • 对 T_arr 数据集，必须并存两口径结果与 delta_form 字段，并在 manifest.arrival 标注容差 tol_Tarr。

X. 一致性、校验与指纹

1. 写后校验：
   • hash_sha256(blob) 与 bytes 入 manifest；
   • 若 fmt="parquet"，启用列统计并在 manifest.stats 中缓存 { min,max,null_count }。
2. 端到端一致：deserialize( serialize(D) ) == canon(D)（启用量化时替换为 ≈，并断言量化上界）。
3. 追溯：attach_provenance(ds, Trace) 与 signature 一并落盘。

XI. 流式 I/O 与增量写入

1. 流式校验：结合 stream_records(ds, batch) 与记录级契约，滚动计算质量指标。
2. 追加写：
   • 仅允许在新 part；禁止改写已发布 part（除非 bump schema_version 并新路径发布）。
   • freeze_release(ds, tag) 之后进入只读；任何增量需新 tag。

XII. 精度与量化契约

1. 若字段 x 量化为步长 q：
   • 存储：x_q 与 q；
   • 契约：|x - x_q| ≤ q/2（若仅存 x_q，则上界解释为相对于理想实值的最大偏差）。
2. 对参与方程的字段（例如 n_eff(x,t)）：默认禁止量化；若确需量化，必须证明对 T_arr 的相对误差界：
   |ΔT_arr| ≤ ( ∫_gamma |Δn_eff| / c_ref d ell )，并将该上界入 manifest.arrival.error_bound。

XIII. 端到端流程（Mx-3 布局选择与落盘）

• 采集与标准化：canon(D)，绑定 S、unit(dim)、CRS。
• 负载剖面：估计 alpha 与 V_scan，选择 fmt 与 target_block。
• 落盘参数：确定 row_group_size_bytes、compress、dict_encoding、quantization。
• 写入：serialize(D, fmt, compress)，分区与命名遵循本章模板。
• 校验：写后 hash_sha256、stats、contract 重跑关键断言（时间/路径/唯一性）。
• 发布：export_manifest、attach_provenance、freeze_release(ds, tag)。

XIV. 接口与实现绑定（与 I60 对齐）

• serialize(ds:any, fmt:str="parquet", compress:str|None=None) -> bytes：必须接受 parquet/jsonl/csv/nc/tfrecord 并产生与本章一致的元数据。
• deserialize(blob:bytes, fmt:str) -> any：恢复 canon(D) 与字段单位、量纲。
• stream_records(ds:any, batch:int=10000) -> iterator：用于流式契约与增量写。
• export_manifest(ds:any) -> dict：含文件列表、指纹、统计与布局参数（见 XV）。

XV. manifest 最小存储布局清单

• format、schema_version、fields（含 unit/dim/nullable）
• layout：{ row_group_size_bytes, compress, dict_encoding, stats_enabled }
• partitioning：键集合与值域说明
• files[]：{ path, bytes, hash_sha256, row_count, row_group_count, ts_start, ts_end, pid_set, ell_min, ell_max }
• quantization（如有）：{ fields, q, error_bound="q/2" }
• arrival（如有）：{ formulation, tol_Tarr, delta_form_field, error_bound }
• provenance 与 signature

XVI. 跨卷绑定与 T_arr 用例要点

1. T_arr 专用数据集需同时持有两口径：
   • T_arr(factored) = ( 1 / c_ref ) * ( ∫_gamma n_eff d ell )；
   • T_arr(general) = ( ∫_gamma ( n_eff / c_ref ) d ell )；
   • delta_form = | T_arr(factored) - T_arr(general) | 并契约化 delta_form ≤ tol_Tarr。
2. 布局：按 pid/ell 分区，行组对齐路径段；在 manifest 中记录 L_gamma = ( ∫_gamma 1 d ell ) 与采样策略。

XVII. 运行建议与基线

• 宽表分析：fmt="parquet"，row_group_size_bytes ≈ 128 MiB，启用列统计与字典编码。
• 顺序样本：fmt="tfrecord"，外置索引；或 nc 用于规则栅格。
• 交换与调试：jsonl（小规模）、csv（与外部系统互操作），务必交付 S 与 manifest。