> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentação de funções para trabalhar com valores Nullable

# Funções para trabalhar com valores Nullable

{/*AUTOGENERATED_START*/}

<div id="assumeNotNull">
  ## assumeNotNull
</div>

Introduzido em: v1.1.0

Retorna o valor não `Nullable` correspondente a um valor do tipo [`Nullable`](/pt-BR/reference/data-types/nullable).
Se o valor original for `NULL`, um resultado arbitrário poderá ser retornado.

Veja também: as funções [`ifNull`](#ifNull) e [`coalesce`](#coalesce).

**Sintaxe**

```sql theme={null}
assumeNotNull(x)
```

**Argumentos**

* `x` — O valor original de qualquer tipo `Nullable`. [`Nullable(T)`](/pt-BR/reference/data-types/nullable)

**Valor retornado**

Retorna o valor não anulável se o valor original não for `NULL`; caso contrário, retorna um valor arbitrário se o valor de entrada for `NULL`. [`Any`](/pt-BR/reference/data-types)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─assumeNotNull(y)─┐
│                0 │
│                3 │
└──────────────────┘
┌─toTypeName(assumeNotNull(y))─┐
│ Int8                         │
│ Int8                         │
└──────────────────────────────┘
```

<div id="coalesce">
  ## coalesce
</div>

Introduzido em: v1.1.0

Retorna o argumento não `NULL` mais à esquerda.

**Sintaxe**

```sql theme={null}
coalesce(x[, y, ...])
```

**Argumentos**

* `x[, y, ...]` — Qualquer número de parâmetros de tipo não composto. Todos os parâmetros devem ser de tipos de dados compatíveis entre si. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna o primeiro argumento não `NULL`; caso todos os argumentos sejam `NULL`, retorna `NULL`. [`Any`](/pt-BR/reference/data-types) ou [`NULL`](/pt-BR/reference/syntax#null)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
-- Considere uma lista de contatos que pode especificar múltiplas formas de contatar um cliente.

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);

-- Os campos mail e phone são do tipo String, mas o campo telegram é UInt32, portanto precisa ser convertido para String.

-- Obtém o primeiro método de contato disponível para o cliente a partir da lista de contatos

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

```response title=Response theme={null}
┌─name─────┬─coalesce(mail, phone, CAST(telegram, 'Nullable(String)'))─┐
│ client 1 │ 123-45-67                                                 │
│ client 2 │ ᴺᵁᴸᴸ                                                      │
└──────────┴───────────────────────────────────────────────────────────┘
```

<div id="firstNonDefault">
  ## firstNonDefault
</div>

Introduzido em: v25.9.0

Retorna o primeiro valor diferente do padrão de um conjunto de argumentos

**Sintaxe**

```sql theme={null}
firstNonDefault(arg1[, arg2[ ...]])
```

**Argumentos**

* `arg1` — O primeiro argumento a ser verificado - `arg2` — O segundo argumento a ser verificado - `...` — Argumentos adicionais a serem verificados

**Valor retornado**

O tipo do resultado é o supertipo de todos os argumentos

**Exemplos**

**inteiros**

```sql title=Query theme={null}
SELECT firstNonDefault(0, 1, 2)
```

```response title=Response theme={null}
1
```

**strings**

```sql title=Query theme={null}
SELECT firstNonDefault('', 'hello', 'world')
```

```response title=Response theme={null}
'hello'
```

**NULLs**

```sql title=Query theme={null}
SELECT firstNonDefault(NULL, 0 :: UInt8, 1 :: UInt8)
```

```response title=Response theme={null}
1
```

**zero Nullable**

```sql title=Query theme={null}
SELECT firstNonDefault(NULL, 0 :: Nullable(UInt8), 1 :: Nullable(UInt8))
```

```response title=Response theme={null}
0
```

<div id="ifNull">
  ## ifNull
</div>

Introduzido na versão: v1.1.0

Retorna um valor alternativo se o primeiro argumento for `NULL`.

**Sintaxe**

```sql theme={null}
ifNull(x, alt)
```

**Argumentos**

* `x` — O valor a verificar se é `NULL`. [`Any`](/pt-BR/reference/data-types)
* `alt` — O valor que a função retorna se `x` for `NULL`. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna o valor de `x` se ele não for `NULL`; caso contrário, `alt`. [`Any`](/pt-BR/reference/data-types)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT ifNull('a', 'b'), ifNull(NULL, 'b');
```

```response title=Response theme={null}
┌─ifNull('a', 'b')─┬─ifNull(NULL, 'b')─┐
│ a                │ b                 │
└──────────────────┴───────────────────┘
```

<div id="isNotNull">
  ## isNotNull
</div>

Introduzido em: v1.1.0

Verifica se o argumento não é `NULL`.

Veja também: operador [`IS NOT NULL`](/pt-BR/reference/operators#is_not_null).

**Sintaxe**

```sql theme={null}
isNotNull(x)
```

**Argumentos**

* `x` — Um valor de um tipo de dado não composto. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna `1` se `x` não for `NULL`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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);
```

```response title=Response theme={null}
┌─x─┐
│ 2 │
└───┘
```

<div id="isNull">
  ## isNull
</div>

Introduzido em: v1.1.0

Verifica se o argumento é `NULL`.

Veja também: operador [`IS NULL`](/pt-BR/reference/operators#is_null).

**Sintaxe**

```sql theme={null}
isNull(x)
```

**Argumentos**

* `x` — Um valor de tipo de dado não composto. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna `1` se `x` for `NULL`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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);
```

```response title=Response theme={null}
┌─x─┐
│ 1 │
└───┘
```

<div id="isNullable">
  ## isNullable
</div>

Introduzido na versão: v22.7.0

Verifica se o tipo de dado do argumento é `Nullable` (ou seja, se permite valores `NULL`).

**Sintaxe**

```sql theme={null}
isNullable(x)
```

**Argumentos**

* `x` — Um valor de qualquer tipo de dado. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna `1` se `x` for do tipo de dado `Nullable`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌───isNullable(ordinary_col)──┬───isNullable(nullable_col)──┐
│                           0 │                           1 │
│                           0 │                           1 │
│                           0 │                           1 │
└─────────────────────────────┴─────────────────────────────┘
```

<div id="isZeroOrNull">
  ## isZeroOrNull
</div>

Introduzido na versão: v20.3.0

Verifica se o argumento é igual a zero (`0`) ou `NULL`.

**Sintaxe**

```sql theme={null}
isZeroOrNull(x)
```

**Argumentos**

* `x` — Um valor numérico. [`UInt`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna `1` se `x` for `NULL` ou igual a zero; caso contrário, `0`. [`UInt8/16/32/64`](/pt-BR/reference/data-types/int-uint) ou [`Float32/Float64`](/pt-BR/reference/data-types/float)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
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);
```

```response title=Response theme={null}
┌─x─┐
│ 1 │
│ 2 │
└───┘
```

<div id="nullIf">
  ## nullIf
</div>

Introduzido em: v1.1.0

Retorna `NULL` se os dois argumentos forem iguais.

**Sintaxe**

```sql theme={null}
nullIf(x, y)
```

**Argumentos**

* `x` — O primeiro valor. [`Any`](/pt-BR/reference/data-types)
* `y` — O segundo valor. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna `NULL` se ambos os argumentos forem iguais; caso contrário, retorna o primeiro argumento. [`NULL`](/pt-BR/reference/syntax#null) ou [`Nullable(x)`](/pt-BR/reference/data-types/nullable)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT nullIf(1, 1), nullIf(1, 2);
```

```response title=Response theme={null}
┌─nullIf(1, 1)─┬─nullIf(1, 2)─┐
│         ᴺᵁᴸᴸ │            1 │
└──────────────┴──────────────┘
```

<div id="toNullable">
  ## toNullable
</div>

Introduzido em: v1.1.0

Converte o tipo do argumento fornecido para `Nullable`.

**Sintaxe**

```sql theme={null}
toNullable(x)
```

**Argumentos**

* `x` — Um valor de qualquer tipo não composto. [`Any`](/pt-BR/reference/data-types)

**Valor retornado**

Retorna o valor de entrada, mas com o tipo `Nullable`. [`Nullable(Any)`](/pt-BR/reference/data-types/nullable)

**Exemplos**

**Exemplo de uso**

```sql title=Query theme={null}
SELECT toTypeName(10), toTypeName(toNullable(10));
```

```response title=Response theme={null}
┌─toTypeName(10)─┬─toTypeName(toNullable(10))─┐
│ UInt8          │ Nullable(UInt8)            │
└────────────────┴────────────────────────────┘
```