CapnProto 형식

CapnProto 형식은 Protocol Buffers 및 Thrift와 유사하지만 JSON이나 MessagePack과는 다른 바이너리 메시지 형식이에요. CapnProto 메시지는 엄격하게 타입이 지정되고 자체 기술(self-describing) 형식이 아니므로 외부 스키마 설명이 필요합니다.

출처: 문서

본문

Input	Output	Alias
✔	✔

설명 (Description)

CapnProto 형식은 Protocol Buffers 및 Thrift 형식과 유사한 바이너리 메시지 형식이지만, JSON이나 MessagePack과는 다릅니다. CapnProto 메시지는 엄격하게 타입이 지정되고 자체 기술 형식이 아니므로 외부 스키마 설명이 필요합니다. 스키마는 쿼리마다 즉시 적용되고 캐시됩니다.

Format Schema도 참조하세요.

데이터 타입 매칭 (Data types matching)

아래 표는 지원되는 데이터 타입과 INSERT, SELECT 쿼리에서 ClickHouse 데이터 타입과 어떻게 일치하는지 보여줍니다.

CapnProto data type ( INSERT )	ClickHouse data type	CapnProto data type ( SELECT )
UINT8 , BOOL	UInt8	UINT8
INT8	Int8	INT8
UINT16	UInt16 , Date	UINT16
INT16	Int16	INT16
UINT32	UInt32 , DateTime	UINT32
INT32	Int32 , Decimal32	INT32
UINT64	UInt64	UINT64
INT64	Int64 , DateTime64 , Decimal64	INT64
FLOAT32	Float32	FLOAT32
FLOAT64	Float64	FLOAT64
TEXT, DATA	String , FixedString	TEXT, DATA
union(T, Void), union(Void, T)	Nullable(T)	union(T, Void), union(Void, T)
ENUM	Enum(8/16)	ENUM
LIST	Array	LIST
STRUCT	Tuple	STRUCT
UINT32	IPv4	UINT32
DATA	IPv6	DATA
DATA	Int128/UInt128/Int256/UInt256	DATA
DATA	Decimal128/Decimal256	DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))	Map	STRUCT(entries LIST(STRUCT(key Key, value Value)))

정수 타입은 입력/출력 중에 서로 변환될 수 있어요.
CapnProto 형식에서 Enum을 사용하려면 format_capn_proto_enum_comparising_mode 설정을 사용하세요.
배열은 중첩될 수 있고 인자로 Nullable 타입의 값을 가질 수 있어요. Tuple과 Map 타입도 중첩될 수 있습니다.

사용 예시 (Example usage)

데이터 삽입 및 선택 (Inserting and selecting data)

다음 명령으로 파일의 CapnProto 데이터를 ClickHouse 테이블에 삽입할 수 있어요:

$ cat capnproto_messages.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_schema = 'schema:Message' FORMAT CapnProto"

여기서 schema.capnp는 다음과 같습니다:

struct Message {
  SearchPhrase @0 :Text;
  c @1 :Uint64;
}

다음 명령으로 ClickHouse 테이블에서 데이터를 선택하고 CapnProto 형식의 파일로 저장할 수 있어요:

$ clickhouse-client --query = "SELECT * FROM test.hits FORMAT CapnProto SETTINGS format_schema = 'schema:Message'"

자동 생성 스키마 사용 (Using autogenerated schema)

데이터에 대한 외부 CapnProto 스키마가 없다면 자동 생성된 스키마를 사용하여 CapnProto 형식으로 데이터를 출력/입력할 수 있어요. 예를 들어:

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS format_capn_proto_use_autogenerated_schema=1

이 경우 ClickHouse는 structureToCapnProtoSchema 함수를 사용하여 테이블 구조에 따라 CapnProto 스키마를 자동 생성하고, 이 스키마를 사용하여 데이터를 CapnProto 형식으로 직렬화합니다.

자동 생성된 스키마로 CapnProto 파일을 읽을 수도 있어요(이 경우 파일은 동일한 스키마로 생성되어야 합니다):

$ cat hits.bin | clickhouse-client --query "INSERT INTO test.hits SETTINGS format_capn_proto_use_autogenerated_schema=1 FORMAT CapnProto"

형식 설정 (Format settings)

format_capn_proto_use_autogenerated_schema 설정은 기본적으로 활성화되어 있으며 format_schema가 설정되지 않은 경우 적용됩니다.

입력/출력 중에 output_format_schema 설정을 사용하여 자동 생성된 스키마를 파일로 저장할 수도 있어요. 예를 들어:

SELECT * FROM test.hits 
FORMAT CapnProto 
SETTINGS 
    format_capn_proto_use_autogenerated_schema=1,
    output_format_schema='path/to/schema/schema.capnp'

이 경우 자동 생성된 CapnProto 스키마가 path/to/schema/schema.capnp 파일에 저장됩니다.

CapnProto 형식