Template - ClickHouse Documentation

入力	出力	エイリアス
✔	✔

説明

他の標準フォーマットでは足りない、より細かなカスタマイズが必要な場合は、 Template フォーマットを使うと、値のプレースホルダーを含む独自のフォーマット文字列と、データのエスケープ規則を指定できます。使用する設定は次のとおりです。

Setting	Description
`format_template_row`	行のフォーマット文字列を含むファイルへの path を指定します。
`format_template_resultset`	行のフォーマット文字列を含むファイルへの path を指定します。
`format_template_rows_between_delimiter`	行間の区切り文字を指定します。これは最後の行を除く各行の後に出力される (または入力として期待される) ものです (デフォルトは `\n`)
`format_template_row_format`	行のフォーマット文字列をインラインで指定します。
`format_template_resultset_format`	結果セットのフォーマット文字列をインラインで指定します。
Some settings of other formats (e.g.`output_format_json_quote_64bit_integers` when using `JSON` escaping

設定とエスケープルール

format_template_row

設定 format_template_row は、次の構文で行のフォーマット文字列を含むファイルへのパスを指定します。

delimiter_1${column_1:serializeAs_1}delimiter_2${column_2:serializeAs_2} ... delimiter_N

各構文要素の意味は次のとおりです。

Part of syntax	Description
`delimiter_i`	値の間の区切り文字 (`$` 記号は `$$` としてエスケープ可能)
`column_i`	選択または挿入する値に対応するカラムの名前または索引 (空の場合、そのカラムはスキップされます)
`serializeAs_i`	カラムの値に適用するエスケープ規則。

サポートされているエスケープ規則は次のとおりです。

Escaping Rule	Description
`CSV`, `JSON`, `XML`	同名のフォーマットと同様
`Escaped`	`TSV` と同様
`Quoted`	`Values` と同様
`Raw`	エスケープなし。`TSVRaw` と同様
`None`	エスケープ規則なし - 下記の注記を参照

エスケープ規則を省略した場合は、None が使用されます。XML は出力にのみ適しています。

例を見てみましょう。次のフォーマット文字列が与えられているとします。

Search phrase: ${s:Quoted}, count: ${c:Escaped}, ad price: $$${p:JSON};

以下の値は、SELECT を使用する場合は出力され、INPUT を使用する場合は入力として期待されます。それぞれ、カラム Search phrase:, , count:, , ad price: $ の間、および ; の区切り文字で区切られます。

s (エスケープルールは Quoted)
c (エスケープルールは Escaped)
p (エスケープルールは JSON)

例えば:

INSERT する場合、以下の行は期待されるテンプレートに一致しており、値 bathroom interior design, 2166, $3 がカラム Search phrase, count, ad price に読み込まれます。
SELECT する場合、値 bathroom interior design, 2166, $3 がすでにテーブルのカラム Search phrase, count, ad price に格納されているとすると、以下の行が出力されます。

Search phrase: 'bathroom interior design', count: 2166, ad price: $3;

format_template_rows_between_delimiter

設定 format_template_rows_between_delimiter は、行間の区切り文字を指定します。これは、最後の行を除く各行の後に出力される (または入力時に期待される) 文字列です (デフォルトは \n) 。

format_template_resultset

設定 format_template_resultset は、結果セット用のフォーマット文字列を含むファイルのパスを指定します。結果セット用のフォーマット文字列は、行用のフォーマット文字列と同じ構文です。プレフィックスや接尾辞、追加情報の出力方法を指定でき、カラム名の代わりに次のプレースホルダーを含めます。

data は、format_template_row フォーマットのデータを含む行で、format_template_rows_between_delimiter で区切られます。このプレースホルダーは、フォーマット文字列内で最初のプレースホルダーでなければなりません。
totals は、format_template_row フォーマットの合計値を含む行です (WITH TOTALS を使用する場合) 。
min は、format_template_row フォーマットの最小値を含む行です (extremes が 1 に設定されている場合) 。
max は、format_template_row フォーマットの最大値を含む行です (extremes が 1 に設定されている場合) 。
rows は、出力される行の総数です。
rows_before_limit は、LIMIT がなかった場合に存在していた行数の最小値です。これは、クエリに LIMIT が含まれている場合にのみ出力されます。クエリに GROUP BY が含まれる場合、rows_before_limit_at_least は、LIMIT がなかった場合に存在していた行数の正確な値です。
time は、リクエストの実行時間 (秒) です。
rows_read は、読み込まれた行数です。
bytes_read は、読み込まれたバイト数 (非圧縮) です。

プレースホルダー data、totals、min、max にはエスケープ規則を指定してはなりません (または None を明示的に指定する必要があります) 。それ以外のプレースホルダーには、任意のエスケープ規則を指定できます。

format_template_resultset 設定が空文字列の場合、デフォルト値として ${data} が使用されます。

INSERT クエリのフォーマットでは、プレフィックスまたは接尾辞がある場合、一部のカラムまたはフィールドを省略できます (例を参照) 。

インライン指定

多くの場合、Templateフォーマットのフォーマット設定 (format_template_row、format_template_resultset で設定) を、クラスター内のすべてのノードのディレクトリにデプロイするのは困難であり、不可能なこともあります。さらに、フォーマットが非常に単純であれば、ファイルに置く必要がない場合もあります。このような場合は、format_template_row_format (format_template_row 用) および format_template_resultset_format (format_template_resultset 用) を使用して、テンプレート文字列を、それを含むファイルへのパスとしてではなく、クエリ内で直接設定できます。

フォーマット文字列およびエスケープシーケンスのルールは、次の場合と同じです。

format_template_row_format を使用する場合の format_template_row。
format_template_resultset_format を使用する場合の format_template_resultset。

使用例

Templateフォーマットの使用例を2つ見ていきます。まずはデータの選択、次にデータの挿入です。

データの取得

Query

SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 FORMAT Template SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format', format_template_rows_between_delimiter = '\n    '

/some/path/resultset.format

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    ${data}
  </table>
  <table border="1"> <caption>Max</caption>
    ${max}
  </table>
  <b>Processed ${rows_read:XML} rows in ${time:XML} sec</b>
 </body>
</html>

/some/path/row.format

<tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr>

Response

<!DOCTYPE HTML>
<html> <head> <title>Search phrases</title> </head>
 <body>
  <table border="1"> <caption>Search phrases</caption>
    <tr> <th>Search phrase</th> <th>Count</th> </tr>
    <tr> <td></td> <td>8267016</td> </tr>
    <tr> <td>bathroom interior design</td> <td>2166</td> </tr>
    <tr> <td>clickhouse</td> <td>1655</td> </tr>
    <tr> <td>spring 2014 fashion</td> <td>1549</td> </tr>
    <tr> <td>freeform photos</td> <td>1480</td> </tr>
  </table>
  <table border="1"> <caption>Max</caption>
    <tr> <td></td> <td>8873898</td> </tr>
  </table>
  <b>Processed 3095973 rows in 0.1569913 sec</b>
 </body>
</html>

データの挿入

Some header
Page views: 5, User id: 4324182021466249494, Useless field: hello, Duration: 146, Sign: -1
Page views: 6, User id: 4324182021466249494, Useless field: world, Duration: 185, Sign: 1
Total rows: 2

INSERT INTO UserActivity SETTINGS
format_template_resultset = '/some/path/resultset.format', format_template_row = '/some/path/row.format'
FORMAT Template

/some/path/resultset.format

Some header\n${data}\nTotal rows: ${:CSV}\n

/some/path/row.format

Page views: ${PageViews:CSV}, User id: ${UserID:CSV}, Useless field: ${:CSV}, Duration: ${Duration:CSV}, Sign: ${Sign:CSV}

プレースホルダー内のPageViews、UserID、Duration、Signは、テーブル内のカラム名です。行内のUseless fieldの後ろにある値と、接尾辞内の\nTotal rows:の後ろにある値は無視されます。入力データ内のすべての区切り文字は、指定されたフォーマット文字列内の区切り文字と厳密に一致している必要があります。

インライン指定

Markdown テーブルを手作業でフォーマットするのは面倒ではありませんか？この例では、Template フォーマットとインライン指定の設定を使って、シンプルなタスク、つまり system.formats テーブルからいくつかの ClickHouse フォーマット名を SELECT し、それらを Markdown テーブルとして整形する方法を見ていきます。これは、Template フォーマットと設定 format_template_row_format および format_template_resultset_format を使えば簡単に実現できます。前の例では、結果セットと行のフォーマット文字列を別々のファイルに指定し、それらのファイルのパスをそれぞれ設定 format_template_resultset と format_template_row で指定していました。ここでは、テンプレートが単純で、Markdown テーブルを作るための | と - が少しあるだけなので、インラインで指定します。結果セットのテンプレート文字列は、設定 format_template_resultset_format を使って指定します。テーブルヘッダーを作るため、${data} の前に |ClickHouse Formats|\n|---|\n を追加しています。行のテンプレート文字列 |`{0:XML}`| は、設定 format_template_row_format で指定します。Template フォーマットは、指定したフォーマットで行をプレースホルダー ${data} に挿入します。この例ではカラムは 1 つだけですが、さらに追加したい場合は、行テンプレート文字列に {1:XML}、{2:XML} などを追加すれば対応できます。その際は必要に応じて適切なエスケープルールを選択してください。この例では、エスケープルール XML を使用しています。

Query

WITH formats AS
(
 SELECT * FROM system.formats
 ORDER BY rand()
 LIMIT 5
)
SELECT * FROM formats
FORMAT Template
SETTINGS
 format_template_row_format='|`${0:XML}`|',
 format_template_resultset_format='|ClickHouse Formats|\n|---|\n${data}\n'

ご覧のとおり、あの Markdown テーブルを作るために大量の | や - を手作業で追加する手間が省けました。

Response

|ClickHouse Formats|
|---|
|`BSONEachRow`|
|`CustomSeparatedWithNames`|
|`Prometheus`|
|`DWARF`|
|`Avro`|

​説明

​設定とエスケープルール

​format_template_row

​format_template_rows_between_delimiter

​format_template_resultset

​インライン指定

​使用例

​データの取得

​データの挿入

​インライン指定

説明

設定とエスケープルール

format_template_row

format_template_rows_between_delimiter

format_template_resultset

インライン指定

使用例

データの取得

データの挿入

インライン指定