CapnProto

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

관련 항목: 포맷 스키마.

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

• 정수 타입은 입출력 시 서로 변환할 수 있습니다.
• 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 파일에 저장됩니다.