> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Документация по формату ArrowStream
# ArrowStream
| Вход | Выход | Псевдоним |
| ---- | ----- | --------- |
| ✔ | ✔ | |
## Описание
`ArrowStream` — это формат Apache Arrow, работающий в «потоковом режиме». Он предназначен для обработки потоковых данных в памяти.
## Пример использования
В примере ниже мы используем набор данных `forex`, доступный в
[Песочнице ClickHouse](https://sql.clickhouse.com). К нему можно подключиться
удалённо с помощью `clickhouse-client`, используя хост `sql-clickhouse.clickhouse.com`
и пользователя `demo` (без пароля). Таблица `forex` находится в базе данных
`forex`, поэтому мы выбираем её в качестве базы данных по умолчанию:
```bash theme={null}
clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex
```
Таблица `forex` хранит курсы валют. Мы можем оценить её размер и
степень сжатия на диске, выполнив запрос к [`system.columns`](/ru/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`](/ru/reference/formats/Arrow/Arrow) в режиме "file mode", которому
для чтения нужен результат целиком, `ArrowStream` передаётся как
последовательность батчей записей, которые потребитель может читать по мере их
поступления. Благодаря этому он хорошо подходит для стриминга результата запроса напрямую в
инструмент визуализации или аналитики без предварительной материализации всего набора данных.
Чтобы передавать результат потоком, отправьте запрос через HTTP-интерфейс ClickHouse с
помощью запроса `POST` и считывайте ответ как поток Arrow. Мы отключаем сжатие
вывода Arrow с помощью настройки
[`output_format_arrow_compression_method`](/ru/reference/settings/formats#output_format_arrow_compression_method),
чтобы потребители могли декодировать батчи напрямую по мере получения.
Вывод `ArrowStream` представляет собой необработанные двоичные данные, поэтому вместо вывода в
терминал мы направляем его в потребитель. Поток является самоописывающимся (он содержит
собственную схему), поэтому здесь мы направляем его напрямую в
[`clickhouse-local`](/ru/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` возвращает каждый батч записей сразу после его получения от
server:
```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);
}
```
Полное пошаговое руководство по потоковой передаче данных `ArrowStream` из ClickHouse в
визуализацию в реальном времени с [Perspective](https://perspective.finos.org/) см. в
записи блога
[Потоковая визуализация в реальном времени с ClickHouse, Apache Arrow и Perspective](https://clickhouse.com/blog/streaming-real-time-visualizations-clickhouse-apache-arrow-perpsective).
## Настройки формата
`ArrowStream` использует те же настройки формата, что и [`Arrow`](/ru/reference/formats/Arrow/Arrow).
| Setting | Description | Default |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `input_format_arrow_allow_missing_columns` | Разрешить отсутствие столбцов при чтении входных форматов Arrow | `1` |
| `input_format_arrow_case_insensitive_column_matching` | Игнорировать регистр при сопоставлении столбцов Arrow со столбцами ClickHouse | `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. Поддерживаемые кодеки: 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` | Использовать тип Arrow FIXED\_SIZE\_BINARY вместо Binary для столбцов FixedString | `1` |
| `output_format_arrow_low_cardinality_as_dictionary` | Включить вывод типа LowCardinality как типа Arrow Dictionary | `0` |
| `output_format_arrow_string_as_string` | Использовать тип Arrow String вместо Binary для столбцов String | `1` |
| `output_format_arrow_unsupported_types_as_binary` | Выводить типы, для которых нет преобразования, как необработанные бинарные данные. Если false, такие типы вызовут исключение UNKNOWN\_TYPE. | `1` |
| `output_format_arrow_use_64_bit_indexes_for_dictionary` | Всегда использовать 64-битные целые числа для индексов словаря в формате Arrow | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | Использовать целые числа со знаком для индексов словаря в формате Arrow | `1` |