メインコンテンツへスキップ
ClickHouse は、ClickHouse サーバー に対して直接 SQL クエリを実行できるネイティブのコマンドラインクライアントを提供しています。 対話型モード (クエリをその場で実行する場合) とバッチモード (スクリプト作成や自動化の場合) の両方をサポートしています。 クエリ結果はターミナルに表示することも、ファイルにエクスポートすることもでき、Pretty、CSV、JSON など、ClickHouse のすべての出力フォーマットに対応しています。 このクライアントは、進捗バー、読み取った行数、処理したバイト数、クエリ実行時間を通じて、クエリ実行に関するリアルタイムのフィードバックを提供します。 コマンドラインオプションと設定ファイルの両方をサポートしています。

​
インストール

ClickHouse をダウンロードするには、次を実行します。 
curl https://clickhouse.com/ | sh
これもインストールするには、次を実行します： 
sudo ./clickhouse install
インストール方法のその他のオプションについては、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.

:)
必要に応じて、追加の接続情報を指定します。
OptionDescription
--port <port>ClickHouse server が接続を受け付けるポートです。デフォルトのポートは 9440 (TLS) と 9000 (TLS なし) です。ClickHouse Client は HTTP(S) ではなくネイティブプロトコルを使用する点に注意してください。
-s [ --secure ]TLS を使用するかどうかを指定します (通常は自動検出されます) 。
-u [ --user ] <username>接続に使用するデータベースユーザーです。デフォルトでは default ユーザーとして接続します。
--password <password>データベースユーザーのパスワードです。設定ファイルで接続用のパスワードを指定することもできます。パスワードを指定しない場合、クライアントが入力を求めます。
-c [ --config ] <path-to-file>ClickHouse Client の設定ファイルの場所です (デフォルトの場所のいずれにもない場合) 。Configuration Files を参照してください。
--connection <name>configuration file で事前設定された接続情報の名前です。
コマンドラインオプションの完全な一覧については、Command Line Options を参照してください。

​
ClickHouse Cloud への接続

ClickHouse Cloud サービスの接続情報は、ClickHouse Cloud コンソールで確認できます。接続先のサービスを選択し、Connect をクリックします。

Native を選択すると、接続情報と clickhouse-client コマンドの例が表示されます。

​
設定ファイルに接続情報を保存する

1 つ以上の 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
これにより 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 Client は replxx (readline に類似) をベースにしているため、使い慣れたキーボードショートカットを利用でき、履歴も保持されます。 履歴はデフォルトで ~/.clickhouse-client-history に書き込まれます。 クライアントを終了するには、Ctrl+D を押すか、クエリの代わりに次のいずれかを入力します。
  • exit または exit;
  • quit または quit;
  • q、Q または :q
  • logout または logout;

​
クエリ処理情報

クエリの処理中、クライアントには次の情報が表示されます。
  1. Progress。デフォルトでは、1 秒あたり最大 10 回更新されます。 短時間で完了するクエリでは、進行状況が表示される前に処理が終わることがあります。
  2. デバッグ用に、パース後に整形されたクエリ。
  3. 指定したフォーマットでの結果。
  4. 結果の行数、経過時間、およびクエリ処理の平均速度。 すべてのデータ量は非圧縮データを基準としています。
時間のかかるクエリは、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 で meta キー (Option) が正しく動作するように設定するには:iTerm2: Preferences -> Profile -> Keys -> Left Option key に移動し、Esc+ をクリックします

​
バッチモード

​
バッチモードを使う

ClickHouse Client を対話モードで使う代わりに、バッチモードで実行できます。 バッチモードでは、ClickHouse は 1 つのクエリを実行するとすぐに終了し、対話型の入力待ちやループはありません。 次のように 1 つのクエリを指定できます。 
$ 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

​
コマンドラインからデータを挿入する例

コマンドラインからデータを挿入する方法はいくつかあります。 以下の例では、バッチモードを使用して 2 行の 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 が現れるまでの内容をすべて読み込み、その後出力します。 
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 は次のことを行います。
  1. データベースのスキーマを自動的に解析します
  2. 検出されたテーブルとカラムに基づいて適切な SQL を生成します
  3. 生成されたクエリをすぐに実行します

​
例

:) ?? 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 機能は無効化されます
これにより、設定ファイルがなくてもすばやくセットアップできます: 
# 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 で任意の場所を指定します
<config>
    <ai>
        {/* 必須: API キー（または環境変数で設定） */}
        <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>You are an expert ClickHouse SQL assistant...</system_prompt> */}
    </ai>
</config>

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キーに環境変数を使用
ai:
  provider: openai  # OPENAI_API_KEY 環境変数を使用

# 設定なし - 自動フォールバック
# (ai セクションが空または存在しない場合 - OPENAI_API_KEY、次に ANTHROPIC_API_KEY を試行)

# モデルのみ上書き - APIキーに環境変数を使用
ai:
  provider: openai
  model: gpt-3.5-turbo

​
パラメータ

  • 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 = 創造的 (デフォルト: 0.0)
  • max_tokens - 応答の最大長 (トークン数) (デフォルト: 1000)
  • system_prompt - AI へのカスタム指示 (任意)

​
仕組み

AI SQL ジェネレーターは、複数のステップで処理を行います。
  1. スキーマの検出
AI は組み込みツールを使ってデータベースを調査します
  • 利用可能なデータベースを一覧表示します
  • 関連するデータベース内のテーブルを検出します
  • CREATE TABLE ステートメントを通じてテーブル構造を調べます
  1. クエリ生成
検出したスキーマに基づいて、AI は次のような SQL を生成します。
  • 自然言語で表した意図に合致する
  • 正しいテーブル名とカラム名を使用する
  • 適切な JOIN と集計を適用する
  1. 実行
生成された SQL は自動的に実行され、結果が表示されます

​
制限事項

  • 有効なインターネット接続が必要です
  • API の利用には、AIプロバイダーによるレート制限やコストが伴います
  • 複雑なクエリでは、複数回の調整が必要になる場合があります
  • AI が読み取り専用でアクセスできるのはスキーマ情報のみで、実際のデータにはアクセスできません

​
セキュリティ

  • API キーが ClickHouse サーバーに送信されることはありません
  • AI が参照するのはスキーマ情報 (テーブル名 / カラム名 / 型) のみで、実際のデータは参照しません
  • 生成されるすべてのクエリは、既存のデータベース権限に従います

​
接続文字列

​
使用方法

ClickHouse Client は、MongoDB、PostgreSQL、MySQL と同様の接続文字列を使って ClickHouse server に接続することもできます。構文は次のとおりです。 
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], ...。一部のパラメーターでは値は不要です。パラメーター名と値では大文字と小文字が区別されます。-

​
注記

ユーザー名、パスワード、またはデータベースを接続文字列で指定した場合、--user、--password、--database では指定できません (逆も同様です) 。 ホスト部分には、ホスト名または IPv4 / IPv6 アドレスを指定できます。 IPv6 アドレスは [] で囲む必要があります。 
clickhouse://[2001:db8::1234]
接続文字列には複数のホストを含めることができます。 ClickHouse Client は、これらのホストへの接続を左から右の順に試みます。 接続が確立されると、残りのホストへの接続は試みられません。 接続文字列は、clickHouse-client の最初の引数として指定する必要があります。 接続文字列は、--host と --port を除き、任意個のほかのコマンドラインオプションと組み合わせて使用できます。 query_parameters では、次のキーを使用できます。
KeyDescription
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"
ユーザー john として、パスワード secret、ホスト 127.0.0.1、ポート 9000 を指定して localhost に接続します 
clickhouse-client clickhouse://john:secret@127.0.0.1:9000
localhost (IPV6 アドレス [::1]、ポート 9000) に default ユーザーとして接続します。 
clickhouse-client clickhouse://[::1]:9000
複数行モードで localhost のポート 9000 に接続します。 
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
ポート 9000 の localhost に接続し、接続文字列で指定した 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
2 つのホストのいずれかに接続します: 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 を参照してください。 
<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

​
環境変数オプション

ユーザー名、パスワード、ホストは、環境変数 CLICKHOUSE_USER、CLICKHOUSE_PASSWORD、CLICKHOUSE_HOST で設定できます。 コマンドライン引数 --user、--password、--host、または接続文字列 (指定した場合) は、環境変数よりも優先されます。

​
コマンドラインオプション

すべてのコマンドラインオプションは、コマンドラインで直接指定することも、設定ファイルで既定値として指定することもできます。

​
一般オプション

OptionDescriptionDefault
-c [ -C, --config, --config-file ] <path-to-file>クライアントの設定ファイルが既定の場所にない場合は、そのファイルの場所を指定します。Configuration Files を参照してください。-
--help使用方法の概要を表示して終了します。--verbose と組み合わせると、クエリ設定を含む利用可能なすべてのオプションを表示します。-
--history_file <path-to-file>コマンド履歴を保存したファイルのパス。-
--history_max_entries履歴ファイルに保存するエントリの最大数。1000000 (100万)
--prompt <prompt>カスタムプロンプトを指定します。サーバーの display_name
--verbose出力の詳細度を上げます。-
-V [ --version ]バージョンを表示して終了します。-

​
接続オプション

OptionDescriptionDefault
--connection <name>設定ファイルに事前設定された接続情報の名前です。接続認証情報を参照してください。-
-d [ --database ] <database>この接続のデフォルトとして使用するデータベースを選択します。サーバー設定の現在のデータベース (デフォルトは default)
-h [ --host ] <host>接続先の ClickHouse server のホスト名です。ホスト名、IPv4 アドレス、IPv6 アドレスのいずれかを指定できます。複数の引数を指定して複数のホストを渡すこともできます。localhost
--jwt <value>認証に JSON Web Token (JWT) を使用します。

サーバー側の JWT 認可は ClickHouse Cloud でのみ利用できます。		-
loginIdP 経由で認証するために、デバイス 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 オプションの代わりに、クライアントは接続文字列もサポートしています。

​
クエリオプション

オプション説明
--param_<name>=<value>パラメータ付きクエリ のパラメータに使用する置換値です。
-q [ --query ] <query>バッチモードで実行するクエリです。複数回指定することも (--query "SELECT 1" --query "SELECT 2")、セミコロンで区切った複数のクエリを 1 回で指定することもできます (--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-dataINSERT ... VALUES (およびその他のインラインフォーマット) を、データをネイティブフォーマットのブロックに変換せず、クエリテキスト内にそのまま含めて送信します。サーバー側でインラインデータを直接解析するため、テーブル構造やカラムのデフォルト値をクライアントに返すための往復を省けます。これにより、ネイティブプロトコル経由で多数の小さな insert を行う場合のパフォーマンスが向上することがあります。send_table_structure_on_insert_with_inline_data は自動的に 0 に設定されます。インラインデータと外部データ (stdin または INFILE からのデータ) は併用できません。

​
クエリ設定

クエリ設定は、たとえばクライアントのコマンドラインオプションとして指定できます。 
$ clickhouse-client --max_threads 1
設定の一覧は、設定を参照してください。

​
フォーマットオプション

OptionDescriptionDefault
-f [ --format ] <format>指定したフォーマットで結果を出力します。

対応フォーマットの一覧については、入出力データのフォーマットを参照してください。		TabSeparated
--pager <command>すべての出力をこのコマンドにパイプして渡します。通常は less (例: 幅の広い結果セットを表示するための less -S) などを使用します。-
-E [ --vertical ]結果の出力に Vertical フォーマット を使用します。これは --format Vertical と同じです。このフォーマットでは各値が別々の行に表示されるため、列数の多いテーブルを表示するときに便利です。-

​
実行の詳細

OptionDescriptionDefault
--enable-progress-table-toggleコントロールキー (Space) を押して、進行状況テーブルの表示を切り替えられるようにします。進行状況テーブルの表示が有効になっている対話型モードでのみ適用されます。enabled
--hardware-utilization進行状況バーにハードウェア使用率の情報を表示します。-
--memory-usage指定すると、非対話型モードでメモリ使用量をstderrに表示します。

設定可能な値:
• none - メモリ使用量を表示しない
• default - バイト数を表示
• readable - 人が読みやすい形式でメモリ使用量を表示		-
--print-profile-eventsProfileEventsパケットを表示します。-
--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に表示します (ベンチマーク用) 。-
最終更新日 2026年6月10日