diff --git a/apis/docs/v1/flush.md b/apis/docs/v1/flush.md
new file mode 100644
index 0000000000..fb5b4478bf
--- /dev/null
+++ b/apis/docs/v1/flush.md
@@ -0,0 +1,67 @@
+# Vald Flush APIs
+
+## Overview
+
+Flush Service is responsible for removing all vectors that are indexed and uncommitted in the `vald-agent`.
+
+```rpc
+service Flush {
+
+ rpc Flush(payload.v1.Flush.Request) returns (payload.v1.Info.Index.Count) {}
+
+}
+```
+
+## Flush RPC
+
+Flush RPC is the method to remove all vectors.
+
+### Input
+
+- the scheme of `payload.v1.Flush.Request`
+
+ ```rpc
+ message Flush {
+ message Request {
+ }
+ }
+ ```
+
+ - Flush.Request
+
+ empty
+
+### Output
+
+- the scheme of `payload.v1.Info.Index.Count`
+
+ ```rpc
+ message Object {
+ message Info_Index_Count {
+ uint32 stored = 0;
+ uint32 uncommitted = 0;
+ bool indexing = false;
+ bool saving = false;
+ }
+ }
+ ```
+
+ Object.Info_Index_Count
+
+ | field | type | label | desc. |
+ | :---------: | :----- | :---- | :------------------------------------------------------------------------- |
+ | stored | uint32 | | count of indices. |
+ | uncommitted | uint32 | | count of uncommitted indices. |
+ | indexing | bool | | the state indicating whether `vald-agent` pods is present in the indexing. |
+ | saving | bool | | the state indicating whether `vald-agent` pods is present in the saving. |
+
+### Status Code
+
+| code | desc. |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 13 | INTERNAL |
diff --git a/apis/docs/v1/insert.md b/apis/docs/v1/insert.md
new file mode 100644
index 0000000000..eae2bd7dce
--- /dev/null
+++ b/apis/docs/v1/insert.md
@@ -0,0 +1,366 @@
+# Vald Insert APIs
+
+## Overview
+
+Insert Service is responsible for inserting new vectors into the `vald-agent`.
+
+```rpc
+service Insert {
+ rpc Insert(payload.v1.Insert.Request) returns (payload.v1.Object.Location) {}
+
+ rpc StreamInsert(stream payload.v1.Insert.Request) returns (stream payload.v1.Object.Location) {}
+
+ rpc MultiInsert(payload.v1.Insert.MultiRequest) returns (payload.v1.Object.Locations) {}
+}
+```
+
+## Insert RPC
+
+Inset RPC is the method to add a new single vector.
+
+### Input
+
+- the scheme of `payload.v1.Insert.Request`
+
+ ```rpc
+ message Insert {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Insert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the insert request. |
+
+ - Insert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Location`
+
+ ```rpc
+ message Object {
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is inserted. |
+ | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Request ID is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamInsert RPC
+
+StreamInsert RPC is the method to add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server.
+Each Insert request and response are independent.
+It's the recommended method to insert a large number of vectors.
+
+### Input
+
+- the scheme of `payload.v1.Insert.Request stream`
+
+ ```rpc
+ message Insert {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Insert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the insert request. |
+
+ - Insert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for the filter targets. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :--------------------------------------------------------------- |
+ | id | string | | \* | The ID of the vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.StreamLocation`
+
+ ```rpc
+ message Object {
+ message StreamLocation {
+ oneof payload {
+ Location location = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.StreamLocation
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :----------------------------------------- |
+ | location | Object.Location | | The information of `Object.Location` data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is inserted. |
+ | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. |
+
+ - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto)
+
+ | field | type | label | description |
+ | :-----: | :------------------ | :------------------- | :-------------------------------------- |
+ | code | int32 | | Status code (code list is next section) |
+ | message | string | | Error message |
+ | details | google.protobuf.Any | repeated(Array[any]) | The details error message list |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Request ID is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiInsert RPC
+
+MultiInsert RPC is the method to add multiple new vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Insert.MultiRequest`
+
+ ```rpc
+ message Insert {
+ message MultiRequest { repeated Request requests = 1; }
+
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Insert.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :------------- | :------------------------------ | :------: | :---------------- |
+ | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | The request list. |
+
+ - Insert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the insert request. |
+
+ - Insert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for the filter targets. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Locations`.
+
+ ```rpc
+ message Object {
+ message Locations { repeated Location locations = 1; }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Locations
+
+ | field | type | label | description |
+ | :------: | :-------------- | :------------------------------- | :----------------------------- |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is inserted. |
+ | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Request ID is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
diff --git a/apis/docs/v1/object.md b/apis/docs/v1/object.md
new file mode 100644
index 0000000000..a9e37ea9d0
--- /dev/null
+++ b/apis/docs/v1/object.md
@@ -0,0 +1,259 @@
+# Vald Object APIs
+
+## Overview
+
+Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent`.
+
+```rpc
+service Object {
+ rpc Exists(payload.v1.Object.ID) returns (payload.v1.Object.ID) {}
+
+ rpc GetObject(payload.v1.Object.VectorRequest)
+ returns (payload.v1.Object.Vector) {}
+
+ rpc StreamGetObject(stream payload.v1.Object.VectorRequest)
+ returns (stream payload.v1.Object.StreamVector) {}
+}
+```
+
+## Exists RPC
+
+Exists RPC is the method to check that a vector exists in the `vald-agent`.
+
+### Input
+
+- the scheme of `payload.v1.Object.ID`
+
+ ```rpc
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.ID`
+
+ ```rpc
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Object.ID
+
+ | field | type | label | description |
+ | :---: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## GetObject RPC
+
+GetObject RPC is the method to get the metadata of a vector inserted into the `vald-agent`.
+
+### Input
+
+- the scheme of `payload.v1.Object.VectorRequest`
+
+ ```rpc
+ message Object {
+ message VectorRequest {
+ ID id = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Filter.Config filters = 2;
+ }
+
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Object.VectorRequest
+
+ | field | type | label | required | description |
+ | :-----: | :------------ | :---- | :------: | :------------------------------------------------------------- |
+ | id | Object.ID | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | filters | Filter.Config | | | Configuration for filter. |
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Vector`
+
+ ```rpc
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Object.Vector
+
+ | field | type | label | description |
+ | :----: | :----- | :--------------------- | :------------------------------------------------------------- |
+ | id | string | | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | The vector data. Its dimension is between 2 and 65,536. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamGetObject RPC
+
+StreamGetObject RPC is the method to get the metadata of multiple existing vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the GetObject request can be communicated in any order between client and server.
+Each Upsert request and response are independent.
+
+- the scheme of `payload.v1.Object.VectorRequest stream`
+
+ ```rpc
+ message Object {
+ message VectorRequest {
+ ID id = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Filter.Config filters = 2;
+ }
+
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Object.VectorRequest
+
+ | field | type | label | required | description |
+ | :-----: | :------------ | :---- | :------: | :------------------------------------------------------------- |
+ | id | Object.ID | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | filters | Filter.Config | | | Configuration for the filter targets. |
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.StreamVector`
+
+ ```rpc
+ message Object {
+ message StreamVector {
+ oneof payload {
+ Vector vector = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Object.StreamVector
+
+ | field | type | label | description |
+ | :----: | :---------------- | :---- | :------------------------------------- |
+ | vector | Vector | | The information of Object.Vector data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Object.Vector
+
+ | field | type | label | description |
+ | :----: | :----- | :--------------------- | :------------------------------------------------------------- |
+ | id | string | | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | The vector data. Its dimension is between 2 and 65,536. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
diff --git a/apis/docs/v1/remove.md b/apis/docs/v1/remove.md
new file mode 100644
index 0000000000..2846ea08ee
--- /dev/null
+++ b/apis/docs/v1/remove.md
@@ -0,0 +1,482 @@
+# Vald Remove APIs
+
+## Overview
+
+Remove Service is responsible for removing vectors indexed in the `vald-agent`.
+
+```rpc
+service Remove {
+
+ rpc Remove(payload.v1.Remove.Request) returns (payload.v1.Object.Location) {}
+
+ rpc RemoveByTimestamp(payload.v1.Remove.TimestampRequest) returns (payload.v1.Object.Locations) {}
+
+ rpc StreamRemove(stream payload.v1.Remove.Request)
+ returns (stream payload.v1.Object.StreamLocation) {}
+
+ rpc MultiRemove(payload.v1.Remove.MultiRequest)
+ returns (payload.v1.Object.Locations) {}
+}
+```
+
+## Remove RPC
+
+Remove RPC is the method to remove a single vector.
+
+### Input
+
+- the scheme of `payload.v1.Remove.Request`
+
+ ```rpc
+ message Remove {
+ message Request {
+ Object.ID id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Remove.Request
+
+ | field | type | label | required | description |
+ | :----: | :-------- | :---- | :------: | :--------------------------------------- |
+ | id | Object.ID | | \* | The ID of vector. |
+ | config | Config | | \* | The configuration of the remove request. |
+
+ - Remove.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. |
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Location`
+
+ ```rpc
+ message Object {
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is removed. |
+ | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## RemoveByTimestamp RPC
+
+RemoveByTimestamp RPC is the method to remove vectors based on timestamp.
+
+### Input
+
+- the scheme of `payload.v1.Remove.TimestampRequest`
+
+ ```rpc
+ message Remove {
+ message TimestampRequest {
+ repeated Timestamp timestamps = 1;
+ }
+
+ message Timestamp {
+ enum Operator {
+ Eq = 0;
+ Ne = 1;
+ Ge = 2;
+ Gt = 3;
+ Le = 4;
+ Lt = 5;
+ }
+ int64 timestamp = 1;
+ Operator operator = 2;
+ }
+ }
+
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Remove.TimestampRequest
+
+ | field | type | label | required | description |
+ | :--------: | :--------------- | :-------------------------------- | :------: | :-------------------------------------------------------------------------------------------- |
+ | timestamps | Remove.Timestamp | repeated(Array[Remove.Timestamp]) | \* | The timestamp comparison list.
If more than one is specified, the `AND` search is applied. |
+
+ - Remove.Timestamp
+
+ | field | type | label | required | description |
+ | :-------: | :------------------------ | :---- | :------: | :------------------------------------------------- |
+ | timestamp | int64 | | \* | The timestamp. |
+ | operator | Remove.Timestamp.Operator | | | The conditional operator. (default value is `Eq`). |
+
+ - Remove.Timestamp.Operator
+
+ | value | description |
+ | :---: | :--------------------- |
+ | Eq | Equal. |
+ | Ne | Not Equal. |
+ | Ge | Greater than or Equal. |
+ | Gt | Greater than. |
+ | Le | Less than or Equal. |
+ | Lt | Less than. |
+
+
+ In the TimestampRequest message, the 'timestamps' field is repeated, allowing the inclusion of multiple Timestamp.
+ When multiple Timestamps are provided, it results in an `AND` condition, enabling the realization of deletions with specified ranges.
+ This design allows for versatile deletion operations, facilitating tasks such as removing data within a specific time range.
+
+
+### Output
+
+- the scheme of `payload.v1.Object.Locations`.
+
+ ```rpc
+ message Object {
+ message Locations { repeated Location locations = 1; }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Locations
+
+ | field | type | label | description |
+ | :------: | :-------------- | :------------------------------- | :----------------------------- |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is removed. |
+ | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | No vectors in the system match the specified timestamp conditions. | Check whether vectors matching the specified timestamp conditions exist in the system, and fix conditions if needed. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamRemove RPC
+
+StreamRemove RPC is the method to remove multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the remove request can be communicated in any order between client and server.
+Each Remove request and response are independent.
+It's the recommended method to remove a large number of vectors.
+
+### Input
+
+- the scheme of `payload.v1.Remove.Request stream`
+
+ ```rpc
+ message Remove {
+ message Request {
+ Object.ID id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Remove.Request
+
+ | field | type | label | required | description |
+ | :----: | :-------- | :---- | :------: | :--------------------------------------- |
+ | id | Object.ID | | \* | The ID of vector. |
+ | config | Config | | \* | The configuration of the insert request. |
+
+ - Remove.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. |
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.StreamLocation`
+
+ ```rpc
+ message Object {
+ message StreamLocation {
+ oneof payload {
+ Location location = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.StreamLocation
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :----------------------------------------- |
+ | location | Object.Location | | The information of `Object.Location` data. |
+ | status | google.rpc.Status | | The status of Google RPC |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is removed. |
+ | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. |
+
+ - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto)
+
+ | field | type | label | description |
+ | :-----: | :------------------ | :------------------- | :-------------------------------------- |
+ | code | int32 | | Status code (code list is next section) |
+ | message | string | | Error message |
+ | details | google.protobuf.Any | repeated(Array[any]) | The details error message list |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiRemove RPC
+
+MultiRemove is the method to remove multiple vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Remove.MultiRequest`
+
+ ```rpc
+ message Remove {
+ message MultiRequest {
+ repeated Request requests = 1;
+ }
+
+ message Request {
+ Object.ID id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message ID {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ }
+ }
+ ```
+
+ - Remove.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :------------- | :------------------------------ | :------: | :--------------- |
+ | requests | Remove.Request | repeated(Array[Insert.Request]) | \* | the request list |
+
+ - Remove.Request
+
+ | field | type | label | required | description |
+ | :----: | :-------- | :---- | :------: | :--------------------------------------- |
+ | id | Object.ID | | \* | The ID of vector. |
+ | config | Config | | \* | The configuration of the remove request. |
+
+ - Remove.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. |
+
+ - Object.ID
+
+ | field | type | label | required | description |
+ | :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Locations`.
+
+ ```rpc
+ message Object {
+ message Locations { repeated Location locations = 1; }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Locations
+
+ | field | type | label | description |
+ | :------: | :-------------- | :------------------------------- | :----------------------------- |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is removed. |
+ | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
diff --git a/apis/docs/v1/search.md b/apis/docs/v1/search.md
new file mode 100644
index 0000000000..ccec2863d0
--- /dev/null
+++ b/apis/docs/v1/search.md
@@ -0,0 +1,1628 @@
+# Vald Search APIs
+
+## Overview
+
+Search Service is responsible for searching vectors similar to the user request vector from `vald-agent`.
+
+```rpc
+service Search {
+ rpc Search(payload.v1.Search.Request) returns (payload.v1.Search.Response) {}
+
+ rpc SearchByID(payload.v1.Search.IDRequest)
+ returns (payload.v1.Search.Response) {}
+
+ rpc StreamSearch(stream payload.v1.Search.Request)
+ returns (stream payload.v1.Search.StreamResponse) {}
+
+ rpc StreamSearchByID(stream payload.v1.Search.IDRequest)
+ returns (stream payload.v1.Search.StreamResponse) {}
+
+ rpc MultiSearch(payload.v1.Search.MultiRequest)
+ returns (payload.v1.Search.Responses) {}
+
+ rpc MultiSearchByID(payload.v1.Search.MultiIDRequest)
+ returns (payload.v1.Search.Responses) {}
+
+ rpc LinearSearch(payload.v1.Search.Request) returns (payload.v1.Search.Response) {}
+
+ rpc LinearSearchByID(payload.v1.Search.IDRequest)
+ returns (payload.v1.Search.Response) {}
+
+ rpc StreamLinearSearch(stream payload.v1.Search.Request)
+ returns (stream payload.v1.Search.StreamResponse) {}
+
+ rpc StreamLinearSearchByID(stream payload.v1.Search.IDRequest)
+ returns (stream payload.v1.Search.StreamResponse) {}
+
+ rpc MultiLinearSearch(payload.v1.Search.MultiRequest)
+ returns (payload.v1.Search.Responses) {}
+
+ rpc MultiLinearSearchByID(payload.v1.Search.MultiIDRequest)
+ returns (payload.v1.Search.Responses) {}
+}
+```
+
+## Search RPC
+
+Search RPC is the method to search vector(s) similar to the request vector.
+
+### Input
+
+- the scheme of `payload.v1.Search.Request`
+
+ ```rpc
+ message Search {
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Response`.
+
+ ```rpc
+ message Search {
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## SearchByID RPC
+
+SearchByID RPC is the method to search similar vectors using a user-defined vector ID.
+The vector with the same requested ID should be indexed into the `vald-agent` before searching.
+
+### Input
+
+- the scheme of `payload.v1.Search.IDRequest`
+
+ ```rpc
+ message Search {
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Response`.
+
+ ```rpc
+ message Search {
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamSearch RPC
+
+StreamSearch RPC is the method to search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server.
+Each Search request and response are independent.
+
+### Input
+
+- the scheme of `payload.v1.Search.Request stream`
+
+ ```rpc
+ message Search {
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.StreamResponse`.
+
+ ```rpc
+ message Search {
+ message StreamResponse {
+ oneof payload {
+ Response response = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.StreamResponse
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamSearchByID RPC
+
+StreamSearchByID RPC is the method to search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server.
+Each SearchByID request and response are independent.
+
+### Input
+
+- the scheme of `payload.v1.Search.IDRequest stream`
+
+ ```rpc
+ message Search {
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.StreamResponse`.
+
+ ```rpc
+ message Search {
+ message StreamResponse {
+ oneof payload {
+ Response response = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.StreamResponse
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiSearch RPC
+
+MultiSearch RPC is the method to search vectors with multiple vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Search.MultiRequest`
+
+ ```rpc
+ message Search {
+ message MultiRequest {
+ repeated Request requests = 1;
+ }
+
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :----------------------- | :---- | :------: | :----------------------- |
+ | requests | repeated(Array[Request]) | | \* | The search request list. |
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Responses`.
+
+ ```rpc
+ message Search {
+ message Responses {
+ repeated Response responses = 1;
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Responses
+
+ | field | type | label | description |
+ | :-------: | :------- | :------------------------ | :----------------------------------- |
+ | responses | Response | repeated(Array[Response]) | The list of search results response. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiSearchByID RPC
+
+MultiSearchByID RPC is the method to search vectors with multiple IDs in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Search.MultiIDRequest stream`
+
+ ```rpc
+ message Search {
+
+ message MultiIDRequest {
+ repeated IDRequest requests = 1;
+ }
+
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ float radius = 3;
+ float epsilon = 4;
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.MultiIDRequest
+
+ | field | type | label | required | description |
+ | :------: | :-------- | :------------------------- | :------: | :--------------------------- |
+ | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. |
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | radius | float | | \* | The search radius. |
+ | epsilon | float | | \* | The search coefficient (default value is `0.1`). |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Responses`.
+
+ ```rpc
+ message Search {
+ message Responses {
+ repeated Response responses = 1;
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Responses
+
+ | field | type | label | description |
+ | :-------: | :------- | :------------------------ | :----------------------------------- |
+ | responses | Response | repeated(Array[Response]) | The list of search results response. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## LinearSearch RPC
+
+LinearSearch RPC is the method to linear search vector(s) similar to the request vector.
+
+### Input
+
+- the scheme of `payload.v1.Search.Request`
+
+ ```rpc
+ message Search {
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Response`.
+
+ ```rpc
+ message Search {
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## LinearSearchByID RPC
+
+LinearSearchByID RPC is the method to linear search similar vectors using a user-defined vector ID.
+The vector with the same requested ID should be indexed into the `vald-agent` before searching.
+You will get a `NOT_FOUND` error if the vector isn't stored.
+
+### Input
+
+- the scheme of `payload.v1.Search.IDRequest`
+
+ ```rpc
+ message Search {
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Response`.
+
+ ```rpc
+ message Search {
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamLinearSearch RPC
+
+StreamLinearSearch RPC is the method to linear search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server.
+Each LinearSearch request and response are independent.
+
+### Input
+
+- the scheme of `payload.v1.Search.Request stream`
+
+ ```rpc
+ message Search {
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.StreamResponse`.
+
+ ```rpc
+ message Search {
+ message StreamResponse {
+ oneof payload {
+ Response response = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.StreamResponse
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamLinearSearchByID RPC
+
+StreamLinearSearchByID RPC is the method to linear search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server.
+Each LinearSearchByID request and response are independent.
+
+### Input
+
+- the scheme of `payload.v1.Search.IDRequest stream`
+
+ ```rpc
+ message Search {
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.StreamResponse`.
+
+ ```rpc
+ message Search {
+ message StreamResponse {
+ oneof payload {
+ Response response = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.StreamResponse
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiLinearSearch RPC
+
+MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Search.MultiRequest`
+
+ ```rpc
+ message Search {
+ message MultiRequest {
+ repeated Request requests = 1;
+ }
+
+ message Request {
+ repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :----------------------- | :---- | :------: | :---------------------- |
+ | requests | repeated(Array[Request]) | | \* | The search request list |
+
+ - Search.Request
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Responses`.
+
+ ```rpc
+ message Search {
+ message Responses {
+ repeated Response responses = 1;
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Responses
+
+ | field | type | label | description |
+ | :-------: | :------- | :------------------------ | :---------------------------------- |
+ | responses | Response | repeated(Array[Response]) | The list of search results response |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiLinearSearchByID RPC
+
+MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Search.MultiIDRequest stream`
+
+ ```rpc
+ message Search {
+
+ message MultiIDRequest {
+ repeated IDRequest requests = 1;
+ }
+
+ message IDRequest {
+ string id = 1;
+ Config config = 2;
+ }
+
+ message Config {
+ string request_id = 1;
+ uint32 num = 2 [ (validate.rules).uint32.gte = 1 ];
+ int64 timeout = 5;
+ Filter.Config ingress_filters = 6;
+ Filter.Config egress_filters = 7;
+ uint32 min_num = 8;
+ AggregationAlgorithm aggregation_algorithm = 9;
+ }
+ }
+
+ enum AggregationAlgorithm {
+ Unknown = 0;
+ ConcurrentQueue = 1;
+ SortSlice = 2;
+ SortPoolSlice = 3;
+ PairingHeap = 4;
+ }
+ ```
+
+ - Search.MultiIDRequest
+
+ | field | type | label | required | description |
+ | :------: | :-------- | :------------------------- | :------: | :--------------------------- |
+ | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. |
+
+ - Search.IDRequest
+
+ | field | type | label | required | description |
+ | :----: | :----- | :---- | :------: | :--------------------------------------- |
+ | id | string | | \* | The vector ID to be searched. |
+ | config | Config | | \* | The configuration of the search request. |
+
+ - Search.Config
+
+ | field | type | label | required | description |
+ | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- |
+ | request_id | string | | | Unique request ID. |
+ | num | uint32 | | \* | The maximum number of results to be returned. |
+ | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). |
+ | ingress_filters | Filter.Config | | | Ingress Filter configuration. |
+ | egress_filters | Filter.Config | | | Egress Filter configuration. |
+ | min_num | uint32 | | | The minimum number of results to be returned. |
+ | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). |
+
+### Output
+
+- the scheme of `payload.v1.Search.Responses`.
+
+ ```rpc
+ message Search {
+ message Responses {
+ repeated Response responses = 1;
+ }
+
+ message Response {
+ string request_id = 1;
+ repeated Object.Distance results = 2;
+ }
+ }
+
+ message Object {
+ message Distance {
+ string id = 1;
+ float distance = 2;
+ }
+ }
+ ```
+
+ - Search.Responses
+
+ | field | type | label | description |
+ | :-------: | :------- | :------------------------ | :----------------------------------- |
+ | responses | Response | repeated(Array[Response]) | The list of search results response. |
+
+ - Search.Response
+
+ | field | type | label | description |
+ | :--------: | :-------------- | :------------------------------- | :--------------------- |
+ | request_id | string | | The unique request ID. |
+ | results | Object.Distance | repeated(Array[Object.Distance]) | Search results. |
+
+ - Object.Distance
+
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
diff --git a/apis/docs/v1/update.md b/apis/docs/v1/update.md
new file mode 100644
index 0000000000..2fb68b05f7
--- /dev/null
+++ b/apis/docs/v1/update.md
@@ -0,0 +1,375 @@
+# Vald Update APIs
+
+## Overview
+
+Update Service updates to new vector from inserted vector in the `vald-agent` components.
+
+```rpc
+service Update {
+ rpc Update(payload.v1.Update.Request) returns (payload.v1.Object.Location) {}
+
+ rpc StreamUpdate(stream payload.v1.Update.Request) returns (stream payload.v1.Object.Location) {}
+
+ rpc MultiUpdate(payload.v1.Update.MultiRequest) returns (stream payload.v1.Object.Locations) {}
+}
+```
+
+## Update RPC
+
+Update RPC is the method to update a single vector.
+
+### Input
+
+- the scheme of `payload.v1.Update.Request`
+
+ ```rpc
+ message Update {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated.min_items = 2 ];
+ }
+ }
+ ```
+
+ - Update.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Update.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Location`
+
+ ```rpc
+ message Object {
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated. |
+ | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamUpdate RPC
+
+StreamUpdate RPC is the method to update multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the update request can be communicated in any order between client and server.
+Each Update request and response are independent.
+It's the recommended method to update the large amount of vectors.
+
+### Input
+
+- the scheme of `payload.v1.Update.Request stream`
+
+ ```rpc
+ message Update {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Update.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Update.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.StreamLocation`
+
+ ```rpc
+ message Object {
+ message StreamLocation {
+ oneof payload {
+ Location location = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.StreamLocation
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :--------------------------------------- |
+ | location | Object.Location | | The information of Object.Location data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated. |
+ | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. |
+
+ - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto)
+
+ | field | type | label | description |
+ | :-----: | :------------------ | :------------------- | :-------------------------------------- |
+ | code | int32 | | Status code (code list is next section) |
+ | message | string | | Error message |
+ | details | google.protobuf.Any | repeated(Array[any]) | The details error message list |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiUpdate RPC
+
+MultiUpdate is the method to update multiple vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Update.MultiRequest`
+
+ ```rpc
+ message Update {
+ message MultiRequest { repeated Request requests = 1; }
+
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Update.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :------------- | :------------------------------ | :------: | :---------------- |
+ | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | The request list. |
+
+ - Update.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Update.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Locations`.
+
+ ```rpc
+ message Object {
+ message Locations { repeated Location locations = 1; }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Locations
+
+ | field | type | label | description |
+ | :------: | :-------------- | :------------------------------- | :----------------------------- |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated. |
+ | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 5 | NOT_FOUND |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. |
+| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
diff --git a/apis/docs/v1/upsert.md b/apis/docs/v1/upsert.md
new file mode 100644
index 0000000000..9ed9f6572c
--- /dev/null
+++ b/apis/docs/v1/upsert.md
@@ -0,0 +1,373 @@
+# Vald Upsert APIs
+
+## Overview
+
+Upsert Service is responsible for updating existing vectors in the `vald-agent` or inserting new vectors into the `vald-agent` if the vector does not exist.
+
+```rpc
+service Upsert {
+
+ rpc Upsert(payload.v1.Upsert.Request)
+ returns (payload.v1.Object.Location) {}
+
+ rpc StreamUpsert(stream payload.v1.Upsert.Request)
+ returns (stream payload.v1.Object.StreamLocation) {}
+
+ rpc MultiUpsert(payload.v1.Upsert.MultiRequest)
+ returns (payload.v1.Object.Locations) {}
+}
+```
+
+## Upsert RPC
+
+Upsert RPC is the method to update the inserted vector to a new single vector or add a new single vector if not inserted before.
+
+### Input
+
+- the scheme of `payload.v1.Upsert.Request`
+
+ ```rpc
+ message Upsert {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Upsert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Upsert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Location`
+
+ ```rpc
+ message Object {
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :----------------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated/inserted. |
+ | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## StreamUpsert RPC
+
+StreamUpsert RPC is the method to update multiple existing vectors or add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the upsert request can be communicated in any order between the client and server.
+Each Upsert request and response are independent.
+It’s the recommended method to upsert a large number of vectors.
+
+### Input
+
+- the scheme of `payload.v1.Upsert.Request stream`
+
+ ```rpc
+ message Upsert {
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Upsert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Upsert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.StreamLocation`
+
+ ```rpc
+ message Object {
+ message StreamLocation {
+ oneof payload {
+ Location location = 1;
+ google.rpc.Status status = 2;
+ }
+ }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.StreamLocation
+
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :--------------------------------------- |
+ | location | Object.Location | | The information of Object.Location data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :----------------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated/inserted. |
+ | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. |
+
+ - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto)
+
+ | field | type | label | description |
+ | :-----: | :------------------ | :------------------- | :-------------------------------------- |
+ | code | int32 | | Status code (code list is next section) |
+ | message | string | | Error message |
+ | details | google.protobuf.Any | repeated(Array[any]) | The details error message list |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |
+
+## MultiUpsert RPC
+
+MultiUpsert is the method to update existing multiple vectors and add new multiple vectors in **1** request.
+
+
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
+
+
+### Input
+
+- the scheme of `payload.v1.Upsert.MultiRequest`
+
+ ```rpc
+ message Upsert {
+ message MultiRequest { repeated Request requests = 1; }
+
+ message Request {
+ Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ];
+ Config config = 2;
+ }
+
+ message Config {
+ bool skip_strict_exist_check = 1;
+ Filter.Config filters = 2;
+ int64 timestamp = 3;
+ }
+ }
+
+ message Object {
+ message Vector {
+ string id = 1 [ (validate.rules).string.min_len = 1 ];
+ repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ];
+ }
+ }
+ ```
+
+ - Upsert.MultiRequest
+
+ | field | type | label | required | description |
+ | :------: | :------------- | :------------------------------ | :------: | :---------------- |
+ | requests | Upsert.Request | repeated(Array[Insert.Request]) | \* | The request list. |
+
+ - Upsert.Request
+
+ | field | type | label | required | description |
+ | :----: | :------------ | :---- | :------: | :--------------------------------------- |
+ | vector | Object.Vector | | \* | The information of vector. |
+ | config | Config | | \* | The configuration of the update request. |
+
+ - Upsert.Config
+
+ | field | type | label | required | description |
+ | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ |
+ | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. |
+ | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. |
+ | filters | Filter.Config | | | Configuration for filter. |
+ | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. |
+
+ - Object.Vector
+
+ | field | type | label | required | description |
+ | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
+ | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. |
+
+### Output
+
+- the scheme of `payload.v1.Object.Locations`.
+
+ ```rpc
+ message Object {
+ message Locations { repeated Location locations = 1; }
+
+ message Location {
+ string name = 1;
+ string uuid = 2;
+ repeated string ips = 3;
+ }
+ }
+ ```
+
+ - Object.Locations
+
+ | field | type | label | description |
+ | :------: | :-------------- | :------------------------------- | :----------------------------- |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
+
+ - Object.Location
+
+ | field | type | label | description |
+ | :---: | :----- | :---------------------- | :----------------------------------------------------------------------------- |
+ | name | string | | The name of vald agent pod where the request vector is updated/inserted. |
+ | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. |
+ | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. |
+
+### Status Code
+
+| code | name |
+| :--: | :---------------- |
+| 0 | OK |
+| 1 | CANCELLED |
+| 3 | INVALID_ARGUMENT |
+| 4 | DEADLINE_EXCEEDED |
+| 6 | ALREADY_EXISTS |
+| 10 | ABORTED |
+| 13 | INTERNAL |
+
+Please refer to [Response Status Code](../status.md) for more details.
+
+### Troubleshooting
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons and how to resolve each error.
+
+| name | common reason | how to resolve |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
+| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. |
+| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. |
+| ALREADY_EXISTS | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. |
+| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |