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.
-gRPC has the message size limitation.
-Please be careful that the size of the request exceed the limit. +gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
### Input @@ -664,30 +744,30 @@ Please be careful that the size of the request exceed the limit. - Search.MultiIDRequest - | field | type | label | required | desc. | - | :------: | :-------- | :------------------------- | :------: | :-------------------------- | - | requests | IDRequest | repeated(Array[IDRequest]) | \* | the searchByID request list | + | field | type | label | required | description | + | :------: | :-------- | :------------------------- | :------: | :--------------------------- | + | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. | - 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 @@ -715,27 +795,27 @@ Please be careful that the size of the request exceed 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 | @@ -744,9 +824,25 @@ Please be careful that the size of the request exceed 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + ## LinearSearch RPC -LinearSearch RPC is the method to linear search vector(s) similar to request vector. +LinearSearch RPC is the method to linear search vector(s) similar to the request vector. ### Input @@ -781,22 +877,22 @@ LinearSearch RPC is the method to linear search vector(s) similar to request vec - 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 | - | 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. | + | 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 @@ -820,21 +916,21 @@ LinearSearch RPC is the method to linear search vector(s) similar to request vec - 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 | @@ -843,11 +939,27 @@ LinearSearch RPC is the method to linear search vector(s) similar to request vec | 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. | + ## LinearSearchByID RPC -LinearSearchByID RPC is the method to linear search similar vectors using by user defined vector ID.
+LinearSearchByID RPC is the method to linear search similar vectors using a user-defined vector ID.
The vector with the same requested ID should be indexed into the `vald-agent` before searching. -If the vector doesn't be stored, you will get a `NOT_FOUND` error as a result. +You will get a `NOT_FOUND` error if the vector isn't stored. ### Input @@ -882,22 +994,22 @@ If the vector doesn't be stored, you will get a `NOT_FOUND` error as a result. - 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 | - | 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. | + | 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 @@ -921,21 +1033,21 @@ If the vector doesn't be stored, you will get a `NOT_FOUND` error as a result. - 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 | @@ -944,10 +1056,26 @@ If the vector doesn't be stored, you will get a `NOT_FOUND` error as a result. | 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. | + ## StreamLinearSearch RPC StreamLinearSearch RPC is the method to linear search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
-By using the bidirectional streaming RPC, the linear search request can be communicated in any order between client and server. +Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. Each LinearSearch request and response are independent. ### Input @@ -983,22 +1111,22 @@ Each LinearSearch 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 | - | 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. | + | 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 @@ -1029,28 +1157,28 @@ Each LinearSearch 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 | @@ -1059,10 +1187,26 @@ Each LinearSearch 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. | + ## StreamLinearSearchByID RPC StreamLinearSearchByID RPC is the method to linear search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
-By using the bidirectional streaming RPC, the linear search request can be communicated in any order between client and server. +Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. Each LinearSearchByID request and response are independent. ### Input @@ -1098,22 +1242,22 @@ Each LinearSearchByID 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 | - | 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. | + | 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 @@ -1144,28 +1288,28 @@ Each LinearSearchByID 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 | @@ -1174,13 +1318,29 @@ Each LinearSearchByID 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. | + ## MultiLinearSearch RPC MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in **1** request.
-gRPC has the message size limitation.
-Please be careful that the size of the request exceed the limit. +gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
### Input @@ -1220,28 +1380,28 @@ Please be careful that the size of the request exceed the limit. - Search.MultiRequest - | field | type | label | required | desc. | + | field | type | label | required | description | | :------: | :----------------------- | :---- | :------: | :---------------------- | - | requests | repeated(Array[Request]) | | \* | the search request list | + | 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 | - | 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. | + | 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 @@ -1269,27 +1429,27 @@ Please be careful that the size of the request exceed the limit. - Search.Responses - | field | type | label | desc. | + | field | type | label | description | | :-------: | :------- | :------------------------ | :---------------------------------- | - | responses | Response | repeated(Array[Response]) | the list of search results response | + | 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 | @@ -1298,13 +1458,29 @@ Please be careful that the size of the request exceed 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. | + ### MultiLinearSearchByID RPC MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request.
-gRPC has the message size limitation.
-Please be careful that the size of the request exceed the limit. +gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
### Input @@ -1345,28 +1521,28 @@ Please be careful that the size of the request exceed the limit. - Search.MultiIDRequest - | field | type | label | required | desc. | - | :------: | :-------- | :------------------------- | :------: | :-------------------------- | - | requests | IDRequest | repeated(Array[IDRequest]) | \* | the searchByID request list | + | field | type | label | required | description | + | :------: | :-------- | :------------------------- | :------: | :--------------------------- | + | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. | - 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 | - | 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. | + | 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 @@ -1394,27 +1570,27 @@ Please be careful that the size of the request exceed 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 | @@ -1422,3 +1598,19 @@ Please be careful that the size of the request exceed 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 | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/docs/api/update.md b/docs/api/update.md index 1c3d2c06e5..cdfe2c6ad6 100644 --- a/docs/api/update.md +++ b/docs/api/update.md @@ -2,7 +2,7 @@ ## Overview -Update Service is responsible for updating vectors which are already inserted in the `vald-agent` components. +Update Service updates to new vector from inserted vector in the `vald-agent` components. ```rpc service Update { @@ -46,26 +46,26 @@ Update RPC is the method to update a single vector. - Update.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the update request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Update.Config - | field | type | label | required | 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 updated.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | 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 @@ -83,15 +83,15 @@ Update RPC is the method to update 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 updated. | - | uuid | string | | the ID of the updated vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | the IP list of `vald-agent` pods where the request vector is updated. | + | name | string | | The name of vald agent pod where the request vector is updated. | + | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | @@ -101,10 +101,27 @@ Update RPC is the method to update a 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + ## StreamUpdate RPC StreamUpdate RPC is the method to update multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
-By using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. +Using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. Each Update request and response are independent. It's the recommended method to update the large amount of vectors. @@ -135,26 +152,26 @@ It's the recommended method to update the large amount of vectors. - Update.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the update request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Update.Config - | field | type | label | required | 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 updated.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | desc. | - | :----: | :----- | :--------------------- | :------: | :--------------------------------------------------------------- | - | 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. | + | field | type | label | required | description | + | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | + | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | ### Output @@ -179,30 +196,30 @@ It's the recommended method to update the large amount 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. | - | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- | - | name | string | | the name of vald agent pod where the request vector is updated. | - | uuid | string | | the ID of the exists 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. | + | field | type | label | description | + | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | + | name | string | | The name of vald agent pod where the request vector is updated. | + | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) - | field | type | label | 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 | @@ -212,13 +229,30 @@ It's the recommended method to update the large amount 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + ## MultiUpdate RPC MultiUpdate is the method to update multiple vectors in **1** request.
-gRPC has the message size limitation.
-Please be careful that the size of the request exceed the limit. +gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit.
### Input @@ -251,32 +285,32 @@ Please be careful that the size of the request exceed the limit. - Update.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. | - Update.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the update request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Update.Config - | field | type | label | required | 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 updated.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | 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 @@ -296,21 +330,21 @@ Please be careful that the size of the request exceed 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 updated. | - | uuid | string | | the ID of the updated vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | the ip list of `vald-agent` pods where the request vector is updated. | + | name | string | | The name of vald agent pod where the request vector is updated. | + | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | @@ -319,3 +353,20 @@ Please be careful that the size of the request exceed the limit. | 5 | NOT_FOUND | | 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/docs/api/upsert.md b/docs/api/upsert.md index b4bdc77373..b7aa1c5362 100644 --- a/docs/api/upsert.md +++ b/docs/api/upsert.md @@ -20,7 +20,7 @@ service Upsert { ## Upsert RPC -Upsert RPC is the method to update a single vector and add a new single vector. +Upsert RPC is the method to update the inserted vector to a new single vector or add a new single vector if not inserted before. ### Input @@ -50,26 +50,26 @@ Upsert RPC is the method to update a single vector and add a new single vector. - Upsert.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the upsert request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Upsert.Config - | field | type | label | required | 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 updated/inserted.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | 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 @@ -87,15 +87,15 @@ Upsert RPC is the method to update a single vector and 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 updated/inserted. | - | uuid | string | | the ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | the IP list of `vald-agent` pods where the request vector is updated/inserted. | + | name | string | | The name of vald agent pod where the request vector is updated/inserted. | + | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | @@ -104,10 +104,26 @@ Upsert RPC is the method to update a single vector and 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + ## StreamUpsert RPC StreamUpsert RPC is the method to update multiple existing vectors or add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
-By using the bidirectional streaming RPC, the upsert request can be communicated in any order between client and server. +Using the bidirectional streaming RPC, the upsert request can be communicated in any order between the client and server. Each Upsert request and response are independent. It’s the recommended method to upsert a large number of vectors. @@ -138,26 +154,26 @@ It’s the recommended method to upsert a large number of vectors. - Upsert.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the upsert request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Upsert.Config - | field | type | label | required | 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 updated/inserted.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | desc. | - | :----: | :----- | :--------------------- | :------: | :--------------------------------------------------------------- | - | 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. | + | field | type | label | required | description | + | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | + | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | ### Output @@ -182,30 +198,30 @@ It’s the recommended method to upsert 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 updated/inserted. | - | uuid | string | | the ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | the IP list of `vald-agent` pods where the request vector is updated/inserted. | + | name | string | | The name of vald agent pod where the request vector is updated/inserted. | + | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) - | field | type | label | 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 | @@ -214,6 +230,22 @@ It’s the recommended method to upsert 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + ## MultiUpsert RPC MultiUpsert is the method to update existing multiple vectors and add new multiple vectors in **1** request. @@ -253,32 +285,32 @@ Please be careful that the size of the request exceeds the limit. - Upsert.MultiRequest - | field | type | label | required | desc. | - | :------: | :------------- | :------------------------------ | :------: | :--------------- | - | requests | Upsert.Request | repeated(Array[Insert.Request]) | \* | the request list | + | field | type | label | required | description | + | :------: | :------------- | :------------------------------ | :------: | :---------------- | + | requests | Upsert.Request | repeated(Array[Insert.Request]) | \* | The request list. | - Upsert.Request - | field | type | label | required | desc. | - | :----: | :------------ | :---- | :------: | :-------------------------------------- | - | vector | Object.Vector | | \* | the information of vector | - | config | Config | | \* | the configuration of the upsert request | + | field | type | label | required | description | + | :----: | :------------ | :---- | :------: | :--------------------------------------- | + | vector | Object.Vector | | \* | The information of vector. | + | config | Config | | \* | The configuration of the update request. | - Upsert.Config - | field | type | label | required | desc. | - | :---------------------: | :------------ | :---- | :------: | :----------------------------------------------------------------------------------------------------------- | - | skip_strict_exist_check | bool | | | check the same vector is already updated/inserted or not.
the ID should be unique if the value is `true`. | - | timestamp | int64 | | | the timestamp of the vector updated/inserted.
if it is N/A, the current time will be used. | - | filters | Filter.Config | | | configuration for filter | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | required | description | + | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | + | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | + | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | + | filters | Filter.Config | | | Configuration for filter. | + | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | - Object.Vector - | field | type | label | required | 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 @@ -298,21 +330,21 @@ Please be careful that the size of the request exceeds the limit. - Object.Locations - | field | type | label | desc. | - | :------: | :-------------- | :------------------------------- | :---------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | the list of `Object.Location` | + | field | type | label | description | + | :------: | :-------------- | :------------------------------- | :----------------------------- | + | 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 updated/inserted. | - | uuid | string | | the ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | the IP list of `vald-agent` pods where the request vector is updated/inserted. | + | name | string | | The name of vald agent pod where the request vector is updated/inserted. | + | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | + | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | @@ -320,3 +352,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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. |