ArrowStream

ArrowStream é o formato no "modo stream" do Apache Arrow. Ele foi projetado para processamento de streams em memória.

No exemplo abaixo, usamos o conjunto de dados forex, que está disponível no playground SQL do ClickHouse. Você pode se conectar a ele remotamente com clickhouse-client usando o host sql-clickhouse.clickhouse.com e o usuário demo (que não tem senha). A tabela forex está no banco de dados forex, por isso o definimos como banco de dados padrão:

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

A tabela forex armazena taxas de câmbio. Podemos verificar seu tamanho e o nível de compressão em disco consultando 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 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

Ao contrário do formato Arrow em "modo de arquivo", que exige o resultado completo antes de poder ser lido, ArrowStream é entregue como uma sequência de lotes de registros que um consumidor pode ler de forma incremental, à medida que chegam. Isso o torna ideal para transmitir o resultado de uma consulta diretamente para uma ferramenta de visualização ou analytics sem antes materializar todo o dataset.

Para transmitir o resultado, envie a consulta pela interface HTTP do ClickHouse com uma requisição POST e leia a resposta como um stream Arrow. Desabilitamos a compactação da saída Arrow por meio da configuração output_format_arrow_compression_method para que os consumidores possam decodificar os lotes diretamente à medida que os recebem.

A saída ArrowStream é binária bruta, portanto, em vez de imprimi-la no terminal, nós a redirecionamos para um consumidor. O stream é autodescritivo (carrega seu próprio esquema), então aqui o redirecionamos diretamente para o clickhouse-local, que lê os lotes recebidos com --input-format ArrowStream e faz consultas sobre eles como se fossem uma tabela. A tabela forex é grande, então restringimos a consulta remota com um predicado WHERE e um LIMIT para manter este exemplo pequeno:

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 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘

O mesmo stream pode ser consumido de forma incremental por qualquer cliente compatível com Arrow, que o lê lote por lote, em vez de fazer a bufferização do resultado completo. Por exemplo, usando a biblioteca Apache Arrow para JavaScript, um RecordBatchReader retorna cada lote de registros assim que ele é transmitido pelo servidor:

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);
}

Para um passo a passo completo de streaming de dados ArrowStream do ClickHouse para uma visualização em tempo real com Perspective, consulte a postagem do blog Streaming de visualizações em tempo real com ClickHouse, Apache Arrow e Perspective.

ArrowStream compartilha as mesmas configurações de formato do formato Arrow.