数据操作

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

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

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

插入 upsert接口

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

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

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

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

插入时不指定唯一标识id

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "documents": [{
        "field_int": 90399,
        "field_float": 90399,
        "field_double": 90399,
        "field_string": "111399",
        "field_vector": [...]
    }, {
        "field_int": 45085,
        "field_float": 45085,
        "field_double": 45085,
        "field_string": "106085",
        "field_vector":  [...]
    }, {
        "field_int": 52968,
        "field_float": 52968,
        "field_double": 52968,
        "field_string": "113968",
        "field_vector":  [...]
    }]
}
' http://${VEARCH_URL}/document/upsert

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

插入时指定唯一标识

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "documents": [{
        "_id": "1000000",
        "field_int": 90399,
        "field_float": 90399,
        "field_double": 90399,
        "field_string": "111399",
        "field_vector":  [...]
    }, {
        "_id": "1000001",
        "field_int": 45085,
        "field_float": 45085,
        "field_double": 45085,
        "field_string": "106085",
        "field_vector": [...]
    }, {
        "_id": "1000002",
        "field_int": 52968,
        "field_float": 52968,
        "field_double": 52968,
        "field_string": "113968",
        "field_vector": [...]
    }]
}
' http://${VEARCH_URL}/document/upsert

upsert接口返回值格式如下

{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 3,
        "document_ids": [
            {
                "_id": "-526059949411103803"
            },
            {
                "_id": "1287805132970120733"
            },
            {
                "_id": "-1948185285365684656"
            }
        ]
    }
}

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 接口参数说明:

字段标识

类型

是否必填

备注

document_ids

string数组

查询条件, filters和document_ids必须包含一项

partition_id

int

指定在哪个partition获取数据, 与document_ids结合使用

filters

json数组

查询条件过滤: 数值过滤 + 标签过滤, filter和document_ids必须包含一项

fields

string数组

指定返回那些字段, 默认返回除向量字段外的所有字段

vector_value

bool

默认false,是否返回向量

limit

int

指定返回结果数量,默认50

  • filter json结构说明

"filters": {
    "operator": "AND",
    "conditions": [
        {
            "field": "field_int",
            "operator": ">=",
            "value": 1
        },
        {
            "field": "field_int",
            "operator": "<=",
            "value": 3
        },
        {
            "field": "field_string",
            "operator": "IN",
            "value": ["aaa", "bbb"]
        }
    ]
}

filters 格式说明:

字段标识

类型

是否必填

备注

operator

string

目前只支持AND

conditions

json数组

详细过滤条件

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

conditions 格式说明:

字段标识

类型

是否必填

备注

field

string

过滤字段名

operator

string

操作符, 支持 >, >=, <, <=, IN

value

json

过滤值

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

根据唯一id标识查找数据

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "document_ids": ["6560995651113580768", "-5621139761924822824", "-104688682735192253"],
    "vector_value": true
}
' http://${VEARCH_URL}/document/query

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

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

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

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "filters": {
        "operator": "AND",
        "conditions": [
            {
                "field": "field_int",
                "operator": ">=",
                "value": 1
            },
            {
                "field": "field_int",
                "operator": "<=",
                "value": 3
            }
        ]
    }
}
' http://${VEARCH_URL}/document/query

query接口返回格式

{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 3,
        "documents": [{
            "_id": "6560995651113580768",
            "field_double": 202558,
            "field_float": 102558,
            "field_int": 1558,
            "field_string": "1558"
        }, {
            "_id": "-5621139761924822824",
            "field_double": 210887,
            "field_float": 110887,
            "field_int": 89887,
            "field_string": "89887"
        }, {
            "_id": "-104688682735192253",
            "field_double": 207588,
            "field_float": 107588,
            "field_int": 46588,
            "field_string": "46588"
        }]
    }
}

删除 delete接口

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

删除指定document_ids

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "document_ids": ["4501743250723073467", "616335952940335471", "-2422965400649882823"]
}
' http://${VEARCH_URL}/document/delete

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

curl -H "content-type: application/json" -XPOST -d'
{
    "db_name": "ts_db",
    "space_name": "ts_space",
    "filters": {
        "operator": "AND",
        "conditions": [
            {
                "field": "field_int",
                "operator": ">=",
                "value": 1
            },
            {
                "field": "field_int",
                "operator": "<=",
                "value": 3
            }
        ]
    },
    "limit": 3
}
' http://${VEARCH_URL}/document/delete

delete接口返回格式

{
    "code": 0,
    "msg": "success",
    "data": {
        "total": 3,
        "document_ids": ["4501743250723073467", "616335952940335471", "-2422965400649882823"]
    }
}