Significantly change article about SummingMergeTree.

Article is restructured, text is changed in many places of the document. New syntax for table creation is described.

docs/ru/data_types/nested_data_structures/aggregatefunction.md

@@ -1,3 +1,5 @@
+<a name="data_type-aggregatefunction"></a>
+
 # AggregateFunction(name, types_of_arguments...)
 
 Промежуточное состояние агрегатной функции. Чтобы его получить, используются агрегатные функции с суффиксом -State. Подробнее смотрите в разделе "AggregatingMergeTree".

docs/ru/operations/table_engines/aggregatingmergetree.md

@@ -1,3 +1,5 @@
+<a name="table_engine-aggregatingmergetree"></a>
+
 # AggregatingMergeTree
 
 Отличается от `MergeTree` тем, что при слиянии, выполняет объединение состояний агрегатных функций, хранимых в таблице, для строчек с одинаковым значением первичного ключа.

docs/ru/operations/table_engines/mergetree.md

@@ -25,6 +25,7 @@
 
     При необходимости можно задать способ сэмплирования данных в таблице.
 
+<a name="table_engines-mergetree-configuring">
 
 ## Конфигурирование движка при создании таблицы
 

docs/ru/operations/table_engines/summingmergetree.md

@@ -2,33 +2,104 @@
 
 # SummingMergeTree
 
-Отличается от `MergeTree` тем, что суммирует данные при слиянии.
+Движок наследует функциональность [MergeTree](mergetree.md#table_engines-mergetree). Отличие заключается в том, что для таблиц `SummingMergeTree` при слиянии кусков данных ClickHouse все строки с одинаковым первичным ключом старается заменить на одну, которая хранит только суммы столбцов с цифровым типом данных. Если первичный ключ подобран таким образом, что одному значению ключа соответствует много строк, это значительно уменьшает объем хранения и ускоряет последующую выборку данных.
 
-```sql
+Мы рекомендуем использовать движок в паре с `MergeTree`. В `MergeTree` храните полные данные, а `SummingMergeTree` используйте для хранения агрегированных данных, например, при подготовке отчетов. Такой подход позволит не утратить ценные данные из-за неправильно выбранного первичного ключа.
-SummingMergeTree(EventDate, (OrderID, EventDate, BannerID, ...), 8192)
+
+## Конфигурирование движка при создании таблицы
+
+```
+ENGINE [=] SummingMergeTree([columns]) [PARTITION BY expr] [ORDER BY expr] [SAMPLE BY expr] [SETTINGS name=value, ...]
 ```
 
-Столбцы для суммирования заданы неявно. При слиянии, для всех строчек с одинаковым значением первичного ключа (в примере - OrderID, EventDate, BannerID, ...), производится суммирование значений в числовых столбцах, не входящих в первичный ключ.
+**Параметры SummingMergeTree**
+
+- `columns` — кортеж с именами столбцов для суммирования данных. Необязательный параметр.
+    Столбцы должны иметь числовой тип и не должны входить в первичный ключ.
+
+**Секции ENGINE**
+
+`SummingMergeTree` использует те же [секции ENGINE](mergetree.md#table_engines-mergetree-configuring), что и `MergeTree`.
+
+
+### Устаревший способ конфигурирования движка
+
+!!!attention
+    Не используйте этот способ в новых проектах и по возможности переведите старые проекты на способ описанный выше.
 
 ```sql
-SummingMergeTree(EventDate, (OrderID, EventDate, BannerID, ...), 8192, (Shows, Clicks, Cost, ...))
+SummingMergeTree(EventDate, (OrderID, EventDate, BannerID, ...), 8192, [columns])
 ```
 
-Явно заданные столбцы для суммирования (последний параметр - Shows, Clicks, Cost, ...). При слиянии, для всех строчек с одинаковым значением первичного ключа, производится суммирование значений в указанных столбцах. Указанные столбцы также должны быть числовыми и не входить в первичный ключ.
+Все параметры, кроме `columns` имеют то же значение, что в и `MergeTree`.
 
-Если значения во всех таких столбцах оказались нулевыми, то строчка удаляется.
+- `columns` — кортеж с именами столбцов для суммирования данных. Необязательный параметр. Описание смотрите выше по тексту.
 
-Для остальных столбцов, не входящих в первичный ключ, при слиянии выбирается первое попавшееся значение. Но для столбцов типа AggregateFunction выполняется агрегация согласно заданной функции, так что этот движок фактически ведёт себя как `AggregatingMergeTree`.
 
-При чтении, суммирование не делается само по себе. Если оно необходимо - напишите соответствующий GROUP BY.
+## Пример использования
 
-Дополнительно, таблица может иметь вложенные структуры данных, которые обрабатываются особым образом.
+Рассмотрим следующую таблицу:
-Если название вложенной таблицы заканчивается на Map и она содержит не менее двух столбцов, удовлетворяющих следующим критериям:
 
--   первый столбец - числовой ((U)IntN, Date, DateTime), назовем его условно key,
+```sql
--   остальные столбцы - арифметические ((U)IntN, Float32/64), условно (values...),
+CREATE TABLE summtt
+(
+    key UInt32,
+    value UInt32
+)
+ENGINE = SummingMergeTree()
+ORDER BY key
+```
 
-то такая вложенная таблица воспринимается как отображение key `=>` (values...) и при слиянии ее строк выполняется слияние элементов двух множеств по key со сложением соответствующих (values...).
+Добавим в неё данные:
+
+```
+:) INSERT INTO summtt Values(1,1),(1,2),(2,1)
+```
+
+ClickHouse может не просуммировать данные или просуммировать их не полностью (смотрите ниже по тексту), поэтому при запросе мы используем агрегатную функцию `sum` и секцию `GROUP BY`.
+
+```sql
+SELECT key, sum(value) FROM summtt GROUP BY key
+```
+```
+┌─key─┬─sum(value)─┐
+│   2 │          1 │
+│   1 │          3 │
+└─────┴────────────┘
+```
+
+## Особенности обработки параметров и данных
+
+При вставке данных в таблицу они сохраняются как есть. Периодически ClickHouse выполняет слияние вставленных кусков данных и именно в этот момент производится суммирование и замена многих строк с одинаковым первичным ключом на одну.
+
+ClickHouse рассчитывает расход ресурсов и может не выполнить суммирование или выполнить его не полностью, если посчитает эту операцию слишком затратной. Поэтому, при выборке данных (`SELECT`) необходимо использовать агрегатную функцию [sum()](../../query_language/agg_functions/reference.md#agg_function-sum) и секцию `GROUP BY` как описано в примере выше.
+
+### Суммирование простых данных
+
+Если столбцы для суммирования не заданы, то ClickHouse суммирует значения в столбцах с числовым типом данных, не входящих в первичный ключ.
+
+Если столбцы для суммирования заданы, то для всех строчек с одинаковым значением первичного ключа ClickHouse суммирует значения в указанных столбцах. Столбцы должны обязательно иметь числовой тип данных.
+
+Если значения во всех столбцах для суммирования оказались нулевыми, то строчка удаляется.
+
+Для столбцов, не входящих в первичный ключ и не суммирующихся, выбирается произвольное значение из имеющихся.
+
+Столбцы, входящие в первичный ключ не суммируются.
+
+### Суммирование в столбцах AggregateFunction
+
+Для столбцов типа [AggregateFunction](../../data_types/nested_data_structures/aggregatefunction.md#data_type-aggregatefunction) ClickHouse выполняет агрегацию согласно заданной функции, повторяя поведение движка [AggregatingMergeTree](aggregatingmergetree.md#table_engine-aggregatingmergetree).
+
+### Обработка вложенных структур
+
+Таблица может иметь вложенные структуры данных, которые обрабатываются особым образом.
+
+Если название вложенной таблицы заканчивается на `Map` и она содержит не менее двух столбцов, удовлетворяющих критериям:
+
+-   первый столбец - числовой `(*Int*, Date, DateTime)`, назовем его условно `key`,
+-   остальные столбцы - арифметические `(*Int*, Float32/64)`, условно `(values...)`,
+
+то вложенная таблица воспринимается как отображение `key => (values...)` и при слиянии её строк выполняется слияние элементов двух множеств по `key` со сложением соответствующих `(values...)`.
 
 Примеры:
 
@@ -39,8 +110,6 @@ SummingMergeTree(EventDate, (OrderID, EventDate, BannerID, ...), 8192, (Shows, C
 [(1, 100), (2, 150)] + [(1, -100)] -> [(2, 150)]
 ```
 
-Для агрегации Map используйте функцию sumMap(key, value).
+При запросе данных используйте функцию [sumMap(key, value)](../../query_language/agg_functions/reference.md#agg_function-summap) для агрегации `Map`.
 
-Для вложенных структур данных не нужно указывать её столбцы в качестве списка столбцов для суммирования.
+Для вложенной структуры данных не нужно указывать её столбцы в кортеже столбцов для суммирования.
-
-Этот движок таблиц разработан по просьбе БК, и является мало полезным. Помните, что при хранении лишь предагрегированных данных, вы теряете часть преимуществ системы.

docs/ru/query_language/agg_functions/reference.md

@@ -73,6 +73,7 @@ FROM ontime
 
 Вычисляет значение arg при максимальном значении val. Если есть несколько разных значений arg для максимальных значений val, то выдаётся первое попавшееся из таких значений.
 
+<a name="agg_function-sum"></a>
 
 ## sum(x)
 
@@ -86,6 +87,7 @@ FROM ontime
 
 Работает только для чисел.
 
+<a name="agg_function-summap"></a>
 
 ## sumMap(key, value)