diff --git a/docs/en/sql-reference/aggregate-functions/reference/initializeAggregation.md b/docs/en/sql-reference/aggregate-functions/reference/initializeAggregation.md deleted file mode 100644 index c8fb535089b..00000000000 --- a/docs/en/sql-reference/aggregate-functions/reference/initializeAggregation.md +++ /dev/null @@ -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 │ -└──────────────────┘ diff --git a/docs/en/sql-reference/functions/other-functions.md b/docs/en/sql-reference/functions/other-functions.md index 8163650efab..30e2e427158 100644 --- a/docs/en/sql-reference/functions/other-functions.md +++ b/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} diff --git a/docs/ru/sql-reference/aggregate-functions/reference/initializeAggregation.md b/docs/ru/sql-reference/aggregate-functions/reference/initializeAggregation.md deleted file mode 100644 index 3565115d8de..00000000000 --- a/docs/ru/sql-reference/aggregate-functions/reference/initializeAggregation.md +++ /dev/null @@ -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 │ -└──────────────────┘ diff --git a/docs/ru/sql-reference/functions/other-functions.md b/docs/ru/sql-reference/functions/other-functions.md index 84bbc6af968..a07bd19faa1 100644 --- a/docs/ru/sql-reference/functions/other-functions.md +++ b/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) число.