> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/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의 "file mode" 형식이며, 메모리 내에서 임의 접근이 가능하도록 설계되었습니다.
## 데이터 타입 매핑
아래 표는 지원되는 데이터 타입과 `INSERT` 및 `SELECT` 쿼리에서 해당 타입이 ClickHouse [데이터 타입](/docs/ko/reference/data-types/index)에 어떻게 매핑되는지를 보여줍니다.
| Arrow 데이터 타입 (`INSERT`) | ClickHouse 데이터 타입 | Arrow 데이터 타입 (`SELECT`) |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------- |
| `BOOL` | [Bool](/docs/ko/reference/data-types/boolean) | `BOOL` |
| `UINT8`, `BOOL` | [UInt8](/docs/ko/reference/data-types/int-uint) | `UINT8` |
| `INT8` | [Int8](/docs/ko/reference/data-types/int-uint)/[Enum8](/docs/ko/reference/data-types/enum) | `INT8` |
| `UINT16` | [UInt16](/docs/ko/reference/data-types/int-uint) | `UINT16` |
| `INT16` | [Int16](/docs/ko/reference/data-types/int-uint)/[Enum16](/docs/ko/reference/data-types/enum) | `INT16` |
| `UINT32` | [UInt32](/docs/ko/reference/data-types/int-uint) | `UINT32` |
| `INT32` | [Int32](/docs/ko/reference/data-types/int-uint) | `INT32` |
| `UINT64` | [UInt64](/docs/ko/reference/data-types/int-uint) | `UINT64` |
| `INT64` | [Int64](/docs/ko/reference/data-types/int-uint) | `INT64` |
| `FLOAT`, `HALF_FLOAT` | [Float32](/docs/ko/reference/data-types/float) | `FLOAT32` |
| `DOUBLE` | [Float64](/docs/ko/reference/data-types/float) | `FLOAT64` |
| `DATE32` | [Date32](/docs/ko/reference/data-types/date32) | `UINT16` |
| `DATE64` | [DateTime](/docs/ko/reference/data-types/datetime) | `UINT32` |
| `TIMESTAMP` | [DateTime64](/docs/ko/reference/data-types/datetime64) | `TIMESTAMP` |
| `TIME32`, `TIME64` | [Time64](/docs/ko/reference/data-types/time64) | `TIME32`, `TIME64` |
| `STRING`, `BINARY` | [String](/docs/ko/reference/data-types/string) | `BINARY` |
| `STRING`, `BINARY`, `FIXED_SIZE_BINARY` | [FixedString](/docs/ko/reference/data-types/fixedstring) | `FIXED_SIZE_BINARY` |
| `DECIMAL` | [Decimal](/docs/ko/reference/data-types/decimal) | `DECIMAL` |
| `DECIMAL256` | [Decimal256](/docs/ko/reference/data-types/decimal) | `DECIMAL256` |
| `LIST` | [Array](/docs/ko/reference/data-types/array) | `LIST` |
| `STRUCT` | [Tuple](/docs/ko/reference/data-types/tuple) | `STRUCT` |
| `MAP` | [Map](/docs/ko/reference/data-types/map) | `MAP` |
| `UINT32` | [IPv4](/docs/ko/reference/data-types/ipv4) | `UINT32` |
| `FIXED_SIZE_BINARY`, `BINARY` | [IPv6](/docs/ko/reference/data-types/ipv6) | `FIXED_SIZE_BINARY` |
| `FIXED_SIZE_BINARY`, `BINARY` | [Int128/UInt128/Int256/UInt256](/docs/ko/reference/data-types/int-uint) | `FIXED_SIZE_BINARY` |
| `DURATION` | [Interval](/docs/ko/reference/data-types/special-data-types/interval) (Nanosecond/Microsecond/Millisecond/Second) | `DURATION` |
| `INT64` | [Interval](/docs/ko/reference/data-types/special-data-types/interval) (Minute/Hour/Day/Week/Month/Quarter/Year) | `INT64` |
배열은 중첩될 수 있으며, 인수로 `Nullable` 타입을 사용할 수도 있습니다. `Tuple` 및 `Map` 타입도 중첩할 수 있습니다.
`DICTIONARY` 타입은 `INSERT` 쿼리에서 지원됩니다. 또한 `SELECT` 쿼리에서는 [`output_format_arrow_low_cardinality_as_dictionary`](/docs/ko/reference/settings/formats#output_format_arrow_low_cardinality_as_dictionary) 설정을 사용해 [LowCardinality](/docs/ko/reference/data-types/lowcardinality) 타입을 `DICTIONARY` 타입으로 출력할 수 있습니다. `LowCardinality` 딕셔너리에는 사용되지 않는 값이 포함될 수 있으므로, 출력된 Arrow `DICTIONARY`에도 사용되지 않는 값이 포함될 수 있다는 점에 유의하십시오.
지원되지 않는 Arrow 데이터 타입:
* `JSON`
* `ENUM`.
ClickHouse 테이블 컬럼의 데이터 타입은 해당 Arrow 데이터 필드와 일치할 필요가 없습니다. 데이터를 삽입할 때 ClickHouse는 먼저 위 표에 따라 데이터 타입을 해석한 다음, 데이터를 ClickHouse 테이블 컬럼에 설정된 데이터 타입으로 [CAST](/docs/ko/reference/functions/regular-functions/type-conversion-functions#CAST)합니다.
## 사용 예시
아래 예시에서는 [ClickHouse SQL playground](https://sql.clickhouse.com)에서 제공되는 `forex` 데이터셋을 사용합니다.
### 데이터 선택
Playground에서 `EUR/USD` 환율 데이터 1일치를 선택해 로컬 `forex_eurusd.arrow` 파일에 저장합니다. HTTP
인터페이스를 통해 Playground에 쿼리하며, 이때 host는 `sql-clickhouse.clickhouse.com`이고 user는
`demo`입니다(`password`는 없음):
```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`](/docs/ko/concepts/features/tools-and-utilities/clickhouse-local)과
[`file`](/docs/ko/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 테이블에 삽입하려면 `FORMAT Arrow`와 함께 `clickhouse-client`로 파이프하여 전달하십시오:
```bash theme={null}
cat forex_eurusd.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"
```
## 포맷 설정
| Setting | Description | Default |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `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 형식의 스키마 추론 중 지원되지 않는 타입의 컬럼을 건너뜁니다 | `0` |
| `input_format_arrow_use_native_reader` | Apache Arrow 라이브러리 대신 `Arrow` 및 `ArrowStream` 포맷에 ClickHouse 네이티브 reader를 사용합니다. Apache Arrow 라이브러리 reader를 사용하려면 `0`으로 설정합니다. | `1` |
| `output_format_arrow_compression_method` | Arrow 출력 형식에 사용할 압축 방식입니다. 지원되는 코덱: lz4\_frame, zstd, none(비압축) | `lz4_frame` |
| `output_format_arrow_fixed_string_as_fixed_byte_array` | FixedString 컬럼에 Binary 대신 Arrow FIXED\_SIZE\_BINARY 타입을 사용합니다. | `1` |
| `output_format_arrow_low_cardinality_as_dictionary` | LowCardinality 타입을 딕셔너리 Arrow 타입으로 출력하도록 설정합니다 | `0` |
| `output_format_arrow_string_as_string` | String 컬럼에 Binary 대신 Arrow String 타입을 사용합니다 | `1` |
| `output_format_arrow_unsupported_types_as_binary` | Arrow에 해당하는 타입이 없는 경우(예: `BFloat16`, `AggregateFunction`) 원시 바이너리 데이터로 출력합니다. `false`이면 이러한 타입에서 예외가 발생합니다. ClickHouse 네이티브 writer와 Apache Arrow 라이브러리 writer 모두에 적용됩니다. | `1` |
| `output_format_arrow_use_64_bit_indexes_for_dictionary` | Arrow 형식에서 딕셔너리 인덱스에 항상 64비트 정수를 사용합니다 | `0` |
| `output_format_arrow_use_native_writer` | Apache Arrow 라이브러리 대신 `Arrow` 및 `ArrowStream` 포맷에 ClickHouse 네이티브 writer를 사용합니다. Apache Arrow 라이브러리 writer를 사용하려면 `0`으로 설정합니다. | `1` |
| `output_format_arrow_use_signed_indexes_for_dictionary` | Arrow 형식에서 딕셔너리 인덱스에 부호 있는 정수를 사용합니다 | `1` |