ClickHouseのドキュメントを雑に翻訳してみた(Interfaces)

以下、 https://clickhouse.yandex/docs/en/interfaces/ の雑な翻訳。Google翻訳に頼りっきりなので品質は期待しないでください。(でも、誤訳などのフィードバックは歓迎)

文章中の (?) 部分は 特に 翻訳が怪しいものになります。あと、全部訳していません。

Interfaces

システムの機能を調べたり、テーブルデータのダウンロードをしたり、手動クエリーを作成するには、clickhouse-clientプログラムを使用します。

Commandline-client

コマンドラインで作業する場合、clickhouse-clientを利用出来ます。

$ clickhouse-client
ClickHouse client version 0.0.26176.
Connecting to localhost:9000.
Connected to ClickHouse server version 0.0.26176.

:)

clickhouse-clientはコマンドライン引数、コンフィグファイルによる設定をサポートしています。より詳しい情報は、 Configuring を参照。

Usage

clickhouse-clientは、インタラクティブ及び非インタラクティブモード(バッチモード)で使用できます。バッチモードを使用するには、 query パラメータを指定するか、 STDIN にデータを送ります。 HTTP interface と同様に、 query パラメータを利用して、 STDIN にデータを送信する場合、実行リクエストは query パラメータ、改行、及び STDIN データを連結されたものになります。これは、大量の INSERT クエリの実行に便利です。

INSERTの例:

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

通常、単一のクエリはバッチモードでのみ処理できます。 スクリプトファイルから複数のクエリの実行には、 --multiquery パラメータを使用します。これは、INSERT を除く全てのクエリで機能します。クエリ結果は、セパレータを伴わずに連続して出力されます。同様に、多数のクエリを処理するために、クエリ毎に clickhouse-client を起動できます。

インタラクティブモードでは、クエリを入力できるコマンドラインがあります。

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

--multiline が指定されている場合: クエリを実行するには、セミコロンを入力しEnterを押します。セミコロンが入力行の最後に付けなかった場合、続きのクエリ入力が求められます。1つのクエリだけが実行されるので、セミコロン後の入力は全て無視されます。

セミコロンの代わり、またはセミコロンのあとに \G を指定する事が出来ます。(出力は)垂直フォーマットの指示になります。この形式では、各値が別の行に出力されます。これは1列が長い表の場合に便利です。この機能はMySQL CLIとの互換性のために追加されました。

コマンドラインは readline (と history や libedit ビルドによっては違います)に基づいています。つまり、使い慣れたキーボードショートカットを使用して履歴を保持します。履歴は ~/.clickhouse-client-history に保存されます。

規定では、出力で使用されるフォーマットは PrettyCompact です。クエリの FORMAT クエリでフォーマットを変更するか、クエリの最後に \G を指定するか、コマンドラインで --format または --vertical 引数を使用するか、またはクライアント構成ファイルを使用して \G を指定します。

clickhouse-client を終了するには、"exit", "quit", "logout", "q", "Q", ":q" 等を入力するか、 Ctrl+D (Ctrl+C) を入力します。

クエリを処理するとき、クライアントは以下の表示を行います:

1. 進捗状況は、1秒間に10回以上更新されません(デフォルト状態)。クイッククエリの場合、進行状況に時間が表示されない事があります。
2. デバッグ状態で、クエリの解析後に整形出力されます。
3. (クエリの)結果は、指定のフォーマットで出力されます。
4. 出力結果の行数、処理の実行日時、及びクエリ処理の平均速度。

Ctrl+C を押すと、処理時間の長いクエリを中断する事が出来ます。ただし、その間サーバーが要求を中止するまで少し待つ必要があります。特定の段階でクエリをキャンセルする事は出来ません。待機せずにもう一度 Ctrl+C を押すと、clickhouse-clientは終了します。

clickhouse-clientでは、外部データ(外部テンポラリテーブル)をクエリに渡す事が出来ます。詳細については、 "External data for query processing" を参照してください。

Configuring

clickhouse-client にコマンドライン引数、及びコンフィグファイルで設定パラメータを渡す事が出来ます。
コマンドライン引数は、コンフィグファイルの設定よりも優先されます。コンフィグファイルの設定は、デフォルト設定より優先されます。

Command line options

--host, -h : ClickHouseサーバー名。デフォルトは 'localhost'。IPv4, IPv6アドレスを指定可能。
--port : ClickHouseサーバーポート番号。デフォルトは '9000'。 HTTPインターフェースと、ネティブインターフェースは別のポート番号です。
--user, -u : ユーザー名。デフォルトは 'default'。
--password : パスワード。デフォルトは空文字列。
--query, -q : 非インタラクティブモード時のクエリ指定。
--database, -d : データベース名を指定。デフォルトはサーバーで設定されたデフォルトのデータベース名。そのデフォルトは 'default'。
--multiline, -m : マルチラインモードを有効にする。
--multiquery, -n : マルチクエリモードを有効にする。非インタラクティブモードでのみ動作する。
--format, -f : 出力フォーマットの指定。
--vertical, -E : 垂直モードを有効にする。'--format=Vertical'の場合と同じ。
--time, -t : 非インタラクティブモードでクエリの実行時間情報をSTDERRに出力する。
--stacktrace : 例外発生時にスタックトレースを出力する。
-config-file : 任意のコンフィグファイルを指定できる。

Configuration files

clickhouse-clientでは以下の順番でコンフィグファイルをフォローする:

• --config-file 指定のファイル
• ./clickhouse-client.xml
• ~/.clickhouse-client/config.xml
• /etc/clickhouse-client/config.xml

コンフィグファイルの例:

<config>
    <user>username</user>
    <password>password</password>
</config>

HTTP interface

HTTPインターフェースを使用すると、任意のプログラミング言語、任意のプラットホームでClickHouseを使用できます。私たちはJavaやPerl、シェルスクリプトからの作業にこれを使用します。他の部門では、Perl,Python,GoからHTTPインターフェースが利用されています。HTTPインターフェースはネティブインターフェースよりも制限されていますが、よりよい互換性があります。

デフォルトで、 clickhouse-serverはポート8123でHTTPを受け付けます。(これはコンフィグで変更できます)パラメータ無しの "GET /" リクエストをすると "Ok." 文字列を返します。これはヘルスチェックスクリプトに利用出来ます。

$ curl 'http://localhost:8123/'
Ok.

リクエストをURL形式か、POST形式で送ります。または、クエリの先頭を "query" パラメータで送信し、残りをPOSTで送信します。(これについてはあとで説明します)URLのサイズは16KBに制限されるので、大規模なクエリを送信する場合は注意してください。

応答が成功した場合は、レスポンスステータスとして200と結果をボディに返します。エラーが発生した場合、レスポンスステータスは500としてエラーテキストがボディに返されます。

GET形式を使用する場合、 "readonly" が設定されます。つまり、データを変更するクエリでは、POST形式のみ使用できます。POST本体または、URLパラメータのいずれかでクエリを送信できます。

例:

$ curl 'http://localhost:8123/?query=SELECT%201'
1

$ wget -O- -q 'http://localhost:8123/?query=SELECT 1'
1

$ GET 'http://localhost:8123/?query=SELECT 1'
1

$ echo -ne 'GET /?query=SELECT%201 HTTP/1.0\r\n\r\n' | nc localhost 8123
HTTP/1.0 200 OK
Connection: Close
Date: Fri, 16 Nov 2012 19:21:50 GMT

1

このように、スペースはURLエスケープされなければならない点は多少不便です。 wget は全てをエスケープしますが、 keep-alive と Transfer-Encoding: chunked を使用するとHTTP 1.1では上手く動作しないため、使用しないでください。

$ echo 'SELECT 1' | curl 'http://localhost:8123/' --data-binary @-
1

$ echo 'SELECT 1' | curl 'http://localhost:8123/?query=' --data-binary @-
1

$ echo '1' | curl 'http://localhost:8123/?query=SELECT' --data-binary @-
1

クエリの一部がパラメータで送信され、もう一部がPOSTで送信されると、これら2つのデータの間には改行が挿入されます。

例(これは動作しません):

$ echo 'ECT 1' | curl 'http://localhost:8123/?query=SEL' --data-binary @-
Code: 59, e.displayText() = DB::Exception: Syntax error: failed at position 0: SEL
ECT 1
, expected One of: SHOW TABLES, SHOW DATABASES, SELECT, INSERT, CREATE, ATTACH, RENAME, DROP, DETACH, USE, SET, OPTIMIZE., e.what() = DB::Exception

デフォルトでは、データは TSV(Tab Separated Values形式) で返されます。(詳細については、Formatsの項を参照) FORMAT 句を使用して他の形式にする事も出来ます。

$ echo 'SELECT 1 FORMAT Pretty' | curl 'http://localhost:8123/?' --data-binary @-
┏━━━┓
┃ 1 ┃
┡━━━┩
│ 1 │
└───┘

INSERTクエリはPOSTで行います。この場合、URLパラメータにクエリの先頭を記述し、POSTを使用して挿入するデータを渡す事が出来ます。挿入するデータは例えばMySQLからのタブ区切りのダンプデータです。このようにして、INSERTクエリはMySQLの LOAD DATA LOCAL INFILE を置き換えます。

例(テーブル作成):

echo 'CREATE TABLE t (a UInt8) ENGINE = Memory' | POST 'http://localhost:8123/'

データの挿入に INSERT クエリを使用する:

echo 'INSERT INTO t VALUES (1),(2),(3)' | POST 'http://localhost:8123/'

データはクエリとは別に送信可能:

echo '(4),(5),(6)' | POST 'http://localhost:8123/?query=INSERT INTO t VALUES'

任意のフォーマットを指定できます。 "Values" フォーマットは "INSERT INTO t VALUES" を書くときに使用されるものと同じです。

echo '(7),(8),(9)' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT Values'

タブで区切られたダンプを INSERT するには、対応するフォーマットを指定します。

echo -ne '10\n11\n12\n' | POST 'http://localhost:8123/?query=INSERT INTO t FORMAT TabSeparated'

テーブルの内容を取得します。並列問い合わせのため、データの出力順番は保証されません。

$ GET 'http://localhost:8123/?query=SELECT a FROM t'
7
8
9
10
11
12
1
2
3
4
5
6

テーブルのドロップ:

POST 'http://localhost:8123/?query=DROP TABLE t'

データテーブルを返さない正常な要求に対しては、空の応答が返されます。

データを送信するとき圧縮を利用出来ます。

ClickHouseの内部圧縮フォーマットを利用するには、特別な圧縮プログラムを使用する必要があります。 (sudo apt-get install compressor-metrika-yandex) URLに 'compress=1' を指定した場合、サーバーは送信したデータを圧縮します。URLに 'decompress=1' を指定した場合、サーバーはPOST形式で渡したのと同じデータを解凍します。

標準のgzipベースのHTTP圧縮も使用できます。gzip圧縮されたPOSTデータを送信するには、 Content-Encoding:gizp をリクエストしてPOST本体を gzip するだけです。応答を圧縮するには、要求ヘッダに Accept-Encoding:gizp を追加し、 ClickHouseの設定 enable_http_compression を有効にする必要があります。

これらを使用して、大量のデータを送信するとき、圧縮されたダンプを生成するときのネットワークトラフィックを削減できます。

'database' URLパラメータを使用して、デフォルトのデータベスを指定する事が出来ます。

$ echo 'SELECT number FROM numbers LIMIT 10' | curl 'http://localhost:8123/?database=system' --data-binary @-
0
1
2
3
4
5
6
7
8
9

デフォルトは、サーバー設定で登録されているデフォルトデータベースの名前が使用されます。デフォルトは、 'default' というデータベース名になります。また、テーブル名の前に "." を使用してデータベースを指定する事も出来ます。

パスワード認証は2つの方法が提供されています:

HTTPベーシック認証方式:

echo 'SELECT 1' | curl 'http://user:password@localhost:8123/' -d @-

URLパラメータにuser, passwordを指定する方式(訳注:パスワードがログに記録される事があるためよろしくない方法):

echo 'SELECT 1' | curl 'http://localhost:8123/?user=user&password=password' -d @-

ユーザー名を指定しない場合、デフォルト名の 'default' が使用されます。パスワードが指定されない場合、空のパスワードが使用されます。また、URLパラメータを使用して、単一のクエリまたは設定プロファイルを指定する事もで出来ます。例: http://localhost:8123/?profile=web&max_rows_to_read=1000000000&query=SELECT+1

より詳しい情報は、 "Setting" の項を参照してください。

$ echo 'SELECT number FROM system.numbers LIMIT 10' | curl 'http://localhost:8123/?' --data-binary @-
0
1
2
3
4
5
6
7
8
9

その他のパラメータにすいては "SET" の項を参照してください。

ClickHouseセッションはHTTPプロトコルで使用できます。これを行うには、HTTPリクエストで session_id GET パラメータを指定する必要があります。任意の英数字の文字列を session_id として使用できます。デフォルトでは、セッションは60秒間使用しないとタイムアウトします。これを変更するには、サーバー設定ファイルの
default_session_timeout を設定するか、GETパラメータに session_timeout を追加します。GETパラメータ session_check=1 を使用して、セッションのステータスを確認する事も出来ます。セッションを使用する場合、同じ session_id で同時に2つのクエリを実行する事は出来ません。

send_progress_in_http_header の設定を有効にすると、 X-ClickHouse-Progress ヘッダーでクエリ実行の進行状況を取得できます。

実行中のクエリは、HTTP接続を終了したあとで自動的に中止されません。解析とデータの整形はサーバー側で実行され、ネットワーク接続が終了されているので破棄されてしまいます。オプションの query_id パラメータは、クエリID(任意の文字列)として渡す事が出来ます。詳細は "Settings, replace_running_query" の項を参照してください。

オプションの 'quota_key' パラメータは、クォーターキー(任意の文字列)として渡す事が出来ます。詳細は "Quotas" の項を参照してください。

HTTPインターフェースでは、外部データ(外部一時テーブル)をクエリに渡す事が出来ます。詳細は、 "External data for query processing" を参照してください。

Response buffering

サーバー側で応答バッファリングを有効にする事が出来ます。この目的のために、 buffer_size 及び wait_end_of_query URLパラメータが提供されます。

buffer_size は、サーバメモリにバッファリングするバイト数を指定します。レスポンスのボディがこの閾値より大きい場合、バッファはHTTPチャンネルに書き込まれ、残りのデータはHTTPチャンネルに直接送信されます。
(HTTPチャンネル？)

応答全体をバッファリングするには、 wait_end_of_query=1 を設定します。この場合、メモリに保存しきれないデータはサーバーのテンポラリファイルにバッファリングされます。

例:

curl -sS 'http://localhost:8123/?max_result_bytes=4000000&buffer_size=3000000&wait_end_of_query=1' -d 'SELECT toUInt8(number) FROM system.numbers LIMIT 9000000 FORMAT RowBinary'

バッファリングを使用して、レスポンスコードとHTTPヘッダーがクライアントに送信されたあと、クエリ処理エラーが発生する状況を回避します。この状況では、応答メッセージの最後にエラーメッセージが書き込まれ、クライアント側は、レスポンスのパース段階でしかエラーは検出できません。

JDBC driver

(省略)

Native interface(TCP)

(省略)

Libraries from third-party developers

(省略)

Visual interfaces from third-party developers

(省略)