Row 操作

更新时间：2026-09-01

插入记录

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	// create alias
25	data := []api.Row{
26		{
27			Fields: map[string]interface{}{
28				"id":       "0001",
29				"bookName": "西游记",
30				"author":   "吴承恩",
31				"vector":   []float32{0.2123, 0.21, 0.213},
32			},
33		},
34		{
35			Fields: map[string]interface{}{
36				"id":       "0002",
37				"bookName": "西游记",
38				"author":   "吴承恩",
39				"vector":   []float32{0.2123, 0.22, 0.213},
40			},
41		},
42	}
43
44	insertArgs := &api.InsertRowArgs{
45		Database: "db_test",
46		Table:    "table_test",
47		Rows:     data,
48	}
49
50	insertResult, err := client.InsertRow(insertArgs)
51	if err != nil {
52		log.Fatalf("Fail to insert row due to error: %v", err)
53		return
54	}
55	log.Printf("insert row response: %v", insertResult)
56}

请求参数

参数	参数类型	是否必选	参数含义
insertRowArgs	InsertRowArgs	是	插入的记录。

InsertRowArgs

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Rows	List	是	插入的记录。

插入或更新记录

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	// create alias
25	data := []api.Row{
26		{
27			Fields: map[string]interface{}{
28				"id":       "0001",
29				"bookName": "西游记",
30				"author":   "吴承恩",
31				"vector":   []float32{0.2123, 0.21, 0.213},
32			},
33		},
34		{
35			Fields: map[string]interface{}{
36				"id":       "0002",
37				"bookName": "西游记",
38				"author":   "吴承恩",
39				"vector":   []float32{0.2123, 0.22, 0.213},
40			},
41		},
42	}
43
44	upsertArgs := &api.UpsertRowArg{
45		Database: "db_test",
46		Table:    "table_test",
47		Rows:     data,
48	}
49
50	upsertResult, err := client.UpsertRow(upsertArgs)
51	if err != nil {
52		log.Fatalf("Fail to insert row due to error: %v", err)
53		return
54	}
55	log.Printf("upsert row response: %v", upsertResult)
56}

请求参数

参数	参数类型	是否必选	参数含义
upsertArgs	UpsertRowArgs	是	插入的记录。

UpsertRowArgs

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Rows	List	是	插入的记录。

更新记录

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	updateArgs := &api.UpdateRowArgs{
25		Database: "db_test",
26		Table:    "table_test",
27		PrimaryKey: map[string]interface{}{
28			"id": "0001",
29		},
30		Update: map[string]interface{}{
31			"bookName": "红楼梦",
32			"author":   "曹雪芹",
33		},
34	}
35	err = client.UpdateRow(updateArgs)
36	if err != nil {
37		log.Fatalf("Fail to update row due to error: %v", err)
38		return
39	}
40}

请求参数

参数	参数类型	是否必选	参数含义
updateArgs	UpdateRowArgs	是	更新记录请求参数。

UpdateRowArgs

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
PrimaryKey	Object	是	指定记录的主键值。
PartitionKey	Object	否	指定记录的分区键值。如果该表的分区键和主键是同一个键，则不需要填写分区键值。只有在有主键值的情况下，分区键值才会生效。
Update	Object	是	待更新的字段列表及其新值。不允许更新主键、分区键和向量字段。

删除记录

功能介绍

删除数据表中的指定记录。

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	// delete row
25	deleteArgs := &api.DeleteRowArgs{
26		Database: "db_test",
27		Table:    "table_test",
28		PrimaryKey: map[string]interface{}{
29			"id": "0001",
30		},
31	}
32
33	err = client.DeleteRow(deleteArgs)
34	if err != nil {
35		log.Fatalf("Fail to delete row due to error: %v", err)
36		return
37	}
38}

请求参数

参数	参数类型	是否必选	参数含义
deleteArgs	DeleteRowArgs	是	删除记录请求参数。

DeleteRowArgs

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

标量查询

功能介绍

基于主键值的点查操作。

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	queryArgs := &api.QueryRowArgs{
25		Database: "db_test",
26		Table:    "table_test",
27		PrimaryKey: map[string]interface{}{
28			"id": "0001",
29		},
30		Projections:    []string{"id", "bookName"},
31		RetrieveVector: false,
32		// 查询该主键相对于向量索引 vector_idx 的逻辑覆盖状态
33		VectorIndexMembership: &api.VectorIndexMembership{
34			IndexName: "vector_idx",
35		},
36	}
37
38	queryResult, err := client.QueryRow(queryArgs)
39	if err != nil {
40		log.Fatalf("Fail to query row due to error: %v", err)
41		return
42	}
43	log.Printf("query row response: %v", queryResult)
44	if queryResult.VectorIndexMembership != nil {
45		log.Printf("vector index membership state: %v", queryResult.VectorIndexMembership.State)
46	}
47}

请求参数

参数	参数类型	是否必选	参数含义
queryArgs	QueryRowArgs	是	标量查询请求参数。

QueryRowArgs

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
PrimaryKey	Object	是	目标记录的主键值。
PartitionKey	Object	否	目标记录的分区键值。
Projections	List	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
RetrieveVector	Boolean	否	是否返回查询结果记录中的向量字段值，默认为False。
ReadConsistency	ReadConsistency	否	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。
VectorIndexMembership	VectorIndexMembership	否	查询目标记录相对于指定向量索引的当前逻辑覆盖状态。只需填写`IndexName`，`State`由服务端返回。注：该参数仅单条查询（QueryRow）支持，批量查询（BatchQueryRow）不支持。

VectorIndexMembership参数

参数	参数类型	是否必选	参数含义
IndexName	String	是	目标向量索引的名称。
State	String	否	请求中无需填写，由服务端在返回结果中填充。

返回参数

参数	参数类型	参数含义
Row	Row	查询到的记录。
VectorIndexMembership	VectorIndexMembership	仅在请求中携带`VectorIndexMembership`时返回，`State`表示目标记录相对于指定向量索引的逻辑覆盖状态，取值为： ROW_NOT_FOUND（api.VectorIndexMembershipRowNotFound）：未查询到该主键对应的记录 NO_VECTOR（api.VectorIndexMembershipNoVector）：记录存在，但索引字段对应的向量为空 KNN（api.VectorIndexMembershipKNN）：记录的向量尚未进入任何向量索引，检索时走暴力计算 DELTA_INDEX（api.VectorIndexMembershipDeltaIndex）：记录的向量已进入增量索引 STABLE_INDEX（api.VectorIndexMembershipStableIndex）：记录的向量已进入全量（stable）索引

说明：

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

标量批量查询

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	batchQueryArgs := &api.BatchQueryRowArgs{
25		Database: "db_test",
26		Table:    "table_test",
27		Keys: []api.QueryKey{
28			{
29				PrimaryKey: map[string]interface{}{
30					"id": "0001",
31				},
32			},
33			{
34				PrimaryKey: map[string]interface{}{
35					"id": "0002",
36				},
37			},
38		},
39		Projections:    []string{"id", "bookName"},
40		RetrieveVector: false,
41	}
42	queryResult, err := client.BatchQueryRow(batchQueryArgs)
43	if err != nil {
44		log.Fatalf("Fail to batch query row due to error: %v", err)
45		return
46	}
47	log.Printf("batch query row response: %v", queryResult)
48}

请求参数

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Keys	List	是	目标记录的主键及分区键
Projections	List	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
RetrieveVector	Boolean	否	是否返回查询结果记录中的向量字段值，默认为False。
ReadConsistency	ReadConsistency	否	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。

QueryKey参数

参数	参数类型	是否必选	参数含义
PrimaryKey	Object	是	目标记录的主键
PartitionKey	Object	否	目标记录的分区键值。如该表的分区键和主键是同一个键，则不需要填写分区键值。

注：批量查询不支持VectorIndexMembership参数，如需查询主键相对于向量索引的逻辑覆盖状态，请使用单条标量查询。

向量TopK检索

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	// search
25	vector := api.FloatVector([]float32{0.3123, 0.43, 0.213})
26	searchArgs := &api.VectorSearchArgs{
27		Database: "db_test",
28		Table:    "table_test",
29		Request: api.VectorTopkSearchRequest{}.
30			New("vector", vector, 5).
31			Filter("bookName='三国演义'").
32			Projections([]string{"id", "bookName", "page"}).
33			// 衰变排名器：基于 page 字段做线性衰变重排
34			Decay([]*api.DecayRanker{
35				api.DecayRanker{}.
36					New(api.LinearDecay, "page", 25, 2).
37					Name("page_decay").
38					Weight(0.3),
39			}).
40			Config(api.VectorSearchConfig{}.New().Ef(200)),
41	}
42
43	searchResult, err := client.VectorSearch(searchArgs)
44	if err != nil {
45		log.Fatalf("Fail to search row due to error: %v", err)
46		return
47	}
48
49	log.Printf("search row response: %v", searchResult)
50}

请求参数

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Request	VectorTopkSearchRequest/VectorRangeSearchRequest	是	检索请求参数描述信息。
Partition_key	Json	否	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
Projections	List	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
ReadConsistency	ReadConsistency	否	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

VectorTopkSearchRequest参数

参数	参数类型	是否必选	参数含义
VectorField	String	是	检索的目标向量字段名称。
Vector	FloatVector	是	检索的目标向量字段值。
Limit	int	否	返回最接近目标向量的向量记录数量，相当于TopK的K值，默认为50
Filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
Decay	List	否	衰变排名器配置。配置后服务端会基于指定的数值或时间类型字段对原始得分做衰变重排，返回的`Score`为衰变后的最终得分。参数结构请参见全文检索接口中的DecayRanker参数。注：`Decay`与`AdvancedOptions`中的两阶段检索（`TwoPhaseRetrieval(true)`）不兼容。
AdvancedOptions	AdvancedOptions	否	检索高级选项，通过`api.NewAdvancedOptions()`创建，支持`AcceptPartialSuccessOnMPP`、`SuccessRateLowerBoundOnMPP`、`TwoPhaseRetrieval`。
Config	VectorSearchConfig	是	向量检索算法的运行参数

VectorRangeSearchRequest参数

参数	参数类型	是否必选	参数含义
VectorField	String	是	检索的目标向量字段名称。
Vector	FloatVector	是	检索的目标向量字段值。
DistanceRange	[float, float]	是	范围检索场景中的最近距离与最远距离，最近距离在前，取值约束如下: 任意距离算法下，distanceFar都必须大于等于distanceNear，不支持小于；当索引距离为L2时，distanceFar和distanceNear仅支持正数；当索引距离为COSINE时，distanceFar和distanceNear的取值范围为[-1.0, 1.0]； distanceFar与distanceNear需要成对出现。
Limit	int	否	与目标向量的距离在约束范围内的最近向量数量，相当于TopK的K值，默认为50
Filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
Decay	List	否	衰变排名器配置，参数结构请参见全文检索接口中的DecayRanker参数。
Config	VectorSearchConfig	是	向量检索算法的运行参数

VectorSearchConfig参数

参数	参数类型	是否必选	参数含义
Ef	int	否	HNSW算法检索过程的动态候选列表的大小。
Pruning	bool	否	HNSW算法检索过程中是否开启剪枝优化
SearchCoarseCount	int	否	PUCK算法检索过程粗聚类中心候选集大小。
NProbe	int	否	IVF系列算法（IVF、IVFSQ、IVFPQ、IVFRABITQ）检索过程中扫描的聚类中心个数。
SearchL	int	否	DISKANN算法检索过程中候选集大小。
FilterMode	FilterMode	否	标量过滤模式，取值为AUTO（api.FilterModeAuto）或POST（api.FilterModePost）。

标量过滤查询

功能介绍

基于标量属性过滤查询记录。

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	selectArgs := &api.SelectRowArgs{
25		Database:    "db_test",
26		Table:       "table_test",
27		Filter:      "id = '001'",
28		Projections: []string{"id", "bookName"},
29		Limit:       10,
30	}
31
32	selectResult, err := client.SelectRow(selectArgs)
33	if err != nil {
34		log.Fatalf("Fail to select row due to error: %v", err)
35		return
36	}
37
38	log.Printf("select row response: %v", selectResult)
39}

请求参数

参数	参数类型	是否必选	参数含义
Filter	String	否	标量过滤条件，表示仅查询符合过滤条件的记录，默认为空。 filter 的表达式格式为 <field_name>，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息。 <field_name>：表示要过滤的字段名：表示要使用的运算符，支持字符串相等（=）、整型相等（==）、不等于（!=）、大于（>）、大于等于（>=）、小于（<）、小于等于（<=）：表示要匹配的值布尔值：true或者false 整型值：常规表示字符串类型：头尾必须使用英文单引号括起来二进制类型：同字符串类型，但是必须采用base64编码日期/时间：同字符串类型
Marker	Json	否	查询的分页起始点，用于控制分页查询返回结果的起始位置，方便用户对数据进行分页展示和浏览，用户不填时，默认从第一条符合条件的记录开始返回。 marker中需要包括主键和分区键。
Projections	List	否	投影字段列表，默认为空，为空时查询结果默认返回所有标量字段。
ReadConsistency	ReadConsistency	否	查询请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，查询请求会随机发送给分片的所有副本； STRONG：强一致性，查询请求只会发送给分片主副本。
Limit	Int	否	查询返回的记录条数，在进行分页查询时，即每页的记录条数。默认为10，取值范围[1, 1000]。

全文检索

功能介绍

基于关键字的全文检索，支持通过标量字段值进行过滤。

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	searchArgs := &api.BM25SearchArgs{
25		Database: "db_test",
26		Table:    "table_test",
27		Request: api.BM25SearchRequest{}.
28			New("book_segment_inverted_idx", "吕布").
29			Limit(12).
30			Filter("bookName='三国演义'").
31			ReadConsistency(api.ReadConsistencyStrong).
32			Projections([]string{"id", "segment"}).
33			// 请求级同义词：检索"吕布"时也可以匹配到"奉先"
34			Synonyms([][]string{{"吕布", "奉先"}}).
35			// 高亮：对 segment 字段返回带标记的命中片段
36			Highlight(
37				api.HighlightParams{}.New().
38					Field(
39						"segment",
40						*api.HighlightField{}.New().
41							FragmentSize(80).
42							NumberOfFragments(2),
43					).
44					PreTags([]string{"<em>"}).
45					PostTags([]string{"</em>"}),
46			).
47			// 衰变排名器：基于 page 字段做线性衰变重排
48			Decay([]*api.DecayRanker{
49				api.DecayRanker{}.
50					New(api.LinearDecay, "page", 25, 2).
51					Name("page_decay").
52					Weight(0.3),
53			}),
54	}
55
56	searchResult, err := client.BM25Search(searchArgs)
57	if err != nil {
58		log.Fatalf("Fail to search row due to error: %v", err)
59		return
60	}
61	log.Printf("search row response: %v", searchResult)
62	for _, row := range searchResult.Rows.Rows {
63		log.Printf("score: %v, highlight: %v", row.Score, row.Highlight)
64	}
65}

请求参数

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Request	BM25SearchRequest	是	全文检索的详细参数
PartitionKey	Json	否	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
Projections	List	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
ReadConsistency	ReadConsistency	否	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

BM25SearchRequest参数

参数名称	类型	是否必填	描述
IndexName	String	是	倒排索引的名字。注：倒排索引创建后异步构建，索引`State`为BUILDING期间发起BM25检索会返回错误码95（Index Building），`State`变为NORMAL后方可检索。
SearchText	String	是	全文检索的检索表达式，UTF-8编码，几种常见用法: content:数据库 ----> 在content这列搜索"数据库"关键字 content: 百度VectorDB数据库 -----> 在content这列匹配"百度VectorDB数据库"中任意关键字 content: "百度VectorDB数据库" -----> 搜索短语"百度VectorDB数据库" content: 百度 AND content: VectorDB ----> 在content这列同时匹配"百度"、"VectorDB" 关键字 content: 百度 OR content: VectorDB. -----> 在content这列匹配"百度"、"VectorDB"的任意一个更多用法见全文检索表达式
Limit	Int	否	指定返回相关性最高的条目数
Filter	String	否	标量过滤条件，表示仅查询符合过滤条件的记录，默认为空。 filter 的表达式格式为 <field_name>，多个表达式之间支持 and（与）、or（或）、not（非）关系。具体信息。 <field_name>：表示要过滤的字段名：表示要使用的运算符，支持字符串相等（=）、整型相等（==）、不等于（!=）、大于（>）、大于等于（>=）、小于（<）、小于等于（<=）：表示要匹配的值布尔值：true或者false 整型值：常规表示字符串类型：头尾必须使用英文单引号括起来二进制类型：同字符串类型，但是必须采用base64编码日期/时间：同字符串类型
Synonyms	List<List>	否	请求级同义词规则，每个内部数组表示一组等价同义词，例如`[][]string{{"土豆", "马铃薯"}, {"优势", "优点"}}`，检索"土豆"时可以匹配到"马铃薯"。使用说明：同义词仅支持单个term（大致等价于一个单词），超过该范围的同义词行为未定义。内部数组包含0个或1个词时会被忽略；同义词成员为空字符串时请求失败。每个同义词会使用`IndexName`指定的倒排索引的分词器解析，包括分词、大小写归一化和停用词过滤；如某个成员被停用词完全消除，整个请求会失败，不会自动忽略该成员。 `Synonyms`只影响本次检索的解析与召回，不会写入索引，也不影响后续请求。
Highlight	HighlightParams	否	全文检索高亮配置，通过`api.HighlightParams{}.New()`创建。传入空配置时使用默认配置；不传时不返回高亮信息。注：过宽的通配、前缀或范围查询（如PrefixQuery命中term数超过1024）可能导致请求失败，此时请调窄查询条件或关闭高亮。
Decay	List	否	衰变排名器配置。配置后服务端会基于指定的数值或时间类型字段对原始相关性得分做衰变重排，返回的`Score`为衰变后的最终得分。注：`Decay`与`AdvancedOptions`中的两阶段检索（`TwoPhaseRetrieval(true)`）不兼容。

HighlightParams参数

通过api.HighlightParams{}.New()创建，并以链式调用方式设置各参数。

参数名称	类型	是否必填	描述
Field(field, config)	String, HighlightField	否	添加一个需要高亮的字段，`field`为字段名，`config`为字段级配置。字段必须属于`IndexName`指定的倒排索引；不设置任何字段时默认对该倒排索引覆盖的所有可高亮字段生成片段。
PreTags	List	否	命中词前置标记，默认为`["<em>"]`。支持配置多个tag，多个命中会按顺序轮转使用。
PostTags	List	否	命中词后置标记，默认为`["</em>"]`。同时显式配置`PreTags`和`PostTags`时，二者数量必须一致。

HighlightField参数

通过api.HighlightField{}.New()创建，并以链式调用方式设置各参数。

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

DecayRanker参数

通过api.DecayRanker{}.New(decayType, fieldName, origin, scale)创建，四个必填参数以位置参数传入，其余可选参数以链式调用方式设置。

参数名称	类型	是否必填	描述
decayType	DecayType	是	衰变函数类型，取值为： LINEAR（api.LinearDecay）：线性衰变 EXPONENTIAL（api.ExponentialDecay）：指数衰变，需同时指定`DecayRate` GAUSSIAN（api.GaussianDecay）：高斯衰变
fieldName	String	是	参与衰变计算的字段名，需为数值或时间类型字段。
origin	Float64	是	衰变的原点，字段值距离原点越远，衰变得分越低。
scale	Float64	是	衰变的尺度，用于控制衰变速度。
Name	String	否	衰变函数名称，便于区分多个衰变函数。
DecayRate	Float64	否	指数衰变率，仅`EXPONENTIAL`类型生效且必填，取值必须大于0。值越大衰变越快，`1.0`为常用基准。
Offset	Float64	否	衰变的偏移量，字段值与`origin`的距离在`Offset`之内时不衰变。
Reverse	Bool	否	是否反向衰变，即距离`origin`越远得分越高。
Weight	Float64	否	该衰变函数在最终得分中的权重。
MinScore	Float64	否	衰变得分下限，起保底作用。
MaxScore	Float64	否	衰变得分上限。

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

返回参数

参数	参数类型	参数含义
Rows	SearchRowResult	检索结果，`Rows.Rows`为命中的记录列表（RowResult）。

RowResult参数

参数	参数类型	参数含义
Row	Row	一行记录。
Score	Float64	全文检索相关性得分。如请求携带`Decay`，该值为衰变后的最终得分。
Highlight	Map<String, List>	仅在请求携带`Highlight`时返回，key为字段名，value为高亮片段数组，例如`{"segment": ["<em>吕布</em>字奉先"]}`。已请求高亮但当前行没有可返回片段时返回空对象。

注：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 这列上搜索，要求同时包括"数据库"、"百度" 关键字	只适用于在单列上建立倒排索引的情况，如在content 这列上建立倒排索引
复合检索: 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.0	不设置boost的话，默认权重都是1.0

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

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

以"百度自研的向量数据库:VectorDB"这个表达式为例，表达式解释器会认为想在"百度自研的向量数据库" 这列上搜索"VectorDB"，这就违背了使用者的初衷，为此需要把表达式写成"百度自研的向量数据库:VectorDB"

混合检索

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow/api"
7	"github.com/baidu/mochow-sdk-go/mochow"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	vector := api.FloatVector([]float32{0.3123, 0.43, 0.213})
25	request := api.HybridSearchRequest{}.
26		New(
27			api.VectorTopkSearchRequest{}.New("vector", vector, 15).Config(api.VectorSearchConfig{}.New().Ef(200)), /*vector search args*/
28			api.BM25SearchRequest{}.New("book_segment_inverted_idx", "吕布").
29				Synonyms([][]string{{"吕布", "奉先"}}).
30				Highlight(
31					api.HighlightParams{}.New().
32						Field(
33							"segment",
34							*api.HighlightField{}.New().NumberOfFragments(0),
35						),
36				), /*BM25 search args*/
37			0.4, /*vector search weight*/
38			0.6  /*BM25 search weight*/).
39		Filter("bookName='三国演义'").
40		Limit(15).
41		// 衰变排名器作用于融合排序后的结果
42		Decay([]*api.DecayRanker{
43			api.DecayRanker{}.
44				New(api.LinearDecay, "page", 25, 2).
45				Name("page_decay"),
46		})
47
48	searchArgs := &api.HybridSearchArgs{
49		Database: "db_test",
50		Table:    "table_test",
51		Request:  request,
52	}
53
54	searchResult, err := client.HybridSearch(searchArgs)
55	if err != nil {
56		log.Fatalf("Fail to search row due to error: %v", err)
57		return
58	}
59
60	log.Printf("hybrid search row response: %v", searchResult)
61}

请求参数

参数	参数类型	是否必选	参数含义
Request	HybridSearchRequest	是	混合检索的详细参数
PartitionKey	Object	否	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
Projections	List	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
ReadConsistency	ReadConsistency	否	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

HybridSearchRequest参数

参数	参数类型	是否必选	参数含义
vectorRequest	VectorSearchRequest	是	向量检索的详细参数
bm25Request	BM25SearchRequest	是	全文检索的详细参数
vectorWeight	float	否	向量检索结果在混合检索中所占权重，默认0.5
bm25Weight	float	否	全文检索结果在混合检索中所占比重，默认0.5
Limit	Int	否	返回的最相关条目数
Filter	String	否	检索的标量过滤条件，表示仅在符合过滤条件的候选集中进行检索，默认为空。Filter表达式语法参照SQL的WHERE子句语法进行设计，其详细描述和使用示例请参见Filter条件表达式。
Decay	List	否	衰变排名器配置，作用于融合排序后的结果，返回的`Score`为衰变后的最终得分。参数结构请参见全文检索接口中的DecayRanker参数。
AdvancedOptions	AdvancedOptions	否	检索高级选项，通过`api.NewAdvancedOptions()`创建。注：`Decay`与`TwoPhaseRetrieval(true)`不兼容。

注：混合检索中的BM25同义词（Synonyms）和高亮（Highlight）在bm25Request中配置，命中行的高亮片段通过RowResult.Highlight返回；Limit和Filter为全局参数，会覆盖vectorRequest、bm25Request中的同名设置。倒排索引State为BUILDING期间发起混合检索会返回错误码95（Index Building）。

SearchIterator

功能介绍

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

请求示例

1package main
2
3import (
4	"log"
5
6	"github.com/baidu/mochow-sdk-go/mochow"
7	"github.com/baidu/mochow-sdk-go/mochow/api"
8)
9
10func main() {
11	clientConfig := &mochow.ClientConfiguration{
12		Account:  "root",
13		APIKey:   "您的账户API密钥",
14		Endpoint: "您的实例访问端点", // 例如：'http://127.0.0.1:5287'
15	}
16
17	// create mochow client
18	client, err := mochow.NewClientWithConfig(clientConfig)
19	if err != nil {
20		log.Fatalf("Fail to init mochow client due to error:%v", err)
21		return
22	}
23
24	vector := api.FloatVector([]float32{0.3123, 0.43, 0.213})
25	batchSize := uint32(1000)
26	request := api.VectorTopkSearchRequest{}.
27		New("vector", vector, batchSize).
28		Filter("bookName='三国演义'").
29		Config(api.VectorSearchConfig{}.New().Ef(batchSize))
30
31	iterator, err := client.SearchIterator(&api.SearchIteratorArgs{
32		Database:        "db_test",
33		Table:           "table_test",
34		Request:         request,
35		BatchSize:       batchSize,
36		TotalSize:       10000,
37		Projections:     []string{"id", "bookName", "author"},
38		ReadConsistency: api.ReadConsistencyEventual,
39	})
40	if err != nil {
41		log.Fatalf("Fail to create search iterator due to error: %v", err)
42		return
43	}
44	defer iterator.Close()
45
46	totalRows := 0
47	for {
48		rows, err := iterator.Next()
49		if err != nil {
50			log.Fatalf("Fail to fetch search results due to error: %v", err)
51			return
52		}
53		if len(rows) == 0 {
54			break
55		}
56		log.Printf("received batch with %d rows", len(rows))
57		totalRows += len(rows)
58	}
59	log.Printf("retrieved a total of %d rows", totalRows)
60}

请求参数

参数	参数类型	是否必选	参数含义
Database	String	是	库名。
Table	String	是	表名。
Request	VectorTopkSearchRequest/MultivectorSearchRequest/BM25SearchRequest/HybridSearchRequest	是	检索请求参数描述信息。请求中的`Limit`必须与`BatchSize`相等。
BatchSize	Uint32	是	每批次检索获取的记录条数。
TotalSize	Uint32	是	获取记录的总条数，不能小于`BatchSize`。
PartitionKey	Json	否	目标记录的分区键值，如果该表的分区键和主键是同一个键，则不需要填写分区键值。需要注意的是，如果没有指定分区键值，那么该检索请求可能会退化为在该表所有分片上都执行的MPP检索。
Projections	List	否	投影字段列表，默认为空，为空时检索结果返回所有标量字段。
ReadConsistency	ReadConsistency	否	检索请求的一致性级别，取值为： EVENTUAL（默认值）：最终一致性，检索请求会随机发送给分片的所有副本； STRONG：强一致性，检索请求只会发送给分片主副本。

接口描述

`Client.SearchIterator`

功能：初始化SearchIterator对象。
参数：*api.SearchIteratorArgs，字段说明见上文请求参数。
返回类型：*api.SearchIterator。

`SearchIterator.Next`

功能：执行检索并返回当前批次的检索结果。返回结果为空时，说明SearchIterator执行结束。
参数：无。
返回类型：[]api.RowResult。

`SearchIterator.Close`

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

限制

仅支持HNSW、HNSWPQ、IVF、IVFSQ、IVFPQ、IVFRABITQ索引类型。
仅支持向量TopK检索（VectorTopkSearchRequest）、多向量检索（MultivectorSearchRequest）、全文检索（BM25SearchRequest）、混合检索（HybridSearchRequest），不支持向量范围检索（VectorRangeSearchRequest）和批量向量检索（VectorBatchSearchRequest）。
对于多向量检索，仅支持ws（api.WeightedRank）融合排序算法。

评价此篇文章

有帮助没帮助

Alias 操作

Index 操作

向量数据库 VectorDB

Row 操作

插入记录

功能介绍

请求示例

请求参数

插入或更新记录

功能介绍

请求示例

请求参数

更新记录

功能介绍

请求示例

请求参数

删除记录

功能介绍

请求示例

请求参数

标量查询

功能介绍

请求示例

请求参数

返回参数

标量批量查询

功能介绍

请求示例

请求参数

向量TopK检索

功能介绍

请求示例

请求参数

标量过滤查询

功能介绍

请求示例

请求参数

全文检索

功能介绍

请求示例

请求参数

返回参数

混合检索

功能介绍

请求示例

请求参数

SearchIterator

功能介绍

请求示例

请求参数

接口描述

Client.SearchIterator

SearchIterator.Next

SearchIterator.Close

限制

`Client.SearchIterator`

`SearchIterator.Next`

`SearchIterator.Close`