---
title: "HYBRID_SEARCH - OceanBase 数据库 V4.6.0 | OceanBase 文档中心"
description: HYBRID_SEARCH HYBRID_SEARCH 用于在一条 SELECT 语句中，通过符合本文档规则的 JSON 字符串描述全文搜索、向量搜索与过滤条件，并返回按融合策略排序后的行。 注意 本语法仅适用于 MySQL 模式。 语法 SELECT select_expr_list FROM HYBRID_SEA…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.6.0

# HYBRID_SEARCH

更新时间：2026-08-05 14:51:35

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.6.0/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/600.sql-statement-of-mysql-mode/8100.select-of-mysql-mode/500.hybrid-search-of-mysql-mode.md)  

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

#### 注意

本语法仅适用于 MySQL 模式。

## 语法

```sql
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`、`rerank`、`from`、`size`、`min_score` 等。   #### 注意    除下文“限制和说明”中列出的差异外，其余语法结构及参数说明与 [SEARCH](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686448) 的 `search_params` 一致，已了解 `SEARCH` 语法结构的用户直接了解两者差异即可。 |

## 全局限制与说明

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

说明如下：

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

限制如下：

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

  ```sql
  -- 不支持：与 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` / `wildcard` / JSON 表达式 / 数组表达式。其中 `wildcard` 支持在顶层 `query`、`bool.must` / `bool.should` 中参与算分；置于 `bool.filter` / `bool.must_not` / `knn.filter` 时仅作硬过滤。其他标量查询条件不参与算分，不支持 `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，巴科斯范式）语法符号的含义和使用规则：

1. 可选参数表示

      - `[ ]` 在 BNF 中表示可选多个元素，如 `param_list = param [, param]*` 表示 `param_list` 可以包含 1 个或多个 `param`。
      - `rank_expression` 中 `[ ]` 也表示子参数可选。
      - `[, "boost" : boost_value]` 代表在支持 `boost` 的表达式中该子参数可选；`term` / `range` / `terms` 及 JSON/ARRAY 标量表达式不支持 `boost`。
 2. 数组表示

      - `[ ]` 在 JSON 结构中表示数组，如 `[condition_list]`。
 3. 选择关系

      - `|` 表示选择关系，如 `param = "query" | "knn"` 表示 param 可以是 "query" 或 "knn"。
 4. 重复表示

      - `*` 表示 0 次或多次重复，如 `param_list = param [, param]*` 表示 `param_list` 可以包含 1 个或多个 `param`。
 5. JSON 格式要求

      - 所有 JSON 列名和字符串值都需要用双引号包围。
      - 数值不需要用双引号包围。

### 语法定义

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

#### DSL_STRING 参数骨架示例

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

```sql
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
      }
    },
    "rerank": {
      "model": "rerank_model",
      "field": "content",
      "query": "oceanbase mysql",
      "rank_window_size": 10
    },
    "from": 0,
    "size": 10
  }'
);

```

#### 顶层参数结构

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

```sql
dsl_string = '{param_list}'
    param_list = param [, param]*
    -- query 和 knn 至少必选一个；混合搜索时可同时使用
    param = "query"     : {query_expression | search_options} --包含查询表达式或查询选项
          | "knn"       : {knn_expression}
          | "rank"      : {rank_expression}
          | "rerank"    : {rerank_params} -- 从 V4.6.0 BP1 版本开始支持
          | "from"      : number
          | "size"      : number
          | "min_score" : number -- 仅 SQL 接口支持

```

##### 查询表达式结构

查询表达式结构用于指定混合搜索中的全文、标量查询条件，并支持配置查询选项。

```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` 对象的内层片段示例：

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

```

###### 标量查询结构

用于定义单个词条中的标量查询表达式，包含 `range_query`、`term_query`、`terms_query`、`wildcard_query`，表示范围查询、精准匹配、多值匹配、通配符匹配。

```sql
scalar_term = range_query | term_query | terms_query | wildcard_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]*

wildcard_query = "wildcard" : {wildcard_condition_list} -- 从 V4.6.0 BP1 版本开始支持
    wildcard_condition_list = wildcard_condition [, wildcard_condition]*
    wildcard_condition = "field_name" : wildcard_pattern
                       | "field_name" : {wildcard_value_object}
    wildcard_pattern = "string_value" | number | boolean
    wildcard_value_object = wildcard_value_body [, "boost" : boost_value]
    wildcard_value_body = "value" : wildcard_pattern
                       | "wildcard" : wildcard_pattern

```

###### 全文查询结构

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

```sql
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]"

```

##### 查询选项结构

#### 说明

查询选项结构从 V4.6.0 BP1 版本开始支持。

用于配置如分区内并行查询等查询选项。

```sql
search_options = "search_options" : {search_options_body}
    search_options_body = "query_dop" : number

```

```json
{
  "query": {
    "search_options": {"query_dop": 4},
    "match": {"content": "oceanbase mysql"}
  }
}

```

##### 向量与排序结构

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

```sql
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]
                 | "num_candidates"  : number -- 从 V4.6.0 BP1 版本开始支持
                 | "search_options"  : {search_option_list}
                 | "filter"          : [condition_list]
                 | "similarity"      : number
                 | "boost"           : boost_value
    search_option_list = search_option [, search_option]*
    search_option = "ef_search"    : number
                 | "refine_k"      : number
                 | "filter_mode"   : ("pre" | "pre-knn" | "pre-brute" | "post" | "post-index-merge")
    multi_knn_condition_list = {knn_condition} [, {knn_condition}]*
    vector_values = float [, float]*

rank_expression = "rank" : {rank_strategy}
    rank_strategy = "rrf" : {rrf_params}
                  | "weighted_sum" : {weighted_sum_params}
    rrf_params = "rank_window_size" : number [, "rank_constant" : number]
    weighted_sum_params = "rank_window_size" : number [, "normalizer" : ("minmax" | "none")]

-- 从 V4.6.0 BP1 版本开始支持
rerank_params = "model" : "string_value"
              | "field" : "field_name"
              | "query" : "string_value"
              | "rank_window_size" : number
              | "type" : "string_value"

```

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

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

```

#### 基础类型定义

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

```sql
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` 参数同时使用。可设置查询选项，查询选项从 V4.6.0 BP1 版本开始支持。 |
| knn | 进行单路/多路向量搜索时可单独使用，混合搜索时可以与 `query` 参数同时使用。 |
| rank（可选） | 多路召回结果的融合粗排策略，支持 `rrf`、`weighted_sum`（含 `normalizer` 等）参数，未指定时按默认融合策略（`rrf`）处理。 |
| rerank（可选）   #### 注意    该参数从 V4.6.0 BP1 版本开始支持。 | 在粗排之后，通过 AI Rerank 模型对候选文档精排。须配合 `query` 或 `knn` 使用，参数见下文 “Rerank 精排” 小节。 |
| from（可选） | 用于指定从搜索结果集的第几行返回结果，不指定则默认从第 1 行返回，需要和 `size` 参数一起使用。 |
| size（可选） | 用于限制返回结果条数，不指定则默认为 `10`。与 `rerank.rank_window_size`、`rank` 的窗口参数须满足 `size` ≤ `rerank.rank_window_size` ≤ `rank`。不指定 `size` 时，按照 `size` = `rerank.rank_window_size` 处理。 |
| 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 使用。`field_name` 必选。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。 |
| term | 精准匹配，支持字符串、数字、布尔值等标量值，转换成 sql 的 '=' 表达式。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。 |
| terms | 对指定集合中的任意一个值精准匹配，支持字符串、数字、布尔值等标量值的数组，转换成 sql 的 'IN' 表达式。该类标量查询不参与算分，不支持 `boost`，且不支持放在 `bool` 的 `must`/`should` 中。 |
| wildcard | 支持通配符模糊搜索，相当于在 SQL 中使用 `LIKE ... ESCAPE '\\'` 子句。   `*` 表示任意多个字符（等同于 SQL 的 `%`），`?` 表示任意单个字符（等同于 SQL 的 `_`）。   使用方式有三种：直接写通配符字符串（例如 `{"wildcard": {"title": "ab*cd?"}}`）、用 `value` 字段（例如 `{"wildcard": {"title": {"value": "ab*cd?", "boost": 0.5}}}`）、或用 `wildcard` 字段（例如 `{"wildcard": {"title": {"wildcard": "ab*cd?", "boost": 0.5}}}`）。`value` 和 `wildcard` 只能二选一，不能同时使用，错误示例如 `{"wildcard": {"title": {"value": "abc", "wildcard": "cbd"}}}`。不支持 case_insensitive、rewrite、_name 参数。   支持 `boost`。   #### 说明    本功能从 V4.6.0 BP1 开始支持。 |
| 全文查询（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`。 |
| 查询选项（search_options）   #### 说明    从 V4.6.0 BP1 版本开始支持。 |
| query_dop（可选） | 用于配置混搜 `query` 召回路径的分区内并行执行；**仅支持全文/标量路径的并行（不支持向量路径并行）**。每个 `query` 召回路径仅可设置一个 `query_dop`，类型为整数，取值范围 `[1, 128]`，默认 `1`。`1` 表示路径内不并行；大于 `1` 时按数据范围切分后并行扫描。超出取值范围会在 JSON 解析阶段报错。仅在混搜并行执行开启时生效。可配合查询 Hint 使用，具体方式请参见文末相关文档“索引混合搜索（SQL 接口）”中的并行执行说明。 |
| knn（向量搜索） |
| field | 向量搜索列名。 |
| k | 最终返回的近邻结果数，取值范围 `[1, 16384]`。 |
| query_vector | 指定搜索向量。 |
| num_candidates（可选） | 指定向量搜索时的候选集数量，等同于 `ef_search`。整数类型，取值范围为 `[1, 10000]`（不在范围内会报错）。当 `filter_mode` 为 `post` 或 `post-index-merge` 时，该参数作为初始预算而非绝对上限。与 `ef_search` 同时设置时优先级和详细示例参见下文 “num_candidates 与 ef_search” 说明。   #### 说明    本功能从 V4.6.0 BP1 开始支持。 |
| search_options（可选） | 向量搜索高级选项，包含 `ef_search`、`refine_k`、`filter_mode` 等子键。`ef_search` 类型为整数，取值范围为 `[1, 10000]`。`refine_k` 用于调整量化向量索引的重排比例，类型为浮点数，取值范围为 `[1.0, 1000.0]`。与 `num_candidates` 同时设置时仍可生效。`filter_mode` 用于控制带过滤条件的向量查询执行路径，类型为字符串；取值与含义参见下文 “filter_mode” 说明。执行计划中可能以数值形式打印（如 `filter_mode=0`）。 |
| filter（可选） | 向量分支内的过滤条件，可包含标量表达式（含 `wildcard`）。 |
| similarity（可选） | 用于指定向量相似度计算的过滤条件。 |
| boost（可选） | 查询权重，详见下方 boost 参数详细说明。 |
| rank（粗排） | rrf | RRF（Reciprocal Rank Fusion）排序策略，用于混合搜索时对多个查询结果进行融合排序。 |
| rank_window_size（可选） | 该值用于指定每个查询所返回的单个结果集的大小。值越大，结果的相关性越高，但会带来性能开销。最终的排序结果集会被裁剪至搜索请求中指定的 `size` 大小。      rank_window_size 必须同时满足：   - 大于或等于 `size` 参数 - 大于或等于 1  默认值为 `size` 参数的值。 |
| rank_constant（可选） | 该值用于控制每个查询所返回的单个结果集中各文档对最终排序结果的影响程度。值越大，表示排名靠后的文档对最终结果的影响越大。默认值为 60。 |
| rerank（精排）   #### 注意    该参数从 V4.6.0 BP1 版本开始支持。 | model | 必填。Rerank 模型名称。支持 `provider/model` 格式（如 `aliyun-dashscope/gte-rerank-v2`，须先通过 `REGISTER_PROVIDER` 注册供应商。 |
| field | 必填。参与精排的文本列名，列须存在于查询表中，类型为 `CHAR`、`VARCHAR` 或 `TEXT`。 |
| query | 必填。用于与文档文本比较相关性的查询字符串。 |
| rank_window_size（可选） | 参与精排的候选文档数，取值范围 `[0, 10000]`，默认 `10`。须满足 `rank_window_size` ≥ `size`；若同时指定 `rank`，还须 <=`rank.rank_window_size`。 |
| type（可选） | 精排实现类型，默认 `model`（调用外部 Rerank 模型）。 |

#### 权重运算符说明

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

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

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

```shell
{
  "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` 的使用规则如下：

1. 支持 `boost` 的表达式

      - `bool` 查询。
      - 全文查询（如 `match`、`match_phrase`、`query_string`、`multi_match`）。
      - 向量查询（单路/多路 `knn`）。
      - 标量查询：`wildcard` 查询。
 2. 不支持 `boost` 的表达式

      - 标量查询：`term` / `range` / `terms`。
      - JSON/ARRAY 标量表达式。
 3. 取值约束

      - 非顶层全文查询的 `boost`、`bool` 查询的 `boost`、全文查询的列权重和词权重，要求大于 `0`。
      - 其他情况的 `boost` 要求大于等于 `0`。
 4. 示例

   a. 查询级别 `boost`（`bool`）：

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

   ```

   b. 列级权重（`query_string`）：

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

   ```

   c. 向量查询 `boost`（`knn`）：

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

   ```

#### num_candidates 与 ef_search

本小节介绍 `num_candidates` 与 `ef_search` 的优先级说明。

#### 说明

`num_candidates` 从 V4.6.0 BP1 版本开始支持。

`num_candidates` 与 `ef_search` 的优先级如下：

| 设置情况 | 生效行为 |
| --- | --- |
| 仅设置 `num_candidates` | 生效，且 `ef_search = num_candidates` |
| 仅设置 `search_options.ef_search` | 按照 `ef_search` |
| 同时设置 `num_candidates` 与 `search_options.ef_search` | `num_candidates` 优先，最终 `ef_search` 等于 `num_candidates` |
| 都不设置 | 保持默认 `ef_search` 的系统参数/会话参数 |

#### filter_mode

`filter_mode` 是 `search_options` 中的参数，用于控制带过滤条件的向量查询的执行路径。取值如下：

| 取值 | 含义 |
| --- | --- |
| `pre` | 前过滤自适应 |
| `pre-knn` | 前过滤 + knn |
| `pre-brute` | 前过滤 + 暴搜 |
| `post` | 基于表达式的迭代式过滤 |
| `post-index-merge` | 基于 index-merge 框架的迭代式过滤 |

#### wildcard 标量查询

本小节介绍 `wildcard` 标量查询的补充信息，包含使用位置、索引能力等。

#### 说明

本功能从 V4.6.0 BP1 版本开始支持。

支持的使用位置：

- 顶层 `query` 中
 - `bool.must` 中
 - `bool.should` 中
 - `bool.filter` 中
 - `bool.must_not` 中
 - `knn.filter` 中（语义与 `bool.filter` 一致）

索引能力如下：

| 索引类型 | 是否支持 |
| --- | --- |
| VARCHAR 列上的普通索引 | 支持（非精确查询中 `LIKE` 可走索引） |
| 前缀索引 | 不支持 |
| 全文索引 | 不支持 |
| JSON SEARCH INDEX | 不支持 |
| JSON CAST 索引 | 不支持 |

## 示例

这里给出一些复杂语法的示例供参考。

### 全文与向量 RRF 混合搜索

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

```sql
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));

```

写入数据。

```sql
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");

```

```sql
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
      }
    }
  }'
);

```

预期返回结果如下：

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

```

### 同时设置 `num_candidates` 与 `ef_search`

本示例展示了同时设置 `num_candidates` 与 `ef_search`：

```sql
-- 同时设置 num_candidates 与 search_options.ef_search：num_candidates 优先
SELECT c1 FROM HYBRID_SEARCH(TABLE doc_table, '{
  "knn": {
    "field": "vector",
    "k": 10,
    "num_candidates": 2000,
    "query_vector": "[0.712338,0.603321,0.133444]",
    "search_options": {
      "ef_search": 101,
      "refine_k": 5.6,
      "filter_mode": "pre"
    }
  }
}');

```

### 模糊匹配示例

本示例展示了 `wildcard` 标量查询的常用场景，包括普通列前缀匹配、JSON 路径匹配、作为 `knn.filter` 中的过滤条件、`bool.must` / `bool.should` 组合过滤：

```sql
-- 普通列前缀匹配
SELECT * FROM HYBRID_SEARCH(TABLE doc_table, '{
  "query": {"wildcard": {"title": "prefix*"}}
}');

```

```sql
-- JSON 路径
SELECT * FROM HYBRID_SEARCH(TABLE doc_table, '{
  "query": {"wildcard": {"doc_json.name": "alpha*"}}
}');

```

```sql
-- 作为 knn.filter
SELECT * FROM HYBRID_SEARCH(TABLE doc_table, '{
  "knn": {
    "field": "vector_col",
    "k": 1,
    "query_vector": "[0.1,0.1,0.1,0.1]",
    "filter": [{"wildcard": {"doc_json.name": "alpha*"}}]
  }
}');

```

```sql
-- bool.must / should 组合
SELECT * FROM HYBRID_SEARCH(TABLE doc_table, '{
  "query": {
    "bool": {
      "must": [
        {"term": {"store_id": "20000"}},
        {"bool": {
          "should": [
            {"wildcard": {"phone": "*1399*"}},
            {"wildcard": {"order_no": "*2024061*"}}
          ],
          "minimum_should_match": 1
        }}
      ]
    }
  }
}');

```

## 相关文档

- 本语法对应功能说明和场景化示例参见[索引混合搜索（SQL 接口）](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005682104)

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线