---
title: "HYBRID_SEARCH - OceanBase Database AI V4.6.2 | OceanBase 文档中心"
description: HYBRID_SEARCH HYBRID_SEARCH 用于在一条 SELECT 语句中，通过符合本文档规则的 JSON 字符串描述全文搜索、向量搜索与过滤条件，并返回按融合策略排序后的行。 语法 SELECT select_expr_list FROM HYBRID_SEARCH(TABLE table_name,…
image: https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*OSPzQ6GUQF4AAAAAQHAAAAgAeiGDAQ/original
---
切换语言

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

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*inJjSpyNOjUAAAAAHtAAAAgAeiGDAQ/original) OceanBase Database AIV 4.6.2

# HYBRID_SEARCH

更新时间：2026-08-18 18:23:09

[编辑](https://github.com/oceanbase/oceanbase-database-ai/edit/V4.6.2/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 字符串描述全文搜索、向量搜索与过滤条件，并返回按融合策略排序后的行。

## 语法

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

-- select_expr_list 为 SELECT 列表
-- 除表列外，还可引用混搜伪列，具体见下文“伪列”小节

```

## 参数说明

| 参数 | 说明 |
| --- | --- |
| `table_name` | 目标表名。仅支持堆表（`ORGANIZATION = HEAP`），可为分区表或非分区表。 |
| `dsl_string` | JSON 字符串，描述 `query`、`knn`、`rank`、`rerank`、`aggs`、`collapse`、`sort`、`from`、`size`、`min_score` 等。 |

## 全局限制与说明

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

说明如下：

- 顶层 `query`（全文搜索）和 `knn`（向量搜索）加起来最多允许有三个子查询：`query` 算一个；`knn` 如果是对象算一个，如果是数组则每个元素各算一个。三者总数不得超过三个，并且至少要包含一个全文搜索或向量搜索。
 - 对于查询的列名，大小写不敏感。
 - 向量查询的 `query_vector`，推荐用字符串输入向量。
 - `min_score` 参数只有 SQL 接口支持，PL 接口不支持。
 - `query` 和每个 `knn` 都是相互独立的搜索路径，彼此的 `filter` 互不影响。如果某一路查询需要过滤条件，必须在该路径下单独指定对应的 `filter`。所有搜索结果会合并为一个结果集，并基于融合算法进行打分排序，最终返回前 `size` 条结果。
 - 任意查询可支持 `boost`，但不一定参与算分，具体规则请参见下文 `boost 参数详细说明` 小节。
 - `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 表达式 / 数组表达式，均支持 `boost`。置于顶层 `query`、`bool.must` / `bool.should` 时参与算分；置于 `bool.filter` / `bool.must_not` / `knn.filter` 时仅作硬过滤。具体规则请参见下文 `boost 参数详细说明` 小节。
 - 非顶层全文查询的 `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` 的全文索引列。
 - `sort` 与 `rank` 不支持同时指定；`aggs` 与 `sort` 不支持同时指定；`aggs` 与 `collapse` 不支持同时指定。
 - 支持 `SELECT count(*)` 查询，该查询的 SELECT 列表仅支持 `count(*)`，不支持与表列、`__score` 或聚合伪列混写。伪列说明见下文“伪列”小节；计数语义见“计数查询（`count(*)`）”小节。

## DSL_STRING 参数语法结构

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

#### 建议阅读顺序

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

### 语法说明

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

1. 可选参数表示

      - `[ ]` 在 BNF 中表示可选多个元素，如 `param_list = param [, param]*` 表示 `param_list` 可以包含 1 个或多个 `param`。
      - `rank_expression` 中 `[ ]` 也表示子参数可选。
      - `[, "boost" : boost_value]` 代表在支持 `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 参数骨架示例

下面的 `dsl_string` 骨架用于展示全部顶层字段的位置与形态：`query`（全文）、`knn`（向量）、`rank`（融合粗排）、`rerank`（模型精排）、`aggs`（聚合）、`collapse`（折叠）、`sort`（排序）、`from` / `size`（分页）、`min_score`（最低分，仅 SQL 接口）。实际请求中按需保留兼容的键即可；完整可运行示例见文末相关文档“混合搜索”。

#### 注意

本骨架仅为结构示意，不可整段直接执行。其中部分字段互斥，具体见上文“全局限制与说明”。

```sql
SELECT ...,
  '{
    "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
    },
    "aggs": {
      "my_terms_agg": {
        "terms": {
          "field": "category"
        }
      }
    },
    "collapse": {
      "field": "category"
    },
    "sort": [
      {
        "publish_time": {
          "order": "desc"
        }
      }
    ],
    "from": 0,
    "size": 10,
    "min_score": 0
  }'
);

```

#### 顶层参数结构

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

```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}
          | "aggs"      : {aggs_expression}
          | "collapse"  : {collapse_expression}
          | "sort"      : [sort_item_list]
          | "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
                    | "boost" : boost_value

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
                      [, "boost" : boost_value]

terms_query = "terms" : {terms_condition_list [, "boost" : boost_value]}
    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}
    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

```

`term` / `terms` 除支持标量列外，还支持单级数组列及 JSON 文档内的数组路径，具体如下：

| **查询** | **列类型** | **描述** |
| --- | --- | --- |
| `term` | 标量 | 等值匹配 |
| `term` | 单级数组 | 判断数组是否包含标量 |
| `term` | JSON 内数组 | 判断数组是否包含标量 |
| `terms` | 标量 | 字段值在参数列表中 |
| `terms` | 单级数组 | 判断参数数组与数组列有交集 |
| `terms` | JSON 内数组 | 判断参数数组与 JSON 数组有交集 |

限制说明如下：

- `term`/`terms` 当前仅支持单级数组。

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

用于定义单个词条中的全文查询表达式，包含 `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]"

```

##### 查询选项结构

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

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

rerank_params = "model" : "string_value"
              | "field" : "field_name"
              | "query" : "string_value"
              | "rank_window_size" : number
              | "type" : "string_value"

aggs_expression = "aggs" : {aggregation_bucket}
    aggregation_bucket = "agg_name" : {aggregation_body}
    aggregation_body = "terms" : {terms_condition_list}
                     | "cardinality" : {cardinality_condition_list}
    terms_condition_list = terms_condition [, terms_condition]*
    terms_condition = "field" : "field_name"
                    | "size" : number
                    | "min_doc_count" : number
                    | "order" : {"_count" : ("asc" | "desc")}
                    | "order" : {"_key" : ("asc" | "desc")}
    cardinality_condition_list = "field" : "field_name"

collapse_expression = "collapse" : {collapse_condition_list}
    collapse_condition_list = "field" : "field_name"

sort_item_list = sort_item [, sort_item]*
    sort_item = "field_name"
              | "__score"
              | {"field_name" : {sort_condition_list}}
    sort_condition_list = sort_condition [, sort_condition]*
    sort_condition = "order" : ("asc" | "desc")
                   | "missing" : ("_first" | "_last" | number)
    weighted_sum_params = "rank_window_size" : number [, "normalizer" : ("minmax" | "none")]

```

单路向量搜索时，`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` 参数同时使用。可设置查询选项。 |
| knn | 进行单路/多路向量搜索时可单独使用，混合搜索时可以与 `query` 参数同时使用。 |
| rank（可选） | 多路召回结果的融合粗排策略，支持 `rrf`、`weighted_sum`（含 `normalizer` 等）参数，未指定时按默认融合策略（`rrf`）处理。 |
| rerank（可选） | 在粗排之后，通过 AI Rerank 模型对候选文档精排。须配合 `query` 或 `knn` 使用，参数见下文详细参数说明中的 `rerank`（精排）。 |
| aggs（可选） | 用于指定聚合统计。当前仅支持单聚合，聚合类型支持 `terms` 与 `cardinality`。 |
| collapse（可选） | 通过指定字段对搜索结果进行分组，每组仅保留排序最佳的一条记录。 |
| sort（可选） | 用于指定排序键，支持单字段或多字段排序，未指定时默认按融合分数（`__score`）排序。 |
| 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 参数详细说明。 |
| 标量查询（scalar_term） | range | 范围搜索，搭配 `gte`、`gt`、`lte`、`lt` 使用，`fieldname` 必选。置于 `bool.must`/`should` 或顶层 `query` 时支持 `boost` 算分（满足时计 1 分 × 级联 `boost`）；置于 `filter`/`must_not` 或 `knn.filter` 时不参与算分。 |
| term | 精准匹配。支持简写 `{"field": value}` 或带 `boost` 的对象形式 `{"field": {"value": ..., "boost": ...}}`。算分规则同 `range`。 |
| terms | 多值精准匹配。可在 `terms` 对象上指定 `boost`。算分规则同 `range`。 |
| 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`。 |
| 全文查询（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） |
| query_dop（可选） | 用于配置混搜 `query` 召回路径的分区内并行执行；**仅支持全文/标量路径的并行（不支持向量路径并行）**。每个 `query` 召回路径仅可设置一个 `query_dop`，类型为整数，取值范围 `[1, 128]`，默认 `1`。`1` 表示路径内不并行；大于 `1` 时按数据范围切分后并行扫描。超出取值范围会在 JSON 解析阶段报错。仅在混搜并行执行开启时生效。可配合查询 Hint 使用，具体方式请参见文末相关文档 [混合搜索](../../../../../../400.ai-search/550.hybrid-search.md) 中的并行执行说明。 |
| 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” 说明。 |
| 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（精排） | 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 模型）。 |
| aggs（聚合） | agg_name | 聚合桶名称（用户自定义键名）。在 `terms` 场景下可在 `SELECT` 列表中直接引用该名称，表示对应分组计数；在 `cardinality` 场景下表示去重计数。 |
| terms | 按字段分组并统计每组文档数。支持参数：`field`（必选），表示分组字段名；`size`（可选，默认 10），表示每个分组返回的文档数，INT 类型，取值范围为 [1, INT32_MAX]；`min_doc_count`（可选，默认 1），表示每个分组的最小文档数，INT 类型，取值范围为 [1, INT32_MAX]；`order`（可选，默认 `{"_count":"desc"}`）表示按文档数或字段值排序，取值范围为 `{"_count":"asc\|desc"}` 或 `{"_key":"asc\|desc"}`。 |
| cardinality | 按字段做去重计数。支持参数：`field`（必选），表示去重字段名。 |
| field | `terms`/`cardinality` 的统计字段名。当前不支持全文索引列、向量列及 LOB/JSON/Geometry 类型。NULL 值不计入统计。 |
| order（可选） | 仅 `terms` 支持。可配置 `{"_count":"asc\|desc"}` 或 `{"_key":"asc\|desc"}`。当按 `_count` 排序且计数相同，按 `_key` 升序作为次序。 |
| collapse（折叠） | field | 折叠字段名（必选）。按该字段分组，每组仅保留排序最优的一条记录。当前不支持全文索引列、向量列及 LOB/JSON/Geometry 类型；不支持 `__score`。NULL 值独立成组。可与 `sort` 同时使用，未指定 `sort` 时按 `__score` 降序折叠；`size` 在折叠之后裁剪。 |
| sort（排序） | sort | 排序键列表，按数组顺序生效。支持对象形式（如 `{"price":{"order":"desc"}}`）和简写形式（如 `"price"`，等价于按该字段升序）。 |
| field_name | 排序字段名。支持普通列与伪列 `__score`。 |
| order（可选） | 排序方向，支持 `asc`、`desc`，默认 `asc`。 |
| missing（可选） | 控制 NULL 值排序位置。支持 `"_first"`、`"_last"` 或具体数值（将 NULL 替换为该值参与排序）。默认 `"_last"`。 |

#### 权重运算符说明

权重运算符 `^` 用于指定**全文查询**语句中**列级别**或者**词元（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` 参数用于指定查询条件在最终相关性计算中的权重。标量条件满足时计 1 分，再乘以级联的 `boost`。不指定时默认为 `1`。级联指的是 `boost` 参数在参与算分时采用嵌套层级相乘的方式进行计算，例如 `bool.boost × 子查询 boost`。

1. 支持 `boost` 的表达式

      - `bool` 查询。
      - 全文查询（如 `match`、`match_phrase`、`query_string`、`multi_match`）。
      - 向量查询（单路/多路 `knn`）。
      - 标量查询：`term` / `range` / `terms` / `wildcard`。
      - JSON/ARRAY 标量表达式。
 2. 是否参与算分

   | **查询位置** | **是否计入 `__score`** |
   | --- | --- |
   | 顶层 `query` 子句 | 是 |
   | `bool.must`、`bool.should` | 是（仅当其外层参与算分时才计入，如 `bool.filter.bool.must` 中，内层 `must` 并不计分） |
   | `bool.filter`、`bool.must_not` | 否 |
   | `knn.filter` | 否 |
   | 嵌套在 `filter`/`must_not` 内的 `bool` | 否（该 `bool` 及其子查询均不算分） |
 3. 取值约束

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

   a. 标量 `range` 带 `boost`：

   ```shell
   {
     "range": {
       "c1": {
         "gt": 1,
         "boost": 2.1
       }
     }
   }

   ```

   b. 标量 `term` 带 `boost`：

   ```shell
   -- 简写，默认 boost 为 1
   {
     "term": {
       "c1": 1
     }
   }

   ```

   ```shell
   -- 对象形式
   {
     "term": {
       "c1": {
         "value": 1,
         "boost": 2.35
       }
     }
   }

   ```

   c. 标量 `terms` 带 `boost`：

   ```shell
   {
     "terms": {
       "c1": [1, 3, 5],
       "boost": 3.14
     }
   }

   ```

   d. `wildcard` 带 `boost`：

   ```shell
   -- 简写，默认 boost 为 1
   {
     "wildcard": {
       "content": "*ocea*"
     }
   }

   ```

   ```shell
   -- 对象形式
   {
     "wildcard": {
       "content": {
         "value": "*ocea*",
         "boost": 1.8
       }
     }
   }

   ```

   e. JSON/单级数组表达式带 `boost`：

   ```shell
   {
     "json_contains": {
       "meta_json": {
         "candidate": "\"mysql\"",
         "path": "$.tags",
         "boost": 3.14
       }
     }
   }

   ```

   ```shell
   {
     "array_contains": {
       "tag_array1": {
         "arg": "ios",
         "boost": 2.1
       }
     }
   }

   ```

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

   ```shell
   {
     "bool": {
       "must": [{"range": {"c1": {"gt": 1, "boost": 2.1}}}],
       "boost": 9.131
     }
   }

   ```

   上述示例中，`must` 内 `range` 满足时得分 = 1 × 2.1 × 9.131。

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

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

   ```

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

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

   ```

   `knn` 本身参与算分；`knn.filter` 内的标量条件不参与算分。

#### num_candidates 与 ef_search

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

`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` 标量查询的补充信息，包含使用位置、索引能力等。

支持的使用位置：

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

索引能力如下：

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

#### 聚合伪列

`HYBRID_SEARCH` 在 `SELECT` 列表中提供下列伪列。伪列仅在混搜语法中有效，不属于 MySQL 通用 `SELECT` 表达式。

| **伪列名** | **含义** | **可用场景** |
| --- | --- | --- |
| `__score` | 各路搜索结果融合后的最终评分 | 返回行的混搜查询中均可引用 |
| `agg_name` | 聚合桶计数值（名称与 `aggs` 中自定义的桶键名一致） | 仅在 `dsl_string` 中声明了同名 `aggs` 时可用 |

对 `terms` 聚合，伪列 `agg_name` 返回该分组键对应的文档数（等价于 `COUNT(*)`）；对 `cardinality` 聚合，伪列 `agg_name` 返回该字段的去重计数（等价于 `COUNT(DISTINCT field)`）。也可在 `SELECT` 中写 `COUNT(DISTINCT field)`，但 `field` 必须与 `cardinality.field` 一致。

#### 计数查询（`count(*)`）

`SELECT count(*)` 用于统计各路搜索结果的并集文档总数；单路搜索返回该路径索引命中数，多路搜索对行键并集去重后计数。计数在索引层完成，不算分、不回主表。

`size`、`from`、`sort`、`aggs`、`collapse` 不影响计数结果；`min_score` 会影响。当同时指定 `rank` 且 `min_score > 0` 时，仅融合窗口内且分数达标的文档参与计数。

下列示例设置 `"size": 1`，但 `count(*)` 仍返回全文命中的真实总数，而非 1：

```sql
SELECT count(*)
FROM HYBRID_SEARCH(
  TABLE doc_table,
  '{
    "query": {
      "match": {"content": "oceanbase"}
    },
    "size": 1
  }'
);

```

## 示例

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

### 同时设置 `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*"}}
}');

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

-- 作为 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*"}}]
  }
}');

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

```

## 相关文档

- 本语法对应功能说明和场景化示例参见 [混合搜索](https://www.oceanbase.com/docs/common-oceanbase-database-ai-1000000006779052)

 上一篇 下一篇 ![有帮助](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) 咨询热线