Avro 형식

Avro 형식은 Apache Avro의 행 지향 직렬화 형식으로, 효율적인 데이터 처리를 위해 바이너리 인코딩을 사용해요. ClickHouse는 Avro 데이터 파일의 읽기와 쓰기를 모두 지원하며, 임베디드 스키마를 가진 자체 기술(self-describing) 메시지를 기대합니다. 스키마 레지스트리를 사용한다면 AvroConfluent 형식을 참조하세요.

출처: 문서

본문

Input	Output	Alias
✔	✔

설명 (Description)

Apache Avro는 효율적인 데이터 처리를 위해 바이너리 인코딩을 사용하는 행 지향 직렬화 형식입니다. Avro 형식은 Avro 데이터 파일의 읽기와 쓰기를 지원합니다. 이 형식은 임베디드 스키마가 있는 자체 기술(self-describing) 메시지를 기대합니다. 스키마 레지스트리와 함께 Avro를 사용한다면 AvroConfluent 형식을 참조하세요.

데이터 타입 매핑 (Data type mapping)

아래 표는 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 or 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인지 알 수 없으므로, 항상 null 타입을 Avro union 타입 집합에 포함해야 합니다.

*** Avro 논리 타입(logical types)

지원되지 않는 Avro 논리 데이터 타입:

time-millis
time-micros
duration

형식 설정 (Format settings)

Setting	Description	Default
input_format_avro_allow_missing_fields	스키마에서 필드를 찾을 수 없을 때 오류를 던지는 대신 기본값을 사용할지 여부.	0
input_format_avro_null_as_default	null 값을 허용하지 않는 컬럼에 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 타입 매핑을 위해 String 컬럼을 식별하는 정규식. 기본적으로 ClickHouse String 컬럼은 Avro bytes 타입으로 기록됩니다.
output_format_avro_rows_in_file	Avro 출력 파일당 최대 행 수. 이 제한에 도달하면 새 파일이 생성됩니다(스토리지 시스템이 파일 분할을 지원하는 경우).	1

예시 (Examples)

Avro 데이터 읽기 (Reading Avro data)

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 데이터 쓰기 (Writing Avro data)

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 스키마 추론 (Inferring the Avro schema)

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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Avro 형식

Avro 형식

본문

설명 (Description)

데이터 타입 매핑 (Data type mapping)

형식 설정 (Format settings)

예시 (Examples)

Avro 데이터 읽기 (Reading Avro data)

Avro 데이터 쓰기 (Writing Avro data)

Avro 스키마 추론 (Inferring the Avro schema)

더 알아보기 (Learn more)