> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ClickHouse command-line client 인터페이스에 대한 문서 # ClickHouse Client export const Image = ({img, alt, size}) => { return {alt} ; }; ClickHouse는 ClickHouse 서버에 직접 SQL 쿼리를 실행할 수 있는 네이티브 command-line client를 제공합니다. 이 client는 대화형 모드(interactive mode)와 배치 모드(배치 모드)를 모두 지원하며, 각각 실시간 쿼리 실행과 스크립팅 및 자동화에 사용할 수 있습니다. 쿼리 결과는 터미널에 표시하거나 파일로 내보낼 수 있으며, Pretty, CSV, JSON 등을 포함한 모든 ClickHouse 출력 [포맷](/ko/reference/formats)을 지원합니다. 이 client는 진행률 표시줄과 읽은 행 수, 처리된 바이트 수, 쿼리 실행 시간 등을 통해 쿼리 실행 상태를 실시간으로 보여줍니다. 또한 [명령줄 옵션](#command-line-options)과 [설정 파일](#configuration_files)을 모두 지원합니다.
## 설치
ClickHouse를 다운로드하려면 다음 명령을 실행하세요: ```bash theme={null} curl https://clickhouse.com/ | sh ``` 추가로 설치하려면 다음을 실행하세요: ```bash theme={null} sudo ./clickhouse install ``` 추가 설치 옵션은 [ClickHouse 설치](/ko/get-started/setup/install)를 참조하십시오. 서로 다른 클라이언트 버전과 서버 버전도 호환되지만, 일부 기능은 이전 버전의 클라이언트에서 사용할 수 없을 수 있습니다. 클라이언트와 서버는 동일한 버전을 사용하는 것을 권장합니다.
## 실행
ClickHouse를 다운로드만 하고 설치하지 않았다면 `clickhouse-client` 대신 `./clickhouse client`를 사용하세요. ClickHouse 서버에 연결하려면 다음을 실행하세요: ```bash theme={null} $ 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 ` | ClickHouse 서버가 연결을 수신하는 포트입니다. 기본 포트는 9440(TLS) 및 9000(TLS 미사용)입니다. ClickHouse Client는 HTTP(S)가 아니라 네이티브 프로토콜을 사용한다는 점에 유의하십시오. | | `-s [ --secure ]` | TLS를 사용할지 여부입니다(대개 자동으로 감지됩니다). | | `-u [ --user ] ` | 연결할 때 사용할 데이터베이스 사용자입니다. 기본적으로 `default` 사용자로 연결됩니다. | | `--password ` | 데이터베이스 사용자의 비밀번호입니다. 연결에 사용할 비밀번호는 설정 파일에서 지정할 수도 있습니다. 비밀번호를 지정하지 않으면 클라이언트가 입력을 요청합니다. | | `-c [ --config ] ` | ClickHouse Client의 설정 파일이 기본 위치 중 하나에 없을 경우 해당 설정 파일의 위치입니다. [설정 파일](#configuration_files)을 참조하십시오. | | `--connection ` | [설정 파일](#connection-credentials)에 미리 구성된 연결 정보의 이름입니다. | 명령줄 옵션의 전체 목록은 [명령줄 옵션](#command-line-options)을 참조하십시오.
### ClickHouse Cloud에 연결하기
ClickHouse Cloud 서비스의 연결 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다. 연결할 서비스를 선택한 다음 **Connect**를 클릭하십시오: ClickHouse Cloud 서비스 연결 버튼

**Native**를 선택하면 예시 `clickhouse-client` 명령과 함께 연결 세부 정보가 표시됩니다: ClickHouse Cloud 네이티브 TCP 연결 세부 정보
### 설정 파일에 연결 정보 저장하기
하나 이상의 ClickHouse 서버에 대한 연결 정보를 [설정 파일](#configuration_files)에 저장할 수 있습니다. 형식은 다음과 같습니다: ```xml theme={null} default hostname 9440 1 default password ``` 자세한 내용은 [설정 파일 섹션](#configuration_files)을 참조하십시오. 쿼리 구문에 집중하기 위해 나머지 예시에서는 접속 정보(`--host`, `--port` 등)를 생략합니다. 명령을 사용할 때는 이를 추가하십시오.
## 대화형 모드
### 대화형 모드 사용하기
ClickHouse를 대화형 모드로 실행하려면 다음을 실행하세요: ```bash theme={null} clickhouse-client ``` 그러면 SQL 쿼리를 대화형으로 입력할 수 있는 Read-Eval-Print Loop (REPL)가 열립니다. 연결되면 쿼리를 입력할 수 있는 프롬프트가 표시됩니다: ```bash theme={null} 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;`
### 쿼리 처리 정보
쿼리를 처리하는 동안 클라이언트는 다음을 표시합니다. 1. 진행 상황으로, 기본적으로 초당 10회를 넘지 않도록 갱신됩니다. 쿼리가 매우 빠르면 진행 상황이 표시되기 전에 처리가 끝날 수 있습니다. 2. 디버깅을 위한 구문 분석 후의 포맷팅된 쿼리. 3. 지정된 포맷의 결과. 4. 결과의 행 수, 경과 시간, 쿼리 처리의 평균 속도. 모든 데이터 양은 비압축 데이터를 기준으로 합니다. 오래 걸리는 쿼리는 `Ctrl+C`를 눌러 취소할 수 있습니다. 하지만 server가 요청을 중단할 때까지는 잠시 기다려야 합니다. 특정 단계에서는 쿼리를 취소할 수 없습니다. 기다리지 않고 `Ctrl+C`를 한 번 더 누르면 클라이언트가 종료됩니다. ClickHouse Client는 쿼리에 사용할 외부 데이터(외부 임시 테이블)를 전달할 수 있습니다. 자세한 내용은 [쿼리 처리용 외부 데이터](/ko/reference/engines/table-engines/special/external-data) 섹션을 참조하십시오.
### 별칭
REPL에서는 다음 별칭을 사용할 수 있습니다: * `\l` - SHOW DATABASES * `\d` - SHOW TABLES * `\c ` - USE DATABASE * `.` - 마지막 쿼리 다시 실행
### 키보드 단축키
* `Alt (Option) + Shift + e` - 현재 쿼리로 편집기를 엽니다. 환경 변수 `EDITOR`를 사용해 편집기를 지정할 수 있습니다. 기본 편집기는 `vim`입니다. * `Alt (Option) + #` - 현재 줄을 주석 처리합니다. * `Ctrl + r` - 퍼지 이력 검색을 수행합니다. 사용 가능한 모든 키보드 단축키의 전체 목록은 [replxx](https://github.com/AmokHuginnsson/replxx/blob/1f149bf/src/replxx_impl.cxx#L262)에서 확인할 수 있습니다. MacOS에서 메타 키(Option)가 올바르게 동작하도록 설정하려면 다음과 같이 하십시오: iTerm2: Preferences -> Profile -> Keys -> Left Option key로 이동한 다음 Esc+를 클릭하십시오
## 배치 모드
### 배치 모드 사용하기
ClickHouse Client를 대화형으로 사용하는 대신 배치 모드로 실행할 수 있습니다. 배치 모드에서는 ClickHouse가 단일 쿼리 하나를 실행한 후 즉시 종료됩니다. 대화형 프롬프트나 반복 실행 루프는 없습니다. 다음과 같이 단일 쿼리를 지정할 수 있습니다: ```bash theme={null} $ clickhouse-client "SELECT sum(number) FROM numbers(10)" 45 ``` 다음과 같이 `--query` 명령줄 옵션을 사용할 수도 있습니다: ```bash theme={null} $ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)" 10 ``` `stdin`을 통해 쿼리를 제공할 수 있습니다: ```bash theme={null} $ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client 4.5 ``` `messages` 테이블이 존재한다고 가정하면, 명령줄에서도 데이터를 삽입할 수 있습니다: ```bash theme={null} $ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV" ``` `--query`를 지정하면 모든 입력이 개행 문자 뒤에 요청에 추가됩니다.
### 원격 ClickHouse 서비스에 CSV 파일 삽입하기
이 예시에서는 샘플 데이터셋이 담긴 CSV 파일 `cell_towers.csv`를 `default` 데이터베이스의 기존 테이블 `cell_towers`에 삽입합니다: ```bash theme={null} 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)에 삽입합니다: ```bash theme={null} 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`가 다시 나타날 때까지 모든 내용을 읽은 다음 출력합니다: ```bash theme={null} 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`의 입력으로 전달합니다: ```bash theme={null} cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV"; ``` 배치 모드에서는 기본 데이터 [포맷](/ko/reference/formats)이 `TabSeparated`입니다. 위 예시와 같이 쿼리의 `FORMAT` 절에서 포맷을 설정할 수 있습니다.
## 매개변수가 있는 쿼리
쿼리에서 매개변수를 지정하고 명령줄 옵션으로 해당 값을 전달할 수 있습니다. 이렇게 하면 클라이언트 측에서 특정 동적 값을 넣어 쿼리를 포맷할 필요가 없습니다. 예시는 다음과 같습니다: ```bash theme={null} $ clickhouse-client --param_parName="[1, 2]" --query "SELECT {parName: Array(UInt16)}" [1,2] ``` [대화형 세션](#interactive-mode)에서도 매개변수를 설정할 수 있습니다: ```text highlight={4,14} theme={null} $ 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. ```
### 쿼리 구문
쿼리에서 명령줄 매개변수로 채우려는 값은 다음 형식으로 중괄호 안에 지정합니다: ```sql theme={null} {:} ``` | 매개변수 | 설명 | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | 플레이스홀더 식별자입니다. 해당 명령줄 옵션은 `--param_ = value`입니다. | | `data type` | 매개변수의 [데이터 타입](/ko/reference/data-types)입니다.

예를 들어 `(integer, ('string', integer))`와 같은 데이터 구조는 `Tuple(UInt8, Tuple(String, UInt8))` 데이터 타입이 될 수 있습니다(다른 [integer](/ko/reference/data-types/int-uint) 타입도 사용할 수 있습니다).

테이블 이름, 데이터베이스 이름, 컬럼 이름을 매개변수로 전달할 수도 있으며, 이 경우 데이터 타입으로 `Identifier`를 사용해야 합니다. |
### 예시
```bash theme={null} $ 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-generation-configuration) 섹션을 참조하십시오.
### 사용 방법
AI SQL 생성 기능을 사용하려면 자연어 질의 앞에 `??`를 붙이십시오: ```bash theme={null} :) ?? show all users who made purchases in the last 30 days ``` AI는 다음 작업을 수행합니다: 1. 데이터베이스 스키마를 자동으로 파악합니다 2. 파악된 테이블과 컬럼을 바탕으로 적절한 SQL을 생성합니다 3. 생성된 쿼리를 즉시 실행합니다
### 예시
```bash theme={null} :) ?? 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는 자동으로 환경 변수 사용을 시도합니다: 1. 먼저 `OPENAI_API_KEY` 환경 변수를 확인합니다 2. 없으면 `ANTHROPIC_API_KEY` 환경 변수를 확인합니다 3. 둘 다 없으면 AI 기능이 비활성화됩니다 따라서 설정 파일 없이도 빠르게 설정할 수 있습니다: ```bash theme={null} # 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 theme={null} {/* 필수: API Key(또는 환경 변수로 설정) */} your-api-key-here {/* 필수: 프로바이더 유형(openai, anthropic) */} openai {/* 사용할 모델(기본값은 프로바이더에 따라 다름) */} gpt-4o {/* 선택 사항: OpenAI 호환 서비스용 사용자 지정 API 엔드포인트 */} {/* https://openrouter.ai/api */} {/* 스키마 탐색 설정 */} true {/* 생성 매개변수 */} 0.0 1000 30 10 {/* 선택 사항: 사용자 지정 system prompt */} {/* You are an expert ClickHouse SQL assistant... */} ``` ```yaml theme={null} 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):** ```yaml theme={null} ai: provider: openai # 호환성을 위해 'openai' 사용 api_key: your-openrouter-api-key base_url: https://openrouter.ai/api/v1 model: anthropic/claude-3.5-sonnet # OpenRouter 모델 명명 규칙 사용 ``` **최소 구성 예시:** ```yaml theme={null} # 최소 설정 - 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 생성기는 여러 단계의 프로세스로 작동합니다: 1. **스키마 검색** AI는 내장 도구를 사용해 데이터베이스를 탐색합니다 * 사용 가능한 데이터베이스를 나열합니다 * 관련 데이터베이스 내의 테이블을 찾아냅니다 * `CREATE TABLE` SQL 문을 통해 테이블 구조를 확인합니다 2. **쿼리 생성** AI는 검색된 스키마를 바탕으로 다음과 같은 SQL을 생성합니다: * 자연어로 표현한 의도에 맞습니다 * 올바른 테이블 및 컬럼 이름을 사용합니다 * 적절한 조인과 집계를 적용합니다 3. **실행** 생성된 SQL은 자동으로 실행되며, 결과가 표시됩니다
### 제한 사항
* 활성 인터넷 연결이 필요합니다 * API 사용에는 AI 프로바이더의 속도 제한 및 비용이 적용됩니다 * 복잡한 쿼리는 여러 차례에 걸쳐 수정해야 할 수 있습니다 * AI는 실제 데이터가 아니라 스키마 정보에만 읽기 전용으로 액세스할 수 있습니다
### 보안
* API keys는 ClickHouse 서버로 전송되지 않습니다 * AI는 실제 데이터가 아니라 스키마 정보(테이블/컬럼 이름 및 타입)만 봅니다 * 생성된 모든 쿼리는 기존 데이터베이스 권한을 준수합니다
## 연결 문자열
### 사용법
ClickHouse Client는 [MongoDB](https://www.mongodb.com/docs/manual/reference/connection-string/), [PostgreSQL](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), [MySQL](https://dev.mysql.com/doc/refman/8.0/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri)와 유사한 연결 문자열(connection string)을 사용해 ClickHouse 서버에 연결하는 것도 지원합니다. 구문은 다음과 같습니다: ```text theme={null} 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[,¶m2=value2], ...`입니다. 일부 매개변수는 값이 필요하지 않습니다. 매개변수 이름과 값은 대소문자를 구분합니다. | - |
### 참고 사항
사용자 이름, 비밀번호 또는 데이터베이스를 연결 문자열에 지정한 경우 `--user`, `--password` 또는 `--database`로는 지정할 수 없습니다(그 반대도 마찬가지입니다). host component에는 호스트명 또는 IPv4/IPv6 주소를 사용할 수 있습니다. IPv6 주소는 `[]`로 감싸야 합니다: ```text theme={null} clickhouse://[2001:db8::1234] ``` 연결 문자열에는 여러 호스트를 포함할 수 있습니다. ClickHouse Client는 이 호스트들에 순서대로(왼쪽에서 오른쪽으로) 연결을 시도합니다. 연결이 설정되면 나머지 호스트에는 연결을 시도하지 않습니다. 연결 문자열은 `clickHouse-client`의 첫 번째 인수로 지정해야 합니다. 연결 문자열은 `--host` 및 `--port`를 제외한 다른 [명령줄 옵션](#command-line-options)과 원하는 만큼 함께 사용할 수 있습니다. `query_parameters`에는 다음 키를 사용할 수 있습니다: | Key | Description | | ----------------- | ------------------------------------------------------------------------------------------ | | `secure` (or `s`) | 지정하면 클라이언트는 보안 연결(TLS)을 통해 서버에 연결합니다. [명령줄 옵션](#command-line-options)의 `--secure`를 참조하십시오. | **퍼센트 인코딩** 다음 매개변수에 포함된 US-ASCII 이외의 문자, 공백 및 특수 문자는 [퍼센트 인코딩](https://en.wikipedia.org/wiki/URL_encoding)해야 합니다: * `user` * `password` * `hosts` * `database` * `query parameters`
### 예시
`localhost`의 9000번 포트에 연결하여 쿼리 `SELECT 1`을 실행합니다. ```bash theme={null} clickhouse-client clickhouse://localhost:9000 --query "SELECT 1" ``` `localhost`에 사용자 `john`, 비밀번호 `secret`, 호스트 `127.0.0.1`, 포트 `9000`을 사용해 연결합니다 ```bash theme={null} clickhouse-client clickhouse://john:secret@127.0.0.1:9000 ``` `default` 사용자로, IPV6 주소 `[::1]` 및 포트 `9000`을 사용하는 `localhost` 호스트에 연결합니다. ```bash theme={null} clickhouse-client clickhouse://[::1]:9000 ``` 멀티라인 모드로 포트 9000의 `localhost`에 연결합니다. ```bash theme={null} clickhouse-client clickhouse://localhost:9000 '-m' ``` `default` 사용자로 포트 9000을 사용해 `localhost`에 연결합니다. ```bash theme={null} clickhouse-client clickhouse://default@localhost:9000 # 동일한 표현: clickhouse-client clickhouse://localhost:9000 --user default ``` `localhost`의 9000 포트에 연결하고 기본 데이터베이스는 `my_database`를 사용합니다. ```bash theme={null} clickhouse-client clickhouse://localhost:9000/my_database # 동일한 표현: clickhouse-client clickhouse://localhost:9000 --database my_database ``` `localhost`의 9000번 포트에 연결하고, 연결 문자열에 지정된 `my_database` 데이터베이스를 기본 데이터베이스로 사용하며, 축약형 `s` 매개변수로 보안 연결을 사용합니다. ```bash theme={null} clickhouse-client clickhouse://localhost/my_database?s # 동일한 표현: clickhouse-client clickhouse://localhost/my_database -s ``` 기본 포트, 기본 사용자, 기본 데이터베이스를 사용해 기본 호스트에 연결합니다. ```bash theme={null} clickhouse-client clickhouse: ``` 기본 포트를 사용하여 기본 호스트에 `my_user` 사용자로 비밀번호 없이 연결합니다. ```bash theme={null} clickhouse-client clickhouse://my_user@ # : 와 @ 사이에 빈 비밀번호를 사용하면 연결 시작 전에 사용자에게 비밀번호 입력을 요청합니다. clickhouse-client clickhouse://my_user:@ ``` 사용자 이름으로 이메일 주소를 사용해 `localhost`에 연결합니다. `@` 기호는 `%40`으로 퍼센트 인코딩됩니다. ```bash theme={null} clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000 ``` 다음 두 호스트 중 하나에 연결합니다: `192.168.1.15`, `192.168.1.25`. ```bash theme={null} clickhouse-client clickhouse://192.168.1.15,192.168.1.25 ```
## 쿼리 ID 형식
대화형 모드에서 ClickHouse Client는 각 쿼리의 쿼리 ID를 표시합니다. 기본적으로 ID는 다음과 같은 형식입니다: ```sql theme={null} Query id: 927f137d-00f1-4175-8914-0dd066365e96 ``` 사용자 지정 포맷은 설정 파일의 `query_id_formats` 태그 내에서 지정할 수 있습니다. 포맷 문자열의 `{query_id}` 자리 표시자는 쿼리 ID로 대체됩니다. 태그 안에는 여러 개의 포맷 문자열을 지정할 수 있습니다. 이 기능은 쿼리 프로파일링을 쉽게 할 수 있도록 URL을 생성하는 데 사용할 수 있습니다. **예시** ```xml theme={null} http://speedscope-host/#profileURL=qp%3Fid%3D{query_id} ``` 위 구성에서는 쿼리 ID가 다음과 같은 포맷으로 표시됩니다: ```response theme={null} 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`](https://github.com/ClickHouse/ClickHouse/blob/master/programs/client/clickhouse-client.xml) ```xml theme={null} username password true /etc/ssl/cert.pem ``` ```yaml theme={null} user: username password: 'password' secure: true openSSL: client: caConfig: '/etc/ssl/cert.pem' ```
## 환경 변수 옵션
사용자 이름, 비밀번호, 호스트는 환경 변수 `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`, `CLICKHOUSE_HOST`로 설정할 수 있습니다. 명령줄 인수 `--user`, `--password`, `--host` 또는 [연결 문자열](#connection_string)이 지정된 경우, 환경 변수보다 우선합니다.
## 명령줄 옵션
모든 명령줄 옵션은 명령줄에서 직접 지정하거나 [설정 파일](#configuration_files)에서 기본값으로 지정할 수 있습니다.
### 일반 옵션
| 옵션 | 설명 | 기본값 | | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------ | | `-c [ -C, --config, --config-file ] ` | 클라이언트 설정 파일이 기본 위치 중 하나에 없을 경우, 해당 설정 파일의 위치를 지정합니다. [설정 파일](#configuration_files)을 참조하십시오. | - | | `--help` | 사용 요약을 출력한 후 종료합니다. `--verbose`와 함께 사용하면 쿼리 설정을 포함한 모든 옵션을 표시합니다. | - | | `--history_file ` | 명령 이력이 저장된 파일의 경로입니다. | - | | `--history_max_entries` | 이력 파일에 저장할 수 있는 최대 항목 수입니다. | `1000000` (100만) | | `--prompt ` | 사용자 지정 프롬프트를 설정합니다. | 서버의 `display_name` | | `--verbose` | 출력 상세 수준을 높입니다. | - | | `-V [ --version ]` | 버전을 출력한 후 종료합니다. | - |
### 연결 옵션
| Option | Description | Default | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `--connection ` | 설정 파일에 있는 미리 구성된 연결 정보의 이름입니다. [연결 자격 증명](#connection-credentials)을 참조하세요. | - | | `-d [ --database ] ` | 이 연결의 기본 데이터베이스로 사용할 데이터베이스를 선택합니다. | 서버 설정의 현재 데이터베이스(기본값은 `default`) | | `-h [ --host ] ` | 연결할 ClickHouse 서버의 호스트명입니다. 호스트명 또는 IPv4/IPv6 주소를 사용할 수 있습니다. 여러 인수로 여러 호스트를 전달할 수도 있습니다. | `localhost` | | `--jwt ` | 인증에 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 ` | 데이터베이스 사용자의 비밀번호입니다. 설정 파일에서 연결의 비밀번호를 지정할 수도 있습니다. 비밀번호를 지정하지 않으면 클라이언트가 비밀번호 입력을 요청합니다. | - | | `--port ` | 서버가 연결을 수락하는 포트입니다. 기본 포트는 9440(TLS) 및 9000(TLS 미사용)입니다.

참고: 클라이언트는 HTTP(S)가 아니라 네이티브 프로토콜을 사용합니다. | `--secure`가 지정되면 `9440`, 그렇지 않으면 `9000`입니다. 호스트명이 `.clickhouse.cloud`로 끝나면 항상 기본값은 `9440`입니다. | | `-s [ --secure ]` | TLS 사용 여부입니다.

포트 9440(기본 보안 포트) 또는 ClickHouse Cloud에 연결할 때 자동으로 활성화됩니다.

[설정 파일](#configuration_files)에서 CA 인증서를 구성해야 할 수 있습니다. 사용 가능한 구성 설정은 [서버 측 TLS 구성](/ko/reference/settings/server-settings/settings#openssl)과 동일합니다. | 포트 9440 또는 ClickHouse Cloud에 연결할 때 자동으로 활성화됨 | | `--ssh-key-file ` | 서버 인증에 사용할 SSH 개인 키가 들어 있는 파일입니다. | - | | `--ssh-key-passphrase ` | `--ssh-key-file`에 지정한 SSH 개인 키의 패스프레이스입니다. | - | | `--tls-sni-override ` | TLS를 사용하는 경우 핸드셰이크에 전달할 서버 이름(SNI)입니다. | `-h` 또는 `--host`로 지정한 호스트입니다. | | `-u [ --user ] ` | 연결에 사용할 데이터베이스 사용자입니다. | `default` | `--host`, `--port`, `--user`, `--password` 옵션 대신 [연결 문자열](#connection_string)도 사용할 수 있습니다.
### 쿼리 옵션
| Option | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--param_=` | [매개변수가 있는 쿼리](#cli-queries-with-parameters)의 매개변수에 대한 치환 값입니다. | | `-q [ --query ] ` | batch mode에서 실행할 쿼리입니다. 여러 번 지정할 수 있으며(`--query "SELECT 1" --query "SELECT 2"`), 세미콜론으로 구분된 여러 쿼리를 한 번에 지정할 수도 있습니다(`--query "SELECT 1; SELECT 2;"`). 후자의 경우 `VALUES` 이외의 포맷을 사용하는 `INSERT` 쿼리는 빈 줄로 구분해야 합니다.

매개변수 없이 단일 쿼리를 지정할 수도 있습니다: `clickhouse-client "SELECT 1"`

`--queries-file`과 함께 사용할 수 없습니다. | | `--queries-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`](/ko/reference/settings/session-settings#send_table_structure_on_insert_with_inline_data)를 자동으로 `0`으로 설정합니다. 인라인 데이터와 외부 데이터(stdin 또는 `INFILE`의 데이터)는 함께 사용할 수 없습니다. |
### 쿼리 설정
클라이언트에서 쿼리 설정은 명령줄 옵션으로 지정할 수 있습니다. 예를 들면 다음과 같습니다: ```bash theme={null} $ clickhouse-client --max_threads 1 ``` [설정](/ko/reference/settings/session-settings)에서 설정 목록을 확인하십시오.
### 포맷 옵션
| 옵션 | 설명 | 기본값 | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `-f [ --format ] ` | 지정한 포맷으로 결과를 출력합니다.

지원되는 포맷 목록은 [입력 및 출력 데이터 포맷](/ko/reference/formats)을 참조하십시오. | `TabSeparated` | | `--pager ` | 모든 출력을 이 명령으로 전달합니다. 일반적으로 `less`(예: 가로로 긴 결과 집합을 표시하려면 `less -S`) 또는 이와 비슷한 명령을 사용합니다. | - | | `-E [ --vertical ]` | 결과를 출력할 때 [Vertical 형식](/ko/reference/formats/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`에 출력합니다(벤치마크용). | - |