diff --git a/docs/ru/interfaces/formats.md b/docs/ru/interfaces/formats.md index bc685443b0d..5442c6a0e5e 100644 --- a/docs/ru/interfaces/formats.md +++ b/docs/ru/interfaces/formats.md @@ -10,6 +10,8 @@ ClickHouse может принимать (`INSERT`) и отдавать (`SELECT | [TabSeparatedRaw](#tabseparatedraw) | ✗ | ✔ | | [TabSeparatedWithNames](#tabseparatedwithnames) | ✔ | ✔ | | [TabSeparatedWithNamesAndTypes](#tabseparatedwithnamesandtypes) | ✔ | ✔ | +| [Template](#template) | ✔ | ✔ | +| [TemplateIgnoreSpaces](#templateignorespaces) | ✔ | ✗ | | [CSV](#csv) | ✔ | ✔ | | [CSVWithNames](#csvwithnames) | ✔ | ✔ | | [Values](#data-format-values) | ✔ | ✔ | @@ -118,6 +120,121 @@ world Этот формат также доступен под именем `TSVWithNamesAndTypes`. +## Template {#template} + +Этот формат позволяет указать произвольную форматную строку, в которую подставляются значения, сериализованные выбранным способом. + +Для этого используются настройки `format_schema`, `format_schema_row`, `format_schema_rows_between_delimiter` и настройки экранирования других форматов (например, `output_format_json_quote_64bit_integers` при экранировании как в `JSON`, см. далее) + +Форматная строка `format_schema_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`) + + Тип экранирования для столбца можно не указывать, в таком случае используется `Escaped`. `XML` и `Raw` поддерживаются только для вывода. + + Так, в форматной строке + + `Search phrase: ${SearchPhrase:Quoted}, count: ${c}, ad price: $$${price:JSON};` + + между разделителями `Search phrase: `, `, count: `, `, ad price: $` и `;` при выводе будут подставлены (при вводе - будут ожидаться) значения столбцов `SearchPhrase`, `c` и `price`, сериализованные как `Quoted`, `Escaped` и `JSON` соответственно, например: + + `Search phrase: 'bathroom interior design', count: 2166, ad price: $3;` + + Настройка `format_schema_rows_between_delimiter` задаёт разделитель между строками, который выводится (или ожмдается при вводе) после каждой строки, кроме последней. + +Форматная строка `format_schema` имеет аналогичный `format_schema_row` синтаксис и позволяет указать префикс, суффикс и способ вывода дополнительной информации. Вместо имён столбцов в ней указываются следующие имена подстановок: + + - `data` - строки с данными в формате `format_schema_row`, разделённые `format_schema_rows_between_delimiter`. Эта подстановка должна быть первой подстановкой в форматной строке. + - `totals` - строка с тотальными значениями в формате `format_schema_row` (при использовании WITH TOTALS) + - `min` - строка с минимальными значениями в формате `format_schema_row` (при настройке extremes, выставленной в 1) + - `max` - строка с максимальными значениями в формате `format_schema_row` (при настройке extremes, выставленной в 1) + - `rows` - общее количество выведенных стрчек + - `rows_before_limit` - не менее скольких строчек получилось бы, если бы не было LIMIT-а. Выводится только если запрос содержит LIMIT. В случае, если запрос содержит GROUP BY, `rows_before_limit` - точное число строк, которое получилось бы, если бы не было LIMIT-а. + - `time` - время выполнения запроса в секундах + - `rows_read` - сколько строк было прочитано при выполнении запроса + - `bytes_read` - сколько байт (несжатых) было прочитано при выполнении запроса + + У подстановок `data`, `totals`, `min` и `max` не должны быть указаны типы экранирования. Остальные подстановки - это отдельные значения, для них может быть указан любой тип экранирования. + Если строка `format_schema` пустая, то по-умолчанию используется `${data}`. + При вводе форматная строка `format_schema` должна иметь вид `some prefix ${data} some suffix` т.е. содержать единственную подстановку `data`. + + Пример вывода: +```sql +SELECT SearchPhrase, count() AS c FROM test.hits GROUP BY SearchPhrase ORDER BY c DESC LIMIT 5 +FORMAT Template +SETTINGS format_schema = ' + Search phrases + + + + ${data} +
Search phrases
Search phrase Count
+ + ${max} +
Max
+ Processed ${rows_read:XML} rows in ${time:XML} sec + +', +format_schema_rows = ' ${SearchPhrase:XML} ${с:XML} ', +format_schema_rows_between_delimiter = '\n ' +``` +```html + + Search phrases + + + + + + + + +
Search phrases
Search phrase Count
8267016
bathroom interior design 2166
yandex 1655
spring 2014 fashion 1549
freeform photos 1480
+ + +
Max
8873898
+ Processed 3095973 rows in 0.1569913 sec + + +``` + +Пример ввода: +```json +{"array": + [ + {"PageViews": 5, "UserID": "4324182021466249494", "Duration": 146, "Sign": -1}, + {"PageViews": 6, "UserID": "4324182021466249494", "Duration": 185, "Sign": 1} + ] +} +``` +```sql +cat data.json | ./clickhouse client --query "INSERT INTO UserActivity FORMAT Template SETTINGS format_schema = '{\"array\":\n [\n \${data}\n ]\n}', format_schema_rows = '{\"PageViews\": \${project:JSON}, \"UserID\": \${date:JSON}, \"Duration\": \${size:JSON}, \"Sign\": \${hits:JSON}}', format_schema_rows_between_delimiter = ',\n '" +``` +В данном примере экранирование `"` и `$` нужно, чтобы настройки корректно передались через аргумент командной строки. Без этих экранирований настройки могли бы выглядеть так: +``` +format_schema = '{"array": + [ + ${data} + ] +}', +format_schema_rows = '{"PageViews": ${PageViews:JSON}, "UserID": ${UserID:JSON}, "Duration": ${Duration:JSON}, "Sign": ${Sign:JSON}}', +format_schema_rows_between_delimiter = ',\n ' +``` +Все разделители во входных данных должны строго соответствовать разделителям в форматных строках. + +## TemplateIgnoreSpaces {#templateignorespaces} + +Отличается от формата `Template` тем, что пропускает пробельные символы между разделителями и значениями во входном потоке. При этом, если форматные строки содержат пробельные символы, эти символы будут ожидаться во входных данных. Подходит только для ввода. + ## TSKV {#tskv} Похож на TabSeparated, но выводит значения в формате name=value. Имена экранируются так же, как строки в формате TabSeparated и, дополнительно, экранируется также символ =.