Merge pull request #25586 from CurtizJ/fix-doc

Fix docs for function `initializeAggregation`

docs/en/sql-reference/aggregate-functions/reference/initializeAggregation.md

@@ -1,37 +0,0 @@
----
-toc_priority: 150
----
-
-## initializeAggregation {#initializeaggregation}
-
-Initializes aggregation for your input rows. It is intended for the functions with the suffix `State`.
-Use it for tests or to process columns of types `AggregateFunction` and `AggregationgMergeTree`.
-
-**Syntax**
-
-``` sql
-initializeAggregation (aggregate_function, column_1, column_2)
-```
-
-**Arguments**
-
--   `aggregate_function` — Name of the aggregation function. The state of this function — the creating one. [String](../../../sql-reference/data-types/string.md#string).
--   `column_n` — The column to translate it into the function as it's argument. [String](../../../sql-reference/data-types/string.md#string).
-
-**Returned value(s)**
-
-Returns the result of the aggregation for your input rows. The return type will be the same as the return type of function, that `initializeAgregation` takes as first argument.
-For example for functions with the suffix `State` the return type will be `AggregateFunction`.
-
-**Example**
-
-Query:
-
-```sql
-SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM system.numbers LIMIT 10000);
-```
-Result:
-
-┌─uniqMerge(state)─┐
-│                3 │
-└──────────────────┘

docs/en/sql-reference/functions/other-functions.md

@@ -831,7 +831,7 @@ Returns 0 for the first row and the difference from the previous row for each su
 
 !!! warning "Warning"
     It can reach the previous row only inside the currently processed data block.
-    
+
 The result of the function depends on the affected data blocks and the order of data in the block.
 
 The rows order used during the calculation of `runningDifference` can differ from the order of rows returned to the user.
@@ -908,7 +908,7 @@ Same as for [runningDifference](./other-functions.md#other_functions-runningdiff
 ## runningConcurrency {#runningconcurrency}
 
 Calculates the number of concurrent events.
-Each event has a start time and an end time. The start time is included in the event, while the end time is excluded. Columns with a start time and an end time must be of the same data type. 
+Each event has a start time and an end time. The start time is included in the event, while the end time is excluded. Columns with a start time and an end time must be of the same data type.
 The function calculates the total number of active (concurrent) events for each event start time.
 
 
@@ -1424,11 +1424,83 @@ Result:
 └───────────┴────────┘
 ```
 
+## initializeAggregation {#initializeaggregation}
+
+Calculates result of aggregate function based on single value. It is intended to use this function to initialize aggregate functions with combinator [-State](../../sql-reference/aggregate-functions/combinators.md#agg-functions-combinator-state). You can create states of aggregate functions and insert them to columns of type [AggregateFunction](../../sql-reference/data-types/aggregatefunction.md#data-type-aggregatefunction) or use initialized aggregates as default values.
+
+**Syntax**
+
+``` sql
+initializeAggregation (aggregate_function, arg1, arg2, ..., argN)
+```
+
+**Arguments**
+
+-   `aggregate_function` — Name of the aggregation function to initialize. [String](../../sql-reference/data-types/string.md).
+-   `arg` — Arguments of aggregate function.
+
+**Returned value(s)**
+
+- Result of aggregation for every row passed to the function.
+
+The return type is the same as the return type of function, that `initializeAgregation` takes as first argument.
+
+**Example**
+
+Query:
+
+```sql
+SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
+```
+Result:
+
+```text
+┌─uniqMerge(state)─┐
+│                3 │
+└──────────────────┘
+```
+
+Query:
+
+```sql
+SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
+```
+Result:
+
+```text
+┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
+│                          0 │ AggregateFunction(sum, UInt8) │
+│                          1 │ AggregateFunction(sum, UInt8) │
+│                          2 │ AggregateFunction(sum, UInt8) │
+│                          0 │ AggregateFunction(sum, UInt8) │
+│                          1 │ AggregateFunction(sum, UInt8) │
+└────────────────────────────┴───────────────────────────────┘
+```
+
+Example with `AggregatingMergeTree` table engine and `AggregateFunction` column:
+
+```sql
+CREATE TABLE metrics
+(
+    key UInt64,
+    value AggregateFunction(sum, UInt64) DEFAULT initializeAggregation('sumState', toUInt64(0))
+)
+ENGINE = AggregatingMergeTree
+ORDER BY key
+```
+
+```sql
+INSERT INTO metrics VALUES (0, initializeAggregation('sumState', toUInt64(42)))
+```
+
+**See Also**
+-   [arrayReduce](../../sql-reference/functions/array-functions.md#arrayreduce)
+
 ## finalizeAggregation {#function-finalizeaggregation}
 
 Takes state of aggregate function. Returns result of aggregation (or finalized state when using[-State](../../sql-reference/aggregate-functions/combinators.md#agg-functions-combinator-state) combinator).
 
-**Syntax** 
+**Syntax**
 
 ``` sql
 finalizeAggregation(state)
@@ -1442,7 +1514,7 @@ finalizeAggregation(state)
 
 -   Value/values that was aggregated.
 
-Type: Value of any types that was aggregated. 
+Type: Value of any types that was aggregated.
 
 **Examples**
 
@@ -1474,7 +1546,7 @@ Result:
 └──────────────────────────────────┘
 ```
 
-Note that `NULL` values are ignored. 
+Note that `NULL` values are ignored.
 
 Query:
 
@@ -1520,10 +1592,9 @@ Result:
 └────────┴─────────────┴────────────────┘
 ```
 
-**See Also** 
+**See Also**
-
 -   [arrayReduce](../../sql-reference/functions/array-functions.md#arrayreduce)
--   [initializeAggregation](../../sql-reference/aggregate-functions/reference/initializeAggregation.md)
+-   [initializeAggregation](#initializeaggregation)
 
 ## runningAccumulate {#runningaccumulate}
 

docs/ru/sql-reference/aggregate-functions/reference/initializeAggregation.md

@@ -1,40 +0,0 @@
----
-toc_priority: 150
----
-
-## initializeAggregation {#initializeaggregation}
-
-Инициализирует агрегацию для введеных строчек. Предназначена для функций с суффиксом `State`.
-Поможет вам проводить тесты или работать со столбцами типов: `AggregateFunction` и `AggregationgMergeTree`.
-
-**Синтаксис**
-
-``` sql
-initializeAggregation (aggregate_function, column_1, column_2)
-```
-
-**Аргументы**
-
--   `aggregate_function` — название функции агрегации, состояние которой нужно создать. [String](../../../sql-reference/data-types/string.md#string).
--   `column_n` — столбец, который передается в функцию агрегации как аргумент. [String](../../../sql-reference/data-types/string.md#string).
-
-**Возвращаемое значение**
-
-Возвращает результат агрегации введенной информации. Тип возвращаемого значения такой же, как и для функции, которая становится первым аргументом для `initializeAgregation`.
-
-Пример:
-
-Возвращаемый тип функций с суффиксом `State`  — `AggregateFunction`.
-
-**Пример**
-
-Запрос:
-
-```sql
-SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM system.numbers LIMIT 10000);
-```
-Результат:
-
-┌─uniqMerge(state)─┐
-│                3 │
-└──────────────────┘

docs/ru/sql-reference/functions/other-functions.md

@@ -13,7 +13,7 @@ toc_title: "Прочие функции"
 
 Возвращает именованное значение из секции [macros](../../operations/server-configuration-parameters/settings.md#macros) конфигурации сервера.
 
-**Синтаксис** 
+**Синтаксис**
 
 ```sql
 getMacro(name)
@@ -854,8 +854,8 @@ WHERE diff != 1
 ## runningConcurrency {#runningconcurrency}
 
 Подсчитывает количество одновременно идущих событий.
-У каждого события есть время начала и время окончания. Считается, что время начала включено в событие, а время окончания исключено из него. Столбцы со временем начала и окончания событий должны иметь одинаковый тип данных. 
+У каждого события есть время начала и время окончания. Считается, что время начала включено в событие, а время окончания исключено из него. Столбцы со временем начала и окончания событий должны иметь одинаковый тип данных.
-Функция подсчитывает количество событий, происходящих одновременно на момент начала каждого из событий в выборке. 
+Функция подсчитывает количество событий, происходящих одновременно на момент начала каждого из событий в выборке.
 
 !!! warning "Предупреждение"
     События должны быть отсортированы по возрастанию времени начала. Если это требование нарушено, то функция вызывает исключение.
@@ -1371,11 +1371,84 @@ SELECT formatReadableSize(filesystemCapacity()) AS "Capacity", toTypeName(filesy
 └───────────┴────────┘
 ```
 
+## initializeAggregation {#initializeaggregation}
+
+Вычисляет результат агрегатной функции для каждой строки. Предназначена для инициализации агрегатных функций с комбинатором [-State](../../sql-reference/aggregate-functions/combinators.md#state). Может быть полезна для создания состояний агрегатных функций для последующей их вставки в столбцы типа [AggregateFunction](../../sql-reference/data-types/aggregatefunction.md#data-type-aggregatefunction) или использования в качестве значений по-умолчанию.
+
+**Синтаксис**
+
+``` sql
+initializeAggregation (aggregate_function, arg1, arg2, ..., argN)
+```
+
+**Аргументы**
+
+-   `aggregate_function` — название агрегатной функции, состояние которой нужно создать. [String](../../sql-reference/data-types/string.md#string).
+-   `arg` — аргументы, которые передаются в агрегатную функцию.
+
+**Возвращаемое значение**
+
+- В каждой строке результат агрегатной функции, примененной к аргументам из этой строки.
+
+Тип возвращаемого значения такой же, как и у функции, переданной первым аргументом.
+
+
+**Пример**
+
+Запрос:
+
+```sql
+SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
+```
+Результат:
+
+```text
+┌─uniqMerge(state)─┐
+│                3 │
+└──────────────────┘
+```
+
+Запрос:
+
+```sql
+SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
+```
+Результат:
+
+```text
+┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
+│                          0 │ AggregateFunction(sum, UInt8) │
+│                          1 │ AggregateFunction(sum, UInt8) │
+│                          2 │ AggregateFunction(sum, UInt8) │
+│                          0 │ AggregateFunction(sum, UInt8) │
+│                          1 │ AggregateFunction(sum, UInt8) │
+└────────────────────────────┴───────────────────────────────┘
+```
+
+Пример с движком таблиц `AggregatingMergeTree` и столбцом типа `AggregateFunction`:
+
+```sql
+CREATE TABLE metrics
+(
+    key UInt64,
+    value AggregateFunction(sum, UInt64) DEFAULT initializeAggregation('sumState', toUInt64(0))
+)
+ENGINE = AggregatingMergeTree
+ORDER BY key
+```
+
+```sql
+INSERT INTO metrics VALUES (0, initializeAggregation('sumState', toUInt64(42)))
+```
+
+**Смотрите также**
+-   [arrayReduce](../../sql-reference/functions/array-functions.md#arrayreduce)
+
 ## finalizeAggregation {#function-finalizeaggregation}
 
 Принимает состояние агрегатной функции. Возвращает результат агрегирования (или конечное состояние при использовании комбинатора [-State](../../sql-reference/aggregate-functions/combinators.md#state)).
 
-**Синтаксис** 
+**Синтаксис**
 
 ``` sql
 finalizeAggregation(state)
@@ -1421,7 +1494,7 @@ SELECT finalizeAggregation(( SELECT sumState(number) FROM numbers(10)));
 └──────────────────────────────────┘
 ```
 
-Обратите внимание, что значения `NULL` игнорируются. 
+Обратите внимание, что значения `NULL` игнорируются.
 
 Запрос:
 
@@ -1470,7 +1543,7 @@ FROM numbers(10);
 **Смотрите также**
 
 -   [arrayReduce](../../sql-reference/functions/array-functions.md#arrayreduce)
--   [initializeAggregation](../../sql-reference/aggregate-functions/reference/initializeAggregation.md)
+-   [initializeAggregation](#initializeaggregation)
 
 ## runningAccumulate {#runningaccumulate}
 
@@ -1537,13 +1610,13 @@ SELECT k, runningAccumulate(sum_k) AS res FROM (SELECT number as k, sumState(k)
 Запрос:
 
 ```sql
-SELECT 
+SELECT
     grouping,
     item,
     runningAccumulate(state, grouping) AS res
-FROM 
+FROM
 (
-    SELECT 
+    SELECT
         toInt8(number / 4) AS grouping,
         number AS item,
         sumState(number) AS state
@@ -1732,7 +1805,7 @@ SELECT number, randomPrintableASCII(30) as str, length(str) FROM system.numbers
 randomString(length)
 ```
 
-**Аргументы** 
+**Аргументы**
 
 -   `length` — длина строки. Положительное целое число.
 
@@ -1831,13 +1904,13 @@ randomStringUTF8(length)
 
 Запрос:
 
-```sql 
+```sql
 SELECT randomStringUTF8(13)
 ```
 
 Результат:
 
-```text 
+```text
 ┌─randomStringUTF8(13)─┐
 │ 𘤗𙉝д兠庇󡅴󱱎󦐪􂕌𔊹𓰛   │
 └──────────────────────┘
@@ -1848,13 +1921,13 @@ SELECT randomStringUTF8(13)
 
 Возвращает текущее значение [пользовательской настройки](../../operations/settings/index.md#custom_settings).
 
-**Синтаксис** 
+**Синтаксис**
 
 ```sql
 getSetting('custom_setting')
 ```
 
-**Параметр** 
+**Параметр**
 
 -   `custom_setting` — название настройки. [String](../../sql-reference/data-types/string.md).
 
@@ -1866,7 +1939,7 @@ getSetting('custom_setting')
 
 ```sql
 SET custom_a = 123;
-SELECT getSetting('custom_a');    
+SELECT getSetting('custom_a');
 ```
 
 **Результат**
@@ -1875,7 +1948,7 @@ SELECT getSetting('custom_a');
 123
 ```
 
-**См. также** 
+**См. также**
 
 -   [Пользовательские настройки](../../operations/settings/index.md#custom_settings)
 
@@ -1889,10 +1962,10 @@ SELECT getSetting('custom_a');
 isDecimalOverflow(d, [p])
 ```
 
-**Аргументы** 
+**Аргументы**
 
 -   `d` — число. [Decimal](../../sql-reference/data-types/decimal.md).
--   `p` — точность. Необязательный параметр. Если опущен, используется исходная точность первого аргумента. Использование этого параметра может быть полезно для извлечения данных в другую СУБД или файл. [UInt8](../../sql-reference/data-types/int-uint.md#uint-ranges). 
+-   `p` — точность. Необязательный параметр. Если опущен, используется исходная точность первого аргумента. Использование этого параметра может быть полезно для извлечения данных в другую СУБД или файл. [UInt8](../../sql-reference/data-types/int-uint.md#uint-ranges).
 
 **Возвращаемое значение**
 
@@ -1926,7 +1999,7 @@ SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
 countDigits(x)
 ```
 
-**Аргументы** 
+**Аргументы**
 
 -   `x` — [целое](../../sql-reference/data-types/int-uint.md#uint8-uint16-uint32-uint64-int8-int16-int32-int64) или [дробное](../../sql-reference/data-types/decimal.md) число.