ArrowStream 형식

ArrowStream 형식

ArrowStream은 Apache Arrow의 "스트림 모드" 형식으로, 메모리 내 스트림 처리를 위해 설계되었어요. "파일 모드" 형식처럼 전체 결과를 기다려야 하는 대신, 소비자가 도착하는 대로 점진적으로 읽을 수 있는 일련의 레코드 배치로 전달된다는 특징이 있답니다.

출처: 문서

본문

설명 (Description)

ArrowStream은 Apache Arrow의 "스트림 모드" 형식입니다. 메모리 내 스트림 처리용으로 설계되었어요.

사용 예시 (Example usage)

아래 예시에서는 ClickHouse SQL 플레이그라운드에서 사용 가능한 forex 데이터셋을 사용합니다. clickhouse-client로 호스트 sql-clickhouse.clickhouse.com과 사용자 demo(비밀번호 없음)를 사용해 원격으로 연결할 수 있어요. forex 테이블은 forex 데이터베이스에 있으므로 기본 데이터베이스로 선택합니다:

clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex

forex 테이블은 환율을 저장합니다. system.columns를 쿼리하여 크기와 디스크에서 얼마나 잘 압축되는지 확인할 수 있어요:

쿼리

SELECT
    table,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed_size,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed_size,
    sum(data_compressed_bytes) / sum(data_uncompressed_bytes) AS compression_ratio
FROM system.columns
WHERE (database = 'forex') AND (table = 'forex')
GROUP BY table
ORDER BY table ASC

응답

   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

읽기 전에 전체 결과가 필요한 Arrow "파일 모드" 형식과 달리, ArrowStream은 소비자가 도착하는 대로 점진적으로 읽을 수 있는 일련의 레코드 배치로 전달됩니다. 이는 전체 데이터셋을 먼저 실체화(materialize)하지 않고 쿼리 결과를 시각화 또는 분석 도구에 바로 스트리밍하기에 적합합니다.

결과를 스트리밍하려면 ClickHouse HTTP 인터페이스에 POST 요청으로 쿼리를 보내고 응답을 Arrow 스트림으로 읽으면 됩니다. output_format_arrow_compression_method 설정으로 Arrow 출력 압축을 비활성화하여 소비자가 받는 즉시 배치를 직접 디코딩할 수 있게 합니다.

ArrowStream 출력은 원시 바이너리이므로 터미널에 출력하지 않고 소비자로 파이프합니다. 스트림은 자체 기술(self-describing) 형식(자체 스키마를 가짐)이므로, 여기서는 들어오는 배치를 --input-format ArrowStream으로 읽고 테이블로 쿼리하는 clickhouse-local로 바로 파이프합니다. forex 테이블이 크므로 예시를 작게 유지하기 위해 원격 쿼리를 WHERE 조건과 LIMIT으로 제한합니다:

curl "https://sql-clickhouse.clickhouse.com:8443/?user=demo&database=forex" \
    --data-binary "
        SELECT
            concat(base, '.', quote) AS base_quote,
            datetime AS last_update,
            CAST(bid, 'Float32') AS bid,
            CAST(ask, 'Float32') AS ask,
            ask - bid AS spread
        FROM forex
        WHERE base = 'USD' AND quote = 'CHF'
        ORDER BY datetime ASC
        LIMIT 5
        FORMAT ArrowStream
        SETTINGS output_format_arrow_compression_method='none'" \
  | clickhouse-local --input-format ArrowStream \
      --query "SELECT * FROM table ORDER BY last_update ASC FORMAT PrettyCompact"

응답

   ┌─base_quote─┬─────────────last_update─┬────bid─┬────ask─┬────────────────spread─┐
1. │ USD.CHF    │ 2000-05-30 17:23:44.000 │  1.688 │ 1.6885 │ 0.0005000829696655273 │
2. │ USD.CHF    │ 2000-05-30 17:23:46.000 │ 1.6885 │  1.689 │ 0.0004999637603759766 │
3. │ USD.CHF    │ 2000-05-30 17:23:48.000 │ 1.6886 │ 1.6891 │ 0.0005000829696655273 │
4. │ USD.CHF    │ 2000-05-30 17:23:49.000 │ 1.6888 │ 1.6893 │ 0.0004999637603759766 │
5. │ USD.CHF    │ 2000-05-30 17:24:45.000 │  1.689 │ 1.6895 │ 0.0004999637603759766 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘

같은 스트림은 Arrow를 아는 어떤 클라이언트에서도 점진적으로 소비할 수 있으며, 결과를 전체 버퍼링하지 않고 배치 단위로 읽습니다. 예를 들어 Apache Arrow JavaScript 라이브러리를 사용하면 RecordBatchReader가 서버에서 스트리밍되는 즉시 각 레코드 배치를 산출합니다:

const reader = await RecordBatchReader.from(response);
await reader.open();
for await (const recordBatch of reader) {
    const batchTable = new Table(recordBatch);
    const ipcStream = tableToIPC(batchTable, 'stream');
    const bytes = new Uint8Array(ipcStream);
    table.update(bytes);
}

ClickHouse에서 ArrowStream 데이터를 Perspective로 실시간 시각화로 스트리밍하는 전체 연습은 블로그 게시물 "Streaming real-time visualizations with ClickHouse, Apache Arrow and Perspective"를 참조하세요.

형식 설정 (Format settings)

ArrowStream은 Arrow 형식과 동일한 형식 설정을 공유합니다.

더 알아보기 (Learn more)

• Formats 개요
• Avro 형식