본문으로 바로가기
본문으로 바로가기

CapnProto

Not supported in ClickHouse Cloud
입력출력별칭
✔✔

설명​

CapnProto 포맷은 Protocol Buffers 포맷 및 Thrift와 유사한 이진 메시지 포맷이며, JSON이나 MessagePack과는 다릅니다. CapnProto 메시지는 엄격하게 타입이 지정되어 있으며 자기 기술(self-describing) 방식이 아니므로 외부 스키마 정의가 필요합니다. 이 스키마는 실행 시점에 동적으로 적용되며 각 쿼리마다 캐시됩니다.

Format Schema도 참고하십시오.

CapnProto와 데이터 타입 매칭​

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

CapnProto 데이터 타입 (INSERT)ClickHouse 데이터 타입CapnProto 데이터 타입 (SELECT)
UINT8, BOOLUInt8UINT8
INT8Int8INT8
UINT16UInt16, DateUINT16
INT16Int16INT16
UINT32UInt32, DateTimeUINT32
INT32Int32, Decimal32INT32
UINT64UInt64UINT64
INT64Int64, DateTime64, Decimal64INT64
FLOAT32Float32FLOAT32
FLOAT64Float64FLOAT64
TEXT, DATAString, FixedStringTEXT, DATA
union(T, Void), union(Void, T)Nullable(T)union(T, Void), union(Void, T)
ENUMEnum(8/16)ENUM
LISTArrayLIST
STRUCTTupleSTRUCT
UINT32IPv4UINT32
DATAIPv6DATA
DATAInt128/UInt128/Int256/UInt256DATA
DATADecimal128/Decimal256DATA
STRUCT(entries LIST(STRUCT(key Key, value Value)))MapSTRUCT(entries LIST(STRUCT(key Key, value Value)))
  • 정수 타입은 입력/출력 시 서로 변환될 수 있습니다.
  • CapnProto 포맷에서 Enum을 사용하려면 format_capn_proto_enum_comparising_mode SETTING을 사용하십시오.
  • Array는 중첩될 수 있으며, 인자로 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 파일에 저장됩니다.