ClickHouse Client
ClickHouseは、ClickHouseサーバーに対してSQLクエリを直接実行するためのネイティブなコマンドラインクライアントを提供します。これはインタラクティブモード(ライブクエリ実行のため)とバッチモード(スクリプト作成や自動化のため)の両方をサポートしています。クエリの結果はターミナルに表示したり、ファイルにエクスポートしたりでき、Pretty、CSV、JSONなどのすべてのClickHouse出力形式をサポートしています。
このクライアントは、進行状況バーと読み取った行数、処理されたバイト数、クエリ実行時間に関するリアルタイムのフィードバックを提供します。また、コマンドラインオプションと設定ファイルの両方をサポートしています。
インストール
ClickHouseをダウンロードするには、次のコマンドを実行します:
さらにインストールするには、次のコマンドを実行します:
詳細なインストールオプションについては、ClickHouseをインストールするを参照してください。
異なるクライアントとサーバーバージョンは互換性がありますが、一部の機能は古いクライアントでは利用できない場合があります。クライアントとサーバーは同じバージョンを使用することをお勧めします。
実行
ClickHouseをダウンロードしたがインストールしていない場合は、./clickhouse client
を使用してください。
ClickHouseサーバーに接続するには、次のコマンドを実行します:
必要に応じて追加の接続詳細を指定します:
--port <port>
- ClickHouseサーバーが接続を受け入れるポート。デフォルトのポートは9440(TLS)および9000(非TLS)です。注意:ClickHouseクライアントはネイティブプロトコルを使用し、HTTP(S)ではありません。
-s [ --secure ]
- TLSを使用するかどうか(通常は自動検出されます)。
-u [ --user ] <username>
- 接続するデータベースユーザー。デフォルトではdefault
ユーザーとして接続します。
--password <password>
- データベースユーザーのパスワード。設定ファイルで接続のためのパスワードを指定することもできます。パスワードを指定しない場合、クライアントはそれを要求します。
-c [ --config ] <path-to-file>
- ClickHouseクライアントの設定ファイルの位置。デフォルトの場所ではない場合。
--connection <name>
- 設定ファイルから事前構成された接続詳細の名前。
コマンドラインオプションの完全なリストについては、コマンドラインオプションを参照してください。
ClickHouse Cloudへの接続
ClickHouse Cloudサービスの詳細はClickHouse Cloudコンソールで利用できます。接続したいサービスを選択し、接続をクリックします:

Nativeを選択すると、詳細が表示され、clickhouse-client
の例が示されます:

設定ファイルに接続を保存する
1つ以上のClickHouseサーバーの接続詳細を設定ファイルに保存することができます。
フォーマットは次のようになります:
詳細については、設定ファイルに関するセクションを参照してください。
クエリ構文に集中するために、残りの例では接続の詳細(--host
、--port
など)が省略されています。コマンドを実行するときは、必ず追加してください。
バッチモード
ClickHouseクライアントをインタラクティブに使用する代わりに、バッチモードで実行できます。
次のように単一のクエリを指定できます:
また、--query
コマンドラインオプションを使用することもできます:
stdin
でクエリを提供できます:
データの挿入:
--query
が指定されている場合、任意の入力は行送りの後にリクエストに追加されます。
リモートClickHouseサービスにCSVファイルを挿入する
この例では、サンプルデータセットCSVファイルcell_towers.csv
を、default
データベースの既存のテーブルcell_towers
に挿入しています:
データを挿入する他の例
注意事項
インタラクティブモードでは、デフォルトの出力形式はPrettyCompact
です。クエリのFORMAT
句で形式を変更するか、--format
コマンドラインオプションを指定することができます。垂直形式を使用するには、--vertical
を使用するか、クエリの最後に\G
を指定します。この形式では、各値が別の行に印刷され、広いテーブルの場合に便利です。
バッチモードでは、デフォルトのデータ形式はTabSeparated
です。クエリのFORMAT
句で形式を設定できます。
インタラクティブモードでは、デフォルトで入力されたものはEnter
キーを押すと実行されます。クエリの最後にセミコロンは必要ありません。
クライアントは-m, --multiline
パラメータで起動できます。マルチラインクエリを入力するには、改行の前にバックスラッシュ\
を入力します。Enter
を押すと、クエリの次の行を入力するよう求められます。クエリを実行するには、セミコロンで終わらせてEnter
を押します。
ClickHouseクライアントはreplxx
(readline
に似ています)に基づいているため、馴染みのあるキーボードショートカットを使用し、履歴を保持します。履歴はデフォルトで~/.clickhouse-client-history
に書き込まれます。
クライアントを終了するには、Ctrl+D
を押すか、クエリの代わりに次のいずれかを入力します:exit
、quit
、logout
、exit;
、quit;
、logout;
、q
、Q
、:q
。
クエリを処理している間、クライアントは次の情報を表示します:
- デフォルトでは、進行状況が1秒あたり10回以上更新されます。クイッククエリの場合、進行状況が表示される時間がない場合があります。
- デバッグ用に解析後のフォーマットされたクエリ。
- 指定された形式での結果。
- 結果の行数、経過時間、クエリ処理の平均速度。すべてのデータ量は未圧縮データに関連しています。
長いクエリをキャンセルするには、Ctrl+C
を押します。ただし、リクエストを中止するまで少し待つ必要があります。特定の段階でクエリをキャンセルすることはできません。待たずにCtrl+C
を2回押すと、クライアントが終了します。
ClickHouseクライアントは、外部データ(外部一時テーブル)をクエリ用に渡すことを許可します。詳細については、クエリ処理のための外部データのセクションを参照してください。
パラメータ付きクエリ
クエリ内にパラメータを指定し、コマンドラインオプションを使って値を渡すことができます。これにより、クライアント側で特定の動的値を使用してクエリをフォーマットする手間が省けます。例えば:
インタラクティブセッション内からパラメータを設定することもできます:
クエリ構文
クエリの中で、コマンドラインパラメータを使用して埋めたい値を次のフォーマットで波括弧で囲んでおきます:
name
— プレースホルダー識別子。対応するコマンドラインオプションは--param_<name>=value
です。data type
— パラメータのデータタイプ。例えば、データ構造(整数、('文字列', 整数))
はTuple(UInt8, Tuple(String, UInt8))
データタイプを持つことができます(他の整数タイプも使えます)。テーブル名、データベース名、カラム名をパラメータとして渡すことも可能で、その場合はデータ型としてIdentifier
を使用する必要があります。
例
AIによるSQL生成
ClickHouseクライアントには、自然言語の説明からSQLクエリを生成するための組み込みAIアシスタンスが含まれています。この機能は、ユーザーが深いSQL知識なしに複雑なクエリを書く手助けをします。
AIアシスタンスは、OPENAI_API_KEY
またはANTHROPIC_API_KEY
の環境変数が設定されている場合に、そのまま機能します。より高度な設定については、設定のセクションを参照してください。
使用方法
AI SQL生成を使用するには、あなたの自然言語のクエリの前に??
を付けます:
AIは以下を行います:
- データベーススキーマを自動的に探索します
- 発見したテーブルとカラムに基づいて適切なSQLを生成します
- 生成されたクエリをすぐに実行します
例
設定
AI SQL生成には、ClickHouseクライアントの設定ファイルでAIプロバイダーを設定する必要があります。OpenAI、Anthropic、またはOpenAI互換のAPIサービスを使用できます。
環境に基づくフォールバック
設定ファイルにAIの設定が指定されていない場合、ClickHouseクライアントは環境変数を自動的に使用しようとします:
- まず
OPENAI_API_KEY
環境変数を確認します - 見つからなければ、
ANTHROPIC_API_KEY
環境変数を確認します - どちらも見つからなければ、AI機能は無効になります
これにより、設定ファイルなしで迅速にセットアップ可能です:
設定ファイル
AI設定に対するより詳細な制御のために、ClickHouseクライアントの設定ファイルで設定します:
~/.clickhouse-client/config.xml
(XMLフォーマット)~/.clickhouse-client/config.yaml
(YAMLフォーマット)- または、
--config-file
でカスタム位置を指定します
XMLフォーマットの例:
YAMLフォーマットの例:
OpenAI互換APIを使用(例:OpenRouter):
最小限の設定例:
パラメータ
必要なパラメータ:
api_key
- AIサービスのAPIキー。環境変数で設定されている場合は省略可能:- OpenAI:
OPENAI_API_KEY
- Anthropic:
ANTHROPIC_API_KEY
- 注:設定ファイル内のAPIキーは環境変数よりも優先されます
- OpenAI:
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
のようにモデル名を使用
- OpenAI:
接続設定:
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ジェネレーターは、以下の多段階プロセスを使用します:
-
スキーマ発見: AIは内蔵ツールを使用してあなたのデータベースを探索します:
- 利用可能なデータベースをリストします
- 関連するデータベース内のテーブルを発見します
CREATE TABLE
ステートメントを介してテーブル構造を調査します
-
クエリ生成: 発見されたスキーマに基づいて、AIは次の条件に一致するSQLを生成します:
- 自然言語の意図に一致します
- 正しいテーブルとカラム名を使用します
- 適切な結合や集計を適用します
-
実行: 生成されたSQLは自動的に実行され、結果が表示されます
制限事項
- インターネット接続が必要です
- APIの使用はAIプロバイダーのレート制限およびコストの対象となります
- 複雑なクエリは複数の修正を必要とする場合があります
- AIはスキーマ情報に対する読み取り専用アクセス権しか持たず、実際のデータにはアクセスできません
セキュリティ
- APIキーはClickHouseサーバーに送信されることはありません
- AIはスキーマ情報(テーブル/カラム名および型)のみを参照し、実際のデータにはアクセスできません
- すべての生成されたクエリは、既存のデータベース権限を尊重します
エイリアス
\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クライアントは、MongoDB、PostgreSQL、MySQLのように接続文字列を使ってClickHouseサーバーに接続することもできます。以下の構文を持ちます:
コンポーネント
user
- (オプション) データベースユーザー名。デフォルト:default
。password
- (オプション) データベースユーザーパスワード。:
が指定され、パスワードが空白の場合、クライアントはユーザーのパスワードを要求します。hosts_and_ports
- (オプション) ホストとオプションポートのリストhost[:port] [, host:[port]], ...
。デフォルト:localhost:9000
。database
- (オプション) データベース名。デフォルト:default
。query_parameters
- (オプション) キーと値のペアのリストparam1=value1[,¶m2=value2], ...
。いくつかのパラメータに対しては値は必要ありません。パラメータ名と値は大文字と小文字を区別します。
接続文字列でユーザー名、パスワード、またはデータベースが指定されている場合、--user
、--password
、または--database
(およびその逆)で再指定することはできません。
ホストコンポーネントはホスト名またはIPv4またはIPv6アドレスのいずれかであることができます。IPv6アドレスは角括弧内に表記する必要があります:
接続文字列には複数のホストを含めることができます。ClickHouseクライアントは左から右の順にこれらのホストに接続しようとします。接続が確立された後、残りのホストへの接続を試みることはありません。
接続文字列はclickHouse-client
の最初の引数として指定する必要があります。接続文字列は、--host
と--port
以外の任意の他のコマンドラインオプションと組み合わせることができます。
query_parameters
に許可されるキーは以下の通りです:
secure
または省略形のs
。指定された場合、クライアントは安全な接続(TLS)を通じてサーバーに接続します。詳細はコマンドラインオプションの--secure
を参照してください。
パーセントエンコーディング
非米国ASCII、スペース、およびuser
、password
、hosts
、database
、query parameters
の特殊文字はパーセントエンコーディングを施さなければなりません。
例
ポート9000のlocalhost
に接続し、クエリSELECT 1
を実行します。
パスワードsecret
を持つユーザーjohn
として、ホスト127.0.0.1
のポート9000にlocalhost
に接続します。
default
ユーザーとして、IPv6アドレス[::1]
のホスト、ポート9000にlocalhost
に接続します。
マルチラインモードでポート9000のlocalhost
に接続します。
ユーザーdefault
として、ポート9000のlocalhost
に接続します。
接続文字列で指定されたmy_database
データベースにデフォルトでlocalhost
にポート9000で接続します。
接続文字列で指定されたデフォルトのmy_database
データベースと省略形のs
パラメータを使用して、安全な接続を持つポート9000のlocalhost
に接続します。
デフォルトホストに、デフォルトのポート、デフォルトのユーザー、およびデフォルトのデータベースで接続します。
デフォルトホストに、デフォルトのポートを使用して、ユーザーmy_user
およびパスワードなしで接続します。
ユーザー名として電子メールを使用してlocalhost
に接続します。@
記号は%40
にパーセントエンコーディングされます。
2つのホストのいずれかに接続します:192.168.1.15
、192.168.1.25
。
クエリIDフォーマット
インタラクティブモードでは、ClickHouseクライアントは各クエリに対してクエリIDを表示します。デフォルトでは、IDは次のようにフォーマットされます:
カスタムフォーマットは、設定ファイル内のquery_id_formats
タグで指定できます。フォーマット文字列内の{query_id}
プレースホルダーは、クエリIDに置き換えられます。複数のフォーマット文字列をタグ内に指定することができます。この機能は、クエリのプロファイリングを容易にするURLを生成するために使用できます。
例
上記の設定により、クエリのIDが次のフォーマットで表示されます:
設定ファイル
ClickHouseクライアントは、次のいずれかの最初に存在するファイルを使用します:
-c [ -C, --config, --config-file ]
パラメータで定義されたファイル。./clickhouse-client.[xml|yaml|yml]
~/.clickhouse-client/config.[xml|yaml|yml]
/etc/clickhouse-client/config.[xml|yaml|yml]
ClickHouseリポジトリのサンプル設定ファイルを参照してください:clickhouse-client.xml
XML構文の例:
YAMLフォーマットでの同じ構成:
クライアント設定の解決
クライアントの構成は次のパターンに従います:
- コマンドラインオプションで渡されたパラメータは 最も高い優先順位を持ちます。
- コマンドラインで渡されていないパラメータには、環境変数オプションが使用されます。
- その他の接続オプションは、設定ファイル内の
connections_credentials
キーの下の1つ以上のconnection
オブジェクトから引き出されます。ここで、connection.name
は接続名と一致します。その名前は、--connection
の値、ルートconnection
パラメータ、--host
オプションまたはルートhost
パラメータ、またはdefault
によって決まります。名前に一致するすべてのconnections
が、出現順に評価されます。それぞれのconnection
オブジェクトでサポートされるキーは次の通りです:name
hostname
port
secure
user
password
database
history_file
history_max_entries
accept-invalid-certificate
prompt
- 最後に、ルートレベルで設定されたパラメータが適用されます。
これには以下が含まれます:
connection
secure
およびno-secure
bind_host
host
port
user
password
database
history_file
history_max_entries
accept-invalid-certificate
prompt
jwt
ssh-key-file
ssh-key-passphrase
ask-password
追加の設定パラメータ
これらの追加のパラメータも、設定のルートレベルで設定でき、他の方法で上書きされません:
quota_key
compression
connect_timeout
send_timeout
receive_timeout
tcp_keep_alive_timeout
handshake_timeout_ms
sync_request_timeout
tcp_port
tcp_port_secure
セキュア接続
openSSL
オブジェクトは、TLS暗号化と認証の動作を決定します。詳細は、OpenSSLを参照してください。
openSSL
オブジェクトおよび他のパラメータは、安全な接続を使用するかどうかの決定にも影響します:
--secure
が渡された場合、またはルートまたはconnection
構成パラメータにsecure
が設定されている場合、接続は暗号化されます。--no-secure
が渡された場合、またはルートのno-secure
パラメータがtrue
の場合、接続は暗号化されません。- ホスト名が
clickhouse.cloud
のサブドメインに解決された場合、接続は暗号化されます。 - ポートがネイティブプロトコルのSSL/TLSポート
9440
に解決された場合、接続は暗号化されます。
環境変数オプション
ユーザー名、パスワード、およびホストは、環境変数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 ]
バージョンを表示して終了します。
接続オプション
--connection <name>
設定ファイルから事前構成された接続詳細の名前。接続認証情報を参照してください。
-d [ --database ] <database>
この接続のデフォルトにするデータベースを選択します。
デフォルト値:サーバー設定からの現在のデータベース(デフォルトではdefault
)。
-h [ --host ] <host>
接続するClickHouseサーバーのホスト名。ホスト名またはIPv4またはIPv6アドレスのいずれかであることができます。複数のホストを複数の引数で渡すことができます。
デフォルト値:localhost
--login
IDPを介して認証するためにデバイスGrant OAuthフローを呼び出します。ClickHouse Cloudホストの場合、OAuth変数は推測され、そうでない場合は--oauth-url
、--oauth-client-id
および--oauth-audience
で提供される必要があります。
--jwt <value>
認証にJSON Web Token(JWT)を使用します。
サーバーJWT認証はClickHouse Cloudでのみ使用可能です。
--no-warnings
クライアントがサーバーに接続するとき、system.warnings
からの警告の表示を無効にします。
--password <password>
データベースユーザーのパスワード。設定ファイルで接続のためのパスワードを指定することもできます。パスワードを指定しない場合、クライアントはそれを要求します。
--port <port>
サーバーが接続を受け入れているポート。デフォルトのポートは9440(TLS)と9000(非TLS)です。
注意:クライアントはネイティブプロトコルを使用し、HTTP(S)ではありません。
デフォルト値:--secure
が指定されている場合は9440、そうでない場合は9000です。ホスト名が.clickhouse.cloud
で終わる場合は、常に9440がデフォルトです。
-s [ --secure ]
TLSを使用するかどうか。
ポート9440(デフォルトの安全なポート)またはClickHouse Cloudに接続する際に自動的に有効になります。
設定ファイルにCA証明書を設定する必要があるかもしれません。利用可能な設定はサーバー側TLS設定と同じです。
--ssh-key-file <path-to-file>
サーバーと認証するためのSSH秘密鍵を含むファイル。
--ssh-key-passphrase <value>
--ssh-key-file
で指定されたSSH秘密鍵のパスフレーズ。
-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
クエリは空行で区切る必要があります。
単一のクエリもパラメータなしで指定できます:
--queries-file
と一緒に使用することはできません。
--queries-file <path-to-file>
クエリを含むファイルへのパス。--queries-file
は複数回指定できます(例:--queries-file queries1.sql --queries-file queries2.sql
)。
--query
と一緒に使用することはできません。
-m [ --multiline ]
指定された場合、マルチラインクエリを許可します(Enterでクエリを送信しない)。クエリはセミコロンで終了したときにのみ送信されます。
クエリ設定
クエリ設定は、クライアント内でコマンドラインオプションとして指定できます。例:
設定のリストについては設定を参照してください。
フォーマットオプション
-f [ --format ] <format>
結果を出力するために指定された形式を使用します。
サポートされている形式のリストについては入力および出力データの形式を参照してください。
デフォルト値:TabSeparated
--pager <command>
すべての出力をこのコマンドにパイプします。一般的にはless
(例:広い結果セットを表示するためにless -S
)あるいは同様のものです。
-E [ --vertical ]
結果を出力するために垂直形式を使用します。これは–-format Vertical
と同じです。この形式では、各値が別の行に印刷され、広いテーブルを表示するときに便利です。
実行の詳細
--enable-progress-table-toggle
進捗テーブルの切り替えを有効にします(制御キーを押すことで)。進捗テーブル印刷が有効になっているインタラクティブモードでのみ適用されます。
デフォルト値:有効
--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
に印刷します。