Arrow

Arrow 格式文档

输入	输出	别名
✔	✔

​

说明

Apache Arrow 提供两种内置的列式存储格式。 ClickHouse 支持对这些格式进行读写。 Arrow 是 Apache Arrow 的“文件模式”格式，专为内存中的随机访问而设计。

​

数据类型匹配

下表列出了支持的数据类型，以及它们在 INSERT 和 SELECT 查询中与 ClickHouse 数据类型 的对应关系。

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, TIME32, TIME64	DateTime64	TIMESTAMP
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

Array 可以嵌套，其参数也可以是 Nullable 类型的值。Tuple 和 Map 类型同样可以嵌套。

DICTIONARY 类型支持用于 INSERT 查询；对于 SELECT 查询，则提供了 output_format_arrow_low_cardinality_as_dictionary 设置，可将 LowCardinality 类型输出为 DICTIONARY 类型。请注意，LowCardinality 字典中可能包含未使用的值，这可能导致输出的 Arrow DICTIONARY 中也出现未使用的值。

不支持的 Arrow 数据类型：

• FIXED_SIZE_BINARY
• JSON
• UUID
• ENUM。

ClickHouse 表中列的数据类型不必与对应的 Arrow 数据字段完全一致。插入数据时，ClickHouse 会根据上表解释数据类型，然后将数据转换为为 ClickHouse 表中列设置的数据类型。

​

示例用法

在下面的示例中，我们使用 ClickHouse SQL playground 提供的 forex 数据集。

​

选择数据

我们从 Playground 中选取一天的 EUR/USD 汇率数据，并将其保存到本地 forex_eurusd.arrow 文件中。我们通过 HTTP 接口查询 Playground， 其中 host 为 sql-clickhouse.clickhouse.com，user 为 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

​

读取文件内容

现在，我们可以使用 clickhouse-local 和 file 表函数读取本地 Arrow 文件。该文件是 自描述的，因此 Arrow 格式会自动推断 schema：

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─┐
1. │ EUR.USD    │ 2020-01-01 17:00:00.065 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
2. │ EUR.USD    │ 2020-01-01 17:00:10.447 │  1.1212 │ 1.12192 │ 0.0007200241088867188 │
3. │ EUR.USD    │ 2020-01-01 17:00:10.498 │ 1.12117 │ 1.12161 │ 0.0004400014877319336 │
4. │ EUR.USD    │ 2020-01-01 17:00:12.579 │  1.1212 │ 1.12161 │ 0.0004100799560546875 │
5. │ 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 列与 CH 列时忽略大小写。	0
input_format_arrow_import_nested	已废弃，无任何作用。	0
input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference	对 Arrow 格式进行 schema 推断时，跳过类型不受支持的列	0
output_format_arrow_compression_method	Arrow 输出格式的压缩方法。支持的编解码器：lz4_frame、zstd、none (未压缩)	lz4_frame
output_format_arrow_fixed_string_as_fixed_byte_array	对 FixedString 列使用 Arrow FIXED_SIZE_BINARY 类型，而不是 Binary 类型。	1
output_format_arrow_low_cardinality_as_dictionary	启用将 LowCardinality 类型输出为 Arrow 的 字典 类型	0
output_format_arrow_string_as_string	对 String 列使用 Arrow String 类型，而不是 Binary 类型	1
output_format_arrow_use_64_bit_indexes_for_dictionary	在 Arrow 格式中始终对字典索引使用 64 位整数	0
output_format_arrow_use_signed_indexes_for_dictionary	在 Arrow 格式中对字典索引使用有符号整数	1