Функции для работы с nullable значениями

assumeNotNull

Введена в: v1.1

Возвращает соответствующее непустое значение для значения типа Nullable. Если исходное значение равно NULL, может быть возвращен произвольный результат.

Смотрите также: функции ifNull и coalesce.

Синтаксис

assumeNotNull(x)

Аргументы

• x — Исходное значение любого nullable типа. Nullable(T)

Возвращаемое значение

Возвращает непустое значение, если исходное значение не было NULL, в противном случае — произвольное значение, если входное значение NULL. Any

Примеры

Пример использования

CREATE TABLE t_null (x Int8, y Nullable(Int8))
ENGINE=MergeTree()
ORDER BY x;

INSERT INTO t_null VALUES (1, NULL), (2, 3);

SELECT assumeNotNull(y) FROM table;
SELECT toTypeName(assumeNotNull(y)) FROM t_null;

┌─assumeNotNull(y)─┐
│                0 │
│                3 │
└──────────────────┘
┌─toTypeName(assumeNotNull(y))─┐
│ Int8                         │
│ Int8                         │
└──────────────────────────────┘

coalesce

Введена в: v1.1

Возвращает самый левый не-NULL аргумент.

Синтаксис

coalesce(x[, y, ...])

Аргументы

• x[, y, ...] — Любое количество параметров некорректного типа. Все параметры должны быть совместимы по типу. Any

Возвращаемое значение

Возвращает первый не-NULL аргумент, иначе NULL, если все аргументы равны NULL. Any или NULL

Примеры

Пример использования

-- Consider a list of contacts that may specify multiple ways to contact a customer.

CREATE TABLE aBook
(
    name String,
    mail Nullable(String),
    phone Nullable(String),
    telegram Nullable(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO aBook VALUES ('client 1', NULL, '123-45-67', 123), ('client 2', NULL, NULL, NULL);

-- The mail and phone fields are of type String, but the telegram field is UInt32 so it needs to be converted to String.

-- Get the first available contact method for the customer from the contact list

SELECT name, coalesce(mail, phone, CAST(telegram,'Nullable(String)')) FROM aBook;

┌─name─────┬─coalesce(mail, phone, CAST(telegram, 'Nullable(String)'))─┐
│ client 1 │ 123-45-67                                                 │
│ client 2 │ ᴺᵁᴸᴸ                                                      │
└──────────┴───────────────────────────────────────────────────────────┘

firstNonDefault

Введена в: v25.9

Возвращает первое не-умолчательное значение из набора аргументов

Синтаксис

Аргументы

• arg1 — Первый аргумент для проверки - arg2 — Второй аргумент для проверки - ... — Дополнительные аргументы для проверки

Возвращаемое значение

Тип результата — супертотип всех аргументов

Примеры

целые числа

SELECT firstNonDefault(0, 1, 2)

1

строки

SELECT firstNonDefault('', 'hello', 'world')

'hello'

нулевые значения

SELECT firstNonDefault(NULL, 0 :: UInt8, 1 :: UInt8)

1

nullable ноль

SELECT firstNonDefault(NULL, 0 :: Nullable(UInt8), 1 :: Nullable(UInt8))

0

ifNull

Введена в: v1.1

Возвращает альтернативное значение, если первый аргумент равен NULL.

Синтаксис

ifNull(x, alt)

Аргументы

• x — Значение для проверки на NULL. Any
• alt — Значение, которое функция возвращает, если x равно NULL. Any

Возвращаемое значение

Возвращает значение x, если оно не равно NULL, в противном случае alt. Any

Примеры

Пример использования

SELECT ifNull('a', 'b'), ifNull(NULL, 'b');

┌─ifNull('a', 'b')─┬─ifNull(NULL, 'b')─┐
│ a                │ b                 │
└──────────────────┴───────────────────┘

isNotDistinctFrom

Введена в: v23.8

Выполняет безопасное сравнение для JOIN ключей. Эта функция будет считать два NULL значения одинаковыми и вернет true, что отличается от обычного поведения equals, где сравнение двух NULL значений вернет NULL.

к сведению

Эта функция является внутренней и используется при реализации JOIN ON. Пожалуйста, не используйте её вручную в запросах.

Для полного примера смотрите: NULL значения в JOIN ключах.

Синтаксис

isNotDistinctFrom(x, y)

Аргументы

• x — Первый JOIN ключ для сравнения. Any
• y — Второй JOIN ключ для сравнения. Any

Возвращаемое значение

Возвращает true, когда x и y оба равны NULL, иначе false. Bool

Примеры

isNotNull

Введена в: v1.1

Проверяет, не равно ли аргумент NULL.

Смотрите также: оператор IS NOT NULL.

Синтаксис

isNotNull(x)

Аргументы

• x — Значение некорректного типа. Any

Возвращаемое значение

Возвращает 1, если x не равно NULL, в противном случае 0. UInt8

Примеры

Пример использования

CREATE TABLE t_null
(
  x Int32,
  y Nullable(Int32)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO t_null VALUES (1, NULL), (2, 3);

SELECT x FROM t_null WHERE isNotNull(y);

┌─x─┐
│ 2 │
└───┘

isNull

Введена в: v1.1

Проверяет, равно ли аргумент NULL.

Смотрите также: оператор IS NULL.

Синтаксис

isNull(x)

Аргументы

• x — Значение некорректного типа. Any

Возвращаемое значение

Возвращает 1, если x равно NULL, в противном случае 0. UInt8

Примеры

Пример использования

CREATE TABLE t_null
(
  x Int32,
  y Nullable(Int32)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO t_null VALUES (1, NULL), (2, 3);

SELECT x FROM t_null WHERE isNull(y);

┌─x─┐
│ 1 │
└───┘

isNullable

Введена в: v22.7

Проверяет, является ли тип данных аргумента Nullable (т.е. позволяет ли он NULL значения).

Синтаксис

isNullable(x)

Аргументы

• x — Значение любого типа данных. Any

Возвращаемое значение

Возвращает 1, если x является типом данных Nullable, в противном случае 0. UInt8

Примеры

Пример использования

CREATE TABLE tab (
    ordinary_col UInt32,
    nullable_col Nullable(UInt32)
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO tab (ordinary_col, nullable_col) VALUES (1,1), (2, 2), (3,3);
SELECT isNullable(ordinary_col), isNullable(nullable_col) FROM tab;

┌───isNullable(ordinary_col)──┬───isNullable(nullable_col)──┐
│                           0 │                           1 │
│                           0 │                           1 │
│                           0 │                           1 │
└─────────────────────────────┴─────────────────────────────┘

isZeroOrNull

Введена в: v20.3

Проверяет, является ли аргумент либо нулем (0), либо NULL.

Синтаксис

isZeroOrNull(x)

Аргументы

• x — Числовое значение. UInt

Возвращаемое значение

Возвращает 1, если x равно NULL или равно нулю, в противном случае 0. UInt8/16/32/64 или Float32/Float64

Примеры

Пример использования

CREATE TABLE t_null
(
  x Int32,
  y Nullable(Int32)
)
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO t_null VALUES (1, NULL), (2, 0), (3, 3);

SELECT x FROM t_null WHERE isZeroOrNull(y);

┌─x─┐
│ 1 │
│ 2 │
└───┘

nullIf

Введена в: v1.1

Возвращает NULL, если оба аргумента равны.

Синтаксис

nullIf(x, y)

Аргументы

• x — Первое значение. Any
• y — Второе значение. Any

Возвращаемое значение

Возвращает NULL, если оба аргумента равны, в противном случае возвращает первое значение. NULL или Nullable(x)

Примеры

Пример использования

SELECT nullIf(1, 1), nullIf(1, 2);

┌─nullIf(1, 1)─┬─nullIf(1, 2)─┐
│         ᴺᵁᴸᴸ │            1 │
└──────────────┴──────────────┘

toNullable

Введена в: v1.1

Преобразует указанный тип аргумента в Nullable.

Синтаксис

toNullable(x)

Аргументы

• x — Значение любого некорректного типа. Any

Возвращаемое значение

Возвращает входное значение, но типа Nullable. Nullable(Any)

Примеры

Пример использования

SELECT toTypeName(10), toTypeName(toNullable(10));

┌─toTypeName(10)─┬─toTypeName(toNullable(10))─┐
│ UInt8          │ Nullable(UInt8)            │
└────────────────┴────────────────────────────┘