Skip to main content

Query (V2)

Milvus version compatibility
Server-side sorting, grouping, and search aggregation parameters (orderByFields, groupByFields, searchAggregation) take effect only on clusters compatible with Milvus v3.0.x or later. On Zilliz Cloud, serverless clusters are compatible with Milvus v3.0.x, while Dedicated clusters are compatible with Milvus v2.6.x unless upgraded to the v3.0.x Public Preview.

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

POST/v2/vectordb/entities/query
Connection Endpoint

The base URL for this API is in the following format:

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

📘Notes
  • Use the cluster endpoint if you are using serving clusters.

    • Free & Serverless

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

    • Dedicated

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

  • You need to fill in ${CLUSTER_ENDPOINT} with that of your Zilliz Cloud cluster.
  • To get the endpoint, use the Describe Cluster V2 API to extract the values from the responses.
shell
export CLUSTER_ENDPOINT="https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530"
Parameters
Authorizationstringheader

The authentication token should be an API key with appropriate privileges or a pair of colon-joined username and password, like username:password. If you are using a project endpoint, only a valid API key with sufficient permissions applies.

Example Value: Bearer {{TOKEN}}
Request Bodyapplication/json
dbNamestring

The name of the database.

collectionNamestringrequired

The name of the collection to which this operation applies.

filterstring

The filter used to find matches for the search.

outputFieldsarray

An array of fields to return along with the query results.

[]outputFieldsstring

An output field name.

partitionNamesarray

The name of the partitions to which this operation applies. Setting this parameter restricts the operation to the specified partitions. If not set, the operation applies to all partitions in the collection.

[]partitionNamesstring

A partition name.

limitinteger

The total number of entities to return. You can use this parameter in combination with offset in param to enable pagination. The sum of this value and offset in param should be less than 16,384.

offsetinteger

The number of records to skip in the search result. You can use this parameter in combination with limit to enable pagination. The sum of this value and limit should be less than 16,384.

exprParamsobject

Expression template parameter values for parameterized filter expressions.

consistencyLevelstring

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

orderByFieldsarray

The scalar fields used to sort query results. Each item can be a field name, fieldName:asc, or fieldName:desc. The default sort direction is ascending.

[]orderByFieldsstringPublic Preview

A scalar field and optional sort direction.

Example Value: word_count:desc
groupByFieldsarray

The names of the fields used to group the query results. Each entry identifies one grouping field.

[]groupByFieldsstringPublic Preview

A single field name used to group the query results.

bash
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,
    "orderByFields": [
        "color:asc"
    ]
}'
Responses200 OK - application/json

A list of dictionaries with each dictionary representing a queried entity.

A response payload variant that the query operation can return.

codeinteger

Response code.

costinteger

Cost of this operation. This applies to free and serverless clusters only, indicating the vCU usage of the current request.

dataarray

A list of dictionaries with each dictionary representing a queried entity.

[]dataobject

An entity object

idoneOf

The primary key value of the returned entity. Milvus primary keys are Int64 or VarChar depending on the collection schema, so the value may arrive as a number or a string.

integer
(To be added soon)
string
(To be added soon)
grpstring

The group that this result belongs to, present when groupingField is specified.

count(*)number

The aggregated count of the group, present when a group-by count-only query is performed.

scanned_remote_bytesinteger

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

scanned_total_bytesinteger

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

cache_hit_rationumber

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

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