ClickHouse Client - ClickHouse Documentation

ClickHouse는 ClickHouse 서버에 직접 SQL 쿼리를 실행할 수 있는 네이티브 command-line client를 제공합니다. 이 client는 대화형 모드(interactive mode)와 배치 모드(배치 모드)를 모두 지원하며, 각각 실시간 쿼리 실행과 스크립팅 및 자동화에 사용할 수 있습니다. 쿼리 결과는 터미널에 표시하거나 파일로 내보낼 수 있으며, Pretty, CSV, JSON 등을 포함한 모든 ClickHouse 출력 포맷을 지원합니다. 이 client는 진행률 표시줄과 읽은 행 수, 처리된 바이트 수, 쿼리 실행 시간 등을 통해 쿼리 실행 상태를 실시간으로 보여줍니다. 또한 명령줄 옵션과 설정 파일을 모두 지원합니다.

설치

ClickHouse를 다운로드하려면 다음 명령을 실행하세요:

curl https://clickhouse.com/ | sh

추가로 설치하려면 다음을 실행하세요:

sudo ./clickhouse install

추가 설치 옵션은 ClickHouse 설치를 참조하십시오. 서로 다른 클라이언트 버전과 서버 버전도 호환되지만, 일부 기능은 이전 버전의 클라이언트에서 사용할 수 없을 수 있습니다. 클라이언트와 서버는 동일한 버전을 사용하는 것을 권장합니다.

실행

ClickHouse를 다운로드만 하고 설치하지 않았다면 clickhouse-client 대신 ./clickhouse client를 사용하세요.

ClickHouse 서버에 연결하려면 다음을 실행하세요:

$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Connecting to server:9000 as user default.
Connected to ClickHouse server version 24.12.2.

:)

필요에 따라 추가 연결 정보를 지정하십시오:

옵션	설명
`--port <port>`	ClickHouse 서버가 연결을 수신하는 포트입니다. 기본 포트는 9440(TLS) 및 9000(TLS 미사용)입니다. ClickHouse Client는 HTTP(S)가 아니라 네이티브 프로토콜을 사용한다는 점에 유의하십시오.
`-s [ --secure ]`	TLS를 사용할지 여부입니다(대개 자동으로 감지됩니다).
`-u [ --user ] <username>`	연결할 때 사용할 데이터베이스 사용자입니다. 기본적으로 `default` 사용자로 연결됩니다.
`--password <password>`	데이터베이스 사용자의 비밀번호입니다. 연결에 사용할 비밀번호는 설정 파일에서 지정할 수도 있습니다. 비밀번호를 지정하지 않으면 클라이언트가 입력을 요청합니다.
`-c [ --config ] <path-to-file>`	ClickHouse Client의 설정 파일이 기본 위치 중 하나에 없을 경우 해당 설정 파일의 위치입니다. 설정 파일을 참조하십시오.
`--connection <name>`	설정 파일에 미리 구성된 연결 정보의 이름입니다.

명령줄 옵션의 전체 목록은 명령줄 옵션을 참조하십시오.

ClickHouse Cloud에 연결하기

ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다. 연결할 서비스를 선택한 다음 Connect를 클릭하십시오:

Native를 선택하면 예시 clickhouse-client 명령과 함께 연결 세부 정보가 표시됩니다:

설정 파일에 연결 정보 저장하기

하나 이상의 ClickHouse 서버에 대한 연결 정보를 설정 파일에 저장할 수 있습니다. 형식은 다음과 같습니다:

<config>
    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>hostname</hostname>
            <port>9440</port>
            <secure>1</secure>
            <user>default</user>
            <password>password</password>
            <!-- <history_file></history_file> -->
            <!-- <history_max_entries></history_max_entries> -->
            <!-- <accept-invalid-certificate>false</accept-invalid-certificate> -->
            <!-- <prompt></prompt> -->
        </connection>
    </connections_credentials>
</config>

자세한 내용은 설정 파일 섹션을 참조하십시오.

쿼리 구문에 집중하기 위해 나머지 예시에서는 접속 정보(--host, --port 등)를 생략합니다. 명령을 사용할 때는 이를 추가하십시오.

대화형 모드

대화형 모드 사용하기

ClickHouse를 대화형 모드로 실행하려면 다음을 실행하세요:

clickhouse-client

그러면 SQL 쿼리를 대화형으로 입력할 수 있는 Read-Eval-Print Loop (REPL)가 열립니다. 연결되면 쿼리를 입력할 수 있는 프롬프트가 표시됩니다:

ClickHouse client version 25.x.x.x
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 25.x.x.x

hostname :)

대화형 모드에서 기본 출력 형식은 PrettyCompact입니다. 쿼리의 FORMAT 절에서 포맷을 변경하거나 --format 명령줄 옵션을 지정할 수 있습니다. Vertical 형식을 사용하려면 --vertical을 사용하거나 쿼리 끝에 \G를 지정할 수 있습니다. 이 형식에서는 각 값이 별도의 줄에 출력되므로 열이 많은 테이블에 편리합니다. 대화형 모드에서는 기본적으로 Enter를 누르면 입력한 내용이 실행됩니다. 쿼리 끝에 세미콜론은 필요하지 않습니다. -m, --multiline 매개변수로 클라이언트를 시작할 수 있습니다. 여러 줄 쿼리를 입력하려면 줄 바꿈 앞에 백슬래시 \를 입력하십시오. Enter를 누르면 쿼리의 다음 줄을 입력하라는 메시지가 표시됩니다. 쿼리를 실행하려면 끝에 세미콜론을 붙인 뒤 Enter를 누르십시오. ClickHouse Client는 replxx(readline과 유사)를 기반으로 하므로 익숙한 키보드 단축키를 사용할 수 있으며 이력을 유지합니다. 이력은 기본적으로 ~/.clickhouse-client-history에 기록됩니다. 클라이언트를 종료하려면 Ctrl+D를 누르거나, 쿼리 대신 다음 중 하나를 입력하십시오.

exit 또는 exit;
quit 또는 quit;
q, Q 또는 :q
logout 또는 logout;

쿼리 처리 정보

쿼리를 처리하는 동안 클라이언트는 다음을 표시합니다.

진행 상황으로, 기본적으로 초당 10회를 넘지 않도록 갱신됩니다. 쿼리가 매우 빠르면 진행 상황이 표시되기 전에 처리가 끝날 수 있습니다.
디버깅을 위한 구문 분석 후의 포맷팅된 쿼리.
지정된 포맷의 결과.
결과의 행 수, 경과 시간, 쿼리 처리의 평균 속도. 모든 데이터 양은 비압축 데이터를 기준으로 합니다.

오래 걸리는 쿼리는 Ctrl+C를 눌러 취소할 수 있습니다. 하지만 server가 요청을 중단할 때까지는 잠시 기다려야 합니다. 특정 단계에서는 쿼리를 취소할 수 없습니다. 기다리지 않고 Ctrl+C를 한 번 더 누르면 클라이언트가 종료됩니다. ClickHouse Client는 쿼리에 사용할 외부 데이터(외부 임시 테이블)를 전달할 수 있습니다. 자세한 내용은 쿼리 처리용 외부 데이터 섹션을 참조하십시오.

별칭

REPL에서는 다음 별칭을 사용할 수 있습니다:

\l - SHOW DATABASES
\d - SHOW TABLES
\c <DATABASE> - USE DATABASE
. - 마지막 쿼리 다시 실행

키보드 단축키

Alt (Option) + Shift + e - 현재 쿼리로 편집기를 엽니다. 환경 변수 EDITOR를 사용해 편집기를 지정할 수 있습니다. 기본 편집기는 vim입니다.
Alt (Option) + # - 현재 줄을 주석 처리합니다.
Ctrl + r - 퍼지 이력 검색을 수행합니다.

사용 가능한 모든 키보드 단축키의 전체 목록은 replxx에서 확인할 수 있습니다.

MacOS에서 메타 키(Option)가 올바르게 동작하도록 설정하려면 다음과 같이 하십시오:iTerm2: Preferences -> Profile -> Keys -> Left Option key로 이동한 다음 Esc+를 클릭하십시오

배치 모드

배치 모드 사용하기

ClickHouse Client를 대화형으로 사용하는 대신 배치 모드로 실행할 수 있습니다. 배치 모드에서는 ClickHouse가 단일 쿼리 하나를 실행한 후 즉시 종료됩니다. 대화형 프롬프트나 반복 실행 루프는 없습니다. 다음과 같이 단일 쿼리를 지정할 수 있습니다:

$ clickhouse-client "SELECT sum(number) FROM numbers(10)"
45

다음과 같이 --query 명령줄 옵션을 사용할 수도 있습니다:

$ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)"
10

stdin을 통해 쿼리를 제공할 수 있습니다:

$ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client
4.5

messages 테이블이 존재한다고 가정하면, 명령줄에서도 데이터를 삽입할 수 있습니다:

$ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV"

--query를 지정하면 모든 입력이 개행 문자 뒤에 요청에 추가됩니다.

원격 ClickHouse 서비스에 CSV 파일 삽입하기

이 예시에서는 샘플 데이터셋이 담긴 CSV 파일 cell_towers.csv를 default 데이터베이스의 기존 테이블 cell_towers에 삽입합니다:

clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv

명령줄에서 데이터를 삽입하는 예시

명령줄에서 데이터를 삽입하는 방법은 여러 가지가 있습니다. 아래 예시는 배치 모드(batch mode)를 사용하여 두 개의 CSV 데이터 행을 ClickHouse 테이블(table)에 삽입합니다:

echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | \
  clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

아래 예시에서 cat <<_EOF는 heredoc을 시작하며, _EOF가 다시 나타날 때까지 모든 내용을 읽은 다음 출력합니다:

cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF

아래 예시에서는 cat을 사용해 file.csv의 내용을 stdout으로 출력한 다음, 이를 파이프로 clickhouse-client의 입력으로 전달합니다:

cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

배치 모드에서는 기본 데이터 포맷이 TabSeparated입니다. 위 예시와 같이 쿼리의 FORMAT 절에서 포맷을 설정할 수 있습니다.

매개변수가 있는 쿼리

쿼리에서 매개변수를 지정하고 명령줄 옵션으로 해당 값을 전달할 수 있습니다. 이렇게 하면 클라이언트 측에서 특정 동적 값을 넣어 쿼리를 포맷할 필요가 없습니다. 예시는 다음과 같습니다:

$ clickhouse-client --param_parName="[1, 2]" --query "SELECT {parName: Array(UInt16)}"
[1,2]

대화형 세션에서도 매개변수를 설정할 수 있습니다:

$ clickhouse-client
ClickHouse client version 25.X.X.XXX (official build).

:) SET param_parName='[1, 2]';

SET param_parName = '[1, 2]'

Query id: 7ac1f84e-e89a-4eeb-a4bb-d24b8f9fd977

Ok.

0 rows in set. Elapsed: 0.000 sec.

:) SELECT {parName:Array(UInt16)}

SELECT {parName:Array(UInt16)}

Query id: 0358a729-7bbe-4191-bb48-29b063c548a7

   ┌─_CAST([1, 2]⋯y(UInt16)')─┐
1. │ [1,2]                    │
   └──────────────────────────┘

1 row in set. Elapsed: 0.006 sec.

쿼리 구문

쿼리에서 명령줄 매개변수로 채우려는 값은 다음 형식으로 중괄호 안에 지정합니다:

{<name>:<data type>}

매개변수	설명
`name`	플레이스홀더 식별자입니다. 해당 명령줄 옵션은 `--param_<name> = value`입니다.
`data type`	매개변수의 데이터 타입입니다. 예를 들어 `(integer, ('string', integer))`와 같은 데이터 구조는 `Tuple(UInt8, Tuple(String, UInt8))` 데이터 타입이 될 수 있습니다(다른 integer 타입도 사용할 수 있습니다). 테이블 이름, 데이터베이스 이름, 컬럼 이름을 매개변수로 전달할 수도 있으며, 이 경우 데이터 타입으로 `Identifier`를 사용해야 합니다.

예시

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" \
    --query "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"

$ clickhouse-client --param_tbl="numbers" --param_db="system" --param_col="number" --param_alias="top_ten" \
    --query "SELECT {col:Identifier} as {alias:Identifier} FROM {db:Identifier}.{tbl:Identifier} LIMIT 10"

AI SQL 생성

ClickHouse Client에는 자연어 설명을 바탕으로 SQL 쿼리를 생성하는 AI 지원 기능이 기본으로 포함되어 있습니다. 이 기능을 사용하면 SQL을 깊이 있게 알지 못해도 복잡한 쿼리를 작성할 수 있습니다. OPENAI_API_KEY 또는 ANTHROPIC_API_KEY 환경 변수가 설정되어 있으면 AI 지원 기능은 별도 설정 없이 바로 사용할 수 있습니다. 더 고급 구성이 필요하면 구성 섹션을 참조하십시오.

사용 방법

AI SQL 생성 기능을 사용하려면 자연어 질의 앞에 ??를 붙이십시오:

:) ?? show all users who made purchases in the last 30 days

AI는 다음 작업을 수행합니다:

데이터베이스 스키마를 자동으로 파악합니다
파악된 테이블과 컬럼을 바탕으로 적절한 SQL을 생성합니다
생성된 쿼리를 즉시 실행합니다

예시

:) ?? count orders by product category

Starting AI SQL generation with schema discovery...
──────────────────────────────────────────────────

🔍 list_databases
   ➜ system, default, sales_db

🔍 list_tables_in_database
   database: sales_db
   ➜ orders, products, categories

🔍 get_schema_for_table
   database: sales_db
   table: orders
   ➜ CREATE TABLE orders (order_id UInt64, product_id UInt64, quantity UInt32, ...)

✨ SQL query generated successfully!
──────────────────────────────────────────────────

SELECT
    c.name AS category,
    COUNT(DISTINCT o.order_id) AS order_count
FROM sales_db.orders o
JOIN sales_db.products p ON o.product_id = p.product_id
JOIN sales_db.categories c ON p.category_id = c.category_id
GROUP BY c.name
ORDER BY order_count DESC

구성

AI SQL 생성을 사용하려면 ClickHouse Client 설정 파일에서 AI 프로바이더를 구성해야 합니다. OpenAI, Anthropic 또는 OpenAI와 호환되는 API 서비스를 사용할 수 있습니다.

환경 변수 기반 폴백

설정 파일에 AI 구성이 지정되어 있지 않으면, ClickHouse Client는 자동으로 환경 변수 사용을 시도합니다:

먼저 OPENAI_API_KEY 환경 변수를 확인합니다
없으면 ANTHROPIC_API_KEY 환경 변수를 확인합니다
둘 다 없으면 AI 기능이 비활성화됩니다

따라서 설정 파일 없이도 빠르게 설정할 수 있습니다:

# OpenAI 사용
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# Anthropic 사용
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

설정 파일

AI 설정을 더 세밀하게 제어하려면 다음 위치에 있는 ClickHouse Client 설정 파일에서 설정하십시오:

$XDG_CONFIG_HOME/clickhouse/config.xml (XDG_CONFIG_HOME이 설정되지 않은 경우 ~/.config/clickhouse/config.xml) (XML 포맷)
$XDG_CONFIG_HOME/clickhouse/config.yaml (XDG_CONFIG_HOME이 설정되지 않은 경우 ~/.config/clickhouse/config.yaml) (YAML 포맷)
~/.clickhouse-client/config.xml (XML 포맷, 레거시 위치)
~/.clickhouse-client/config.yaml (YAML 포맷, 레거시 위치)
또는 --config-file로 사용자 지정 경로를 지정하십시오

XML
YAML

<config>
    <ai>
        {/* 필수: API Key(또는 환경 변수로 설정) */}
        <api_key>your-api-key-here</api_key>

        {/* 필수: 프로바이더 유형(openai, anthropic) */}
        <provider>openai</provider>

        {/* 사용할 모델(기본값은 프로바이더에 따라 다름) */}
        <model>gpt-4o</model>

        {/* 선택 사항: OpenAI 호환 서비스용 사용자 지정 API 엔드포인트 */}
        {/* <base_url>https://openrouter.ai/api</base_url> */}

        {/* 스키마 탐색 설정 */}
        <enable_schema_access>true</enable_schema_access>

        {/* 생성 매개변수 */}
        <temperature>0.0</temperature>
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        {/* 선택 사항: 사용자 지정 system prompt */}
        {/* <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> */}
    </ai>
</config>

ai:
  # 필수: API Key(또는 환경 변수로 설정)
  api_key: your-api-key-here

  # 필수: 프로바이더 유형(openai, anthropic)
  provider: openai

  # 사용할 모델
  model: gpt-4o

  # 선택 사항: OpenAI 호환 서비스용 사용자 지정 API 엔드포인트
  # base_url: https://openrouter.ai/api

  # 스키마 접근 활성화 - AI가 데이터베이스(database)/테이블(table) 정보를 쿼리할 수 있도록 허용
  enable_schema_access: true

  # 생성 매개변수
  temperature: 0.0      # 무작위성 제어(0.0 = deterministic)
  max_tokens: 1000      # 최대 응답 길이
  timeout_seconds: 30   # 요청 timeout
  max_steps: 10         # 최대 스키마 탐색 단계 수

  # 선택 사항: 사용자 지정 system prompt
  # system_prompt: |
  #   ClickHouse SQL 전문가 어시스턴트입니다. 자연어를 SQL로 변환하십시오.
  #   성능에 중점을 두고 ClickHouse 고유의 최적화를 사용하십시오.
  #   항상 설명 없이 실행 가능한 SQL만 반환하십시오.

OpenAI 호환 API 사용(예: OpenRouter):

ai:
  provider: openai  # 호환성을 위해 'openai' 사용
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # OpenRouter 모델 명명 규칙 사용

최소 구성 예시:

# 최소 설정 - API Key에 환경 변수 사용
ai:
  provider: openai  # OPENAI_API_KEY 환경 변수 사용

# 설정 없음 - 자동 폴백
# (ai 섹션이 비어 있거나 없는 경우 - OPENAI_API_KEY, ANTHROPIC_API_KEY 순으로 시도)

# 모델만 재정의 - API Key에 환경 변수 사용
ai:
  provider: openai
  model: gpt-3.5-turbo

매개변수

필수 매개변수

api_key - AI 서비스용 API Key입니다. 환경 변수로 설정되어 있으면 생략할 수 있습니다:
- OpenAI: OPENAI_API_KEY
- Anthropic: ANTHROPIC_API_KEY
- 참고: 구성 파일의 API Key가 환경 변수보다 우선 적용됩니다
provider - AI 프로바이더입니다: openai 또는 anthropic
- 생략하면 사용 가능한 환경 변수를 기준으로 자동 폴백이 사용됩니다

모델 구성

model - 사용할 모델입니다(기본값: 프로바이더별 기본값)
- OpenAI: gpt-4o, gpt-4, gpt-3.5-turbo 등
- Anthropic: claude-3-5-sonnet-20241022, claude-3-opus-20240229 등
- OpenRouter: anthropic/claude-3.5-sonnet과 같은 모델 이름을 사용합니다

연결 설정

base_url - OpenAI 호환 서비스용 사용자 지정 API 엔드포인트입니다(선택 사항)
timeout_seconds - 요청 타임아웃 시간(초)입니다(기본값: 30)

스키마 탐색

enable_schema_access - AI가 데이터베이스 스키마를 탐색할 수 있도록 허용합니다(기본값: true)
max_steps - 스키마 탐색을 위한 도구 호출의 최대 단계 수입니다(기본값: 10)

생성 매개변수

temperature - 무작위성을 제어합니다. 0.0 = deterministic, 1.0 = 창의적(기본값: 0.0)
max_tokens - tokens 기준 최대 응답 길이입니다(기본값: 1000)
system_prompt - AI에 전달할 사용자 지정 지침입니다(선택 사항)

작동 방식

AI SQL 생성기는 여러 단계의 프로세스로 작동합니다:

스키마 검색

AI는 내장 도구를 사용해 데이터베이스를 탐색합니다

사용 가능한 데이터베이스를 나열합니다
관련 데이터베이스 내의 테이블을 찾아냅니다
CREATE TABLE SQL 문을 통해 테이블 구조를 확인합니다

쿼리 생성

AI는 검색된 스키마를 바탕으로 다음과 같은 SQL을 생성합니다:

자연어로 표현한 의도에 맞습니다
올바른 테이블 및 컬럼 이름을 사용합니다
적절한 조인과 집계를 적용합니다

실행

생성된 SQL은 자동으로 실행되며, 결과가 표시됩니다

제한 사항

활성 인터넷 연결이 필요합니다
API 사용에는 AI 프로바이더의 속도 제한 및 비용이 적용됩니다
복잡한 쿼리는 여러 차례에 걸쳐 수정해야 할 수 있습니다
AI는 실제 데이터가 아니라 스키마 정보에만 읽기 전용으로 액세스할 수 있습니다

보안

API keys는 ClickHouse 서버로 전송되지 않습니다
AI는 실제 데이터가 아니라 스키마 정보(테이블/컬럼 이름 및 타입)만 봅니다
생성된 모든 쿼리는 기존 데이터베이스 권한을 준수합니다

연결 문자열

사용법

ClickHouse Client는 MongoDB, PostgreSQL, MySQL와 유사한 연결 문자열(connection string)을 사용해 ClickHouse 서버에 연결하는 것도 지원합니다. 구문은 다음과 같습니다:

clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]

구성 요소(모두 선택 사항)	설명	기본값
`user`	데이터베이스 사용자 이름입니다.	`default`
`password`	데이터베이스 사용자 비밀번호입니다. `:`가 지정되어 있고 비밀번호가 비어 있으면 클라이언트가 사용자 비밀번호 입력을 요청합니다.	-
`hosts_and_ports`	호스트와 선택적 포트 목록 `host[:port] [, host:[port]], ...`입니다.	`localhost:9000`
`database`	데이터베이스 이름입니다.	`default`
`query_parameters`	key-value 쌍 목록 `param1=value1[,&param2=value2], ...`입니다. 일부 매개변수는 값이 필요하지 않습니다. 매개변수 이름과 값은 대소문자를 구분합니다.	-

참고 사항

사용자 이름, 비밀번호 또는 데이터베이스를 연결 문자열에 지정한 경우 --user, --password 또는 --database로는 지정할 수 없습니다(그 반대도 마찬가지입니다). host component에는 호스트명 또는 IPv4/IPv6 주소를 사용할 수 있습니다. IPv6 주소는 []로 감싸야 합니다:

clickhouse://[2001:db8::1234]

연결 문자열에는 여러 호스트를 포함할 수 있습니다. ClickHouse Client는 이 호스트들에 순서대로(왼쪽에서 오른쪽으로) 연결을 시도합니다. 연결이 설정되면 나머지 호스트에는 연결을 시도하지 않습니다. 연결 문자열은 clickHouse-client의 첫 번째 인수로 지정해야 합니다. 연결 문자열은 --host 및 --port를 제외한 다른 명령줄 옵션과 원하는 만큼 함께 사용할 수 있습니다. query_parameters에는 다음 키를 사용할 수 있습니다:

Key	Description
`secure` (or `s`)	지정하면 클라이언트는 보안 연결(TLS)을 통해 서버에 연결합니다. 명령줄 옵션의 `--secure`를 참조하십시오.

퍼센트 인코딩 다음 매개변수에 포함된 US-ASCII 이외의 문자, 공백 및 특수 문자는 퍼센트 인코딩해야 합니다:

user
password
hosts
database
query parameters

예시

localhost의 9000번 포트에 연결하여 쿼리 SELECT 1을 실행합니다.

clickhouse-client clickhouse://localhost:9000 --query "SELECT 1"

localhost에 사용자 john, 비밀번호 secret, 호스트 127.0.0.1, 포트 9000을 사용해 연결합니다

clickhouse-client clickhouse://john:secret@127.0.0.1:9000

default 사용자로, IPV6 주소 [::1] 및 포트 9000을 사용하는 localhost 호스트에 연결합니다.

clickhouse-client clickhouse://[::1]:9000

멀티라인 모드로 포트 9000의 localhost에 연결합니다.

clickhouse-client clickhouse://localhost:9000 '-m'

default 사용자로 포트 9000을 사용해 localhost에 연결합니다.

clickhouse-client clickhouse://default@localhost:9000

# 동일한 표현:
clickhouse-client clickhouse://localhost:9000 --user default

localhost의 9000 포트에 연결하고 기본 데이터베이스는 my_database를 사용합니다.

clickhouse-client clickhouse://localhost:9000/my_database

# 동일한 표현:
clickhouse-client clickhouse://localhost:9000 --database my_database

localhost의 9000번 포트에 연결하고, 연결 문자열에 지정된 my_database 데이터베이스를 기본 데이터베이스로 사용하며, 축약형 s 매개변수로 보안 연결을 사용합니다.

clickhouse-client clickhouse://localhost/my_database?s

# 동일한 표현:
clickhouse-client clickhouse://localhost/my_database -s

기본 포트, 기본 사용자, 기본 데이터베이스를 사용해 기본 호스트에 연결합니다.

clickhouse-client clickhouse:

기본 포트를 사용하여 기본 호스트에 my_user 사용자로 비밀번호 없이 연결합니다.

clickhouse-client clickhouse://my_user@

# : 와 @ 사이에 빈 비밀번호를 사용하면 연결 시작 전에 사용자에게 비밀번호 입력을 요청합니다.
clickhouse-client clickhouse://my_user:@

사용자 이름으로 이메일 주소를 사용해 localhost에 연결합니다. @ 기호는 %40으로 퍼센트 인코딩됩니다.

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

다음 두 호스트 중 하나에 연결합니다: 192.168.1.15, 192.168.1.25.

clickhouse-client clickhouse://192.168.1.15,192.168.1.25

쿼리 ID 형식

대화형 모드에서 ClickHouse Client는 각 쿼리의 쿼리 ID를 표시합니다. 기본적으로 ID는 다음과 같은 형식입니다:

Query id: 927f137d-00f1-4175-8914-0dd066365e96

사용자 지정 포맷은 설정 파일의 query_id_formats 태그 내에서 지정할 수 있습니다. 포맷 문자열의 {query_id} 자리 표시자는 쿼리 ID로 대체됩니다. 태그 안에는 여러 개의 포맷 문자열을 지정할 수 있습니다. 이 기능은 쿼리 프로파일링을 쉽게 할 수 있도록 URL을 생성하는 데 사용할 수 있습니다. 예시

<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>

위 구성에서는 쿼리 ID가 다음과 같은 포맷으로 표시됩니다:

speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d

설정 파일

ClickHouse Client는 다음 경로 중 먼저 존재하는 파일을 사용합니다.

-c [ -C, --config, --config-file ] 매개변수로 지정한 파일
./clickhouse-client.[xml|yaml|yml]
$XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (XDG_CONFIG_HOME이 설정되어 있지 않으면 ~/.config/clickhouse/config.[xml|yaml|yml])
~/.clickhouse-client/config.[xml|yaml|yml]
/etc/clickhouse-client/config.[xml|yaml|yml]

예시 설정 파일은 ClickHouse 리포지토리에서 확인할 수 있습니다: clickhouse-client.xml

XML
YAML

<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

user: username
password: 'password'
secure: true
openSSL:
  client:
    caConfig: '/etc/ssl/cert.pem'

환경 변수 옵션

사용자 이름, 비밀번호, 호스트는 환경 변수 CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_HOST로 설정할 수 있습니다. 명령줄 인수 --user, --password, --host 또는 연결 문자열이 지정된 경우, 환경 변수보다 우선합니다.

명령줄 옵션

모든 명령줄 옵션은 명령줄에서 직접 지정하거나 설정 파일에서 기본값으로 지정할 수 있습니다.

일반 옵션

옵션	설명	기본값
`-c [ -C, --config, --config-file ] <path-to-file>`	클라이언트 설정 파일이 기본 위치 중 하나에 없을 경우, 해당 설정 파일의 위치를 지정합니다. 설정 파일을 참조하십시오.	-
`--help`	사용 요약을 출력한 후 종료합니다. `--verbose`와 함께 사용하면 쿼리 설정을 포함한 모든 옵션을 표시합니다.	-
`--history_file <path-to-file>`	명령 이력이 저장된 파일의 경로입니다.	-
`--history_max_entries`	이력 파일에 저장할 수 있는 최대 항목 수입니다.	`1000000` (100만)
`--prompt <prompt>`	사용자 지정 프롬프트를 설정합니다.	서버의 `display_name`
`--verbose`	출력 상세 수준을 높입니다.	-
`-V [ --version ]`	버전을 출력한 후 종료합니다.	-

연결 옵션

Option	Description	Default
`--connection <name>`	설정 파일에 있는 미리 구성된 연결 정보의 이름입니다. 연결 자격 증명을 참조하세요.	-
`-d [ --database ] <database>`	이 연결의 기본 데이터베이스로 사용할 데이터베이스를 선택합니다.	서버 설정의 현재 데이터베이스(기본값은 `default`)
`-h [ --host ] <host>`	연결할 ClickHouse 서버의 호스트명입니다. 호스트명 또는 IPv4/IPv6 주소를 사용할 수 있습니다. 여러 인수로 여러 호스트를 전달할 수도 있습니다.	`localhost`
`--jwt <value>`	인증에 JSON Web Token (JWT)을 사용합니다. 서버 JWT 인증은 ClickHouse Cloud에서만 사용할 수 있습니다.	-
`login`	IdP를 통해 인증하기 위해 device grant OAuth 흐름을 호출합니다. ClickHouse Cloud 호스트의 경우 OAuth 변수는 자동으로 추론되며, 그 외의 경우에는 `--oauth-url`, `--oauth-client-id`, `--oauth-audience`로 제공해야 합니다.	-
`--no-warnings`	클라이언트가 서버에 연결할 때 `system.warnings`의 경고를 표시하지 않습니다.	-
`--no-server-client-version-message`	클라이언트가 서버에 연결할 때 서버-클라이언트 버전 불일치 메시지를 표시하지 않습니다.	-
`--password <password>`	데이터베이스 사용자의 비밀번호입니다. 설정 파일에서 연결의 비밀번호를 지정할 수도 있습니다. 비밀번호를 지정하지 않으면 클라이언트가 비밀번호 입력을 요청합니다.	-
`--port <port>`	서버가 연결을 수락하는 포트입니다. 기본 포트는 9440(TLS) 및 9000(TLS 미사용)입니다. 참고: 클라이언트는 HTTP(S)가 아니라 네이티브 프로토콜을 사용합니다.	`--secure`가 지정되면 `9440`, 그렇지 않으면 `9000`입니다. 호스트명이 `.clickhouse.cloud`로 끝나면 항상 기본값은 `9440`입니다.
`-s [ --secure ]`	TLS 사용 여부입니다. 포트 9440(기본 보안 포트) 또는 ClickHouse Cloud에 연결할 때 자동으로 활성화됩니다. 설정 파일에서 CA 인증서를 구성해야 할 수 있습니다. 사용 가능한 구성 설정은 서버 측 TLS 구성과 동일합니다.	포트 9440 또는 ClickHouse Cloud에 연결할 때 자동으로 활성화됨
`--ssh-key-file <path-to-file>`	서버 인증에 사용할 SSH 개인 키가 들어 있는 파일입니다.	-
`--ssh-key-passphrase <value>`	`--ssh-key-file`에 지정한 SSH 개인 키의 패스프레이스입니다.	-
`--tls-sni-override <server name>`	TLS를 사용하는 경우 핸드셰이크에 전달할 서버 이름(SNI)입니다.	`-h` 또는 `--host`로 지정한 호스트입니다.
`-u [ --user ] <username>`	연결에 사용할 데이터베이스 사용자입니다.	`default`

--host, --port, --user, --password 옵션 대신 연결 문자열도 사용할 수 있습니다.

쿼리 옵션

Option	Description
`--param_<name>=<value>`	매개변수가 있는 쿼리의 매개변수에 대한 치환 값입니다.
`-q [ --query ] <query>`	batch mode에서 실행할 쿼리입니다. 여러 번 지정할 수 있으며(`--query "SELECT 1" --query "SELECT 2"`), 세미콜론으로 구분된 여러 쿼리를 한 번에 지정할 수도 있습니다(`--query "SELECT 1; SELECT 2;"`). 후자의 경우 `VALUES` 이외의 포맷을 사용하는 `INSERT` 쿼리는 빈 줄로 구분해야 합니다. 매개변수 없이 단일 쿼리를 지정할 수도 있습니다: `clickhouse-client "SELECT 1"` `--queries-file`과 함께 사용할 수 없습니다.
`--queries-file <path-to-file>`	쿼리가 들어 있는 파일의 경로입니다. `--queries-file`은 여러 번 지정할 수 있습니다. 예: `--queries-file queries1.sql --queries-file queries2.sql`. `--query`와 함께 사용할 수 없습니다.
`-m [ --multiline ]`	지정하면 여러 줄 쿼리를 허용합니다(Enter를 눌러도 쿼리가 전송되지 않음). 쿼리는 세미콜론으로 끝날 때만 전송됩니다.
`--inline-insert-data`	데이터를 Native 형식의 블록으로 변환하는 대신, `INSERT ... VALUES`(및 기타 인라인 포맷)를 쿼리 텍스트에 있는 그대로 전송합니다. 서버가 인라인 데이터를 직접 구문 분석하므로 테이블(table) 구조와 컬럼(column) 기본값을 클라이언트로 다시 보내는 왕복 과정을 피할 수 있습니다. 따라서 네이티브 프로토콜을 통해 많은 소규모 삽입을 수행할 때 성능이 향상될 수 있습니다. `send_table_structure_on_insert_with_inline_data`를 자동으로 `0`으로 설정합니다. 인라인 데이터와 외부 데이터(stdin 또는 `INFILE`의 데이터)는 함께 사용할 수 없습니다.

쿼리 설정

클라이언트에서 쿼리 설정은 명령줄 옵션으로 지정할 수 있습니다. 예를 들면 다음과 같습니다:

$ clickhouse-client --max_threads 1

설정에서 설정 목록을 확인하십시오.

포맷 옵션

옵션	설명	기본값
`-f [ --format ] <format>`	지정한 포맷으로 결과를 출력합니다. 지원되는 포맷 목록은 입력 및 출력 데이터 포맷을 참조하십시오.	`TabSeparated`
`--pager <command>`	모든 출력을 이 명령으로 전달합니다. 일반적으로 `less`(예: 가로로 긴 결과 집합을 표시하려면 `less -S`) 또는 이와 비슷한 명령을 사용합니다.	-
`-E [ --vertical ]`	결과를 출력할 때 Vertical 형식을 사용합니다. 이는 `--format Vertical`과 같습니다. 이 형식에서는 각 값이 별도의 줄에 출력되므로 열이 많은 테이블을 표시할 때 유용합니다.	-

실행 세부 정보

옵션	설명	기본값
`--enable-progress-table-toggle`	제어 키(Space)를 눌러 진행률 테이블 표시를 전환할 수 있도록 합니다. 진행률 테이블 출력이 활성화된 대화형 모드에서만 적용됩니다.	`enabled`
`--hardware-utilization`	진행률 표시줄에 하드웨어 사용률 정보를 출력합니다.	-
`--memory-usage`	지정하면 비대화형 모드에서 메모리 사용량을 `stderr`에 출력합니다. 가능한 값: • `none` - 메모리 사용량을 출력하지 않음 • `default` - 바이트 수를 출력 • `readable` - 사람이 읽기 쉬운 포맷으로 메모리 사용량을 출력	-
`--print-profile-events`	`ProfileEvents` 패킷을 출력합니다.	-
`--progress`	쿼리 실행 진행 상황을 출력합니다. 가능한 값: • `tty\|on\|1\|true\|yes` - 대화형 모드에서 터미널로 출력합니다 • `err` - 비대화형 모드에서 `stderr`로 출력합니다 • `off\|0\|false\|no` - 진행 상황 출력을 비활성화합니다	대화형 모드에서는 `tty`, 비대화형(배치) 모드에서는 `off`
`--progress-table`	쿼리 실행 중 변경되는 메트릭을 표시하는 진행률 테이블을 출력합니다. 가능한 값: • `tty\|on\|1\|true\|yes` - 대화형 모드에서 터미널로 출력합니다 • `err` - 비대화형 모드에서 `stderr`로 출력합니다 • `off\|0\|false\|no` - 진행률 테이블 출력을 비활성화합니다	대화형 모드에서는 `tty`, 비대화형(배치) 모드에서는 `off`
`--stacktrace`	예외의 스택 트레이스를 출력합니다.	-
`-t [ --time ]`	비대화형 모드에서 쿼리 실행 시간을 `stderr`에 출력합니다(벤치마크용).	-

​설치

​실행

​ClickHouse Cloud에 연결하기

​설정 파일에 연결 정보 저장하기

​대화형 모드

​대화형 모드 사용하기

​쿼리 처리 정보

​별칭

​키보드 단축키

​배치 모드

​배치 모드 사용하기

​원격 ClickHouse 서비스에 CSV 파일 삽입하기

​명령줄에서 데이터를 삽입하는 예시

​매개변수가 있는 쿼리

​쿼리 구문

​예시

​AI SQL 생성

​사용 방법

​예시

​구성

​환경 변수 기반 폴백

​설정 파일

​매개변수

​작동 방식

​제한 사항

​보안

​연결 문자열

​사용법

​참고 사항

​예시

​쿼리 ID 형식

​설정 파일

​환경 변수 옵션

​명령줄 옵션

​일반 옵션

​연결 옵션

​쿼리 옵션

​쿼리 설정

​포맷 옵션

​실행 세부 정보

설치

실행

ClickHouse Cloud에 연결하기

설정 파일에 연결 정보 저장하기

대화형 모드

대화형 모드 사용하기

쿼리 처리 정보

별칭

키보드 단축키

배치 모드

배치 모드 사용하기

원격 ClickHouse 서비스에 CSV 파일 삽입하기

명령줄에서 데이터를 삽입하는 예시

매개변수가 있는 쿼리

쿼리 구문

예시

AI SQL 생성

사용 방법

예시

구성

환경 변수 기반 폴백

설정 파일

매개변수

작동 방식

제한 사항

보안

연결 문자열

사용법

참고 사항

예시

쿼리 ID 형식

설정 파일

환경 변수 옵션

명령줄 옵션

일반 옵션

연결 옵션

쿼리 옵션

쿼리 설정

포맷 옵션

실행 세부 정보