Help us understand the problem. What is going on with this article?

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

More than 1 year has passed since last update.

以下、 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 (と historylibedit ビルドによっては違います)に基づいています。つまり、使い慣れたキーボードショートカットを使用して履歴を保持します。履歴は ~/.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-aliveTransfer-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

(省略)

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした