---
alias: []
description: 'Documentation for the JSONEachRowWithProgress format'
input_format: false
keywords: ['JSONEachRowWithProgress']
output_format: true
slug: /interfaces/formats/JSONEachRowWithProgress
title: 'JSONEachRowWithProgress'
doc_type: 'reference'
---

{/*AUTOGENERATED_START*/}
| Input | Output | Alias |
|-------|--------|-------|
| ✗     | ✔      |       |

## Description {#description}

Differs from [`JSONEachRow`](/reference/formats/JSON/JSONEachRow)/[`JSONStringsEachRow`](/reference/formats/JSON/JSONStringsEachRow) in that ClickHouse streams each event as a separate JSON object and also yields progress information.

The related `JSONStringsEachRowWithProgress` format uses the same top-level object kinds; field values are serialized as strings.

The compact siblings `JSONCompactEachRowWithProgress` and `JSONCompactStringsEachRowWithProgress` share the same stream-object kinds and progress/`LIMIT`/exception caveats; their `row` / `totals` / `min` / `max` payloads are value arrays instead of named objects.

## Stream objects {#stream-objects}

Each line of the response is one JSON object. Clients should dispatch on the top-level key:

| Top-level key | When it appears | Shape |
|---------------|-----------------|-------|
| `meta` | Once, before the first `row` (a `progress` object may be emitted before it) | `{"meta":[{"name":...,"type":...}, ...]}` — column names and types |
| `row` | Once per result row | `{"row":{...}}` — column values for that row |
| `progress` | Periodically while the query runs | `{"progress":{...}}` — counters such as `read_rows`, `read_bytes`, `total_rows_to_read` |
| `totals` | When totals are present | `{"totals":{...}}` — totals row values |
| `min` / `max` | When extremes are present | `{"min":{...}}` / `{"max":{...}}` — extreme row values |
| `rows_before_limit_at_least` | When the query contains `LIMIT` | `{"rows_before_limit_at_least":N}` — lower estimate of rows there would have been without `LIMIT` (not proof that rows were dropped) |
| `rows_before_aggregation` | When the query performs aggregation and the `rows_before_aggregation` counter is enabled | `{"rows_before_aggregation":N}` |
| `exception` | When the query fails, on the HTTP path with `http_write_exception_in_output_format=1` | `{"exception":"..."}` — error text as a **top-level string**, not nested under `row` |

The `rows_before_limit_at_least` object is emitted when the query contains `LIMIT`, even if the limit did not drop any rows. It is a lower estimate of the number of rows there would have been without `LIMIT` (same meaning as in `JSON`); clients must not treat it as proof that rows were dropped.

`meta` is emitted once before the first `row`, but a `progress` object can arrive before `meta`. The top-level `exception` object is emitted on the HTTP path only when `http_write_exception_in_output_format=1`; otherwise the error surfaces through the transport. When emitted it is a separate top-level object, not nested under `row`.

## Example usage {#example-usage}

```json
{"meta":[{"name":"num","type":"UInt8"},{"name":"str","type":"String"},{"name":"arr","type":"Array(UInt8)"}]}
{"row":{"num":42,"str":"hello","arr":[0,1]}}
{"row":{"num":43,"str":"hello","arr":[0,1,2]}}
{"row":{"num":44,"str":"hello","arr":[0,1,2,3]}}
{"progress":{"read_rows":"3","read_bytes":"24","written_rows":"0","written_bytes":"0","total_rows_to_read":"3"}}
```

A `progress` object may still be emitted before `meta`. On the HTTP path with `http_write_exception_in_output_format=1`, a failed query ends with a separate top-level object (not nested under `row`):

```json
{"exception":"Code: 62. DB::Exception: Syntax error: failed at position 1 (SELECT) (line 1, col 1): ..."}
```

## Format settings {#format-settings}
{/*AUTOGENERATED_END*/}