Template

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

Описание

Для случаев, когда вам нужно больше настройки, чем предлагают другие стандартные форматы, формат 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_i	Разделитель между значениями (символ $ можно экранировать как $$)
column_i	Имя или индекс колонки, значения которой нужно выбрать или вставить (если пусто, колонка будет пропущена)
serializeAs_i	Правило экранирования для значений колонки.

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

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

примечание

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

Рассмотрим пример. Данная строка формата:

Следующие значения будут выведены (если использовать 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.

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_format (для format_template_row) и format_template_resultset_format (для format_template_resultset), чтобы задать строку шаблона непосредственно в запросе, а не как путь к файлу, который его содержит.

примечание

Правила для строк формата и escape-последовательностей такие же, как для:

• format_template_row при использовании format_template_row_format.
• format_template_resultset при использовании format_template_resultset_format.

Пример Использования

Рассмотрим два примера того, как мы можем использовать формат Template, сначала для выбора данных, а затем для вставки данных.

Выбор Данных

Результат:

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

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

Встроенная Спецификация

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

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

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