mcpField
D
downloading-batch-export-files

downloading-batch-export-files

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

关于 downloading-batch-export-files

这项 PostHog 技能用于一次性导出 events、persons、sessions 或 HogQL 查询结果。它通过 MCP 启动并监控导出，再通过经过身份验证的 REST 下载端点获取文件。

主要功能

  1. 01导出 events、persons、sessions 或 HogQL
  2. 02选择格式、压缩方式和分片大小
  3. 03监控导出状态并获取文件 ID
  4. 04通过 REST 端点下载分片
  5. 05将文件保存而非打印内容

适用场景

  1. 01创建一次性数据分析导出
  2. 02下载指定时间段的事件
  3. 03将 HogQL 查询结果导出为文件

MCP 相关

使用 PostHog MCP 工具启动并监控批量导出。由于下载路由会重定向，文件通过经过身份验证的 REST 下载端点获取。

安装

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

$npx skills add https://github.com/posthog/ai-plugin --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