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

> 用于处理 Nullable 值的函数文档

# 用于处理 Nullable 值的函数

{/*AUTOGENERATED_START*/}

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

引入版本：v1.1.0

返回 [`Nullable`](/zh/reference/data-types/nullable) 类型的值对应的非 `Nullable` 值。
如果原始值为 `NULL`，则可能返回任意结果。

另请参见：函数 [`ifNull`](#ifNull) 和 [`coalesce`](#coalesce)。

**语法**

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

**参数**

* `x` — 任意 Nullable 类型的原始值。[`Nullable(T)`](/zh/reference/data-types/nullable)

**返回值**

如果原始值不是 `NULL`，则返回其非 Nullable 值；如果输入值为 `NULL`，则返回任意值。[`Any`](/zh/reference/data-types/index)

**示例**

**用法示例**

```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>

首次引入版本：v1.1.0

返回第一个非 `NULL` 参数。

**语法**

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

**参数**

* `x[, y, ...]` — 任意数量的非复合类型参数。所有参数的数据类型都必须彼此兼容。[`Any`](/zh/reference/data-types/index)

**返回值**

返回第一个非 `NULL` 的参数；如果所有参数均为 `NULL`，则返回 `NULL`。[`Any`](/zh/reference/data-types/index) 或 [`NULL`](/zh/reference/syntax#null)

**示例**

**使用示例**

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

```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>

Introduced in: v25.9.0

返回一组参数中第一个非默认值

**语法**

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

**参数**

* `arg1` — 要检查的第一个参数 - `arg2` — 要检查的第二个参数 - `...` — 要检查的其他参数

**返回值**

结果类型为所有参数的超类型

**示例**

**整数**

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

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

**String**

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

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

**NULL 值**

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

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

**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>

引入版本：v1.1.0

如果第一个参数为 `NULL`，则返回替代值。

**语法**

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

**参数**

* `x` — 要检查是否为 `NULL` 的值。[`Any`](/zh/reference/data-types/index)
* `alt` — 当 `x` 为 `NULL` 时，函数返回的值。[`Any`](/zh/reference/data-types/index)

**返回值**

如果 `x` 不为 `NULL`，则返回 `x`；否则返回 `alt`。[`Any`](/zh/reference/data-types/index)

**示例**

**用法示例**

```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>

引入版本：v1.1.0

检查参数是否不为 `NULL`。

另请参见：运算符 [`IS NOT NULL`](/zh/reference/operators/index#is_not_null)。

**语法**

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

**参数**

* `x` — 非复合数据类型的值。[`Any`](/zh/reference/data-types/index)

**返回值**

如果 `x` 不是 `NULL`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```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>

引入版本：v1.1.0

检查参数是否为 `NULL`。

另请参见：运算符 [`IS NULL`](/zh/reference/operators/index#is_null)。

**语法**

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

**参数**

* `x` — 非复合数据类型的一个值。[`Any`](/zh/reference/data-types/index)

**返回值**

如果 `x` 为 `NULL`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```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>

引入版本：v22.7.0

检查参数的数据类型是否为 `Nullable` (即允许 `NULL` 值) 。

**语法**

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

**参数**

* `x` — 任意数据类型的值。[`Any`](/zh/reference/data-types/index)

**返回值**

如果 `x` 的数据类型是 `Nullable`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```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>

引入版本：v20.3.0

检查参数是否为零 (`0`) 或 `NULL`。

**语法**

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

**参数**

* `x` — 数值。[`UInt`](/zh/reference/data-types/int-uint)

**返回值**

如果 `x` 为 `NULL` 或等于零，则返回 `1`；否则返回 `0`。返回类型为 [`UInt8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Float32/Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```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>

引入版本：v1.1.0

当两个参数相等时，返回 `NULL`。

**语法**

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

**参数**

* `x` — 第一个值。[`Any`](/zh/reference/data-types/index)
* `y` — 第二个值。[`Any`](/zh/reference/data-types/index)

**返回值**

如果两个参数相等，则返回 `NULL`；否则返回第一个参数。[`NULL`](/zh/reference/syntax#null) 或 [`Nullable(x)`](/zh/reference/data-types/nullable)

**示例**

**使用示例**

```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>

引入版本：v1.1.0

将提供的参数类型转换为 `Nullable`。

**语法**

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

**参数**

* `x` — 任意非复合类型的值。[`Any`](/zh/reference/data-types/index)

**返回值**

返回输入值，但其类型为 `Nullable`。[`Nullable(Any)`](/zh/reference/data-types/nullable)

**示例**

**使用示例**

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

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