downloading-batch-export-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Downloading batch export files

下载批量导出文件

Use this skill when a user wants a one-off downloadable export of PostHog data. The export is started and monitored through MCP, but the final file download uses the existing REST endpoint directly.

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

Available MCP tools

可用的 MCP 工具

Tool	Purpose
`posthog:file-download-batch-exports-create`	Start an on-demand export and return the run ID
`posthog:file-download-batch-exports-retrieve`	Poll the run status and return file IDs after completion

Do not rely on a generated MCP tool for the

/download/

endpoint. That endpoint is a redirecting file download endpoint, so raw HTTP/download handling is the right interface until MCP has explicit redirect support.

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

不要依赖为

/download/

端点生成的 MCP 工具。该端点是一个带重定向的文件下载端点，因此在 MCP 明确支持重定向之前，直接使用原始 HTTP 或下载处理方式是合适的接口。

Workflow

工作流

1. Choose the export shape

1. 选择导出形式

Ask a short clarifying question if the user did not specify the required inputs:

```
model
```
: one of
```
events
```
,
```
persons
```
,
```
sessions
```
, or
```
hogql
```
```
data_interval_start
```
and
```
data_interval_end
```
: ISO 8601 datetimes. Any supplied bound may not be in the future. When both bounds are supplied, they must be ordered and at most one week apart Required for
```
events
```
,
```
persons
```
, and
```
sessions
```
. For
```
hogql
```
, required only for the placeholders the query references. If only one placeholder is referenced, the other bound may be omitted and the one-week limit does not apply.
```
file.format
```
:
```
Parquet
```
or
```
JSONLines
```
; prefer
```
Parquet
```
for compact analytics exports and
```
JSONLines
```
for line-oriented text processing
```
file.compression
```
: optional, one of
```
zstd
```
,
```
gzip
```
,
```
brotli
```
,
```
lz4
```
, or
```
snappy
```
. If
```
JSONLines
```
was chosen as format, only
```
gzip
```
and
```
brotli
```
are supported.
```
file.max_size_mb
```
: part size in MiB, 1024 by default. A part can go a little over this size. Lower it when the user wants smaller parts, raise it for fewer and bigger ones, or set it to
```
null
```
to write a single file of any size.

For

events

include

and

exclude

are optional event-name filters. Use them only when the user asks for specific events or wants to omit specific events.

For

hogql

, pass the query as

hogql_query

and leave out

include

and

exclude

. You may prompt the user to export a slice of data by including a WHERE clause in the HogQL query, for example limiting results from the

events

table by bounding

timestamp

. Always prefer limiting the data exported to the minimum necessary to solve the user's request. Every column in the SELECT clause must be a field or have an alias. This model is in closed beta and is enabled per team.

hogql

query can reference the

{data_interval_start}

and

{data_interval_end}

placeholders. The export replaces them with the

data_interval_start

and

data_interval_end

values, so one query can export any interval. Supply a bound for every placeholder the query references; a missing bound fails the request. The bounds only replace placeholders and do not filter anything themselves, so a query without placeholders runs unchanged even when bounds are supplied. Prefer placeholders over literal dates when the user wants a time range, or several consecutive ranges from the same query. Compare with

>= {data_interval_start}

and

< {data_interval_end}

, so consecutive ranges do not export the same row twice.

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

```
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

子句来导出部分数据，例如通过限定

timestamp

范围来限制

events

表中的结果。始终优先将导出的数据限制在满足用户请求所需的最小范围内。

SELECT

子句中的每一列都必须是字段或具有别名。该模型处于 closed beta 阶段，并按团队启用。

hogql

查询可以引用

{data_interval_start}

和

{data_interval_end}

占位符。导出时，系统会将它们替换为

data_interval_start

和

data_interval_end

的值，因此一个查询即可导出任意时间区间。必须为查询引用的每个占位符提供边界；缺少边界会导致请求失败。这些边界只用于替换占位符，本身不会过滤任何内容，因此即使提供了边界，不含占位符的查询也会原样运行。当用户需要一个时间范围，或需要从同一查询导出多个连续时间范围时，优先使用占位符，而不是字面日期。使用

>= {data_interval_start}

和

< {data_interval_end}

进行比较，这样连续的时间范围不会重复导出同一行。

2. Start the export

2. 启动导出

Call

posthog:file-download-batch-exports-create

with the selected shape. The response contains an

id

for the export run.

Example request:

json

{
  "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"
}

Example request for the

hogql

model:

json

{
  "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"
}

根据所选配置调用

posthog:file-download-batch-exports-create

。响应中包含导出运行的

id

。

示例请求：

json

{
  "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

模型的示例请求：

json

{
  "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. Poll until completion

3. 轮询直至完成

Call

posthog:file-download-batch-exports-retrieve

with the returned

id

Status handling:

Status	Action
`Starting` or `Running`	Wait briefly and poll again
`Completed`	Read the `files` array and download each file
`Cancelled`	Stop and report that the run was cancelled
`Failed` , `FailedRetryable` , `FailedBilling` , `Terminated` , or `TimedOut`	Stop and report the `error` field

When

Completed

, the

files

array contains file UUIDs. For single-file exports it usually contains one UUID. For split exports, download every UUID unless the user asked for a specific part.

Completed

response also carries

records_completed

, the number of rows the run exported. Report it to the user, because the count is otherwise only visible by opening every file.

使用返回的

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. Optionally, cancel a running export

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

If required by the user, a running export can be cancelled by calling

posthog:file-download-batch-exports-cancel-create

with the returned

id

An export that has already finished or has already failed may not be cancelled.

After cancelling an export, the

id

may not be used anymore and the export must start again from the beginning. However, you may still use the

id

to retrieve the export status (which will always be

Cancelled

如果用户要求，可以调用

posthog:file-download-batch-exports-cancel-create

并传入返回的

id

，从而取消正在运行的导出。已经完成或已经失败的导出可能无法再取消。

取消导出后，

id

可能无法再用于其他操作，并且必须从头重新开始导出。不过，仍可以使用该

id

获取导出状态，其状态将始终为

Cancelled

。

5. Download files through REST

5. 通过 REST 下载文件

Use a direct authenticated HTTP request to the existing endpoint:

text

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

part

can be either:

a file UUID from the

files

array returned by

file-download-batch-exports-retrieve

a zero-based file index, ordered by key

If there is only one file, this also works without

part

text

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

Let the HTTP client follow the redirect, or inspect the

Location

header if you need the temporary signed URL. Use the same PostHog authentication context as other API calls.

对现有端点发起直接经过身份验证的 HTTP 请求：

text

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

part

可以是以下任一种：

file-download-batch-exports-retrieve

返回的

files

数组中的文件 UUID

从零开始的文件索引，按
```
key
```
排序

如果只有一个文件，也可以不提供

part

：

text

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

可以让 HTTP 客户端自动跟随重定向，也可以在需要获取临时签名 URL 时检查

Location

标头。使用与其他 API 调用相同的 PostHog 身份验证上下文。

6. Save, do not print, file contents

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

Treat the result as a file download, not a chat response. Parquet is binary and must be written as bytes. JSONLines may still be large; save it to a file rather than pasting the contents unless the user explicitly asks for a tiny sample.

Use a filename that includes the model, run ID, and part identifier when possible, for example:

text

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

将结果视为文件下载，而不是聊天回复。 Parquet 是二进制文件，必须以字节形式写入。 JSONLines 也可能很大；应将其保存到文件，而不是粘贴内容，除非用户明确要求提供一个小样本。

尽可能使用包含 model、run ID 和 part 标识符的文件名，例如：

text

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

Important notes

重要说明

The maximum export interval is one week. Split longer user requests into separate export runs or ask which week to export.
The
```
hogql
```
model is in closed beta and is enabled per team. A permission error that says HogQL batch exports are not enabled means the team does not have the beta. Report that instead of retrying with a different query, and tell the user they can contact PostHog support to request access.
The
```
hogql
```
model runs under stricter resource limits than the other models, because user queries are less predictable. If an export fails on memory, execution time, or bytes read, suggest narrowing the query with a WHERE clause instead of retrying it unchanged.
The
```
hogql
```
model accepts an optional
```
hogql_modifiers
```
object. Each modifier in it overrides the project HogQL modifier with the same name for this export only, and the project modifiers apply to all others. Unless the project sets the
```
convertToProjectTimezone
```
modifier,
```
timestamp
```
columns come out in UTC, so pass
```
{"convertToProjectTimezone": true}
```
when the user wants them in the project timezone. Pass the same
```
hogql_modifiers
```
to
```
posthog:file-download-batch-exports-count-rows-create
```
, so that the count matches the export.
A run can briefly report
```
Running
```
after completion while file records are being created. Poll again instead of failing immediately.
Download URLs are temporary. If a URL expires, call the REST download endpoint again for a fresh redirect.
Do not send the signed URL to unrelated services unless the user explicitly asks; it grants temporary access to the exported file.
If the user wants all parts of a split export, iterate over every UUID in
```
files
```
; do not assume part
```
0
```
is enough.
Large batch exports may take a few minutes or even longer to complete. Suggest to the user that they can speed-up their download by including only certain events or narrowing the date range.

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