Arrow

입력	출력	별칭
✔	✔

설명

Apache Arrow에는 두 가지 기본 제공 열 지향 저장 포맷이 있습니다. ClickHouse는 이러한 포맷의 읽기와 쓰기를 지원합니다. Arrow는 Apache Arrow의 “file mode” 형식이며, 메모리 내에서 임의 접근이 가능하도록 설계되었습니다.

데이터 타입 매핑

아래 표는 지원되는 데이터 타입과 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`	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 테이블 컬럼에 설정된 데이터 타입으로 CAST합니다.

사용 예시

아래 예시에서는 ClickHouse SQL playground에서 제공되는 forex 데이터셋을 사용합니다.

데이터 선택

Playground에서 EUR/USD 환율 데이터 1일치를 선택해 로컬 forex_eurusd.arrow 파일에 저장합니다. HTTP 인터페이스를 통해 Playground에 쿼리하며, 이때 host는 sql-clickhouse.clickhouse.com이고 user는 demo입니다(password는 없음):

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─┐
│ 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 테이블에 삽입하려면 FORMAT Arrow와 함께 clickhouse-client로 파이프하여 전달하십시오:

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`
`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`이면 이러한 타입에서 예외가 발생합니다.	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	Arrow 형식에서 딕셔너리 인덱스에 항상 64비트 정수를 사용합니다	`0`
`output_format_arrow_use_signed_indexes_for_dictionary`	Arrow 형식에서 딕셔너리 인덱스에 부호 있는 정수를 사용합니다	`1`

SQL Reference

Data Types

Engines

Functions

Formats

Interfaces

Settings

System Tables

Data Lakes

설명

데이터 타입 매핑

사용 예시

데이터 선택

파일 다시 읽기

데이터 삽입

포맷 설정

​설명

​데이터 타입 매핑

​사용 예시

​데이터 선택

​파일 다시 읽기

​데이터 삽입

​포맷 설정

설명

데이터 타입 매핑

사용 예시

데이터 선택

파일 다시 읽기

데이터 삽입

포맷 설정