数据操作

http://${VEARCH_URL} 代表vearch服务, $db_name是创建的库名, $space_name是创建的空间名, $id是数据记录的唯一id.

_id 是服务端生成的记录唯一标识，可以由用户指定，对数据的修改和删除需要使用该唯一标识。

$id 是插入数据时使用指定的值替换服务端生成的唯一标识，$id值不能使用url路径等特殊字符。若库中已存在该唯一标识的记录则更新覆盖。

插入 upsert接口

如果设置了主键_id, 则将使用指定的主键。 如果未设置, 则由 Vearch 生成。

如果插入时指定的_id已经存在, 则更新现有数据; 否则, 它将被插入。

当插入数据中的documents包含多条数据, 则为批量插入, 一般建议批量插入不超过100条。

插入和更新现在支持只传入部分字段的值, 插入时只传入部分字段必须包含向量字段, 更新时无此限制。

插入时不指定唯一标识id

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "documents": [{
6. "field_int": 90399,
7. "field_float": 90399,
8. "field_double": 90399,
9. "field_string": "111399",
10. "field_vector": [...]
11. }, {
12. "field_int": 45085,
13. "field_float": 45085,
14. "field_double": 45085,
15. "field_string": "106085",
16. "field_vector":  [...]
17. }, {
18. "field_int": 52968,
19. "field_float": 52968,
20. "field_double": 52968,
21. "field_string": "113968",
22. "field_vector":  [...]
23. }]
24. }
25. ' http://${VEARCH_URL}/document/upsert

field_vector是向量字段, 其它字段为标量字段。所有字段名、值类型和定义表结构时保持一致。

插入时指定唯一标识

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "documents": [{
6. "_id": "1000000",
7. "field_int": 90399,
8. "field_float": 90399,
9. "field_double": 90399,
10. "field_string": "111399",
11. "field_vector":  [...]
12. }, {
13. "_id": "1000001",
14. "field_int": 45085,
15. "field_float": 45085,
16. "field_double": 45085,
17. "field_string": "106085",
18. "field_vector": [...]
19. }, {
20. "_id": "1000002",
21. "field_int": 52968,
22. "field_float": 52968,
23. "field_double": 52968,
24. "field_string": "113968",
25. "field_vector": [...]
26. }]
27. }
28. ' http://${VEARCH_URL}/document/upsert

upsert接口返回值格式如下

1. {
2. "code": 0,
3. "msg": "success",
4. "data": {
5. "total": 3,
6. "document_ids": [
7. {
8. "_id": "-526059949411103803"
9. },
10. {
11. "_id": "1287805132970120733"
12. },
13. {
14. "_id": "-1948185285365684656"
15. }
16. ]
17. }
18. }

total 标识插入成功的数量, document_ids返回生成的_id和插入结果信息。

精确查找 query接口

/document/query 接口用于精确查找与查询条件完全匹配的数据, 查找时不可包含向量数据。

支持两种方式: 一种是直接通过主键获取文档, 另一种是根据过滤条件获取对应的文档。

如果直接通过document_ids获取文档时设置了partition_id, 则获取指定数据分区上对应的文档。 此时document_id的含义就是该分区上的文档编号。

document_id可以是指定分区的[0, max_docid], max_docid和partition_id信息可以通过 <http://master_server/dbs/$db_name/spaces/$space_name> 接口获取。 可以通过这种方式获取集群的完整数据。

query 接口参数说明:

• filter json结构说明

1. "filters": {
2. "operator": "AND",
3. "conditions": [
4. {
5. "field": "field_int",
6. "operator": ">=",
7. "value": 1
8. },
9. {
10. "field": "field_int",
11. "operator": "<=",
12. "value": 3
13. },
14. {
15. "field": "field_string",
16. "operator": "IN",
17. "value": ["aaa", "bbb"]
18. }
19. ]
20. }

filters 格式说明:

1. filter 条件支持多个, 多个条件之间是交的关系, 即最外层operator目前支持AND。

conditions 格式说明:

(2) conditions 具体过滤条件, 目前支持两类字段类型过滤, 数值类型和字符串类型(包括字符串数组类型) 数值类型操作符: >, >=, <, <= ; 字符串操作符类型 IN

根据唯一id标识查找数据

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "document_ids": ["6560995651113580768", "-5621139761924822824", "-104688682735192253"],
6. "vector_value": true
7. }
8. ' http://${VEARCH_URL}/document/query

获取指定数据分区上对应的文档, 此时document_id可以是指定分区的[0, max_docid]

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "document_ids": ["0", "1", "2"],
6. "partition_id": 1,
7. "vector_value": true
8. }
9. ' http://${VEARCH_URL}/document/query

根据自定义的标量字段的 Filter 表达式查找

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "filters": {
6. "operator": "AND",
7. "conditions": [
8. {
9. "field": "field_int",
10. "operator": ">=",
11. "value": 1
12. },
13. {
14. "field": "field_int",
15. "operator": "<=",
16. "value": 3
17. }
18. ]
19. }
20. }
21. ' http://${VEARCH_URL}/document/query

query接口返回格式

1. {
2. "code": 0,
3. "msg": "success",
4. "data": {
5. "total": 3,
6. "documents": [{
7. "_id": "6560995651113580768",
8. "field_double": 202558,
9. "field_float": 102558,
10. "field_int": 1558,
11. "field_string": "1558"
12. }, {
13. "_id": "-5621139761924822824",
14. "field_double": 210887,
15. "field_float": 110887,
16. "field_int": 89887,
17. "field_string": "89887"
18. }, {
19. "_id": "-104688682735192253",
20. "field_double": 207588,
21. "field_float": 107588,
22. "field_int": 46588,
23. "field_string": "46588"
24. }]
25. }
26. }

模糊查询 search接口

根据向量数值进行相似度检索, 返回指定的 limit 个最相似的 Document。

参数说明:

查询参数整体json简单示例如下:

1. {
2. "vectors": [],
3. "filters": [],
4. "index_params": {"nprobe": 20},
5. "fields": ["field1", "field2"],
6. "is_brute_search": 0,
7. "vector_value": false,
8. "load_balance": "leader",
9. "limit": 10,
10. "ranker": {
11. "type": "WeightedRanker",
12. "params": [0.5, 0.5]
13. }
14. }

index_params 参数指定索引计算时的参数, 不同索引支持的参数不同, 如下示例:

• metric_type: 计算类型, 支持InnerProduct和L2, 默认L2。
• nprobe: 搜索桶数量。
• recall_num: 精排召回数量, 默认等于查询参数中limit的值, 设置从索引中查询到结果之后利用原始向量重新计算距离重新排序。
• parallel_on_queries: 默认1, 搜索间并行; 0代表桶间并行。
• efSearch: 图遍历的距离。

IVFPQ

1. "index_params": {
2. "parallel_on_queries": 1,
3. "recall_num" : 100,
4. "nprobe": 80,
5. "metric_type": "L2"
6. }

8. 当设置recall_num会用原始向量做计算重排(精排)

GPU

1. "index_params": {
2. "recall_num" : 100,
3. "nprobe": 80,
4. "metric_type": "L2"
5. }

HNSW

1. "index_params": {
2. "efSearch": 64,
3. "metric_type": "L2"
4. }

IVFFLAT

1. "index_params": {
2. "parallel_on_queries": 1,
3. "nprobe": 80,
4. "metric_type": "L2"
5. }

FLAT

1. "index_params": {
2. "metric_type": "L2"
3. }

• vectors json结构说明:

1. "vectors": [{
2. "field": "field_name",
3. "feature": [0.1, 0.2, 0.3, 0.4, 0.5],
4. "min_score": 0.9
5. }]

1. vector 支持多个(对应定义表结构时包含多个特征字段)。
2. field 指定创建表时特征字段的名称。
3. feature 传递特征, 维数和定义表结构时维数必须相同。

4. min_score 指定返回结果中分值必须大于等于0.9, min_score可以指定返回结果分值最小值, max_score可以指定最大值。如设置: “min_score”: 0.8, “max_score”: 0.95 代表过滤0.8<= 分值<= 0.95 的结果。同时另外一种分值过滤的方式是使用: “symbol”:”>=”, “value”:0.9 这种组合方式, symbol支持的值类型包含: > 、 >= 、 <、 <= 4种, value及min_score、max_score值在0到1之间。

5. filter json结构说明:

参考query接口部分对filter json的说明

• is_brute_search 0使用索引搜索(建完索引前查询结果为空), 1使用暴力搜索, 默认值0。
• vector_value 为了减小网络开销, 搜索结果中默认不包含特征数据只包含标量信息字段, 设置成true指定返回结果中包含原始特征数据。
• load_balance leader, random, no_leader, least_connection, 默认random。leader仅从主数据节点查询, random: 从ps主从节点随机选择, no_leader:只查询从节点, least_connection: 最少连接数。
• limit 指定最多返回的结果数量。若请求url中设置了limit值, 优先使用url中指定的limit值。

根据向量查询 支持单条或者多条查询, 多条可以将多个查询的特征拼接成一个特征数组(比如定义128维的特征, 批量查询10条, 则将10个128维特征按顺序拼接成1280维特征数组赋值给feature字段), 后台接收到请求后按表结构定义的特征字段维度进行拆分, 按顺序返回匹配结果。

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "vectors": [
4. {
5. "field": "field_vector",
6. "feature": [
7. "..."
8. ]
9. }
10. ],
11. "filters": {
12. "operator": "AND",
13. "conditions": [
14. {
15. "field": "field_int",
16. "operator": ">=",
17. "value": 1
18. },
19. {
20. "field": "field_int",
21. "operator": "<=",
22. "value": 3
23. },
24. {
25. "field": "field_string",
26. "operator": "IN",
27. "value": [
28. "aaa",
29. "bbb"
30. ]
31. }
32. ]
33. },
34. "index_params": {
35. "metric_type": "L2"
36. },
37. "limit": 3,
38. "db_name": "ts_db",
39. "space_name": "ts_space"
40. }
41. ' http://${VEARCH_URL}/document/search

多向量查询 表空间定义时支持多个特征字段, 因此查询时可以支持相应数据的特征进行查询。以每条记录两个向量为例: 定义表结构字段

1. {
2. "field_vector1": {
3. "type": "vector",
4. "dimension": 128
5. },
6. "field_vector2": {
7. "type": "vector",
8. "dimension": 256
9. }
10. }

field_vector1、field_vector2均为向量字段, 查询时搜索条件可以指定两个向量:

1. {
2. "vectors": [{
3. "field": "field_vector1",
4. "feature": [...]
5. },
6. {
7. "field": "field_vector2",
8. "feature": [...]
9. }],
10. "ranker": {
11. "type": "WeightedRanker",
12. "params": [0.5, 0.5]
13. }
14. }

field1和field2过滤的结果求交集, 其他参数及请求地址和普通查询一致。

search接口返回格式

1. {
2. "code": 0,
3. "msg": "success",
4. "data": {
5. "documents": [
6. [{
7. "_id": "6979025510302030694",
8. "_score": 16.55717658996582,
9. "field_double": 207598,
10. "field_float": 107598,
11. "field_int": 6598,
12. "field_string": "6598",
13. }, {
14. "_id": "-104688682735192253",
15. "_score": 17.663991928100586,
16. "field_double": 207588,
17. "field_float": 107588,
18. "field_int": 46588,
19. "field_string": "46588"
20. }, {
21. "_id": "8549822044854277588",
22. "_score": 17.88829803466797,
23. "field_double": 220413,
24. "field_float": 120413,
25. "field_int": 99413,
26. "field_string": "99413"
27. }]
28. ]
29. }
30. }

删除 delete接口

删除支持两种方法: 指定document_ids和过滤条件。

删除指定document_ids

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "document_ids": ["4501743250723073467", "616335952940335471", "-2422965400649882823"]
6. }
7. ' http://${VEARCH_URL}/document/delete

删除满足过滤条件的文档, limit指定每个数据分片删除的条数

1. curl -H "content-type: application/json" -XPOST -d'
2. {
3. "db_name": "ts_db",
4. "space_name": "ts_space",
5. "filters": {
6. "operator": "AND",
7. "conditions": [
8. {
9. "field": "field_int",
10. "operator": ">=",
11. "value": 1
12. },
13. {
14. "field": "field_int",
15. "operator": "<=",
16. "value": 3
17. }
18. ]
19. },
20. "limit": 3
21. }
22. ' http://${VEARCH_URL}/document/delete

delete接口返回格式

1. {
2. "code": 0,
3. "msg": "success",
4. "data": {
5. "total": 3,
6. "document_ids": ["4501743250723073467", "616335952940335471", "-2422965400649882823"]
7. }
8. }