clickhouse-client

ClickHouseは、ClickHouseサーバーに対して直接SQLクエリを実行するためのネイティブなコマンドラインクライアントを提供します。インタラクティブモード（ライブクエリ実行用）とバッチモード（スクリプトと自動化用）の両方をサポートしています。クエリ結果は端末に表示するか、ファイルにエクスポートでき、Pretty、CSV、JSONなどのすべてのClickHouse出力フォーマットをサポートしています。

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

インストール

ClickHouseをダウンロードするには、次のコマンドを実行します：

次にインストールするには、以下を実行します：

さらに多くのインストールオプションについては、ClickHouseをインストールを参照してください。

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

実行する

备注

ClickHouseをダウンロードしただけでインストールしていない場合は、./clickhouse clientを使用してください。clickhouse-clientを使用しないでください。

ClickHouseサーバーに接続するには、次のコマンドを実行します：

必要に応じて、追加の接続詳細を指定します：

--port <port> - ClickHouseサーバーが接続を受け付けるポート。デフォルトポートは9440（TLS）と9000（非TLS）です。ClickHouse Clientはネイティブプロトコルを使用し、HTTP(S)は使用しません。

-s [ --secure ] - TLSを使用するかどうか（通常は自動検出されます）。

-u [ --user ] <username> - 接続するデータベースユーザー。デフォルトではdefaultユーザーとして接続します。

--password <password> - データベースユーザーのパスワード。構成ファイル内に接続用のパスワードを指定することもできます。パスワードを指定しない場合は、クライアントがパスワードを尋ねます。

-c [ --config ] <path-to-file> - ClickHouse Clientの構成ファイルの場所（デフォルトの場所でない場合）。

--connection <name> - 構成ファイルから事前に構成された接続詳細の名前。

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

ClickHouse Cloudへの接続

ClickHouse Cloudサービスの詳細は、ClickHouse Cloudコンソールで確認できます。接続したいサービスを選択し、接続をクリックします：

ネイティブを選択すると、詳細が表示され、clickhouse-clientコマンドの例が示されます：

構成ファイルに接続を保存する

1つまたは複数のClickHouseサーバーの接続詳細を構成ファイルに保存できます。

形式は次のようになります：

詳細は構成ファイルに関するセクションを参照してください。

备注

クエリ構文に集中するため、残りの例では接続詳細（--host、--portなど）を省略しています。コマンドを使用するときはそれらを追加することを忘れないでください。

バッチモード

ClickHouse Clientをインタラクティブに使用するのではなく、バッチモードで実行できます。

単一のクエリを次のように指定できます：

--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 Clientはreplxx（readline類似）に基づいているため、親しみのあるキーボードショートカットを使用し、履歴を保持します。履歴はデフォルトで~/.clickhouse-client-historyに書き込まれます。

クライアントを終了するには、Ctrl+Dを押すか、クエリの代わりに次のいずれかを入力します：exit、quit、 logout、 exit;、 quit;、 logout;、 q、 Q、 :q。

クエリを処理する際、クライアントは以下を表示します：

1. プログレスは、デフォルトで1秒あたり10回以上更新されません。クイッククエリの場合、プログレスが表示される暇がないことがあります。
2. デバッグ用に解析後のフォーマットされたクエリ。
3. 指定されたフォーマットでの結果。
4. 結果の行数、経過時間、クエリ処理の平均速度。すべてのデータ量は未圧縮データ参照します。

長いクエリをキャンセルするにはCtrl+Cを押します。ただし、サーバーがリクエストを中断するのを待つ必要があります。特定の段階でクエリをキャンセルすることはできません。待たずに2度目にCtrl+Cを押すと、クライアントが終了します。

ClickHouse Clientは、クエリのために外部データ（外部一時テーブル）を渡すことも可能です。詳細については、クエリ処理用の外部データに関するセクションを参照してください。

パラメーターを使用したクエリ

クエリ内でパラメーターを指定し、コマンドラインオプションでその値を渡すことができます。これにより、クライアントサイドで特定の動的値でクエリをフォーマットする必要がなくなります。例：

インタラクティブセッション内からパラメーターを設定することも可能です：

クエリ構文

クエリ内では、コマンドラインパラメータを使用して埋め込みたい値を次の形式で中括弧で囲みます：

• name — プレースホルダー識別子。対応するコマンドラインオプションは--param_<name> = valueです。
• data type — パラメータのデータ型。例えば、データ構造(integer, ('string', integer))はTuple(UInt8, Tuple(String, UInt8))データ型を持ち得ます（他の整数型も使用可能です）。テーブル名やデータベース名、カラム名をパラメータとして渡すことも可能で、その場合はデータ型としてIdentifierを使用する必要があります。

例

エイリアス

• \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 Clientは、接続文字列を使用してClickHouseサーバーに接続することもサポートしています。これはMongoDBやPostgreSQL、MySQLに類似しています。構文は次のようになります：

構成要素

• 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 Clientは、これらのホストに順番に接続を試みます（左から右へ）。接続が確立されると、残りのホストへの接続は試みられません。

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

query_parametersに対しては、以下のキーが許可されています：

• secureまたは省略形ス。指定された場合、クライアントはセキュアな接続（TLS）を介してサーバーに接続します。コマンドラインオプションの--secureを参照してください。

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

非US ASCII、スペース、user、password、hosts、databaseおよびquery parameters内の特殊文字はパーセントエンコードする必要があります。

例

ポート9000のlocalhostに接続し、SELECT 1クエリを実行します。

ユーザーjohnとして、パスワードsecretで、ホスト127.0.0.1およびポート9000に接続します。

ユーザーdefaultのlocalhostに、IPV6アドレス[::1]のホストとポート9000に接続します。

マルチラインモードでポート9000のlocalhostに接続します。

ユーザーdefaultとしてポート9000のlocalhostに接続します。

ポート9000のlocalhostに接続し、デフォルトでmy_databaseデータベースを使用します。

ポート9000のlocalhostに接続し、接続文字列で指定されたmy_databaseデータベースにデフォルトで接続し、省略形のスパラメータを使用して安全な接続を確立します。

デフォルトのホストを使用して、デフォルトのポート、デフォルトのユーザー、デフォルトのデータベースに接続します。

デフォルトのポートを使用して、デフォルトのホストに接続し、ユーザーmy_userとして、パスワードなしで接続します。

ユーザー名にメールを使用してlocalhostに接続します。@記号はパーセントエンコードして%40になります。

2つのホストのいずれかに接続します：192.168.1.15、192.168.1.25。

クエリID形式

インタラクティブモードでは、ClickHouse Clientは各クエリのクエリIDを表示します。デフォルトでは、IDは次のようにフォーマットされます：

カスタムフォーマットは、構成ファイル内のquery_id_formatsタグ内で指定できます。フォーマット文字列内の{query_id}プレースホルダーはクエリIDで置き換えられます。タグ内には複数のフォーマット文字列が許可されています。この機能は、クエリのプロファイリングを促進するためのURLを生成するために使用できます。

例

上記の構成では、クエリのIDは次の形式で表示されます：

構成ファイル

ClickHouse Clientは次のいずれかの最初に存在するファイルを使用します：

• -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形式の同じ構成：

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

すべてのコマンドラインオプションは、コマンドラインで直接指定するか、構成ファイルのデフォルトとして指定できます。

一般オプション

-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

--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"）または、セミコロンで区切られた複数のクエリを一度に指定できます（例：--query "SELECT 1; SELECT 2;"）。後者の場合、VALUES以外の形式のINSERTクエリは空の行で区切る必要があります。

単一のクエリはパラメータなしでも指定できます：

--queries-fileと同時に使用することはできません。

--queries-file <path-to-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

プログレステーブルの切り替えを有効にします。Controlキー（スペース）を押すことで切り替えが行えます。プログレステーブル表示が有効なインタラクティブモードでのみ適用可能です。

デフォルト値：有効

--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に印刷します（ベンチマーク用）。