跳到主要内容

查询 (V2)

This operation conducts a filtering on the scalar field with a specified boolean expression.

POST/v2/vectordb/entities/query
连接端点

该 API 的 Base URL 格式如下：

https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

📘说明
  • 如果您使用的是服务集群，请使用集群端点。

    • Free 与 Serverless 版

      https://{cluster-id}.serverless.{region}.vectordb.zillizcloud.com

    • Dedicated 版

      https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530

  • 你需要填入您的 Zilliz Cloud 集群的 ${CLUSTER_ENDPOINT}。
  • 您可以使用 查看集群详情 V2 来获取集群的 Endpoint.
export CLUSTER_ENDPOINT="https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530"
参数
Authorizationstringheader

认证令牌，应为具备适当权限的 API 密钥或用冒号分隔的用户名和密码，如 username:password。

示例值：Bearer {{TOKEN}}
请求体application/json
dbNamestring

数据库名称。

collectionNamestring必填项

Collection 名称。

filterstring

用于对标量字段进行过滤的表达式。

outputFieldsarray

需要在查询结果中返回的字名称数组。

[]outputFieldsstring

随查询结果返回的字段名称。

partitionNamesarray

Partition 名称列表。设置此参数可限制操作范围到指定的 Partition。未设置时，操作范围为 Collection 中的所有 Partition。

[]partitionNamesstring

Partition 名称。

limitinteger

需要在搜索结果中返回的 Entity 数量。 您可以使用此参数与 offset 参数结合使用以实现分页。 此值与 offset 参数之和不应超过 16,384。

offsetinteger

需要在搜索结果中跳过的 Entity 数量。 您可以使用此参数与 limit 参数结合使用以实现分页。 此值与 limit 参数之和不应超过 16,384。

exprParamsobject

Expression template parameter values for parameterized filter expressions.

consistencyLevelstring

Consistency level. Possible values are Strong, Session, Bounded, and Eventually.

export TOKEN="db_admin:xxxxxxxxxxxxx"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/query" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "collectionName": "quick_setup",
    "filter": "color like \"red_%\"",
    "outputFields": [
        "color"
    ],
    "limit": 3
}'
响应200 - application/json
codeinteger

响应码。

costinteger

当前操作的花费。仅用于 Free 和 Serverless 集群，表示当前操作消耗的 vCU。

dataarray

查询到的 Entity 列表，每个字典表示一个查询到的 Entity。

[]dataobject

Entity 对象。

scanned_remote_bytesinteger

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

scanned_total_bytesinteger

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

cache_hit_rationumber

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

返回错误消息。

codeinteger

响应码。

messagestring

错误描述。

{
    "code": 0,
    "cost": 0,
    "data": [
        {
            "color": "red_7025",
            "id": 1
        },
        {
            "color": "red_4794",
            "id": 4
        },
        {
            "color": "red_9392",
            "id": 6
        }
    ]
}