Skip to content

Commit

Permalink
📝 Add troubleshooting for each rpc v2
Browse files Browse the repository at this point in the history 
Signed-off-by: vankichi <kyukawa315@gmail.com>
  • Loading branch information
@vankichi
vankichi committed Sep 8, 2023
1 parent 2a6f5ea commit 937e9c2
Show file tree
Hide file tree
Showing 6 changed files with 564 additions and 225 deletions.
164 changes: 82 additions & 82 deletions docs/api/insert.md
View file

Large diffs are not rendered by default.

72 changes: 60 additions & 12 deletions docs/api/object.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ 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. |
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. |

### 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 |

For more details, please refer to [Response Status Code](./status.md).

### Troubleshooting

When the response code is NOT `0 (OK)`, the request process may not be completed.

Here are some common reason and how to resolve of each error.

| name | common reason | how to resolve |
| :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| CANCELLED | Executed cancel() of rpc from client/server side or something network problems between client and server | Check the code, especially around timeout and connection management and fix if needed. |
| INVALID_ARGUMENT | Requested vector's ID is empty or some request payload is invalid. | Check request payload and fix request payload |
| DEADLINE_EXCEEDED | RPC timeout setting is too short on client or server side | Check gRPC timeout setting both of client side and server side and fix if needed |
| NOT_FOUND | Requested ID is NOT inserted | Send request with ID which is already inserted |
| INTERNAL | Target Vald cluster or network route has some critical error | Check target Vald cluster at 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,14 +106,14 @@ 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. |
- 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. |
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. |

### Status Code

| code | desc. |
| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
Expand All @@ -132,6 +148,22 @@ GetObject RPC is the method to get the metadata of a vector inserted into the `v
| 5 | NOT_FOUND |
| 13 | INTERNAL |

For more details, please refer to [Response Status Code](./status.md).

### Troubleshooting

When the response code is NOT `0 (OK)`, the request process may not be completed.

Here are some common reason and how to resolve of each error.

| name | common reason | how to resolve |
| :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| CANCELLED | Executed cancel() of rpc from client/server side or something network problems between client and server | Check the code, especially around timeout and connection management and fix if needed. |
| INVALID_ARGUMENT | Requested vector's ID is empty or some request payload is invalid. | Check request payload and fix request payload |
| DEADLINE_EXCEEDED | RPC timeout setting is too short on client or server side | Check gRPC timeout setting both of client side and server side and fix if needed |
| NOT_FOUND | Requested ID is NOT inserted | Send request with ID which is already inserted |
| INTERNAL | Target Vald cluster or network route has some critical error | Check target Vald cluster at 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>
Expand All @@ -155,14 +187,14 @@ 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. |
- 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. |
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. |

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

### Status Code

| code | desc. |
| code | name |
| :--: | :---------------- |
| 0 | OK |
| 1 | CANCELLED |
| 3 | INVALID_ARGUMENT |
| 4 | DEADLINE_EXCEEDED |
| 5 | NOT_FOUND |
| 13 | INTERNAL |

For more details, please refer to [Response Status Code](./status.md).

### Troubleshooting

When the response code is NOT `0 (OK)`, the request process may not be completed.

Here are some common reason and how to resolve of each error.

| name | common reason | how to resolve |
| :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| CANCELLED | Executed cancel() of rpc from client/server side or something network problems between client and server | Check the code, especially around timeout and connection management and fix if needed. |
| INVALID_ARGUMENT | Requested vector's ID is empty or some request payload is invalid. | Check request payload and fix request payload |
| DEADLINE_EXCEEDED | RPC timeout setting is too short on client or server side | Check gRPC timeout setting both of client side and server side and fix if needed |
| NOT_FOUND | Requested ID is NOT inserted | Send request with ID which is already inserted |
| INTERNAL | Target Vald cluster or network route has some critical error | Check target Vald cluster at first and check network route including ingress as second |
Loading

0 comments on commit 937e9c2

Please sign in to comment.