Functions for Nullable arguments.

docs/mkdocs_ru.yml

@@ -208,6 +208,7 @@ pages:
   - 'Функции для реализации оператора IN.': 'functions/in_functions.md'
   - 'Функция arrayJoin': 'functions/array_join.md'
   - 'Функции для работы с географическими координатами': 'functions/geo.md'
+  - 'Функции для работы с Nullable-агрументами': 'functions/functions_for_nulls.md'
 
 - 'Агрегатные функции':
   - 'Введение': 'agg_functions/index.md'

docs/ru/data_types/array.md

@@ -2,5 +2,80 @@
 
 # Array(T)
 
-Массив из элементов типа T. Типом T может быть любой тип, в том числе, массив.
-Многомерные массивы не рекомендуется использовать, так как их поддержка довольно слабая (например, многомерные массивы нельзя сохранить в таблицы с движком семейства MergeTree).
+Массив из элементов типа `T`.
+
+`T` может любым, в том числе, массивом. Используйте многомерные массивы с осторожностью. ClickHouse поддерживает многомерные массивы ограниченно, например, их нельзя хранить в таблицах семейства `MergeTree`.
+
+## Создание массива
+
+Массив можно создать с помощью функции:
+
+```
+array(T)
+```
+
+Также можно использовать квадратные скобки
+
+```
+[]
+```
+
+Пример создания массива:
+```
+:) SELECT array(1, 2) AS x, toTypeName(x)
+
+SELECT
+    [1, 2] AS x,
+    toTypeName(x)
+
+┌─x─────┬─toTypeName(array(1, 2))─┐
+│ [1,2] │ Array(UInt8)            │
+└───────┴─────────────────────────┘
+
+1 rows in set. Elapsed: 0.002 sec.
+
+:) SELECT [1, 2] AS x, toTypeName(x)
+
+SELECT
+    [1, 2] AS x,
+    toTypeName(x)
+
+┌─x─────┬─toTypeName([1, 2])─┐
+│ [1,2] │ Array(UInt8)       │
+└───────┴────────────────────┘
+
+1 rows in set. Elapsed: 0.002 sec.
+```
+
+## Особенности работы с типами данных
+
+При создании массива "на лету" ClickHouse автоматически определяет тип аргументов как тип, в котором можно хранить все перечисленные аргументы. Если среди аргументов есть [NULL](../query_language/syntax.md#null-literal), то тип элементов массива — [Nullable](nullable.md#data_type-nullable).
+
+Примеры автоматического определения типа данных:
+
+```
+:) SELECT array(1, 2, NULL) AS x, toTypeName(x)
+
+SELECT
+    [1, 2, NULL] AS x,
+    toTypeName(x)
+
+┌─x──────────┬─toTypeName(array(1, 2, NULL))─┐
+│ [1,2,NULL] │ Array(Nullable(UInt8))        │
+└────────────┴───────────────────────────────┘
+
+1 rows in set. Elapsed: 0.002 sec.
+```
+
+Если попытаться создать массив из несовместимых типов данных, то ClickHouse выбросит исключение:
+
+```
+:) SELECT array(1, 'a')
+
+SELECT [1, 'a']
+
+Received exception from server (version 1.1.54388):
+Code: 386. DB::Exception: Received from localhost:9000, 127.0.0.1. DB::Exception: There is no supertype for types UInt8, String because some of them are String/FixedString and some of them are not.
+
+0 rows in set. Elapsed: 0.246 sec.
+```

docs/ru/data_types/special_data_types/nothing.md

@@ -4,7 +4,7 @@
 
 Этот тип данных предназначен только для того, чтобы представлять [NULL](../../query_language/syntax.md#null-literal).
 
-Невозможно создать значение типа `Nothing`, поэтому он используется там, где значение не подразумевается. Например, `NULL` записывается как `Nullable(Nothing)` ([Nullable](../../data_types/nullable.md#data_type-nullable) — это тип данных, позволяющий хранить `NULL` в таблицах). Также тип Nothing используется для обозначения пустых массивов:
+Невозможно создать значение типа `Nothing`, поэтому он используется там, где значение не подразумевается. Например, `NULL` записывается как `Nullable(Nothing)` ([Nullable](../../data_types/nullable.md#data_type-nullable) — это тип данных, позволяющий хранить `NULL` в таблицах). Также тип `Nothing` используется для обозначения пустых массивов:
 
 ```bash
 :) SELECT toTypeName(Array())

docs/ru/functions/functions_for_nulls.md

+# Функции для работы с Nullable-агрументами
+
+## isNull
+
+Проверяет является ли аргумент [NULL](../query_language/syntax.md#null-literal).
+
+```
+isNull(x)
+```
+
+**Параметры**
+
+- `x` — значение с не составным типом данных.
+
+**Возвращаемое значение**
+
+- `1`, если `x` — `NULL`.
+- `0`, если `x` — не `NULL`.
+
+**Пример**
+
+Входная таблица
+
+```
+┌─x─┬────y─┐
+│ 1 │ ᴺᵁᴸᴸ │
+│ 2 │    3 │
+└───┴──────┘
+```
+
+Запрос
+
+```
+:) SELECT x FROM t_null WHERE isNull(y)
+
+SELECT x
+FROM t_null
+WHERE isNull(y)
+
+┌─x─┐
+│ 1 │
+└───┘
+
+1 rows in set. Elapsed: 0.010 sec.
+```
+
+## isNotNull
+
+Проверяет не является ли аргумент [NULL](../query_language/syntax.md#null-literal).
+
+```
+isNotNull(x)
+```
+
+**Параметры**
+
+- `x` — значение с не составным типом данных.
+
+**Возвращаемое значение**
+
+- `0`, если `x` — `NULL`.
+- `1`, если `x` — не `NULL`.
+
+**Пример**
+
+Входная таблица
+
+```
+┌─x─┬────y─┐
+│ 1 │ ᴺᵁᴸᴸ │
+│ 2 │    3 │
+└───┴──────┘
+```
+
+Запрос
+
+```
+:) SELECT x FROM t_null WHERE isNotNull(y)
+
+SELECT x
+FROM t_null
+WHERE isNotNull(y)
+
+┌─x─┐
+│ 2 │
+└───┘
+
+1 rows in set. Elapsed: 0.010 sec.
+```
+
+## coalesce
+
+Последовательно проверяет являются ли переданные аргументы `NULL` и возвращает первый не `NULL`.
+
+```
+coalesce(x,...)
+```
+**Параметры**
+
+- Произвольное количество параметров не составного типа. Все параметры должны быть совместимы по типу данных.
+
+**Возвращаемые значения**
+
+- Первый не `NULL` аргумент.
+- `NULL`, если все аргументы — `NULL`.
+
+**Пример**
+
+Предположим, что у нас адресная книга, в которой может быть указано несколько способов связи с клиентом.
+
+```
+┌─name─────┬─mail─┬─phone─────┬──icq─┐
+│ client 1 │ ᴺᵁᴸᴸ │ 123-45-67 │  123 │
+│ client 2 │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ      │ ᴺᵁᴸᴸ │
+└──────────┴──────┴───────────┴──────┘
+```
+
+Поля `mail` и `phone` имеют тип String, а поле `icq` — `UInt32`, его необходимо будет преобразовать в `String`.
+
+Получим из адресной книги первый доступный способ связаться с клиентом:
+
+```
+:) SELECT coalesce(mail, phone, CAST(icq,'Nullable(String)')) FROM aBook
+
+SELECT coalesce(mail, phone, CAST(icq, 'Nullable(String)'))
+FROM aBook
+
+┌─name─────┬─coalesce(mail, phone, CAST(icq, 'Nullable(String)'))─┐
+│ client 1 │ 123-45-67                                            │
+│ client 2 │ ᴺᵁᴸᴸ                                                 │
+└──────────┴──────────────────────────────────────────────────────┘
+
+2 rows in set. Elapsed: 0.006 sec.
+```
+
+## ifNull
+
+Возвращает альтернативное значение, если основной аргумент — `NULL`.
+
+```
+ifNull(x,alt)
+```
+
+**Параметры**
+
+- `x` — значение для проверки на `NULL`,
+- `alt` — значение, которое функция вернёт, если `x` — `NULL`.
+
+**Возвращаемые значения**
+
+- Значение `x`, если `x` — не `NULL`.
+- Значение `alt`, если `x` — `NULL`.
+
+**Пример**
+
+```
+SELECT ifNull('a', 'b')
+
+┌─ifNull('a', 'b')─┐
+│ a                │
+└──────────────────┘
+```
+```
+SELECT ifNull(NULL, 'b')
+
+┌─ifNull(NULL, 'b')─┐
+│ b                 │
+└───────────────────┘
+```
+
+## nullIf
+
+Возвращает `NULL`, если аргументы равны.
+
+```
+nullIf(x, y)
+```
+
+**Параметры**
+
+`x`, `y` — значения для сравнивания. Они должны быть совместимых типов, иначе ClickHouse сгенерирует исключение.
+
+**Возвращаемые значения**
+
+- `NULL`, если аргументы равны.
+- Значение `x`, если аргументы не равны.
+
+**Пример**
+
+```
+SELECT nullIf(1, 1)
+
+┌─nullIf(1, 1)─┐
+│         ᴺᵁᴸᴸ │
+└──────────────┘
+```
+```
+SELECT nullIf(1, 2)
+
+┌─nullIf(1, 2)─┐
+│            1 │
+└──────────────┘
+```
+
+## assumeNotNull
+
+Приводит значение типа [Nullable](../data_types/nullable.md#data_type-nullable) к не `Nullable`, если значение не `NULL`.
+
+```
+assumeNotNull(x)
+```
+
+**Параметры**
+
+- `x` — значение.
+
+**Возвращаемые значения**
+
+- То же значение с не `Nullable` типом, если значение не `NULL`.
+- Значение по умолчанию для не `Nullable` типа, если исходное значение — `NULL`.
+
+**Пример**
+
+Рассмотрим таблицу `t_null`.
+
+```
+SHOW CREATE TABLE t_null
+
+┌─statement─────────────────────────────────────────────────────────────────┐
+│ CREATE TABLE default.t_null ( x Int8,  y Nullable(Int8)) ENGINE = TinyLog │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+```
+┌─x─┬────y─┐
+│ 1 │ ᴺᵁᴸᴸ │
+│ 2 │    3 │
+└───┴──────┘
+```
+
+Применим функцию `assumeNotNull` к столбцу `y`.
+
+```
+SELECT assumeNotNull(y) FROM t_null
+
+┌─assumeNotNull(y)─┐
+│                0 │
+│                3 │
+└──────────────────┘
+```
+```
+SELECT toTypeName(assumeNotNull(y)) FROM t_null
+
+┌─toTypeName(assumeNotNull(y))─┐
+│ Int8                         │
+│ Int8                         │
+└──────────────────────────────┘
+```
+
+## toNullable
+
+Преобразует тип аргумента к `Nullable`.
+
+```
+toNullable(x)
+```
+
+**Параметры**
+
+- `x` — значение произвольного не составного типа.
+
+**Возвращаемое значение**
+
+- Входное значение с типом не `Nullable`.
+
+**Пример**
+
+```
+SELECT toTypeName(10)
+
+┌─toTypeName(10)─┐
+│ UInt8          │
+└────────────────┘
+
+SELECT toTypeName(toNullable(10))
+
+┌─toTypeName(toNullable(10))─┐
+│ Nullable(UInt8)            │
+└────────────────────────────┘
+```

docs/ru/functions/index.md

@@ -27,6 +27,13 @@
 
 Функции могут быть по-разному реализованы для константных и не константных аргументов (выполняется разный код). Но результат работы для константы и полноценного столбца, содержащего только одно такое же значение, должен совпадать.
 
+## Обработка NULL
+
+Функции имеют следующие виды поведения:
+
+- Если хотя бы один из аргументов функции — `NULL`, то результат функции тоже `NULL`.
+- Специальное поведение, указанное в описании каждой функции отдельно. В исходном коде ClickHouse такие функции можно определить по свойству `UseDefaultImplementationForNulls=false`.
+
 ## Неизменяемость
 
 Функции не могут поменять значения своих аргументов - любые изменения возвращаются в качестве результата. Соответственно, от порядка записи функций в запросе, результат вычислений отдельных функций не зависит.

docs/ru/table_engines/mysql.md

@@ -13,3 +13,5 @@ MySQL('host:port', 'database', 'table', 'user', 'password');
 На данный момент простые условия `WHERE`, такие как `=, !=, >, >=, <, <=` будут выполняться на стороне сервера MySQL.
 
 Остальные условия и ограничение выборки `LIMIT` будут выполнены в ClickHouse только после выполнения запроса к MySQL.
+
+Движок `MySQL` не поддерживает тип данных [Nullable](../data_types/nullable.md#data_type-nullable), поэтому при чтении данных из таблиц MySQL `NULL` преобразуются в значения по умолчанию для заданного типа столбца, обычно это `0` или пустая строка.