メインコンテンツまでスキップ
メインコンテンツまでスキップ

テンプレート

InputOutputAlias

説明

他の標準形式が提供するよりも多くのカスタマイズが必要な場合、Template形式ではユーザーが値のプレースホルダーを含むカスタムフォーマット文字列を指定し、データに対するエスケープルールを定義できます。

以下の設定を使用します:

設定説明
format_template_row行のフォーマット文字列を含むファイルへのパスを指定します。
format_template_resultset行のフォーマット文字列を含むファイルへのパスを指定します。
format_template_rows_between_delimiter行間の区切り文字を指定します。最後の行を除くすべての行の後に印刷(または期待)されます(デフォルトは\n)。
format_template_row_format行のフォーマット文字列を指定します インライン
format_template_resultset_format結果セットのフォーマット文字列を指定します インライン
他の形式の一部の設定(例:output_format_json_quote_64bit_integersを使用する場合のJSONエスケープ)

設定とエスケープルール

format_template_row

設定format_template_rowは、以下の構文を持つ行のフォーマット文字列を含むファイルへのパスを指定します:

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

ここで:

構文の一部説明
delimiter_i値の間の区切り文字($記号は$$としてエスケープできます)
column_i選択または挿入する値のカラムの名前またはインデックス(空の場合はカラムはスキップされます)
serializeAs_iカラム値に対するエスケープルール。

以下のエスケープルールがサポートされています:

エスケープルール説明
CSV, JSON, XML同名の形式に類似
EscapedTSVに類似
QuotedValuesに類似
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の場合、以下の行は期待されるテンプレートに一致し、Search phrase, count, ad priceの各カラムにbathroom interior design, 2166, $3の値を読み込みます。
  • 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形式です(極端な値が1に設定されている場合)。
  • maxは、最大値を持つ行で、format_template_row形式です(極端な値が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}がデフォルト値として使用されます。

挿入クエリでは、フォーマットに従って列やフィールドをスキップできます(プレフィックスまたはサフィックスを参照)。

インライン指定

フォーマット設定(format_template_row, format_template_resultsetで設定された内容)をクラスタ内のすべてのノードにディレクトリとして展開するのが困難または不可能な場合があります。 さらに、フォーマットが非常に単純であり、ファイルに配置する必要がないこともあります。

このような場合には、format_template_row_formatformat_template_row用)およびformat_template_resultset_formatformat_template_resultset用)を使用して、クエリ内で直接テンプレート文字列を設定できます。 ファイルへのパスではなく。

注記

フォーマット文字列とエスケープシーケンスに関するルールは、次の場合と同じです:

使用例

Template形式を使用する2つの例を見てみましょう。まずはデータを選択する場合、次にデータを挿入する場合です。

データの選択

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    '
<!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>
<tr> <td>${0:XML}</td> <td>${1:XML}</td> </tr>

結果:

<!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 header\n${data}\nTotal rows: ${:CSV}\n
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にしました。

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テーブルを作るために手動でたくさんの|-を追加する手間が省けました:

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