类别：

条件表达式函数、半结构化和结构化数据函数 （类型谓词）

IS_NULL_VALUE

如果其 VARIANT 实参是 :ref:`JSON null <label-variant_null>`值，则返回 TRUE。

重要

JSON null 值与 SQL NULL 值不同。

此函数仅对 JSON null 值而非 SQL NULL 值返回 TRUE。在下面示例的输出中 ，第一行和第三行出现差异。

将缺少的 JSON 值转换为 SQL NULL 值，IS_NULL_VALUE 将为此值返回 NULL。以下示例输出 中的第 4 列显示了这一点。

此函数不同于 IS [ NOT ] NULL 函数。

另请参阅：

IS_<object_type>

语法

IS_NULL_VALUE( <variant_expr> )

实参

variant_expr

VARIANT 类型值计算的表达式。

返回

此函数返回 BOOLEAN 或 NULL 类型值：

  • 对于 JSON null 值，则返回 TRUE。

  • 对于非 null JSON 值，则返回 FALSE。

  • 对于 SQL NULL 值，则返回 NULL。

示例

此示例使用 IS_NULL_VALUE 函数。首先，创建一个带有 VARIANT 列的表：

CREATE OR REPLACE TABLE test_is_null_value_function (
  variant_value VARIANT);

使用 PARSE_JSON 函数将字符串值插入到该列中：

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON('"string value"'));

备注

该 PARSE_JSON 函数会返回 VARIANT 值。

在该列中插入一个 JSON null 值：

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON('null'));

在该列中插入一个空对象：

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON('{}'));

将两行包含 JSON 名称/值对的行插入该 VARIANT 列：

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON('{"x": null}'));

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON('{"x": "foo"}'));

在列中插入 NULL

INSERT INTO test_is_null_value_function (variant_value)
  (SELECT PARSE_JSON(NULL));

查询表：

SELECT variant_value,
       variant_value:x value_of_x,
       IS_NULL_VALUE(variant_value) is_variant_value_a_json_null,
       IS_NULL_VALUE(variant_value:x) is_x_a_json_null,
       IS_NULL_VALUE(variant_value:y) is_y_a_json_null
  FROM test_is_null_value_function;

+----------------+------------+------------------------------+------------------+------------------+
| VARIANT_VALUE  | VALUE_OF_X | IS_VARIANT_VALUE_A_JSON_NULL | IS_X_A_JSON_NULL | IS_Y_A_JSON_NULL |
|----------------+------------+------------------------------+------------------+------------------|
| "string value" | NULL       | False                        | NULL             | NULL             |
| null           | NULL       | True                         | NULL             | NULL             |
| {}             | NULL       | False                        | NULL             | NULL             |
| {              | null       | False                        | True             | NULL             |
|   "x": null    |            |                              |                  |                  |
| }              |            |                              |                  |                  |
| {              | "foo"      | False                        | False            | NULL             |
|   "x": "foo"   |            |                              |                  |                  |
| }              |            |                              |                  |                  |
| NULL           | NULL       | NULL                         | NULL             | NULL             |
+----------------+------------+------------------------------+------------------+------------------+

在查询结果中：

  • variant_value 列显示了六行已插入的 VARIANT 值。

  • value_of_x 列显示每行 x 名称的 JSON 值。

  • is_variant_value_a_json_null 列返回每行 VARIANT 值的 IS_NULL_VALUE 函数结果。

  • is_x_a_json_null 列返回每行 x 名称的 IS_NULL_VALUE 函数结果。没有 x 名称的行返回 NULL。

  • is_y_a_json_null 列返回每行 y 名称的 IS_NULL_VALUE 函数结果。由于任何行中都没有匹配的 y 名称，所以所有行都返回 NULL。