Docs (ru)

2024-11-22 23:52:03 +00:00 · 2019-04-22 03:34:19 +03:00 · 2019-04-22 03:34:19 +03:00 · 96776c7fd5
commit 96776c7fd5
parent f43f7c43a5
1 changed files with 117 additions and 0 deletions
--- 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 = '<!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>',
+format_schema_rows = '<tr> <td>${SearchPhrase:XML}</td> <td>${с:XML}</td> </tr>',
+format_schema_rows_between_delimiter = '\n    '
+```
+```html
+<!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>yandex</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>
+```
+
+Пример ввода:
+```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 и, дополнительно, экранируется также символ =.