Skip to content

Commit

Permalink
Add troubleshooting for each rpc (#2163)
Browse files Browse the repository at this point in the history 
* 📝 Add troubleshooting for each rpc

Signed-off-by: vankichi <[email protected]>

* Apply suggestions from code review

Co-authored-by: Yusuke Kato <[email protected]>

* style: Format code with prettier and gofumpt

* 📝 Add troubleshooting for each rpc v2

Signed-off-by: vankichi <[email protected]>

---------

Signed-off-by: vankichi <[email protected]>
Co-authored-by: Yusuke Kato <[email protected]>
Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com>
Co-authored-by: Hiroto Funakoshi <[email protected]>
  • Loading branch information
@vankichi @kpango
@deepsource-autofix @hlts2
4 people authored Sep 13, 2023
1 parent 17b305c commit b017c4b
Show file tree
Hide file tree
Showing 6 changed files with 1,050 additions and 615 deletions.
176 changes: 112 additions & 64 deletions docs/api/insert.md
View file

Large diffs are not rendered by default.

106 changes: 77 additions & 29 deletions docs/api/object.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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 |
Expand All @@ -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`.
Expand All @@ -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
Expand All @@ -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 |
Expand All @@ -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).<br>
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`
Expand All @@ -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
Expand All @@ -187,25 +219,41 @@ 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 |
| 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. |
Loading

0 comments on commit b017c4b

Please sign in to comment.