Template

Вход	Выход	Псевдоним
✔	✔

Описание

Для случаев, когда вам нужно больше настройки, чем предлагают другие стандартные форматы, формат Template позволяет пользователю указывать собственную строку формата с заполнителями для значений и задавать правила экранирования для данных.

Он использует следующие настройки:

Настройка	Описание
format_template_row	Указывает путь к файлу, содержащему строки формата для строк.
format_template_resultset	Указывает путь к файлу, содержащему строки формата для строк
format_template_rows_between_delimiter	Указывает разделитель между строками, который выводится (или ожидается) после каждой строки, кроме последней (\n по умолчанию)
format_template_row_format	Указывает строку формата для строк in-line.
format_template_resultset_format	Указывает строку формата для результирующего набора in-line.
Некоторые настройки других форматов (например, output_format_json_quote_64bit_integers при использовании JSON экранирования)

Настройки и правила экранирования

format_template_row

Настройка format_template_row указывает путь к файлу, который содержит строки формата для строк с синтаксисом:

Где:

Часть синтаксиса	Описание
delimiter_i	Разделитель между значениями (символ $ можно экранировать как $$)
column_i	Имя или индекс колонки, значения которой необходимо выбрать или вставить (если пусто, колонка будет пропущена)
serializeAs_i	Правило экранирования для значений колонки.

Поддерживаются следующие правила экранирования:

Правило экранирования	Описание
CSV, JSON, XML	Похоже на форматы с теми же именами
Escaped	Похоже на TSV
Quoted	Похоже на Values
Raw	Без экранирования, похоже на TSVRaw
None	Нет правила экранирования - см. примечание ниже

примечание

Если правило экранирования опущено, будет использовано None. XML подходит только для вывода.

Давайте рассмотрим пример. При заданной строке формата:

Следующие значения будут выведены (если используется SELECT) или ожидаются (если используется INPUT), между колонками Поисковая фраза:, , количество:, , цена объявления: $ и ; соответственно:

• s (с правилом экранирования Quoted)
• c (с правилом экранирования Escaped)
• p (с правилом экранирования JSON)

Например:

• Если вставляется, строка ниже соответствует ожидаемому шаблону и будет считывать значения дизайн ванной комнаты, 2166, $3 в колонки Поисковая фраза, количество, цена объявления.
• Если выбирается, строка ниже является выводом, если значения дизайн ванной комнаты, 2166, $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} как значение по умолчанию.

Для запросов вставки формат позволяет пропускать некоторые колонки или поля, если есть префикс или суффикс (см. пример).

In-line спецификация

Часто настройки формата (установленные с помощью 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, сначала для выбора данных, затем для вставки данных.

Выбор данных

Результат:

Вставка данных

PageViews, UserID, Duration и Sign внутри заполнителей - это имена колонок в таблице. Значения после Неиспользуемое поле в строках и после \nВсего строк: в суффиксе будут игнорироваться. Все разделители во входных данных должны строго совпадать с разделителями в заданных строках формата.

In-line спецификация

Устали вручную форматировать таблицы markdown? В этом примере мы посмотрим, как можно использовать формат Template и настройки in-line спецификации, чтобы выполнить простую задачу - выбрать имена некоторых форматов ClickHouse из таблицы system.formats и отформатировать их как таблицу markdown. Это можно легко сделать с помощью формата Template и настроек format_template_row_format и format_template_resultset_format.

В предыдущих примерах мы указали строки формата результирующего набора и строки формата для строк в отдельных файлах, где пути к этим файлам указывались с помощью настроек format_template_resultset и format_template_row соответственно. Здесь мы сделаем это in-line, потому что наш шаблон тривиален, состоящий только из нескольких | и - для составления таблицы markdown. Мы укажем нашу строку шаблона результирующего набора с помощью настройки format_template_resultset_format. Чтобы сделать заголовок таблицы, мы добавили |Форматы ClickHouse|\n|---|\n перед ${data}. Мы используем настройку format_template_row_format, чтобы указать строку шаблона |`{0:XML}`| для наших строк. Формат Template вставит наши строки с данным форматом в заполнитель ${data}. В этом примере у нас только одна колонка, но если вы хотите добавить больше, вы можете сделать это, добавляя {1:XML}, {2:XML}... и т.д. в вашу строку шаблона для строк, выбирая правило экранирования соответствующим образом. В этом примере мы выбрали правило экранирования XML.

Смотрите-ка! Мы избавили себя от необходимости вручную добавлять все эти | и - для создания таблицы markdown: