docs/developer_guides/appendix_b_api_reference.md
In this section, we introduce the RPCs of milvus service. A brief description of the RPCs is listed as follows.
| RPC | description |
|---|---|
| CreateCollection | create a collection based on schema statement |
| DropCollection | drop a collection |
| HasCollection | check whether a collection exists |
| LoadCollection | load collection to memory for future search |
| ReleaseCollection | release the collection from memory |
| DescribeCollection | show a collection's schema and its descriptive statistics |
| GetCollectionStatistics | show a collection's statistics |
| ShowCollections | list all collections |
| CreatePartition | create a partition |
| DropPartition | drop a partition |
| HasPartition | check whether a partition exists |
| LoadPartition | load partition to memory for future search |
| ReleasePartitions | release partitions from memory |
| GetPartitionStatistics | show a partition's statistics |
| ShowPartitions | list a collection's all partitions |
| CreateIndex | create an index for a field in the collection |
| DescribeIndex | get index details for a field in the collection |
| GetIndexStates | get build index state |
| DropIndex | drop a specific index for a field in the collection |
| Insert | insert a batch of rows into a collection or a partition |
| Search | query the columns of a collection or a partition with ANNS statements and boolean expressions |
| Flush | Perform persistent storage of data in memory |
MsgBase is a base struct in each request.
message MsgBase {
MsgType msg_type = 1;
int64 msgID = 2;
uint64 timestamp = 3;
int64 sourceID = 4;
}
MsgType is the enum to distinguish different message types in message queue, such as insert msg, search msg, etc. msgID is the unique id identifier of message. timestamp is the time when this message was generated. sourceID is the unique id identifier of the source.
Interface:
rpc CreateCollection(CreateCollectionRequest) returns (common.Status){}
Description:
Create a collection through CreateCollectionRequest.
Parameters:
CreateCollectionRequest struct is shown as follows:
message CreateCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
// `schema` is the serialized `schema.CollectionSchema`
bytes schema = 4;
}
message CollectionSchema {
string name = 1;
string description = 2;
bool autoID = 3;
repeated FieldSchema fields = 4;
}
CreateCollectionRequest contains MsgBase, db_name, collection_name and serialized collection schema schema. db_name contains only a string named collection_name. Collection with the same collection_name is going to be created.
Collection schema contains all the base information of a collection including collection name, description, autoID and fields. Collection description is defined by the database manager to describe the collection. autoID determines whether the ID of each row of data is user-defined. If autoID is true, our system will generate a unique ID for each data. If autoID is false, users need to give each entity an ID when inserting.
Fields is a list of FieldSchema. Each schema should include Field name, description, dataType, type_params and index_params.
FieldSchema struct is shown as follows:
message FieldSchema {
int64 fieldID = 1;
string name = 2;
bool is_primary_key = 3;
string description = 4;
DataType data_type = 5;
repeated common.KeyValuePair type_params = 6;
repeated common.KeyValuePair index_params = 7;
}
Field schema contains all the base information of a field including fieldID, name, description, data_type, type_params and index_params. data_type is an enum type to distinguish different data types. Total enum is shown in the last of this doc
type_params contains the detailed information of data_type. For example, vector data type should include dimension information. You can give a pair of <dim, 8> to let the field store an 8-dimension vector.
index_params：For fast search, you build an index for the field. You specify detailed index information for a field. Detailed information about index can be seen in chapter 2.2.3
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc DropCollection(DropCollectionRequest) returns (common.Status) {}
Description:
This method is used to delete collection.
Parameters:
DropCollectionRequest struct is shown as follows:
message DropCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
}
Collection with the same collection_name is going to be deleted.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc HasCollection(HasCollectionRequest) returns (BoolResponse) {}
Description:
This method is used to test collection existence.
Parameters:
HasCollectionRequest struct is shown as follows:
message HasCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
}
The server finds the collection through collection_name and checks whether the collection exists.
Returns:
message BoolResponse {
common.Status status = 1;
bool value = 2;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
value represents whether the collection exists. If collection exists, value will be true. If collection doesn't exist, value will be false.
Interface:
rpc LoadCollection(LoadCollectionRequest) returns (common.Status) {}
Description:
This method is used to load collection.
Parameters:
LoadCollectionRequest struct is shown as follows:
message LoadCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
}
Collection with the same collection_name is going to be loaded to memory.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc ReleaseCollection(ReleaseCollectionRequest) returns (common.Status) {}
Description:
This method is used to release collection.
Parameters:
ReleaseCollectionRequest struct is shown as follows:
message ReleaseCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
}
Collection with the same collection_name is going to be released from memory.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc DescribeCollection(DescribeCollectionRequest) returns (CollectionDescription) {}
Description:
This method is used to get collection schema.
Parameters:
DescribeCollectionRequest struct is shown as follows:
message DescribeCollectionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
int64 collectionID = 4;
}
The server finds the collection through collection_name and gets detailed collection information. And collectionID is for internal component to get collection details.
Returns:
message DescribeCollectionResponse {
common.Status status = 1;
schema.CollectionSchema schema = 2;
int64 collectionID = 3;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
schema is collection schema same as the collection schema in CreateCollection.
Interface:
rpc GetCollectionStatistics(GetCollectionStatisticsRequest) returns (GetCollectionStatisticsResponse) {}
Description:
This method is used to get collection statistics.
Parameters:
GetCollectionStatisticsRequest struct is shown as follows:
message GetCollectionStatisticsRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
}
The server finds the collection through collection_name and gets detailed collection statistics.
Returns:
message GetCollectionStatisticsResponse {
common.Status status = 1;
repeated common.KeyValuePair stats = 2;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the error details.
stats is a map saving different statistics. For example, you can get row_count of a collection with key 'row_count'.
Interface:
rpc ShowCollections(ShowCollectionsRequest) returns (ShowCollectionsResponse) {}
Description:
This method is used to get collection schema.
Parameters: None
Returns:
message ShowCollectionsResponse {
common.Status status = 1;
repeated string collection_names = 2;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the error details.
collection_names is a list contains all collections' names.
Interface:
rpc CreatePartition(CreatePartitionRequest) returns (common.Status) {}
Description:
This method is used to create a partition
Parameters:
CreatePartitionRequest struct is shown as follows:
message CreatePartitionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string partition_name = 4;
}
The server creates partition with the partition_name in collection with name of collection_name
Returns:
common.Status
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc DropPartition(DropPartitionRequest) returns (common.Status) {}
Description:
This method is used to drop partition.
Parameters:
DropPartitionRequest struct is shown as follows:
message DropPartitionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string partition_name = 4;
}
Drop partition with the same partition_name in collection with collection_name is going to be deleted.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc HasPartition(HasPartitionRequest) returns (BoolResponse) {}
Description:
This method is used to test partition existence.
Parameters:
HasPartitionRequest struct is shown as follows:
message HasPartitionRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string partition_name = 4;
}
Partition with the same partition_name is going to be tested whether it is in collection with collection_name.
Returns:
message BoolResponse {
common.Status status = 1;
bool value = 2;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
value represents whether the partition exists. If partition exists, value will be true. If partition doesn't exist, value will be false.
Interface:
rpc LoadPartitions(LoadPartitionsRequest) returns (common.Status) {}
Description:
This method is used to load collection.
Parameters:
LoadPartitionsRequest struct is shown as follows:
message LoadPartitionsRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
repeated string partition_names = 4;
}
partition_names is a list of partition_name. These partitions in collection with the collection_name are going to be loaded to memory.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc ReleasePartitions(ReleasePartitionsRequest) returns (common.Status) {}
Description:
This method is used to release partition.
Parameters:
ReleasePartitionsRequest struct is shown as follows:
message ReleasePartitionsRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
repeated string partition_names = 4;
}
partition_names is a list of partition_name. These partitions in collection with the collection_name are going to be released from memory.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
Interface:
rpc GetPartitionStatistics(GetPartitionStatisticsRequest) returns (GetPartitionStatisticsResponse) {}
Description:
This method is used to get partition statistics.
Parameters:
GetPartitionStatisticsRequest struct is shown as follows:
message GetPartitionStatisticsRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string partition_name = 4;
}
The server finds the partition through partition_name in collection with collection_name and gets detailed partition statistics.
Returns:
message GetPartitionStatisticsResponse {
common.Status status = 1;
repeated common.KeyValuePair stats = 2;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
stats is a map saving different statistics. For example, you can get row_count of a partition with key 'row_count'.
Interface:
rpc ShowPartitions(ShowPartitionsRequest) returns (StringListResponse) {}
Description:
This method is used to get partition descriptions.
Parameters:
ShowPartitionsRequest struct is shown as follows:
message ShowPartitionsRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
int64 collectionID = 4;
}
Partitions in the collection with collection_name are going to be listed.
Returns:
message ShowPartitionsResponse {
common.Status status = 1;
repeated string partition_names = 2;
repeated int64 partitionIDs = 3;
}
status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
partition_names is a list contains all partitions' name. partitionIDs is a list contains all partitions' ids. And the index of a partition in partition_names and partitionIDs are same.
Interface:
rpc Insert(InsertRequest) returns (InsertResponse){}
Description:
Insert a batch of rows into a collection or a partition
Parameters:
InsertRequest struct is shown as follows:
message InsertRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string partition_name = 4;
repeated common.Blob row_data = 5;
repeated uint32 hash_keys = 6;
}
message Blob {
bytes value = 1;
}
Insert a batch of row_data into collection with collection_name and partition with partition_name. Blob contains bytes of value.
Returns:
message InsertResponse {
common.Status status = 1;
int64 rowID_begin = 2;
int64 rowID_end = 3;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
rowID_begin and rowID_end are the ID of inserted values.
Interface:
rpc CreateIndex(CreateIndexRequest) returns (common.Status){}
Description:
Create an index for a collection.
Parameters:
CreateIndexRequest struct is shown as follows:
message CreateIndexRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string field_name = 4;
repeated common.KeyValuePair extra_params = 5;
}
CreateIndex for the field with field_name in collection with collection_name.
extra_params：For fast search, you build index for field. You specify detailed index information for a field. Detailed information about index can be seen in chapter 2.2.3
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe error detail.
Interface:
rpc DescribeIndex(DescribeIndexRequest) returns (common.Status){}
Description:
Get an index detailed info
Parameters:
DescribeIndexRequest struct is shown as follows:
message DescribeIndexRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string field_name = 4;
string index_name = 5;
}
Get details of an index for the field with field_name in collection with collection_name.
index_name： A field can create multiple indexes. And you can drop a specific index through index_name.
Returns:
message DescribeIndexResponse {
common.Status status = 1;
repeated IndexDescription index_descriptions = 2;
}
message IndexDescription {
string index_name = 1;
int64 indexID = 2;
repeated common.KeyValuePair params = 3;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe error detail.
index_descriptions is a list of index descriptions. If index_name is specific in request, the list length will be 0. Otherwise, if index_name is empty, the response will return all indexes in the field of a collection.
params：For fast search, you build index for field. You specify detailed index information for a field. Detailed information about index can be seen in chapter 2.2.3
Interface:
rpc GetIndexStates(GetIndexStatesRequest) returns (GetIndexStatesRequest){}
Description:
Get index build progress info.
Parameters:
GetIndexStatesRequest struct is shown as follows:
message GetIndexStatesRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string field_name = 4;
string index_name = 5;
}
Get index build progress info for the field with field_name in collection with collection_name.
index_name： A field can create multiple indexes. And you can get specific index state through index_name.
Returns:
message GetIndexStatesResponse {
common.Status status = 1;
common.IndexState state = 2;
}
enum IndexState {
IndexStateNone = 0;
Unissued = 1;
InProgress = 2;
Finished = 3;
Failed = 4;
Deleted = 5;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.
index state is an enum type to distinguish the different processes in the index building process.
Interface:
rpc DropIndex(DropIndexRequest) returns (common.Status){}
Description:
Drop an index for a collection.
Parameters:
DropIndexRequest struct is shown as follows:
message DropIndexRequest {
common.MsgBase base = 1;
string db_name = 2;
string collection_name = 3;
string field_name = 4;
string index_name = 5;
}
DropIndex for the field with field_name in collection with collection_name.
index_name： A field can create multiple indexes. And you can drop specific index through index_name.
Returns:
message Status {
ErrorCode error_code = 1;
string reason = 2;
}
Status represents the server error code. It doesn't contain grpc error but contains the server error code. We can get the executing result in common status. error_code is an enum type to distinguish the executing error type. The total Errorcode is shown in the last of this code. And the reason field is a string to describe the detailed error.