test/milvus
1
0
Fork 0
mirror of https://gitee.com/milvus-io/milvus.git synced 2024-12-05 05:18:52 +08:00
Code Issues Actions 14 Packages Projects Releases Wiki Activity
b4c334ffdb
milvus/docs/design_docs/milvus_proto.md
binbin 93071c16e8
[skip e2e] Fix grammer error (#14187) 
Signed-off-by: Binbin Lv <binbin.lv@zilliz.com>
2021-12-24 17:06:29 +08:00

45 KiB
Raw Blame History

Brief

This document will help SDK developers to understand each API of Milvus RPC proto.

Table of contents

=================

milvus.proto

CreateCollection

Create a collection with schema. Return a common.Status(see common.Status) to tell client whether the operation is successful.

rpc CreateCollection(CreateCollectionRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful.

rpc DropCollection(DropCollectionRequest) returns (common.Status) {}

back to top

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 to tell client whether the collection is exist.

rpc HasCollection(HasCollectionRequest) returns (BoolResponse) {}

back to top

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) to tell client whether the operation is successful. Note: this interface only send a request to server ask to load collection, it returns at once after the request is consumed. Collection loading progress is asynchronously.

rpc LoadCollection(LoadCollectionRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful.

rpc ReleaseCollection(ReleaseCollectionRequest) returns (common.Status) {}

back to top

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

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. (Required)
  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

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. (Required)
  string collection_name = 3;
}

GetCollectionStatisticsResponse

See common.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

ShowCollectionsRequest

See 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) to tell client whether the operation is successful.

rpc CreatePartition(CreatePartitionRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful.

rpc DropPartition(DropPartitionRequest) returns (common.Status) {}

back to top

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 to tell client whether the partition exists

rpc HasPartition(HasPartitionRequest) returns (BoolResponse) {}

back to top

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) to tell client whether the operation is successful. Note: this interface only send a request to server ask to load partitions, it returns at once after the request is consumed. Loading progress is asynchronously.

rpc LoadPartitions(LoadPartitionsRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful.

rpc ReleasePartitions(ReleasePartitionsRequest) returns (common.Status) {}

back to top

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

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

ShowPartitionsRequest

See 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) to tell client whether the operation is successful. For more information please refer the document.

rpc CreateAlias(CreateAliasRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful. For more information please refer the document.

rpc DropAlias(DropAliasRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful. For more information please refer the document.

rpc AlterAlias(AlterAliasRequest) returns (common.Status) {}

back to top

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) to tell client whether the operation is successful.

rpc CreateIndex(CreateIndexRequest) returns (common.Status) {}

back to top

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

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

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

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

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) to tell client whether the operation is successful.

rpc DropIndex(DropIndexRequest) returns (common.Status) {}

back to top

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.

rpc Insert(InsertRequest) returns (MutationResult) {}

back to top

InsertRequest

See scheml.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.

rpc Delete(DeleteRequest) returns (MutationResult) {}

back to top

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

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.

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

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<string, schema.LongArray> coll_segIDs = 3;
}

Query

Retrieve entities by expression.

rpc Query(QueryRequest) returns (QueryResults) {}

back to top

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.

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

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, schema.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. See schema.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. See schema.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

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.

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.

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

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.

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.

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.

rpc GetMetrics(GetMetricsRequest) returns (GetMetricsResponse) {}

back to top

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) to tell client whether the operation is successful. For more information, refer this document.

rpc LoadBalance(LoadBalanceRequest) returns (common.Status) {}

back to top

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

GetCompactionStateRequest

message GetCompactionStateRequest {
  // The compaction id which is returned by ManualCompaction().
  int64 compactionID = 1;
}

GetCompactionStateResponse

See common.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

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

GetCompactionPlansRequest

message GetCompactionPlansRequest {
  // The compaction action id
  int64 compactionID = 1;
}

GetCompactionPlansResponse

See common.CompactionState. See 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

Used by [ShowCollections()]](#showcollections) and ShowPartitions().

enum ShowType {
  // Will return all colloections/partitions
  All = 0;

  // Will return loaded collections/partitions with their inMemory_percentages
  InMemory = 1;
}

back to top

BoolResponse

Used by HasCollection() and HasPartition().

message BoolResponse {
  // Response status
  common.Status status = 1;

  // bool value
  bool value = 2;
}

back to top

MutationResult

Used by Insert() and 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

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

IndexState

Used by 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

SegmentState

Used by GetPersistentSegmentInfo() and 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

Status

Used by some interfaces to return server error code and message. See ErrorCode.

message Status {
  // See ErrorCode
  ErrorCode error_code = 1;
  
  // Fail reason if the error_code is not Success
  string reason = 2;
}

back to top

KeyValuePair

Pass key(string)-value(string) paremeters to server, for example "nlist":"1024".

message KeyValuePair {
    string key = 1;
    string value = 2;
}

back to top

KeyDataPair

Pass key(string)-value(binary data) paremeters to server.

message KeyDataPair {
    string key = 1;
    bytes data = 2;
}

back to top

DslType

Used to support DSL(Domain Specific Language). But now only support expression. Now in SearchRequest the DslType always be BoolExprV1.

enum DslType {
    Dsl = 0;
    BoolExprV1 = 1;
}

back to top

CompactionState

Used by GetCompactionState() to get compaction state.

enum CompactionState {
  UndefiedState = 0;

  // Compaction action is in progress
  Executing = 1;

  // Compaction action completed
  Completed = 2;
}

back to top

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

FieldSchema

To define field schema. Used by 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

CollectionSchema

To define collection schema. Used by 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

BoolArray

Bool values array.

message BoolArray {
  repeated bool data = 1;
}

back to top

IntArray

Integer values array.

message IntArray {
  repeated int32 data = 1;
}

back to top

LongArray

Long values array.

message LongArray {
  repeated int64 data = 1;
}

back to top

FloatArray

Float values array.

message FloatArray {
  repeated float data = 1;
}

back to top

DoubleArray

Double values array.

message DoubleArray {
  repeated double data = 1;
}

back to top

BytesArray

Byte values array. For special fields such as binary vector. Note: each bit is one dimension.

message BytesArray {
  repeated bytes data = 1;
}

back to top

StringArray

String values array. String type is planned in v2.1.

message StringArray {
  repeated string data = 1;
}

back to top

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

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

FieldData

Represent a field. Can be vector field or scalar field. Used by 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

IDs

Represent an array of ID. Used by Insert()/Delete()/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

SearchResultData

Used by 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