JSONEachRowWithProgress

입력	출력	별칭
✗	✔

설명

JSONEachRow/JSONStringsEachRow와 다른 점은 ClickHouse가 각 이벤트를 별도의 JSON 객체로 스트리밍하며 진행 정보도 함께 출력한다는 것입니다. 관련 포맷인 JSONStringsEachRowWithProgress는 동일한 최상위 객체 종류를 사용하되, 필드 값을 문자열로 직렬화합니다. compact 계열 포맷인 JSONCompactEachRowWithProgress와 JSONCompactStringsEachRowWithProgress도 동일한 스트림 객체 종류를 사용하며, 진행 상황/LIMIT/예외 관련 주의 사항도 동일하게 적용됩니다. 단, 이들 포맷의 row / totals / min / max payload는 이름이 지정된 객체가 아니라 값 배열입니다.

스트림 객체

응답의 각 줄은 하나의 JSON 객체입니다. 클라이언트는 최상위 키에 따라 처리해야 합니다.

최상위 키	출력 시점	구조
`meta`	첫 번째 `row` 이전에 한 번 (`progress` 객체가 그보다 먼저 출력될 수 있음)	`{"meta":[{"name":...,"type":...}, ...]}` — 컬럼명(column names)과 타입(types)
`row`	결과 행(row)마다 한 번	`{"row":{...}}` — 해당 행의 컬럼 값
`progress`	쿼리(query) 실행 중 주기적으로	`{"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`	쿼리가 집계(aggregation)를 수행하고 `rows_before_aggregation` 카운터가 활성화되어 있을 때	`{"rows_before_aggregation":N}`
`exception`	HTTP 경로에서 `http_write_exception_in_output_format=1`로 설정된 상태에서 쿼리가 실패할 때	`{"exception":"..."}` — `row` 내부에 중첩되지 않은 최상위 문자열 형태의 오류 텍스트

rows_before_limit_at_least 객체는 쿼리에 LIMIT가 포함되어 있으면, 제한으로 인해 제외된 행이 없더라도 출력됩니다. 이 값은 LIMIT가 없었다면 반환되었을 행 수의 하한 추정치이며, JSON에서와 의미가 같습니다. 클라이언트는 이를 행이 제외되었다는 증거로 간주해서는 안 됩니다. meta는 첫 번째 row 이전에 한 번 출력되지만, progress 객체가 meta보다 먼저 도착할 수 있습니다. 최상위 exception 객체는 HTTP 경로에서 http_write_exception_in_output_format=1로 설정된 경우에만 출력됩니다. 그 외에는 오류가 전송 계층을 통해 전달됩니다. 이 객체는 출력될 때 row 내부에 중첩되지 않고 별도의 최상위 객체로 출력됩니다.

사용 예시

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

meta보다 progress 객체가 먼저 출력될 수도 있습니다. HTTP 경로에서 http_write_exception_in_output_format=1이 설정된 경우, 실패한 쿼리는 row 아래에 중첩되지 않은 별도의 최상위 객체로 끝납니다:

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

SQL 참고

데이터 타입

엔진

함수

포맷

설정

시스템 테이블

데이터 레이크

설명

스트림 객체

사용 예시

포맷 설정

​설명

​스트림 객체

​사용 예시

​포맷 설정

설명

스트림 객체

사용 예시

포맷 설정