ArrowStream

Документация по формату ArrowStream

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

​

Описание

ArrowStream — это формат Apache Arrow, работающий в «потоковом режиме». Он предназначен для обработки потоковых данных в памяти.

​

Пример использования

В примере ниже мы используем набор данных forex, доступный в Песочнице ClickHouse. К нему можно подключиться удалённо с помощью clickhouse-client, используя хост sql-clickhouse.clickhouse.com и пользователя demo (без пароля). Таблица forex находится в базе данных forex, поэтому мы выбираем её в качестве базы данных по умолчанию:

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

Таблица forex хранит курсы валют. Мы можем оценить её размер и степень сжатия на диске, выполнив запрос к system.columns:

Query

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

   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

В отличие от формата Arrow в режиме “file mode”, которому для чтения нужен результат целиком, ArrowStream передаётся как последовательность батчей записей, которые потребитель может читать по мере их поступления. Благодаря этому он хорошо подходит для стриминга результата запроса напрямую в инструмент визуализации или аналитики без предварительной материализации всего набора данных.

Чтобы передавать результат потоком, отправьте запрос через HTTP-интерфейс ClickHouse с помощью запроса POST и считывайте ответ как поток Arrow. Мы отключаем сжатие вывода Arrow с помощью настройки output_format_arrow_compression_method, чтобы потребители могли декодировать батчи напрямую по мере получения.

Вывод ArrowStream представляет собой необработанные двоичные данные, поэтому вместо вывода в терминал мы направляем его в потребитель. Поток является самоописывающимся (он содержит собственную схему), поэтому здесь мы направляем его напрямую в 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"

Response

   ┌─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 возвращает каждый батч записей сразу после его получения от server:

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 см. в записи блога Потоковая визуализация в реальном времени с 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 со столбцами 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