如何通过HTTP API在Collection中进行相似性检索 - DashVector

This topic describes how to perform similarity searches in a collection by using the HTTP API.

Prerequisites

A cluster is created. For more information, see Create a cluster.
An API key is obtained. For more information, see Manage API keys.
The SDK of the latest version is installed. For more information, see Install DashVector SDK.

Method and URL

HTTP

POST https://{Endpoint}/v1/collections/{CollectionName}/query

Example

Note

You need to replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster in the sample code for the code to run properly.
You need to create a collection named quickstart in advance. For more information, see the "Example" section of the Create a collection topic.

Perform a similarity search by using a vector

Shell

curl -XPOST \
  -H 'dashvector-auth-token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "topk": 10,
    "include_vector": true
  }' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query

# example output:
# {
#   "code": 0,
#   "request_id": "2cd1cac7-f1ee-4d15-82a8-b65e75d8fd13",
#   "message": "Success",
#   "output": [
#     {
#       "id": "1",
#       "vector":[
#         0.10000000149011612,
#         0.20000000298023224,
#         0.30000001192092896,
#         0.4000000059604645
#       ],
#       "fields": {
#         "name": "zhangshan",
#         "weight": null,
#         "age": 20,
#         "anykey": "anyvalue"
#       },
#       "score": 0.3
#     }
#   ]
# }

Perform a similarity search by using the vector associated with the primary key

Shell

curl -XPOST \
  -H 'dashvector-auth-token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "1",
    "topk": 1,
    "include_vector": true
  }' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query

# example output:
# {
#   "code":0,
#   "request_id":"fab4e8a2-15e4-4b55-816f-3b66b7a44962",
#   "message":"Success",
#   "output":[
#     {
#       "id":"1",
#       "vector":[
#         0.10000000149011612,
#         0.20000000298023224,
#         0.30000001192092896,
#         0.4000000059604645
#       ],
#        "fields": {
#         "name": "zhangshan",
#         "weight": null,
#         "age": 20,
#         "anykey": "anyvalue"
#       },
#       "score": 0.3
#     }
#   ]
# }

Perform a similarity search by using the vector or primary key and a conditional filter

Shell

curl -XPOST \
  -H 'dashvector-auth-token: sk-YdC9WPy9DBJslHlC81u74hb8xHPRb33C1216835E211EEBCBC7A664A2F9815' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": "age > 18",
    "topk": 1,
    "include_vector": true
  }' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query
  
# example output:
# {
#   "code":0,
#   "request_id":"4c7331d8-fba1-4c3a-8673-124568670de7",
#   "message":"Success",
#   "output":[
#     {
#       "id":"1",
#       "vector":[
#         0.10000000149011612,
#         0.20000000298023224,
#         0.30000001192092896,
#         0.4000000059604645
#       ],
#        "fields": {
#         "name": "zhangshan",
#         "weight": null,
#         "age": 20,
#         "anykey": "anyvalue"
#       },
#       "score": 0.0
#     }
#   ]
# }

Perform a similarity search by using both dense and sparse vectors

Shell

curl -XPOST \
  -H 'dashvector-auth-token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.1, 0.2, 0.3, 0.4],
    "sparse_vector":{"1":0.4, "10000":0.6, "222222":0.8},
    "topk": 1,
    "include_vector": true
  }' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/query

# example output:
# {
#   "code":0,
#   "request_id":"ad84f7a0-b4b2-4023-ae80-b6f092609a53",
#   "message":"Success",
#   "output":[
#     {
#       "id":"2",
#       "vector":[
#         0.10000000149011612,
#         0.20000000298023224,
#         0.30000001192092896,
#         0.4000000059604645
#       ],
#       "fields":{"name":null,"weight":null,"age":null},
#       "score":1.46,
#       "sparse_vector":{
#         "10000":0.6,
#         "1":0.4,
#         "222222":0.8
#       }
#     }
#   ]
# }

Request parameters

Note

To perform a similarity search, you need to specify either the vector or id field. If neither is specified, the system performs a match query only by using a conditional filter.

Parameter	Location	Type	Required	Description
{Endpoint}	path	str	Yes	The endpoint of the cluster. You can view the endpoint on the cluster details page in the console.
{CollectionName}	path	str	Yes	The name of the collection.
dashvector-auth-token	header	str	Yes	The API key.
vector	body	array	No	The vector.
sparse_vector	body	dict	No	The sparse vector.
id	body	str	No	The primary key. The similarity search is performed based on the vector associated with the primary key.
topk	body	int	No	The number of top results to be returned by similarity. Default value: 10.
filter	body	str	No	The conditional filter, which must comply with the syntax of the SQL WHERE clause. For more information, see Conditional filtering.
include_vector	body	bool	No	Specifies whether to return the vector. Default value: false.
output_fields	body	array	No	The list of fields to be returned. All fields are returned by default. If the value is [], no fields are returned.
partition	body	str	No	The name of the partition.

Response parameters

Parameter	Type	Description	Example
code	int	The returned status code. For more information, see Status codes.	0
message	str	The returned message.	success
request_id	str	The unique ID of the request.	19215409-ea66-4db9-8764-26ce2eb5bb99
output	array	The list of similar documents that are returned.