PostHog 按需批量导出实战：用 file_download_batch_exports API 下载 Parquet / JSONLines 数据文件
PostHog 按需批量导出实战用 file_download_batch_exports API 下载 Parquet / JSONLines 数据文件【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本文基于 PostHog 仓库中的技能文档 downloading-batch-export-files讲解如何按需on-demand一次性导出 PostHog 的 events、persons、sessions 或任意 HogQL 查询结果并下载为本地文件从通过 MCP 工具发起导出、轮询运行状态到最终通过 REST 重定向端点拿到文件以及取消导出、处理失败等完整流程。读完本文你可以独立编写或指导 Agent 完成选择导出形态 → 启动导出 → 轮询完成 → REST 下载 → 规范保存这一全链路操作并理解每种文件格式、压缩选项和区间限制在源码中的落点。适用场景与整体架构这个技能针对的是一次性可下载导出one-off downloadable export需求用户想要一份原始 PostHog 数据文件而不是周期性的数据管道同步。其分工是发起与监控走 MCPposthog:file-download-batch-exports-create启动导出并返回 run IDposthog:file-download-batch-exports-retrieve轮询状态、完成后返回文件 ID。这两个工具在 tools.yaml 中均配置为enabled: true分别要求batch_export:write与batch_export:read权限下载走原生 REST/download/端点是一个返回 302 重定向到临时签名 URL 的文件下载端点因此技能文档明确不要依赖为它生成的 MCP 工具——在 MCP 具备重定向处理支持之前直接使用原始 HTTP 下载是正确接口。这一点也体现在 tools.yaml 中file-download-batch-exports-download-retrieve被刻意设置为enabled: false。路由层可佐证该端点的注册方式routes.py 在 project 路由下注册了file_download_batch_exports对应 file_download.py 中的FileDownloadBatchExportOnDemandViewSet。选择导出形态model、区间与文件格式模型与必填输入发起导出前需要确认以下输入若用户未指定应先追问澄清输入说明model四选一events、persons、sessions、hogqldata_interval_start/data_interval_endISO 8601 时间区间最长为一周。events、persons、sessions必填hogql不支持file.formatParquet或JSONLines。紧凑的分析型导出优先Parquet面向逐行文本处理用JSONLinesfile.compression可选zstd、gzip、brotli、lz4、snappy之一。注意若格式选JSONLines仅支持gzip与brotlifile.max_size_mb可选的分片大小上限MB。希望得到多个小文件而非单个大文件时设置这些约束并非只写在文档里而是在 API 序列化器中强制执行。file_download.py 中一周上限由模块级常量FILE_DOWNLOAD_MAX_RANGE dt.timedelta(weeks1)表达FileFormat的 choices 正是Parquet与JSONLinesformat字段默认值为Parquet压缩 choices 为[zstd, gzip, brotli, lz4, snappy]max_size_mb为min_value0的整数帮助文本即Split download into multiple files of at most this size in MBevents、persons、sessions各有独立请求序列化器均要求data_interval_start/data_interval_enddefault_timezonedt.UTC且只有 events 序列化器带include/exclude两个可选的事件名列表过滤器——这与技能文档中include/exclude 仅用于 events且只在用户明确要求筛选事件时使用的指引一致。events 的 include / exclude对events模型include和exclude是可选的事件名过滤。仅在用户想要特定事件、或想排除某些事件时传递避免无谓缩小或改变导出范围。hogql 模型闭 beta 与查询约束hogql模型将hogql_query作为查询载荷不传data_interval_start、data_interval_end、include、exclude——查询在导出启动时刻执行as of the time the export starts因此没有区间概念。源码侧的FileDownloadHogQLRequestSerializer也印证了这一点它只包含file、model固定为hogql与hogql_query三个字段帮助文本HOGQL_QUERY_HELP_TEXT明确写出闭 beta、按团队启用、不支持占位符、SELECT 中每列必须是字段或带别名等约束。针对hogql的实战要点可通过在查询中加入 WHERE 子句来导出数据切片例如对events表用timestamp限定范围始终将导出量压缩到满足需求的最小集合SELECT 子句中每一列都必须是字段或带别名占位符placeholder不受支持该模型处于闭 beta、按团队启用。从源码看file_download.py 中check_hogql_batch_exports_enabled函数通过特性标志hogql-batch-exports按团队 UUID 组织分组判定权限未启用时抛出PermissionDenied(HogQL batch exports are not enabled for this team.)。遇到这个报错时应直接告知用户联系 PostHog 支持申请开通而不是换一条查询重试用户查询运行在比其它模型更严格的资源限制下因为用户查询不可预测。若导出因内存、执行时间或读取字节数失败应建议用户用 WHERE 子句收窄查询而不是原样重试。源码中可看到专门的用户查询设置get_user_hogql_batch_export_query_settings被用于此类执行路径。此外MCP 侧还提供了一个配套的预检工具posthog:file-download-batch-exports-count-rows-create在 tools.yaml 中启用它只统计一条 HogQL 查询若现在启动导出的话会产出多少行而不会真正启动导出。对应实现 file_download.py 中count_rows_for_hogql_batch_export将max_execution_time压到 30 秒执行一个 count 查询超时或查询过重时返回明确的收窄建议。当用户想预估导出体积时这是一个先于创建导出的低成本检查手段——但注意计数查询本身可能和导出查询一样昂贵需要权衡。启动导出create 请求示例调用posthog:file-download-batch-exports-create并传入所选形态响应中包含导出运行的id。events 模型示例JSONLines gzip仅导出$pageview{ model: events, file: { format: JSONLines, compression: gzip }, include: [$pageview], data_interval_start: 2026-05-25T00:00:00Z, data_interval_end: 2026-05-26T00:00:00Z }hogql 模型示例Parquet无区间字段{ model: hogql, file: { format: Parquet }, hogql_query: SELECT event, timestamp, properties.$current_url AS url FROM events WHERE timestamp now() - INTERVAL 1 HOUR }两个示例恰好覆盖了文档强调的差别非 hogql 模型必须给出一周以内的 ISO 8601 区间hogql 模型则用带 WHERE 限定的查询替代区间。若用户希望多个小文件可在file中追加max_size_mb例如max_size_mb: 250。轮询运行状态用返回的id调用posthog:file-download-batch-exports-retrieve按状态机处理状态动作Starting或Running稍等片刻后再次轮询Completed读取files数组逐个下载文件Cancelled停止并告知用户运行已被取消Failed、FailedRetryable、FailedBilling、Terminated、TimedOut停止报告error字段内容Completed时files数组包含文件 UUID单文件导出通常只有一个 UUID分片导出则包含多个。除非用户只要某个特定分片否则应下载所有UUID不要假设 part0就足够。一个容易踩坑的细节运行刚完成时可能短暂仍报告Running文件记录正在创建中。此时不要立即判失败再次轮询即可。取消运行中的导出如果用户要求可用posthog:file-download-batch-exports-cancel-create并传入id取消运行中的导出。MCP 工具的描述明确只有状态为Starting或Running时调用才成功否则调用会失败取消后返回的状态恒为Cancelled。取消后的语义要注意已结束的或已失败的导出不可再取消取消后该id不能再用于继续导出必须从头重新启动一个新的导出。但id仍可用于 retrieve 查询状态此时永远是Cancelled。通过 REST 下载文件文件下载不走 MCP而是直接用带认证的 HTTP 请求访问既有端点GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/{part}/其中part可以是files数组中返回的文件 UUID零基的文件索引按 key 排序。如果只有一个文件也可以省略partGET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/该端点行为是重定向redirect——让 HTTP 客户端跟随重定向即可拿到文件如需检查可读取Location头获得临时签名 URL。认证使用与其它 PostHog API 调用相同的上下文例如 API key 或会话。该端点在 routes.py 中注册于 project 级路由下run_id即 create 时返回的导出运行 ID。保存而非打印文件内容结果应当按文件下载处理而不是当作聊天回复输出Parquet 是二进制必须以字节方式写入磁盘JSONLines 也可能很大应保存到文件除非用户明确只要一小段样例文件名建议包含模型、运行 ID 和分片标识例如posthog-events-run_id-part.jsonl.gz posthog-persons-run_id-part.parquet重要注意事项速查区间上限一周更长的需求拆成多个导出运行或先询问导出哪一周。hogql 闭 beta 按团队启用报HogQL batch exports 未启用的权限错误时如实报告并建议用户联系支持申请不要换查询重试。hogql 资源限制更严因内存/时间/字节数失败时建议用 WHERE 子句收窄查询而非原样重试。Completed 附近的短暂 Running文件记录创建期间会短暂报Running继续轮询而非判失败。下载 URL 是临时的过期后重新调用 REST 下载端点即可获取新的重定向无需重建导出。签名 URL 具有临时访问权除非用户明确要求不要把它发给无关服务。分片导出要遍历全部files用户要全量时逐个下载所有 UUID。大导出可能耗时数分钟甚至更久可建议用户只包含特定事件或缩短日期范围以加速。延伸阅读仓库内相关路径技能文档本身products/batch_exports/skills/downloading-batch-export-files/SKILL.mdMCP 工具定义create/retrieve/cancel/count-rows 的启用状态与描述products/batch_exports/mcp/tools.yamlAPI 实现序列化器、一周区间常量、hogql 权限检查、count-rowsproducts/batch_exports/backend/api/file_download.py路由注册products/batch_exports/backend/routes.py相关 API 测试products/batch_exports/backend/tests/temporal/destinations/file_download/test_file_download_api.py【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考