Milvus RESTful API
Overview
With the RESTful API, you can use Milvus by sending HTTP requests to the Milvus server web port. The RESTful API is available as long as you have a running Milvus server. You can set the web port in the Milvus configuration file. Refer to Milvus Configuration for more information.
API Reference
/state
Checks whether the web server is running.
Request
| Request Component |
Value |
| Name |
/state |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Response
| Status code |
Description |
| 200 |
The request is successful. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/state" -H "accept: application/json"
Response
{ "message": "Success", "code": 0 }
/devices
Gets CPU/GPU information from the host.
Request
| Request Component |
Value |
| Name |
/devices |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/devices" -H "accept: application/json"
Response
{ "cpu": { "memory": 31 }, "gpus": { "GPU0": { "memory": 5 } } }
/config/advanced (GET)
Gets the values of parameters in cache_config and engine_config of the Milvus configuration file.
Request
| Request Component |
Value |
| Name |
/config/advanced |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/config/advanced" -H "accept: application/json"
Response
{
"cpu_cache_capacity": 4,
"cache_insert_data": false,
"use_blas_threshold": 1100,
"gpu_search_threshold": 1000
}
/config/advanced (PUT)
Updates the values of parameters in cache_config and engine_config of the Milvus configuration file.
Request
| Request Component | Value |
|---|
| Name | /config/advanced
|
| Header | accept: application/json
|
| Body |
{
"cpu_cache_capacity": integer($int64),
"cache_insert_data": boolean,
"use_blas_threshold": integer($int64),
"gpu_search_threshold": integer($int64)
}
|
| Method | PUT |
Note: gpu_search_config is available only in GPU-supported Milvus.
Body Parameters
| Parameter |
Description |
Required? |
cpu_cache_capacity |
Value of cpu_cache_capacity in the Milvus configuration file. The default is 4. |
No |
cache_insert_data |
Value of cache_insert_data in the Milvus configuration file. The default is false. |
No |
use_blas_threshold |
Value of use_blas_threshold in the Milvus configuration file. The default is 1100. |
No |
gpu_search_threshold |
Value of gpu_search_threshold in the Milvus configuration file. The default is 1000. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/config/advanced" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"cpu_cache_capacity\":4,\"cache_insert_data\":false,\"use_blas_threshold\":1100,\"gpu_search_threshold\":1000}"
Response
{ "message": "OK", "code": 0 }
/config/advanced (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/config/advanced |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/config/advanced"
/config/gpu_resources (GET)
Gets the parameter values in gpu_resource_config of the Milvus configuration file.
Note: This method is available only for GPU-supported Milvus.
Request
| Request Component |
Value |
| Name |
/config/gpu_resources |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/config/gpu_resources" -H "accept: application/json"
Response
{
"enable": true,
"cache_capacity": 1,
"search_resources": ["GPU0"],
"build_index_resources": ["GPU0"]
}
/config/gpu_resources (PUT)
Updates the parameter values in gpu_resource_config of the Milvus configuration file.
Note: This method is available only for GPU-supported Milvus.
Request
| Request Component | Value |
|---|
| Name | /config/gpu_resources
|
| Header | accept: application/json
|
| Body |
{
"enable": boolean,
"cache_capacity": integer($int64),
"search_resources": [string],
"build_index_resources": [string]
}
|
| Method | PUT |
Body Parameters
| Parameter |
Description |
Required? |
enable |
Specifies whether to enable GPU resources. |
Yes |
cache_capacity |
Size of GPU memory per card used for cache in GBs. |
Yes |
search_resources |
GPU devices used for search computation, must be in format gpux. |
Yes |
build_index_resources |
GPU devices used for index building, must be in format gpux. |
Yes |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/config/gpu_resources" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"enable\":true,\"cache_capacity\":1,\"search_resources\":[\"GPU0\"],\"build_index_resources\":[\"GPU0\"]}"
Response
{ "message": "OK", "code": 0 }
/config/gpu_resources (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Note: This method is available only for GPU-supported Milvus.
Request
| Request Component |
Value |
| Name |
/config/gpu_resources |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/config/gpu_resources"
/collections (GET)
Gets all collections starting from offset and ends with page_size.
Request
| Request Component |
Value |
| Name |
/collections |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
offset |
Row offset from which the data page starts. The default is 0. |
No |
page_size |
Size of the data page. The default is 10. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections?offset=0&page_size=1" -H "accept: application/json"
Response
{
"collections": [
{
"collection_name": "test_collection",
"dimension": 1,
"index_file_size": 10,
"metric_type": "L2",
"count": 0,
"index": "FLAT",
"index_params": {"nlist": 4096}
}
],
"count": 58
}
/collections (POST)
Creates a collection.
Request
| Request Component | Value |
|---|
| Name | /tables
|
| Header | accept: application/json
|
| Body |
{
"collection_name": string,
"dimension": integer($int64),
"index_file_size": integer($int64),
"metric_type": string
}
|
| Method | POST |
Body Parameters
| Parameter |
Description |
Required? |
collection_name |
The name of the collection to create, which must be unique within its database. |
Yes |
dimension |
The dimension of the vectors that are to be inserted into the created collection. |
Yes |
index_file_size |
Threshold value that triggers index building for raw data files. The default is 1024. |
No |
metric_type |
The method vector distances are compared in Milvus. The default is L2. Currently supported metrics include L2 (Euclidean distance), IP (Inner Product), HAMMING (Hamming distance), JACCARD (Jaccard distance), and TANIMOTO (Tanomoto distance). |
No |
Response
| Status code |
Description |
| 201 |
Created |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X POST "http://127.0.0.1:19121/collections" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"collection_name\":\"test_collection\",\"dimension\":1,\"index_file_size\":10,\"metric_type\":\"L2\"}"
Response
{ "message": "OK", "code": 0 }
/collections (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/collections |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/collections"
/collections/{collection_name} (GET)
Gets all information about a collection by name.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name} |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
info |
Type of information to acquire. info must either be empty or stat. When info is empty, Milvus returns collection name, dimension, index file size, metric type, offset, index type, and nlist of the collection. When info is stat, Milvus returns the collection offset, partition status, and segment status. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection" -H "accept: application/json"
Response
{
"collection_name": "test_collection",
"dimension": 1,
"index_file_size": 10,
"metric_type": "L2",
"count": 0,
"index": "FLAT",
"index_params": {"nprobe": 16384}
}
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection?info=stat" -H "accept: application/json"
Response
{
"count": 150000,
"partitions_stat": [
{
"count": 1000,
"partition_tag": "_default",
"segments_stat": [
{
"count": 1000,
"index": "FLAT",
"segment_name": "1583727170217439000",
"size": 5284922
}
]
}
]
}
/collections/{collection_name} (DELETE)
Drops a collection by name.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name} |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
DELETE |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 204 |
Deleted |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X DELETE "http://127.0.0.1:19121/collections/test_collection" -H "accept: application/json"
If the deletion is successful, no message will be returned.
/collections/{collection_name} (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/collections/{collection_name} |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/collections/test_collection"
/collections/{collection_name}/indexes (GET)
Gets the index type and nlist of a collection.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/indexes |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection/indexes" -H "accept: application/json"
Response
{ "index_type": "FLAT", "params": { "nlist": 4096 } }
/collections/{collection_name}/indexes (POST)
Updates the index type and nlist of a collection.
Request
| Request Component | Value |
|---|
| Name | /tables
|
| Header | accept: application/json
|
| Body |
{
"index_type": string,
"params": {
......
}
}
|
| Method | POST |
Body Parameters
| Parameter |
Description |
Required? |
index_type |
The type of indexing method to query the collection. Please refer to Milvus Indexes for detailed introduction of supported indexes. The default is "FLAT". |
No |
params |
The extra params of indexing method to query the collection. Please refer to Index and search parameters for detailed introduction of supported indexes. |
No |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 201 |
Created |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X POST "http://127.0.0.1:19121/collections/test_collection/indexes" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"index_type\":\"IVFFLAT\",\"params\": {\"nlist\":4096}}"
Response
{ "message": "OK", "code": 0 }
/collections/{collection_name}/indexes (DELETE)
Drops an index for a collection.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/indexes |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
DELETE |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 204 |
Deleted |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
Resource not available |
Example
Request
$ curl -X DELETE "http://127.0.0.1:19121/collections/test_collection/indexes" -H "accept: application/json"
If the deletion is successful, no message will be returned.
/collections/{collection_name}/indexes (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/indexes |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/collections/test_collection/indexes"
/collections/{collection_name}/partitions (GET)
Gets all partitions in a collection starting from offset and ends with page_size.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/partitions |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
offset |
Row offset from which the data page starts. The default is 0. |
No |
page_size |
Size of the data page. The default is 10. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection/partitions?offset=0&page_size=3" -H "accept: application/json"
Response
{
"partitions": [
{ "partition_tag": "_default" },
{ "partition_tag": "test_tag" },
{ "partition_tag": "test_2" }
],
"count": 10
}
/collections/{collection_name}/partitions (POST)
Creates a partition in a collection.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/partitions |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
POST |
Response
| Status code |
Description |
| 201 |
Created |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X POST "http://127.0.0.1:19121/collections/test_collection/partitions" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"partition_tag\": \"test\"}"
Response
{ "message": "OK", "code": 0 }
/collections/{collection_name}/partitions (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/partitions |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/collections/test_collection/partitions"
/collections/{collection_name}/partitions (DELETE)
Deletes a partition by tag.
Request
| Request Component | Value |
|---|
| Name | /collections/{collection_name}/partitions
|
| Header | accept: application/json
|
| Body |
{
"partition_tag": string
}
|
| Method | POST |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection that contains the partition. |
Yes |
partition_tag |
Tag of the partition to delete. |
yes |
Response
| Status code |
Description |
| 204 |
Deleted |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The requested resource does not exist. |
Example
Request
$ curl -X DELETE "http://127.0.0.1:19121/collections/test_collection/partitions -H "accept: application/json" -d "{\"partition_tag\": \"tags_01\"}"
The deletion is successful if no information is returned.
/collections/{collection_name}/segments (GET)
Gets all segments in a collection starting from offset and ends with page_size.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/segments |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
offset |
Row offset from which the data page starts. The default is 0. |
No |
page_size |
Size of the data page. The default is 10. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection/segments?offset=0&page_size=1" -H "accept: application/json"
Response
{
"code": 0,
"message": "OK",
"count": 2,
"segments": [
{
"count": 10000,
"index": "IVFFLAT",
"partition_tag": "_default",
"segment_name": "1583727470444700000",
"size": 5284922
}
]
}
/collections/{collection_name}/segments/{segment_name}/vectors (GET)
Gets all vectors of segment in a collection starting from offset and ends with page_size.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/segments |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
segment_name |
Name of the segment. |
Yes |
offset |
Row offset from which the data page starts. The default is 0. |
No |
page_size |
Size of the data page. The default is 10. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection/segments/1583727470444700000/vectors?offset=0&page_size=1" -H "accept: application/json"
Response
{
"code": 0,
"message": "OK",
"count": 2,
"vectors": [
{
"vector": [0.1],
"id": "1583727470435045000"
}
]
}
/collections/{collection_name}/segments/{segment_name}/ids (GET)
Gets all vector ids of segment in a collection starting from offset and ends with page_size.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/segments |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
segment_name |
Name of the segment. |
Yes |
offset |
Row offset from which the data page starts. The default is 0. |
No |
page_size |
Size of the data page. The default is 10. |
No |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/collections/test_collection/segments/1583727470444700000/ids?offset=0&page_size=1" -H "accept: application/json"
Response
{
"ids": ["1583727470435045000"],
"count": 10000
}
/collections/{collection_name}/vectors (PUT)
- Searches vectors in a collection.
Request
| Request Component | Value |
|---|
| Name | /tables/{table_name}/vectors
|
| Header | accept: application/json
|
| Body |
{
"search": {
"topk": integer($int64),
"partition_tags": [string],
"file_ids": [string],
"vectors": [[number($float/$uint8)]]
"params": {
"nprobe": 16
}
}
}
|
| Method | PUT |
Body Parameters
| Parameter |
Description |
Required? |
topk |
The top k most similar results of each query vector. |
Yes |
tags |
Tags of partitions that you need to search. You do not have to specify this value if the collection is not partitioned or you wish to search the whole collection. |
No |
file_ids |
IDs of the vector files. You do not have to specify this value if you do not use Milvus in distributed scenarios. Also, if you assign a value to file_ids, the value of tags is ignored. |
No |
vectors |
Vectors to query. |
Yes |
params |
Extra params for search. Please refer to Index and search parameters to get more detail information. |
Yes |
Note: Type of items of vectors depends on the metric used by the collection. If the collection uses L2 or IP, you must use float. If the collection uses HAMMING, JACCARD, or TANIMOTO, you must use uint8.
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/collections/test_collection/vectors" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"topk\":2,\"vectors\":[[0.1]], \"params\":{\"nprobe\":16}}"
Response
{
"num": 1,
"results": [
[
{ "id": "1578989029645098000", "distance": "0.000000" },
{ "id": "1578989029645098001", "distance": "0.010000" }
]
]
}
- Delete vectors
Request
| Request Component | Value |
|---|
| Name | /tables/{table_name}/vectors
|
| Header | accept: application/json
|
| Body |
{
"delete": {
"ids": [$string]
}
}
|
| Method | PUT |
Body Parameters
| Parameter |
Description |
Required? |
| ids |
IDs of vectors. |
Yes |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/collections/test_collection/vectors" -H "accept: application/json" -H "Content-Type: application/json" -d "{"delete": {"ids": ["1578989029645098000"]}}"
Response
{ "code": 0, "message": "success" }
/collections/{collection_name}/vectors (POST)
Inserts vectors to a collection.
Note: It is recommended that you do not insert more than 1 million vectors per request.
Request
| Request Component | Value |
|---|
| Name | /tables/{table_name}/vectors
|
| Header | accept: application/json
|
| Body |
{
"partition_tag": string,
"vectors": [[number($float/$uint8)]],
"ids": [integer($int64)]
}
|
| Method | POST |
Body Parameters
| Parameter |
Description |
Required? |
partition_tag |
Tag of the partition to insert vectors to. |
No |
vectors |
Vectors to insert to the collection. |
Yes |
ids |
IDs of the vectors to insert to the collection. If you assign IDs to the vectors, you must provide IDs for all vectors in the collection. If you do not specify this parameter, Milvus automatically assigns IDs to the vectors. |
No |
Note: Type of items of vectors depends on the metric used by the collection. If the collection uses L2 or IP, you must use float. If the collection uses HAMMING, JACCARD, or TANIMOTO, you must use uint8.
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
Response
| Status code |
Description |
| 201 |
Created |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X POST "http://127.0.0.1:19121/collections/test_collection/vectors" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"vectors\":[[0.1],[0.2],[0.3],[0.4]]}"
Response
{
"ids": [
"1578989029645098000",
"1578989029645098001",
"1578989029645098002",
"1578989029645098003"
]
}
/collections/{collection_name}/vectors?id={vector_id} (GET)
Obtain a vector to by ID.
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/vectors |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
collection_name |
Name of the collection. |
Yes |
vector_id |
Vector id. |
Yes |
Response
| Status code |
Description |
| 201 |
Created |
| 400 |
The request is incorrect. Refer to the error message for details. |
| 404 |
The required resource does not exist. |
Example
Request
$ curl -X POST "http://127.0.0.1:19121/collections/test_collection/vectors?id=1578989029645098000" -H "accept: application/json" -H "Content-Type: application/json"
Response
{
"vectors": [
{
"id": "1578989029645098000",
"vector": [0.1]
}
]
}
/collections/{collection_name}/vectors (OPTIONS)
Use this API for Cross-Origin Resource Sharing (CORS).
Request
| Request Component |
Value |
| Name |
/collections/{collection_name}/vectors |
| Header |
N/A |
| Body |
N/A |
| Method |
OPTIONS |
Example
Request
$ curl -X OPTIONS "http://127.0.0.1:19121/collections/test_collection/vectors"
/system/{msg} (GET)
Gets information about the Milvus server.
Request
| Request Component |
Value |
| Name |
/system/{msg} |
| Header |
accept: application/json |
| Body |
N/A |
| Method |
GET |
Query Parameters
| Parameter |
Description |
Required? |
msg |
Type of the message to return. You can use status or version. |
Yes |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X GET "http://127.0.0.1:19121/system/version" -H "accept: application/json"
Response
{ "reply": "0.7.0" }
system/{op} (PUT)
Flush a collection
Request
| Request Component | Value |
|---|
| Name | /system/task
|
| Header | accept: application/json
|
| Body |
{
"flush": {
"collection_names": [$string]
}
}
|
| Method | PUT |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/system/task" -H "accept: application/json" -d "{\"flush\": {\"collection_names\": [\"test_collection\"]}}"
Response
{ "code": 0, "message": "success" }
Compact segments in a collection
Request
| Request Component | Value |
|---|
| Name | /system/task
|
| Header | accept: application/json
|
| Body |
{
"compact": {
"collection_name": $string
}
}
|
| Method | PUT |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/system/task" -H "accept: application/json" -d "{\"compact\": {\"collection_name\": \"test_collection\"}}"
Response
{ "code": 0, "message": "success" }
Load a collection to memory
Request
| Request Component | Value |
|---|
| Name | /system/task
|
| Header | accept: application/json
|
| Body |
{
"load": {
"collection_name": $string
}
}
|
| Method | PUT |
Response
| Status code |
Description |
| 200 |
The request is successful. |
| 400 |
The request is incorrect. Refer to the error message for details. |
Example
Request
$ curl -X PUT "http://127.0.0.1:19121/system/task" -H "accept: application/json" -d "{\"load\": {\"collection_name\": \"test_collection\"}}"
Response
{ "code": 0, "message": "success" }
Index and search parameters
For each index type, the RESTful API has specific index parameters and search parameters.
| Index type | Create index param | Search param |
|---|
| IVFFLAT |
{"nlist": $int}
|
{"nprobe": $int}
|
| IVFPQ |
{"m": $int, "nlist": $int}
|
{"nprobe": $int}
|
| IVFSQ8 |
{"nlist": $int}
|
{"nprobe": $int}
|
| IVFSQ8H |
{"nlist": $int}
|
{"nprobe": $int}
|
| HNSW |
{"M": $int, "efConstruction": $int}
|
{"ef": $int}
|
For detailed information about the parameters above, refer to Milvus Indexes
Error Codes
The RESTful API returns error messages as JSON text. Each type of error message has a specific error code.
| Type |
Code |
| SUCCESS |
0 |
| UNEXPECTED_ERROR |
1 |
| CONNECT_FAILED |
2 |
| PERMISSION_DENIED |
3 |
| TABLE_NOT_EXISTS |
4 |
| ILLEGAL_ARGUMENT |
5 |
| ILLEGAL_RANGE |
6 |
| ILLEGAL_DIMENSION |
7 |
| ILLEGAL_INDEX_TYPE |
8 |
| ILLEGAL_TABLE_NAME |
9 |
| ILLEGAL_TOPK |
10 |
| ILLEGAL_ROWRECORD |
11 |
| ILLEGAL_VECTOR_ID |
12 |
| ILLEGAL_SEARCH_RESULT |
13 |
| FILE_NOT_FOUND |
14 |
| META_FAILED |
15 |
| CACHE_FAILED |
16 |
| CANNOT_CREATE_FOLDER |
17 |
| CANNOT_CREATE_FILE |
18 |
| CANNOT_DELETE_FOLDER |
19 |
| CANNOT_DELETE_FILE |
20 |
| BUILD_INDEX_ERROR |
21 |
| ILLEGAL_NLIST |
22 |
| ILLEGAL_METRIC_TYPE |
23 |
| OUT_OF_MEMORY |
24 |
| PATH_PARAM_LOSS |
31 |
| UNKNOWN_PATH |
32 |
| QUERY_PARAM_LOSS |
33 |
| BODY_FIELD_LOSS |
34 |
| ILLEGAL_BODY |
35 |
| BODY_PARSE_FAIL |
36 |
| ILLEGAL_QUERY_PARAM |
37 |
