Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ArrowStream

View as MarkdownEdit this pageReport an issueSet up docs MCP
输入 输出 别名
✔ ✔

说明

ArrowStream 是 Apache Arrow 的“流模式”格式，专为内存中的流式处理而设计。

示例用法

在下面的示例中，我们使用 forex 数据集，可在 ClickHouse SQL playground 中使用。你可以使用主机 sql-clickhouse.clickhouse.com 和用户 demo (无需密码) ，通过 clickhouse-client 远程连接到它。forex 表位于 forex 数据库中，因此我们将其选作默认数据库：

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

forex 表用于存储货币汇率。我们可以通过查询 system.columns 来查看它的大小， 以及它在磁盘上的压缩情况：

Querysql
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
Responseresponse
   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

与需要先获得完整结果后才能读取的 Arrow“文件模式”格式不同，ArrowStream 是以 记录批次序列的形式传输的，消费者可以在这些批次到达时 逐步读取。这使它非常适合将查询结果直接流式传输到 可视化或分析工具中，而无需先将整个数据集物化。

要流式传输结果，请通过 ClickHouse 的 HTTP interface 使用 POST 请求发送查询，并将响应作为 Arrow stream 读取。我们通过 output_format_arrow_compression_method 设置禁用 Arrow 输出的压缩， 以便消费者在收到批次时可以直接对其进行解码。

ArrowStream 输出是原始二进制数据，因此我们不将其打印到 终端，而是通过管道将其传给消费者。该 stream 是自描述的 (它携带 自己的 schema) ，因此这里我们将它直接通过管道传给 clickhouse-local，后者使用 --input-format ArrowStream 读取传入批次，并将其作为一张表进行查询。 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"
Responseresponse
   ┌─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 实现的实时可视化，请参阅 这篇博客文章 使用 ClickHouse、Apache Arrow 和 Perspective 实现实时流式可视化.

格式设置

ArrowStream 与 Arrow 格式共享相同的格式设置。

Setting Description Default
input_format_arrow_allow_missing_columns 读取 Arrow 输入格式时允许缺失列 1
input_format_arrow_case_insensitive_column_matching 匹配 Arrow 列与 CH 列时忽略大小写。 0
input_format_arrow_import_nested 已废弃，不执行任何操作。 0
input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference 对 Arrow 格式进行 schema inference 时，跳过包含不支持类型的列 0
output_format_arrow_compression_method Arrow 输出格式的压缩方法。支持的编解码器：lz4_frame、zstd、none (未压缩) lz4_frame
output_format_arrow_date_as_uint16 将 Date 值写为普通的 16 比特数值 (读取时为 UInt16) ，而不是转换为 32 比特的 Arrow DATE32 类型 (读取时为 Date32) 。 0
output_format_arrow_fixed_string_as_fixed_byte_array 对 FixedString 列使用 Arrow FIXED_SIZE_BINARY 类型，而不是 Binary 类型。 1
output_format_arrow_low_cardinality_as_dictionary 启用将 LowCardinality 类型输出为 Arrow 的 Dictionary 类型 0
output_format_arrow_string_as_string 对 String 列使用 Arrow String 类型，而不是 Binary 类型 1
output_format_arrow_unsupported_types_as_binary 将没有对应 Arrow 等价类型的类型 (例如 BFloat16、AggregateFunction) 输出为原始二进制数据。如果为 false，此类类型将引发异常。 1
output_format_arrow_use_64_bit_indexes_for_dictionary 在 Arrow 格式中始终对字典索引使用 64 比特整数 0
output_format_arrow_use_signed_indexes_for_dictionary 在 Arrow 格式中对字典索引使用有符号整数 1
Navigation