HYBRID_SEARCH - OceanBase 数据库 V5.0.1

HYBRID_SEARCH 用于在一条 SELECT 语句中，通过符合本文档规则的 JSON 字符串描述全文搜索、向量搜索与过滤条件，并返回按融合策略排序后的行。

注意

本语法仅适用于 MySQL 模式。

语法

SELECT select_expr_list
FROM HYBRID_SEARCH(TABLE table_name, dsl_string) [table_alias];

-- select_expr_list 为 SELECT 列表，与常规 SELECT 语法一致

参数说明

参数	说明
`table_name`	目标表名。仅支持堆表（`ORGANIZATION = HEAP`），可为分区表或非分区表。
`dsl_string`	JSON 字符串，描述 `query`、`knn`、`rank`、`from`、`size`、`min_score` 等。注意除下文“限制和说明”中列出的差异外，其余语法结构及参数说明与 SEARCH 的 `search_params` 一致，已了解 `SEARCH` 语法结构的用户直接了解两者差异即可。

全局限制与说明

本节只列出语法限制，功能限制请参见文末相关文档索引混合搜索（SQL 接口），需结合本节内容一并理解。

说明如下：

顶层 query（全文搜索）和 knn（向量搜索）加起来最多允许有三个子查询：query 算一个；knn 如果是对象算一个，如果是数组则每个元素各算一个。三者总数不得超过三个，并且至少要包含一个全文搜索或向量搜索。
对于查询的列名，大小写不敏感。
向量查询的 query_vector，推荐用字符串输入向量。
min_score 参数只有 SQL 接口支持，PL 接口不支持。
query 和每个 knn 都是相互独立的搜索路径，彼此的 filter 互不影响。如果某一路查询需要过滤条件，必须在该路径下单独指定对应的 filter。所有搜索结果会合并为一个结果集，并基于融合算法进行打分排序，最终返回前 size 条结果。

限制如下：

不支持 rank_feature，es_mode，_source 参数。

不支持在与 HYBRID_SEARCH 同层直接使用 WHERE / ORDER BY / LIMIT；若需要进一步过滤或排序，请将混搜结果作为子查询再处理。例如：

-- 不支持：与 HYBRID_SEARCH 同层使用 WHERE
SELECT id
FROM HYBRID_SEARCH(TABLE doc_table, '{"knn":{"field":"vector","k":5,"query_vector":"[1,2,3]"}}')
WHERE id > 3;

-- 支持：先子查询，再过滤
SELECT id
FROM (
  SELECT id
  FROM HYBRID_SEARCH(TABLE doc_table, '{"knn":{"field":"vector","k":5,"query_vector":"[1,2,3]"}}')
) t
WHERE id > 3;

部分嵌套 JSON/ARRAY 元素路径不支持下推，如 json 的 path 里如果是 array，元素是 json，不支持再对这个 json 元素指定路径。
标量查询，包括 term / range / terms / json 表达式 / array 表达式，不算分，不支持 boost，不可以在 bool 的 must / should 中使用。
非顶层全文查询的 boost、bool 查询的 boost、全文查询的列权重和词权重，要求大于 0，其他情况的 boost 要求大于等于 0。
multi_match / query_string 多查询的多个全文列，必须是使用相同的字符集和 collation，全文索引必须使用相同的 parser。
match / multi_match / query_string 用于词项级匹配时，对应全文列应使用 FTS_INDEX_TYPE = MATCH（或未指定时与 MATCH 等价的默认类型）。match_phrase 仅适用于已创建 FTS_INDEX_TYPE = PHRASE_MATCH 的全文索引列。

DSL_STRING 参数语法结构

dsl_string 是 JSON 格式的字符串，其语法结构将在此节详细介绍，请配合下文参数和示例一起理解。

建议阅读顺序

先看 DSL_STRING 参数骨架示例（整体由哪些顶层字段组成），再按需对照 语法定义 中的 BNF 分块；各字段含义与约束以 详细参数说明 表格为准。端到端建表与更多场景示例见文末相关文档索引混合搜索（SQL 接口）。

语法说明

本节介绍 BNF（Backus-Naur Form，巴科斯范式）语法符号的含义和使用规则：

可选参数表示
- [ ] 在 BNF 中表示可选多个元素，如 param_list = param [, param]* 表示 param_list 可以包含 1 个或多个 param。
- rank_expression 中 [ ] 也表示子参数可选。
- [, "boost" : boost_value] 代表在支持 boost 的表达式中该子参数可选；term / range / terms 及 JSON/ARRAY 标量表达式不支持 boost。
数组表示
- [ ] 在 JSON 结构中表示数组，如 [condition_list]。
选择关系
- | 表示选择关系，如 param = "query" | "knn" 表示 param 可以是 "query" 或 "knn"。
重复表示
- * 表示 0 次或多次重复，如 param_list = param [, param]* 表示 param_list 可以包含 1 个或多个 param。
JSON 格式要求
- 所有 JSON 列名和字符串值都需要用双引号包围。
- 数值不需要用双引号包围。

语法定义

本节详细介绍 dsl_string 的语法结构，参数说明请参考下方详细参数说明表格。

DSL_STRING 参数骨架示例

下面是一条与下文“全文与向量 RRF 混合搜索”示例等价的 dsl_string 骨架：顶层可同时出现 query（全文）、knn（向量）、rank（如 RRF 融合）、from / size（分页）等。只需一路搜索时，删除不需要的顶层键即可；SQL 接口还可选增加 min_score，具体见参数表。

SELECT * FROM HYBRID_SEARCH(
  TABLE doc_table,
  '{
    "query": {
      "match": {
        "content": "oceanbase mysql"
      }
    },
    "knn": {
      "field": "vector",
      "k": 5,
      "query_vector": "[1,2,3]"
    },
    "rank": {
      "rrf": {
        "rank_window_size": 10,
        "rank_constant": 60
      }
    },
    "from": 0,
    "size": 10
  }'
);

顶层参数结构

顶层参数结构用于指定混合搜索的参数。

dsl_string = '{param_list}'
    param_list = param [, param]*
    -- query 和 knn 至少必选一个；混合搜索时可同时使用
    param = "query"     : {query_expression}
          | "knn"       : {knn_expression}
          | "rank"      : {rank_expression}
          | "from"      : number
          | "size"      : number
          | "min_score" : number -- 仅 SQL 接口支持

查询表达式结构

查询表达式结构用于指定混合搜索中的全文、标量查询条件。

query_expression = bool_query | scalar_term | fulltext_term

bool_query = "bool" : {bool_condition_list}
    bool_condition_list = bool_condition [, bool_condition]*
    bool_condition = "must"    : [condition_list]
                  | "should"   : [condition_list]
                  | "must_not" : [condition_list]
                  | "filter"   : [condition_list]
                  | "boost"    : boost_value
    condition_list = query_expression [, query_expression]*

bool 下 must / should / must_not / filter 的值均为查询表达式数组：数组中每一项仍是完整的 query_expression（可继续嵌套 bool 或接 match / term 等）。下面仅展示 query 对象的内层片段示例：

{
  "bool": {
    "must": [
      {
        "match": {
          "content": "oceanbase"
        }
      }
    ],
    "filter": [
      {
        "term": {
          "status": 1
        }
      }
    ]
  }
}

标量查询结构

用于定义单个词条中的标量查询表达式，包含 range_query、term_query、terms_query，对应 SQL 语法中的 range、term、terms 表达式，表示范围查询、精准匹配、多值匹配。

scalar_term = range_query | term_query | terms_query

range_query = "range" : {"field_name" : {range_condition_list}}
    range_condition_list = range_condition [, range_condition]*
    range_condition = "gte" : number
                    | "gt"  : number
                    | "lte" : number
                    | "lt"  : number

term_query = "term" : {term_condition_list}
    term_condition_list = term_condition [, term_condition]*
    term_condition = "field_name" : scalar_value
                   | "field_name" : term_value_object
    term_value_object = "value" : scalar_value

terms_query = "terms" : {terms_condition_list}
    terms_condition_list = terms_condition [, terms_condition]*
    terms_condition = "field_name" : [scalar_value_list]
    scalar_value_list = scalar_value [, scalar_value]*

全文查询结构

用于定义单个词条中的全文查询表达式，包含 match_query、match_phrase_query、query_string、multi_match，对应 SQL 语法中的 match、match_phrase、query_string、multi_match 表达式，表示词项级匹配、短语级匹配、全文查询、多列词项级匹配。

fulltext_term = match_query | match_phrase_query | query_string | multi_match

match_query = "match" : {"field_name" : match_body}
    match_body = "string_value" | {match_condition}
    match_condition = "query" : "string_value" [, "operator" : ("OR" | "AND")] [, "minimum_should_match" : number] [, "boost" : boost_value]

match_phrase_query = "match_phrase" : {"field_name" : phrase_body}
    phrase_body = "string_value" | {phrase_condition}
    phrase_condition = "query" : "string_value" [, "slop" : number] [, "boost" : boost_value]

query_string = "query_string" : {query_string_condition}
    query_string_condition = "fields" : [field_weight_list]
                           | "query"  : "string_value" -- 可含词元级 ^，具体见下文「权重运算符说明」
                           | "boost"  : boost_value
                           | "type"   : ("best_fields" | "most_fields")
                           | "default_operator" : ("AND" | "OR")
                           | "minimum_should_match" : number

multi_match = "multi_match" : {multi_match_condition}
    multi_match_condition = "fields" : [field_weight_list]
                         | "query"  : "string_value" -- 不支持查询串内词元级 ^
                         | "boost"  : boost_value
                         | "type"   : ("best_fields" | "most_fields")
                         | "operator" : ("AND" | "OR")
                         | "minimum_should_match" : number
    field_weight_list = field_weight [, field_weight]*
    field_weight = "field_name[^number]"

向量与排序结构

用于指定向量搜索参数，可配置搜索向量字段、相似度、过滤条件、权重等信息，支持单路及多路向量检索。

knn_expression = "knn" : {knn_condition_list} | [multi_knn_condition_list]
    knn_condition_list = knn_condition [, knn_condition]*
    knn_condition = "field"        : "field_name"
                 | "k"            : number
                 | "query_vector" : [vector_values]
                 | "filter"       : [condition_list]
                 | "similarity"   : number
                 | "boost"        : boost_value
    multi_knn_condition_list = {knn_condition} [, {knn_condition}]*
    vector_values = float [, float]*

rank_expression = "rank" : {rank_strategy}
    rank_strategy = "rrf" : {rrf_params}
    rrf_params = "rank_window_size" : number [, "rank_constant" : number]

单路向量搜索时，knn 为单个对象；多路时为对象数组，每个元素是一组 knn_condition。下面仅展示多路向量搜索时的 knn 片段示例：

{
  "knn": [
    {
      "field": "vector_a",
      "k": 3,
      "query_vector": "[1,0,0]"
    },
    {
      "field": "vector_b",
      "k": 3,
      "query_vector": "[0,1,0]"
    }
  ]
}

基础类型定义

上述语法中用到的基础数据类型定义。

field_name = "string_value"
field_list = field_name [, field_name]*
number = integer | decimal
boost_value = integer | float
boolean = true | false
scalar_value = "string_value" | number | boolean

详细参数说明

表达式类型	参数名称	参数描述
顶层关键字参数
	query	进行全文搜索时可单独使用，混合搜索时可以与 `knn` 参数同时使用。
	knn	进行单路/多路向量搜索时可单独使用，混合搜索时可以与 `query` 参数同时使用。
	rank（可选）	用于指定混合搜索时的排序策略，支持 RRF（Reciprocal Rank Fusion）算法。
	from（可选）	用于指定从搜索结果集的第几行返回结果，不指定则默认从第 1 行返回，需要和 `size` 参数一起使用。
	size（可选）	用于限制返回结果的函数，不指定则默认为 `10`。
bool	must	必须满足，需要计算得分。在内部需要布尔逻辑时，须嵌套 bool 表达式，bool 表达式中的多个条件默认按 AND 逻辑组合。
	should	应该满足，类似于 OR，需要计算得分。在内部需要布尔逻辑时，须嵌套 bool 表达式，bool 表达式中的多个条件默认按 AND 逻辑组合。
	must_not	必须不满足，不计算得分，转换成 'NOT' 表达式，must_not 内多个以 'AND' 相连。在内部需要布尔逻辑时，须嵌套 bool 表达式，bool 表达式中的多个条件默认按 AND 逻辑组合。 bool 中至少需要包含 1 个正向条件（must / should / filter），不支持只有 1 个 must_not 条件。
	filter	必须满足，不计算得分，转换成 'AND' 表达式。在内部需要布尔逻辑时，须嵌套 bool 表达式，bool 表达式中的多个条件默认按 AND 逻辑组合。
	boost（可选）	查询权重，详见下方 boost 参数详细说明。注意：`term`/`range`/`terms` 等标量查询不支持 `boost`。
标量查询（scalar_term）	range	范围搜索，搭配 gte、gt、lte、lt 使用。`fieldname` 必选。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。
	term	精准匹配，支持字符串、数字、布尔值等标量值，转换成 sql 的 '=' 表达式。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。
	terms	对指定集合中的任意一个值精准匹配，支持字符串、数字、布尔值等标量值的数组，转换成 sql 的 'IN' 表达式。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。
全文查询（fulltext_term）	match	全文匹配，在单列上做词项匹配。对应列应建立单列全文索引（`FTS_INDEX_TYPE = MATCH` 或与默认等价的类型）。支持完整对象形式 `{"field":{"query":"...","operator":"OR\|AND","minimum_should_match":n,"boost":...}}`，或不写可选子段时的简化形式 `{"field":"查询字符串"}`。查询串按索引所用分词器分词；同一关键词重复出现仅提高权重，不改变是否匹配。`operator` 为关键词间逻辑，可选，默认 `OR`。`OR` 表示应当匹配任意关键词；`AND` 表示应当匹配全部关键词。`minimum_should_match` 仅在 `operator = OR` 时生效，为 `[0, INT32_MAX]` 的整数，可选，默认 `1`；值为 `0` 时按 `1` 处理；大于等于关键词个数时等效于 `operator = AND`。
	match_phrase	全文匹配，在单列上做短语匹配。对应列须建立 `FTS_INDEX_TYPE = PHRASE_MATCH` 的单列全文索引。支持完整对象形式 `{"field":{"query":"...","slop":n,"boost":...}}` 或简化形式 `{"field":"短语字符串"}`。短语按索引分词器分词；若短语中含停用词，对应位置可匹配任意词元（Token）。`slop` 为词元间最大允许偏移，取值为 `[0, INT32_MAX]` 的整数；`0` 表示精确匹配，正整数表示模糊匹配（可选，默认 `0`）。
	query_string	全文匹配，在多列上使用运算符 `^` 扩展查询语义。先按运算符将 `query` 拆成多组；每组内在各列上分别匹配后再按列汇总；最后汇总各组得分。全文搜索参数中，只有 `query_string` 支持词元级别权重：可在 `query` 中使用 `^` 接正浮点数为该组关键词指定权重。不得包含保留词（不区分大小写）`OR`、`AND`、`NOT`、`TO`；不得包含字符 `+ - & \| ! = < > ( ) [ ] { } " ~ * ? : \ /`（文档中展示为字面约束，实际 JSON 中需合法转义）。
	multi_match	全文匹配，在多列上做词项匹配，以列为中心（field-centric）：各列分别对关键词打分后再汇总。各列须为单列全文索引且字符集、分词器一致。 `multi_match` 不支持词元级别权重，仅支持列级别与整条查询级别的权重设置：列级别权重通过 `fields` 的 `列名^权重` 指定。查询级别权重通过 `boost` 指定。
全文查询类型的公共参数	fields	`multi_match` / `query_string` 的列列表；列名后可加 `^` 与正浮点数指定列权重，默认 `1.0`。同一列名多次出现时以最后一次权重为准。
	query	`multi_match` / `query_string` 的查询字符串；`match` / `match_phrase` 的查询内容写在各自列对象下的 `query` 列名（或简化形式中直接作为列值字符串）。关键词重复仅影响权重。
	minimum_should_match（可选）	在 `match`、`multi_match` 中：当 `operator = OR` 时，表示至少应匹配的关键词个数，默认 `1`，`0` 按 `1` 处理；大于等于关键词个数时等效于 `AND`。在 `query_string` 中：当 `default_operator = OR` 时，表示至少应满足的组数（组由运算符与 `^` 权重划分），规则同上。说明嵌套在 `bool` 的 `should` 时，若存在 `must`/`filter` 且未写本参数，`should` 子句的默认行为仍可能为 `0`（可不满足任意 `should`），与全文子句内本参数的语义不同，需区分上下文。
	boost（可选）	查询权重，详见下方 boost 参数详细说明。
	type（可选）	`multi_match` / `query_string` 的匹配模式，支持 `best_fields`，表示取最大值、`most_fields`，表示求和，不支持 `cross_fields`、`phrase`；不指定时默认 `best_fields`。
	default_operator（可选）	仅 `query_string`。组与组之间、组内关键词之间的默认逻辑：`OR` 表示匹配任意组/词；`AND` 表示全部匹配。可选，默认 `OR`。
	operator（可选）	`match`、`multi_match` 的关键词间逻辑：`OR` 或 `AND`。可选，默认 `OR`。
knn（向量搜索）
	field	向量搜索列名。
	k	执行向量搜索返回行数。
	query_vector	指定搜索向量。
	filter（可选）	过滤条件。
	similarity（可选）	用于指定向量相似度计算的过滤条件。
	boost（可选）	查询权重，详见下方 boost 参数详细说明。
rank（RRF 排序策略）	rrf	RRF（Reciprocal Rank Fusion）排序策略，用于混合搜索时对多个查询结果进行融合排序。
	rank_window_size（可选）	该值用于指定每个查询所返回的单个结果集的大小。值越大，结果的相关性越高，但会带来性能开销。最终的排序结果集会被裁剪至搜索请求中指定的 `size` 大小。 rank_window_size 必须同时满足：大于或等于 `size` 参数大于或等于 1 默认值为 `size` 参数的值。
	rank_constant（可选）	该值用于控制每个查询所返回的单个结果集中各文档对最终排序结果的影响程度。值越大，表示排名靠后的文档对最终结果的影响越大。默认值为 60。

权重运算符说明

权重运算符 ^ 用于指定全文查询语句中列级别或者词元（Token）级别的权重，语法格式为 列名^权重 或 关键词^权重，例如 "title^2.0"。参数支持如下：

仅 multi_match 和 query_string 支持列级别权重。
仅 query_string 支持词元级别权重。

词元级别的权重运算符用于指定其左侧关键词（截至空格）的权重，无权重运算符对应的关键词的默认权重为 1.0。一个权重运算符对应的关键词或者连续的无权重运算符对应的关键词为一组。

{
  "query": {
    "query_string": {
      "fields": ["title^2.0", "content"],
      "query": "红心火龙果 果冻橙^1.5 秋月梨^1.2 蓝莓 山竹"
    }
  }
}

如上例所示，查询词元 "红心火龙果果冻橙^1.5 秋月梨^1.2 蓝莓山竹" 时，词元会分为四组，分别为：默认权重为 1.0 的红心、火龙果，指定权重为 1.5 的果冻、橙，指定权重为 1.2 的秋月、梨，默认权重为 1.0 的蓝莓、山竹。

权重运算符可以和 boost 参数同时使用，具体示例见下一小节 boost 参数详细说明。

boost 参数详细说明

boost 参数用于指定查询条件在最终相关性计算中的权重，值必须 ≥ 0，不指定时默认为 1。上述语法结构中，bool、single_term、单路和多路向量搜索（knn）都支持指定 boost 参数。结合本文限制，boost 的使用规则如下：

支持 boost 的表达式
- bool 查询。
- 全文查询（如 match、match_phrase、query_string、multi_match）。
- 向量查询（单路/多路 knn）。
不支持 boost 的表达式
- 标量查询：term / range / terms。
- JSON/ARRAY 标量表达式。
取值约束
- 非顶层全文查询的 boost、bool 查询的 boost、全文查询的列权重和词权重，要求大于 0。
- 其他情况的 boost 要求大于等于 0。

示例

a. 查询级别 boost（bool）：

{
  "bool": {
    "filter": [{"term": {"category": "Gaming"}}],
    "boost": 2.0
  }
}

b. 列级权重（query_string）：

{
  "query_string": {
    "fields": ["product_name^2.0", "description^1.0"],
    "query": "gaming keyboard",
    "boost": 1.5
  }
}

c. 向量查询 boost（knn）：

{
  "knn": {
    "field": "vector",
    "k": 5,
    "query_vector": "[1,2,3]",
    "boost": 1.5
  }
}

示例

全文搜索

本示例搜索 doc_table 表中 content 列包含 oceanbase mysql 的所有行，并返回符合结果的 4 条记录。

SELECT * FROM HYBRID_SEARCH(
  TABLE doc_table,
  '{
    "query": {
      "match": {"content": "oceanbase mysql"}
    }
  }'
);

预期返回结果如下：

+------+---------+---------------------------------+----------------------------------+--------------------+
| c1   | vector  | query                           | content                          | __score            |
+------+---------+---------------------------------+----------------------------------+--------------------+
|    2 | [1,2,1] | hello world, what is your name  | oceanbase mysql database         |  2.170969786679347 |
|    1 | [1,2,3] | hello world                     | oceanbase Elasticsearch database | 0.3503184713375797 |
|    3 | [1,1,1] | hello world, how are you        | oceanbase oracle database        | 0.3503184713375797 |
|    6 | [2,1,1] | hello world, where are you from | starrocks oceanbase database     | 0.3503184713375797 |
+------+---------+---------------------------------+----------------------------------+--------------------+
4 rows in set

全文与向量 RRF 混合搜索

创建示例表，其中包含一个向量列，并为其创建向量索引，以及分别为两个 VARCHAR 列创建全文索引。

CREATE TABLE doc_table(c1 INT, vector VECTOR(3), query VARCHAR(255), content VARCHAR(255), VECTOR INDEX idx1(vector) WITH (distance=l2, type=hnsw, lib=vsag), FULLTEXT INDEX idx2(query), FULLTEXT INDEX idx3(content));

写入数据。

INSERT INTO doc_table VALUES(1, '[1,2,3]', "hello world", "oceanbase Elasticsearch database"),
                            (2, '[1,2,1]', "hello world, what is your name", "oceanbase mysql database"),
                            (3, '[1,1,1]', "hello world, how are you", "oceanbase oracle database"),
                            (4, '[1,3,1]', "real world, where are you from", "postgres oracle database"),
                            (5, '[1,3,2]', "real world, how old are you", "redis oracle database"),
                            (6, '[2,1,1]', "hello world, where are you from", "starrocks oceanbase database");

SELECT * FROM HYBRID_SEARCH(
  TABLE doc_table,
  '{
    "query": {
      "match": {"content": "oceanbase mysql"}
    },
    "knn": {
      "field": "vector",
      "k": 5,
      "query_vector": "[1,2,3]"
    },
    "rank": {
      "rrf": {
        "rank_constant": 60,
        "rank_window_size": 10
      }
    }
  }'
);

预期返回结果如下：

+------+---------+---------------------------------+----------------------------------+----------------------+
| c1   | vector  | query                           | content                          | __score              |
+------+---------+---------------------------------+----------------------------------+----------------------+
|    1 | [1,2,3] | hello world                     | oceanbase Elasticsearch database |  0.03252247488101534 |
|    2 | [1,2,1] | hello world, what is your name  | oceanbase mysql database         | 0.032266458495966696 |
|    3 | [1,1,1] | hello world, how are you        | oceanbase oracle database        | 0.031754032258064516 |
|    5 | [1,3,2] | real world, how old are you     | redis oracle database            | 0.016129032258064516 |
|    6 | [2,1,1] | hello world, where are you from | starrocks oceanbase database     | 0.016129032258064516 |
|    4 | [1,3,1] | real world, where are you from  | postgres oracle database         |             0.015625 |
+------+---------+---------------------------------+----------------------------------+----------------------+
6 rows in set