Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickHouse에서 Native 형식과 바이너리 형식 사용하기

View as MarkdownEdit this pageReport an issueSet up docs MCP

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 │              │                    │         │                  │                │
└───────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

프로덕션 환경에서는 FROM INFILE을 사용해 데이터를 가져옵니다:

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
FORMAT 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

값을 2개 이상 내보내면 파일이 손상되므로 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

ClickHouse Cloud에서 지원되지 않음

Protocol Buffers를 사용하려면 먼저 스키마 파일을 정의해야 합니다:

syntax = "proto3";

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

이 스키마 파일(이 경우 schema.proto)의 경로는 형식 포맷에서 format_schema 설정 옵션으로 지정합니다:

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

이렇게 하면 데이터가 proto.bin 파일에 저장됩니다. ClickHouse는 형식 데이터 가져오기와 중첩된 메시지도 지원합니다. 단일 Protocol Buffer 메시지를 처리하려면 ProtobufSingle 사용을 고려하십시오(이 경우 길이 구분 기호는 생략됩니다).

Cap'n Proto

ClickHouse Cloud에서 지원되지 않음

ClickHouse가 지원하는 또 다른 널리 쓰이는 바이너리 형식의 직렬화 포맷은 Cap'n Proto입니다. Protobuf format과 마찬가지로, 이 예시에서는 스키마 파일(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는 다양한 시나리오와 플랫폼을 지원하기 위해 텍스트와 바이너리 형식을 포함한 여러 포맷을 제공합니다. 다음 문서에서 더 많은 포맷과 활용 방법을 살펴보십시오.

또한 clickhouse-local도 확인해 보십시오. ClickHouse 서버를 시작하지 않고 로컬/원격 파일을 다룰 수 있는 이식 가능한 완전한 기능의 도구입니다.

Navigation