# Brief This document will help sdk developers to understand each API of milvus RPC proto. # Table of contents ================= - [Brief](#brief) - [# Table of contents](#-table-of-contents) - [milvus.proto](#milvusproto) - [CreateCollection](#createcollection) - [CreateCollectionRequest](#createcollectionrequest) - [DropCollection](#dropcollection) - [DropCollectionRequest](#dropcollectionrequest) - [HasCollection](#hascollection) - [HasCollectionRequest](#hascollectionrequest) - [LoadCollection](#loadcollection) - [LoadCollectionRequest](#loadcollectionrequest) - [ReleaseCollection](#releasecollection) - [ReleaseCollectionRequest](#releasecollectionrequest) - [DescribeCollection](#describecollection) - [DescribeCollectionRequest](#describecollectionrequest) - [DescribeCollectionResponse](#describecollectionresponse) - [GetCollectionStatistics](#getcollectionstatistics) - [GetCollectionStatisticsRequest](#getcollectionstatisticsrequest) - [GetCollectionStatisticsResponse](#getcollectionstatisticsresponse) - [ShowCollections](#showcollections) - [ShowCollectionsRequest](#showcollectionsrequest) - [ShowCollectionsResponse](#showcollectionsresponse) - [CreatePartition](#createpartition) - [CreatePartitionRequest](#createpartitionrequest) - [DropPartition](#droppartition) - [DropPartitionRequest](#droppartitionrequest) - [HasPartition](#haspartition) - [HasPartitionRequest](#haspartitionrequest) - [LoadPartitions](#loadpartitions) - [LoadPartitionsRequest](#loadpartitionsrequest) - [ReleasePartitions](#releasepartitions) - [ReleasePartitionsRequest](#releasepartitionsrequest) - [GetPartitionStatistics](#getpartitionstatistics) - [GetPartitionStatisticsRequest](#getpartitionstatisticsrequest) - [GetPartitionStatisticsResponse](#getpartitionstatisticsresponse) - [ShowPartitions](#showpartitions) - [ShowPartitionsRequest](#showpartitionsrequest) - [ShowPartitionsResponse](#showpartitionsresponse) - [CreateAlias](#createalias) - [CreateAliasRequest](#createaliasrequest) - [DropAlias](#dropalias) - [DropAliasRequest](#dropaliasrequest) - [AlterAlias](#alteralias) - [AlterAliasRequest](#alteraliasrequest) - [CreateIndex](#createindex) - [CreateIndexRequest](#createindexrequest) - [DescribeIndex](#describeindex) - [DescribeIndexRequest](#describeindexrequest) - [DescribeIndexResponse](#describeindexresponse) - [GetIndexState](#getindexstate) - [GetIndexStateRequest](#getindexstaterequest) - [GetIndexStateResponse](#getindexstateresponse) - [GetIndexBuildProgress](#getindexbuildprogress) - [GetIndexBuildProgressRequest](#getindexbuildprogressrequest) - [GetIndexBuildProgressResponse](#getindexbuildprogressresponse) - [DropIndex](#dropindex) - [DropIndexRequest](#dropindexrequest) - [Insert](#insert) - [InsertRequest](#insertrequest) - [Delete](#delete) - [DeleteRequest](#deleterequest) - [Search](#search) - [SearchRequest](#searchrequest) - [SearchResults](#searchresults) - [Flush](#flush) - [FlushRequest](#flushrequest) - [FlushResponse](#flushresponse) - [Query](#query) - [QueryRequest](#queryrequest) - [QueryResults](#queryresults) - [CalcDistance](#calcdistance) - [VectorIDs](#vectorids) - [VectorsArray](#vectorsarray) - [CalcDistanceRequest](#calcdistancerequest) - [CalcDistanceResults](#calcdistanceresults) - [GetPersistentSegmentInfo](#getpersistentsegmentinfo) - [GetPersistentSegmentInfoRequest](#getpersistentsegmentinforequest) - [PersistentSegmentInfo](#persistentsegmentinfo) - [GetPersistentSegmentInfoResponse](#getpersistentsegmentinforesponse) - [GetQuerySegmentInfo](#getquerysegmentinfo) - [GetQuerySegmentInfoRequest](#getquerysegmentinforequest) - [QuerySegmentInfo](#querysegmentinfo) - [GetQuerySegmentInfoResponse](#getquerysegmentinforesponse) - [GetMetrics](#getmetrics) - [GetMetricsRequest](#getmetricsrequest) - [GetMetricsResponse](#getmetricsresponse) - [LoadBalance](#loadbalance) - [LoadBalanceRequest](#loadbalancerequest) - [GetCompactionState](#getcompactionstate) - [GetCompactionStateRequest](#getcompactionstaterequest) - [GetCompactionStateResponse](#getcompactionstateresponse) - [ManualCompaction](#manualcompaction) - [ManualCompactionRequest](#manualcompactionrequest) - [ManualCompactionResponse](#manualcompactionresponse) - [GetCompactionStateWithPlans](#getcompactionstatewithplans) - [GetCompactionPlansRequest](#getcompactionplansrequest) - [GetCompactionPlansResponse](#getcompactionplansresponse) - [CompactionMergeInfo](#compactionmergeinfo) - [ShowType](#showtype) - [BoolResponse](#boolresponse) - [MutationResult](#mutationresult) - [common.proto](#commonproto) - [ErrorCode](#errorcode) - [IndexState](#indexstate) - [SegmentState](#segmentstate) - [Status](#status) - [KeyValuePair](#keyvaluepair) - [KeyDataPair](#keydatapair) - [DslType](#dsltype) - [CompactionState](#compactionstate) - [schema.proto](#schemaproto) - [DataType](#datatype) - [FieldSchema](#fieldschema) - [CollectionSchema](#collectionschema) - [BoolArray](#boolarray) - [IntArray](#intarray) - [LongArray](#longarray) - [FloatArray](#floatarray) - [DoubleArray](#doublearray) - [BytesArray](#bytesarray) - [StringArray](#stringarray) - [ScalarField](#scalarfield) - [VectorField](#vectorfield) - [FieldData](#fielddata) - [IDs](#ids) - [SearchResultData](#searchresultdata) # milvus.proto ## CreateCollection Create a collection with schema. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc CreateCollection(CreateCollectionRequest) returns (common.Status) {} ``` [back to top](#brief) ### CreateCollectionRequest ``` message CreateCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The unique collection name in milvus.(Required) string collection_name = 3; // The serialized `schema.CollectionSchema`(Required) bytes schema = 4; // Once set, no modification is allowed (Optional) // https://github.com/milvus-io/milvus/issues/6690 int32 shards_num = 5; } ``` ## DropCollection Drop a collection by name. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc DropCollection(DropCollectionRequest) returns (common.Status) {} ``` [back to top](#brief) ### DropCollectionRequest ``` message DropCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The name of the collection whcih to be dropped. (Required) string collection_name = 3; } ``` ## HasCollection To test existence of a collection by name. Return [BoolResponse](#boolresponse) to tell client whether the collection is exist. ``` rpc HasCollection(HasCollectionRequest) returns (BoolResponse) {} ``` [back to top](#brief) ### HasCollectionRequest ``` message HasCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The name of the collection which you want to check. (Required) string collection_name = 3; // If time_stamp is not zero, will return true when time_stamp >= created collection timestamp, otherwise will return false. uint64 time_stamp = 4; } ``` ## LoadCollection Load a collection data into cache of query node. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc LoadCollection(LoadCollectionRequest) returns (common.Status) {} ``` [back to top](#brief) ### LoadCollectionRequest ``` message LoadCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The name of the collection which you want to load into cache. (Required) string collection_name = 3; } ``` ## ReleaseCollection Release a collection data from cache of query node. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc ReleaseCollection(ReleaseCollectionRequest) returns (common.Status) {} ``` [back to top](#brief) ### ReleaseCollectionRequest ``` message ReleaseCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The name of the collection which you want to release. (Required) string collection_name = 3; } ``` ## DescribeCollection Get a collection's information including id, schema, alias, timestamp and internal data transfer channel. (Some returned information is for developers). ``` rpc DescribeCollection(DescribeCollectionRequest) returns (DescribeCollectionResponse) {} ``` [back to top](#brief) ### DescribeCollectionRequest ``` message DescribeCollectionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name you want to describe, you can pass collection_name or collectionID string collection_name = 3; // The collection ID you want to describe int64 collectionID = 4; // If time_stamp is not zero, will describe collection success when time_stamp >= created collection timestamp, otherwise will throw error. uint64 time_stamp = 5; } ``` ### DescribeCollectionResponse ``` message DescribeCollectionResponse { // Contain error_code and reason common.Status status = 1; // The schema param when you created collection. schema.CollectionSchema schema = 2; // The collection id int64 collectionID = 3; // System design related, users should not perceive repeated string virtual_channel_names = 4; // System design related, users should not perceive repeated string physical_channel_names = 5; // Hybrid timestamp in milvus uint64 created_timestamp = 6; // The utc timestamp calculated by created_timestamp uint64 created_utc_timestamp = 7; // The shards number you set. int32 shards_num = 8; // The aliases of this collection repeated string aliases = 9; // The message ID/posititon when collection is created repeated common.KeyDataPair start_positions = 10; } ``` ## GetCollectionStatistics Get collection statistics. Currently only support return row count. ``` rpc GetCollectionStatistics(GetCollectionStatisticsRequest) returns (GetCollectionStatisticsResponse) {} ``` [back to top](#brief) ### GetCollectionStatisticsRequest ``` message GetCollectionStatisticsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name you want get statistics string collection_name = 3; } ``` ### GetCollectionStatisticsResponse See [common.KeyValuePair](#keyvaluepair). ``` message GetCollectionStatisticsResponse { // Contain error_code and reason common.Status status = 1; // Collection statistics data in key-value pairs. Currently only return one pair: "row_count":xxx repeated common.KeyValuePair stats = 2; } ``` ## ShowCollections Get all collections name in db, or get in-memory state for each collection. ``` rpc ShowCollections(ShowCollectionsRequest) returns (ShowCollectionsResponse) {} ``` [back to top](#brief) ### ShowCollectionsRequest See [ShowType](#showtype). ``` message ShowCollectionsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // Not useful for now uint64 time_stamp = 3; // Decide return Loaded collections or All collections(Optional) ShowType type = 4; // When type is InMemory, will return these collection's inMemory_percentages.(Optional) repeated string collection_names = 5; } ``` ### ShowCollectionsResponse ``` message ShowCollectionsResponse { // Contain error_code and reason common.Status status = 1; // Collection name array repeated string collection_names = 2; // Collection Id array repeated int64 collection_ids = 3; // Hybrid timestamps in milvus repeated uint64 created_timestamps = 4; // The utc timestamp calculated by created_timestamp repeated uint64 created_utc_timestamps = 5; // Load percentage on querynode when type is InMemory repeated int64 inMemory_percentages = 6; } ``` ## CreatePartition Create a partition in a collection. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc CreatePartition(CreatePartitionRequest) returns (common.Status) {} ``` [back to top](#brief) ### CreatePartitionRequest ``` message CreatePartitionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus. (Required) string collection_name = 3; // The name of the partition to be created. (Required) string partition_name = 4; } ``` ## DropPartition Drop a partition by name. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc DropPartition(DropPartitionRequest) returns (common.Status) {} ``` [back to top](#brief) ### DropPartitionRequest ``` message DropPartitionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus. (Required) string collection_name = 3; // The name of the partition which you want to drop. (Required) string partition_name = 4; } ``` ## HasPartition To test existence of a partition by name. Return [BoolResponse](#boolresponse) to tell client whether the partition is exist. ``` rpc HasPartition(HasPartitionRequest) returns (BoolResponse) {} ``` [back to top](#brief) ### HasPartitionRequest ``` message HasPartitionRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus string collection_name = 3; // The name of the partition which you want to check string partition_name = 4; } ``` ## LoadPartitions Load multiple partitions data into cache of query node. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc LoadPartitions(LoadPartitionsRequest) returns (common.Status) {} ``` [back to top](#brief) ### LoadPartitionsRequest ``` message LoadPartitionsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus. (Required) string collection_name = 3; // A name array of the partitions whcih you want to load. (Required) repeated string partition_names = 4; } ``` ## ReleasePartitions Release partitions data from cache of query node. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc ReleasePartitions(ReleasePartitionsRequest) returns (common.Status) {} ``` [back to top](#brief) ### ReleasePartitionsRequest ``` message ReleasePartitionsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus. (Required) string collection_name = 3; // A name array of the partitions whcih you want to release. (Required) repeated string partition_names = 4; } ``` ## GetPartitionStatistics Get partition statistics. Currently only support return row count. ``` rpc GetPartitionStatistics(GetPartitionStatisticsRequest) returns (GetPartitionStatisticsResponse) {} ``` [back to top](#brief) ### GetPartitionStatisticsRequest ``` message GetPartitionStatisticsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name in milvus string collection_name = 3; // The partition name you want to collect statistics string partition_name = 4; } ``` ### GetPartitionStatisticsResponse ``` message GetPartitionStatisticsResponse { // Contain error_code and reason common.Status status = 1; // Collection statistics data in key-value pairs. Currently only return one pair: "row_count":xxx repeated common.KeyValuePair stats = 2; } ``` ## ShowPartitions Get all partitions name in db, or get in-memory state for each partition. ``` rpc ShowPartitions(ShowPartitionsRequest) returns (ShowPartitionsResponse) {} ``` [back to top](#brief) ### ShowPartitionsRequest See [ShowType](#showtype). ``` message ShowPartitionsRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The collection name you want to describe, you can pass collection_name or collectionID string collection_name = 3; // The collection id in milvus int64 collectionID = 4; // When type is InMemory, will return these patitions's inMemory_percentages.(Optional) repeated string partition_names = 5; // Decide return Loaded partitions or All partitions(Optional) ShowType type = 6; } ``` ### ShowPartitionsResponse ``` message ShowPartitionsResponse { // Contain error_code and reason common.Status status = 1; // All partition names for this collection repeated string partition_names = 2; // All partition ids for this collection repeated int64 partitionIDs = 3; // All hybrid timestamps repeated uint64 created_timestamps = 4; // All utc timestamps calculated by created_timestamps repeated uint64 created_utc_timestamps = 5; // Load percentage on querynode repeated int64 inMemory_percentages = 6; } ``` ## CreateAlias Create an alias for a collection. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. For more information please refer the [document](https://wiki.lfaidata.foundation/display/MIL/MEP+10+--+Support+Collection+Alias). ``` rpc CreateAlias(CreateAliasRequest) returns (common.Status) {} ``` [back to top](#brief) ### CreateAliasRequest ``` message CreateAliasRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The alias. (Required) string alias = 4; } ``` ## DropAlias Delete an alias. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. For more information please refer the [document](https://wiki.lfaidata.foundation/display/MIL/MEP+10+--+Support+Collection+Alias). ``` rpc DropAlias(DropAliasRequest) returns (common.Status) {} ``` [back to top](#brief) ### DropAliasRequest ``` message DropAliasRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The alias. (Required) string alias = 3; } ``` ## AlterAlias Alter an alias from a collection to another. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. For more information please refer the [document](https://wiki.lfaidata.foundation/display/MIL/MEP+10+--+Support+Collection+Alias). ``` rpc AlterAlias(AlterAliasRequest) returns (common.Status) {} ``` [back to top](#brief) ### AlterAliasRequest ``` message AlterAliasRequest{ // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The alias. (Required) string alias = 4; } ``` ## CreateIndex Create an index. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc CreateIndex(CreateIndexRequest) returns (common.Status) {} ``` [back to top](#brief) ### CreateIndexRequest ``` message CreateIndexRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The particular collection name you want to create index. (Required) string collection_name = 3; // The vector field name in this particular collection. (Required) string field_name = 4; // Support keys: index_type, metric_type, params. Different index_type may has different params. repeated common.KeyValuePair extra_params = 5; } ``` ## DescribeIndex Get index information. ``` rpc DescribeIndex(DescribeIndexRequest) returns (DescribeIndexResponse) {} ``` [back to top](#brief) ### DescribeIndexRequest ``` message DescribeIndexRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The particular collection name in Milvus. (Required) string collection_name = 3; // The vector field name in this particular collection. (Required) string field_name = 4; // No need to set up for now @2021.06.30 string index_name = 5; } ``` ### DescribeIndexResponse ``` message IndexDescription { // Index name string index_name = 1; // Index id int64 indexID = 2; // Will return index_type, metric_type, params(like nlist). repeated common.KeyValuePair params = 3; // The vector field name string field_name = 4; } message DescribeIndexResponse { // Response status common.Status status = 1; // All index informations, for now only return tha latest index you created for the collection. repeated IndexDescription index_descriptions = 2; } ``` ## GetIndexState Get index state . ``` rpc GetIndexState(GetIndexStateRequest) returns (GetIndexStateResponse) {} ``` [back to top](#brief) ### GetIndexStateRequest ``` message GetIndexStateRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2 ; // The target collection name. (Required) string collection_name = 3; // The target field name. (Required) string field_name = 4; // No need to set up for now @2021.06.30 string index_name = 5; } ``` ### GetIndexStateResponse See [common.IndexState](#indexstate) ``` message GetIndexStateResponse { // Response status common.Status status = 1; // Index state common.IndexState state = 2; // If the index build failed, the fail_reason will be returned. string fail_reason = 3; } ``` ## GetIndexBuildProgress Get index build progress state. ``` rpc GetIndexBuildProgress(GetIndexBuildProgressRequest) returns (GetIndexBuildProgressResponse) {} ``` [back to top](#brief) ### GetIndexBuildProgressRequest ``` message GetIndexBuildProgressRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2 ; // The collection name in milvus string collection_name = 3; // The vector field name in this collection string field_name = 4; // Not useful for now string index_name = 5; } ``` ### GetIndexBuildProgressResponse ``` message GetIndexBuildProgressResponse { // Response status common.Status status = 1; // How many rows are indexed int64 indexed_rows = 2; // Totally how many rows need to be indexed int64 total_rows = 3; } ``` ## DropIndex Drop an index. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. ``` rpc DropIndex(DropIndexRequest) returns (common.Status) {} ``` [back to top](#brief) ### DropIndexRequest ``` message DropIndexRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The target field name. (Required) string field_name = 4; // No need to set up for now @2021.06.30 string index_name = 5; } ``` ## Insert Insert entities into a collection. See [MutationResult](#mutationresult). ``` rpc Insert(InsertRequest) returns (MutationResult) {} ``` [back to top](#brief) ### InsertRequest See [scheml.FieldData](#fielddata). ``` message InsertRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The target partition name. (Optional) string partition_name = 4; // The fields data. See schema.FieldData repeated schema.FieldData fields_data = 5; // Not useful for now repeated uint32 hash_keys = 6; // Row count inserted uint32 num_rows = 7; } ``` ## Delete Delete entities from a collection by an expression. See [MutationResult](#mutationresult). ``` rpc Delete(DeleteRequest) returns (MutationResult) {} ``` [back to top](#brief) ### DeleteRequest ``` message DeleteRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The target partition name. (Optional) string partition_name = 4; // The expression to filter out entities. Currently only support primary key as filtering condition. For example: "id in [1, 2, 3]" (Required) string expr = 5; // Reserved repeated uint32 hash_keys = 6; } ``` ## Search Do ANN search. ``` rpc Search(SearchRequest) returns (SearchResults) {} ``` [back to top](#brief) ### SearchRequest ``` message SearchRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // The target collection name. (Required) string collection_name = 3; // The target partition names. (Optional) repeated string partition_names = 4; // The filtering expression. (Optional) string dsl = 5; // Serialized `PlaceholderGroup` bytes placeholder_group = 6; // Always be BoolExprV1 common.DslType dsl_type = 7; // Specifiy output fields, the returned result will return other fields data. (Optional) repeated string output_fields = 8; // ANN search parameters. For example, if the index is IVF, the search parameters will be: "nprobe":xxx repeated common.KeyValuePair search_params = 9; // Filtering entities by timestamp. (Optional) uint64 travel_timestamp = 10; // The time tolerance between entities visibility and search action. Default is 0. In Milvus, each entity has a timestamp. To ensure data consistence, each node(query node and data node) will consume data in a time interval. So entity visibility is a bit later than its timestamp. If this value is 0, Milvus will hold the search action, wait until all entities whose timestamp is earlier that the search action's timestamp to be fully consumed. uint64 guarantee_timestamp = 11; } ``` ### SearchResults See [schema.SearchResultData](#searchresultdata). ``` message SearchResults { // Response status common.Status status = 1; // Search results schema.SearchResultData results = 2; } ``` ## Flush Flush data node's buffer into storage. After flush, all growing segments become sealed, and persisted into storage asynchronously. ``` rpc Flush(FlushRequest) returns (FlushResponse) {} ``` [back to top](#brief) ### FlushRequest ``` message FlushRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // Specify target collection names. (Required) repeated string collection_names = 3; } ``` ### FlushResponse ``` message FlushResponse{ // Not useful for now common.Status status = 1; // Not useful for now string db_name = 2; // Return a map mapping collection id and flushed segments. map coll_segIDs = 3; } ``` ## Query Retrieve entities by expression. ``` rpc Query(QueryRequest) returns (QueryResults) {} ``` [back to top](#brief) ### QueryRequest ``` message QueryRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string db_name = 2; // Target collection name. (Required) string collection_name = 3; // Filtering expression. (Required) For more information: https://milvus.io/docs/v2.0.0/boolean.md string expr = 4; // Specifiy output fields, the returned result will return other fields data. (Optional) repeated string output_fields = 5; // Target partition names. (Optional) repeated string partition_names = 6; // Filtering entities by timestamp. (Optional) uint64 travel_timestamp = 7; // The time tolerance between entities visibility and query action. Default is 0. uint64 guarantee_timestamp = 8; // guarantee_timestamp } ``` ### QueryResults See [schema.FieldData](#fielddata). ``` message QueryResults { // Response status common.Status status = 1; // See schema.FieldData repeated schema.FieldData fields_data = 2; } ``` ## CalcDistance Calculate distance between two vector arrays. ``` rpc CalcDistance(CalcDistanceRequest) returns (CalcDistanceResults) {} ``` [back to top](#brief) ### VectorIDs ``` message VectorIDs { // Target collection name. (Required) string collection_name = 1; // Target field name. (Required) string field_name = 2; // Specify id array. See schema.IDs schema.IDs id_array = 3; repeated string partition_names = 4; } ``` ### VectorsArray See [VectorIDs](#vectorids), [schema.VectorField](#vectorfield). ``` message VectorsArray { // Specify vectors by long id, or input vectors data as input // See schema.VectorField oneof array { VectorIDs id_array = 1; // vector ids schema.VectorField data_array = 2; // vectors data } } ``` ### CalcDistanceRequest See [VectorsArray](#vectorsarray). See [schema.KeyValuePair](#keyvaluepair). ``` message CalcDistanceRequest { // Not useful for now common.MsgBase base = 1; // vectors on the left of operator VectorsArray op_left = 2; // vectors on the right of operator VectorsArray op_right = 3; // Extra parameters in key-value format. Currently only support metric type: "metric":"L2"/"IP"/"HAMMIN"/"TANIMOTO" repeated common.KeyValuePair params = 4; } ``` ### CalcDistanceResults See [schema.IntArray](#intarray). See [schema.FloatArray](#floatarray). ``` message CalcDistanceResults { // Response status common.Status status = 1; // Distance results array. The array size = num(op_left)*num(op_right) // For float vectors, return float distance values. // For binary vectors, return integer distance values. // For example: // Assume the vectors_left: L_1, L_2, L_3 // Assume the vectors_right: R_a, R_b // Distance between L_n and R_m we called "D_n_m" // The returned distance values are arranged like this: // [D_1_a, D_1_b, D_2_a, D_2_b, D_3_a, D_3_b] oneof array { schema.IntArray int_dist = 2; schema.FloatArray float_dist = 3; } } ``` ## GetPersistentSegmentInfo Get segment persist state from data node. ``` rpc GetPersistentSegmentInfo(GetPersistentSegmentInfoRequest) returns (GetPersistentSegmentInfoResponse) {} ``` [back to top](#brief) ### GetPersistentSegmentInfoRequest ``` message GetPersistentSegmentInfoRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string dbName = 2; // Target collection's name. (Required) string collectionName = 3; } ``` ### PersistentSegmentInfo See [common.SegmentState](#segmentstate). ``` message PersistentSegmentInfo { // The segment's ID int64 segmentID = 1; // The collection ID to which the segment belong int64 collectionID = 2; // The partition ID to which the segment belong int64 partitionID = 3; // The segment's row count int64 num_rows = 4; // See common.SegmentState common.SegmentState state = 5; } ``` ### GetPersistentSegmentInfoResponse See [PersistentSegmentInfo](#persistentsegmentinfo). ``` message GetPersistentSegmentInfoResponse { // Response status common.Status status = 1; // Array of multiple segment info. See PersistentSegmentInfo repeated PersistentSegmentInfo infos = 2; } ``` ## GetQuerySegmentInfo Get segments information from query nodes. ``` rpc GetQuerySegmentInfo(GetQuerySegmentInfoRequest) returns (GetQuerySegmentInfoResponse) {} ``` [back to top](#brief) ### GetQuerySegmentInfoRequest ``` message GetQuerySegmentInfoRequest { // Not useful for now common.MsgBase base = 1; // Not useful for now string dbName = 2; // Target collection's name. (Required) string collectionName = 3; } ``` ### QuerySegmentInfo See [common.SegmentState](#segmentstate). ``` message QuerySegmentInfo { // The segment id int64 segmentID = 1; // The collection id to which the segment belong int64 collectionID = 2; // The partition id to which the segment belong int64 partitionID = 3; // Memory size cost for the segment int64 mem_size = 4; // Row count of the segment int64 num_rows = 5; // The index name of the segment string index_name = 6; // Index id, mostly for developers int64 indexID = 7; // The query node id which the segment is loaded int64 nodeID = 8; // The segment state, see common.SegmentState common.SegmentState state = 9; } ``` ### GetQuerySegmentInfoResponse See [QuerySegmentInfo](#querysegmentinfo). ``` message GetQuerySegmentInfoResponse { // Response status common.Status status = 1; // Array of QuerySegmentInfo. See QuerySegmentInfo. repeated QuerySegmentInfo infos = 2; } ``` ## GetMetrics Get server runtime statistics. For more information refer the [document](https://wiki.lfaidata.foundation/display/MIL/MEP+8+--+Add+metrics+for+proxy). ``` rpc GetMetrics(GetMetricsRequest) returns (GetMetricsResponse) {} ``` [back to top](#brief) ### GetMetricsRequest ``` message GetMetricsRequest { // Not useful for now common.MsgBase base = 1; // Request in json format string request = 2; } ``` ### GetMetricsResponse ``` message GetMetricsResponse { // Response status common.Status status = 1; // Response in json format string response = 2; // Metrics from which component string component_name = 3; } ``` ## LoadBalance Handoff segments from one query node to others. Client can use GetPersistentSegmentInfo() to know which segment loaded on which query node, then use LoadBalance() to reassign them into different query node. Return a `common.Status`(see [common.Status](#status)) to tell client whether the operation is successful. For more information, refer this [document](https://wiki.lfaidata.foundation/display/MIL/MEP+17+--+Support+handoff+and+load+balance+segment+on+query+nodes). ``` rpc LoadBalance(LoadBalanceRequest) returns (common.Status) {} ``` [back to top](#brief) ### LoadBalanceRequest ``` message LoadBalanceRequest { // Not useful for now common.MsgBase base = 1; // Source query node id. (Required) int64 src_nodeID = 2; // Target query node id array. (Optional) // If this field is not specified, system will automatically balance load these segments. repeated int64 dst_nodeIDs = 3; // Segment id array to be handoff. (Required) repeated int64 sealed_segmentIDs = 4; } ``` ## GetCompactionState Get a compaction action state. ``` rpc GetCompactionState(GetCompactionStateRequest) returns (GetCompactionStateResponse) {} ``` [back to top](#brief) ### GetCompactionStateRequest ``` message GetCompactionStateRequest { // The compaction id which is returned by ManualCompaction(). int64 compactionID = 1; } ``` ### GetCompactionStateResponse See [common.CompactionState](#compactionstate) ``` message GetCompactionStateResponse { // Response status common.Status status = 1; // Compaction action state. See common.CompactionState. common.CompactionState state = 2; // The runtime plan number which is in progress int64 executingPlanNo = 3; // The time out plan number int64 timeoutPlanNo = 4; // The completed plan number int64 completedPlanNo = 5; } ``` ## ManualCompaction Manually trigger compaction action. ``` rpc ManualCompaction(ManualCompactionRequest) returns (ManualCompactionResponse) {} ``` [back to top](#brief) ### ManualCompactionRequest ``` message ManualCompactionRequest { // Target collection id int64 collectionID = 1; // Setup a timetravel range, segment blob between the range will be compacted uint64 timetravel = 2; } ``` ### ManualCompactionResponse ``` message ManualCompactionResponse { // Response status common.Status status = 1; // Compaction action id int64 compactionID = 2; } ``` ## GetCompactionStateWithPlans Get runtime plans/state for compaction action. ``` rpc GetCompactionStateWithPlans(GetCompactionPlansRequest) returns (GetCompactionPlansResponse) {} ``` [back to top](#brief) ### GetCompactionPlansRequest ``` message GetCompactionPlansRequest { // The compaction action id int64 compactionID = 1; } ``` ### GetCompactionPlansResponse See [common.CompactionState](#compactionstate). See [CompactionMergeInfo](#compactionmergeinfo). ``` message GetCompactionPlansResponse { // Response status common.Status status = 1; // See common.CompactionState common.CompactionState state = 2; // The runtime plans of the compaction action. See CompactionMergeInfo repeated CompactionMergeInfo mergeInfos = 3; } ``` ### CompactionMergeInfo ``` message CompactionMergeInfo { // Segment id array to be merged repeated int64 sources = 1; // New generated segment id after merging int64 target = 2; } ``` ## ShowType ``` enum ShowType { // Will return all colloections All = 0; // Will return loaded collections with their inMemory_percentages InMemory = 1; } ``` [back to top](#brief) ## BoolResponse Used by [HasCollection()](#hascollection) and [HasPartition()](#haspartition). ``` message BoolResponse { // Response status common.Status status = 1; // bool value bool value = 2; } ``` [back to top](#brief) ## MutationResult Used by [Insert()](#insert) and [Delete()](#delete). ``` message MutationResult { // Response status common.Status status = 1; // For insert, return the ids of inserted entities. // For delete, return the ids of input to be deleted. schema.IDs IDs = 2; // Reserved. Indicate succeed indexes. repeated uint32 succ_index = 3; // Reserved. Indicate error indexes. repeated uint32 err_index = 4; // Reserved. bool acknowledged = 5; // Reserved. int64 insert_cnt = 6; // Reserved. int64 delete_cnt = 7; // Reserved. int64 upsert_cnt = 8; // Reserved. uint64 timestamp = 9; } ``` [back to top](#brief) # common.proto ## ErrorCode Error code retrurned by server. ``` enum ErrorCode { Success = 0; UnexpectedError = 1; ConnectFailed = 2; PermissionDenied = 3; CollectionNotExists = 4; IllegalArgument = 5; IllegalDimension = 7; IllegalIndexType = 8; IllegalCollectionName = 9; IllegalTOPK = 10; IllegalRowRecord = 11; IllegalVectorID = 12; IllegalSearchResult = 13; FileNotFound = 14; MetaFailed = 15; CacheFailed = 16; CannotCreateFolder = 17; CannotCreateFile = 18; CannotDeleteFolder = 19; CannotDeleteFile = 20; BuildIndexError = 21; IllegalNLIST = 22; IllegalMetricType = 23; OutOfMemory = 24; IndexNotExist = 25; EmptyCollection = 26; // internal error code. DDRequestRace = 1000; } ``` [back to top](#brief) ## IndexState Used by [GetIndexState()](#getindexstate). ``` enum IndexState { IndexStateNone = 0; // Build index not yet assigned or begin Unissued = 1; // Build index in progress InProgress = 2; // Build index finished Finished = 3; // Build index failed Failed = 4; } ``` [back to top](#brief) ## SegmentState Used by [GetPersistentSegmentInfo()](#getpersistentsegmentinfo) and [GetQuerySegmentInfo()](#getquerysegmentinfo). ``` enum SegmentState { SegmentStateNone = 0; // Segment doesn't exist NotExist = 1; // Segment is in buffer, waiting for insert, not yet persisted Growing = 2; // Segment is in buffer, but is sealed, not allow insert Sealed = 3; // Segment was persisted into storage Flushed = 4; // Segment is to be flushed into storage Flushing = 5; // Segment has been marked as deleted Dropped = 6; } ``` [back to top](#brief) ## Status Used by some interfaces to return server error code and message. See [ErrorCode](#errorcode). ``` message Status { // See ErrorCode ErrorCode error_code = 1; // Fail reason if the error_code is not Success string reason = 2; } ``` [back to top](#brief) ## KeyValuePair Pass key(string)-value(string) paremeters to server, for example "nlist":"1024". ``` message KeyValuePair { string key = 1; string value = 2; } ``` [back to top](#brief) ## KeyDataPair Pass key(string)-value(binary data) paremeters to server. ``` message KeyDataPair { string key = 1; bytes data = 2; } ``` [back to top](#brief) ## DslType Used to support DSL(Domain Specific Language). But now only support expression. Now in [SearchRequest](#searchrequest) the `DslType` always be `BoolExprV1`. ``` enum DslType { Dsl = 0; BoolExprV1 = 1; } ``` [back to top](#brief) ## CompactionState Used by [GetCompactionState()](#getcompactionstate) to get compaction state. ``` enum CompactionState { UndefiedState = 0; // Compaction action is in progress Executing = 1; // Compaction action completed Completed = 2; } ``` [back to top](#brief) # schema.proto ## DataType To define field data type. ``` enum DataType { None = 0; Bool = 1; Int8 = 2; Int16 = 3; Int32 = 4; Int64 = 5; Float = 10; Double = 11; // Not avaiable in v2.0, plan to support in 2.1 String = 20; // Binary vector, each dimension is one bit BinaryVector = 100; // Float vector, each dimension is a float FloatVector = 101; } ``` [back to top](#brief) ## FieldSchema To define field schema. Used by [CreateCollection()](#createcollection). ``` message FieldSchema { // Field unique id, typically sdk ought to automatically set this id for user. int64 fieldID = 1; // Field name. (Required) string name = 2; // Is primary key or not, each collection only has one primary key field. Currently only support int64 type field as primary key. Once string type is supported, string type field also can be primary key. Default is false. bool is_primary_key = 3; // Field description. (Optional) string description = 4; // Field data type, see DataType. DataType data_type = 5; // Extra parameters. Reserved. repeated common.KeyValuePair type_params = 6; // Deprecated repeated common.KeyValuePair index_params = 7; // When it is true, Milvus will automatically generate id for each entity. Only primary key field can set autoID as true. Default is false. bool autoID = 8; } ``` [back to top](#brief) ## CollectionSchema To define collection schema. Used by [CreateCollection()](#createcollection). ``` message CollectionSchema { // Collection name. (Required) string name = 1; // Collection description. (Optional) string description = 2; // Deprecated bool autoID = 3; // Fields schema, see FieldSchema. (Required) repeated FieldSchema fields = 4; } ``` [back to top](#brief) ## BoolArray Bool values array. ``` message BoolArray { repeated bool data = 1; } ``` [back to top](#brief) ## IntArray Integer values array. ``` message IntArray { repeated int32 data = 1; } ``` [back to top](#brief) ## LongArray Long values array. ``` message LongArray { repeated int64 data = 1; } ``` [back to top](#brief) ## FloatArray Float values array. ``` message FloatArray { repeated float data = 1; } ``` [back to top](#brief) ## DoubleArray Double values array. ``` message DoubleArray { repeated double data = 1; } ``` [back to top](#brief) ## BytesArray Byte values array. For special fields such as binary vector. ``` message BytesArray { repeated bytes data = 1; } ``` [back to top](#brief) ## StringArray String values array. String type is planned in v2.1. ``` message StringArray { repeated string data = 1; } ``` [back to top](#brief) ## ScalarField Store data for non-vector field. ``` message ScalarField { oneof data { BoolArray bool_data = 1; IntArray int_data = 2; LongArray long_data = 3; FloatArray float_data = 4; DoubleArray double_data = 5; StringArray string_data = 6; BytesArray bytes_data = 7; } } ``` [back to top](#brief) ## VectorField Store data for vector field. ``` message VectorField { // Vector dimension int64 dim = 1; oneof data { // For float vectors. The array size is vector_count*dimension. FloatArray float_vector = 2; // For binary vectors. The array size is vector_count*dimension/8. bytes binary_vector = 3; } } ``` [back to top](#brief) ## FieldData Represent a field. Can be vector field or scalar field. Used by [Insert()](#insert). ``` message FieldData { // Field data type DataType type = 1; // Field name. (Required) string field_name = 2; oneof field { // For scalar field ScalarField scalars = 3; // For vector field VectorField vectors = 4; } // Deprecated int64 field_id = 5; } ``` [back to top](#brief) ## IDs Represent an array of ID. Used by [Insert()](#insert)/[Delete()](#delete)/[Query()](#query), return id array. ``` message IDs { oneof id_field { // Long id array LongArray int_id = 1; // String id array. String id is planned in v2.1. StringArray str_id = 2; } } ``` [back to top](#brief) ## SearchResultData Used by [Search()](#search), to return search results. ``` message SearchResultData { // Target vectors count int64 num_queries = 1; // Specified search topK int64 top_k = 2; // Return field data specified by output field names. See Search() repeated FieldData fields_data = 3; // TopK scores array. The array size is num_queries*topK. repeated float scores = 4; // TopK ids array. The array size is num_queries*topK. IDs ids = 5; // Sometimes not all target vectors return same topK result. The topks will tell client the topK of each target vector. repeated int64 topks = 6; } ``` [back to top](#brief)