ClickHouse 클라이언트

ClickHouse 클라이언트 (ClickHouse Client)

ClickHouse는 ClickHouse 서버에 직접 SQL 쿼리를 실행하기 위한 네이티브 명령줄 클라이언트를 제공해요. 대화형 모드(실시간 쿼리 실행)와 배치 모드(스크립팅과 자동화)를 모두 지원하며, 모든 ClickHouse 출력 포맷을 사용할 수 있어요.

출처: 문서

본문

ClickHouse는 ClickHouse 서버에 직접 SQL 쿼리를 실행하기 위한 네이티브 명령줄 클라이언트를 제공해요. 대화형 모드(실시간 쿼리 실행용)와 배치 모드(스크립팅과 자동화용)를 모두 지원해요. 쿼리 결과는 Pretty, CSV, JSON 등 모든 ClickHouse 출력 포맷을 지원하며 터미널에 표시하거나 파일로 내보낼 수 있어요.

클라이언트는 진행 표시줄, 읽은 행 수, 처리된 바이트 수, 쿼리 실행 시간으로 쿼리 실행에 대한 실시간 피드백을 제공해요. 명령줄 옵션과 설정 파일을 모두 지원해요.

설치 (Install)

ClickHouse를 다운로드하려면:

curl https://clickhouse.com/ | sh

설치하려면 다음도 실행해요:

sudo ./clickhouse install

더 많은 설치 옵션은 ClickHouse 설치를 참고해요.

클라이언트와 서버 버전은 서로 호환되지만 일부 기능은 구형 클라이언트에서 사용하지 못할 수 있어요. 클라이언트와 서버에 같은 버전을 사용하는 것을 권장해요.

실행 (Run)

참고: 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 없음). --port와 --secure가 모두 지정되지 않으면 두 기본 포트가 동시에 시도되고 먼저 응답하는 쪽이 사용되므로, 그중 하나만 듣는 서버는 다른 쪽의 연결 타임아웃을 기다리지 않고 연결돼요. ClickHouse 클라이언트는 HTTP(S)가 아니라 네이티브 프로토콜을 사용한다는 점에 주의하세요.
-s [ --secure ]	TLS 사용 여부 (보통 자동 감지).
-u [ --user ] <username>	연결할 데이터베이스 사용자. 기본적으로 default 사용자로 연결.
--password <password>	데이터베이스 사용자의 비밀번호. 설정 파일에서 연결에 대한 비밀번호를 지정할 수도 있어요. 비밀번호를 지정하지 않으면 클라이언트가 물어봐요.
-c [ --config ] <path-to-file>	기본 위치 중 하나에 없을 때 ClickHouse 클라이언트의 설정 파일 위치. 설정 파일 참조.
--connection <name>	설정 파일에서 사전 구성된 연결 세부 정보의 이름.

명령줄 옵션의 전체 목록은 명령줄 옵션을 참고해요.

ClickHouse Cloud에 연결 (Connecting to ClickHouse Cloud)

ClickHouse Cloud 서비스에 대한 세부 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있어요. 연결할 서비스를 선택하고 Connect를 클릭하세요:

Native를 선택하면 예시 clickhouse-client 명령과 함께 세부 정보가 표시돼요.

설정 파일에 연결 저장 (Storing connections in a configuration file)

하나 이상의 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 등)를 생략해요. 명령을 사용할 때 추가하는 것을 기억하세요.

대화형 모드 (Interactive mode)

대화형 모드 사용 (Using interactive mode)

대화형 모드로 ClickHouse를 실행하려면 간단히:

clickhouse-client

이것은 Read-Eval-Print Loop (REPL)을 열고, 여기서 대화형으로 SQL 쿼리 입력을 시작할 수 있어요. 연결되면 쿼리를 입력할 프롬프트를 받아요:

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 클라이언트는 replxx(readline과 유사)를 기반으로 하므로 익숙한 키보드 단축키를 사용하고 기록을 유지해요. 기록은 기본적으로 ~/.clickhouse-client-history에 쓰여요.

클라이언트를 종료하려면 Ctrl+D를 누르거나, 쿼리 대신 다음 중 하나를 입력하세요:

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

도움말 보기 (Getting help)

클라이언트를 떠나지 않고 어떤 함수, 테이블 엔진, 데이터 타입, 포맷, 설정 및 시스템의 다른 구성 요소의 문서를 찾아볼 수 있어요. 이름 뒤에 help를 입력하세요(동등한 형식 /help, man, /man도 동작):

help domainWithoutWWW

검색은 대소문자를 구분하지 않으며 system.documentation 테이블을 조회해요. 일치하는 문서는 터미널에서 Markdown으로 렌더링되며, 굵게/기울임 텍스트, 표, 구문 강조 코드 블록을 포함해요. 여러 구성 요소가 이름을 공유하면(예: 함수이자 테이블 엔진인 file) 모두 표시돼요.

정확히 일치하는 것이 없으면 클라이언트는 비슷한 이름(오타 허용)과 문서에서 그 단어를 언급하는 구성 요소를 나열해요:

help maxx_threads

help만 입력하면 짧은 사용 요약을 출력해요.

명령 (Commands)

클라이언트는 서버로 보내는 대신 / 접두사가 붙은 몇 가지 명령을 직접 실행해요:

명령	설명
/help <name>, /man <name>	<name>의 문서를 보여줌. 위의 help와 같음
/clear	터미널 지우기

입력 시작 부분에 /를 입력하면 명령을 힌트로 나열하고, 이름을 더 입력하면 목록이 좁혀져요. Tab은 입력 중인 명령을 완성하며, 힌트가 비활성화된 경우에도 명령이 완성되는 방식이에요. 그 자체로 제출된 /는 명령이 아니에요. Oracle SQL*Plus에서처럼 마지막 입력을 반복해요. 철자가 틀린 명령 이름은 쿼리로 실행되지 않고, 뜻했을 수 있는 명령과 함께 보고돼요:

:) /hepl

Exception on client:
Code: 36. DB::Exception: Unknown command `/hepl`. Maybe you meant: ['/help']. Type `/` at the beginning of the line to see all the commands. (BAD_ARGUMENTS)

쿼리 처리 정보 (Query processing information)

쿼리를 처리할 때 클라이언트는 다음을 보여줘요:

1. 진행 상황. 기본적으로 초당 10회 이하로 갱신돼요. 빠른 쿼리의 경우 진행이 표시될 시간이 없을 수 있어요.
2. 파싱 후 포맷된 쿼리. 디버깅용.
3. 지정된 포맷의 결과.
4. 결과의 줄 수, 경과 시간, 쿼리 처리 평균 속도. 모든 데이터 양은 압축되지 않은 데이터를 말해요.

Ctrl+C를 눌러 긴 쿼리를 취소할 수 있어요. 하지만 서버가 요청을 중단할 때까지 조금 기다려야 해요. 특정 단계에서는 쿼리를 취소할 수 없어요. 기다리지 않고 두 번째로 Ctrl+C를 누르면 클라이언트가 종료돼요.

ClickHouse 클라이언트는 쿼리에 외부 데이터(외부 임시 테이블)를 전달할 수 있어요. 자세한 내용은 쿼리 처리를 위한 외부 데이터 섹션을 참고해요.

별칭 (Aliases)

REPL 안에서 다음 별칭을 사용할 수 있어요:

• \l - SHOW DATABASES
• \d - SHOW TABLES
• \d <TABLE> - DESCRIBE TABLE <TABLE>
• \c <DATABASE> - USE <DATABASE>
• . - 마지막 쿼리 반복

테이블을 이름 짓는 대신 SHOW TABLES 쿼리를 이어가는 \d의 인수 — \d FROM system 또는 \d LIKE 'hits%'처럼 — 는 목록을 유지해요. 그런 절 중 하나로 철자된 테이블 이름은 따옴표로 묶어야 해요: \d format``.

키보드 단축키 (Keyboard shortcuts)

• Alt (Option) + Shift + e - 현재 쿼리로 편집기를 엽니다. EDITOR 환경 변수로 사용할 편집기를 지정할 수 있어요. 기본적으로 vim이 사용돼요.
• Alt (Option) + # - 줄을 주석 처리.
• Ctrl + r - 퍼지(fuzzy) 기록 검색.

사용 가능한 모든 키보드 단축키의 전체 목록은 replxx에서 볼 수 있어요.

팁: macOS에서 메타 키(Option)의 올바른 동작을 설정하려면: iTerm2: Preferences -> Profile -> Keys -> Left Option key로 이동해 Esc+를 클릭하세요.

배치 모드 (Batch mode)

배치 모드 사용 (Using batch mode)

ClickHouse 클라이언트를 대화형으로 사용하는 대신 배치 모드로 실행할 수 있어요. 배치 모드에서 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가 지정되면 모든 입력이 줄바꿈 뒤에 요청에 추가돼요.

로컬에서 CSV 파일을 원격 ClickHouse 서비스에 삽입 (Inserting a CSV file into a remote ClickHouse service)

이 예시는 샘플 데이터 세트 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

명령줄에서 데이터 삽입 예시 (Examples of inserting data from the command line)

명령줄에서 데이터를 삽입하는 방법은 여러 가지가 있어요. 아래 예시는 배치 모드를 사용해 두 행의 CSV 데이터를 ClickHouse 테이블에 삽입해요:

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는 _EOF를 다시 볼 때까지 모든 것을 읽는 heredoc을 시작한 다음 그것을 출력해요:

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

아래 예시에서 file.csv의 내용은 cat을 사용해 stdout으로 출력되고 clickhouse-client에 입력으로 파이프돼요:

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

배치 모드에서 기본 데이터 포맷은 TabSeparated예요. 위 예시에서 보여준 것처럼 쿼리의 FORMAT 절에서 포맷을 설정할 수 있어요.

파라미터가 있는 쿼리 (Queries with parameters)

쿼리에 파라미터를 지정하고 명령줄 옵션으로 값을 전달할 수 있어요. 이렇게 하면 클라이언트 측에서 특정 동적 값으로 쿼리를 포맷하는 것을 피할 수 있어요. 예를 들어:

$ 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.

쿼리 구문 (Query syntax)

쿼리에서 명령줄 파라미터로 채우고 싶은 값을 다음 형식으로 중괄호 안에 넣어요:

{<name>:<data type>}

파라미터	설명
name	자리 표시자 식별자. 대응하는 명령줄 옵션은 --param_<name> = value이에요.
data type	파라미터의 데이터 타입.

예를 들어 (integer, ('string', integer)) 같은 데이터 구조는 Tuple(UInt8, Tuple(String, UInt8)) 데이터 타입을 가질 수 있어요(다른 정수 타입도 사용 가능).

테이블 이름, 데이터베이스 이름, 열 이름을 파라미터로 전달하는 것도 가능하며, 그 경우 데이터 타입으로 Identifier를 사용해야 해요.

예시 (Examples)

$ 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 생성 (AI-powered SQL generation)

ClickHouse 클라이언트는 자연어 설명에서 SQL 쿼리를 생성하는 내장 AI 지원을 포함해요. 이 기능은 SQL에 대한 깊은 지식 없이 복잡한 쿼리를 작성하는 데 도움을 줍니다.

OPENAI_API_KEY 또는 ANTHROPIC_API_KEY 환경 변수 중 하나가 설정되어 있으면 AI 지원이 별도 설정 없이 동작해요. 더 고급 설정은 설정 섹션을 참고해요.

사용법 (Usage)

AI SQL 생성을 사용하려면 자연어 쿼리 앞에 ??를 붙이세요:

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

AI는 다음을 수행해요:

1. 데이터베이스 스키마를 자동으로 탐색
2. 발견된 테이블과 열에 기반해 적절한 SQL 생성
3. 생성된 쿼리를 즉시 실행

예시 (Example)

:) ?? 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

설정 (Configuration)

AI SQL 생성은 ClickHouse 클라이언트 설정 파일에서 AI 제공자를 설정해야 해요. OpenAI, Anthropic, 또는 OpenAI 호환 API 서비스를 사용할 수 있어요.

환경 기반 폴백 (Environment-based fallback)

설정 파일에 AI 설정이 지정되지 않으면 ClickHouse 클라이언트는 자동으로 환경 변수를 사용하려 시도해요:

1. 먼저 OPENAI_API_KEY 환경 변수를 확인
2. 없으면 ANTHROPIC_API_KEY 환경 변수를 확인
3. 둘 다 없으면 AI 기능이 비활성화

이것은 설정 파일 없이 빠른 설정을 가능하게 해요:

# Using OpenAI
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# Using Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

설정 파일 (Configuration file)

AI 설정을 더 제어하려면 ClickHouse 클라이언트 설정 파일에 구성해요. 위치:

• $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로 사용자 정의 위치 지정

<config>
    <ai>
        {/* Required: Your API key (or set via environment variable) */}
        <api_key>your-api-key-here</api_key>

        {/* Required: Provider type (openai, anthropic) */}
        <provider>openai</provider>

        {/* Model to use (defaults vary by provider) */}
        <model>gpt-4o</model>

        {/* Optional: Custom API endpoint for OpenAI-compatible services */}
        {/* <base_url>https://openrouter.ai/api</base_url> */}

        {/* Schema exploration settings */}
        <enable_schema_access>true</enable_schema_access>

        {/* Generation parameters */}
        {/* Optional: temperature is only sent to the model when set here.
             It is omitted by default because some models reject this parameter. */}
        {/* <temperature>0.0</temperature> */}
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        {/* Optional: Custom system prompt */}
        {/* <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> */}
    </ai>
</config>

ai:
  # Required: Your API key (or set via environment variable)
  api_key: your-api-key-here

  # Required: Provider type (openai, anthropic)
  provider: openai

  # Model to use
  model: gpt-4o

  # Optional: Custom API endpoint for OpenAI-compatible services
  # base_url: https://openrouter.ai/api

  # Enable schema access - allows AI to query database/table information
  enable_schema_access: true

  # Generation parameters
  # temperature is only sent to the model when set here; omitted by default
  # because some models reject this parameter.
  # temperature: 0.0    # Controls randomness (0.0 = deterministic)
  max_tokens: 1000      # Maximum response length
  timeout_seconds: 30   # Request timeout
  max_steps: 10         # Maximum schema exploration steps

  # Optional: Custom system prompt
  # system_prompt: |
  #   You are an expert ClickHouse SQL assistant. Convert natural language to SQL.
  #   Focus on performance and use ClickHouse-specific optimizations.
  #   Always return executable SQL without explanations.

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

ai:
  provider: openai  # Use 'openai' for compatibility
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # Use OpenRouter model naming

최소 구성 예시 (Minimal configuration examples):

# Minimal config - uses environment variable for API key
ai:
  provider: openai  # Will use OPENAI_API_KEY env var

# No config at all - automatic fallback
# (Empty or no ai section - will try OPENAI_API_KEY then ANTHROPIC_API_KEY)

# Only override model - uses env var for API key
ai:
  provider: openai
  model: gpt-3.5-turbo

파라미터 (Parameters)

필수 파라미터

api_key - AI 서비스의 API 키. 환경 변수로 설정하면 생략 가능:

OpenAI: OPENAI_API_KEY Anthropic: ANTHROPIC_API_KEY 참고: 설정 파일의 API 키가 환경 변수보다 우선해요

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 = 결정적, 1.0 = 창의적. 기본적으로 생략되며 일부 모델이 이 파라미터를 거부하므로 명시적으로 설정할 때만 모델로 보내져요. max_tokens - 최대 응답 길이(토큰) (기본: 1000) system_prompt - AI에 대한 사용자 정의 지침 (선택)

어떻게 동작하나 (How it works)

AI SQL 생성기는 다단계 프로세스를 사용해요:

1. 스키마 발견 (Schema Discovery)

AI는 내장 도구로 데이터베이스를 탐색해요

• 사용 가능한 데이터베이스 나열
• 관련 데이터베이스 안의 테이블 발견
• CREATE TABLE 문으로 테이블 구조 검사

2. 쿼리 생성 (Query Generation)

발견된 스키마를 기반으로 AI는 다음을 수행하는 SQL을 생성해요:

• 자연어 의도와 일치
• 올바른 테이블과 열 이름 사용
• 적절한 조인과 집계 적용

3. 실행 (Execution)

생성된 SQL이 자동으로 실행되고 결과가 표시돼요

제한 사항 (Limitations)

• 활성 인터넷 연결이 필요
• API 사용은 AI 제공자의 비율 제한과 비용이 적용됨
• 복잡한 쿼리는 여러 번의 개선이 필요할 수 있음
• AI는 실제 데이터가 아니라 스키마 정보에만 읽기 전용 접근을 가짐

보안 (Security)

• API 키는 ClickHouse 서버로 절대 보내지지 않음
• AI는 실제 데이터가 아닌 스키마 정보(테이블/열 이름과 타입)만 봄
• 모든 생성된 쿼리는 기존 데이터베이스 권한을 존중

연결 문자열 (Connection string)

사용법 (Usage)

ClickHouse 클라이언트는 대안으로 MongoDB, PostgreSQL, MySQL과 유사한 연결 문자열로 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	키-값 쌍의 목록 param1=value1[,&param2=value2], .... 일부 파라미터는 값이 필요 없어요. 파라미터 이름과 값은 대소문자를 구분해요.	-

참고 사항 (Notes)

사용자 이름, 비밀번호 또는 데이터베이스가 연결 문자열에 지정되었다면 --user, --password 또는 --database로 지정할 수 없어요(그 반대도 마찬가지).

호스트 구성 요소는 호스트 이름 또는 IPv4/IPv6 주소일 수 있어요. IPv6 주소는 [] 안에 있어야 해요:

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

연결 문자열은 여러 호스트를 포함할 수 있어요. ClickHouse 클라이언트는 이 호스트들에 순서대로(왼쪽에서 오른쪽으로) 연결을 시도해요. 연결이 확립된 후에는 나머지 호스트에 대한 연결 시도가 없어요.

연결 문자열은 clickhouse-client의 첫 번째 인수로 지정해야 해요. 연결 문자열은 --host와 --port를 제외한 임의의 수의 다른 명령줄 옵션과 결합할 수 있어요.

query_parameters에 허용되는 키:

키	설명
secure (또는 s)	지정하면 클라이언트가 보안 연결(TLS)로 서버에 연결. 명령줄 옵션의 --secure 참조.

퍼센트 인코딩

다음 파라미터의 비-US ASCII, 공백 및 특수 문자는 퍼센트 인코딩되어야 해요:

• user
• password
• hosts
• database
• query parameters

예시 (Examples)

포트 9000의 localhost에 연결하고 SELECT 1 쿼리를 실행.

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

사용자 john, 비밀번호 secret, 호스트 127.0.0.1, 포트 9000으로 localhost에 연결.

clickhouse-client clickhouse://john:[email protected]:9000

default 사용자로, IPv6 주소 [::1], 포트 9000의 호스트에 연결.

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

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

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

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

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

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --user default

포트 9000의 localhost에 연결하고 기본 데이터베이스를 my_database로.

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

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --database my_database

포트 9000의 localhost에 연결하고 연결 문자열에서 지정된 my_database 데이터베이스를 기본으로, 약식 s 파라미터로 보안 연결을 사용.

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

# equivalent to:
clickhouse-client clickhouse://localhost/my_database -s

기본 호스트에 기본 포트, 기본 사용자, 기본 데이터베이스로 연결.

clickhouse-client clickhouse:

기본 호스트에 기본 포트로, 사용자 my_user와 비밀번호 없이 연결.

clickhouse-client clickhouse://my_user@

# Using a blank password between : and @ means to asking the user to enter the password before starting the connection.
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 포맷 (Query ID format)

대화형 모드에서 ClickHouse 클라이언트는 모든 쿼리에 대해 쿼리 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

설정 파일 (Configuration files)

ClickHouse 클라이언트는 다음 중 첫 번째로 존재하는 파일을 사용해요:

• -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

<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'

환경 변수 옵션 (Environment variable options)

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

명령줄 옵션 (Command-line options)

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

일반 옵션 (General options)

옵션	설명	기본값
-c [ -C, --config, --config-file ] <path-to-file>	기본 위치 중 하나에 없을 때 클라이언트의 설정 파일 위치. 설정 파일 참조.	-
--help	사용 요약을 출력하고 종료. 모든 가능한 옵션(쿼리 설정 포함)을 표시하려면 --verbose와 결합.	-
--history_file <path-to-file>	명령 기록을 담은 파일 경로.	-
--history_max_entries	기록 파일의 최대 항목 수.	1000000 (백만)
--prompt <prompt>	사용자 정의 프롬프트 지정.	서버의 display_name
--verbose	출력 상세 정도 증가.	-
-V [ --version ]	버전 출력 후 종료.	-

연결 옵션 (Connection options)

옵션	설명	기본값
--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 기본값. --port와 --secure가 모두 지정되지 않으면 포트 9000과 9440이 동시에 프로브되고 먼저 응답하는 쪽이 사용돼요. | | -s [ --secure ] | TLS 사용 여부. |

포트 9440(기본 보안 포트) 또는 ClickHouse Cloud에 연결할 때 자동 활성화되고, --port와 --secure가 모두 지정되지 않아 프로브에 보안 포트가 먼저 응답하는 경우에도 자동 활성화되는데, 이는 보안 포트에서만 응답하는 서버(예: 일반 포트가 방화벽으로 막힌 play.clickhouse.com)에서 항상 해당하며 두 포트 모두에서 듣는 서버에서도 해당할 수 있어요. 그 경우 TLS가 요청되지 않았으므로 사용 불가해 보이는 보안 포트(예: 신뢰할 수 없는 인증서)는 오류가 아니에요. 클라이언트는 자동 선택 없이 연결했을 것 같은 일반 포트로 폴백해요. TLS를 요구하려면 --secure를 지정하세요. | 설정 파일에서 CA 인증서를 구성해야 할 수 있어요. 사용 가능한 구성 설정은 서버 측 TLS 설정과 같아요. | 포트 9440 또는 ClickHouse Cloud에 연결할 때 자동 활성화 | | --ssh-key-file [path-to-file] | 서버와 인증할 SSH 개인 키를 담은 파일. |

파일 이름은 생략할 수 있어요. 클라이언트는 ~/.ssh/config에서 이 호스트에 구성된 첫 번째 사용 가능한 신원 파일을 선택한 다음 ~/.ssh/id_ed25519 같은 기본 신원 파일을 선택해요. 각 신원에 대해 ssh-agent가 보유한 사본이 암호가 필요 없으므로 선호돼요. 에이전트는 일치하는 IdentityAgent 설정 또는 구성되지 않았을 때 SSH_AUTH_SOCK으로 선택돼요. | - | | --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 옵션 대신 클라이언트는 연결 문자열도 지원해요.

쿼리 옵션 (Query options)

옵션	설명
--param_<name>=<value>	파라미터가 있는 쿼리의 파라미터에 대한 치환 값.
-q [ --query ] <query>	배치 모드에서 실행할 쿼리. 여러 번 지정할 수 있고(--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 | INSERT ... VALUES(및 기타 인라인 포맷)를 데이터를 네이티브 포맷의 블록으로 변환하는 대신 쿼리 텍스트로 그대로 보냄. 서버가 인라인 데이터를 직접 파싱해 테이블 구조와 열 기본값을 클라이언트로 되돌려 보내는 왕복을 피해요. 이는 네이티브 프로토콜에서 많은 작은 insert의 성능을 개선할 수 있어요. send_table_structure_on_insert_with_inline_data을 자동으로 0으로 설정. 인라인 데이터와 외부 데이터(stdin 또는 INFILE에서)와 결합할 수 없어요. |

쿼리 설정 (Query settings)

클라이언트에서 명령줄 옵션으로 쿼리 설정을 지정할 수 있어요, 예를 들어:

$ clickhouse-client --max_threads 1

설정 목록은 설정을 참고해요.

포맷팅 옵션 (Formatting options)

옵션	설명	기본값
-f [ --format ] <format>	결과를 출력할 지정 포맷 사용.

지원되는 포맷 목록은 입출력 데이터 포맷 참조. | TabSeparated | | --pager <command> | 모든 출력을 이 명령으로 파이프. 보통 less(예: 넓은 결과 세트를 표시하려면 less -S) 또는 유사한 것. | - | | -E [ --vertical ] | Vertical 포맷으로 결과 출력. –-format Vertical과 같음. 이 포맷에서 각 값은 별도 줄에 인쇄되어 넓은 테이블 표시에 유용해요. | - | | --echo [ <bool> ] | 실행 전에 각 쿼리 출력. 선택적 부울 값 받음. | 대화형 모드에서 true, 비대화형(배치) 모드에서 false | | --echo-formatted [ <bool> ] | 에코된 쿼리 포맷. 선택적 부울 값 받음. | 대화형 모드에서 true, 비대화형(배치) 모드에서 false | | --echo-query-id [ <bool> ] | 실행 전에 쿼리 id 출력. 선택적 부울 값 받음. | 대화형 모드에서 true, 비대화형(배치) 모드에서 false | | --echo-query-separator <string> | 포맷된 에코 쿼리 전에 이 구분자를 출력(--echo-formatted 필요). 입력한 쿼리와 재포맷된 에코를 구분하기 쉽게 함. | 빈 (비활성화) | | --highlight [ --hilite ] <bool> | 명령 프롬프트와 에코된 쿼리의 구문 강조 토글. | true | | --hints <bool> | 커서가 입력 끝에 있을 때 가장 잘 일치하는 제안을 위한 입력 중 자동 완성 힌트(인라인 "유령" 텍스트) 표시. Up/Down(또는 Ctrl-Up/Ctrl-Down)으로 힌트 탐색; Tab 또는 Right로 인라인 힌트 수락; Enter는 명시적으로 선택된 후에만 힌트를 수락하고 그렇지 않으면 쿼리를 실행; Tab은 클래식 완성 목록도 엽니다. --highlight 필요(힌트에 색상 필요). 제안 힌트는 제안 메커니즘도 필요하므로 --disable_suggestion이 그것들을 끔; 클라이언트의 /-명령은 정적 목록이며 --hints와 --highlight가 켜져 있는 한 힌트가 유지돼요. Tab은 힌트가 꺼져 있어도 /-명령을 완성해요. | true |

실행 세부 정보 (Execution details)

옵션	설명	기본값
--chime [N]	쿼리가 완료되면(성공 및 오류 시) 최소 N초 동안 실행된 후 BEL 제어 문자를 stderr에 씀. stderr가 터미널(TTY)에 연결된 경우에만 출력. stderr 리디렉션(예: 2>err.log)은 억제하고, stdout 리디렉션(예: > result.tsv)은 억제하지 않음. 값 없이 --chime을 전달하면 기본 임계값 사용. --chime 0으로 비활성화.	5초
--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로 출력 (벤치마크용). | - |

더 알아보기 (Learn more)

• clickhousectl
• 드라이버 및 인터페이스 (Drivers and interfaces)
• 네이티브 인터페이스 (TCP)