コマンドラインクライアント

clickhouse-client

ClickHouseはネイティブのコマンドラインクライアント、clickhouse-clientを提供しています。このクライアントはコマンドラインオプションと設定ファイルをサポートしています。詳細は設定をご覧ください。

clickhouse-clientパッケージからインストールし、clickhouse-clientコマンドで実行します。

$ clickhouse-client
ClickHouse client version 20.13.1.5273 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 20.13.1.

:)

異なるクライアントとサーバーバージョンは互換性がありますが、一部の機能は古いクライアントでは使用できない可能性があります。クライアントとサーバーアプリの同じバージョンを使用することをお勧めします。古いバージョンのクライアントを使用しようとすると、サーバーはclickhouse-clientが以下のメッセージを表示します：

ClickHouse client version is older than ClickHouse server.
It may lack support for new features.

使用法

クライアントは、インタラクティブモードと非インタラクティブ（バッチ）モードで使用できます。

接続の詳細を集める

ClickHouseにネイティブTCPで接続するには、次の情報が必要です。

• HOSTとPORT: 通常、TLSを使用している場合はポートは9440、TLSを使用していない場合は9000です。

• データベース名: デフォルトでは、defaultという名前のデータベースがあります。接続したいデータベースの名前を使用してください。

• ユーザー名とパスワード: デフォルトのユーザー名はdefaultです。使用するケースに適したユーザー名を利用してください。

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

Native を選択すると、例として clickhouse-client コマンドで使用可能な詳細が表示されます。

セルフマネージドのClickHouseを使用している場合、接続の詳細はClickHouse管理者によって設定されます。

インタラクティブ

ClickHouse CloudサービスまたはTLSおよびパスワードを使用する任意のClickHouseサーバーに接続するには、インタラクティブに--secure、ポート9440、およびユーザー名とパスワードを指定します：

clickhouse-client --host <HOSTNAME> \
                  --secure \
                  --port 9440 \
                  --user <USERNAME> \
                  --password <PASSWORD>

セルフマネージドのClickHouseサーバーに接続するには、そのサーバーの詳細が必要です。TLSが使用されるかどうか、ポート番号、パスワードもすべて設定可能です。ClickHouse Cloudの例を出発点として使用してください。

バッチ

バッチモードを使用するには、queryパラメーターを指定するか、stdinにデータを送信します（stdinがターミナルでないことを確認します）。両方を行うこともできます。HTTPインターフェースに似ていますが、queryパラメーターを使用しstdinにデータを送信する場合、リクエストはqueryパラメーター、改行、stdinのデータの連結です。これは大きなINSERTクエリに便利です。

クライアントを使用してデータを挿入する例：

リモートClickHouseサービスにCSVファイルを挿入する

この例はTLSとパスワードを使用するClickHouse Cloudまたは任意のClickHouseサーバーに適しています。この例ではサンプルデータセットのCSVファイルcell_towers.csvを既存のdefaultデータベース内のcell_towersテーブルに挿入します：

clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --secure \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv

Note

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

データを挿入する三つの方法

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 | 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 | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

注意事項

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

デフォルトでは、バッチモードでは単一のクエリしか処理できません。“スクリプト”から複数のクエリを作成するには、--multiqueryパラメータを使用します。これはINSERTを除くすべてのクエリに有効です。クエリ結果は連続して無分別に出力されます。同様に、大量のクエリを処理するには、各クエリに対して‘clickhouse-client’を実行することができます。‘clickhouse-client’プログラムの起動に数十ミリ秒かかることに注意してください。

インタラクティブモードでは、クエリを入力するためのコマンドラインが得られます。

‘multiline’が指定されていない場合（デフォルト）：クエリを実行するにはEnterキーを押します。クエリの最後にセミコロンは必要ありません。複数行のクエリを入力するには、改行前にバックスラッシュ\を入力します。Enterキーを押した後、次の行のクエリを入力するように求められます。

multilineが指定されている場合：クエリを実行するには、最後にセミコロンを付けてEnterキーを押します。入力した行の最後にセミコロンを付けなかった場合、次の行のクエリを入力するように求められます。

単一のクエリのみが実行されるため、セミコロン以降のすべては無視されます。

\Gをセミコロンとして、または後に指定することができます。これはVerticalフォーマットを示します。このフォーマットでは、各値が別々の行に印刷されるため、幅広いテーブルに便利です。この珍しい機能はMySQL CLIとの互換性のために追加されました。

コマンドラインは‘replxx’（‘readline’に似ています）に基づいています。つまり、慣れ親しんだキーボードショートカットを使用し、履歴を保持します。履歴は~/.clickhouse-client-historyに書き込まれます。

デフォルトでは、使用されるフォーマットはPrettyCompactです。クエリのFORMAT句でフォーマットを変更するか、クエリの最後に\Gを指定したり、コマンドラインで--formatまたは--vertical引数を使用したり、クライアントの設定ファイルを使用したりすることでフォーマットを変更できます。

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

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

1. プログレスは、1秒間に最大10回（デフォルト）更新されます。クエリが迅速な場合、プログレスは表示されない可能性があります。
2. デバッグのために、解析後のフォーマットされたクエリ。
3. 指定されたフォーマットでの結果。
4. 結果の行数、経過時間、クエリ処理の平均速度。すべてのデータ量は圧縮されていないデータを指します。

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

コマンドラインクライアントは外部データ（外部一時テーブル）をクエリに渡すことができます。詳細については、「クエリ処理のための外部データ」セクションをご覧ください。

パラメータ付きクエリ

クライアントアプリケーションから値を渡してパラメータ付きクエリを作成できます。これにより、クライアント側で特定の動的値を持つクエリをフォーマットする必要がなくなります。 例えば：

$ clickhouse-client --param_parName="[1, 2]"  -q "SELECT * FROM table WHERE a = {parName:Array(UInt16)}"

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

$ clickhouse-client -nq "
  SET param_parName='[1, 2]';
  SELECT {parName:Array(UInt16)}"

クエリ構文

通常どおりにクエリをフォーマットし、次にアプリのパラメータからクエリに渡したい値を以下の形式で中括弧に入れます：

{<name>:<data type>}

• name — プレースホルダー識別子。コンソールクライアントでは--param_<name> = valueとしてアプリパラメータで使用されます。
• data type — アプリパラメータ値のデータ型。例えば、(integer, ('string', integer))のようなデータ構造は、Tuple(UInt8, Tuple(String, UInt8))データ型を持つことができます（他の整数タイプも使用できます）。テーブル、データベース、カラム名をパラメータとして渡すことも可能で、その場合Identifierをデータ型として使用する必要があります。

例

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" -q "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にパラメータを渡すことができ（すべてのパラメータにはデフォルト値があります）、以下の方法を使用します：

• コマンドラインから

  コマンドラインオプションは、設定ファイル内でのデフォルト値と設定を上書きします。

• 設定ファイルから。

  設定ファイルの設定はデフォルト値を上書きします。

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

• --host, -h – サーバー名（デフォルトは 'localhost'）。名前またはIPv4もしくはIPv6アドレスを使用できます。
• --port – 接続先のポート。デフォルト値: 9000。HTTPインターフェースとネイティブインターフェースは異なるポートを使用することに注意してください。
• --user, -u – ユーザー名。デフォルト値: default。
• --password – パスワード。デフォルト値: 空文字列。
• --ask-password - ユーザーにパスワードの入力を促します。
• --query, -q – 非インタラクティブモード使用時の処理クエリ。--queryは複数回指定できます（例：--query "SELECT 1" --query "SELECT 2"）。--queries-fileとは同時に使用できません。
• --queries-file – 実行するクエリが記述されたファイルパス。--queries-fileは複数回指定できます（例：--queries-file queries1.sql --queries-file queries2.sql）。--queryとは同時に使用できません。
• --multiquery, -n – 指定された場合、セミコロンで区切られた複数のクエリを--queryオプションの後にリストできます。便利なことに、--queryを省略し、--multiqueryの後にクエリを直接渡すことも可能です。
• --multiline, -m – 指定された場合、複数行のクエリを許可します（Enterでクエリを送信しません）。
• --database, -d – 現在のデフォルトデータベースを選択します。デフォルト値: サーバー設定からの現在のデータベース（デフォルトは ‘default’）。
• --format, -f – 結果を出力するためのデフォルトのフォーマットを指定します。
• --vertical, -E – 指定された場合、結果を出力するためにデフォルトでVerticalフォーマットを使用します。これは–format=Verticalと同じです。このフォーマットでは、各値が別々の行に印刷されるため、幅広いテーブルの表示に役立ちます。
• --time, -t – 指定された場合、非インタラクティブモードでクエリ実行時間を‘stderr’に出力します。
• --memory-usage – 指定された場合、非インタラクティブモードでメモリ使用量を‘stderr’に出力します。可能な値は：'none' - メモリ使用量を出力しない、'default' - バイト数を出力、'readable' - メモリ使用量を人間が読みやすい形式で出力。
• --stacktrace – 指定された場合、例外が発生したときにスタックトレースも出力します。
• --config-file – 設定ファイルの名前。
• --secure – 指定された場合、セキュア接続（TLS）を介してサーバーに接続します。CA証明書を設定ファイルで設定する必要があるかもしれません。利用可能な設定はサーバー側のTLS設定と同じです。
• --history_file — コマンド履歴を含むファイルのパス。
• --history_max_entries — 履歴ファイルの最大エントリー数。デフォルト値：1 000 000。
• --param_<name> — パラメータ付きクエリのための値。
• --hardware-utilization — プログレスバーでハードウェア利用情報を表示。
• --print-profile-events – ProfileEventsパケットを出力。
• --profile-events-delay-ms – ProfileEventsパケットの出力間隔（-1 - 合計のみ出力、0 - 単一パケットごとに出力）。
• --jwt – 指定された場合、JSON Web Tokenを介して認証を有効にします。サーバーJWT認証はClickHouse Cloudでのみ利用可能です。
• --progress – クエリ実行の進捗を表示。可能な値: 'tty|on|1|true|yes' - インタラクティブモードでTTYに出力; 'err' - 非インタラクティブモードでSTDERRに出力; 'off|0|false|no' - 進捗表示を無効にします。デフォルト：インタラクティブモードではTTY、非インタラクティブモードでは無効。
• --progress-table – クエリ実行中に変化するメトリクスを持つ進捗テーブルを表示。可能な値: 'tty|on|1|true|yes' - インタラクティブモードでTTYに出力; 'err' - 非インタラクティブモードでSTDERRに出力; 'off|0|false|no' - 進捗テーブルを無効にします。デフォルト：インタラクティブモードではTTY、非インタラクティブモードでは無効。
• --enable-progress-table-toggle – 進捗テーブル印刷が有効なインタラクティブモードで、コントロールキー（スペース）を押して進捗テーブルを切り替えることを有効にします。デフォルト：'true'。

--host、--port、--user、--passwordオプションの代わりに、ClickHouseクライアントは接続文字列もサポートしています（次のセクションを参照）。

エイリアス

• \l - SHOW DATABASES
• \d - SHOW TABLES
• \c <DATABASE> - USE DATABASE
• . - 最後のクエリを繰り返す

ショートキー

• Alt (Option) + Shift + e - 現在のクエリをエディタで開く。環境変数を設定できます（デフォルトはvim）。
• Alt (Option) + # - 行をコメントアウト。
• Ctrl + r - あいまい履歴検索。

Tip

MacOSでメタキー（Option）の正しい動作を設定するには：

iTerm2: Preferences -> Profile -> Keys -> Left Option keyへ行き、Esc+をクリックします。

使用可能なすべてのショートキーの完全なリストはreplxxをご覧ください。

接続文字列

clickhouse-clientはまた、MongoDBやPostgreSQL、MySQLと似た接続文字列を使用してclickhouseサーバーに接続することをサポートしています。以下の構文で接続文字列を記述します：

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

ここで

• user - （オプション）ユーザー名,
• password - （オプション）ユーザーパスワード。:が指定され、パスワードが空白ならば、クライアントはユーザーにパスワードを入力するように促します。
• hosts_and_ports - （オプション）ホストとポートのリスト host[:port] [, host:[port]], ...,
• database - （オプション）データベース名,
• query_parameters - （オプション）キーと値のペアのリスト param1=value1[,&param2=value2], ...。一部のパラメータには値が必要ありません。パラメータ名と値は大文字小文字を区別します。

ユーザーが指定されていない場合、defaultユーザーがパスワードなしで使用されます。
ホストが指定されていない場合、localhostが使用されます。
ポートが指定されていない場合、デフォルトで9000が使用されます。
データベースが指定されていない場合、defaultデータベースが使用されます。

ユーザー名、パスワード、またはデータベースが接続文字列で指定されている場合、--user、--password、または--databaseで指定することはできません（その逆も同様です）。

ホストコンポーネントは、ホスト名とIPアドレスのどちらかを指定できます。IPv6アドレスを指定するには、角括弧内に記載します：

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

URIでは複数のホストへの接続が可能です。接続文字列には複数のホストを含めることができます。ClickHouse-clientはこれらのホストに順に接続を試みます（つまり、左から右へ）。接続が確立されると、残りのホストへの接続は行われません。

接続文字列はclickhouse-clientの最初の引数として指定する必要があります。接続文字列は任意の他のcommand-line-optionsと組み合わせて使用できますが、--host/-hおよび--portは除きます。

query_parametersコンポーネントに許可されるキーは以下の通りです：

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

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

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

例

ポート9000でlocalhostに接続し、クエリ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

デフォルトユーザーを使用し、ホストにIPV6アドレス[::1]、ポート9000を使用してlocalhostに接続します。

clickhouse-client clickhouse://[::1]:9000

ポート9000を使用し、複数行モードでlocalhostに接続します。

clickhouse-client clickhouse://localhost:9000 '-m'

ユーザーdefaultを使用してポート9000でlocalhostに接続します。

clickhouse-client clickhouse://default@localhost:9000

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --user default

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

clickhouse-client clickhouse://localhost:9000/my_database

# equivalent to:
clickhouse-client clickhouse://localhost:9000 --database my_database

ショートカット's' URIパラメータを使用して、接続文字列で指定されたmy_databaseデータベースとセキュア接続を使用してlocalhostに接続します。

clickhouse-client clickhouse://localhost/my_database?s

# equivalent to:
clickhouse-client clickhouse://localhost/my_database -s

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

clickhouse-client clickhouse:

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

clickhouse-client clickhouse://my_user@

# Using a blank password between : and @ means to asking user to enter the password before starting the connection.
clickhouse-client clickhouse://my_user:@

ユーザー名としてメールアドレスを使用してlocalhostに接続します。'@' シンボルはパーセントエンコードされ、'%40'になります。

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

指定されたホストの一つに接続します：192.168.1.15、192.168.1.25。

clickhouse-client clickhouse://192.168.1.15,192.168.1.25

設定ファイル

clickhouse-clientは以下の最初に存在するファイルを使用します：

• --config-fileパラメータで定義された。
• ./clickhouse-client.xml, .yaml, .yml
• ~/.clickhouse-client/config.xml, .yaml, .yml
• /etc/clickhouse-client/config.xml, .yaml, .yml

設定ファイルの例：

<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

または、YAML形式で同じ設定：

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

クエリ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