gRPC 인터페이스

gRPC 인터페이스 (gRPC interface)

ClickHouse는 HTTP/2와 Protocol Buffers를 사용하는 오픈소스 원격 프로시저 호출 시스템인 gRPC 인터페이스를 지원해요. 여기서 설정 방법과 내장 클라이언트 사용법을 설명해 드릴게요.

출처: 문서

본문

소개 (Introduction)

ClickHouse는 gRPC 인터페이스를 지원해요. 이는 HTTP/2와 Protocol Buffers를 사용하는 오픈소스 원격 프로시저 호출 시스템이에요. ClickHouse의 gRPC 구현은 다음을 지원해요:

  • SSL;
  • 인증;
  • 세션;
  • 압축;
  • 같은 채널을 통한 병렬 쿼리;
  • 쿼리 취소;
  • 진행 상황과 로그 얻기;
  • 외부 테이블.

인터페이스의 명세는 clickhouse_grpc.proto에 설명되어 있어요.

gRPC 설정 (gRPC configuration)

gRPC 인터페이스를 사용하려면 주요 서버 설정에 grpc_port를 설정하세요. 다른 설정 옵션은 다음 예시를 참고해요:

<grpc_port>9100</grpc_port>
    <grpc>
        <enable_ssl>false</enable_ssl>

        <!-- The following two files are used only if SSL is enabled -->
        <ssl_cert_file>/path/to/ssl_cert_file</ssl_cert_file>
        <ssl_key_file>/path/to/ssl_key_file</ssl_key_file>

        <!-- Whether server requests client for a certificate -->
        <ssl_require_client_auth>false</ssl_require_client_auth>

        <!-- The following file is used only if ssl_require_client_auth=true -->
        <ssl_ca_cert_file>/path/to/ssl_ca_cert_file</ssl_ca_cert_file>

        <!-- Default compression algorithm (applied if client doesn't specify another algorithm, see result_compression in QueryInfo).
             Supported algorithms: none, deflate, gzip, stream_gzip -->
        <compression>deflate</compression>

        <!-- Default compression level (applied if client doesn't specify another level, see result_compression in QueryInfo).
             Supported levels: none, low, medium, high -->
        <compression_level>medium</compression_level>

        <!-- Send/receive message size limits in bytes. -1 means unlimited -->
        <max_send_message_size>-1</max_send_message_size>
        <max_receive_message_size>-1</max_receive_message_size>

        <!-- Enable if you want to get detailed logs -->
        <verbose_logs>false</verbose_logs>
    </grpc>

내장 클라이언트 (Built-in client)

제공된 명세를 사용해 gRPC가 지원하는 어떤 프로그래밍 언어로든 클라이언트를 작성할 수 있어요. 또는 내장 Python 클라이언트를 사용할 수 있어요. 저장소의 utils/grpc-client/clickhouse-grpc-client.py에 있어요. 내장 클라이언트는 grpcio와 grpcio-tools Python 모듈이 필요해요.

클라이언트는 다음 인수를 지원해요:

  • --help – 도움말 메시지를 보여주고 종료.
  • --host HOST, -h HOST – 서버 이름. 기본값: localhost. IPv4 또는 IPv6 주소도 사용할 수 있어요.
  • --port PORT – 연결할 포트. 이 포트는 ClickHouse 서버 설정에서 활성화되어 있어야 해요(grpc_port 참조). 기본값: 9100.
  • --user USER_NAME, -u USER_NAME – 사용자 이름. 기본값: default.
  • --password PASSWORD – 비밀번호. 기본값: 빈 문자열.
  • --query QUERY, -q QUERY – 비대화형 모드에서 처리할 쿼리.
  • --database DATABASE, -d DATABASE – 기본 데이터베이스. 지정하지 않으면 서버 설정에 설정된 현재 데이터베이스가 사용돼요(기본적으로 default).
  • --format OUTPUT_FORMAT, -f OUTPUT_FORMAT – 결과 출력 포맷. 대화형 모드 기본값: PrettyCompact.
  • --debug – 디버그 정보 표시를 활성화.

대화형 모드로 클라이언트를 실행하려면 --query 인수 없이 호출해요.

배치 모드에서는 쿼리 데이터를 stdin으로 전달할 수 있어요.

클라이언트 사용 예시

다음 예시에서는 테이블을 만들고 CSV 파일의 데이터를 로드한 다음 테이블 내용을 조회해요.

./clickhouse-grpc-client.py -q "CREATE TABLE grpc_example_table (id UInt32, text String) ENGINE = MergeTree() ORDER BY id;"
echo -e "0,Input data for\n1,gRPC protocol example" > a.csv
cat a.csv | ./clickhouse-grpc-client.py -q "INSERT INTO grpc_example_table FORMAT CSV"

./clickhouse-grpc-client.py --format PrettyCompact -q "SELECT * FROM grpc_example_table;"

┌─id─┬─text──────────────────┐
│  0 │ Input data for        │
│  1 │ gRPC protocol example │
└────┴───────────────────────┘

더 알아보기 (Learn more)