test/milvus
1
0
Fork 0
mirror of https://gitee.com/milvus-io/milvus.git synced 2024-11-30 02:48:45 +08:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity
c666645629
milvus/docs/developer_guides/appendix_b_api_reference.md
binbin 07bbc7d96e
[skip e2e] Refine docs (#14863) 
Signed-off-by: Binbin Lv <binbin.lv@zilliz.com>
2022-01-05 17:11:20 +08:00

965 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## Appendix B. API Reference
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.
```protobuf
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.
#### 3.1 Definition Requests
###### 3.1.1 CreateCollection
**Interface:**
```
rpc CreateCollection(CreateCollectionRequest) returns (common.Status){}
```
**Description:**
Create a collection through CreateCollectionRequest.
**Parameters:**
- **CreateCollectionRequest**
CreateCollectionRequest struct is shown as follows:
```protobuf
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:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.2 DropCollection
**Interface:**
```
rpc DropCollection(DropCollectionRequest) returns (common.Status) {}
```
**Description:**
This method is used to delete collection.
**Parameters:**
- **DropCollectionRequest**
DropCollectionRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.3 HasCollection
**Interface:**
```
rpc HasCollection(HasCollectionRequest) returns (BoolResponse) {}
```
**Description:**
This method is used to test collection existence.
**Parameters:**
- **HasCollectionRequest**
HasCollectionRequest struct is shown as follows:
```protobuf
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:**
- **BoolResponse**
```protobuf
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.
###### 3.1.4 LoadCollection
**Interface:**
```
rpc LoadCollection(LoadCollectionRequest) returns (common.Status) {}
```
**Description:**
This method is used to load collection.
**Parameters:**
- **LoadCollectionRequest**
LoadCollectionRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.5 ReleaseCollection
**Interface:**
```
rpc ReleaseCollection(ReleaseCollectionRequest) returns (common.Status) {}
```
**Description:**
This method is used to release collection.
**Parameters:**
- **ReleaseCollectionRequest**
ReleaseCollectionRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.6 DescribeCollection
**Interface:**
```
rpc DescribeCollection(DescribeCollectionRequest) returns (CollectionDescription) {}
```
**Description:**
This method is used to get collection schema.
**Parameters:**
- **DescribeCollectionRequest**
DescribeCollectionRequest struct is shown as follows:
```protobuf
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:**
- **DescribeCollectionResponse**
```protobuf
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](#311-createcollection).
###### 3.1.7 GetCollectionStatistics
**Interface:**
```
rpc GetCollectionStatistics(GetCollectionStatisticsRequest) returns (GetCollectionStatisticsResponse) {}
```
**Description:**
This method is used to get collection statistics.
**Parameters:**
- **GetCollectionStatisticsRequest**
GetCollectionStatisticsRequest struct is shown as follows:
```protobuf
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:**
- **GetCollectionStatisticsResponse**
```protobuf
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'.
###### 3.1.8 ShowCollections
**Interface:**
```
rpc ShowCollections(ShowCollectionsRequest) returns (ShowCollectionsResponse) {}
```
**Description:**
This method is used to get collection schema.
**Parameters:** None
**Returns:**
- **ShowCollectionsResponse**
```protobuf
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.
###### 3.1.9 CreatePartition
**Interface:**
```
rpc CreatePartition(CreatePartitionRequest) returns (common.Status) {}
```
**Description:**
This method is used to create a partition
**Parameters:**
- **CreatePartitionRequest**
CreatePartitionRequest struct is shown as follows:
```protobuf
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**
```protobuf
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.
###### 3.1.10 DropPartition
**Interface:**
```
rpc DropPartition(DropPartitionRequest) returns (common.Status) {}
```
**Description:**
This method is used to drop partition.
**Parameters:**
- **DropPartitionRequest**
DropPartitionRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.11 HasPartition
**Interface:**
```
rpc HasPartition(HasPartitionRequest) returns (BoolResponse) {}
```
**Description:**
This method is used to test partition existence.
**Parameters:**
- **HasPartitionRequest**
HasPartitionRequest struct is shown as follows:
```protobuf
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:**
- **BoolResponse**
```protobuf
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.
###### 3.1.12 LoadPartitions
**Interface:**
```
rpc LoadPartitions(LoadPartitionsRequest) returns (common.Status) {}
```
**Description:**
This method is used to load collection.
**Parameters:**
- **LoadPartitionsRequest**
LoadPartitionsRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.13 ReleasePartitions
**Interface:**
```
rpc ReleasePartitions(ReleasePartitionsRequest) returns (common.Status) {}
```
**Description:**
This method is used to release partition.
**Parameters:**
- **ReleasePartitionsRequest**
ReleasePartitionsRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.1.14 GetPartitionStatistics
**Interface:**
```
rpc GetPartitionStatistics(GetPartitionStatisticsRequest) returns (GetPartitionStatisticsResponse) {}
```
**Description:**
This method is used to get partition statistics.
**Parameters:**
- **GetPartitionStatisticsRequest**
GetPartitionStatisticsRequest struct is shown as follows:
```protobuf
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:**
- **GetCollectionStatisticsResponse**
```protobuf
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'.
###### 3.1.15 ShowPartitions
**Interface:**
```
rpc ShowPartitions(ShowPartitionsRequest) returns (StringListResponse) {}
```
**Description:**
This method is used to get partition descriptions.
**Parameters:**
- **ShowPartitionsRequest**
ShowPartitionsRequest struct is shown as follows:
```protobuf
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:**
- **StringListResponse**
```protobuf
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.
#### 3.2 Manipulation Requests
###### 3.2.1 Insert
**Interface:**
```
rpc Insert(InsertRequest) returns (InsertResponse){}
```
**Description:**
Insert a batch of rows into a collection or a partition
**Parameters:**
- **InsertRequest**
InsertRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.2.2 Delete
- DeleteByID
#### 3.3 Query
#### 3.3 Index
###### 3.3.1 CreateIndex
**Interface:**
```
rpc CreateIndex(CreateIndexRequest) returns (common.Status){}
```
**Description:**
Create an index for a collection.
**Parameters:**
- **CreateIndexRequest**
CreateIndexRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.3.2 DescribeIndex
**Interface:**
```
rpc DescribeIndex(DescribeIndexRequest) returns (common.Status){}
```
**Description:**
Get an index detailed info
**Parameters:**
- **DescribeIndexRequest**
DescribeIndexRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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
###### 3.3.3 GetIndexStates
**Interface:**
```
rpc GetIndexStates(GetIndexStatesRequest) returns (GetIndexStatesRequest){}
```
**Description:**
Get index build progress info.
**Parameters:**
- **GetIndexStatesRequest**
GetIndexStatesRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
###### 3.3.4 DropIndex
**Interface:**
```
rpc DropIndex(DropIndexRequest) returns (common.Status){}
```
**Description:**
Drop an index for a collection.
**Parameters:**
- **DropIndexRequest**
DropIndexRequest struct is shown as follows:
```protobuf
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:**
- **common.Status**
```protobuf
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.
Reference in New Issue View Git Blame Copy Permalink