Avro

입력	출력	별칭
✔	✔

설명

Apache Avro는 효율적인 데이터 처리를 위해 바이너리 인코딩을 사용하는 행 지향 직렬화 포맷입니다. Avro 포맷은 Avro data files의 읽기와 쓰기를 지원합니다. 이 포맷은 스키마가 내장된 자체 기술형 메시지를 사용한다고 가정합니다. 스키마 레지스트리와 함께 Avro를 사용하는 경우 AvroConfluent 포맷을 참고하십시오.

데이터 타입 매핑

아래 표에는 Apache Avro 포맷이 지원하는 모든 데이터 타입과 INSERT 및 SELECT 쿼리에서 각각에 대응하는 ClickHouse 데이터 타입이 나와 있습니다.

Avro data type `INSERT`	ClickHouse data type	Avro data type `SELECT`
`boolean`, `int`, `long`, `float`, `double`	Int(8\16\32), UInt(8\16\32)	`int`
`boolean`, `int`, `long`, `float`, `double`	Int64, UInt64	`long`
`boolean`, `int`, `long`, `float`, `double`	Float32	`float`
`boolean`, `int`, `long`, `float`, `double`	Float64	`double`
`bytes`, `string`, `fixed`, `enum`	String	`bytes` 또는 `string` *
`bytes`, `string`, `fixed`	FixedString(N)	`fixed(N)`
`enum`	Enum(8\16)	`enum`
`array(T)`	Array(T)	`array(T)`
`map(V, K)`	Map(V, K)	`map(string, K)`
`union(null, T)`, `union(T, null)`	Nullable(T)	`union(null, T)`
`union(T1, T2, …)` **	Variant(T1, T2, …)	`union(T1, T2, …)` **
`null`	Nullable(Nothing)	`null`
`int (date)` ***	Date, Date32	`int (date)` ***
`long (timestamp-millis)` ***	DateTime64(3)	`long (timestamp-millis)` ***
`long (timestamp-micros)` ***	DateTime64(6)	`long (timestamp-micros)` ***
`bytes (decimal)` ***	DateTime64(N)	`bytes (decimal)` ***
`int`	IPv4	`int`
`fixed(16)`	IPv6	`fixed(16)`
`bytes (decimal)` ***	Decimal(P, S)	`bytes (decimal)` ***
`string (uuid)` ***	UUID	`string (uuid)` ***
`fixed(16)`	Int128/UInt128	`fixed(16)`
`fixed(32)`	Int256/UInt256	`fixed(32)`
`record`	Tuple	`record`

bytes가 기본값이며, 설정 output_format_avro_string_column_pattern으로 제어됩니다.

** Variant 타입은 필드 값으로 null을 암묵적으로 허용하므로, 예를 들어 Avro union(T1, T2, null)은 Variant(T1, T2)로 변환됩니다. 따라서 ClickHouse에서 Avro를 생성할 때는 스키마 추론 과정에서 실제로 어떤 값이 null인지 알 수 없으므로, Avro union 타입 집합에 항상 null 타입을 포함해야 합니다. *** Avro 논리 타입 지원되지 않는 Avro 논리 데이터 타입:

time-millis
time-micros
duration

포맷 설정

설정	설명	기본값
`input_format_avro_allow_missing_fields`	스키마에서 필드를 찾을 수 없을 때 오류를 발생시키는 대신 기본값을 사용할지 여부입니다.	`0`
`input_format_avro_null_as_default`	`null` 값을 널을 허용하지 않는 컬럼에 삽입할 때 오류를 발생시키는 대신 기본값을 사용할지 여부입니다.	`0`
`output_format_avro_codec`	Avro 출력 파일의 압축 알고리즘입니다. 가능한 값: `null`, `deflate`, `snappy`, `zstd`.
`output_format_avro_sync_interval`	Avro 파일의 동기화 마커 빈도(바이트 단위)입니다.	`16384`
`output_format_avro_string_column_pattern`	Avro 문자열 유형 매핑에 사용할 `String` 컬럼을 식별하는 정규식입니다. 기본적으로 ClickHouse `String` 컬럼은 Avro `bytes` 유형으로 기록됩니다.
`output_format_avro_rows_in_file`	Avro 출력 파일당 최대 행 수입니다. 이 한도에 도달하면 새 파일이 생성됩니다(스토리지 시스템이 파일 분할을 지원하는 경우).	`1`

예시

Avro 데이터 읽기

Avro 파일의 데이터를 ClickHouse 테이블로 가져오려면:

$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"

수집된 Avro 파일의 루트 스키마는 반드시 record 타입이어야 합니다. 테이블 컬럼과 Avro 스키마 필드 간의 대응 관계를 찾기 위해 ClickHouse는 이름을 비교합니다. 이 비교는 대소문자를 구분하며, 사용되지 않는 필드는 건너뜁니다. ClickHouse 테이블 컬럼의 데이터 타입은 삽입되는 Avro 데이터의 해당 필드와 다를 수 있습니다. 데이터를 삽입할 때 ClickHouse는 위 표에 따라 데이터 타입을 해석한 다음, 데이터를 해당 컬럼 타입으로 캐스팅합니다. 데이터를 가져오는 중 스키마에서 필드를 찾을 수 없고 설정 input_format_avro_allow_missing_fields가 활성화되어 있으면, 오류를 발생시키는 대신 기본값이 사용됩니다.

Avro 파일에 데이터 쓰기

ClickHouse 테이블의 데이터를 Avro 파일에 쓰려면 다음과 같이 하십시오:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro

컬럼 이름은 다음 조건을 충족해야 합니다:

[A-Za-z_]로 시작해야 합니다
뒤에는 [A-Za-z0-9_]만 사용할 수 있습니다

Avro 파일의 출력 압축 및 동기화 인터벌은 각각 output_format_avro_codec 및 output_format_avro_sync_interval 설정으로 구성할 수 있습니다.

Avro 스키마 추론

ClickHouse DESCRIBE 함수를 사용하면 다음 예시처럼 Avro 파일에서 추론된 포맷을 빠르게 확인할 수 있습니다. 이 예시에는 ClickHouse S3 공개 버킷에서 공개적으로 접근할 수 있는 Avro 파일의 URL이 포함되어 있습니다.

DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro', 'Avro');

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

SQL 참고

데이터 타입

엔진

함수

포맷

설정

시스템 테이블

데이터 레이크

설명

데이터 타입 매핑

포맷 설정

예시

Avro 데이터 읽기

Avro 파일에 데이터 쓰기

Avro 스키마 추론

​설명

​데이터 타입 매핑

​포맷 설정

​예시

​Avro 데이터 읽기

​Avro 파일에 데이터 쓰기

​Avro 스키마 추론

설명

데이터 타입 매핑

포맷 설정

예시

Avro 데이터 읽기

Avro 파일에 데이터 쓰기

Avro 스키마 추론