SuperAPI AI 工具集

downloading-batch-export-files

通用与其它

查看项目

更新于 10-16 03:45

技能介绍

用途:当用户需要一次性下载 PostHog 数据(events、persons、sessions 或 HogQL 查询结果)时使用本技能。导出任务通过 MCP 启动和监控,最终文件下载直接使用现有 REST 端点。

主要能力:MCP 工具 posthog:file-download-batch-exports-create 启动按需导出并返回 run ID;posthog:file-download-batch-exports-retrieve 轮询状态并在完成后返回文件 ID;posthog:file-download-batch-exports-cancel-create 可取消运行中的导出。不要依赖生成的 MCP 工具访问 /download/ 端点,该端点会重定向,需用原始 HTTP 处理。

使用方式:先确定导出形态。model 取 events、persons、sessions 或 hogql;data_interval_start 与 data_interval_end 为 ISO 8601 时间,不得为未来,两者同时提供时须有序且最多相隔一周(events、persons、sessions 必填;hogql 仅对查询引用的占位符必填)。file.format 为 Parquet 或 JSONLines;file.compression 可选 zstd、gzip、brotli、lz4、snappy,JSONLines 仅支持 gzip 和 brotli;file.max_size_mb 默认 1024,设为 null 则写单文件。events 可用 include/exclude 过滤事件名;hogql 传 hogql_query,SELECT 每列须为字段或有别名。启动后轮询,Completed 时读取 files 数组并下载每个 UUID,同时报告 records_completed。下载用 GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/{part}/,part 可为文件 UUID 或从零开始的索引,单文件可省略 part。文件内容应保存而非打印,Parquet 按字节写入。

适用场景与限制:最大导出区间为一周,更长需求需拆分。hogql 模型处于封闭测试、按团队启用,未启用会报权限错误,应告知用户联系 PostHog 支持申请,而非换查询重试;其资源限制更严,失败时建议用 WHERE 收窄查询。hogql_modifiers 可覆盖项目修饰符,如 {"convertToProjectTimezone": false} 输出 UTC 时间戳,并应传给 count-rows 工具以保持一致。下载 URL 为临时签名链接,过期需重新请求;不要将签名 URL 发给无关服务。大导出可能耗时数分钟,建议缩小事件范围或日期区间。