Arrow - ClickHouse Documentation

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

Описание

Apache Arrow включает два встроенных формата столбцового хранения. ClickHouse поддерживает чтение и запись в этих форматах. Arrow — это формат Apache Arrow в «файловом режиме», предназначенный для произвольного доступа к данным в памяти.

Соответствие типов данных

В таблице ниже показаны поддерживаемые типы данных и их соответствие типам данных ClickHouse в запросах INSERT и SELECT.

Тип данных Arrow (`INSERT`)	Тип данных ClickHouse	Тип данных Arrow (`SELECT`)
`BOOL`	Bool	`BOOL`
`UINT8`, `BOOL`	UInt8	`UINT8`
`INT8`	Int8/Enum8	`INT8`
`UINT16`	UInt16	`UINT16`
`INT16`	Int16/Enum16	`INT16`
`UINT32`	UInt32	`UINT32`
`INT32`	Int32	`INT32`
`UINT64`	UInt64	`UINT64`
`INT64`	Int64	`INT64`
`FLOAT`, `HALF_FLOAT`	Float32	`FLOAT32`
`DOUBLE`	Float64	`FLOAT64`
`DATE32`	Date32	`UINT16`
`DATE64`	DateTime	`UINT32`
`TIMESTAMP`	DateTime64	`TIMESTAMP`
`TIME32`, `TIME64`	Time64	`TIME32`, `TIME64`
`STRING`, `BINARY`	String	`BINARY`
`STRING`, `BINARY`, `FIXED_SIZE_BINARY`	FixedString	`FIXED_SIZE_BINARY`
`DECIMAL`	Decimal	`DECIMAL`
`DECIMAL256`	Decimal256	`DECIMAL256`
`LIST`	Array	`LIST`
`STRUCT`	Tuple	`STRUCT`
`MAP`	Map	`MAP`
`UINT32`	IPv4	`UINT32`
`FIXED_SIZE_BINARY`, `BINARY`	IPv6	`FIXED_SIZE_BINARY`
`FIXED_SIZE_BINARY`, `BINARY`	Int128/UInt128/Int256/UInt256	`FIXED_SIZE_BINARY`
`DURATION`	Interval (Nanosecond/Microsecond/Millisecond/Second)	`DURATION`
`INT64`	Interval (Minute/Hour/Day/Week/Month/Quarter/Year)	`INT64`

Массивы могут быть вложенными и могут иметь тип Nullable в качестве аргумента. Типы Tuple и Map также могут быть вложенными. Тип DICTIONARY поддерживается в запросах INSERT, а для запросов SELECT есть настройка output_format_arrow_low_cardinality_as_dictionary, которая позволяет выводить тип LowCardinality как тип DICTIONARY. Обратите внимание, что в словаре LowCardinality могут быть неиспользуемые значения, из-за чего при выводе в Arrow DICTIONARY тоже могут появляться неиспользуемые значения. Неподдерживаемые типы данных Arrow:

JSON
ENUM.

Типы данных столбцов таблицы ClickHouse не обязаны совпадать с типами данных соответствующих полей Arrow. При вставке данных ClickHouse интерпретирует типы данных в соответствии с таблицей выше, а затем приводит данные к типу данных, заданному для столбца таблицы ClickHouse.

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

В примере ниже используется набор данных forex, доступный в Песочнице ClickHouse.

Выборка данных

Мы выбираем курсы EUR/USD за один день из Песочницы ClickHouse и сохраняем их в локальный файл forex_eurusd.arrow. Мы отправляем запрос к песочнице через HTTP- интерфейс, где хост — sql-clickhouse.clickhouse.com, а пользователь — demo (без пароля):

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 = 'EUR' AND quote = 'USD'
            AND datetime >= '2020-01-01' AND datetime < '2020-01-02'
        ORDER BY datetime ASC
        FORMAT Arrow
        SETTINGS output_format_arrow_compression_method='zstd'" > forex_eurusd.arrow

Чтение файла

Теперь мы можем прочитать локальный файл Arrow с помощью clickhouse-local, используя табличную функцию file. Файл самоописывающийся, поэтому формат Arrow автоматически определяет схему:

clickhouse-local --query "
    SELECT *
    FROM file('forex_eurusd.arrow', Arrow)
    ORDER BY last_update ASC
    LIMIT 5
    FORMAT PrettyCompact"

Response

   ┌─base_quote─┬─────────────last_update─┬─────bid─┬─────ask─┬────────────────spread─┐
│ EUR.USD    │ 2020-01-01 17:00:00.065 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
│ EUR.USD    │ 2020-01-01 17:00:10.447 │  1.1212 │ 1.12192 │ 0.0007200241088867188 │
│ EUR.USD    │ 2020-01-01 17:00:10.498 │ 1.12117 │ 1.12161 │ 0.0004400014877319336 │
│ EUR.USD    │ 2020-01-01 17:00:12.579 │  1.1212 │ 1.12161 │ 0.0004100799560546875 │
│ EUR.USD    │ 2020-01-01 17:00:12.630 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
   └────────────┴─────────────────────────┴─────────┴─────────┴───────────────────────┘

Вставка данных

Чтобы загрузить файл Arrow в таблицу ClickHouse, передайте его в clickhouse-client, указав FORMAT Arrow:

cat forex_eurusd.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"

Настройки формата

Настройка	Описание	По умолчанию
`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`
`input_format_arrow_use_native_reader`	Использовать встроенное средство чтения ClickHouse для форматов `Arrow` и `ArrowStream` вместо библиотеки Apache Arrow. Установите `0`, чтобы использовать средство чтения из библиотеки Apache Arrow.	`1`
`output_format_arrow_compression_method`	Метод сжатия для выходного формата Arrow. Поддерживаемые кодеки: lz4_frame, zstd, none (без сжатия)	`lz4_frame`
`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`	Выводить типы, у которых нет эквивалента в Arrow (например, `BFloat16`, `AggregateFunction`), как необработанные бинарные данные. Если `false`, такой тип вызывает исключение. Применяется как к встроенному средству записи, так и к средству записи из библиотеки Apache Arrow.	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	Всегда использовать 64-битные целые числа для индексов словаря в формате Arrow	`0`
`output_format_arrow_use_native_writer`	Использовать встроенное средство записи ClickHouse для форматов `Arrow` и `ArrowStream` вместо библиотеки Apache Arrow. Установите `0`, чтобы использовать средство записи из библиотеки Apache Arrow.	`1`
`output_format_arrow_use_signed_indexes_for_dictionary`	Использовать знаковые целые числа для индексов словаря в формате Arrow	`1`

​Описание

​Соответствие типов данных

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

​Выборка данных

​Чтение файла

​Вставка данных

​Настройки формата