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

> 比较函数文档

# 比较函数

<div id="comparison-rules">
  ## 比较规则
</div>

下面的比较函数返回 `0` 或 `1`，返回类型为 [UInt8](/zh/reference/data-types/int-uint)。只有同一组内的值才能进行比较
(例如 `UInt16` 和 `UInt64`) ，不能跨组比较 (例如 `UInt16` 和 `DateTime`) 。
数值和字符串之间可以比较，字符串也可以与日期比较，日期也可以与时间进行比较。
对于元组和数组，比较采用字典序，也就是说会依次比较左侧和右侧元组/数组中对应的各个
元素。

以下类型可以比较：

* 数值和十进制数
* 字符串和定长字符串
* 日期
* 带时间的日期
* 元组 (按字典序比较)
* 数组 (按字典序比较)

<Note>
  字符串按字节逐个比较。如果其中一个字符串包含 UTF-8 编码的多字节字符，可能会产生不符合预期的结果。
  如果字符串 S1 以另一个字符串 S2 作为前缀，则认为 S1 比 S2 长。
</Note>

{/*AUTOGENERATED_START*/}

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

首次引入版本：v1.1.0

比较两个值是否相等。

**语法**

```sql theme={null}
equals(a, b)
        -- a = b
        -- a == b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

如果 `a` 等于 `b`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

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

```response title=Response theme={null}
┌─equals(1, 1)─┬─equals(1, 2)─┐
│            1 │            0 │
└──────────────┴──────────────┘
```

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

引入版本：v1.1.0

与 `in` 相同，但在分布式查询中使用全局集合分发。该集合会发送到所有远程服务器。

**语法**

```sql theme={null}
globalIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 `x` 在该集合中，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 1 IN (1, 2, 3)
```

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

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

引入版本：v1.1.0

与 `in` 相同，但在分布式查询中使用全局集合分发机制。该集合会被发送到所有远程服务器。
这是 IgnoreSet Variant，用于在不创建集合的情况下进行类型分析。

**语法**

```sql theme={null}
globalIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

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

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 1 IN (1, 2, 3)
```

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

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

引入版本：v1.1.0

与 `notIn` 相同，但在分布式查询中使用全局集合分发机制。该集合会发送到所有远程服务器。

**语法**

```sql theme={null}
globalNotIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 x 不在集合中，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 4 NOT IN (1, 2, 3)
```

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

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

引入版本：v1.1.0

与 `notIn` 相同，但在分布式查询中使用全局集合分发机制。该集合会被发送到所有远程服务器。
这是 IgnoreSet Variant，用于在不创建集合的情况下进行类型分析。

**语法**

```sql theme={null}
globalNotIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 x 不在该集合中，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 4 NOT IN (1, 2, 3)
```

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

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

引入版本：v1.1.0

与 `notNullIn` 相同，但在分布式查询中使用全局集合分发机制。该 Set 会发送到所有远程服务器。

**语法**

```sql theme={null}
globalNotNullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 x 不在该集合中，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT notNullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

与 `notNullIn` 相同，但在分布式查询中使用全局集合分发机制。该集合会发送到所有远程服务器。
这是 IgnoreSet Variant，用于在不创建集合的情况下进行类型分析。

**语法**

```sql theme={null}
globalNotNullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 `x` 不在该集合中，则返回 1；否则返回 0。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT notNullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

与 `nullIn` 相同，但在分布式查询中使用全局集合分发机制。该集合会发送到所有远程服务器。

**语法**

```sql theme={null}
globalNullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 `x` 在该集合中，则返回 1，否则返回 0。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT nullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

与 `nullIn` 相同，但在分布式查询中使用全局集合分发。该集合会被发送到所有远程服务器。
这是用于类型分析且不会创建该集合的 IgnoreSet Variant。

**语法**

```sql theme={null}
globalNullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 x 在该集合中，返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT nullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

比较两个值，判断前者是否大于后者。

**语法**

```sql theme={null}
greater(a, b)
    -- a > b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

如果 `a` 大于 `b`，则返回 `1`；否则返回 `0` [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 2 > 1, 1 > 2;
```

```response title=Response theme={null}
┌─greater(2, 1)─┬─greater(1, 2)─┐
│             1 │             0 │
└───────────────┴───────────────┘
```

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

引入版本：v1.1.0

比较两个值是否满足大于等于关系。

**语法**

```sql theme={null}
greaterOrEquals(a, b)
    -- a >= b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

如果 `a` 大于或等于 `b`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 2 >= 1, 2 >= 2, 1 >= 2;
```

```response title=Response theme={null}
┌─greaterOrEquals(2, 1)─┬─greaterOrEquals(2, 2)─┬─greaterOrEquals(1, 2)─┐
│                     1 │                     1 │                     0 │
└───────────────────────┴───────────────────────┴───────────────────────┘
```

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

Introduced in: v1.1.0

检查左操作数是否属于右操作数 Set。若属于则返回 1，否则返回 0。左操作数中的 NULL 值会被跳过 (视为不在该集合中) 。

**语法**

```sql theme={null}
in(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 x 在该集合中，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 1 IN (1, 2, 3)
```

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

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

Introduced in：v1.1.0

检查左操作数是否属于右操作数集合。如果属于，则返回 1，否则返回 0。左操作数中的 NULL 值会被跳过 (视为不在集合中) 。
这是 IgnoreSet 的一种Variant，用于类型分析且不会创建集合。

**Syntax**

```sql theme={null}
in(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

如果 x 在该集合中，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 1 IN (1, 2, 3)
```

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

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

引入版本：v25.11.0

对两个值执行 NULL 安全的“不等于”比较。
如果两个值不同 (即不相等) ，则返回 `true`，包括一个值为 NULL 而另一个值不为 NULL 的情况。
如果两个值相等，或两者均为 NULL，则返回 `false`。

**语法**

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

**参数**

* `x` — 要比较的第一个值。可以是任意 ClickHouse 数据类型。[`Any`](/zh/reference/data-types)
* `y` — 要比较的第二个值。可以是任意 ClickHouse 数据类型。[`Any`](/zh/reference/data-types)

**返回值**

如果两个值不同，则返回 `true`，其中 NULL 也视为可比较值：

* 如果 x != y，则返回 `true`。
  * 如果 x 或 y 中恰好一个为 NULL，则返回 `true`。
  * 如果 x = y，或者 x 和 y 都为 NULL，则返回 `false`。[`Bool`](/zh/reference/data-types/boolean)

**示例**

**数字和 NULL 的基本用法**

```sql title=Query theme={null}
SELECT
    isDistinctFrom(1, 2) AS result_1,
    isDistinctFrom(1, 1) AS result_2,
    isDistinctFrom(NULL, 1) AS result_3,
    isDistinctFrom(NULL, NULL) AS result_4
```

```response title=Response theme={null}
┌─result_1─┬─result_2─┬─result_3─┬─result_4─┐
│        1 │        0 │        1 │        0 │
└──────────┴──────────┴──────────┴──────────┘
```

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

引入版本：v23.8.0

对两个值执行 NULL 安全的“相等”比较。
如果两个值相等 (包括两者都为 NULL 的情况) ，则返回 `true`。
如果两个值不同，或其中恰好一个为 NULL，则返回 `false`。

**语法**

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

**参数**

* `x` — 要比较的第一个值。可以是任意 ClickHouse 数据类型。[`Any`](/zh/reference/data-types)
* `y` — 要比较的第二个值。可以是任意 ClickHouse 数据类型。[`Any`](/zh/reference/data-types)

**返回值**

如果两个值相等，则返回 `true`；NULL 也会被视为可比较值：

* 如果 x = y，则返回 `true`。
  * 如果 x 和 y 均为 NULL，则返回 `true`。
  * 如果 x != y，或者 x 和 y 中恰好有一个为 NULL，则返回 `false`。[`Bool`](/zh/reference/data-types/boolean)

**示例**

**数字和 NULL 的基本用法**

```sql title=Query theme={null}
SELECT
    isNotDistinctFrom(1, 1) AS result_1,
    isNotDistinctFrom(1, 2) AS result_2,
    isNotDistinctFrom(NULL, NULL) AS result_3,
    isNotDistinctFrom(NULL, 1) AS result_4
```

```response title=Response theme={null}
┌─result_1─┬─result_2─┬─result_3─┬─result_4─┐
│        1 │        0 │        1 │        0 │
└──────────┴──────────┴──────────┴──────────┘
```

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

引入版本：v1.1.0

比较两个值，判断是否为小于关系。

**语法**

```sql theme={null}
less(a, b)
    -- a < b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

若 `a` 小于 `b`，则返回 `1`；否则返回 `0` [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 1 < 2, 2 < 1;
```

```response title=Response theme={null}
┌─less(1, 2)─┬─less(2, 1)─┐
│          1 │          0 │
└────────────┴────────────┘
```

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

Introduced in: v1.1.0

比较两个值是否满足小于或等于关系。

**语法**

```sql theme={null}
lessOrEquals(a, b)
-- a <= b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

如果 `a` 小于或等于 `b`，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 1 <= 2, 2 <= 2, 3 <= 2;
```

```response title=Response theme={null}
┌─lessOrEquals(1, 2)─┬─lessOrEquals(2, 2)─┬─lessOrEquals(3, 2)─┐
│                  1 │                  1 │                  0 │
└────────────────────┴────────────────────┴────────────────────┘
```

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

引入版本：v1.1.0

比较两个值是否不相等。

**语法**

```sql theme={null}
notEquals(a, b)
    -- a != b
    -- a <> b
```

**参数**

* `a` — 第一个值。<sup>[\*](#comparison-rules)</sup> - `b` — 第二个值。<sup>[\*](#comparison-rules)</sup>

**返回值**

如果 `a` 不等于 `b`，返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT 1 != 2, 1 != 1;
```

```response title=Response theme={null}
┌─notEquals(1, 2)─┬─notEquals(1, 1)─┐
│               1 │               0 │
└─────────────────┴─────────────────┘
```

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

引入版本：v1.1.0

检查左操作数是否不属于右操作数集合。如果不在集合中，则返回 1，否则返回 0。左操作数中的 NULL 值会被跳过。

**语法**

```sql theme={null}
notIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 x 不在该集合中，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 4 NOT IN (1, 2, 3)
```

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

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

引入版本：v1.1.0

检查左操作数是否**不**属于右操作数集合。若不在集合中，则返回 1，否则返回 0。左操作数中的 NULL 值会被跳过。
这是 IgnoreSet Variant，用于在不创建集合的情况下进行类型分析。

**语法**

```sql theme={null}
notIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 x 不在该集合中，则返回 1；否则返回 0。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT 4 NOT IN (1, 2, 3)
```

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

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

首次引入版本：v1.1.0

检查左操作数是否不属于右操作数集合。与 `notIn` 不同，NULL 值不会被跳过：NULL 会与集合元素进行比较，且 NULL = NULL 的结果为 true。

**语法**

```sql theme={null}
notNullIn(x, set)
```

**参数**

* `x` — 待检查的值。 - `set` — 值的集合。

**返回值**

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

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT notNullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

检查左操作数是否不在右操作数集合中。与 `notIn` 不同，NULL 值不会被跳过：NULL 会与集合中的元素进行比较，并且 NULL = NULL 的结果为 true。
这是 IgnoreSet 的一个Variant，用于类型分析，且不会创建集合。

**语法**

```sql theme={null}
notNullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值集合。

**返回值**

如果 x 不在该集合中，则返回 1；否则返回 0。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT notNullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

检查左操作数是否属于右操作数集合。与 `in` 不同，NULL 值不会被跳过：NULL 会与集合元素进行比较，且 NULL = NULL 的结果为 true。

**语法**

```sql theme={null}
nullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 值的集合。

**返回值**

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

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT nullIn(NULL, tuple(1, NULL))
```

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

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

引入版本：v1.1.0

检查左操作数是否属于右操作数集合。与 `in` 不同，NULL 值不会被跳过：NULL 会与集合中的元素进行比较，且 NULL = NULL 的结果为 true。
这是 IgnoreSet 的一个 Variant，用于在不创建集合的情况下进行类型分析。

**语法**

```sql theme={null}
nullIn(x, set)
```

**参数**

* `x` — 要检查的值。 - `set` — 一组值。

**返回值**

如果 x 在该集合中，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT nullIn(NULL, tuple(1, NULL))
```

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