Protobuf - ClickHouse Documentation

입력	출력	별칭
✔	✔

설명

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 등)을 찾습니다. 중첩 메시지는 중첩 데이터 구조의 입력이나 출력에 적합합니다. 아래와 같은 protobuf 스키마에 정의된 기본값은 적용되지 않으며, 대신 테이블 기본값이 사용됩니다:

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)에는 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 스키마가 없더라도 자동 생성된 스키마를 사용해 데이터를 Protobuf 형식으로 출력하거나 입력할 수 있습니다. 이를 위해 format_protobuf_use_autogenerated_schema 설정을 사용합니다. 예시:

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

이 경우 ClickHouse는 함수 structureToProtobufSchema를 사용해 테이블 구조에 따라 Protobuf 스키마를 자동으로 생성합니다. 그런 다음 이 스키마를 사용해 데이터를 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

​설명

​사용 예시

​데이터 읽기 및 쓰기

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

​format_schema_source='string'

​format_schema_source='query'

​자동 생성된 스키마 사용

​Protobuf 캐시 삭제

설명

사용 예시

데이터 읽기 및 쓰기

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

`format_schema_source='string'`

`format_schema_source='query'`

자동 생성된 스키마 사용

Protobuf 캐시 삭제