Row 操作

更新时间：2026-09-01

使用前准备

Row 操作通过 Table 对象发起。以下示例中的 db_test、table_test、字段和索引需要已经创建，并与示例中的类型一致。

初始化客户端并获取表对象：

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

account = "root"
api_key = "您的账户 API 密钥"
endpoint = "您的实例访问端点"  # 例如：http://127.0.0.1:8511

config = Configuration(
    credentials=BceCredentials(account, api_key),
    endpoint=endpoint,
)
client = pymochow.MochowClient(config)
database = client.database("db_test")
table = database.table("table_test")
            

SDK 将响应 JSON 的驼峰字段转换为 Python 下划线属性，例如 nextMarker、isTruncated、vectorIndexMembership 分别通过 response.next_marker、response.is_truncated、response.vector_index_membership 读取。

插入记录

功能介绍

Table.insert 将一条或一批记录插入表中。记录主键已经存在时请求失败；批量插入不保证批次原子性。协议限制单批最多 1000 条。

请求示例

下面是包含客户端初始化的完整示例。Row 会把 FloatVector、BinaryVector 和 SparseFloatVector 转换为协议表示。

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.table import FloatVector, Row, SparseFloatVector

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

rows = [
    Row(
        id="00001",
        book_name="三国演义",
        page=25,
        content="吕布字奉先",
        vector=FloatVector([0.3123, 0.43, 0.213]),
        sparse_vector=SparseFloatVector([[1, 0.56], [100, 0.23]]),
    ),
    Row(
        id="00002",
        book_name="三国演义",
        page=30,
        content="关羽字云长",
        vector=FloatVector([0.1223, 0.53, 0.313]),
        sparse_vector=SparseFloatVector.from_dict({2: 0.66, 200: 0.33}),
    ),
]
response = table.insert(rows=rows)
print(response)
            

二进制向量可以用 Base64 字符串构造，也可以从只包含 0、1 的列表构造：

                Python
                
                from pymochow.model.table import BinaryVector, Row

binary_vector = BinaryVector.from_binary_list([0, 1, 0, 1, 1, 0, 0, 1])
row = Row(id="binary-001", binary_vector=binary_vector)

请求参数

参数	类型	是否必填	说明
`rows`	`List[Row]`	是	待插入记录列表。`Row(**kwargs)` 的字段名和值必须符合表 Schema。
`config`	`Configuration`	否	本次请求配置；未传时使用表对象继承的配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`affected_count`	`int`	写入成功的记录数，对应协议字段 `affectedCount`。

插入或更新记录

功能介绍

Table.upsert 根据主键插入或覆盖记录：主键不存在时插入，存在时更新。批量 Upsert 不保证批次原子性，协议限制单批最多 1000 条。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.table import FloatVector, Row

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

response = table.upsert(
    rows=[
        Row(
            id="00001",
            book_name="三国演义",
            page=26,
            content="吕布字奉先",
            vector=FloatVector([0.3123, 0.43, 0.213]),
        )
    ]
)
print(response)
            

请求参数

参数	类型	是否必填	说明
`rows`	`List[Row]`	是	待插入或覆盖的记录。
`config`	`Configuration`	否	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`affected_count`	`int`	写入成功的记录数，对应协议字段 `affectedCount`。

更新记录

功能介绍

Table.update 按主键更新指定字段，不允许更新主键和分区键。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

response = table.update(
    primary_key={"id": "00001"},
    partition_key={"user_id": "user-01"},
    update_fields={"page": 27, "content": "吕布，字奉先"},
)
print(response)
            

请求参数

参数	类型	是否必填	说明
`primary_key`	`dict`	是	目标记录主键。
`partition_key`	`dict`	否	目标记录分区键；分区键与主键相同时无需填写。
`update_fields`	`dict`	是	字段名到新值的映射，支持标量字段和向量字段，不允许包含主键或分区键。
`config`	`Configuration`	否	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。

删除记录

功能介绍

Table.delete 支持按主键删除或按过滤条件删除，两种方式有且只能选择一种。按过滤条件删除全部记录时可使用 filter="*"。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

# 按主键删除。
response = table.delete(
    primary_key={"id": "00001"},
    partition_key={"user_id": "user-01"},
)
print(response)

# 按过滤条件删除。不能同时传 primary_key 或 partition_key。
response = table.delete(filter="book_name = '三国演义' AND page > 100")
print(response)
            

请求参数

参数	类型	是否必填	说明
`primary_key`	`dict`	条件必填	与 `filter` 二选一。
`partition_key`	`dict`	否	仅随 `primary_key` 使用，不能与 `filter` 同时出现。
`filter`	`str`	条件必填	与 `primary_key` 二选一；`"*"` 表示删除全部记录。
`config`	`Configuration`	否	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。

标量查询

功能介绍

Table.query 按主键查询单条记录。默认不返回向量字段，读取一致性默认为 EVENTUAL。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

response = table.query(
    primary_key={"id": "00001"},
    partition_key={"user_id": "user-01"},
    projections=["id", "book_name", "page", "vector"],
    retrieve_vector=True,
    read_consistency=ReadConsistency.STRONG,
    vector_index_membership="book_vector_idx",
)
print(response.row)
print(response.vector_index_membership.state)
            

vector_index_membership 既可以直接传索引名，也可以传协议对象：

                Python
                
                response = table.query(
    primary_key={"id": "00001"},
    vector_index_membership={"indexName": "book_vector_idx"},
)

请求参数

参数	类型	是否必填	默认值	说明
`primary_key`	`dict`	是	无	目标记录主键。
`partition_key`	`dict`	否	`None`	目标记录分区键。
`projections`	`List[str]`	否	`None`	投影字段；不传时返回所有标量字段。
`retrieve_vector`	`bool`	否	`False`	是否返回向量字段。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	`EVENTUAL` 随机访问分片副本；`STRONG` 访问主副本。
`vector_index_membership`	`str` 或 `dict`	否	`None`	指定待检查的向量索引；仅单行 Query 支持。
`config`	`Configuration`	否	`None`	本次请求配置。

VectorIndexMembership

vector_index_membership 返回当前行版本相对于本次请求实际访问副本上 serving 索引的逻辑覆盖状态：

`state`	说明
`ROW_NOT_FOUND`	当前查询读视图中不存在该主键对应的逻辑行；此时 `row` 为空对象。
`NO_VECTOR`	行存在，但索引对应的向量列未产生可索引向量，例如字段不存在、为 `null`、向量数组为空、向量 Map 为空或 Map 中向量数组均为空。
`KNN`	当前行版本未被 serving stable/delta index 覆盖，逻辑上归入 KNN 路径。
`DELTA_INDEX`	当前行版本位于最近 complete generation 的 delta layer，且 serving delta index 已存在。
`STABLE_INDEX`	当前行版本位于最近 complete generation 的 stable layer，且 serving stable index 已存在。

使用时注意：

仅 query 单行查询支持，batch_query 不支持。
该能力不执行 ANN 检索，也不检查行的 VID 是否真实存在于底层索引文件，不能用于判断索引文件损坏或漏点。
返回的是逻辑覆盖状态。索引重建期间旧 stable index 仍在 serving 时，结果仍基于旧 serving index；不能把它解释为新索引的重建进度。
EVENTUAL 会随机访问副本。各副本的 compaction 和索引构建进度可能不同，同一主键的连续查询可能出现不同瞬态状态；需要主副本视图时使用 ReadConsistency.STRONG。
indexName 必须是当前表中已存在的非空索引名。协议支持以 FLOAT_VECTOR 为目标列的稠密向量索引和 FEDERATED 索引及合法向量复合形态，不支持稀疏、二进制向量索引。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`row`	`Row`	查询到的一行记录；记录不存在时为空对象。
`vector_index_membership`	动态对象	仅请求 Membership 时返回，其 `state` 属性为上述五种状态之一。

批量标量查询

功能介绍

Table.batch_query 一次按多个主键查询记录。每个键使用 BatchQueryKey 表示。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency
from pymochow.model.table import BatchQueryKey

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

response = table.batch_query(
    keys=[
        BatchQueryKey(
            primary_key={"id": "00001"},
            partition_key={"user_id": "user-01"},
        ),
        BatchQueryKey(
            primary_key={"id": "00002"},
            partition_key={"user_id": "user-01"},
        ),
    ],
    projections=["id", "book_name", "vector"],
    retrieve_vector=True,
    read_consistency=ReadConsistency.EVENTUAL,
)
print(response.rows)
            

请求参数

参数	类型	是否必填	默认值	说明
`keys`	`List[BatchQueryKey]`	是	无	主键列表；`BatchQueryKey(primary_key, partition_key=None)`。
`projections`	`List[str]`	否	`None`	投影字段列表。
`retrieve_vector`	`bool`	否	`False`	是否返回向量字段。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

批量查询没有 vector_index_membership 参数，不支持查询向量索引逻辑覆盖状态。

BatchQueryKey 参数

参数	类型	是否必填	默认值	说明
`primary_key`	`dict`	是	无	目标记录主键。
`partition_key`	`dict`	否	`None`	目标记录分区键；分区键与主键相同时无需填写。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[Row]`	查询结果记录列表。

标量过滤查询

功能介绍

Table.select 按标量过滤条件查询记录，并通过响应中的 next_marker 分页。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

marker = None
while True:
    response = table.select(
        filter="book_name = '三国演义' AND page >= 20",
        marker=marker,
        projections=["id", "book_name", "page"],
        read_consistency=ReadConsistency.EVENTUAL,
        limit=100,
    )
    print(response.rows)
    if not response.is_truncated:
        break
    marker = response.next_marker
            

请求参数

参数	类型	是否必填	默认值	说明
`filter`	`str`	否	`None`	标量过滤表达式；不传或传空字符串表示不过滤。
`marker`	`dict`	否	`None`	分页起点，通常使用上次响应的 `next_marker`。
`projections`	`List[str]`	否	`None`	投影字段列表。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	读取一致性。
`limit`	`int`	否	`10`	每页记录数，取值范围 `[1, 1000]`。
`config`	`Configuration`	否	`None`	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[Row]`	当前页记录列表。
`is_truncated`	`bool`	是否还有后续记录，对应协议字段 `isTruncated`。
`next_marker`	`dict`	下一页起点，对应协议字段 `nextMarker`。

向量TopK检索

功能介绍

Table.vector_search(request=VectorTopkSearchRequest(...)) 基于向量字段执行 KNN 或 ANN TopK 检索，并支持标量过滤。Table.search 是兼容旧版本的弃用接口，新代码应使用请求对象。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import FilterMode, ReadConsistency
from pymochow.model.table import (
    AdvancedOptions,
    FloatVector,
    VectorSearchConfig,
    VectorTopkSearchRequest,
)

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

search_config = VectorSearchConfig(
    ef=200,
    pruning=True,
    filter_mode=FilterMode.AUTO,
)

# 向量 TopK 检索。
topk_request = VectorTopkSearchRequest(
    vector_field="vector",
    vector=FloatVector([0.3123, 0.43, 0.213]),
    limit=10,
    offset=0,
    filter="book_name = '三国演义'",
    config=search_config,
    advanced_options=AdvancedOptions(
        accept_partial_success_on_mpp=False,
        success_rate_lower_bound_on_mpp=1.0,
        two_phase_retrieval=False,
    ),
)
topk_response = table.vector_search(
    request=topk_request,
    projections=["id", "book_name", "page"],
    read_consistency=ReadConsistency.EVENTUAL,
)
print(topk_response.rows)
            

Table.vector_search 参数

参数	类型	是否必填	默认值	说明
`request`	`VectorTopkSearchRequest`	是	无	TopK 向量检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表；为空时返回所有标量字段。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

VectorTopkSearchRequest 参数

参数	类型	是否必填	默认值	说明
`vector_field`	`str`	是	无	目标向量字段名。
`vector`	`Vector`	是	`None`	`FloatVector`、`BinaryVector` 或 `SparseFloatVector`。
`limit`	`int`	否	`50`	TopK 的 K 值。
`offset`	`int`	否	`None`	结果偏移量。
`filter`	`str`	否	`None`	标量过滤表达式。
`config`	`VectorSearchConfig`	否	`None`	向量算法检索参数。
`advanced_options`	`AdvancedOptions`	否	`None`	MPP 和两阶段检索选项。

Python 的 VectorTopkSearchRequest 没有 decay 参数。不要向该构造函数传入 decay，也不要把其他语言 SDK 或协议中的向量 decay 写法套用到当前 Python SDK。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[MatchedRow]`	命中记录列表。每项的 `row` 为记录，`distance` 为向量距离，`score` 为记录得分。L2 距离越小越相似，IP 和 COSINE 距离越大越相似。

向量范围检索

功能介绍

Table.vector_search(request=VectorRangeSearchRequest(...)) 返回距离位于指定区间内的向量记录，并支持标量过滤。

请求示例

                Python
                
            

                from pymochow.model.table import (
    FloatVector,
    VectorRangeSearchRequest,
    VectorSearchConfig,
)

request = VectorRangeSearchRequest(
    vector_field="vector",
    vector=FloatVector([0.3123, 0.43, 0.213]),
    distance_range=(0.0, 0.8),
    limit=20,
    offset=0,
    filter="page >= 20",
    config=VectorSearchConfig(ef=200),
)
response = table.vector_search(
    request=request,
    projections=["id", "book_name", "page"],
)
print(response.rows)
            

VectorRangeSearchRequest 参数

参数	类型	是否必填	默认值	说明
`vector_field`	`str`	是	无	目标向量字段名。
`distance_range`	`Tuple[float, float]`	是	无	`(distance_near, distance_far)`；两端成对出现且 far 大于 near。L2 使用非负值，COSINE 范围为 `[-1.0, 1.0]`。
`vector`	`Vector`	是	`None`	`FloatVector`、`BinaryVector` 或 `SparseFloatVector`。
`limit`	`int`	否	`None`	最多返回的记录数。
`offset`	`int`	否	`None`	结果偏移量。
`filter`	`str`	否	`None`	标量过滤表达式。
`advanced_options`	`AdvancedOptions`	否	`None`	MPP 和两阶段检索选项。
`config`	`VectorSearchConfig`	否	`None`	向量算法检索参数，字段见“向量检索公共子参数”。

Table.vector_search 参数

参数	类型	是否必填	默认值	说明
`request`	`VectorRangeSearchRequest`	是	无	范围向量检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[MatchedRow]`	命中记录列表；每项包含 `row`、`distance` 和 `score`。

批量向量检索

功能介绍

Table.vector_search(request=VectorBatchSearchRequest(...)) 使用多个查询向量执行一批 KNN 或 ANN 检索，并支持标量过滤。Table.batch_search 是兼容旧版本的弃用接口。

请求示例

                Python
                
            

                from pymochow.model.table import (
    FloatVector,
    VectorBatchSearchRequest,
    VectorSearchConfig,
)

request = VectorBatchSearchRequest(
    vector_field="vector",
    vectors=[
        FloatVector([0.3123, 0.43, 0.213]),
        FloatVector([0.1223, 0.53, 0.313]),
    ],
    limit=10,
    offset=0,
    distance_range=(0.0, 0.8),
    filter="page >= 20",
    merge_batch_result=False,
    config=VectorSearchConfig(ef=200),
)
response = table.vector_search(request=request)
print(response.rows)
            

VectorBatchSearchRequest 参数

参数	类型	是否必填	默认值	说明
`vector_field`	`str`	是	无	目标向量字段。
`vectors`	`List[Vector]`	是	`None`	当前 SDK 固定序列化为 `vectorFloats`，应使用 `FloatVector`。
`limit`	`int`	否	`None`	每个查询向量的结果数。
`offset`	`int`	否	`None`	结果偏移量。
`distance_range`	`Tuple[float, float]`	否	`None`	`(distance_near, distance_far)`，约束与范围检索相同。
`filter`	`str`	否	`None`	标量过滤表达式。
`merge_batch_result`	`bool`	否	`None`	是否合并多个查询向量的结果。
`advanced_options`	`AdvancedOptions`	否	`None`	高级选项。
`config`	`VectorSearchConfig`	否	`None`	向量算法检索参数，字段见“向量检索公共子参数”。

Table.vector_search 参数

参数	类型	是否必填	默认值	说明
`request`	`VectorBatchSearchRequest`	是	无	批量向量检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`list`	批量命中结果；匹配项包含 `row`、`distance` 和 `score`，分组或合并形式由 `merge_batch_result` 控制。

多向量检索

功能介绍

Table.vector_search(request=MultiVectorSearchRequest(...)) 对多个向量列分别检索，并使用 RRF 或加权得分进行融合排序。

请求示例

                Python
                
            

                from pymochow.model.schema import RRFRank
from pymochow.model.table import (
    FloatVector,
    MultiVectorSearchRequest,
    VectorSearchConfig,
    VectorTopkSearchRequest,
)

request = MultiVectorSearchRequest(
    requests=[
        VectorTopkSearchRequest(
            vector_field="title_vector",
            vector=FloatVector([0.3123, 0.43, 0.213]),
            limit=20,
            config=VectorSearchConfig(ef=200),
        ),
        VectorTopkSearchRequest(
            vector_field="content_vector",
            vector=FloatVector([0.1123, 0.63, 0.113]),
            limit=20,
            config=VectorSearchConfig(ef=200),
        ),
    ],
    ranking=RRFRank(k=60),
    limit=10,
    offset=0,
    filter="book_name = '三国演义'",
)
response = table.vector_search(request=request)
print(response.rows)
            

MultiVectorSearchRequest 参数

参数	类型	是否必填	默认值	说明
`requests`	`List[VectorTopkSearchRequest 或 VectorRangeSearchRequest]`	是	无	子向量请求列表；每路可分别设置 `limit`。
`ranking`	`FusionRankPolicy`	是	无	`RRFRank(k)` 或 `WeightedRank(weights)`。
`limit`	`int`	否	`None`	融合后返回数量，可与每路 `limit` 不同。
`offset`	`int`	否	`None`	融合后结果偏移量。
`filter`	`str`	否	`None`	全局过滤条件，会覆盖子请求过滤条件。

RRFRank 序列化为 strategy="rrf"；WeightedRank 序列化为 strategy="ws"，权重数量应与子请求数量一致。

RRFRank 参数

参数	类型	是否必填	说明
`k`	`int`	是	RRF 融合排序参数。

WeightedRank 参数

参数	类型	是否必填	说明
`weights`	`List[float]`	是	每路检索的权重，数量应与子请求数量一致。

Table.vector_search 参数

参数	类型	是否必填	默认值	说明
`request`	`MultiVectorSearchRequest`	是	无	多向量检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[MatchedRow]`	融合结果；每项的 `row` 为记录，`score` 为融合排序得分。

向量检索公共子参数

VectorSearchConfig 参数

参数	适用索引	说明
`ef`	HNSW、HNSWPQ、HNSWSQ、HNSWRABITQ	动态候选列表大小，HNSW 协议要求不小于 `limit`，最大 10000。
`pruning`	HNSW	是否启用剪枝。
`search_coarse_count`	PUCK	粗聚类中心候选数。
`w`、`search_l`	DISKANN	搜索宽度和候选集大小，`search_l` 应不小于 `limit`。
`nprobe`	IVF、IVFSQ、IVFPQ、IVFRABITQ	扫描聚类中心数，范围 `[1, nlist]`。
`filter_mode`	支持过滤的向量检索	`FilterMode.AUTO` 或 `FilterMode.POST`。
`post_filter_amplification_factor`	后过滤	后过滤候选放大系数。

AdvancedOptions 参数

参数	默认值	说明
`accept_partial_success_on_mpp`	`False`	是否接受 MPP 部分成功。
`success_rate_lower_bound_on_mpp`	`1.0`	可接受的最低 MPP 成功率，范围 `[0.0, 1.0]`。
`two_phase_retrieval`	`None`	是否启用两阶段检索；MultiVector 不支持，并且与 decay 不兼容。

全文检索

功能介绍

Table.bm25_search 使用倒排索引执行 BM25 全文检索，支持标量过滤、请求级同义词、高亮和衰变重排。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency
from pymochow.model.table import (
    BM25SearchRequest,
    DecayRanker,
    Highlight,
    HighlightField,
)

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

highlight = Highlight(
    fields={
        "content": HighlightField(
            fragment_size=120,
            number_of_fragments=3,
        ),
        "title": HighlightField(number_of_fragments=0),
    },
    pre_tags=["<em>", "<strong>"],
    post_tags=["</em>", "</strong>"],
)

decay = DecayRanker(
    decay_type="EXPONENTIAL",
    field="publish_time",
    origin=1717200000,
    scale=31536000,
    name="publish_time_decay",
    decay_rate=1.0,
    offset=0,
    reverse=False,
    weight=1.0,
    min_score=0.2,
)

request = BM25SearchRequest(
    index_name="book_segment_inverted_idx",
    search_text="content:吕布",
    limit=20,
    filter="book_name = '三国演义'",
    synonyms=[["吕布", "奉先"], ["优势", "优点"]],
    highlight=highlight,
    decay=[decay],
)
response = table.bm25_search(
    request=request,
    projections=["id", "title", "content", "publish_time"],
    read_consistency=ReadConsistency.EVENTUAL,
)
for matched_row in response.rows:
    print(matched_row.row, matched_row.score, matched_row.highlight)
            

BM25SearchRequest 参数

参数	类型	是否必填	默认值	说明
`index_name`	`str`	是	无	倒排索引名称；索引状态为 `NORMAL` 后方可检索。
`search_text`	`str`	是	无	UTF-8 全文检索表达式。
`limit`	`int`	否	`None`	返回结果数。
`filter`	`str`	否	`None`	标量过滤条件。
`synonyms`	`List[List[str]]`	否	`None`	本次请求的等价同义词组。
`highlight`	`Highlight`	否	`None`	高亮配置；不传时响应不含高亮。
`decay`	`List[DecayRanker]`	否	`None`	衰变排名器列表。

Table.bm25_search 参数

参数	类型	是否必填	默认值	说明
`request`	`BM25SearchRequest`	是	无	全文检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表；为空时返回所有标量字段。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

Synonyms

每个内部列表是一组等价词，例如 [["数据库", "VectorDB"], ["优势", "优点"]]。
内部列表只有 0 或 1 个词时会被忽略；成员为空字符串或非字符串时请求失败。
每个词按指定倒排索引的 analyzer 分词。当前要求结果最多为一个 term；被消除为空、分成多个 term 或产生不支持的位置增量时请求失败。
同义词只影响本次请求，不写入索引，也不影响后续检索。
同时使用高亮时，检索和高亮采用同义词扩展后的查询语义，因此同义词召回也可产生高亮片段。

全文检索表达式

检索类型	用法	示例	说明
关键词检索	`field_name:keyword` 或 `field_name:(keyword_1 keyword_2)`	`title:数据库`、`title:(数据库百度)`	在指定字段匹配一个或任意一个关键词。
单列关键词检索	`keyword` 或 `keyword_1 AND keyword_2`	`数据库`、`数据库 AND 百度`	仅适用于单列倒排索引；多列索引必须显式指定字段名。
复合检索	`query_1 AND query_2`、`query_1 OR query_2`	`(title:数据库 OR title:百度) AND content:VectorDB`	使用 `AND`、`OR` 和括号组合条件。
Phrase 检索	`field_name:"phrase"`	`title:"百度VectorDB数据库"`	短语必须使用双引号。
Match 检索	`field_name:statement`	`content:百度VectorDB的优缺点`	匹配分词后的任意词，匹配词越多相关性越高。
Prefix 检索	`field_name:keyword*`	`title:数据*`	匹配指定前缀的词。
更改查询权重	`field_name:keyword^boost`	`title:数据库^2 OR content:百度`	`boost` 调整该条件的相关性权重，默认权重为 1。

全文检索表达式将以下字符用于特殊语义：

+ - && || ! ( ) { } [ ] ^ " ~ * ? : `

需要匹配这些字符时使用反斜线转义。例如匹配 百度自研的向量数据库:VectorDB 时，表达式应写为 百度自研的向量数据库\\:VectorDB。

Highlight 和 HighlightField

Python 使用 Highlight(fields, pre_tags, post_tags)，其中 fields 是字段名到 HighlightField 的映射。字段必须属于 index_name 指定的倒排索引；Highlight(fields={}) 使用协议默认字段范围，即索引覆盖的所有可高亮字段。

Python 参数	协议字段	默认值/范围	说明
`Highlight.fields`	`fields`	默认全部可高亮字段	字段级配置映射。
`Highlight.pre_tags`	`preTags`	`["<em>"]`	命中词前置标签，可传多个并按命中顺序轮转。
`Highlight.post_tags`	`postTags`	`["</em>"]`	命中词后置标签，可传多个并按命中顺序轮转。
`HighlightField.fragment_size`	`fragmentSize`	默认 100，范围 `[1, 2147483647]`	片段目标长度，不是严格字符串长度上限。
`HighlightField.number_of_fragments`	`numberOfFragments`	默认 3，范围 `[0, 10000]`	最大片段数；`0` 返回完整字段，此时 `fragment_size` 不生效。

标签规则：

只显式配置一侧时，服务端按相同数量补齐另一侧的默认标签。
两侧均显式配置时，pre_tags 与 post_tags 数量必须一致。
标签会原样插入，不进行 HTML 转义；直接渲染 HTML 时应自行执行可信内容校验和转义。
请求了高亮但某条结果没有片段时，highlight 为空对象；未请求时响应行不包含该字段。
过宽的通配、前缀或范围查询可能展开过多 term（例如超过 1024）而失败，应缩小条件或关闭高亮。

DecayRanker

Python 构造函数为：

Text

1DecayRanker(decay_type, field, origin, scale, name=None,
2            decay_rate=None, offset=None, reverse=None, weight=None,
3            min_score=None, max_score=None)

Python 参数 field 会按协议映射为 fieldName，decay_type 映射为 type。

Python 参数	协议字段	是否必填	默认值/约束	说明
`decay_type`	`type`	是	`LINEAR`、`EXPONENTIAL`、`GAUSSIAN`，大小写不敏感	衰变函数类型。
`field`	`fieldName`	是	支持的数值或时间标量字段	参与衰变计算的字段。
`origin`	`origin`	是	有限数值	衰变中心。
`scale`	`scale`	是	必须大于 `1e-6`	衰变尺度。
`name`	`name`	否	无	函数标识，不参与计算。
`decay_rate`	`decayRate`	EXPONENTIAL 必填	必须大于 0	指数衰变率。
`offset`	`offset`	否	默认 `0`	不产生衰变的距离容忍区间。
`reverse`	`reverse`	否	默认 `false`	是否反向衰变。
`weight`	`weight`	否	默认 `1.0`	多个函数加权时的权重。
`min_score`	`minScore`	否	与最大值同时存在时小于最大值	单函数得分下限。
`max_score`	`maxScore`	否	与最小值同时存在时大于最小值	单函数得分上限。

fieldName 支持 BOOL、整数、FLOAT、DOUBLE、DATE、TIME、DATETIME、TIMESTAMP，不支持向量、字符串、二进制或复杂类型。origin、scale、offset 必须与字段使用相同单位：DATE 按天、TIME 按秒、DATETIME/TIMESTAMP 按微秒；数值字段按原值计算。

令 d = max(0, abs(fieldValue - origin) - offset) / scale：

LINEAR：线性衰变，适合存在明确衰变边界的场景；不需要 decayRate。
EXPONENTIAL：指数衰变，reverse=false 时为 exp(-decayRate * d)；必须设置 decayRate > 0。
GAUSSIAN：高斯衰变，reverse=false 时为 exp(-0.5 * d * d)；不需要 decayRate。

多个函数先分别计算并应用上下限，再按 weight 加权；最终 score 为原始检索得分乘以整体衰变分数。decay 与 AdvancedOptions(two_phase_retrieval=True) 不兼容。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[MatchedRow]`	全文检索结果。

MatchedRow 参数

参数	类型	说明
`row`	`Row`	一行记录。
`score`	`float`	BM25 相关性得分；配置 `decay` 时为衰变后的最终得分。
`highlight`	动态对象	仅请求高亮时返回；属性按字段名保存高亮片段列表。已请求但无片段时为空对象。

混合检索

功能介绍

Table.hybrid_search 同时执行一个向量检索分支和一个 BM25 分支，再按权重融合。外层 limit 和 filter 会覆盖两个子请求中的同名设置。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency
from pymochow.model.table import (
    BM25SearchRequest,
    DecayRanker,
    FloatVector,
    Highlight,
    HighlightField,
    HybridSearchRequest,
    VectorSearchConfig,
    VectorTopkSearchRequest,
)

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

vector_request = VectorTopkSearchRequest(
    vector_field="vector",
    vector=FloatVector([0.3123, 0.43, 0.213]),
    limit=20,
    config=VectorSearchConfig(ef=200),
)
bm25_request = BM25SearchRequest(
    index_name="book_segment_inverted_idx",
    search_text="content:吕布",
    limit=20,
    synonyms=[["吕布", "奉先"]],
    highlight=Highlight(
        fields={
            "content": HighlightField(
                fragment_size=100,
                number_of_fragments=2,
            )
        },
        pre_tags=["<em>"],
        post_tags=["</em>"],
    ),
)
hybrid_request = HybridSearchRequest(
    vector_request=vector_request,
    bm25_request=bm25_request,
    vector_weight=0.4,
    bm25_weight=0.6,
    limit=20,
    filter="book_name = '三国演义'",
    decay=[
        DecayRanker(
            decay_type="LINEAR",
            field="page",
            origin=25,
            scale=100,
            name="page_decay",
            weight=0.3,
        )
    ],
)
response = table.hybrid_search(
    request=hybrid_request,
    projections=["id", "book_name", "content", "page"],
    read_consistency=ReadConsistency.EVENTUAL,
)
for matched_row in response.rows:
    print(
        matched_row.row,
        matched_row.score,
        matched_row.distance,
        matched_row.highlight,
    )
            

HybridSearchRequest 参数

参数	类型	是否必填	默认值	说明
`vector_request`	`VectorTopkSearchRequest、VectorRangeSearchRequest 或 VectorBatchSearchRequest`	是	无	向量分支。
`bm25_request`	`BM25SearchRequest`	是	无	BM25 分支；`synonyms` 和 `highlight` 在此对象中配置。
`vector_weight`	`float`	否	`0.5`	向量分支权重。
`bm25_weight`	`float`	否	`0.5`	BM25 分支权重。
`limit`	`int`	否	`None`	融合后返回数量。
`filter`	`str`	否	`None`	全局过滤，覆盖子请求过滤。
`advanced_options`	`AdvancedOptions`	否	`None`	高级选项。
`decay`	`List[DecayRanker]`	否	`None`	作用于融合后结果；与两阶段检索不兼容。

Table.hybrid_search 参数

参数	类型	是否必填	默认值	说明
`request`	`HybridSearchRequest`	是	无	混合检索请求。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键；不指定可能在所有分片执行 MPP 检索。
`projections`	`List[str]`	否	`None`	投影字段列表；为空时返回所有标量字段。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	检索读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

Hybrid 参数交互：

bm25_request.synonyms 和 bm25_request.highlight 只作用于 BM25 分支，不改变向量分支召回。
请求高亮时，纯向量召回记录返回 highlight={}。
decay 作用于融合后的结果，改变最终 score 和排序。
同时使用三者时，BM25 先按 synonyms 扩展并参与融合，融合后应用 Hybrid 外层 decay，最后按同义词扩展后的 BM25 语义生成高亮。
建议不要在 Hybrid 的 bm25_request 中再配置 decay；应使用 Hybrid 外层 decay 明确作用于融合结果。

返回参数

参数	类型	说明
`code`	`int`	返回码。
`msg`	`str`	返回信息。
`rows`	`List[MatchedRow]`	混合检索结果。

MatchedRow 参数

参数	类型	说明
`row`	`Row`	一行记录。
`distance`	`float`	向量分支距离。
`score`	`float`	融合排序得分；配置 `decay` 时为衰变后的最终得分。
`highlight`	动态对象	仅 BM25 分支请求高亮时返回；纯向量召回记录为空对象。

SearchIterator

功能介绍

Table.search_iterator 分批获取较大的检索结果集。调用 next() 返回当前批次的行列表，完成时返回 None；close() 用于结束迭代器。

请求示例

                Python
                
            

                import pymochow
from pymochow.auth.bce_credentials import BceCredentials
from pymochow.configuration import Configuration
from pymochow.model.enum import ReadConsistency
from pymochow.model.table import (
    FloatVector,
    VectorSearchConfig,
    VectorTopkSearchRequest,
)

config = Configuration(
    credentials=BceCredentials("root", "您的账户 API 密钥"),
    endpoint="您的实例访问端点",
)
client = pymochow.MochowClient(config)
table = client.database("db_test").table("table_test")

batch_size = 100
request = VectorTopkSearchRequest(
    vector_field="vector",
    vector=FloatVector([0.3123, 0.43, 0.213]),
    limit=batch_size,
    filter="book_name = '三国演义'",
    config=VectorSearchConfig(ef=200),
)
iterator = table.search_iterator(
    request=request,
    batch_size=batch_size,
    total_size=1000,
    projections=["id", "book_name", "page"],
    read_consistency=ReadConsistency.EVENTUAL,
)

try:
    while True:
        rows = iterator.next()
        if rows is None:
            break
        print(rows)
finally:
    iterator.close()
            

请求参数

参数	类型	是否必填	默认值	说明
`request`	`SearchRequest`	是	无	TopK、MultiVector、BM25 或 Hybrid 请求。
`batch_size`	`int`	是	无	每次 `next()` 的结果数，必须等于 `request` 的 `limit`。
`total_size`	`int`	是	无	计划获取的总结果数，不能小于 `batch_size`。
`partition_key`	`Dict[str, Any]`	否	`None`	分区键。
`projections`	`List[str]`	否	`None`	投影字段列表。
`read_consistency`	`ReadConsistency`	否	`EVENTUAL`	读取一致性。
`config`	`Configuration`	否	`None`	本次请求配置。

返回类型和迭代器方法

Table.search_iterator 返回 SearchIterator 对象。

SearchIterator.next

项目	说明
参数	无。
返回类型	`List[MatchedRow]` 或 `None`。正常批次返回检索结果列表；迭代结束后返回 `None`。最后一批的长度可能小于 `batch_size`。

SearchIterator.close

项目	说明
参数	无。
返回类型	无。释放迭代器；调用后不应继续调用 `next()`。

SearchIterator 对应的服务端响应还包含 iterated_ids（协议字段 iteratedIds），但该字段由 SDK 内部维护，不作为 next() 的返回值暴露给调用方。

支持范围和限制

支持 VectorTopkSearchRequest、MultiVectorSearchRequest、BM25SearchRequest、HybridSearchRequest。
向量索引仅支持 HNSW、HNSWPQ、IVF、IVFSQ、IVFPQ、IVFRABITQ。
不支持 VectorRangeSearchRequest 和 VectorBatchSearchRequest。
MultiVector 仅支持 ws 融合，即必须使用 WeightedRank，不能使用 RRFRank。
SDK 自动管理协议中的 iteratedIds：首次为空字符串，后续使用上次响应值。用户不应自行构造 SearchIterator 或直接操作 iteratedIds。
最后一批数量可能小于 batch_size；达到 total_size 后 next() 返回 None。
如果服务端响应不包含 iteratedIds，SDK 会抛出 ClientError("search iterator is not supported")。

下面展示 MultiVector Iterator 的请求构造。注意使用 WeightedRank，且外层 limit 必须等于 batch_size：

                Python
                
            

                from pymochow.model.schema import WeightedRank
from pymochow.model.table import (
    FloatVector,
    MultiVectorSearchRequest,
    VectorSearchConfig,
    VectorTopkSearchRequest,
)

batch_size = 100
request = MultiVectorSearchRequest(
    requests=[
        VectorTopkSearchRequest(
            vector_field="title_vector",
            vector=FloatVector([0.3123, 0.43, 0.213]),
            limit=batch_size,
            config=VectorSearchConfig(ef=200),
        ),
        VectorTopkSearchRequest(
            vector_field="content_vector",
            vector=FloatVector([0.1123, 0.63, 0.113]),
            limit=batch_size,
            config=VectorSearchConfig(ef=200),
        ),
    ],
    ranking=WeightedRank(weights=[0.4, 0.6]),
    limit=batch_size,
)
            

BM25 和 Hybrid Iterator 分别将 BM25SearchRequest 或 HybridSearchRequest 作为 request 传给 table.search_iterator，并同样保证请求的 limit == batch_size。

返回结果

SDK 返回 HttpResponse 动态对象，可直接打印，也可以读取下列常用属性：

操作	常用响应属性	说明
Insert、Upsert	`code`、`msg`、`affected_count`	返回码、信息和成功写入记录数。
Update、Delete	`code`、`msg`	返回码和信息。
Query	`row`、`vector_index_membership`	单行结果和可选 Membership。
BatchQuery	`rows`	记录列表。
Select	`rows`、`is_truncated`、`next_marker`	当前页、是否截断和下一页标记。
向量、BM25、Hybrid	`rows`	命中列表；元素按接口包含 `row`、`distance`、`score`、`highlight` 等属性。
SearchIterator	`next()` 返回 `list` 或 `None`	`iterated_ids` 由 SDK 内部维护。

ReadConsistency.EVENTUAL 是 Query、BatchQuery、Select 和各类检索的默认值；业务要求读取主副本最新视图时显式使用 ReadConsistency.STRONG。

评价此篇文章

有帮助没帮助

Alias 操作

Index 操作

向量数据库 VectorDB

Row 操作

使用前准备

插入记录

功能介绍

请求示例

请求参数

返回参数

插入或更新记录

功能介绍

请求示例

请求参数

返回参数

更新记录

功能介绍

请求示例

请求参数

返回参数

删除记录

功能介绍

请求示例

请求参数

返回参数

标量查询

功能介绍

请求示例

请求参数

VectorIndexMembership

返回参数

批量标量查询

功能介绍

请求示例

请求参数

BatchQueryKey 参数

返回参数

标量过滤查询

功能介绍

请求示例

请求参数

返回参数

向量TopK检索

功能介绍

请求示例

Table.vector_search 参数

VectorTopkSearchRequest 参数

返回参数

向量范围检索

功能介绍

请求示例

VectorRangeSearchRequest 参数

Table.vector_search 参数

返回参数

批量向量检索

功能介绍

请求示例

VectorBatchSearchRequest 参数

Table.vector_search 参数

返回参数

多向量检索

功能介绍

请求示例

MultiVectorSearchRequest 参数

RRFRank 参数

WeightedRank 参数

Table.vector_search 参数

返回参数

向量检索公共子参数

VectorSearchConfig 参数

AdvancedOptions 参数

全文检索

功能介绍

请求示例

BM25SearchRequest 参数

Table.bm25_search 参数

Synonyms

全文检索表达式

Highlight 和 HighlightField

DecayRanker

返回参数

MatchedRow 参数