ClickHouseクライアント

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コンソールで確認できます。接続したいサービスを選択し、接続をクリックします：

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

設定ファイルに接続を保存

1つ以上のClickHouseサーバーの接続詳細を設定ファイルに保存できます。

フォーマットは次のようになります：

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

注記

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

バッチモード

ClickHouseクライアントをインタラクティブに使用する代わりに、バッチモードで実行できます。

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

--queryコマンドラインオプションを使用することもできます：

stdinでクエリを提供できます：

データの挿入：

--queryを指定すると、入力は行の改行の後に要求に追加されます。

リモートClickHouseサービスへのCSVファイルの挿入

この例では、サンプルデータセットCSVファイルcell_towers.csvを、既存のテーブルcell_towersに挿入しています。データベースはdefaultです：

データ挿入の他の例

注意事項

インタラクティブモードでは、デフォルトの出力形式はPrettyCompactです。クエリのFORMAT句で形式を変更するか、--formatコマンドラインオプションを指定することができます。垂直フォーマットを使用するには、--verticalを使用するか、クエリの最後に\Gを指定します。この形式では、各値が別の行に印刷されるため、幅の広いテーブルに便利です。

バッチモードでは、デフォルトのデータ 形式 はTabSeparatedです。形式はクエリのFORMAT句で設定できます。

インタラクティブモードでは、デフォルトでエンターを押すと入力したものが実行されます。クエリの最後にセミコロンは不要です。

クライアントを-m, --multilineパラメーターで起動できます。複数行のクエリを入力するには、行の改行の前にバックスラッシュ\を入力します。エンターを押すと、次の行のクエリを入力するよう求められます。クエリを実行するには、セミコロンで終了させてエンターを押します。

ClickHouseクライアントはreplxx（readlineに似ている）に基づいているため、親しみのあるキーボードショートカットを使用し、履歴を保持します。履歴はデフォルトで~/.clickhouse-client-historyに書き込まれます。

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

クエリを処理する際、クライアントは次のことを表示します：

1. 進捗は、デフォルトでは1秒間に10回以上更新されません。クイッククエリの場合、進捗が表示される時間がないかもしれません。
2. デバッグ用に解析後のフォーマットされたクエリ。
3. 指定された形式での結果。
4. 結果の行数、経過時間、クエリ処理の平均速度。すべてのデータ量は圧縮されていないデータに関連します。

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

ClickHouseクライアントでは、外部データ（外部一時テーブル）を使用してクエリを実行できます。詳細については、クエリ処理のための外部データのセクションを参照してください。

パラメータを含むクエリ

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

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

クエリ構文

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

• 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 -> 左のOptionキーをクリックし、Esc+をクリック。

接続文字列

ClickHouseクライアントは、MongoDB、PostgreSQL、MySQLの接続文字列を使用してClickHouseサーバーに接続することをサポートしています。その構文は次の通りです：

コンポーネント

• 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クライアントは、これらのホストに左から右に順番に接続しようとします。接続が確立されると、残りのホストへの接続を試みることはありません。

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

query_parametersに許可されているキーは：

• secureまたは省略形のs。指定されている場合、クライアントはセキュア接続(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データベースをデフォルトとします。

接続文字列で指定されたmy_databaseデータベースをデフォルトとして、ポート9000のlocalhostに接続し、shorthanded sパラメータを使用してセキュア接続を行います。

デフォルトホストにデフォルトポート、デフォルトユーザー、デフォルトデータベースで接続します。

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

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

2つのホストのうちの1つに接続します：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形式で同じ設定：

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

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

一般オプション

-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は複数回指定可能です（例えば、--queries-file queries1.sql --queries-file queries2.sql）。

--queryとの併用はできません。

-m [ --multiline ]

指定した場合、複数行のクエリを許可します（エンターでクエリを送信しない）。クエリはセミコロンで終了するまで送信されません。

クエリ設定

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

設定のリストは、設定を参照してください。

フォーマットオプション

-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にクエリ実行時間を印刷します（ベンチマーク用）。