> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ArrowStream フォーマットに関するドキュメント

# ArrowStream

| 入力 | 出力 | 別名 |
| - | - | - |
| ✔ | ✔ | |

<h2 id="description">
  説明
</h2>

`ArrowStream` は、Apache Arrow の「ストリームモード」フォーマットです。メモリ内でのストリーム処理向けに設計されています。

<h2 id="example-usage">
  使用例
</h2>

以下の例では、[ClickHouse SQL playground](https://sql.clickhouse.com) で利用できる `forex` データセットを使用します。`clickhouse-client` を使用すると、host に `sql-clickhouse.clickhouse.com`、user に `demo` (password なし) を指定してリモート接続できます。`forex` table は `forex` database にあるため、デフォルトの database としてそれを選択します。

```bash theme={null}
clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex
```

`forex` テーブルには為替レートが保存されています。そのサイズや、
[`system.columns`](/ja/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`](/ja/reference/formats/Arrow/Arrow) の "file mode" フォーマットは、読み取る前に結果全体が揃っている必要がありますが、`ArrowStream` は到着した順にコンシューマーが
順次読み取れるレコードバッチ列として配信されます。これにより、クエリ結果全体を先に
マテリアライズすることなく、可視化ツールや分析ツールへ直接ストリーミングする用途に
適しています。

結果をストリーミングするには、ClickHouse の HTTPインターフェイス経由でクエリを
`POST` リクエストとして送信し、レスポンスを Arrow ストリームとして読み取ります。Arrow 出力の
圧縮は
[`output_format_arrow_compression_method`](/ja/reference/settings/formats/output-format#output_format_arrow_compression_method)
設定で無効にしています。これにより、コンシューマーは受信した
バッチを受信しながらそのままデコードできます。

`ArrowStream` の出力は生のバイナリなので、
ターミナルに表示する代わりにコンシューマーにパイプします。このストリームは自己記述的で (自身の
スキーマを持っています) 、ここではそのまま
[`clickhouse-local`](/ja/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 library](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)
を参照してください。

<h2 id="format-settings">
  フォーマット設定
</h2>

`ArrowStream` は [`Arrow`](/ja/reference/formats/Arrow/Arrow) フォーマットと同じフォーマット設定を使用します。

| 設定 | 説明 | デフォルト |
| - | - | - |
| `input_format_arrow_allow_missing_columns` | Arrow 入力フォーマットの読み取り時に、欠落しているカラムを許可します | `1` |
| `input_format_arrow_case_insensitive_column_matching` | Arrow のカラムと CH columns の照合時に、大文字と小文字を区別しません。 | `0` |
| `input_format_arrow_import_nested` | 廃止された設定です。何も行いません。 | `0` |
| `input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference` | Arrow フォーマットのスキーマ推論時に、サポートされていない型のカラムをスキップします | `0` |
| `output_format_arrow_compression_method` | Arrow 出力フォーマットの圧縮方式です。サポートされる codecs: lz4\_frame, zstd, none (非圧縮) | `lz4_frame` |
| `output_format_arrow_date_as_uint16` | Date の値を 32 ビットの Arrow DATE32 型に変換して書き込む (読み戻すと Date32) のではなく、通常の 16 ビット数値として書き込みます (読み戻すと UInt16) 。 | `0` |
| `output_format_arrow_fixed_string_as_fixed_byte_array` | FixedString カラムでは、Binary の代わりに Arrow FIXED\_SIZE\_BINARY 型を使用します。 | `1` |
| `output_format_arrow_low_cardinality_as_dictionary` | LowCardinality 型を Dictionary Arrow 型として出力します | `0` |
| `output_format_arrow_record_batch_size` | 小さな block をまとめる際の、レコードバッチ あたりの目標行数です。バッファリングによりメモリ使用量が増加し、クエリが完了するまで最初の batch が遅延する可能性があります。`0` を指定すると行数の目標は無効になります。 | `0` |
| `output_format_arrow_record_batch_size_bytes` | レコードバッチ あたりに蓄積する block データの目標バイト数です。バッファリングによりメモリ使用量が増加し、クエリが完了するまで最初の batch が遅延する可能性があります。`0` を指定するとバイト数の目標は無効になります。 | `0` |
| `output_format_arrow_string_as_string` | String 型のカラムでは、Binary の代わりに Arrow String type を使用します | `1` |
| `output_format_arrow_unsupported_types` | Arrow に対応する型がない型 (例: `JSON`、`Dynamic`、`QBit`、`AggregateFunction`) の書き込み方法を指定します: `throw`、`text` (行ごとに 1 つの `serializeText` の値を、`String` カラムが使用する Arrow 型で書き込みます) 、`binary` (行ごとに 1 つの `serializeBinary` の値を Arrow `Binary` として書き込みます) 。`AggregateFunction` はテキスト形式が生の aggregate state であるため、`text` モードでも `Binary` になります。 | `binary` |
| `output_format_arrow_unsupported_types_as_binary` | `output_format_arrow_unsupported_types` に置き換えられました: `0` は `throw`、`1` は `binary` を意味します。その設定がデフォルトのままの場合にのみ参照されます。 | `1` |
| `output_format_arrow_use_64_bit_indexes_for_dictionary` | Arrow フォーマットの dictionary indexes には常に 64 ビット整数を使用します | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | Arrow フォーマットの dictionary indexes に符号付き整数を使用します | `1` |