ClickHouse 커넥터

ClickHouse 커넥터 (ClickHouse connector)

ClickHouse 커넥터는 외부 ClickHouse 서버의 테이블을 질의할 수 있게 해 줘요. 그 서버의 데이터베이스에 있는 데이터를 조회하거나, ClickHouse에 접근하는 다른 카탈로그 또는 다른 지원 데이터 소스의 데이터와 조합해 쓸 수 있어요.

출처: 문서

본문

요구사항 (Requirements)

ClickHouse 서버에 연결하려면 다음이 필요해요:

ClickHouse(25.3 이상) 또는 Altinity(23.3 이상).
Trino 코디네이터와 워커에서 ClickHouse 서버로 네트워크 접근. 기본 포트는 8123이에요.

설정 (Configuration)

이 커넥터는 ClickHouse 서버를 질의할 수 있어요. connector.name을 clickhouse로 설정해 ClickHouse 커넥터를 지정하는 카탈로그 속성 파일을 만드세요.

예를 들어 etc/catalog/example.properties 파일을 만들고, 연결 속성은 환경에 맞게 바꾸세요:

connector.name=clickhouse
connection-url=jdbc:clickhouse://host1:8123/
connection-user=exampleuser
connection-password=examplepassword

SSL을 쓰려면 URL에 ?ssl=true를 추가하세요:

connection-url=jdbc:clickhouse://host1:8443/?ssl=true

ClickHouse로 보내는 쿼리에 코멘트를 추가해 출처를 표시할 수 있어요:

query.comment-format=Query sent by Trino.

SELECT * FROM example_table; /*Query sent by Trino.*/

$QUERY_ID와 $USER 같은 자리 표시자를 쓸 수도 있어요:

query.comment-format=Query $QUERY_ID sent by user $USER from Trino.

SELECT * FROM example_table; /*Query 20230622_180528_00000_bkizg sent by user Jane from Trino.*/

대소문자를 구분하는 이름을 대소문자 무시 매핑으로 처리하도록 설정할 수 있어요. case-insensitive-name-matching.config-file을 통해 구성 파일에서 스키마·테이블 이름 매핑을 지정하세요:

{
  "schemas": [
    {
      "remoteSchema": "CaseSensitiveName",
      "mapping": "case_insensitive_1"
    },
    {
      "remoteSchema": "cASEsENSITIVEnAME",
      "mapping": "case_insensitive_2"
    }],
  "tables": [
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "tablex",
      "mapping": "table_1"
    },
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "TABLEX",
      "mapping": "table_2"
    }]
}

구성 파일을 주기적으로 다시 읽게 하려면 다음 속성을 쓰세요:

case-insensitive-name-matching.config-file.refresh-period=30s

스키마와 테이블 확인:

SHOW SCHEMAS FROM example;

SHOW TABLES FROM example.web;

DESCRIBE example.web.clicks;
SHOW COLUMNS FROM example.web.clicks;

SELECT * FROM example.web.clicks;

테이블 생성 예시(engine, order_by, partition_by, primary_key, sample_by 지정):

CREATE TABLE default.trino_ck (
  id int NOT NULL,
  birthday DATE NOT NULL,
  name VARCHAR,
  age BIGINT,
  logdate DATE NOT NULL
)
WITH (
  engine = 'MergeTree',
  order_by = ARRAY['id', 'birthday'],
  partition_by = ARRAY['toYYYYMM(logdate)'],
  primary_key = ARRAY['id'],
  sample_by = 'id'
);

메타데이터 캐시를 비우고 싶을 때:

USE example.example_schema;
CALL system.flush_metadata_cache();

ClickHouse에 대해 SQL로 명령을 실행할 수도 있어요:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

테이블 함수로 결과를 받아올 수도 있어요:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        *
      FROM
        tpch.nation'
    )
  );

푸시다운 여부를 확인하는 예시 — 문자열 부등식 비교는 푸시다운되지 않고, 동등 비교는 푸시다운돼요:

-- Not pushed down
SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name != 'CANADA';
-- Pushed down
SELECT * FROM nation WHERE name = 'CANADA';

더 알아보기 (Learn more)

다른 OLAP 데이터베이스 커넥터가 궁금하다면 Druid 커넥터 문서를 이어서 읽어 보세요.