CapnProto

CapnProto 문서

입력	출력	별칭
✔	✔

​

설명

CapnProto 포맷은 Protocol Buffers 포맷 및 Thrift와 유사한 바이너리 메시지 포맷이지만, JSON이나 MessagePack과는 다릅니다. CapnProto 메시지는 엄격한 타입이 적용되며 자체적으로 구조를 설명하지 않으므로 외부 스키마 설명이 필요합니다. 스키마는 런타임에 적용되며 각 쿼리별로 캐시됩니다.

관련 항목: 포맷 스키마.

​

데이터 타입 매핑

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

CapnProto 데이터 타입 (INSERT)	ClickHouse 데이터 타입	CapnProto 데이터 타입 (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 타입도 중첩할 수 있습니다.

​

사용 예시

​

데이터 삽입 및 조회

다음 명령을 사용하여 파일의 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'"

​

자동 생성 스키마 사용

데이터용 외부 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_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 파일에 저장됩니다.