CapnProto - ClickHouse Documentation

입력	출력	별칭
✔	✔

설명

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 파일에 저장됩니다.

​설명

​데이터 타입 매핑

​사용 예시

​데이터 삽입 및 조회

​자동 생성 스키마 사용

​포맷 설정

설명

데이터 타입 매핑

사용 예시

데이터 삽입 및 조회

자동 생성 스키마 사용

포맷 설정