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

> Arrow 格式文档

# Arrow

| 输入 | 输出 | 别名 |
| - | - | - |
| ✔ | ✔ | |

## 说明

[Apache Arrow](https://arrow.apache.org/) 提供两种内置的列式存储格式。
ClickHouse 支持对这些格式进行读写。
`Arrow` 是 Apache Arrow 的“文件模式”格式，专为内存中的随机访问而设计。

## 数据类型匹配

下表列出了支持的数据类型，以及它们在 `INSERT` 和 `SELECT` 查询中与 ClickHouse [数据类型](/zh/reference/data-types/index) 的对应关系。

| Arrow 数据类型 (`INSERT`) | ClickHouse 数据类型 | Arrow 数据类型 (`SELECT`) |
| - | - | - |
| `BOOL` | [Bool](/zh/reference/data-types/boolean) | `BOOL` |
| `UINT8`, `BOOL` | [UInt8](/zh/reference/data-types/int-uint) | `UINT8` |
| `INT8` | [Int8](/zh/reference/data-types/int-uint)/[Enum8](/zh/reference/data-types/enum) | `INT8` |
| `UINT16` | [UInt16](/zh/reference/data-types/int-uint) | `UINT16` |
| `INT16` | [Int16](/zh/reference/data-types/int-uint)/[Enum16](/zh/reference/data-types/enum) | `INT16` |
| `UINT32` | [UInt32](/zh/reference/data-types/int-uint) | `UINT32` |
| `INT32` | [Int32](/zh/reference/data-types/int-uint) | `INT32` |
| `UINT64` | [UInt64](/zh/reference/data-types/int-uint) | `UINT64` |
| `INT64` | [Int64](/zh/reference/data-types/int-uint) | `INT64` |
| `FLOAT`, `HALF_FLOAT` | [Float32](/zh/reference/data-types/float) | `FLOAT32` |
| `DOUBLE` | [Float64](/zh/reference/data-types/float) | `FLOAT64` |
| `DATE32` | [Date32](/zh/reference/data-types/date32) | `UINT16` |
| `DATE64` | [DateTime](/zh/reference/data-types/datetime) | `UINT32` |
| `TIMESTAMP` | [DateTime64](/zh/reference/data-types/datetime64) | `TIMESTAMP` |
| `TIME32`, `TIME64` | [Time64](/zh/reference/data-types/time64) | `TIME32`, `TIME64` |
| `STRING`, `BINARY` | [String](/zh/reference/data-types/string) | `BINARY` |
| `STRING`, `BINARY`, `FIXED_SIZE_BINARY` | [FixedString](/zh/reference/data-types/fixedstring) | `FIXED_SIZE_BINARY` |
| `DECIMAL` | [Decimal](/zh/reference/data-types/decimal) | `DECIMAL` |
| `DECIMAL256` | [Decimal256](/zh/reference/data-types/decimal) | `DECIMAL256` |
| `LIST` | [Array](/zh/reference/data-types/array) | `LIST` |
| `STRUCT` | [Tuple](/zh/reference/data-types/tuple) | `STRUCT` |
| `MAP` | [Map](/zh/reference/data-types/map) | `MAP` |
| `UINT32` | [IPv4](/zh/reference/data-types/ipv4) | `UINT32` |
| `FIXED_SIZE_BINARY`, `BINARY` | [IPv6](/zh/reference/data-types/ipv6) | `FIXED_SIZE_BINARY` |
| `FIXED_SIZE_BINARY`, `BINARY` | [Int128/UInt128/Int256/UInt256](/zh/reference/data-types/int-uint) | `FIXED_SIZE_BINARY` |
| `DURATION` | [Interval](/zh/reference/data-types/special-data-types/interval) (Nanosecond/Microsecond/Millisecond/Second) | `DURATION` |
| `INT64` | [Interval](/zh/reference/data-types/special-data-types/interval) (Minute/Hour/Day/Week/Month/Quarter/Year) | `INT64` |

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

`DICTIONARY` 类型支持用于 `INSERT` 查询；对于 `SELECT` 查询，则提供了 [`output_format_arrow_low_cardinality_as_dictionary`](/zh/reference/settings/formats/output-format#output_format_arrow_low_cardinality_as_dictionary) 设置，可将 [LowCardinality](/zh/reference/data-types/lowcardinality) 类型输出为 `DICTIONARY` 类型。请注意，`LowCardinality` 字典中可能包含未使用的值，这可能导致输出的 Arrow `DICTIONARY` 中也出现未使用的值。

不支持的 Arrow 数据类型：

* `JSON`
* `ENUM`.

ClickHouse 表列的数据类型不必与对应的 Arrow 数据字段完全一致。插入数据时，ClickHouse 会先根据上表解释数据类型，然后再将数据[转换](/zh/reference/functions/regular-functions/type-conversion-functions#CAST)为 ClickHouse 表列设置的数据类型。

## 示例用法

在下面的示例中，我们使用 [ClickHouse SQL playground](https://sql.clickhouse.com) 提供的 `forex` 数据集。

### 选择数据

我们从 Playground 中选取一天的 `EUR/USD` 汇率数据，并将其保存到本地
`forex_eurusd.arrow` 文件中。我们通过 HTTP 接口查询 Playground，
其中 host 为 `sql-clickhouse.clickhouse.com`，user 为
`demo` (无需密码) ：

```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 = '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`](/zh/concepts/features/tools-and-utilities/clickhouse-local) 和
[`file`](/zh/reference/functions/table-functions/file) 表函数读取本地 Arrow 文件。该文件是
自描述的，因此 `Arrow` 格式会自动推断 schema：

```bash theme={null}
clickhouse-local --query "
    SELECT *
    FROM file('forex_eurusd.arrow', Arrow)
    ORDER BY last_update ASC
    LIMIT 5
    FORMAT PrettyCompact"
```

```response title="Response" theme={null}
   ┌─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` 导入：

```bash theme={null}
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_record_batch_size` | 合并小块时每个 record batch 的目标行数。缓冲可能增加内存占用，并使第一个批次延迟到查询结束后才输出。`0` 表示禁用行数目标。 | `0` |
| `output_format_arrow_record_batch_size_bytes` | 每个 record batch 累积块数据的目标字节数。缓冲可能增加内存占用，并使第一个批次延迟到查询结束后才输出。`0` 表示禁用字节数目标。 | `0` |
| `output_format_arrow_string_as_string` | 对 String 列使用 Arrow String 类型，而不是 Binary 类型 | `1` |
| `output_format_arrow_unsupported_types` | 对于没有对应 Arrow 等价类型的类型 (例如 `JSON`、`Dynamic`、`QBit`、`AggregateFunction`) 写出何种内容：`throw`、`text` (每行一个 `serializeText` 值，使用 `String` 列所对应的 Arrow 类型) 或 `binary` (每行一个 `serializeBinary` 值，以 Arrow `Binary` 表示)。在 `text` 模式下 `AggregateFunction` 同样为 `Binary`，因为其文本形式即为原始 aggregate state。 | `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` | 在 Arrow 格式中始终对字典索引使用 64 位整数 | `0` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | 在 Arrow 格式中对字典索引使用有符号整数 | `1` |