바이너리

바이너리 (Binary) 포맷

ClickHouse는 여러 바이너리 포맷을 지원해서 더 나은 성능과 공간 효율을 얻을 수 있어요. 바이너리 포맷은 데이터가 이진 형태로 저장되므로 문자 인코딩 측면에서도 안전해요. 예시에는 some_data 테이블과 데이터를 사용할게요. 여러분 ClickHouse 인스턴스에서 직접 재현해 보셔도 좋아요.

출처: 문서

본문

Native ClickHouse 포맷으로 내보내기

ClickHouse 노드 사이에서 데이터를 내보내고 가져오는 데 가장 효율적인 포맷은 Native 포맷이에요. 내보내기는 INTO OUTFILE 절로 해요.

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse' FORMAT Native

이렇게 하면 네이티브 포맷의 data.clickhouse 파일이 생성돼요.

Native 포맷에서 가져오기

작은 파일이나 탐색 목적이라면 file() 함수를 쓸 수 있어요.

DESCRIBE file('data.clickhouse', Native);

┌─name──┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path  │ String │              │                    │         │                  │                │
│ month │ Date   │              │                    │         │                  │                │
│ hits  │ UInt32 │              │                    │         │                  │                │
└───────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

file() 함수를 쓸 때 ClickHouse Cloud에서는 파일이 있는 머신의 clickhouse client에서 명령을 실행해야 해요. 또 다른 방법은 clickhouse-local을 사용해 로컬에서 파일을 탐색하는 거예요. 프로덕션에서는 FROM INFILE로 데이터를 가져와요.

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
FORMAT Native

Native 포맷 압축

Native 포맷(그리고 대부분의 다른 포맷)으로 내보낼 때 COMPRESSION 절을 사용해 압축도 켤 수 있어요.

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

내보낼 때 LZ4 압축을 사용했어요. 데이터를 가져올 때도 이것을 지정해야 해요.

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

RowBinary로 내보내기

지원되는 또 다른 바이너리 포맷은 RowBinary로, 행을 이진 표현으로 가져오고 내보낼 수 있어요.

SELECT * FROM some_data
INTO OUTFILE 'data.binary' FORMAT RowBinary

이렇게 하면 바이너리 행 포맷의 data.binary 파일이 생성돼요.

RowBinary 파일 탐색

이 포맷은 자동 스키마 추론을 지원하지 않아서, 적재 전에 탐색하려면 스키마를 명시적으로 정의해야 해요.

SELECT *
FROM file('data.binary', RowBinary, 'path String, month Date, hits UInt32')
LIMIT 5

┌─path───────────────────────────┬──────month─┬─hits─┐
│ Bangor_City_Forest             │ 2015-07-01 │   34 │
│ Alireza_Afzal                  │ 2017-02-01 │   24 │
│ Akhaura-Laksam-Chittagong_Line │ 2015-09-01 │   30 │
│ 1973_National_500              │ 2017-10-01 │   80 │
│ Attachment                     │ 2017-09-01 │ 1356 │
└────────────────────────────────┴────────────┴──────┘

RowBinaryWithNames를 쓰는 것도 고려해 보세요. 컬럼 목록이 있는 헤더 행을 추가로 포함해요. RowBinaryWithNamesAndTypes는 컬럼 타입이 있는 추가 헤더 행도 포함한답니다.

RowBinary 파일에서 가져오기

RowBinary 파일에서 데이터를 적재하려면 FROM INFILE 절을 쓸 수 있어요.

INSERT INTO sometable
FROM INFILE 'data.binary'
FORMAT RowBinary

RawBLOB로 단일 바이너리 값 가져오기

바이너리 파일 전체를 읽어 테이블의 필드 하나에 저장하고 싶다고 가정해 볼게요. 이럴 때 RawBLOB 포맷을 쓸 수 있어요. 이 포맷은 단일 컬럼 테이블에서만 직접 사용할 수 있어요.

CREATE TABLE images(data String) ENGINE = Memory

이미지 파일을 images 테이블에 저장해 볼게요.

cat image.jpg | clickhouse-client -q "INSERT INTO images FORMAT RawBLOB"

data 필드 길이를 확인하면 원본 파일 크기와 같을 거예요.

SELECT length(data) FROM images

┌─length(data)─┐
│         6121 │
└──────────────┘

RawBLOB 데이터 내보내기

이 포맷은 INTO OUTFILE 절로 데이터를 내보낼 때도 쓸 수 있어요.

SELECT * FROM images LIMIT 1
INTO OUTFILE 'out.jpg'
FORMAT RawBLOB

단일 값보다 많이 내보내면 손상된 파일이 생기므로 LIMIT 1을 써야 한다는 점을 기억하세요.

MessagePack

ClickHouse는 MsgPack을 사용해 MessagePack 가져오기·내보내기를 지원해요. MessagePack 포맷으로 내보내려면:

SELECT *
FROM some_data
INTO OUTFILE 'data.msgpk'
FORMAT MsgPack

MessagePack 파일에서 데이터를 가져오려면:

INSERT INTO sometable
FROM INFILE 'data.msgpk'
FORMAT MsgPack

Protocol Buffers

Protocol Buffers로 작업하려면 먼저 스키마 파일을 정의해야 해요.

syntax = "proto3";

message MessageType {
  string path = 1;
  date month = 2;
  uint32 hits = 3;
};

이 스키마 파일(우리 예시에서는 schema.proto)의 경로는 Protobuf 포맷의 format_schema 설정 옵션에 넣어요.

SELECT * FROM some_data
INTO OUTFILE 'proto.bin'
FORMAT Protobuf
SETTINGS format_schema = 'schema:MessageType'

이렇게 하면 데이터가 proto.bin 파일에 저장돼요. ClickHouse는 Proto3 데이터와 중첩 메시지 가져오기도 지원해요. 단일 Protocol Buffer 메시지로 작업하려면 ProtobufSingle을 쓰는 걸 고려해 보세요 (이 경우 길이 구분자가 생략돼요).

Cap'n Proto

ClickHouse가 지원하는 또 다른 인기 바이너리 직렬화 포맷은 Cap'n Proto예요. Protobuf 포맷과 비슷하게 예시에서 스키마 파일(schema.capnp)을 정의해야 해요.

@0xec8ff1a10aa10dbe;

struct PathStats {
  path @0 :Text;
  month @1 :UInt32;
  hits @2 :UInt32;
}

이제 CapnProto 포맷과 이 스키마로 가져오고 내보낼 수 있어요.

SELECT
    path,
    CAST(month, 'UInt32') AS month,
    hits
FROM some_data
INTO OUTFILE 'capnp.bin'
FORMAT CapnProto
SETTINGS format_schema = 'schema:PathStats'

Date 컬럼을 UInt32로 캐스팅해야 대응하는 타입들과 맞출 수 있다는 점을 주목하세요.

다른 포맷

ClickHouse는 다양한 시나리오와 플랫폼을 다루기 위해 텍스트·바이너리 여러 포맷을 지원해요. 다음 문서에서 더 많은 포맷과 작업 방법을 살펴보세요.

• CSV 및 TSV 포맷
• Parquet
• JSON 포맷
• Regex과 템플릿
• Native 및 바이너리 포맷
• SQL 포맷

또한 clickhouse-local을 확인해 보세요. ClickHouse 서버를 시작하지 않고 로컬/원격 파일을 다룰 수 있는 휴대형 풀기능 도구예요.

더 알아보기 (Learn more)

• CSV 및 TSV 포맷
• JSON 포맷
• Parquet