Protobuf

입력	출력	별칭
✔	✔

설명

Protobuf 형식은 Protocol Buffers 형식입니다. 이 형식을 사용하려면 외부 포맷 스키마가 필요하며, 이 스키마는 쿼리 간에 캐시됩니다. ClickHouse는 다음을 지원합니다:

proto2 및 proto3 구문
Repeated/optional/required 필드

테이블 컬럼과 Protocol Buffers’ 메시지 타입의 필드가 어떻게 대응되는지 확인하기 위해 ClickHouse는 이름을 비교합니다. 이 비교는 대소문자를 구분하지 않으며, 문자 _(밑줄)와 .(점)은 동일한 것으로 간주됩니다. 컬럼과 Protocol Buffers’ 메시지의 필드 타입이 다르면 필요한 변환이 적용됩니다. 중첩된 메시지도 지원합니다. 예를 들어, 다음 메시지 타입의 필드 z는 다음과 같습니다:

message MessageType {
  message XType {
    message YType {
      int32 z;
    };
    repeated YType y;
  };
  XType x;
};

ClickHouse는 x.y.z라는 이름의 컬럼(또는 x_y_z, X.y_Z 등)을 찾습니다. 중첩 메시지는 중첩 데이터 구조의 입력이나 출력에 적합합니다. wire에서 누락된 매핑된 필드의 경우:

일반 널 비허용 매핑 컬럼은 파싱 중 protobuf 스키마 필드 기본값(proto2의 [default = …], 그 외에는 타입 기본값)을 사용하며, 테이블 DEFAULT 표현식은 사용하지 않습니다.
매핑된 Nullable(...) 컬럼은 필드가 없을 때 NULL로 처리됩니다(protobuf 필드/타입 기본값을 사용하지 않습니다).
google.protobuf.*Value 래퍼에 대해 input_format_protobuf_flatten_google_wrappers가 활성화된 경우:
- Nullable(...) 컬럼에서 누락된 래퍼는 누락된 외부 필드로 처리되어 NULL이 됩니다.
- 존재하지만 비어 있는 래퍼(str {})는 중첩 스칼라 기본값('' / 0)을 유지합니다.
- 누락된 래퍼에 매핑된 널 비허용 컬럼은 NULL 대신 중첩 스칼라 기본값을 받습니다.

input_format_defaults_for_omitted_fields가 활성화된 경우(기본값), 메시지 타입에 일치하는 필드가 없는 테이블 컬럼에는 테이블 DEFAULT(및 기본 표현식)가 적용됩니다. 이 설정이 0이면 매핑되지 않은 컬럼은 테이블 DEFAULT 표현식 대신 파싱 중 삽입되는 데이터 타입 기본값을 유지합니다. proto2 스키마 필드 기본값의 예시(메시지에서 누락된 매핑 필드에 사용됨):

syntax = "proto2";

message MessageType {
  optional int32 result_per_page = 3 [default = 10];
}

메시지에 oneof가 포함되어 있고 input_format_protobuf_oneof_presence가 설정된 경우, ClickHouse는 oneof에서 발견된 필드를 나타내는 컬럼의 값을 채웁니다.

syntax = "proto3";

message StringOrString {
  oneof string_oneof {
    string string1 = 1;
    string string2 = 42;
  }
}

CREATE TABLE string_or_string ( string1 String, string2 String, string_oneof Enum('no'=0, 'hello' = 1, 'world' = 42))  Engine=MergeTree ORDER BY tuple();
INSERT INTO string_or_string from INFILE '$CURDIR/data_protobuf/String1' SETTINGS format_schema='$SCHEMADIR/string_or_string.proto:StringOrString' FORMAT ProtobufSingle;
SELECT * FROM string_or_string

   ┌─────────┬─────────┬──────────────┐
   │ string1 │ string2 │ string_oneof │
   ├─────────┼─────────┼──────────────┤
1. │         │ string2 │ world        │
   ├─────────┼─────────┼──────────────┤
2. │ string1 │         │ hello        │
   └─────────┴─────────┴──────────────┘

존재 여부를 나타내는 컬럼 이름은 oneof의 이름과 같아야 합니다. 중첩된 메시지가 지원됩니다(basic-examples 참조). 빈 메시지도 지원됩니다. 허용되는 타입은 Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Enum, Enum8 또는 Enum16입니다. Enum(및 Enum8 또는 Enum16)에는 없음을 나타내는 0과 대상 테이블에 일치하는 컬럼이 있는 모든 oneof case의 태그가 포함되어야 하며, 문자열 표현은 중요하지 않습니다. 일치하는 테이블 컬럼이 없는 oneof 메시지 멤버의 경우 누락된 Enum 태그도 허용됩니다. 이러한 브랜치가 입력에 있으면 ClickHouse는 oneof 존재 여부를 생략된 것으로 처리하고 존재 여부 컬럼에 0을 기록합니다. 설정 input_format_protobuf_oneof_presence은 기본적으로 비활성화되어 있습니다 ClickHouse는 protobuf 메시지를 length-delimited 길이 구분 형식으로 입력하고 출력합니다. 즉, 각 메시지 앞에 해당 메시지의 길이를 가변 길이 정수(varint)로 기록해야 합니다.

사용 예시

데이터 읽기 및 쓰기

예시 파일이 예시에서 사용하는 파일은 examples 리포지토리에서 확인할 수 있습니다.

이 예시에서는 protobuf_message.bin 파일의 데이터를 ClickHouse 테이블로 읽어옵니다. 그런 다음 Protobuf 형식을 사용해 이 데이터를 protobuf_message_from_clickhouse.bin이라는 파일로 다시 씁니다. schemafile.proto 파일이 다음과 같다고 가정합니다:

syntax = "proto3";

message MessageType {
  string name = 1;
  string surname = 2;
  uint32 birthDate = 3;
  repeated string phoneNumbers = 4;
};

바이너리 파일 생성

이미 Protobuf 포맷으로 데이터를 직렬화하고 역직렬화하는 방법을 알고 있다면 이 단계는 건너뛰어도 됩니다.Python을 사용해 일부 데이터를 protobuf_message.bin에 직렬화한 뒤 ClickHouse로 읽어오겠습니다. 다른 언어를 사용하려면 “인기 있는 언어에서 길이 구분 Protobuf 메시지를 읽고 쓰는 방법”도 참고하십시오.다음 명령을 실행하여 schemafile.proto와 같은 디렉터리에 schemafile_pb2.py라는 Python 파일을 생성하십시오. 이 파일에는 UserData Protobuf 메시지를 나타내는 Python 클래스가 포함됩니다:

protoc --python_out=. schemafile.proto

이제 schemafile_pb2.py와 같은 디렉터리에 generate_protobuf_data.py라는 새 Python 파일을 생성하십시오. 여기에 다음 코드를 붙여 넣으십시오:

import schemafile_pb2  # 'protoc'가 생성한 모듈
from google.protobuf import text_format
from google.protobuf.internal.encoder import _VarintBytes # 내부 varint 인코더 가져오기

def create_user_data_message(name, surname, birthDate, phoneNumbers):
    """
    UserData Protobuf 메시지를 생성하고 채웁니다.
    """
    message = schemafile_pb2.MessageType()
    message.name = name
    message.surname = surname
    message.birthDate = birthDate
    message.phoneNumbers.extend(phoneNumbers)
    return message

# 예시 사용자 데이터
data_to_serialize = [
    {"name": "Aisha", "surname": "Khan", "birthDate": 19920815, "phoneNumbers": ["(555) 247-8903", "(555) 612-3457"]},
    {"name": "Javier", "surname": "Rodriguez", "birthDate": 20001015, "phoneNumbers": ["(555) 891-2046", "(555) 738-5129"]},
    {"name": "Mei", "surname": "Ling", "birthDate": 19980616, "phoneNumbers": ["(555) 956-1834", "(555) 403-7682"]},
]

output_filename = "protobuf_messages.bin"

# 바이너리 파일을 바이너리 쓰기 모드('wb')로 엽니다
with open(output_filename, "wb") as f:
    for item in data_to_serialize:
        # 현재 사용자에 대한 Protobuf 메시지 인스턴스를 생성합니다
        message = create_user_data_message(
            item["name"],
            item["surname"],
            item["birthDate"],
            item["phoneNumbers"]
        )

        # 메시지를 직렬화합니다
        serialized_data = message.SerializeToString()

        # 직렬화된 데이터의 길이를 구합니다
        message_length = len(serialized_data)

        # Protobuf 라이브러리의 내부 _VarintBytes를 사용해 길이를 인코딩합니다
        length_prefix = _VarintBytes(message_length)

        # 길이 접두사를 씁니다
        f.write(length_prefix)
        # 직렬화된 메시지 데이터를 씁니다
        f.write(serialized_data)

print(f"Protobuf messages (length-delimited) written to {output_filename}")

# --- 선택 사항: 검증(다시 읽어서 출력) ---
# 다시 읽을 때도 varint용 내부 Protobuf 디코더를 사용합니다.
from google.protobuf.internal.decoder import _DecodeVarint32

print("\n--- Verifying by reading back ---")
with open(output_filename, "rb") as f:
    buf = f.read() # varint 디코딩을 쉽게 하기 위해 파일 전체를 버퍼로 읽습니다
    n = 0
    while n < len(buf):
        # varint 길이 접두사를 디코딩합니다
        msg_len, new_pos = _DecodeVarint32(buf, n)
        n = new_pos

        # 메시지 데이터를 추출합니다
        message_data = buf[n:n+msg_len]
        n += msg_len

        # 메시지를 파싱합니다
        decoded_message = schemafile_pb2.MessageType()
        decoded_message.ParseFromString(message_data)
        print(text_format.MessageToString(decoded_message, as_utf8=True))

이제 명령줄에서 스크립트를 실행하십시오. 예를 들어 uv를 사용해 Python 가상 환경에서 실행하는 것을 권장합니다:

uv venv proto-venv
source proto-venv/bin/activate

다음 Python 라이브러리를 설치해야 합니다:

uv pip install --upgrade protobuf

바이너리 파일을 생성하려면 스크립트를 실행하십시오:

python generate_protobuf_data.py

스키마와 일치하는 ClickHouse 테이블을 생성하십시오:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

명령줄에서 테이블에 데이터를 삽입하세요:

cat protobuf_messages.bin | clickhouse-client --query "INSERT INTO test.protobuf_messages SETTINGS format_schema='schemafile:MessageType' FORMAT Protobuf"

Protobuf 형식을 사용하여 데이터를 바이너리 파일에 다시 쓸 수도 있습니다:

SELECT * FROM test.protobuf_messages INTO OUTFILE 'protobuf_message_from_clickhouse.bin' FORMAT Protobuf SETTINGS format_schema = 'schemafile:MessageType'

Protobuf 스키마를 사용하면 이제 ClickHouse에서 파일 protobuf_message_from_clickhouse.bin에 기록된 데이터를 역직렬화할 수 있습니다.

ClickHouse Cloud에서 데이터 읽기 및 쓰기

ClickHouse Cloud에서는 Protobuf 스키마 파일을 업로드할 수 없습니다. 하지만 format_protobuf_schema 설정을 사용해 쿼리에서 스키마를 지정할 수 있습니다. 이 예시에서는 로컬 머신에서 직렬화된 데이터를 읽어 ClickHouse Cloud의 테이블에 삽입하는 방법을 보여줍니다. 이전 예시와 마찬가지로, ClickHouse Cloud에서 Protobuf 스키마에 맞게 테이블을 생성합니다:

CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE IF NOT EXISTS test.protobuf_messages (
  name String,
  surname String,
  birthDate UInt32,
  phoneNumbers Array(String)
)
ENGINE = MergeTree()
ORDER BY tuple()

설정 format_schema_source는 format_schema 설정의 소스를 정의합니다 가능한 값:

‘file’ (기본값): Cloud에서는 지원되지 않습니다
‘string’: format_schema는 스키마(schema)의 리터럴 내용입니다.
‘query’: format_schema는 스키마(schema)를 가져오기 위한 쿼리입니다.

`format_schema_source='string'`

스키마를 문자열로 지정해 ClickHouse Cloud에 데이터를 삽입하려면 다음을 실행하십시오:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};', format_schema='schemafile:MessageType' FORMAT Protobuf"

테이블에 삽입된 데이터를 조회하세요:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

`format_schema_source='query'`

Protobuf 스키마를 테이블(table)에 저장할 수도 있습니다. 데이터를 삽입할 ClickHouse Cloud 테이블을 생성합니다:

CREATE TABLE testing.protobuf_schema (
  schema String
)
ENGINE = MergeTree()
ORDER BY tuple();

INSERT INTO testing.protobuf_schema VALUES ('syntax = "proto3";message MessageType {  string name = 1;  string surname = 2;  uint32 birthDate = 3;  repeated string phoneNumbers = 4;};');

데이터를 ClickHouse Cloud에 삽입할 때 실행할 쿼리에서 스키마를 지정하세요:

cat protobuf_messages.bin | clickhouse client --host <hostname> --secure --password <password> --query "INSERT INTO testing.protobuf_messages SETTINGS format_schema_source='SELECT schema FROM testing.protobuf_schema', format_schema='schemafile:MessageType' FORMAT Protobuf"

테이블에 삽입된 데이터를 조회하세요:

clickhouse client --host <hostname> --secure --password <password> --query "SELECT * FROM testing.protobuf_messages"

Aisha Khan 19920815 ['(555) 247-8903','(555) 612-3457']
Javier Rodriguez 20001015 ['(555) 891-2046','(555) 738-5129']
Mei Ling 19980616 ['(555) 956-1834','(555) 403-7682']

자동 생성된 스키마 사용

데이터용 외부 Protobuf 스키마가 없더라도 자동 생성된 스키마를 사용해 데이터를 형식으로 출력하거나 입력할 수 있습니다. 이를 위해 format_protobuf_use_autogenerated_schema 설정을 사용합니다. 예시:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1

이 경우 ClickHouse는 함수 structureToProtobufSchema를 사용해 테이블 구조에 따라 Protobuf 스키마를 자동으로 생성합니다. 그런 다음 이 스키마를 사용해 데이터를 형식으로 직렬화합니다. 자동 생성된 스키마를 사용해 Protobuf 파일도 읽을 수 있습니다. 이 경우 파일은 동일한 스키마를 사용해 생성되어 있어야 합니다:

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

설정 format_protobuf_use_autogenerated_schema는 기본적으로 활성화되어 있으며, format_schema가 설정되지 않은 경우에 적용됩니다. 또한 설정 output_format_schema를 사용하면 입력/출력 시 자동 생성된 스키마를 파일에 저장할 수 있습니다. 예시:

SELECT * FROM test.hits format Protobuf SETTINGS format_protobuf_use_autogenerated_schema=1, output_format_schema='path/to/schema/schema.proto'

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

Protobuf 캐시 삭제

format_schema_path에서 로드된 Protobuf 스키마를 다시 로드하려면 SYSTEM DROP ... FORMAT CACHE SQL 문을 사용하십시오.

SYSTEM DROP FORMAT SCHEMA CACHE FOR Protobuf

SQL 참고

데이터 타입

엔진

함수

포맷

인터페이스

설정

시스템 테이블

데이터 레이크

설명

사용 예시

데이터 읽기 및 쓰기

ClickHouse Cloud에서 데이터 읽기 및 쓰기

`format_schema_source='string'`

`format_schema_source='query'`

자동 생성된 스키마 사용

Protobuf 캐시 삭제

​설명

​사용 예시

​데이터 읽기 및 쓰기

​ClickHouse Cloud에서 데이터 읽기 및 쓰기

​format_schema_source='string'

​format_schema_source='query'

​자동 생성된 스키마 사용

​Protobuf 캐시 삭제

설명

사용 예시

데이터 읽기 및 쓰기

ClickHouse Cloud에서 데이터 읽기 및 쓰기

`format_schema_source='string'`

`format_schema_source='query'`

자동 생성된 스키마 사용

Protobuf 캐시 삭제