diff --git a/docs/api/insert.md b/docs/api/insert.md
index c16eae32d0..5c101e830f 100644
--- a/docs/api/insert.md
+++ b/docs/api/insert.md
@@ -46,25 +46,25 @@ Inset RPC is the method to add a new single vector.
- Insert.Request
- | field | type | label | required | desc. |
- | :----: | :------------ | :---- | :------: | :-------------------------------------- |
- | vector | Object.Vector | | \* | the information of vector |
- | config | Config | | \* | the configuration of the 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 | desc. |
- | :---------------------: | :------------ | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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 |
+ | 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 | desc. |
+ | 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. |
+ | 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
@@ -82,15 +82,15 @@ Inset RPC is the method to add a new single vector.
- Object.Location
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -99,10 +99,26 @@ Inset RPC is the method to add a new single vector.
| 6 | ALREADY_EXISTS |
| 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).
-By using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server.
+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.
@@ -133,25 +149,25 @@ It's the recommended method to insert a large number of vectors.
- Insert.Request
- | field | type | label | required | desc. |
- | :----: | :------------ | :---- | :------: | :-------------------------------------- |
- | vector | Object.Vector | | \* | the information of vector |
- | config | Config | | \* | the configuration of the 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 | desc. |
- | :---------------------: | :------------ | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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 |
+ | 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 | desc. |
+ | 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. |
+ | 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
@@ -176,30 +192,30 @@ It's the recommended method to insert a large number of vectors.
- Object.StreamLocation
- | field | type | label | desc. |
+ | field | type | label | description |
| :------: | :---------------- | :---- | :----------------------------------------- |
- | location | Object.Location | | the information of `Object.Location` data. |
- | status | google.rpc.Status | | the status of google RPC. |
+ | location | Object.Location | | The information of `Object.Location` data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
- Object.Location
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+ | 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 |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -208,6 +224,22 @@ It's the recommended method to insert a large number of vectors.
| 6 | ALREADY_EXISTS |
| 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.
@@ -247,31 +279,31 @@ Please be careful that the size of the request exceeds the limit.
- Insert.MultiRequest
- | field | type | label | required | desc. |
- | :------: | :------------- | :------------------------------ | :------: | :--------------- |
- | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | the request list |
+ | field | type | label | required | description |
+ | :------: | :------------- | :------------------------------ | :------: | :---------------- |
+ | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | The request list. |
- Insert.Request
- | field | type | label | required | desc. |
- | :----: | :------------ | :---- | :------: | :-------------------------------------- |
- | vector | Object.Vector | | \* | the information of vector |
- | config | Config | | \* | the configuration of the 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 | desc. |
- | :---------------------: | :------------ | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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 |
+ | 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 | desc. |
+ | 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. |
+ | 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
@@ -291,21 +323,21 @@ Please be careful that the size of the request exceeds the limit.
- Object.Locations
- | field | type | label | desc. |
+ | field | type | label | description |
| :------: | :-------------- | :------------------------------- | :----------------------------- |
- | location | Object.Location | repeated(Array[Object.Location]) | the list of `Object.Location`. |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
- Object.Location
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -313,3 +345,19 @@ Please be careful that the size of the request exceeds the limit.
| 4 | DEADLINE_EXCEEDED |
| 6 | ALREADY_EXISTS |
| 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/docs/api/object.md b/docs/api/object.md
index 0175faa5ab..ca4b0e89c2 100644
--- a/docs/api/object.md
+++ b/docs/api/object.md
@@ -2,7 +2,7 @@
## Overview
-Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent` or not.
+Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent`.
```rpc
service Object {
@@ -18,7 +18,7 @@ service Object {
## Exists RPC
-Exists RPC is the method to check the a vector exists in the `vald-agent`.
+Exists RPC is the method to check that a vector exists in the `vald-agent`.
### Input
@@ -34,9 +34,9 @@ Exists RPC is the method to check the a vector exists in the `vald-agent`.
- Object.ID
- | field | type | label | required | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -52,13 +52,13 @@ Exists RPC is the method to check the a vector exists in the `vald-agent`.
- Object.ID
- | field | type | label | desc. |
+ | field | type | label | description |
| :---: | :----- | :---- | :------------------------------------------------------------- |
- | id | string | | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | The ID of a vector. ID should consist of 1 or more characters. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -67,6 +67,22 @@ Exists RPC is the method to check the a vector exists in the `vald-agent`.
| 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`.
@@ -90,16 +106,16 @@ GetObject RPC is the method to get the metadata of a vector inserted into the `v
- Object.VectorRequest
- | field | type | label | required | desc. |
+ | 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. |
+ | 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 | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -116,14 +132,14 @@ GetObject RPC is the method to get the metadata of a vector inserted into the `v
- Object.Vector
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -132,10 +148,26 @@ GetObject RPC is the method to get the metadata of a vector inserted into the `v
| 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).
-By using the bidirectional streaming RPC, the GetObject request can be communicated in any order between client and server.
+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`
@@ -155,16 +187,16 @@ Each Upsert request and response are independent.
- Object.VectorRequest
- | field | type | label | required | desc. |
+ | 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. |
+ | 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 | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -187,21 +219,21 @@ Each Upsert request and response are independent.
- Object.StreamVector
- | field | type | label | desc. |
+ | field | type | label | description |
| :----: | :---------------- | :---- | :------------------------------------- |
- | vector | Vector | | the information of Object.Vector data. |
- | status | google.rpc.Status | | the status of google RPC. |
+ | vector | Vector | | The information of Object.Vector data. |
+ | status | google.rpc.Status | | The status of Google RPC. |
- Object.Vector
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -209,3 +241,19 @@ Each Upsert request and response are independent.
| 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/docs/api/remove.md b/docs/api/remove.md
index 3e53ac3759..0fe159d293 100644
--- a/docs/api/remove.md
+++ b/docs/api/remove.md
@@ -2,7 +2,7 @@
## Overview
-Remove Service is responsible for removing vectors that are indexed in the `vald-agent`.
+Remove Service is responsible for removing vectors indexed in the `vald-agent`.
```rpc
service Remove {
@@ -47,23 +47,23 @@ Remove RPC is the method to remove a single vector.
- Remove.Request
- | field | type | label | required | desc. |
- | :----: | :-------- | :---- | :------: | :-------------------------------------- |
- | id | Object.ID | | \* | the id of vector |
- | config | Config | | \* | the configuration of the 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 | desc. |
- | :---------------------: | :---- | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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. |
+ | 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 | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -81,15 +81,15 @@ Remove RPC is the method to remove a single vector.
- Object.Location
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -98,10 +98,26 @@ Remove RPC is the method to remove a single vector.
| 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. |
+
## 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).
-By using the bidirectional streaming RPC, the remove request can be communicated in any order between client and server.
+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.
@@ -131,23 +147,23 @@ It's the recommended method to remove a large number of vectors.
- Remove.Request
- | field | type | label | required | desc. |
- | :----: | :-------- | :---- | :------: | :-------------------------------------- |
- | id | Object.ID | | \* | the id of vector |
- | config | Config | | \* | the configuration of the insert 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 | desc. |
- | :---------------------: | :---- | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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. |
+ | 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 | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -172,30 +188,30 @@ It's the recommended method to remove a large number of vectors.
- Object.StreamLocation
- | field | type | label | desc. |
+ | field | type | label | description |
| :------: | :---------------- | :---- | :----------------------------------------- |
- | location | Object.Location | | the information of `Object.Location` data. |
- | status | google.rpc.Status | | the status of google RPC |
+ | location | Object.Location | | The information of `Object.Location` data. |
+ | status | google.rpc.Status | | The status of Google RPC |
- Object.Location
- | field | type | label | desc. |
+ | 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. |
+ | 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 | desc. |
+ | 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 |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -204,6 +220,22 @@ It's the recommended method to remove a large number of vectors.
| 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. |
+
## MultiRemove RPC
MultiRemove is the method to remove multiple vectors in **1** request.
@@ -243,29 +275,29 @@ Please be careful that the size of the request exceeds the limit.
- Remove.MultiRequest
- | field | type | label | required | desc. |
+ | field | type | label | required | description |
| :------: | :------------- | :------------------------------ | :------: | :--------------- |
| requests | Remove.Request | repeated(Array[Insert.Request]) | \* | the request list |
- Remove.Request
- | field | type | label | required | desc. |
- | :----: | :-------- | :---- | :------: | :-------------------------------------- |
- | id | Object.ID | | \* | the id of vector |
- | config | Config | | \* | the configuration of the 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 | desc. |
- | :---------------------: | :---- | :---- | :------: | :--------------------------------------------------------------------------------------------------- |
- | skip_strict_exist_check | bool | | | check 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. |
+ | 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 | desc. |
+ | field | type | label | required | description |
| :---: | :----- | :---- | :------: | :------------------------------------------------------------- |
- | id | string | | \* | the ID of a vector. ID should consist of 1 or more characters. |
+ | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. |
### Output
@@ -285,21 +317,21 @@ Please be careful that the size of the request exceeds the limit.
- Object.Locations
- | field | type | label | desc. |
+ | field | type | label | description |
| :------: | :-------------- | :------------------------------- | :----------------------------- |
- | location | Object.Location | repeated(Array[Object.Location]) | the list of `Object.Location`. |
+ | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. |
- Object.Location
- | field | type | label | desc. |
+ | 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.Vector`. |
- | ips | string | repeated(Array[string]) | the IP list of `vald-agent` pods where the request vector is removed. |
+ | 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 | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -307,3 +339,19 @@ Please be careful that the size of the request exceeds the limit.
| 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/docs/api/search.md b/docs/api/search.md
index c9455b6362..1576006978 100644
--- a/docs/api/search.md
+++ b/docs/api/search.md
@@ -2,7 +2,7 @@
## Overview
-Search Service is responsible for searching vectors from `vald-agent` which are similar to user request vector.
+Search Service is responsible for searching vectors similar to the user request vector from `vald-agent`.
```rpc
service Search {
@@ -44,7 +44,7 @@ service Search {
## Search RPC
-Search RPC is the method to search vector(s) similar to request vector.
+Search RPC is the method to search vector(s) similar to the request vector.
### Input
@@ -81,24 +81,24 @@ Search RPC is the method to search vector(s) similar to request vector.
- Search.Request
- | field | type | label | required | desc. |
+ | 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 |
+ | 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 | desc. |
- | :-------------------: | :------------------- | :---- | :------: | :--------------------------------------------------------------------------- |
- | request_id | string | | | unique request ID |
- | num | uint32 | | \* | the maximum number of result 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 result to be returned |
- | aggregation_algorithm | AggregationAlgorithm | | | the search aggregation algorithm option (default value is `ConcurrentQueue`) |
+ | 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
@@ -122,21 +122,21 @@ Search RPC is the method to search vector(s) similar to request vector.
- Search.Response
- | field | type | label | desc. |
- | :--------: | :-------------- | :------------------------------- | :-------------------- |
- | request_id | string | | the unique request ID |
- | results | Object.Distance | repeated(Array[Object.Distance]) | search results |
+ | 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 | desc. |
- | :------: | :----- | :---- | :---------------------------------------------------- |
- | id | string | | the vector ID |
- | distance | float | | the distance between result vector and request vector |
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -145,6 +145,22 @@ Search RPC is the method to search vector(s) similar to request vector.
| 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 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.
@@ -185,24 +201,24 @@ The vector with the same requested ID should be indexed into the `vald-agent` be
- Search.IDRequest
- | field | type | label | required | desc. |
- | :----: | :----- | :---- | :------: | :-------------------------------------- |
- | id | string | | \* | the vector ID to be searched |
- | config | Config | | \* | the configuration of the search request |
+ | 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 | desc. |
- | :-------------------: | :------------------- | :---- | :------: | :--------------------------------------------------------------------------- |
- | request_id | string | | | unique request ID |
- | num | uint32 | | \* | the maximum number of result 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 result to be returned |
- | aggregation_algorithm | AggregationAlgorithm | | | the search aggregation algorithm option (default value is `ConcurrentQueue`) |
+ | 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
@@ -226,21 +242,21 @@ The vector with the same requested ID should be indexed into the `vald-agent` be
- Search.Response
- | field | type | label | desc. |
- | :--------: | :-------------- | :------------------------------- | :-------------------- |
- | request_id | string | | the unique request ID |
- | results | Object.Distance | repeated(Array[Object.Distance]) | search results |
+ | 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 | desc. |
- | :------: | :----- | :---- | :---------------------------------------------------- |
- | id | string | | the vector ID |
- | distance | float | | the distance between result vector and request vector |
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -249,10 +265,26 @@ The vector with the same requested ID should be indexed into the `vald-agent` be
| 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 | 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).
-By using the bidirectional streaming RPC, the search request can be communicated in any order between client and server.
+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
@@ -290,24 +322,24 @@ Each Search request and response are independent.
- Search.Request
- | field | type | label | required | desc. |
+ | 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 |
+ | 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 | desc. |
- | :-------------------: | :------------------- | :---- | :------: | :--------------------------------------------------------------------------- |
- | request_id | string | | | unique request ID |
- | num | uint32 | | \* | the maximum number of result 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 result to be returned |
- | aggregation_algorithm | AggregationAlgorithm | | | the search aggregation algorithm option (default value is `ConcurrentQueue`) |
+ | 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
@@ -338,28 +370,28 @@ Each Search request and response are independent.
- Search.StreamResponse
- | field | type | label | desc. |
- | :------: | :---------------- | :---- | :------------------------- |
- | response | Response | | the search result response |
- | status | google.rpc.Status | | the status of google RPC |
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
- Search.Response
- | field | type | label | desc. |
- | :--------: | :-------------- | :------------------------------- | :-------------------- |
- | request_id | string | | the unique request ID |
- | results | Object.Distance | repeated(Array[Object.Distance]) | search results |
+ | 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 | desc. |
- | :------: | :----- | :---- | :---------------------------------------------------- |
- | id | string | | the vector ID |
- | distance | float | | the distance between result vector and request vector |
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -368,10 +400,26 @@ Each Search request and response are independent.
| 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 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).
-By using the bidirectional streaming RPC, the search request can be communicated in any order between client and server.
+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
@@ -409,24 +457,24 @@ Each SearchByID request and response are independent.
- Search.IDRequest
- | field | type | label | required | desc. |
- | :----: | :----- | :---- | :------: | :-------------------------------------- |
- | id | string | | \* | the vector ID to be searched |
- | config | Config | | \* | the configuration of the search request |
+ | 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 | desc. |
- | :-------------------: | :------------------- | :---- | :------: | :--------------------------------------------------------------------------- |
- | request_id | string | | | unique request ID |
- | num | uint32 | | \* | the maximum number of result 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 result to be returned |
- | aggregation_algorithm | AggregationAlgorithm | | | the search aggregation algorithm option (default value is `ConcurrentQueue`) |
+ | 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
@@ -457,28 +505,28 @@ Each SearchByID request and response are independent.
- Search.StreamResponse
- | field | type | label | desc. |
- | :------: | :---------------- | :---- | :------------------------- |
- | response | Response | | the search result response |
- | status | google.rpc.Status | | the status of google RPC |
+ | field | type | label | description |
+ | :------: | :---------------- | :---- | :-------------------------- |
+ | response | Response | | The search result response. |
+ | status | google.rpc.Status | | The status of Google RPC. |
- Search.Response
- | field | type | label | desc. |
- | :--------: | :-------------- | :------------------------------- | :-------------------- |
- | request_id | string | | the unique request ID |
- | results | Object.Distance | repeated(Array[Object.Distance]) | search results |
+ | 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 | desc. |
- | :------: | :----- | :---- | :---------------------------------------------------- |
- | id | string | | the vector ID |
- | distance | float | | the distance between result vector and request vector |
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -487,6 +535,22 @@ Each SearchByID request and response are independent.
| 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 | 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.
@@ -535,30 +599,30 @@ Please be careful that the size of the request exceeds the limit.
- Search.MultiRequest
- | field | type | label | required | desc. |
- | :------: | :----------------------- | :---- | :------: | :---------------------- |
- | requests | repeated(Array[Request]) | | \* | the search request list |
+ | field | type | label | required | description |
+ | :------: | :----------------------- | :---- | :------: | :----------------------- |
+ | requests | repeated(Array[Request]) | | \* | The search request list. |
- Search.Request
- | field | type | label | required | desc. |
+ | 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 |
+ | 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 | desc. |
- | :-------------------: | :------------------- | :---- | :------: | :--------------------------------------------------------------------------- |
- | request_id | string | | | unique request ID |
- | num | uint32 | | \* | the maximum number of result 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 result to be returned |
- | aggregation_algorithm | AggregationAlgorithm | | | the search aggregation algorithm option (default value is `ConcurrentQueue`) |
+ | 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
@@ -586,27 +650,27 @@ Please be careful that the size of the request exceeds the limit.
- Search.Responses
- | field | type | label | desc. |
- | :-------: | :------- | :------------------------ | :---------------------------------- |
- | responses | Response | repeated(Array[Response]) | the list of search results response |
+ | field | type | label | description |
+ | :-------: | :------- | :------------------------ | :----------------------------------- |
+ | responses | Response | repeated(Array[Response]) | The list of search results response. |
- Search.Response
- | field | type | label | desc. |
- | :--------: | :-------------- | :------------------------------- | :-------------------- |
- | request_id | string | | the unique request ID |
- | results | Object.Distance | repeated(Array[Object.Distance]) | search results |
+ | 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 | desc. |
- | :------: | :----- | :---- | :---------------------------------------------------- |
- | id | string | | the vector ID |
- | distance | float | | the distance between result vector and request vector |
+ | field | type | label | description |
+ | :------: | :----- | :---- | :------------------------------------------------------------- |
+ | id | string | | The vector ID. |
+ | distance | float | | The distance between the result vector and the request vector. |
### Status Code
-| code | desc. |
+| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
@@ -615,13 +679,29 @@ Please be careful that the size of the request exceeds the limit.
| 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 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.