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](#configuring) を参照。

### Usage

clickhouse-clientは、インタラクティブ及び非インタラクティブモード(バッチモード)で使用できます。バッチモードを使用するには、 `query` パラメータを指定するか、 `STDIN` にデータを送ります。 [HTTP interface](#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

(省略)