search 函数

适用于：检查标记为“是”的 Databricks Runtime 19.0 及更高版本

重要

此功能在 Beta 版中。 工作区管理员可以从 预览 页控制对此功能的访问。 请参阅 Manage Azure Databricks 预览版。

返回 true 是否 search_pattern 在任何提供的目标列值中找到。

有关使用全文搜索索引加速 search 查询的信息，请参阅 Unity 目录托管表上的全文搜索索引。

Syntax

search ( column [, ...], search_pattern [, mode => mode] )

Arguments

  • column：一个或多个可搜索的目标表达式。 可搜索表达式具有以下类型之一：

    • STRING 使用 UTF8_BINARY 排序规则。
    • VARIANT。
    • STRUCT 至少有一个可搜索字段。 结构会自动扩展到任何嵌套深度处的可搜索叶字段。
    • ARRAY 任何可搜索类型。

    非字符串目标值没有隐式强制转换。

  • search_pattern：具有要搜索的值的可折叠（常量） STRING 表达式。

  • mode：一个可选的命名 STRING 参数，用于控制如何执行匹配。 下列其中一项：

    • 'substring' （默认值）：如果 search_pattern 出现在目标值中的任何位置，则匹配。 等效于 contains 函数。
    • 'word'：根据目标值匹配各个单词 search_pattern ，而不考虑顺序。

Returns

BOOLEAN。

  • true 如果在 search_pattern 任何目标列值中找到。
  • NULL 如果在 search_pattern 任何目标列值中找不到，则至少有一个值是 NULL。
  • 否则为 false。

Notes

  • isearch 函数 是不区分大小写的变体， search 具有其他相同行为。
  • 对于参数 STRUCT ，该函数搜索可从顶层结构访问的每个可搜索叶字段，而不考虑嵌套深度。 相同的扩展以递归方式应用于 STRUCT 字段 VARIANT 和 ARRAY 值。
  • 在 'substring' 模式下， VARIANT 键和非字符串标量值在一个 VARIANT 内部不匹配。 使用 'word' 模式或提取单个字段来搜索这些字段。

常见错误条件

示例

-- Basic examples.
> SELECT search(column, 'needle', mode => 'substring') FROM VALUES ('Needle') AS table(column);
 false

> SELECT search(column, 'quick fox', mode => 'substring') FROM VALUES ('quick brown fox') AS table(column);
 false

> SELECT search(column, lower('NEEDLE')) FROM VALUES ('needle') AS table(column);
 true

> SELECT search(column, 'quick fox', mode => 'word') FROM VALUES ('quick brown fox') AS table(column);
 true

> SELECT search(column, 'qui fox', mode => 'word') FROM VALUES ('quick fox') AS table(column);
 false

-- Automatic expansion of STRUCT columns to their searchable leaf fields.
> CREATE TABLE test_table (
    usage_stats STRUCT<digits: INT>,
    customer_info STRUCT<
      contact: STRUCT<json_field: VARIANT>,
      name: STRING>)
  USING DELTA;

> SELECT * FROM test_table WHERE search(usage_stats.digits, 'needle');
 [DATATYPE_MISMATCH.UNEXPECTED_INPUT_TYPE]

> SELECT * FROM test_table WHERE search(customer_info, 'needle');
-- Equivalent to:
> SELECT * FROM test_table
  WHERE search(customer_info.contact.json_field, customer_info.name, 'needle');

> SELECT * FROM test_table WHERE search(customer_info.contact, 'needle');
-- Equivalent to:
> SELECT * FROM test_table
  WHERE search(customer_info.contact.json_field, 'needle');

-- VARIANT behavior: substring mode does not match keys or non-string scalar values.
> CREATE TABLE test_table AS
  SELECT parse_json('{
    "role": "user",
    "id": 101,
    "preferences": {"theme": "dark", "language": "en"}
  }') AS column;

> SELECT search(column, 'user', mode => 'substring') FROM test_table;
 true

> SELECT search(column, 'preferences', mode => 'substring') FROM test_table;
 false

> SELECT search(column, '101', mode => 'substring') FROM test_table;
 false

-- NULL behavior.
> SELECT search(NULL, 'needle', mode => 'substring');
 NULL

> SELECT search(CAST(NULL AS STRING), 'needle', mode => 'substring');
 NULL

> SELECT search('needle in haystack', NULL, mode => 'substring');
 [SEARCH_REQUIRES_STRING_LITERALS_ARGUMENTS]
  • Last updated on