Metabase 结果导出完全指南：CSV、XLSX、JSON、PDF 与 PNG 的实战与源码解析

Metabase 结果导出完全指南：CSV、XLSX、JSON、PDF 与 PNG 的实战与源码解析

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 作为开源商业智能工具，允许用户将问题（Question）和仪表板（Dashboard）的查询结果导出为 CSV、XLSX、JSON、PDF 与 PNG 文件。本文基于当前仓库docs/questions/exporting-results.md文档，结合src/metabase/query_processor相关源码，系统讲解各类导出方式的操作路径、格式化行为、行数限制与权限控制，帮助读者在自托管 Metabase 中准确完成结果分享与数据交付。

阅读本文后，你将掌握：从问题页与仪表板卡片下载各类格式文件的具体操作；透视表（Pivot Table）导出时"透视/非透视"两种结果的区别；行数与单元格字符限制的底层实现与调整方法；以及下载结果权限（Download results）在后端权限模型中的校验机制。

问题（Question）结果导出

导出单个问题结果是最常见的场景。打开任意问题后，点击问题右下角的Download（下载）按钮即可触发导出：

Metabase 支持将问题结果导出为以下四种格式：

格式化（Formatted）与未格式化（Unformatted）导出

点击下载格式时，Metabase 会提供两种导出模式：

• Formatted（格式化）：应用你在 Metabase 中对列所做的所有格式化设置，例如浮点数的保留小数位数、日期时间显示格式、货币符号等，导出的文件与页面上的表格展示保持一致。
• Unformatted（未格式化）：导出问题的原始结果，不应用任何列格式化。例如你在表格中把一个浮点数列格式化为只显示两位小数，未格式化导出会把原始结果中的全部小数位原样带出。

从源码看，格式化行为由 src/metabase/query_processor/streaming/csv.clj 中基于formatter/create-formatter创建的列格式化器驱动，format-rows?标记决定是否套用格式化；在 XLSX 导出路径中，未格式化导出会移除数字格式样式，让 Excel 使用 General 格式以保留完整小数精度（见 src/metabase/query_processor/streaming/xlsx.clj 中compute-typed-cell-styles对format-rows?的处理）。

若界面上看不到导出选项，通常意味着当前用户缺少下载结果权限，详见下文权限章节。

透视表（Pivot Table）的导出行为

默认情况下，Metabase 会导出**已透视（Pivoted）的结果，同时提供导出未透视（Unpivoted）**结果的选项。

• Pivot table in Metabase（Metabase 中的透视表）：

• Exported unpivoted results（导出的未透视结果）：

• Exported pivoted results（导出的透视结果）：

为什么导出为扁平表而非原生 Excel 透视表

需要特别说明：Metabase 导出的"透视结果"在 Excel 中是以扁平表形式展示的，并非 Excel 原生 PivotTable。原因是 Excel 并不支持 Metabase 的全部聚合函数——若强行把 Metabase 透视表还原为 Excel 原生透视表，在缺少这些函数支持的情况下可能导致数据正确性问题，违背了分析数据的初衷。

如果你确实需要 Excel 原生透视表，正确做法是：先撤销问题中的所有汇总（Summarization）与分组（Grouping），导出原始、未聚合的行数据，再在 Excel 中自行创建透视表。此时有一个注意点：Metabase 的某些汇总操作包含隐式连接（implicit joins），撤销汇总后你可能需要手动关联表，才能包含全部所需列。

源码层面，透视表导出由 src/metabase/query_processor/streaming/csv.clj 处理：透视导出时结果行先被暂存，在finish!阶段由pivot.postprocess/build-pivot-output构建透视输出；同时存在enable-pivoted-exports设置（定义于 src/metabase/query_processor/settings.clj，默认true，可配置是否启用"透视导出与透视订阅"）。XLSX 的透视导出还会针对"货币列内联符号"等场景做专门处理，见 src/metabase/query_processor/streaming/xlsx.clj。

导出限制（Export Limits）

行数限制（Row Limit）

默认情况下，Metabase 最多导出结果的前1,048,575 行。这一数值并非随意设定——它对应 Excel 单个工作表的行数上限，由于还包含一行表头，因此比 Excel 上限少一行。该常量定义于 src/metabase/query_processor/settings.clj 中的absolute-max-results，源码注释明确引用 Excel 规格说明。

针对不同格式有两条规则：

• CSV 导出：可以通过环境变量MB_DOWNLOAD_ROW_LIMIT提高该限制。注意提高限制可能影响 Metabase 的性能（内存与带宽开销随行数增长）。
• XLSX 导出：始终受限于 Excel 的 1,048,575 行上限（外加一行表头），即使MB_DOWNLOAD_ROW_LIMIT设置得更高也无效。

从实现看，download-row-limit的 getter 会保证返回值不低于 1,048,575（即absolute-max-results），而 src/metabase/query_processor/middleware/limit.clj 中的determine-query-max-rows会区分查询上下文：#{:csv-download :json-download :xlsx-download :embedded-csv-download :embedded-json-download :embedded-xlsx-download :public-csv-download :public-json-download :public-xlsx-download}视为下载场景并应用download-row-limit；#{:dashboard-subscription :pulse :notification}视为订阅/通知场景并应用attachment-row-limit。对于:xlsx-download系列上下文，还会额外与absolute-max-results取最小值，从代码层面强制 XLSX 不可突破 Excel 上限。相关测试位于 test/metabase/query_processor/middleware/limit_test.clj（可在仓库中检索验证）。

Excel 导出中的单元格字符数限制

导出为.xlsx时，Metabase 会将每个单元格的字符数限制为 32,767，这是 Excel 自身强制的单元格字符上限。如果单个单元格内容超过该长度，Metabase 会截断内容以适配该限制。

从文档卡片（Document）中的图表导出结果

Metabase 的文档（Documents）功能允许你在文档中嵌入图表，这些图表同样支持结果导出。操作步骤：

1. 将鼠标悬停在文档中的图表上；
2. 点击图表右上角的三个点菜单（...）；
3. 选择Download results（下载结果）；
4. 选择格式：.csv、.xlsx或.json。

与问题导出一致，这里也支持格式化/未格式化两种模式：点击下载格式时，Mac 上按住Option键、Windows 上按住Alt键即可导出未格式化结果。若看不到Download results选项，同样是因为缺少下载结果权限。

通过公开链接（Public Link）导出数据

你可以为问题创建公开链接，让没有 Metabase 账号的人通过该链接直接下载指定格式（CSV、XLSX、JSON）的数据；公开链接也支持导出原始、未格式化的问题结果。这适合面向外部合作伙伴或内部非账号用户提供一次性数据交付。

实现层面，公开链接导出走public-*-download系列查询上下文，见 src/metabase/public_sharing_rest/api.clj 与 src/metabase/embedding_rest/api/common.clj（公开链接与嵌入导出的后端入口），其行数限制同样受download-row-limit约束。

通过告警（Alerts）导出问题数据

Metabase 的告警（Alerts）功能可以在问题结果满足条件时发送通知，同时支持把数据作为附件一同输出。对于"定期把查询结果发给指定邮箱"这类场景，告警附件与仪表板订阅是两条互补的自动化导出路径。告警/订阅附件的行数上限对应源码中的attachment-row-limit设置（src/metabase/query_processor/settings.clj）。

仪表板（Dashboard）结果导出

仪表板支持三种导出方式：导出为 PDF、导出单张卡片结果、通过订阅定期导出。它们的入口如下：

• 导出仪表板为 PDF
• 导出仪表板卡片结果
• 通过仪表板订阅导出

导出仪表板为 PDF

点击仪表板右上角的Share（分享）按钮，然后选择Export as PDF（导出为 PDF）。对于包含多个标签页（Tabs）的仪表板，可选择Export tab as PDF仅导出当前标签页。

需要明确：PDF 中只包含仪表板上当前可见的图表截图，不含表格的完整数据行。若希望按计划自动收到仪表板 PDF，可以为仪表板订阅附加 PDF。

导出仪表板卡片结果

要导出仪表板中某一张卡片的查询结果：将鼠标悬停在该卡片上，点击三个点菜单（...），选择Download results：

随后可选择格式：.csv、.xlsx、.json，若卡片是图表还可选.png。同样地，Mac 按住Option、Windows 按住Alt再点击格式即可导出原始未格式化结果。若看不到该选项，说明缺少下载结果权限。

通过仪表板订阅导出结果

通过仪表板订阅（Dashboard Subscriptions），你可以按计划（如每日、每周）定期把仪表板上所有问题的查询结果作为附件发送给订阅者，也可以附加整个仪表板的 PDF。这是"定时数据报表"最常见的落地方式，适合把日报、周报自动投递到邮箱。

移除导出内容中的 Metabase 品牌标识

默认情况下，所有数据导出（PDF、PNG、告警与订阅邮件等）都会带有 Metabase 品牌标识，例如"Made with Metabase"徽标：

如需在导出内容中移除 Metabase 徽标与品牌信息，需要订阅 Metabase 的 Pro 或 Enterprise 付费计划。这是功能授权层面的差异，与后端导出管线无关。

下载结果权限（Download results permissions）

前文多次提到"看不到导出选项可能是缺少下载结果权限"。在 Metabase 的权限模型中，下载权限属于数据权限（Data permissions）的一部分，通过:perms/download-results键进行控制。

从 src/metabase/permissions/schema.clj 可以看到，下载结果权限的取值集合为：

权限粒度可到表级（{:model :model/Table}），也可在数据库级授予。后端在 src/metabase/permissions/models/data_permissions.clj 中会把表级的下载权限值合并、并取最严格的级别作为用户的最终下载级别；其计算与full-database-permission-for-user共享缓存（见该文件 L753-L756 附近的注释）。关于如何为各组配置下载权限，可参考数据权限文档。

总结与延伸阅读

Metabase 的结果导出能力覆盖了"手动下载、公开分享、定时投递"三类典型需求：

• 手动导出：问题/卡片右下角 Download，或文档图表的三点菜单，支持 CSV、XLSX、JSON、PNG（图表）；
• 公开分享：通过公开链接让无账号用户直接下载指定格式数据；
• 定时投递：告警附件与仪表板订阅，把数据（或仪表板 PDF）按计划发送到邮箱。

核心限制与可调项集中在行数上限（MB_DOWNLOAD_ROW_LIMIT、attachment-row-limit）、XLSX 的 Excel 规格硬上限（1,048,575 行与每单元格 32,767 字符）以及按表/库配置的下载权限。相关实现可进一步阅读：

• 告警：基于条件的自动数据通知
• 仪表板订阅：定时导出全部卡片数据并附带 PDF
• 表格可视化：表格展示与格式化行为的入口
• 导出管线源码：src/metabase/query_processor/streaming/csv.clj、src/metabase/query_processor/streaming/xlsx.clj、src/metabase/query_processor/middleware/limit.clj

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase