ClickHouse Client

ClickHouse は、ClickHouse サーバー に対して直接 SQL クエリを実行できるネイティブのコマンドラインクライアントを提供しています。 対話型モード (クエリをその場で実行する場合) とバッチモード (スクリプト作成や自動化の場合) の両方をサポートしています。 クエリ結果はターミナルに表示することも、ファイルにエクスポートすることもでき、Pretty、CSV、JSON など、ClickHouse のすべての出力フォーマットに対応しています。

このクライアントは、進捗バー、読み取った行数、処理したバイト数、クエリ実行時間を通じて、クエリ実行に関するリアルタイムのフィードバックを提供します。 コマンドラインオプションと設定ファイルの両方をサポートしています。

ClickHouse をダウンロードするには、次を実行します。

curl https://clickhouse.com/ | sh

これもインストールするには、次を実行します：

sudo ./clickhouse install

インストール方法のその他のオプションについては、Install ClickHouseを参照してください。

異なるバージョンのクライアントとサーバー間でも互換性はありますが、古いクライアントでは一部の機能を利用できない場合があります。クライアントとサーバーには同じバージョンを使用することを推奨します。

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.

:)

必要に応じて、追加の接続情報を指定します。

コマンドラインオプションの完全な一覧については、コマンドラインオプション を参照してください。

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>

詳しくは、設定ファイルのセクションを参照してください。

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;

クライアントを離れずに、任意の関数、テーブルエンジン、データ型、フォーマット、設定、その他のシステム要素のドキュメントを参照できます。help に続けて名前を入力してください (/help、man、/man も同様に使用できます) :

help domainWithoutWWW

このルックアップでは大文字と小文字を区別せず、system.documentation テーブルを照会します。一致したドキュメントは、太字/斜体のテキスト、表、構文ハイライト付きのコードブロックを含む Markdown から、ターミナル上にレンダリングされます。1 つの名前が複数のコンポーネントで共有されている場合 (たとえば file は関数であると同時にテーブルエンジンでもあります) 、それらがすべて表示されます。

完全一致するものがない場合、クライアントは類似した名前 (タイプミスを許容) と、その語に言及しているコンポーネントのドキュメントを一覧表示します。

help maxx_threads

help を単独で入力すると、簡単な使い方の概要が表示されます。

Client は、サーバー に送信する代わりに、/ で始まるいくつかのコマンドを自ら実行します。

入力の先頭で / を入力すると、コマンドがヒントとして一覧表示され、名前をさらに入力すると一覧が絞り込まれます。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)

クエリの処理中、クライアントには次の情報が表示されます。

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 で確認できます。

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 を指定すると、入力内容はすべて、改行の後にリクエストへ追加されます。

この例では、サンプルデータセットの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>}

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

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 はここで設定した場合にのみモデルへ送信されます。
             一部のモデルはこのパラメーターを受け付けないため、デフォルトでは省略されます。 */}
        {/* <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>

ai:
  # 必須: API キー（または環境変数で設定）
  api_key: your-api-key-here

  # 必須: プロバイダーの種類（openai、anthropic）
  provider: openai

  # 使用するモデル
  model: gpt-4o

  # 任意: OpenAI 互換サービス用のカスタム API エンドポイント
  # base_url: https://openrouter.ai/api

  # スキーマアクセスを有効化 - AI がデータベース/テーブル情報をクエリできるようにします
  enable_schema_access: true

  # 生成パラメータ
  # temperature はここで設定した場合にのみモデルへ送信され、デフォルトでは省略されます
  # 一部のモデルはこのパラメーターを受け付けないためです。
  # temperature: 0.0    # ランダム性を制御します（0.0 = 決定論的）
  max_tokens: 1000      # 応答の最大長
  timeout_seconds: 30   # リクエストのタイムアウト
  max_steps: 10         # スキーマ探索の最大ステップ数

  # 任意: カスタムのシステムプロンプト
  # system_prompt: |
  #   あなたは ClickHouse SQL のエキスパートアシスタントです。自然言語を SQL に変換してください。
  #   パフォーマンスを重視し、ClickHouse 固有の最適化を使用してください。
  #   説明は付けず、常に実行可能な SQL を返してください。

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

AI SQL ジェネレーターは、複数のステップで処理を行います。

1. スキーマの検出

AI は組み込みツールを使ってデータベースを調査します

• 利用可能なデータベースを一覧表示します
• 関連するデータベース内のテーブルを検出します
• CREATE TABLE ステートメントを通じてテーブル構造を調べます

2. クエリ生成

検出したスキーマに基づいて、AI は次のような SQL を生成します。

• 自然言語で表した意図に合致する
• 正しいテーブル名とカラム名を使用する
• 適切な JOIN と集計を適用する

3. 実行

生成された SQL は自動的に実行され、結果が表示されます

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

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

ClickHouse Client は、MongoDB、PostgreSQL、MySQL と同様の接続文字列を使って ClickHouse server に接続することもできます。構文は次のとおりです。

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

ユーザー名、パスワード、またはデータベースを接続文字列で指定した場合、--user、--password、--database では指定できません (逆も同様です) 。

ホスト部分には、ホスト名または IPv4 / IPv6 アドレスを指定できます。 IPv6 アドレスは [] で囲む必要があります。

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

接続文字列には複数のホストを含めることができます。 ClickHouse Client は、これらのホストへの接続を左から右の順に試みます。 接続が確立されると、残りのホストへの接続は試みられません。

接続文字列は、clickhouse-client の最初の引数として指定する必要があります。 接続文字列は、--host と --port を除き、任意個のほかのコマンドラインオプションと組み合わせて使用できます。

query_parameters では、次のキーを使用できます。

パーセントエンコーディング

以下のパラメータに含まれる 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

対話型モードでは、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>

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

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

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

クエリ設定は、たとえばクライアントのコマンドラインオプションとして指定できます。

$ clickhouse-client --max_threads 1

設定の一覧は、設定を参照してください。