diff --git a/docs/en/sql_reference/aggregate_functions/combinators.md b/docs/en/sql_reference/aggregate_functions/combinators.md index 46a680a7978e75b73b59ec8eb2ef28c24349777b..86ecbe4494607e2629833d7998a27947135c6bdf 100644 --- a/docs/en/sql_reference/aggregate_functions/combinators.md +++ b/docs/en/sql_reference/aggregate_functions/combinators.md @@ -51,33 +51,108 @@ Converts an aggregate function for tables into an aggregate function for arrays ## -OrDefault {#agg-functions-combinator-ordefault} -Fills the default value of the aggregate function’s return type if there is nothing to aggregate. +Changes behaviour of an aggregate function. + +If an aggregate function doesn't have input values, with this combinator it returns the default value for its return data type. Applies to the aggregate functions that can take empty input data. +`-OrDefault` can be combined with other combinators. + +**Syntax** + +``` sql +OrDefault(x) +``` + +**Parameters** + +- `x` — Aggregate function parameters. + +**Returned values** + +Returns the default value of an aggregate function’s return type if there is nothing to aggregate. + +Type depends on the aggregate function used. + +**Example** + +Query: ``` sql SELECT avg(number), avgOrDefault(number) FROM numbers(0) ``` +Result: + ``` text ┌─avg(number)─┬─avgOrDefault(number)─┐ │ nan │ 0 │ └─────────────┴──────────────────────┘ ``` +Also `-OrDefault` can be used with a few combinators. It is useful when the aggregate function does not accept the empty input. + +Query: + +``` sql +SELECT avgOrDefaultIf(x, x > 10) +FROM +( + SELECT toDecimal32(1.23, 2) AS x +) +``` + +Result: + +``` text +┌─avgOrDefaultIf(x, greater(x, 10))─┐ +│ 0.00 │ +└───────────────────────────────────┘ +``` + + ## -OrNull {#agg-functions-combinator-ornull} -Fills `null` if there is nothing to aggregate. The return column will be nullable. +Changes behaviour of an aggregate function. + +This combinator replaces returned value with nullable one, if the aggregate function does not have values to calculate. Works with different aggregate functions. +`-OrNull` can be combined with other combinators. + +**Syntax** + +``` sql +OrNull(x) +``` + +**Parameters** + +- `x` — Aggregate function parameters. + +**Returned values** + +Returns the `Null` value of an aggregate function’s return type if there is nothing to aggregate. + +Type: [Nullable](../data_types/nullable.md). + +**Example** + +Add `-orNull` to the end of aggregate function. + +Query: ``` sql -SELECT avg(number), avgOrNull(number) FROM numbers(0) +SELECT sumOrNull(number) FROM numbers(10) WHERE number > 10 ``` +Result: + ``` text -┌─avg(number)─┬─avgOrNull(number)─┐ -│ nan │ ᴺᵁᴸᴸ │ -└─────────────┴───────────────────┘ +┌─sumOrNull(number)─┐ +│ ᴺᵁᴸᴸ │ +└───────────────────┘ ``` --OrDefault and -OrNull can be combined with other combinators. It is useful when the aggregate function does not accept the empty input. +Also `-OrNull` can be used with a few combinators. It is useful when the aggregate function does not accept the empty input. + +Query: ``` sql SELECT avgOrNullIf(x, x > 10) @@ -87,6 +162,8 @@ FROM ) ``` +Result: + ``` text ┌─avgOrNullIf(x, greater(x, 10))─┐ │ ᴺᵁᴸᴸ │ diff --git a/docs/ru/sql_reference/aggregate_functions/combinators.md b/docs/ru/sql_reference/aggregate_functions/combinators.md index e4295f0d76e2cd6a4aa317644eb75e29e0aba9b9..35ee9d5bb5603ea842b9ef462c115bdffd08fa7d 100644 --- a/docs/ru/sql_reference/aggregate_functions/combinators.md +++ b/docs/ru/sql_reference/aggregate_functions/combinators.md @@ -45,6 +45,127 @@ Преобразует агрегатную функцию для таблиц в агрегатную функцию для массивов, которая применяет агрегирование для соответствующих элементов массивов и возвращает массив результатов. Например, `sumForEach` для массивов `[1, 2]`, `[3, 4, 5]` и `[6, 7]` даст результат `[10, 13, 5]`, сложив соответственные элементы массивов. +## -OrDefault {#agg-functions-combinator-ordefault} + +Изменяет поведение агрегатной функции. + +Если на вход агрегатной функции передан пустой набор данных, то с помощью комбинатора `-OrDefault` функция возвращает значение по умолчанию для соответствующего типа данных. Комбинатор применяется к агрегатным функциям, которые могут принимать пустые входные данные. +`-OrDefault` можно использовать с другими комбинаторами. + +**Синтаксис** + +``` sql +OrDefault(x) +``` + +**Параметры** + +- `x` — Параметры агрегатной функции. + +**Возращаемые зачения** + +Возвращает значение по умолчанию для соответствующего типа агрегатной функции, если агрегировать нечего. + +Тип данных зависит от используемой агрегатной функции. + +**Пример** + +Запрос: + +``` sql +SELECT avg(number), avgOrDefault(number) FROM numbers(0) +``` + +Результат: + +``` text +┌─avg(number)─┬─avgOrDefault(number)─┐ +│ nan │ 0 │ +└─────────────┴──────────────────────┘ +``` + +Также `-OrDefault` может использоваться с другими комбинаторами. Это полезно, когда агрегатная функция не принимает пустые входные данные. + +Запрос: + +``` sql +SELECT avgOrDefaultIf(x, x > 10) +FROM +( + SELECT toDecimal32(1.23, 2) AS x +) +``` + +Результат: + +``` text +┌─avgOrDefaultIf(x, greater(x, 10))─┐ +│ 0.00 │ +└───────────────────────────────────┘ +``` + + +## -OrNull {#agg-functions-combinator-ornull} + +Изменяет поведение агрегатной функции. + +Этот комбинатор заменяет возвращаемое значение на `Null`, если на вход агрегатной функции передан пустой набор данных. Комбинатор работает с различными агрегатными функциями. +`-OrNull` может использоваться с другими комбинаторами. + +**Синтаксис** + +``` sql +OrNull(x) +``` + +**Параметры** + +- `x` — Параметры агрегатной функции. + +**Возвращаемые значения** + +Возвращает значение `Null` для соответствующего типа агрегатной функции, если агрегировать нечего. + +Тип: [Nullable](../data_types/nullable.md). + +**Пример** + +Добавьте `-orNull` в конец агрегатной функции. + +Запрос: + +``` sql +SELECT sumOrNull(number) FROM numbers(10) WHERE number > 10 +``` + +Результат: + +``` text +┌─sumOrNull(number)─┐ +│ ᴺᵁᴸᴸ │ +└───────────────────┘ +``` + +Также `-OrNull` может использоваться с другими комбинаторами. Это полезно, когда агрегатная функция не принимает пустые входные данные. + +Запрос: + +``` sql +SELECT avgOrNullIf(x, x > 10) +FROM +( + SELECT toDecimal32(1.23, 2) AS x +) +``` + +Результат: + +``` text +┌─avgOrNullIf(x, greater(x, 10))─┐ +│ ᴺᵁᴸᴸ │ +└────────────────────────────────┘ +``` + ## -Resample {#agg-functions-combinator-resample} Позволяет поделить данные на группы, а затем по-отдельности агрегирует данные для этих групп. Группы образуются разбиением значений одного из столбцов на интервалы.