mcpField
D
downloading-batch-export-files

downloading-batch-export-files

github.com/posthog数据与数据库76322 次安装今天更新
代码仓库

关于 downloading-batch-export-files

面向 PostHog 单次数据导出的工作流技能。它指导用户选择导出配置、通过 MCP 启动并监控任务，再通过 REST 下载端点保存文件。

主要功能

  1. 01配置模型、日期范围和文件格式
  2. 02通过 MCP 启动并轮询导出任务
  3. 03通过 REST 端点下载文件
  4. 04处理拆分文件和任务状态
  5. 05将大型或二进制结果保存为文件

适用场景

  1. 01导出 events、persons 或 sessions 供分析
  2. 02将 HogQL 查询作为批量导出运行
  3. 03为后续处理选择文件格式和压缩方式

MCP 相关

使用 MCP 工具创建并监控批量导出任务。文件通过 PostHog REST 下载端点获取，因为下载路由会重定向。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill downloading-batch-export-files

安装后在 Claude Code 中输入/downloading-batch-export-files确认已加载。

详细介绍

下载批量导出文件

当用户需要一次性下载 PostHog 数据导出文件时，使用此技能。 通过 MCP 启动并监控导出，但最终文件下载需直接使用现有的 REST 端点。

可用的 MCP 工具

工具用途
posthog:file-download-batch-exports-create启动按需导出并返回运行 ID
posthog:file-download-batch-exports-retrieve轮询运行状态，并在完成后返回文件 ID

不要依赖为 /download/ 端点生成的 MCP 工具。 该端点会重定向到文件下载，因此在 MCP 明确支持重定向之前，原始 HTTP／下载处理才是正确的接口。

工作流

1. 选择导出格式

如果用户未指定必要输入，请提出一个简短的澄清问题：

  • model：以下之一：events、persons、sessions 或 hogql
  • data_interval_start 和 data_interval_end：ISO 8601 日期时间。任何提供的时间边界都不能是未来时间。如果同时提供两个边界，它们必须按时间顺序排列，且间隔最多为一周 events、persons 和 sessions 必须提供。 对于 hogql，仅当查询引用了占位符时才需要提供。如果只引用了一个占位符，可以省略另一个时间边界，且不受一周间隔的限制。
  • file.format：Parquet 或 JSONLines；紧凑型分析数据导出优先使用 Parquet，按行处理文本则优先使用 JSONLines
  • file.compression：可选，以下之一：zstd、gzip、brotli、lz4 或 snappy。如果选择的格式是 JSONLines，则仅支持 gzip 和 brotli。
  • file.max_size_mb：分片大小，单位为 MiB，默认为 1024。分片大小可能略微超出此值。 用户需要更小的分片时调低该值，需要更少且更大的分片时调高该值，或设为 null 以写入一个不限大小的文件。

对于 events，include 和 exclude 是可选的事件名称筛选条件。 只有在用户要求指定事件或排除指定事件时才使用。

对于 hogql，将查询作为 hogql_query 传入，并省略 include 和 exclude。 你可以建议用户在 HogQL 查询中加入 WHERE 子句来导出部分数据，例如通过限制 events 表的 timestamp 来限定结果。 始终优先将导出数据限制在解决用户请求所需的最小范围内。 SELECT 子句中的每一列都必须是字段或带有别名。 此模型目前处于封闭 Beta 阶段，按团队启用。

hogql 查询可以引用 {data_interval_start} 和 {data_interval_end} 占位符。 导出时会将其替换为 data_interval_start 和 data_interval_end 的值，因此一个查询就可以导出任意时间区间。 为查询引用的每个占位符提供相应的时间边界；缺少边界会导致请求失败。 这些边界只会替换占位符，本身不会筛选任何数据，因此即使提供了时间边界，不含占位符的查询仍会原样运行。 当用户需要指定时间范围，或使用同一查询导出多个连续时间范围时，优先使用占位符而不是字面日期。 使用 >= {data_interval_start} 和 < {data_interval_end} 进行比较，确保连续时间范围不会重复导出同一行。

2. 启动导出

使用选定的格式调用 posthog:file-download-batch-exports-create。 响应中包含导出运行的 id。

请求示例：

{
  "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 模型的请求示例：

{
  "model": "hogql",
  "file": {
    "format": "Parquet"
  },
  "hogql_query": "SELECT event, timestamp, properties.$current_url AS url FROM events WHERE timestamp >= {data_interval_start} AND timestamp < {data_interval_end}",
  "data_interval_start": "2026-05-25T00:00:00Z",
  "data_interval_end": "2026-05-26T00:00:00Z"
}
3. 轮询直至完成

使用返回的 id 调用 posthog:file-download-batch-exports-retrieve。

状态处理：

状态操作
Starting 或 Running短暂等待后再次轮询
Completed读取 files 数组并下载每个文件
Cancelled停止并报告运行已取消
Failed、FailedRetryable、FailedBilling、Terminated 或 TimedOut停止并报告 error 字段

当状态为 Completed 时，files 数组包含文件 UUID。 单文件导出通常包含一个 UUID。 对于拆分导出，除非用户指定了特定部分，否则下载所有 UUID。

Completed 响应还包含 records_completed，即本次运行导出的行数。 请将其告知用户，因为只有逐个打开文件才能查看该数量。

4. 可选：取消正在运行的导出

如果用户有需要，可以使用返回的 id 调用 posthog:file-download-batch-exports-cancel-create，取消正在运行的导出。

已经完成或失败的导出可能无法取消。

取消导出后，可能无法再使用该 id，必须从头开始重新导出。不过，仍可使用该 id 查询导出状态（状态始终为 Cancelled）。

5. 通过 REST 下载文件

向现有端点发送直接的身份验证 HTTP 请求：

GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/{part}/

part 可以是以下任一项：

  • file-download-batch-exports-retrieve 返回的 files 数组中的文件 UUID
  • 按键排序的从零开始的文件索引

如果只有一个文件，也可以不指定 part：

GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/

让 HTTP 客户端跟随重定向；如果需要临时签名 URL，也可以检查 Location 标头。 使用与其他 API 调用相同的 PostHog 身份验证上下文。

6. 保存文件，不要打印内容

将结果视为文件下载，而非聊天回复。 Parquet 是二进制格式，必须以字节形式写入。 JSONLines 文件也可能很大；请将其保存到文件中，不要粘贴内容，除非用户明确要求查看少量样例。

尽可能使用包含模型、运行 ID 和部分标识符的文件名，例如：

posthog-events-<run_id>-<part>.jsonl.gz
posthog-persons-<run_id>-<part>.parquet

重要说明

  • 导出的最长时间范围为一周。请将更长的用户请求拆分为多个单独的导出任务，或询问用户要导出哪一周。
  • hogql 模型处于封闭测试阶段，需按团队启用。如果出现提示未启用 HogQL 批量导出的权限错误，说明该团队尚未获得测试资格。请报告这一情况，不要尝试更换查询，并告知用户可以联系 PostHog 支持团队申请访问权限。
  • hogql 模型的资源限制比其他模型更严格，因为用户查询的可预测性较低。如果导出因内存、执行时间或读取字节数限制而失败，请建议使用 WHERE 子句缩小查询范围，而不是原样重试。
  • hogql 模型接受可选的 hogql_modifiers 对象。对象中的每个修饰符都会在本次导出中覆盖项目中同名的 HogQL 修饰符；项目修饰符则适用于其他所有情况。除非项目设置了 convertToProjectTimezone 修饰符，否则 timestamp 列会以 UTC 时区显示；如果用户希望使用项目时区，请传入 {"convertToProjectTimezone": true}。向 posthog:file-download-batch-exports-count-rows-create 传入相同的 hogql_modifiers，以确保行数与导出内容相符。
  • 创建文件记录期间，运行任务在完成后可能会短暂显示为 Running。请再次轮询，不要立即判定失败。
  • 下载 URL 是临时的。如果 URL 过期，请再次调用 REST 下载端点以获取新的重定向。
  • 除非用户明确要求，否则不要将签名 URL 发送给无关服务；该 URL 授予对导出文件的临时访问权限。
  • 如果用户需要拆分导出的所有部分，请遍历 files 中的每个 UUID；不要假设第 0 部分就足够。
  • 大型批量导出可能需要几分钟甚至更长时间才能完成。请建议用户仅包含特定事件或缩小日期范围，以加快下载速度。

评论

支持 Markdown