> ## 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

| Вход | Выход | Псевдоним |
| - | - | - |
| ✔ | ✔ | |

## Описание

`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#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_record_batch_size` | Целевое количество строк на батч записей при объединении небольших блоков. Буферизация может увеличить потребление памяти и задержать первый батч до завершения запроса. `0` отключает целевое количество строк. | `0` |
| `output_format_arrow_record_batch_size_bytes` | Целевой объём накопленных данных блоков в байтах на батч записей. Буферизация может увеличить потребление памяти и задержать первый батч до завершения запроса. `0` отключает целевой объём в байтах. | `0` |
| `output_format_arrow_string_as_string` | Использовать тип Arrow String вместо Binary для столбцов String | `1` |
| `output_format_arrow_unsupported_types` | Что записывать для типа, у которого нет эквивалента в Arrow (например, `JSON`, `Dynamic`, `QBit`, `AggregateFunction`): `throw`, `text` (одно значение `serializeText` на строку, в том типе Arrow, который использовался бы для столбца `String`) или `binary` (одно значение `serializeBinary` на строку, как Arrow `Binary`). `AggregateFunction` записывается как `Binary` и в режиме `text`, поскольку его текстовая форма — это необработанное агрегатное состояние. | `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` | Всегда использовать 64-битные целые числа для индексов словаря в формате Arrow | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | Использовать целые числа со знаком для индексов словаря в формате Arrow | `1` |