zpq 0.5.0이 Parquet 파일을 SQL로 처리한다

zpq 0.5.0은 로컬 디스크나 S3의 Parquet 파일을 조회·필터링·집계하고, 결과를 NDJSON·CSV·Parquet으로 내보내는 Zig 기반 명령줄 도구다. 단일 테이블을 처리하며 조인은 지원하지 않는다.

프로젝트 저장소와 프로젝트 사이트에서 설치 방법과 예제를 확인할 수 있다. Homebrew로 설치하거나 최신 릴리스에서 운영체제와 CPU에 맞는 바이너리를 받을 수 있다. Linux x86_64 기본 빌드는 AVX2가 필요하며, 이를 지원하지 않는 구형 CPU에는 -compat 빌드를 써야 한다. 직접 빌드하려면 Zig 0.17.0이 필요하다.

ClickBench 공개 데이터로 파일을 살펴보고 SQL 질의를 실행하는 예시는 다음과 같다.

$ zpq inspect hits_0.parquet | head -12
hits_0.parquet: Parquet v1, 1000000 rows, 122446530 bytes, 2 row groups
 created_by: parquet-cpp version 1.5.1-SNAPSHOT; sorting_columns: unsupported
 row group 0: 450560 rows, 188923477 uncompressed bytes
 WatchID INT64 SNAPPY: 3883794/3883596 compressed/uncompressed bytes
 min=4611687214012840539 (unknown) max=9223369186199968220 (unknown); nulls=0
 index=absent/absent, Bloom=absent, dictionary fallback=present
 hint: page pruning unavailable: column index absent
 hint: compression saves no bytes: compressed >= uncompressed
 hint: dictionary fallback: mixed data encodings in encoding_stats
 JavaEnable INT32 SNAPPY: 20529/24207 compressed/uncompressed bytes
 min=0 (unknown) max=1 (unknown); nulls=0
 index=absent/absent, Bloom=absent, dictionary fallback=absent

$ zpq query --query "SELECT SearchPhrase, count(*) AS c FROM 'hits_0.parquet' \
 WHERE SearchPhrase <> '' GROUP BY SearchPhrase ORDER BY c DESC LIMIT 3" | jq -c .
{"SearchPhrase":"ведомосквы вместу","c":4943}
{"SearchPhrase":"ведомосквы вы из","c":2471}
{"SearchPhrase":"ведомосквиталия страции","c":2026}

프로젝트 설명에 따르면 zpq는 정확한 결과를 얻는 데 필요한 작업만 하도록 푸터와 통계를 먼저 확인하고 관련 페이지를 읽는다. DECIMAL 값은 정수로 정확하게 유지하며, 스레드 수와 관계없이 같은 행 순서를 반환한다고 설명한다. S3 파일도 직접 읽을 수 있다.

프로젝트 측 벤치마크는 ClickBench, PDS-H, 합성 집계 사례 390개를 포함한 질의 464개를 비교했다. 질의마다 새 프로세스를 시작한 콜드 실행에서 zpq는 438개 질의에서 DuckDB 2.0과 Polars 2.0보다 빨랐고, 나머지에서도 두 도구 중 빠른 쪽보다 1.5배 넘게 느린 경우는 없었다고 밝혔다. 기하평균 실행 시간은 콜드 실행에서 더 빠른 경쟁 도구의 0.56배, 핫 실행에서 0.48배였다. 전체 결과와 방법은 벤치마크 페이지에 공개돼 있다.

제약도 있다. 조인과 윈도 함수는 지원하지 않으며, 일부 SQL은 오류 메시지와 종료 코드 2를 반환하며 거부된다. --max-memory는 엄격한 메모리 상한이 아니어서, 카디널리티가 높은 GROUP BY나 count(DISTINCT)는 한도 근처에서 설정값의 약 2배까지 메모리를 사용할 수 있다. 결과는 정확하게 반환되거나 질의가 정상적으로 거부되며, 엄격한 상한이 필요하면 cgroup의 memory.max나 ulimit -v를 사용하라고 안내한다. JSON 출력에서 DATE와 TIMESTAMP는 저장된 정수로, CSV 출력에서는 ISO 형식으로 표시된다. Windows 빌드는 없고, libzpq를 통한 SQL은 실험적이다.

자세한 변경 사항은 CHANGELOG.md, 기능과 출력 형식은 기능 문서와 출력 형식 문서에서 확인할 수 있다.