ClickHouse/docs/en/sql-reference/functions/functions-for-nulls.md

toc_priority	toc_title
63	Nullable

Functions for Working with Nullable Values

isNull

Checks whether the argument is NULL.

isNull(x)

Alias: ISNULL.

Arguments

• x — A value with a non-compound data type.

Returned value

• 1 if x is NULL.
• 0 if x is not NULL.

Example

Input table

┌─x─┬────y─┐
│ 1 │ ᴺᵁᴸᴸ │
│ 2 │    3 │
└───┴──────┘

Query

SELECT x FROM t_null WHERE isNull(y);

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

isNotNull

Checks whether the argument is NULL.

isNotNull(x)

Arguments:

• x — A value with a non-compound data type.

Returned value

• 0 if x is NULL.
• 1 if x is not NULL.

Example

Input table

┌─x─┬────y─┐
│ 1 │ ᴺᵁᴸᴸ │
│ 2 │    3 │
└───┴──────┘

Query

SELECT x FROM t_null WHERE isNotNull(y);

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

coalesce

Checks from left to right whether NULL arguments were passed and returns the first non-NULL argument.

coalesce(x,...)

Arguments:

• Any number of parameters of a non-compound type. All parameters must be compatible by data type.

Returned values

• The first non-NULL argument.
• NULL, if all arguments are NULL.

Example

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

┌─name─────┬─mail─┬─phone─────┬──icq─┐
│ client 1 │ ᴺᵁᴸᴸ │ 123-45-67 │  123 │
│ client 2 │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ      │ ᴺᵁᴸᴸ │
└──────────┴──────┴───────────┴──────┘

The mail and phone fields are of type String, but the icq 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(icq,'Nullable(String)')) FROM aBook;

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

ifNull

Returns an alternative value if the main argument is NULL.

ifNull(x,alt)

Arguments:

• x — The value to check for NULL.
• alt — The value that the function returns if x is NULL.

Returned values

• The value x, if x is not NULL.
• The value alt, if x is NULL.

Example

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

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

SELECT ifNull(NULL, 'b');

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

nullIf

Returns NULL if the arguments are equal.

nullIf(x, y)

Arguments:

x, y — Values for comparison. They must be compatible types, or ClickHouse will generate an exception.

Returned values

• NULL, if the arguments are equal.
• The x value, if the arguments are not equal.

Example

SELECT nullIf(1, 1);

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

SELECT nullIf(1, 2);

┌─nullIf(1, 2)─┐
│            1 │
└──────────────┘

assumeNotNull

Results in an equivalent non-Nullable value for a Nullable type. In case the original value is NULL the result is undetermined. See also ifNull and coalesce functions.

assumeNotNull(x)

Arguments:

• x — The original value.

Returned values

• The original value from the non-Nullable type, if it is not NULL.
• Implementation specific result if the original value was NULL.

Example

Consider the t_null table.

SHOW CREATE TABLE t_null;

┌─statement─────────────────────────────────────────────────────────────────┐
│ CREATE TABLE default.t_null ( x Int8,  y Nullable(Int8)) ENGINE = TinyLog │
└───────────────────────────────────────────────────────────────────────────┘

┌─x─┬────y─┐
│ 1 │ ᴺᵁᴸᴸ │
│ 2 │    3 │
└───┴──────┘

Apply the assumeNotNull function to the y column.

SELECT assumeNotNull(y) FROM t_null;

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

SELECT toTypeName(assumeNotNull(y)) FROM t_null;

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

toNullable

Converts the argument type to Nullable.

toNullable(x)

Arguments:

• x — The value of any non-compound type.

Returned value

• The input value with a Nullable type.

Example

SELECT toTypeName(10);

┌─toTypeName(10)─┐
│ UInt8          │
└────────────────┘

SELECT toTypeName(toNullable(10));

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