从十万行到千万行：HENGSHI SENSE 大数据量导出的工程边界

摘要：财务对账、业务归档和数据复核，常常需要把分析结果带出 BI 平台。HENGSHI SENSE 6.2 调整了图表明细数据的导出规则：从固定十万行改为遵循系统安全策略，最高支持千万行。理解这项变化，需要同时看导出对象、文件格式、资源消耗和权限控制。本文从这些环节说明怎样交付一份可核对、可继续使用的导出结果。

1 千万行对应什么能力

6.2 版本发布说明明确了这次优化的对象：图表明细数据。管理员配置的导出行数规则，决定用户实际能够导出的规模。把上限写成“千万行”，不意味着所有用户都默认获得这一额度，也不能据此推算一份文件的生成时间。

在“设置—安全管理—安全策略”中，管理员可以控制允许导出的用户和行数。当前手册允许将行数设在 1 到 10000000 之间，并列出了文件不超过 1000 万行、20 亿个单元格，以及每个 sheet 最多 100 万行的产品边界。超过单个 sheet 的部分分配到后续 sheet。这些限制约束不同层面：行数控制数据规模，单元格数量还与字段宽度有关。

实施时应分别核对产品支持范围、现场配置和目标账号的权限。查询返回了多少行、文件实际写入多少行，也要单独记录。达到可配置上限，只能说明规模允许，不能替代结果完整性和资源容量验证。

2 先选导出结果，再选导出方式

同一张报表可以承载不同交付目的。财务需要逐笔核对时，应确认导出的是目标范围内的明细；管理层需要阅读分析结论时，汇总表或带版式的文档可能更合适。先写清楚接收人要用文件完成什么工作，才能决定是否需要全量数据。

需求	优先核对的内容	验收重点
核对当前表格	本页范围、展开层级和所选导出选项	当前页记录与展示语义
批量处理数据	明细或聚合结果、全部数据范围	行数、字段类型和分 sheet 结果
汇报与阅读	PDF、PPT、PNG 等交付形式	分页、标题、图表和水印

“导出本页”和“导出全部”也有不同的格式能力。以表格为例，当前手册将单元格样式、明文、筛选条件说明、按展开层级和控件标题等选项限定在本页导出；全部导出不支持同一组选项。不能把一个格式选项是否可用，理解成业务过滤是否应生效：目标数据范围仍需按实际导出入口核对。需要批量加工数据时，应优先检查字段和值；需要复现阅读版式时，则应选择适合该目的的输出方式。

3 流式处理降低工作集，容量仍要实测

大数据量导出通常经历查询、读取结果、格式转换、文件写入和下载几个环节。若实现把全部结果留在内存后再生成文件，行数和字段数量增加都会放大内存压力。流式处理的工程思路，是让读取与写入分批推进，及时释放已经处理的数据。

设计这类流水线时，开发人员需要检查每一段是否仍在累积结果：数据库驱动怎样读取数据，转换阶段是否缓存整表，文件写入器是否保留全部单元格。只把文件端改成分批写入，无法消除其他阶段的全量缓冲。临时文件、长文本、样式和并发任务，也会影响资源峰值。

因此，评估导出不能只写“内存不随行数增长”。更有用的记录包括字段数量、数据类型、查询耗时、生成耗时、内存峰值和临时磁盘占用。将这些项目放到目标环境中测量，才能判断哪一种数据规模适合在线交付。这里讨论的是容量设计与验收方法，不代表某套部署的性能实测结论。

3.1 用一个小型示例拆开读取、写入和发布

下面用 Python 3.8 及以上版本的标准库演示 SQLite 到 CSV 的分批写入。它用于解释导出流水线，不是 HENGSHI 的内部实现、开放接口或 Excel 导出代码。示例只读取订单号和金额；数据库需预先存在 example_orders 表，其中 order_id 为唯一整数主键，order_date 为 YYYY-MM-DD 格式的文本，net_amount 为已确认精度的金额文本。

import csv
import os
import sqlite3
from contextlib import closing
from pathlib import Path
from uuid import uuid4


def export_csv(db_path, out_dir, start, end):
    out_dir = Path(out_dir)
    out_dir.mkdir(parents=True, exist_ok=True)
    final = out_dir / f"export-{uuid4().hex}.csv"
    partial = final.with_suffix(".csv.partial")
    rows = 0
    try:
        with closing(sqlite3.connect(db_path)) as conn:
            conn.execute("BEGIN")
            cursor = conn.execute(
                "SELECT order_id, net_amount FROM example_orders "
                "WHERE order_date >= ? AND order_date < ? "
                "ORDER BY order_id",
                (start, end),
            )
            with partial.open("x", newline="", encoding="utf-8-sig") as file:
                writer = csv.writer(file)
                writer.writerow(["order_id", "net_amount"])
                while batch := cursor.fetchmany(5000):
                    writer.writerows(batch)
                    rows += len(batch)
                file.flush()
                os.fsync(file.fileno())
            conn.rollback()  # 结束本次只读事务
        os.replace(partial, final)
        return {"path": str(final), "rows": rows}
    except Exception:
        partial.unlink(missing_ok=True)
        raise

在准备好示例表后，可以调用 export_csv(“demo.db”, “exports”, “2026-10-01”, “2026-11-01”)。左闭右开的日期范围避免把下月第一天混入本月。参数绑定将取值与 SQL 分开；固定的主键排序便于复核顺序；显式只读事务使这次 SQLite 查询在一个一致的读取视图中完成。其他数据库的事务隔离和游标行为，需要按相应驱动单独确认。

循环每次读取最多 5000 行，写完才取下一批，因此应用不必先建立一份完整结果列表。5000 是演示值，不能视为最佳参数。单行越宽，同样的行数占用越大；数据库执行排序、驱动缓存、文件格式转换仍可能消耗大量内存或磁盘。读写链路中任意一段重新累积全表，都会削弱分批处理的效果。

临时文件与最终文件放在同一目录，写入完成、文件关闭后再执行 os.replace，避免把尚未写完的文件当成可下载结果。异常处理会清理本进程留下的临时文件；进程被强制终止时，仍需额外的过期清理机制。这个例子没有实现断点续传、任务调度或下载鉴权，也没有保留电子表格的字段类型。真实交付还需处理长编码、空值、文本被误识别为公式等情况。

3.2 容量评估要看字段宽度和并发

同为 100 万行，20 个短字段和 200 个含长文本的字段，生成代价可能相差很大。初步估算文件体积时，可以用代表性样本测出每行编码后的平均字节数，再乘以目标行数；压缩、样式、共享字符串以及临时文件会改变实际磁盘占用，因此估算只能帮助选择测试规模。

并发也应单独验证。三个任务同时运行时，数据库连接、读取快照、文件写入带宽和临时磁盘可能相互争用。建议先测一个任务的查询与生成耗时，再逐步增加并发，记录峰值和失败环节。若接收方只需汇总结果，减少字段或改用聚合交付，通常比直接提高导出额度更有实际价值。

4 异步执行与失败恢复分别验证

异步处理可以把耗时工作移出一次长时间等待的请求。要让这项设计可靠，工程团队还需明确任务由谁持有、怎样取得结果、失败后如何处理，以及临时文件由谁清理。浏览器收到“已提交”，与后台完成文件生成，是两个不同的状态。

对 HENGSHI SENSE 的具体导出入口，应按现场版本验证其完成与下载行为。不能仅因为存在异步请求，就承诺关闭页面、退出登录或服务重启后一定能继续任务；系统“任务管理”中的更新、订阅等执行计划，也不等同于所有交互式导出的统一队列。

遇到 Gateway Time-out 时，排障人员先保存导出时间、入口和报错，再沿代理、负载均衡、WAF 与服务端检查实际超时位置。外层请求被中断，不足以说明数据库慢或文件生成失败；只调大一个超时值，也不能解决所有链路问题。

4.1 按失败阶段决定怎样恢复

排障时可以将一次导出分成下列阶段。表中的阶段是分析问题的方法，不代表产品对外提供同名任务状态。先找最后一个已确认完成的环节，再决定是否重跑查询，能够减少无效重试。

失败阶段	先保留的证据	恢复时检查什么
查询或取数	原始错误、查询条件、数据源与发生时间	连接和权限是否正常；源数据是否变化；是否需要重新固定比对批次
文件生成	已读取行数、临时文件大小、磁盘与进程日志	磁盘是否足够；字段转换是否失败；不完整产物是否已隔离
结果发布	文件是否完整生成、结果登记或存储错误	可否复用已生成文件；完成标记是否与实际产物一致
下载传输	响应状态、代理日志、客户端下载错误	结果是否仍有效；允许重新下载还是必须重新生成

超时后不要连续点击导出。先确认前一请求是否仍在执行，避免多个相同任务叠加。对于支持重试的实际入口，还要检查重试会继续原任务还是重新取数；若源数据已经变化，即使第二次成功，结果也未必能与第一次按同一口径比较。

5 把授权与数据口径带到文件交付中

查看和导出是不同的授权动作。业务人员可以被允许阅读看板，同时受到导出用户范围或导出行数限制。管理员应使用实际业务角色，核对应用的数据权限模式、行列规则、脱敏要求和导出策略；界面上的字段隐藏，也不能代替列级权限检查。

导出前还要固定业务范围：期间、组织、筛选条件、指标定义，以及数据最近一次成功更新的时间。对账文件生成期间若源端持续变化，团队需要约定比对时点，必要时采用已经确认的数据批次。否则，即使两次查询都成功，也可能因取数时间不同而出现差异。

交付时建议附上范围说明、实际行数和关键汇总值。对订单号、长编码、日期、空值及金额精度做抽样复核，避免接收人在电子表格软件中二次打开时改变数据含义。文件能打开，是检查的起点。

6 用一次月结演练检查整条链路

以下为示例场景，不是产品性能测试结果。某财务团队计划核对 230 万行订单明细。负责人先确定月结范围和字段清单，再确认目标账号获准导出这一规模。按手册列出的单 sheet 上限，结果需要跨多个 sheet；验收人员应汇总各 sheet 的记录数，并检查每个分界处的订单是否重复或遗漏。

团队随后用相同期间和筛选条件核对金额总计，抽查退款、空值、长订单号和跨日记录，再记录查询与文件生成的耗时。若导出失败，应先确认失败环节再重试，避免重复提交继续占用资源。完成数据核验后，再按约定的接收人和渠道分发文件。

6.1 将验收结论留下来

验收记录可以采用下面的 JSON 结构。它是虚构的人工交接样例，不是平台 API 返回值，也没有性能实测含义。各 sheet 的行数仅统计数据记录，不计表头；实际分配仍应以导出文件为准。

{
  "example_only": true,
  "period": {
    "start_inclusive": "2026-10-01",
    "end_exclusive": "2026-11-01"
  },
  "data_batch": "示例：财务确认的月结批次",
  "expected_data_rows": 2300000,
  "actual_data_rows": 2300000,
  "sheet_data_rows": [
    1000000,
    1000000,
    300000
  ],
  "amount_reconciliation": "同批次、同筛选条件下汇总一致",
  "boundary_samples": "已检查 sheet 分界前后订单及长编码",
  "delivery_scope": "获准接收的财务对账人员"
}

实际使用时，应补齐具体数据集、筛选条件、文件名称、核对人和测量结果。记录行数能发现截断，记录金额汇总能发现部分取值差异，分界抽查能发现重复或遗漏；这几种检查互相补充，不能只凭其中一项就宣布文件完整。

HENGSHI SENSE 将图表明细导出与安全策略衔接后，企业可以按业务需要配置交付规模。数据团队则需要把配置上限落实为一套可复验的操作：选对对象、固定口径、验证容量，并检查文件内容。这样，导出的数据才能继续用于月结、归档和后续分析。