Template

输入	输出	别名
✔	✔

描述

对于需要比其他标准格式提供更多自定义的情况，Template 格式允许用户使用占位符指定自己的自定义格式字符串，并指定数据的转义规则。

它使用以下设置

设置	描述
`format_template_row`	指定包含行格式字符串的文件的路径。
`format_template_resultset`	指定包含行格式字符串的文件的路径
`format_template_rows_between_delimiter`	指定行之间的分隔符，该分隔符在除最后一行之外的每行之后打印（或预期）（默认为 `\n`）
`format_template_row_format`	指定内联行格式字符串。
`format_template_resultset_format`	指定内联结果集格式字符串。
其他格式的一些设置（例如，使用 `JSON` 转义时的 `output_format_json_quote_64bit_integers`

设置和转义规则

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`	类似于同名格式
`Escaped`	类似于 `TSV`
`Quoted`	类似于 `Values`
`Raw`	不转义，类似于 `TSVRaw`
`None`	无转义规则 - 请参阅下面的注释

注意

如果省略转义规则，则将使用 None。 XML 仅适用于输出。

让我们看一个例子。给定以下格式字符串

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

以下值将在列 Search phrase:、, count:、, ad price: $ 和 ; 分隔符之间打印（如果使用 SELECT）或预期（如果使用 INPUT）

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} 用作默认值。

对于插入查询，格式允许跳过一些列或字段（如果存在前缀或后缀）（请参阅示例）。

内联规范

通常，将模板格式的格式配置（由 format_template_row、format_template_resultset 设置）部署到集群中所有节点上的目录中具有挑战性或不可能。此外，格式可能非常简单，不需要放置在文件中。

对于这些情况，可以使用 format_template_row_format（对于 format_template_row）和 format_template_resultset_format（对于 format_template_resultset）在查询中直接设置模板字符串，而不是作为包含该字符串的文件的路径。

注意

格式字符串和转义序列的规则与以下规则相同

format_template_row 在使用 format_template_row_format 时。
format_template_resultset 在使用 format_template_resultset_format 时。

示例用法

让我们看两个如何使用 Template 格式的示例，首先用于选择数据，然后用于插入数据。

选择数据

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>

结果

<!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 表中 SELECT 一些 ClickHouse 格式的名称，并将它们格式化为 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。我们使用设置 format_template_row_format 为我们的行指定模板字符串 |`{0:XML}`|。 Template 格式将使用给定格式将我们的行插入到占位符 ${data} 中。在此示例中，我们只有一列，但如果您想添加更多列，可以通过将 {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`|

描述​

设置和转义规则​

format_template_row​

format_template_rows_between_delimiter​

format_template_resultset​

内联规范​

示例用法​

选择数据​

插入数据​

内联规范​

描述

设置和转义规则

format_template_row

format_template_rows_between_delimiter

format_template_resultset

内联规范

示例用法

选择数据

插入数据

内联规范