> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> ArrowStream 格式文档
# ArrowStream
| 输入 | 输出 | 别名 |
| -- | -- | -- |
| ✔ | ✔ | |
## 说明
`ArrowStream` 是 Apache Arrow 的“流模式”格式，专为内存中的流式处理而设计。
## 示例用法
在下面的示例中，我们使用 `forex` 数据集，可在
[ClickHouse SQL playground](https://sql.clickhouse.com) 中使用。你可以使用主机 `sql-clickhouse.clickhouse.com`
和用户 `demo` (无需密码) ，通过 `clickhouse-client` 远程连接到它。`forex` 表位于
`forex` 数据库中，因此我们将其选作默认数据库：
```bash theme={null}
clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex
```
`forex` 表用于存储货币汇率。我们可以通过查询 [`system.columns`](/zh/reference/system-tables/columns) 来查看它的大小，
以及它在磁盘上的压缩情况：
```sql title="Query" theme={null}
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
```
```response title="Response" theme={null}
┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB │ 280.48 GiB │ 0.22708227109363446 │
└───────┴─────────────────┴───────────────────┴─────────────────────┘
```
与需要先获得完整结果后才能读取的 [`Arrow`](/zh/reference/formats/Arrow/Arrow)“文件模式”格式不同，`ArrowStream` 是以
record batch 序列的形式传输的，消费者可以在这些批次到达时
逐步读取。这使它非常适合将查询结果直接流式传输到
可视化或分析工具中，而无需先将整个数据集物化。
要流式传输结果，请通过 ClickHouse 的 HTTP interface 使用
`POST` 请求发送查询，并将响应作为 Arrow stream 读取。我们通过
[`output_format_arrow_compression_method`](/zh/reference/settings/formats#output_format_arrow_compression_method)
设置禁用 Arrow 输出的压缩，
以便消费者在收到批次时可以直接对其进行解码。
`ArrowStream` 输出是原始二进制数据，因此我们不将其打印到
终端，而是通过管道将其传给消费者。该 stream 是自描述的 (它携带
自己的 schema) ，因此这里我们将它直接通过管道传给
[`clickhouse-local`](/zh/concepts/features/tools-and-utilities/clickhouse-local)，后者使用
`--input-format ArrowStream` 读取传入批次，并将其作为一张表进行查询。
`forex` 表很大，因此我们用 `WHERE`
谓词和 `LIMIT` 对远程查询加以限制，以使此示例保持简洁：
```bash theme={null}
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"
```
```response title="Response" theme={null}
┌─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 库](https://arrow.apache.org/docs/js/)，
`RecordBatchReader` 会在每个记录批次从
服务器流式传输过来后立即返回该批次：
```js theme={null}
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](https://perspective.finos.org/) 实现的实时可视化，请参阅
这篇博客文章
[使用 ClickHouse、Apache Arrow 和 Perspective 实现实时流式可视化](https://clickhouse.com/blog/streaming-real-time-visualizations-clickhouse-apache-arrow-perpsective).
## 格式设置
`ArrowStream` 与 [`Arrow`](/zh/reference/formats/Arrow/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` | 将无法转换的类型输出为原始二进制数据。如果为 false，此类类型将引发 UNKNOWN\_TYPE 异常。 | `1` |
| `output_format_arrow_use_64_bit_indexes_for_dictionary` | 在 Arrow 格式中始终对字典索引使用 64 比特整数 | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | 在 Arrow 格式中对字典索引使用有符号整数 | `1` |