> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> JSONCompactEachRowWithProgress 格式文档

# JSONCompactEachRowWithProgress

| 输入 | 输出 | 别名 |
| - | - | - |
| ✗ | ✔ | |

<h2 id="description">
  描述
</h2>

将 [`JSONCompactEachRow`](/docs/zh/reference/formats/JSON/JSONCompactEachRow) 的紧凑逐行输出与流式进度信息相结合。ClickHouse 以流式方式将每个事件作为独立的 JSON 对象输出；列值保留其原生 JSON 类型。

相关的 `JSONCompactStringsEachRowWithProgress` 格式使用相同的顶层对象类型，但字段值会被序列化为字符串。

与 [`JSONEachRowWithProgress`](/docs/zh/reference/formats/JSON/JSONEachRowWithProgress) 遵循相同的流契约 (`writesProgressConcurrently` / `finalizeImpl`) ，区别在于 `row` / `totals` / `min` / `max` 载荷是按列顺序排列的值**数组**，而非具名对象。

<h2 id="stream-objects">
  流对象
</h2>

响应的每一行都是一个 JSON 对象。客户端应根据顶层键分派处理：

| 顶层键 | 出现时机 | 形态 |
| - | - | - |
| `meta` | 出现一次，位于第一个 `row` 之前 (在它之前可能会先输出 `progress` 对象) | `{"meta":[{"name":...,"type":...}, ...]}` — 列名和类型 |
| `row` | 每个结果行出现一次 | `{"row":[...]}` — 按表头顺序排列的列值 |
| `progress` | 查询运行期间定期出现 | `{"progress":{...}}` — 计数器，例如 `read_rows`、`read_bytes`、`total_rows_to_read` |
| `totals` | 存在汇总值时 | `{"totals":[...]}` — 按表头顺序排列的汇总行值 |
| `min` / `max` | 存在极值时 | `{"min":[...]}` / `{"max":[...]}` — 按表头顺序排列的极值行值 |
| `rows_before_limit_at_least` | 查询包含 `LIMIT` 时 | `{"rows_before_limit_at_least":N}` — 不使用 `LIMIT` 时本应返回行数的下限估计 (并不能证明有行被丢弃) |
| `rows_before_aggregation` | 查询执行了聚合且启用了 `rows_before_aggregation` 计数器时 | `{"rows_before_aggregation":N}` |
| `exception` | 查询失败时，在 HTTP 路径上且设置了 `http_write_exception_in_output_format=1` | `{"exception":"..."}` — 错误文本以**顶层字符串**形式输出，而非嵌套在 `row` 中 |

只要查询包含 `LIMIT`，就会输出 `rows_before_limit_at_least` 对象，即使该限制实际上并未丢弃任何行。它表示不使用 `LIMIT` 时本应返回行数的下限估计 (含义与 `JSON` 格式中相同) ；客户端不得据此认定有行被丢弃。

`meta` 会在第一个 `row` 之前输出一次，但 `progress` 对象可能先于 `meta` 到达。仅当设置了 `http_write_exception_in_output_format=1` 时，HTTP 路径上才会输出顶层 `exception` 对象；否则错误将通过传输层反馈。该对象输出时是一个独立的顶层对象，而非嵌套在 `row` 中。

<h2 id="example-usage">
  使用示例
</h2>

```sql title="Query" theme={null}
SELECT *
FROM generateRandom('a Array(Int8), d Decimal32(4), c Tuple(DateTime64(3), UUID)', 1, 10, 2)
LIMIT 5
FORMAT JSONCompactEachRowWithProgress
```

```response title="Response" theme={null}
{"meta":[{"name":"a","type":"Array(Int8)"},{"name":"d","type":"Decimal(9, 4)"},{"name":"c","type":"Tuple(DateTime64(3), UUID)"}]}
{"row":[[-8], 46848.5225, ["2064-06-11 14:00:36.578","b06f4fa1-22ff-f84f-a1b7-a5807d983ae6"]]}
{"row":[[-76], -85331.598, ["2038-06-16 04:10:27.271","2bb0de60-3a2c-ffc0-d7a7-a5c88ed8177c"]]}
{"row":[[-32], -31470.8994, ["2027-07-18 16:58:34.654","1cdbae4c-ceb2-1337-b954-b175f5efbef8"]]}
{"row":[[-116], 32104.097, ["1979-04-27 21:51:53.321","66903704-3c83-8f8a-648a-da4ac1ffa9fc"]]}
{"row":[[], 2427.6614, ["1980-04-24 11:30:35.487","fee19be8-0f46-149b-ed98-43e7455ce2b2"]]}
{"progress":{"read_rows":"5","read_bytes":"184","total_rows_to_read":"5","elapsed_ns":"335771"}}
{"rows_before_limit_at_least":5}
```

<h2 id="format-settings">
  格式设置
</h2>