Skip to main content

Search

This operation conducts a vector similarity search with an optional scalar filtering expression.

POST
/v2/vectordb/entities/search
Cluster Endpoint

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

https://${CLUSTER_ENDPOINT}

📘Notes
  • 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.
export CLUSTER_ENDPOINT=""
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges or a pair of colon-joined username and password, like username:password.

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

The name of the database.

collectionNamestringrequired

The name of the collection to which this operation applies.

dataarrayrequired

A list of vector embeddings. Zilliz Cloud searches for the most similar vector embeddings to the specified ones.

[]datanumber<float32>

A vector embedding

annsFieldstringrequired

The name of the vector field.

filterstring

The filter used to find matches for the search.

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.

groupingFieldstring

The name of the field that serves as the aggregation criteria.

outputFieldsarray

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

[]outputFieldsstring

A field name

searchParamsobject

The parameter settings specific to this operation.

metricTypestring

The name of the metric type that applies to the current search. The value should be the same as the metric type of the target collection.

paramsobject

Extra search parameters.

radiusnumber<float64>

Determines the threshold of least similarity. When setting metrictype to L2, ensure that this value is greater than that of rangefilter. Otherwise, this value should be lower than that of range_filter.

range_filternumber<float64>

Refines the search to vectors within a specific similarity range. When setting metric_type to IP or COSINE, ensure that this value is greater than that of radius. Otherwise, this value should be lower than that of radius.

partitionNamesarray

The name of the partitions to which this operation applies. Setting this parameter indicates that the search is within the specified partitions. Otherwise, the search is across all partitions in the collection.

[]partitionNamesstring

A partition name.

consistencyLevelstring

The consistency level of the search operation. The value should be the same as the consistency level of the target collection.

export TOKEN="db_admin:xxxxxxxxxxxxx"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/search" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
    "collectionName": "quick_setup",
    "data": [
        [
            0.3580376395471989,
            -0.6023495712049978,
            0.18414012509913835,
            -0.26286205330961354,
            0.9029438446296592
        ]
    ],
    "annsField": "vector",
    "limit": 3,
    "outputFields": [
        "color"
    ]
}'
Responses200 - application/json
codeinteger

Response code.

dataarray

A list of entity objects.

[]dataobject

An entity object.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

{
    "code": 0,
    "data": [
        {
            "color": "orange_6781",
            "distance": 1,
            "id": 448300048035776800
        },
        {
            "color": "red_4794",
            "distance": 0.9353201,
            "id": 448300048035776800
        },
        {
            "color": "grey_8510",
            "distance": 0.7733054,
            "id": 448300048035776800
        }
    ]
}