Row 操作

更新时间：2026-09-01

插入记录

功能介绍

将一条或者一批记录插入到指定的表中。插入语义为Insert，若记录的主键已存在，则插入失败并报错。当插入一批时，该接口暂不支持批次的原子性。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>
#include <vector>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::Row row;
    row.Set("id", std::string("0001"))
       .Set("bookName", std::string("西游记"))
       .Set("segment", std::string("孙悟空三打白骨精"))
       .Set("vector", mochow::FloatVector{0.2123F, 0.21F, 0.213F});

    std::vector<mochow::Row> rows = {row};
    mochow::DmlResult result;
    mochow::Status status = table.Insert(rows, &result);
    if (!status.IsOk()) {
        std::cerr << "insert failed: " << status.Message()
                  << ", request_id=" << status.RequestId() << std::endl;
        return 1;
    }
    std::cout << "affected rows: " << result.affected_rows << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

参数	参数类型	是否必选	参数含义
rows	const std::vector<mochow::Row>&	是	插入的记录列表。
result	mochow::DmlResult*	是	输出参数，用于接收写入结果，不能为空指针。
options	mochow::RequestOptions	否	单次请求级选项，可设置`WithRequestId`、`WithRequestTimeoutMs`、`WithIdempotencyKey`和`WithRetry`。

Row参数

参数	参数类型	是否必选	参数含义
Set	std::string, mochow::FieldValue	是	设置一个字段的值，支持链式调用。`FieldValue`可由bool、整型、浮点、`std::string`、`mochow::Date`、`mochow::Time`、`mochow::Datetime`、`mochow::Timestamp`、`mochow::HLC`、`mochow::Binary`、`mochow::FloatVector`、`mochow::BinaryVector`、`mochow::SparseFloatVector`隐式构造，数组与Map分别使用`FieldValue::ArrayValue`、`FieldValue::MapValue`构造。
Contains / Get / Values	std::string	否	读取已设置的字段。

返回参数

DmlResult参数

参数	参数类型	参数含义
affected_rows	uint64_t	本次请求影响的记录数。
metadata	mochow::ResponseMetadata	响应元信息，可通过`RequestId()`、`HttpStatus()`、`ServerCode()`读取。

插入或更新记录

功能介绍

将一条或者一批记录插入到指定的表中。插入语义为Upsert（Insert or else Update），即，当记录的主键不存在时，则正常插入，若发现主键已存在，则用新的记录覆盖旧的记录。当插入一批时，该接口暂不支持批次的原子性。该接口可用于批量迁移/灌库等场景。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>
#include <vector>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::Row row;
    row.Set("id", std::string("0001"))
       .Set("bookName", std::string("西游记"))
       .Set("vector", mochow::FloatVector{0.2123F, 0.21F, 0.213F});

    std::vector<mochow::Row> rows = {row};
    mochow::DmlResult result;
    mochow::Status status = table.Upsert(rows, &result);
    if (!status.IsOk()) {
        std::cerr << "upsert failed: " << status.Message() << std::endl;
        return 1;
    }
    std::cout << "affected rows: " << result.affected_rows << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

参数	参数类型	是否必选	参数含义
rows	const std::vector<mochow::Row>&	是	待插入记录列表。
result	mochow::DmlResult*	是	输出参数，用于接收写入结果，不能为空指针。
options	mochow::RequestOptions	否	单次请求级选项。

返回参数

返回结构与插入记录一致，见DmlResult参数。

更新记录

功能介绍

更新表中指定记录的一个或多个标量字段的值。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>
#include <utility>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::Row update;
    update.Set("bookName", std::string("红楼梦"));

    mochow::UpdateRequest request;
    request.WithPrimaryKey(mochow::Row().Set("id", std::string("0001")))
           .WithUpdate(std::move(update));

    mochow::DmlResult result;
    mochow::Status status = table.Update(request, &result);
    if (!status.IsOk()) {
        std::cerr << "update failed: " << status.Message() << std::endl;
        return 1;
    }

    (void)client->Close();
    return 0;
}
            

请求参数

UpdateRequest参数

参数	参数类型	是否必选	参数含义
WithPrimaryKey	mochow::Row	是	指定记录的主键值。
WithPartitionKey	mochow::Row	否	指定记录的分区键值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
WithUpdate	mochow::Row	是	待更新的字段列表及其新值。不允许更新主键、分区键和向量字段。

返回参数

返回结构与插入记录一致，见DmlResult参数。

删除记录

功能介绍

删除表中的指定记录，支持基于主键删除和基于标量过滤条件删除。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::DmlResult result;

    // 基于主键删除
    mochow::DeleteRequest delete_by_key;
    delete_by_key.WithPrimaryKey(mochow::Row().Set("id", std::string("0001")));
    mochow::Status status = table.Delete(delete_by_key, &result);
    if (!status.IsOk()) {
        std::cerr << "delete by primary key failed: " << status.Message()
                  << std::endl;
        return 1;
    }

    // 基于标量过滤条件删除
    mochow::DeleteRequest delete_by_filter;
    delete_by_filter.WithFilter("bookName = '西游记'");
    status = table.Delete(delete_by_filter, &result);
    if (!status.IsOk()) {
        std::cerr << "delete by filter failed: " << status.Message()
                  << std::endl;
        return 1;
    }

    (void)client->Close();
    return 0;
}
            

请求参数

DeleteRequest参数

参数	参数类型	是否必选	参数含义
WithPrimaryKey	mochow::Row	否	指定记录的主键值。
WithPartitionKey	mochow::Row	否	指定记录的分区键值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
WithFilter	std::string	否	删除的标量过滤条件。当要删除全部记录时，可设置为`"*"`；Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。必须填写主键值或过滤条件，二者有且仅能选其一。

返回参数

返回结构与插入记录一致，见DmlResult参数。

标量查询

功能介绍

基于主键值进行点查。可选携带vectorIndexMembership，查询目标记录相对于指定向量索引的当前逻辑覆盖状态。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::QueryRequest request;
    request.WithPrimaryKey(mochow::Row().Set("id", std::string("0001")))
           .WithProjections({"id", "bookName"})
           // 建议配合强一致读，避免不同副本索引进度不一致
           .WithReadConsistency(mochow::ReadConsistency::Strong)
           .WithVectorIndexMembership("vector_idx");

    mochow::QueryResult result;
    mochow::Status status = table.Query(request, &result);
    if (!status.IsOk()) {
        std::cerr << "query failed: " << status.Message() << std::endl;
        return 1;
    }

    std::cout << "rows: " << result.rows.size() << std::endl;
    if (result.vector_index_membership.has_value()) {
        std::cout << "membership state: "
                  << result.vector_index_membership->state << std::endl;
    }

    (void)client->Close();
    return 0;
}
            

请求参数

QueryRequest参数

参数	参数类型	是否必选	参数含义
WithPrimaryKey	mochow::Row	是	指定记录的主键值。
WithPartitionKey	mochow::Row	否	指定记录的分区键值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	查询请求的一致性级别，取值为： `Eventual`（默认值）：最终一致性，查询请求会随机发送给分片的所有副本 `Strong`：强一致性，查询请求只会发送给分片主副本
WithVectorIndexMembership	std::string	否	查询目标记录相对于指定向量索引的当前逻辑覆盖状态，参数为向量索引名称。该参数仅单条查询（`Query`）支持，批量查询（`BatchQuery`）不支持。

返回参数

QueryResult参数

参数	参数类型	参数含义
rows	std::vector<mochow::Row>	查询到的记录列表，未命中时为空。
vector_index_membership	std::optional<mochow::VectorIndexMembership>	仅在请求携带`WithVectorIndexMembership`且服务端返回该字段时有值，结构见VectorIndexMembership参数。
next_marker	mochow::Row	分页起始点，标量过滤查询（`Select`）场景使用。
is_truncated	bool	结果是否被截断，标量过滤查询（`Select`）场景使用。
metadata	mochow::ResponseMetadata	响应元信息，可通过`RequestId()`、`HttpStatus()`、`ServerCode()`读取。

VectorIndexMembership参数

参数	参数类型	参数含义
index_name	std::string	请求中指定的向量索引名称；服务端只返回`state`，该字段由 SDK 回填为请求值。
state	std::string	目标记录相对于指定向量索引的逻辑覆盖状态，取值为： ROW_NOT_FOUND：未查询到该主键对应的记录 NO_VECTOR：记录存在，但索引字段对应的向量为空（多向量表中某一向量字段未写入时可能出现） KNN：记录的向量尚未进入任何向量索引，检索时走暴力计算 DELTA_INDEX：记录的向量已进入增量索引 STABLE_INDEX：记录的向量已进入全量（stable）索引

说明：

该状态表示当前行版本相对于本次请求实际访问副本上正在提供服务（serving）的索引的逻辑覆盖状态，不会执行ANN检索，也不检查向量在底层索引文件中是否真实存在。
由于默认的Eventual一致性会随机选择副本，不同副本的索引进度可能不同；如需稳定结果，建议配合WithReadConsistency(mochow::ReadConsistency::Strong)使用。
索引重建期间，如旧的全量索引仍在提供服务，返回值仍然基于旧的serving索引。

批量标量查询

功能介绍

基于主键值的批量点查操作。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::BatchQueryRequest request;
    request.AddKeys({
               mochow::RowKey(mochow::Row().Set("id", std::string("0001"))),
               mochow::RowKey(mochow::Row().Set("id", std::string("0002"))),
           })
           .WithProjections({"id", "bookName"})
           .WithReadConsistency(mochow::ReadConsistency::Strong);

    mochow::QueryResult result;
    mochow::Status status = table.BatchQuery(request, &result);
    if (!status.IsOk()) {
        std::cerr << "batch query failed: " << status.Message() << std::endl;
        return 1;
    }
    std::cout << "rows: " << result.rows.size() << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

BatchQueryRequest参数

参数	参数类型	是否必选	参数含义
WithKeys / AddKey / AddKeys	std::vector<mochow::RowKey> / mochow::RowKey	是	目标记录的主键及分区键列表，不能为空。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	查询请求的一致性级别，取值为： `Eventual`（默认值）：最终一致性，查询请求会随机发送给分片的所有副本 `Strong`：强一致性，查询请求只会发送给分片主副本

RowKey参数

参数	参数类型	是否必选	参数含义
RowKey(primary_key)	mochow::Row	是	目标记录的主键。
RowKey(primary_key, partition_key)	mochow::Row, mochow::Row	否	同时指定主键与分区键。
WithPrimaryKey	mochow::Row	是	目标记录的主键。
WithPartitionKey	mochow::Row	否	目标记录的分区键值。如该表的分区键和主键是同一个键，则不需要填写分区键值。

返回参数

返回结构见标量查询的QueryResult参数；批量查询不返回vector_index_membership。

标量过滤查询

功能介绍

基于标量属性过滤查询记录，支持通过marker进行分页。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <string>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::SelectRequest request;
    request.WithFilter("bookName = '西游记'")
           .WithMarker(mochow::Row().Set("id", std::string("0050")))
           .WithProjections({"id", "bookName"})
           .WithReadConsistency(mochow::ReadConsistency::Eventual)
           .WithLimit(10);

    mochow::QueryResult result;
    mochow::Status status = table.Select(request, &result);
    if (!status.IsOk()) {
        std::cerr << "select failed: " << status.Message() << std::endl;
        return 1;
    }
    std::cout << "rows: " << result.rows.size()
              << ", is_truncated: " << result.is_truncated << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

SelectRequest参数

参数	参数类型	是否必选	参数含义
WithFilter	std::string	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
WithMarker	mochow::Row	否	查询的分页起始点，用于控制分页查询返回结果的起始位置。不填时默认从第一条符合条件的记录开始返回。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
WithReadConsistency	mochow::ReadConsistency	否	查询请求的一致性级别，取值为： `Eventual`（默认值）：最终一致性，查询请求会随机发送给分片的所有副本 `Strong`：强一致性，查询请求只会发送给分片主副本
WithLimit	int	否	查询返回的记录条数，在进行分页查询时即每页的记录条数。默认为10，取值范围[1, 1000]，必须大于0。

返回参数

返回结构见标量查询的QueryResult参数。分页场景下使用is_truncated判断是否还有后续数据，并将next_marker作为下一次请求的WithMarker入参。

向量TopK检索

功能介绍

基于向量字段值的KNN或ANN TopK检索操作，支持通过标量字段值进行过滤。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorSearchRequest request;
    request.WithVectorField("vector")
           .WithVector({0.3123F, 0.43F, 0.213F})
           .WithLimit(10)
           .WithParam("ef", uint64_t{200})
           .WithFilter("bookName = '三国演义'")
           .WithProjections({"id", "bookName"})
           .WithReadConsistency(mochow::ReadConsistency::Strong);

    mochow::SearchResult result;
    mochow::Status status = table.VectorSearch(request, &result);
    if (!status.IsOk()) {
        std::cerr << "vector search failed: " << status.Message() << std::endl;
        return 1;
    }
    for (const mochow::SearchHit& hit : result.hits) {
        std::cout << "score: " << hit.score;
        if (hit.has_distance) {
            std::cout << ", distance: " << hit.distance;
        }
        std::cout << std::endl;
    }

    (void)client->Close();
    return 0;
}
            

请求参数

VectorSearchRequest参数

参数	参数类型	是否必选	参数含义
WithVectorField	std::string	是	检索的指定向量字段名称。
WithVector	std::initializer_list<float> / mochow::FloatVector / mochow::BinaryVector / mochow::SparseFloatVector	是	检索的目标向量字段值，不能为空。稠密浮点向量以`vectorFloats`下发，二值向量与稀疏向量以`vector`下发。
WithLimit	int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为10，必须大于0。
WithFilter	std::string	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
WithParam	std::string, mochow::FieldValue	否	向量检索算法的运行参数，键名与HTTP协议一致，详见向量检索运行参数。
WithDistanceRange	double, double	否	范围检索的最近距离与最远距离，详见向量范围检索。
WithWeight	double	否	该路检索在混合检索中的权重，取值必须为有限值且大于0。
WithPartitionKey	mochow::Row	否	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	检索请求的一致性级别，取值为： `Eventual`（默认值）：最终一致性，查询请求会随机发送给分片的所有副本 `Strong`：强一致性，查询请求只会发送给分片主副本
WithAdvancedOptions	mochow::AdvancedSearchOptions	否	高级检索选项，详见AdvancedSearchOptions参数。
WithDecay / AddDecay	std::vector<mochow::DecayRanker> / mochow::DecayRanker	否	衰变排名器配置，详见全文检索接口中的DecayRanker参数。

向量检索运行参数

参数	参数类型	是否必选	适用算法	参数含义
ef	uint64_t	否	HNSW、HNSWSQ、HNSWPQ、HNSWRABITQ	检索过程的动态候选列表的大小。
nprobe	uint64_t	否	IVF、IVFSQ、IVFPQ、IVFRABITQ	检索过程的候选聚类数量，取值范围为[1, nlist]。
searchCoarseCount	uint64_t	否	PUCK	粗聚类中心候选集大小。
W	uint64_t	否	DISKANN	检索过程的候选节点宽度。
searchL	uint64_t	否	DISKANN	检索过程中搜索堆的最大候选集合大小，需满足`searchL >= limit`。

注：WithParam("limit", ...)会覆盖WithLimit下发的值，且必须为正整数。

AdvancedSearchOptions参数

参数	参数类型	是否必选	参数含义
AcceptPartialSuccessOnMPP	bool	否	MPP检索时是否接受部分分片成功，默认值为false。
SuccessRateLowerBoundOnMPP	double	否	MPP检索的成功率下界，默认值为1.0，取值必须为有限值且在[0, 1]。
TwoPhaseRetrieval	bool	否	是否开启两阶段检索。与`WithDecay`不兼容。

返回参数

SearchResult参数

参数	参数类型	参数含义
hits	std::vector<mochow::SearchHit>	命中结果列表，结构见SearchHit参数。
iterated_ids	std::string	迭代游标，SearchIterator场景由 SDK 内部使用。
metadata	mochow::ResponseMetadata	响应元信息，可通过`RequestId()`、`HttpStatus()`、`ServerCode()`读取。

SearchHit参数

参数	参数类型	参数含义
row	mochow::Row	一行记录。
score	double	相关性得分。如请求携带`WithDecay`，该值为衰变后的最终得分。
distance	double	向量距离，仅当`has_distance`为true时有效。
has_distance	bool	标识`distance`是否有效。
highlight	std::map<std::string, std::vector<std::string>>	高亮片段，仅全文检索携带`WithHighlight`时返回，详见全文检索接口的返回参数。

向量范围检索

功能介绍

基于向量字段值的KNN或ANN范围检索操作，支持通过标量字段值进行过滤。范围检索通过WithDistanceRange在同一个VectorSearchRequest上开启，SDK 会将其编码为distanceNear与distanceFar两个检索参数。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorSearchRequest request;
    request.WithVectorField("vector")
           .WithVector({0.3123F, 0.43F, 0.213F})
           .WithDistanceRange(0.0, 20.0)
           .WithLimit(10)
           .WithParam("ef", uint64_t{200})
           .WithFilter("bookName = '三国演义'")
           .WithProjections({"id", "bookName"});

    mochow::SearchResult result;
    mochow::Status status = table.VectorSearch(request, &result);
    if (!status.IsOk()) {
        std::cerr << "range search failed: " << status.Message() << std::endl;
        return 1;
    }
    std::cout << "hits: " << result.hits.size() << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

参数结构与向量TopK检索的VectorSearchRequest参数一致，范围检索额外要求：

参数	参数类型	是否必选	参数含义
WithDistanceRange	double, double	是	范围检索场景中的最近距离与最远距离，最近距离在前，取值约束如下：任意距离算法下，distanceFar都必须大于等于distanceNear，不支持小于当索引距离为L2时，distanceFar和distanceNear仅支持正数当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0] distanceFar与distanceNear需要成对出现

返回参数

返回结构见向量TopK检索的SearchResult参数。

批量向量检索

功能介绍

基于多个向量字段值的KNN或ANN检索操作，支持通过标量字段值进行过滤。仅适用于多节点标准版，不支持单节点免费测试版。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorBatchSearchRequest request;
    request.WithVectorField("vector")
           .AddVectors({
               {0.3123F, 0.43F, 0.213F},
               {0.5F, 0.32F, 0.513F},
           })
           .WithLimit(10)
           .WithParam("ef", uint64_t{200})
           .WithFilter("bookName = '三国演义'")
           .WithProjections({"id", "bookName"});

    mochow::BatchSearchResult result;
    mochow::Status status = table.VectorBatchSearch(request, &result);
    if (!status.IsOk()) {
        std::cerr << "batch vector search failed: " << status.Message()
                  << std::endl;
        return 1;
    }
    for (const mochow::BatchSearchItem& item : result.results) {
        std::cout << "hits: " << item.hits.size() << std::endl;
    }

    (void)client->Close();
    return 0;
}
            

请求参数

VectorBatchSearchRequest参数

参数	参数类型	是否必选	参数含义
WithVectorField	std::string	是	检索的指定向量字段名称。
WithVectors / AddVector / AddVectors	std::vector<mochow::FloatVector> / mochow::FloatVector	是	检索的目标向量字段值列表，不能为空。
WithLimit	int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为10。
WithDistanceRange	double, double	否	范围检索场景中的最近距离与最远距离，取值约束与向量范围检索一致。
WithParam	std::string, mochow::FieldValue	否	向量检索算法的运行参数，见向量TopK检索的向量检索运行参数。
WithFilter	std::string	否	检索的标量过滤条件，默认为空。
WithPartitionKey	mochow::Row	否	目标记录的分区键值，未指定时该检索请求可能退化为MPP检索。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	检索请求的一致性级别，取值为`Eventual`（默认值）或`Strong`。
WithAdvancedOptions	mochow::AdvancedSearchOptions	否	高级检索选项，见向量TopK检索的AdvancedSearchOptions参数。

返回参数

BatchSearchResult参数

参数	参数类型	参数含义
results	std::vector<mochow::BatchSearchItem>	每个检索向量对应一组结果，元素包含`search_vector`（本路检索向量）与`hits`（命中列表，结构见SearchHit参数）。
metadata	mochow::ResponseMetadata	响应元信息。

多向量检索

功能介绍

对多个向量列分别进行相似性检索，对多路结果进行融合排序后返回最终结果。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorSearchRequest first;
    first.WithVectorField("vector1")
         .WithVector({1.0F, 0.21F, 0.213F, 0.0F})
         .WithLimit(100)
         .WithParam("ef", uint64_t{200});

    mochow::VectorSearchRequest second;
    second.WithVectorField("vector2")
          .WithVector({1.0F, 0.32F, 0.513F, 0.0F})
          .WithLimit(100)
          .WithParam("ef", uint64_t{200});

    // 子检索不支持单独设置 filter，过滤条件统一放在外层请求上
    mochow::MultiVectorSearchRequest request;
    request.AddVectorSearches({first, second})
           .WithRanking(mochow::FusionRankPolicy::RRF(60))
           .WithLimit(100)
           .WithFilter("bookName = '三国演义'")
           .WithProjections({"id", "bookName"});

    mochow::SearchResult result;
    mochow::Status status = table.MultiVectorSearch(request, &result);
    if (!status.IsOk()) {
        std::cerr << "multi vector search failed: " << status.Message()
                  << std::endl;
        return 1;
    }
    std::cout << "hits: " << result.hits.size() << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

MultiVectorSearchRequest参数

参数	参数类型	是否必选	参数含义
AddVectorSearch / AddVectorSearches	mochow::VectorSearchRequest / std::vector<mochow::VectorSearchRequest>	是	多向量检索每路的检索向量及其检索参数，至少需要两路子检索。子检索中只有`WithVectorField`、`WithVector`、`WithLimit`、`WithParam`、`WithWeight`生效，`filter`等公共参数需设置在外层请求上。
WithRanking	mochow::FusionRankPolicy	否	融合排序算法参数，详见FusionRankPolicy参数。
WithLimit	int	否	请求返回的向量记录数量，默认为10，必须大于0。该参数表示对每路检索的结果进行融合排序之后，将分值最高的`limit`条向量返回，可以与每路子检索的`WithLimit`不同。
WithFilter	std::string	否	检索的标量过滤条件，默认为空。
WithPartitionKey	mochow::Row	否	目标记录的分区键值，未指定时该检索请求可能退化为MPP检索。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	检索请求的一致性级别，取值为`Eventual`（默认值）或`Strong`。
WithAdvancedOptions	mochow::AdvancedSearchOptions	否	高级检索选项，见向量TopK检索的AdvancedSearchOptions参数。
WithDecay / AddDecay	std::vector<mochow::DecayRanker> / mochow::DecayRanker	否	衰变排名器配置，详见全文检索接口中的DecayRanker参数。

FusionRankPolicy参数

参数	参数类型	是否必选	参数含义
FusionRankPolicy::RRF(k)	uint64_t	否	RRF融合排序算法，`k`默认值为60，必须大于0。
FusionRankPolicy::Weighted(weights)	std::vector<double>	否	加权融合排序算法（协议中的`ws`策略），权重数量必须与子检索路数一致，每个权重必须为有限值且大于0。

返回参数

返回结构见向量TopK检索的SearchResult参数。

全文检索

功能介绍

基于关键字的全文检索（BM25），支持通过标量字段值进行过滤，支持请求级同义词、命中词高亮与衰变重排。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>
#include <utility>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::Highlight highlight;
    highlight.Field("segment",
                    mochow::HighlightField().FragmentSize(80)
                                            .NumberOfFragments(2))
             .PreTags({"<em>"})
             .PostTags({"</em>"});

    mochow::BM25SearchRequest request;
    request.WithIndexName("book_segment_inverted_idx")
           .WithQuery("吕布")
           .WithLimit(10)
           .WithFilter("bookName = '三国演义'")
           // 每个同义词必须是单个 term
           .WithSynonyms({{"吕布", "奉先"}})
           .WithHighlight(std::move(highlight))
           .AddDecay(mochow::DecayRanker(mochow::DecayType::Linear,
                                         "publishTime",
                                         1735660800.0,
                                         31536000.0)
                         .Name("publish_time_decay")
                         .Weight(0.3))
           .WithProjections({"id", "bookName", "segment"})
           .WithReadConsistency(mochow::ReadConsistency::Strong);

    mochow::SearchResult result;
    mochow::Status status = table.BM25Search(request, &result);
    if (!status.IsOk()) {
        std::cerr << "bm25 search failed: " << status.Message() << std::endl;
        return 1;
    }
    for (const mochow::SearchHit& hit : result.hits) {
        std::cout << "score: " << hit.score << std::endl;
        for (const auto& entry : hit.highlight) {
            for (const std::string& fragment : entry.second) {
                std::cout << entry.first << ": " << fragment << std::endl;
            }
        }
    }

    (void)client->Close();
    return 0;
}
            

请求参数

BM25SearchRequest参数

参数	参数类型	是否必选	参数含义
WithIndexName	std::string	是	倒排索引的名字，不能为空。索引处于BUILDING状态时发起检索会返回错误码95（Index Building）。
WithQuery	std::string	是	全文检索的检索表达式（UTF-8编码），对应协议中的`searchText`，不能为空。几种常见用法： `content:数据库`：在content这列搜索“数据库”关键字 `content:百度VectorDB数据库`：在content这列匹配“百度VectorDB数据库”中任意关键字 `content:"百度VectorDB数据库"`：搜索短语“百度VectorDB数据库” `content:百度 AND content:VectorDB`：在content列同时匹配“百度”“VectorDB”关键字 `content:百度 OR content:VectorDB`：在content列匹配“百度”“VectorDB”的任意一个更多用法见全文检索表达式。
WithLimit	int	否	指定返回相关性最高的条目数，默认为10，必须大于0。
WithFilter	std::string	否	检索的标量过滤条件，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
WithWeight	double	否	该路检索在混合检索中的权重，取值必须为有限值且大于0。
WithSynonyms / AddSynonymGroup	std::vector<std::vector<std::string>> / std::vector<std::string>	否	请求级同义词规则，每个内部数组表示一组等价同义词，例如`{{"土豆", "马铃薯"}, {"优势", "优点"}}`，检索“土豆”时可以匹配到“马铃薯”。使用说明：同义词仅支持单个term（大致等价于一个单词），超过该范围的同义词行为未定义内部数组包含0个或1个词时会被忽略；SDK 对空数组直接返回`StatusCode::InvalidArgument` 每个同义词会使用`WithIndexName`指定的倒排索引的分词器解析，包括分词、大小写归一化和停用词过滤；如某个成员被停用词完全消除，整个请求会失败，不会自动忽略该成员同义词只影响本次检索的解析与召回，不会写入索引，也不影响后续请求
WithHighlight	mochow::Highlight	否	全文检索高亮配置，详见Highlight参数；不设置时不返回高亮信息。注：过宽的通配、前缀或范围查询（如PrefixQuery命中term数超过1024）可能导致请求失败，此时请调窄查询条件或关闭高亮。
WithDecay / AddDecay	std::vector<mochow::DecayRanker> / mochow::DecayRanker	否	衰变排名器配置。配置后服务端会基于指定的数值或时间类型字段对原始相关性得分做衰变重排，返回的`score`为衰变后的最终得分。注：衰变排名器与`AdvancedSearchOptions`中的两阶段检索（`TwoPhaseRetrieval(true)`）不兼容。
WithPartitionKey	mochow::Row	否	目标记录的分区键值，未指定时该检索请求可能退化为MPP检索。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	检索请求的一致性级别，取值为`Eventual`（默认值）或`Strong`。
WithAdvancedOptions	mochow::AdvancedSearchOptions	否	高级检索选项，见向量TopK检索的AdvancedSearchOptions参数。

Highlight参数

参数	参数类型	是否必选	参数含义
Field	std::string, mochow::HighlightField	是	需要高亮的字段及其字段级配置，可多次调用。字段必须属于`WithIndexName`指定的倒排索引。SDK 要求至少配置一个字段，否则返回`StatusCode::InvalidArgument`。
PreTags	std::vector<std::string>	否	命中词前置标记，默认为`["<em>"]`。支持配置多个tag，多个命中会按顺序轮转使用。
PostTags	std::vector<std::string>	否	命中词后置标记，默认为`["</em>"]`。同时显式配置`PreTags`和`PostTags`时，二者数量必须一致。

HighlightField参数

参数	参数类型	是否必选	参数含义
FragmentSize	uint32_t	否	当前字段每个高亮片段的目标长度，默认100，取值范围为[1, 2147483647]。该值为目标长度而非严格上限，为保留完整词语，实际片段长度可能存在差异。
NumberOfFragments	uint32_t	否	当前字段最多返回的片段数，默认3，取值范围为[0, 10000]。设置为0时不切片，返回完整字段的高亮结果。

DecayRanker参数

参数	参数类型	是否必选	参数含义
DecayRanker(type, field_name, origin, scale)	mochow::DecayType, std::string, double, double	是	构造衰变排名器，四个参数均必填。`origin`与`scale`必须为有限值。
type	mochow::DecayType	是	衰变函数类型，取值为： `Linear`：线性衰变 `Exponential`：指数衰变，需同时指定`DecayRate` `Gaussian`：高斯衰变
field_name	std::string	是	参与衰变计算的字段名（协议字段为`fieldName`），需为数值或时间类型字段，不能为空。
origin	double	是	衰变的原点，字段值距离原点越远，衰变得分越低。
scale	double	是	衰变的尺度，用于控制衰变速度。
Name	std::string	否	衰变函数名称，便于区分多个衰变函数。
DecayRate	double	否	指数衰变率，仅`Exponential`类型生效且必填，取值必须大于0。值越大衰变越快，`1.0`为常用基准。
Offset	double	否	衰变的偏移量，字段值与`origin`的距离在`offset`之内时不衰变。
Reverse	bool	否	是否反向衰变，即距离`origin`越远得分越高。
Weight	double	否	该衰变函数在最终得分中的权重。
MinScore	double	否	衰变得分下限，起保底作用。
MaxScore	double	否	衰变得分上限。

注：WithDecay接受一个列表，每个元素表示一个独立的衰变函数，多个函数可以使用相同或不同的字段，不按数组顺序依次执行。

返回参数

请求中携带WithHighlight时，每条命中结果会额外返回highlight。

参数	参数类型	参数含义
row	mochow::Row	一行记录。
score	double	全文检索相关性得分。如请求携带衰变排名器，该值为衰变后的最终得分。
highlight	std::map<std::string, std::vector<std::string>>	仅在请求携带`WithHighlight`时返回，key为字段名，value为高亮片段数组，例如`{"segment": ["<em>吕布</em>字奉先"]}`。已请求高亮但当前行没有可返回片段时返回空对象，对应`highlight`为空map。

注：PreTags和PostTags会原样插入返回片段，服务端不做HTML转义；如需直接渲染为HTML，请自行处理转义与可信渲染策略。

全文检索表达式

检索类型	用法	例子	例子含义	备注
关键词检索	`field_name:keyword` `field_name:(keyword_1, keyword_2)`	`title:数据库` `title:(数据库百度)`	在title这列搜索“数据库”关键字在title这列搜索“数据库”“百度”关键字，满足任意一个即可
关键词检索	`keyword` `keyword_1 AND keyword_2`	`数据库` `数据库 AND 百度`	在content这列上搜索“数据库”关键字在content这列上搜索，要求同时包括“数据库”“百度”关键字	只适用于在单列上建立倒排索引的情况。对于多列倒排索引，必须使用上述 `field_name:keyword` 的方式指定检索词。
复合检索: AND/OR	`query_1 AND query_2` `query_1 OR query_2` `(query_1 OR query_2) AND query_3`	`title:数据库 AND title:百度` `title:数据库 OR title:百度` `(title:数据库 OR title:百度) AND content:VectorDB`	在title这列搜索，要求同时包括“数据库”“百度”这2个关键字在title这列搜索，要求包括“数据库”“百度”任意一个在title这列搜索，要求包括“数据库”“百度”任意一个，同时content列包含“VectorDB”关键字
Phrase检索	`field_name:"phrase"`	`title:"百度VectorDB数据库"`	在title这列搜索“百度VectorDB数据库”短语	短语必须使用双引号
Match检索	`field_name:statement`	`content:百度VectorDB的优缺点`	在content这列搜索“百度VectorDB的优缺点”的任意词，匹配词数量越多，相关性得分越高
Prefix检索	`field_name:keyword*`	`title:数据*`	在title这列检索，包含以“数据”为前缀词的文档
更改查询权重	`field_name:keyword^boost`	`title:数据库^2 OR content:百度`	title包括“数据库”关键字，或content包含“百度”关键字，最后计算相关性得分时，title列匹配的文档权重系数为2，content列匹配的权重系数为1	不设置boost的话，默认权重都是1

全文检索表达式会将一些特殊字符用于专用目的，如想在表达式中匹配一些特殊字符，需要用 \ 符号进行转义。当前被征用特殊字符包括：

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

注：在C++字符串字面量中书写转义符时需要额外转义反斜杠，例如"百度自研的向量数据库\\:VectorDB"。

混合检索

功能介绍

同时进行关键字全文检索和向量检索，检索结果融合排序后返回，也支持通过标量属性进行过滤。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorSearchRequest vector_part;
    vector_part.WithVectorField("vector")
               .WithVector({0.3123F, 0.43F, 0.213F})
               .WithLimit(10)
               .WithParam("ef", uint64_t{200})
               .WithWeight(0.5);

    mochow::BM25SearchRequest text_part;
    text_part.WithIndexName("book_segment_inverted_idx")
             .WithQuery("吕布")
             .WithLimit(10)
             .WithWeight(0.5);

    mochow::HybridSearchRequest request;
    request.AddVectorSearch(vector_part)
           .AddBM25Search(text_part)
           .WithLimit(10)
           .WithFilter("bookName = '三国演义'")
           .WithProjections({"id", "bookName"})
           .WithReadConsistency(mochow::ReadConsistency::Strong);

    mochow::SearchResult result;
    mochow::Status status = table.HybridSearch(request, &result);
    if (!status.IsOk()) {
        std::cerr << "hybrid search failed: " << status.Message() << std::endl;
        return 1;
    }
    std::cout << "hits: " << result.hits.size() << std::endl;

    (void)client->Close();
    return 0;
}
            

请求参数

HybridSearchRequest参数

参数	参数类型	是否必选	参数含义
AddVectorSearch / AddVectorSearches	mochow::VectorSearchRequest / std::vector<mochow::VectorSearchRequest>	否	向量检索的详细参数，当前最多支持一路向量子请求。子请求的`WithWeight`表示该路结果在融合排序中的权重。
AddBM25Search / AddBM25Searches	mochow::BM25SearchRequest / std::vector<mochow::BM25SearchRequest>	否	全文检索的详细参数，当前最多支持一路BM25子请求。子请求的`WithWeight`表示该路结果在融合排序中的权重。
WithLimit	int	否	返回的最相关条目数，默认为10，必须大于0。
WithFilter	std::string	否	检索的标量过滤条件，默认为空。作为全局参数下发。
WithPartitionKey	mochow::Row	否	目标记录的分区键值，未指定时该检索请求可能退化为MPP检索。
WithProjections / AddProjection / AddProjections	std::vector<std::string> / std::string	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
WithRetrieveVector	bool	否	是否返回结果记录中的向量字段值，默认值为false。
WithReadConsistency	mochow::ReadConsistency	否	检索请求的一致性级别，取值为`Eventual`（默认值）或`Strong`。
WithAdvancedOptions	mochow::AdvancedSearchOptions	否	高级检索选项，见向量TopK检索的AdvancedSearchOptions参数。
WithDecay / AddDecay	std::vector<mochow::DecayRanker> / mochow::DecayRanker	否	衰变排名器配置，作用于融合排序后的结果，返回的`score`为衰变后的最终得分。参数结构请参见全文检索接口中的DecayRanker参数。

注：混合检索中的BM25同义词（WithSynonyms）和高亮（WithHighlight）在BM25子请求中配置；WithLimit和WithFilter为全局参数，需设置在HybridSearchRequest上。至少需要一路子请求，向量或BM25子请求超过一路时 SDK 返回StatusCode::NotSupported。

返回参数

返回结构见向量TopK检索的SearchResult参数；BM25子请求携带高亮时，命中行的highlight同样会返回。

SearchIterator

功能介绍

SearchIterator 提供了一种分页获取搜索结果的机制。在 SearchIterator 请求中，检索请求的WithLimit用于指定当前分页的返回结果数量，且必须与batch_size相等。通过多次调用迭代器，可以突破单次检索的 topK 数量限制，逐步获取完整的结果集。对于 topK 值较大的搜索请求，推荐使用 SearchIterator 来实现结果的分批次获取。

请求示例

                C++
                
            

                #include <iostream>
#include <memory>

#include "mochow/Mochow.h"

int main() {
    mochow::ClientOptions options;
    options.endpoint = "http://127.0.0.1:5287";  // $您的实例访问端点
    options.credentials.account = "root";
    options.credentials.api_key = "$您的账户API密钥";

    auto client_result = mochow::MochowClient::Create(options);
    if (!client_result.IsOk()) {
        std::cerr << "create client failed: "
                  << client_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::MochowClient> client = client_result.MoveValue();
    mochow::Database db = client->GetDatabase("db_test");
    mochow::Table table = db.GetTable("book_vector");

    mochow::VectorSearchRequest request;
    request.WithVectorField("vector")
           .WithVector({1.0F, 0.21F, 0.213F})
           .WithLimit(1000)  // 必须与 batch_size 相等
           .WithParam("ef", uint64_t{2000})
           .WithProjections({"id", "bookName"});

    auto iterator_result = table.NewSearchIterator(request, 1000, 10000);
    if (!iterator_result.IsOk()) {
        std::cerr << "create search iterator failed: "
                  << iterator_result.GetStatus().Message() << std::endl;
        return 1;
    }
    std::shared_ptr<mochow::SearchIterator> iterator =
        iterator_result.MoveValue();

    while (iterator->HasNext()) {
        mochow::SearchResult page;
        mochow::Status status = iterator->Next(&page);
        if (!status.IsOk()) {
            std::cerr << "iterate failed: " << status.Message() << std::endl;
            iterator->Close();
            return 1;
        }
        std::cout << "page hits: " << page.hits.size()
                  << ", returned: " << iterator->ReturnedCount() << "/"
                  << iterator->TotalSize() << std::endl;
    }
    iterator->Close();

    (void)client->Close();
    return 0;
}
            

接口描述

`Table::NewSearchIterator`

功能：初始化mochow::SearchIterator对象。

参数：

参数	参数类型	是否必选	参数含义
request	mochow::VectorSearchRequest、mochow::MultiVectorSearchRequest、mochow::BM25SearchRequest 或 mochow::HybridSearchRequest	是	检索请求参数描述信息。`partition_key`、`projections`、`read_consistency`等公共参数直接设置在该请求对象上。
batch_size	int	是	每批次检索获取记录条数，必须大于0，且必须与请求的`WithLimit`相等。
total_size	int	是	获取记录总条数，不能小于`batch_size`。

返回类型：mochow::Result<std::shared_ptr<mochow::SearchIterator>>。参数不合法时返回StatusCode::InvalidArgument，向量请求携带WithDistanceRange时返回StatusCode::NotSupported。

`SearchIterator::HasNext`

功能：判断是否还有下一批结果。
参数：无。
返回类型：bool。

`SearchIterator::Next`

功能：执行检索，并将本批结果写入输出参数。当返回结果为空时，说明 SearchIterator 执行结束。

参数：

参数	参数类型	是否必选	参数含义
result	mochow::SearchResult*	是	输出参数，用于接收本批检索结果，不能为空指针。
options	mochow::RequestOptions	否	单次请求级选项。

返回类型：mochow::Status。

`SearchIterator::ReturnedCount` / `SearchIterator::TotalSize`

功能：分别返回已获取的记录条数与初始化时指定的记录总条数。
参数：无。
返回类型：int。

`SearchIterator::Close`

功能：释放 SearchIterator。执行Close后，不应该再调用Next。
参数：无。
返回类型：无。

限制

仅支持 HNSW、HNSWPQ、IVF、IVFSQ、IVFPQ、IVFRABITQ 索引类型。
仅支持向量TopK检索（VectorSearchRequest）、多向量检索（MultiVectorSearchRequest）、全文检索（BM25SearchRequest）、混合检索（HybridSearchRequest），不支持向量范围检索、批量向量检索。
对于多向量检索，仅支持ws融合排序算法，即FusionRankPolicy::Weighted。

评价此篇文章

有帮助没帮助

Java SDK

Table 操作

向量数据库 VectorDB

Row 操作

插入记录

功能介绍

请求示例

请求参数

返回参数

插入或更新记录

功能介绍

请求示例

请求参数

返回参数

更新记录

功能介绍

请求示例

请求参数

返回参数

删除记录

功能介绍

请求示例

请求参数

返回参数

标量查询

功能介绍

请求示例

请求参数

返回参数

批量标量查询

功能介绍

请求示例

请求参数

返回参数

标量过滤查询

功能介绍

请求示例

请求参数

返回参数

向量TopK检索

功能介绍

请求示例

请求参数

返回参数

向量范围检索

功能介绍

请求示例

请求参数

返回参数

批量向量检索

功能介绍

请求示例

请求参数

返回参数

多向量检索

功能介绍

请求示例

请求参数

返回参数

全文检索

功能介绍

请求示例

请求参数

返回参数

混合检索

功能介绍

请求示例

请求参数

返回参数

SearchIterator

功能介绍

请求示例

接口描述

Table::NewSearchIterator

SearchIterator::HasNext

SearchIterator::Next

SearchIterator::ReturnedCount / SearchIterator::TotalSize

SearchIterator::Close

限制

`Table::NewSearchIterator`

`SearchIterator::HasNext`

`SearchIterator::Next`

`SearchIterator::ReturnedCount` / `SearchIterator::TotalSize`

`SearchIterator::Close`