From 74dc4d6127627f5ad6f16065acdcb311b7a5623d Mon Sep 17 00:00:00 2001 From: Kosuke Morimoto Date: Mon, 25 Nov 2024 13:22:32 +0900 Subject: [PATCH] update --- apis/docs/v1/doc.tmpl | 47 +- apis/docs/v1/filter.md | 1120 +++++++++++++------------- apis/docs/v1/flush.md | 35 +- apis/docs/v1/index.md | 361 ++++----- apis/docs/v1/insert.md | 301 ++++--- apis/docs/v1/object.md | 206 ++--- apis/docs/v1/payload.md.tmpl | 109 +-- apis/docs/v1/payload.tmpl | 17 +- apis/docs/v1/remove.md | 224 +++--- apis/docs/v1/search.md | 1326 +++++++++++++++++-------------- apis/docs/v1/update.md | 268 +++---- apis/docs/v1/upsert.md | 237 +++--- apis/proto/v1/vald/flush.proto | 4 +- apis/proto/v1/vald/insert.proto | 91 ++- 14 files changed, 2193 insertions(+), 2153 deletions(-) diff --git a/apis/docs/v1/doc.tmpl b/apis/docs/v1/doc.tmpl index eee7c0504d..9e21107649 100644 --- a/apis/docs/v1/doc.tmpl +++ b/apis/docs/v1/doc.tmpl @@ -1,11 +1,18 @@ -{{ range .Files -}} -{{ range .Services -}} +{{- range .Files -}} +{{- range .Services -}} +{{- $descs := dict -}} +{{- range $desc := (splitList "---\n" .Description) -}} +{{- $lines := splitList "\n" $desc -}} +{{- $_ := set $descs (first $lines) (join "\n" (rest $lines)) -}} +{{- end -}} # Vald {{ .Name }} APIs ## Overview +{{- if hasKey $descs "Overview" }} -{{.Description}} +{{ pluck "Overview" $descs | first }} +{{ end -}} ```rpc service {{.Name}} { @@ -13,12 +20,19 @@ service {{.Name}} { {{ end }} } ``` +{{ range .Methods }} -{{ range .Methods -}} +{{- $descs := dict -}} +{{- range $desc := (splitList "---\n" .Description) -}} +{{- $lines := splitList "\n" $desc -}} +{{- $_ := set $descs (first $lines) (join "\n" (rest $lines)) -}} +{{- end -}} ## {{ .Name }} RPC +{{ if hasKey $descs "Overview" }} -{{ .Description }} +{{ pluck "Overview" $descs | first }} +{{ end }} ### Input - the scheme of `{{ .RequestFullType }}` @@ -37,16 +51,23 @@ service {{.Name}} { ``` {{ printf "{{ template \"field.%s\" }}" .ResponseFullType }} +{{ if hasKey $descs "Status Code" }} + ### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +{{ pluck "Status Code" $descs | first }} + +Please refer to [Response Status Code](../status.md) for more details. + +{{ end }} + +{{- if hasKey $descs "Troubleshooting" }} + +### Troubleshooting + +{{ pluck "Troubleshooting" $descs | first }} + +{{ end }} {{ end -}} {{- end -}} diff --git a/apis/docs/v1/filter.md b/apis/docs/v1/filter.md index 851ce77f27..69248ef65d 100644 --- a/apis/docs/v1/filter.md +++ b/apis/docs/v1/filter.md @@ -1,10 +1,6 @@ # Vald Filter APIs -## Overview - -Filter service provides ways to connect to Vald through filter. - -```rpc +## Overview```rpc service Filter { rpc SearchObject(payload.v1.Search.ObjectRequest) returns (payload.v1.Search.Response) {} @@ -22,11 +18,8 @@ service Filter { } ``` - ## SearchObject RPC -A method to search object. - ### Input - the scheme of `payload.v1.Search.ObjectRequest` @@ -78,6 +71,16 @@ A method to search object. + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + + message Filter.Target { string host = 1; uint32 port = 2; @@ -86,60 +89,68 @@ A method to search object. - Search.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | bytes | | The binary object to be searched. | - | config | Search.Config | | The configuration of the search request. | - | vectorizer | Filter.Target | | Filter configuration. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -160,33 +171,23 @@ A method to search object. - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiSearchObject RPC -A method to search multiple objects. - ### Input - the scheme of `payload.v1.Search.MultiObjectRequest` @@ -243,6 +244,16 @@ A method to search multiple objects. + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + + message Filter.Target { string host = 1; uint32 port = 2; @@ -251,66 +262,75 @@ A method to search multiple objects. - Search.MultiObjectRequest - | field | type | label | desc. | - | :------: | :------------------- | :------- | :-------------------------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | + - Search.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | bytes | | The binary object to be searched. | - | config | Search.Config | | The configuration of the search request. | - | vectorizer | Filter.Target | | Filter configuration. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -336,39 +356,30 @@ A method to search multiple objects. - Search.Responses - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | responses | Search.Response | repeated | Represent the multiple search response content. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamSearchObject RPC -A method to search object by bidirectional streaming. - ### Input - the scheme of `payload.v1.Search.ObjectRequest` @@ -420,6 +431,16 @@ A method to search object by bidirectional streaming. + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + + message Filter.Target { string host = 1; uint32 port = 2; @@ -428,60 +449,68 @@ A method to search object by bidirectional streaming. - Search.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | bytes | | The binary object to be searched. | - | config | Search.Config | | The configuration of the search request. | - | vectorizer | Filter.Target | | Filter configuration. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -508,40 +537,31 @@ A method to search object by bidirectional streaming. - Search.StreamResponse - | field | type | label | desc. | - | :------: | :---------------- | :---- | :----------------------------- | - | response | Search.Response | | Represent the search response. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## InsertObject RPC -A method insert object. - ### Input - the scheme of `payload.v1.Insert.ObjectRequest` @@ -588,46 +608,51 @@ A method insert object. - Insert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | - | vectorizer | Filter.Target | | Filter configurations. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -643,27 +668,16 @@ A method insert object. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamInsertObject RPC -Represent the streaming RPC to insert object by bidirectional streaming. - ### Input - the scheme of `payload.v1.Insert.ObjectRequest` @@ -710,46 +724,51 @@ Represent the streaming RPC to insert object by bidirectional streaming. - Insert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | - | vectorizer | Filter.Target | | Filter configurations. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -771,34 +790,24 @@ Represent the streaming RPC to insert object by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiInsertObject RPC -A method to insert multiple objects. - ### Input - the scheme of `payload.v1.Insert.MultiObjectRequest` @@ -850,52 +859,58 @@ A method to insert multiple objects. - Insert.MultiObjectRequest - | field | type | label | desc. | - | :------: | :------------------- | :------- | :------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | + - Insert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | - | vectorizer | Filter.Target | | Filter configurations. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -916,33 +931,23 @@ A method to insert multiple objects. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## UpdateObject RPC -A method to update object. - ### Input - the scheme of `payload.v1.Update.ObjectRequest` @@ -990,49 +995,53 @@ A method to update object. - Update.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be updated. | - | config | Update.Config | | The configuration of the update request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1048,27 +1057,16 @@ A method to update object. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamUpdateObject RPC -A method to update object by bidirectional streaming. - ### Input - the scheme of `payload.v1.Update.ObjectRequest` @@ -1116,49 +1114,53 @@ A method to update object by bidirectional streaming. - Update.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be updated. | - | config | Update.Config | | The configuration of the update request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1180,34 +1182,24 @@ A method to update object by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiUpdateObject RPC -A method to update multiple objects. - ### Input - the scheme of `payload.v1.Update.MultiObjectRequest` @@ -1260,55 +1252,60 @@ A method to update multiple objects. - Update.MultiObjectRequest - | field | type | label | desc. | - | :------: | :------------------- | :------- | :---------------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | + - Update.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be updated. | - | config | Update.Config | | The configuration of the update request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1329,33 +1326,23 @@ A method to update multiple objects. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## UpsertObject RPC -A method to upsert object. - ### Input - the scheme of `payload.v1.Upsert.ObjectRequest` @@ -1403,49 +1390,53 @@ A method to upsert object. - Upsert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1461,27 +1452,16 @@ A method to upsert object. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamUpsertObject RPC -A method to upsert object by bidirectional streaming. - ### Input - the scheme of `payload.v1.Upsert.ObjectRequest` @@ -1529,49 +1509,53 @@ A method to upsert object by bidirectional streaming. - Upsert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1593,34 +1577,24 @@ A method to upsert object by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiUpsertObject RPC -A method to upsert multiple objects. - ### Input - the scheme of `payload.v1.Upsert.MultiObjectRequest` @@ -1673,55 +1647,60 @@ A method to upsert multiple objects. - Upsert.MultiObjectRequest - | field | type | label | desc. | - | :------: | :------------------- | :------- | :---------------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | + - Upsert.ObjectRequest - | field | type | label | desc. | - | :--------: | :------------ | :---- | :--------------------------------------- | - | object | Object.Blob | | The binary object to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | - | vectorizer | Filter.Target | | Filter target. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + - Object.Blob - | field | type | label | desc. | - | :----: | :----- | :---- | :----------------- | - | id | string | | The object ID. | - | object | bytes | | The binary object. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -1742,25 +1721,18 @@ A method to upsert multiple objects. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + + diff --git a/apis/docs/v1/flush.md b/apis/docs/v1/flush.md index 862f2ecdf9..fbf297e531 100644 --- a/apis/docs/v1/flush.md +++ b/apis/docs/v1/flush.md @@ -1,21 +1,14 @@ # Vald Flush APIs -## Overview - -Flush service provides ways to flush all indexed vectors. - -```rpc +## Overview```rpc service Flush { rpc Flush(payload.v1.Flush.Request) returns (payload.v1.Info.Index.Count) {} } ``` - ## Flush RPC -A method to flush all indexed vector. - ### Input - the scheme of `payload.v1.Flush.Request` @@ -45,20 +38,12 @@ A method to flush all indexed vector. - Info.Index.Count - | field | type | label | desc. | - | :---------: | :----- | :---- | :--------------------------- | - | stored | uint32 | | The stored index count. | - | uncommitted | uint32 | | The uncommitted index count. | - | indexing | bool | | The indexing index count. | - | saving | bool | | The saving index count. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | + + + diff --git a/apis/docs/v1/index.md b/apis/docs/v1/index.md index 4b5ffad85e..b27cb74e41 100644 --- a/apis/docs/v1/index.md +++ b/apis/docs/v1/index.md @@ -1,10 +1,6 @@ # Vald Index APIs -## Overview - -Represent the index manager service. - -```rpc +## Overview```rpc service Index { rpc IndexInfo(payload.v1.Empty) returns (payload.v1.Info.Index.Count) {} @@ -15,11 +11,8 @@ service Index { } ``` - ## IndexInfo RPC -Represent the RPC to get the index information. - ### Input - the scheme of `payload.v1.Empty` @@ -49,28 +42,17 @@ Represent the RPC to get the index information. - Info.Index.Count - | field | type | label | desc. | - | :---------: | :----- | :---- | :--------------------------- | - | stored | uint32 | | The stored index count. | - | uncommitted | uint32 | | The uncommitted index count. | - | indexing | bool | | The indexing index count. | - | saving | bool | | The saving index count. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## IndexDetail RPC -Represent the RPC to get the index information for each agents. - ### Input - the scheme of `payload.v1.Empty` @@ -113,43 +95,34 @@ Represent the RPC to get the index information for each agents. - Info.Index.Detail - | field | type | label | desc. | - | :---------: | :---------------------------- | :------- | :--------------------------------- | - | counts | Info.Index.Detail.CountsEntry | repeated | count infos for each agents | - | replica | uint32 | | index replica of vald cluster | - | live_agents | uint32 | | live agent replica of vald cluster | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | counts | Info.Index.Detail.CountsEntry | repeated | count infos for each agents | + | replica | uint32 | | index replica of vald cluster | + | live_agents | uint32 | | live agent replica of vald cluster | + - Info.Index.Detail.CountsEntry - | field | type | label | desc. | - | :---: | :--------------- | :---- | :---- | - | key | string | | | - | value | Info.Index.Count | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Count | | | + - Info.Index.Count - | field | type | label | desc. | - | :---------: | :----- | :---- | :--------------------------- | - | stored | uint32 | | The stored index count. | - | uncommitted | uint32 | | The uncommitted index count. | - | indexing | bool | | The indexing index count. | - | saving | bool | | The saving index count. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## IndexStatistics RPC -Represent the RPC to get the index statistics. - ### Input - the scheme of `payload.v1.Empty` @@ -208,56 +181,45 @@ Represent the RPC to get the index statistics. - Info.Index.Statistics - | field | type | label | desc. | - | :----------------------------------: | :----- | :------- | :---- | - | valid | bool | | | - | median_indegree | int32 | | | - | median_outdegree | int32 | | | - | max_number_of_indegree | uint64 | | | - | max_number_of_outdegree | uint64 | | | - | min_number_of_indegree | uint64 | | | - | min_number_of_outdegree | uint64 | | | - | mode_indegree | uint64 | | | - | mode_outdegree | uint64 | | | - | nodes_skipped_for_10_edges | uint64 | | | - | nodes_skipped_for_indegree_distance | uint64 | | | - | number_of_edges | uint64 | | | - | number_of_indexed_objects | uint64 | | | - | number_of_nodes | uint64 | | | - | number_of_nodes_without_edges | uint64 | | | - | number_of_nodes_without_indegree | uint64 | | | - | number_of_objects | uint64 | | | - | number_of_removed_objects | uint64 | | | - | size_of_object_repository | uint64 | | | - | size_of_refinement_object_repository | uint64 | | | - | variance_of_indegree | double | | | - | variance_of_outdegree | double | | | - | mean_edge_length | double | | | - | mean_edge_length_for_10_edges | double | | | - | mean_indegree_distance_for_10_edges | double | | | - | mean_number_of_edges_per_node | double | | | - | c1_indegree | double | | | - | c5_indegree | double | | | - | c95_outdegree | double | | | - | c99_outdegree | double | | | - | indegree_count | int64 | repeated | | - | outdegree_histogram | uint64 | repeated | | - | indegree_histogram | uint64 | repeated | | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | valid | bool | | | + | median_indegree | int32 | | | + | median_outdegree | int32 | | | + | max_number_of_indegree | uint64 | | | + | max_number_of_outdegree | uint64 | | | + | min_number_of_indegree | uint64 | | | + | min_number_of_outdegree | uint64 | | | + | mode_indegree | uint64 | | | + | mode_outdegree | uint64 | | | + | nodes_skipped_for_10_edges | uint64 | | | + | nodes_skipped_for_indegree_distance | uint64 | | | + | number_of_edges | uint64 | | | + | number_of_indexed_objects | uint64 | | | + | number_of_nodes | uint64 | | | + | number_of_nodes_without_edges | uint64 | | | + | number_of_nodes_without_indegree | uint64 | | | + | number_of_objects | uint64 | | | + | number_of_removed_objects | uint64 | | | + | size_of_object_repository | uint64 | | | + | size_of_refinement_object_repository | uint64 | | | + | variance_of_indegree | double | | | + | variance_of_outdegree | double | | | + | mean_edge_length | double | | | + | mean_edge_length_for_10_edges | double | | | + | mean_indegree_distance_for_10_edges | double | | | + | mean_number_of_edges_per_node | double | | | + | c1_indegree | double | | | + | c5_indegree | double | | | + | c95_outdegree | double | | | + | c99_outdegree | double | | | + | indegree_count | int64 | repeated | | + | outdegree_histogram | uint64 | repeated | | + | indegree_histogram | uint64 | repeated | | -## IndexStatisticsDetail RPC -Represent the RPC to get the index statistics for each agents. + +## IndexStatisticsDetail RPC ### Input @@ -328,69 +290,60 @@ Represent the RPC to get the index statistics for each agents. - Info.Index.StatisticsDetail - | field | type | label | desc. | - | :-----: | :--------------------------------------- | :------- | :-------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | + - Info.Index.StatisticsDetail.DetailsEntry - | field | type | label | desc. | - | :---: | :-------------------- | :---- | :---- | - | key | string | | | - | value | Info.Index.Statistics | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Statistics | | | + - Info.Index.Statistics - | field | type | label | desc. | - | :----------------------------------: | :----- | :------- | :---- | - | valid | bool | | | - | median_indegree | int32 | | | - | median_outdegree | int32 | | | - | max_number_of_indegree | uint64 | | | - | max_number_of_outdegree | uint64 | | | - | min_number_of_indegree | uint64 | | | - | min_number_of_outdegree | uint64 | | | - | mode_indegree | uint64 | | | - | mode_outdegree | uint64 | | | - | nodes_skipped_for_10_edges | uint64 | | | - | nodes_skipped_for_indegree_distance | uint64 | | | - | number_of_edges | uint64 | | | - | number_of_indexed_objects | uint64 | | | - | number_of_nodes | uint64 | | | - | number_of_nodes_without_edges | uint64 | | | - | number_of_nodes_without_indegree | uint64 | | | - | number_of_objects | uint64 | | | - | number_of_removed_objects | uint64 | | | - | size_of_object_repository | uint64 | | | - | size_of_refinement_object_repository | uint64 | | | - | variance_of_indegree | double | | | - | variance_of_outdegree | double | | | - | mean_edge_length | double | | | - | mean_edge_length_for_10_edges | double | | | - | mean_indegree_distance_for_10_edges | double | | | - | mean_number_of_edges_per_node | double | | | - | c1_indegree | double | | | - | c5_indegree | double | | | - | c95_outdegree | double | | | - | c99_outdegree | double | | | - | indegree_count | int64 | repeated | | - | outdegree_histogram | uint64 | repeated | | - | indegree_histogram | uint64 | repeated | | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | valid | bool | | | + | median_indegree | int32 | | | + | median_outdegree | int32 | | | + | max_number_of_indegree | uint64 | | | + | max_number_of_outdegree | uint64 | | | + | min_number_of_indegree | uint64 | | | + | min_number_of_outdegree | uint64 | | | + | mode_indegree | uint64 | | | + | mode_outdegree | uint64 | | | + | nodes_skipped_for_10_edges | uint64 | | | + | nodes_skipped_for_indegree_distance | uint64 | | | + | number_of_edges | uint64 | | | + | number_of_indexed_objects | uint64 | | | + | number_of_nodes | uint64 | | | + | number_of_nodes_without_edges | uint64 | | | + | number_of_nodes_without_indegree | uint64 | | | + | number_of_objects | uint64 | | | + | number_of_removed_objects | uint64 | | | + | size_of_object_repository | uint64 | | | + | size_of_refinement_object_repository | uint64 | | | + | variance_of_indegree | double | | | + | variance_of_outdegree | double | | | + | mean_edge_length | double | | | + | mean_edge_length_for_10_edges | double | | | + | mean_indegree_distance_for_10_edges | double | | | + | mean_number_of_edges_per_node | double | | | + | c1_indegree | double | | | + | c5_indegree | double | | | + | c95_outdegree | double | | | + | c99_outdegree | double | | | + | indegree_count | int64 | repeated | | + | outdegree_histogram | uint64 | repeated | | + | indegree_histogram | uint64 | repeated | | -## IndexProperty RPC -Represent the RPC to get the index property. + +## IndexProperty RPC ### Input @@ -462,63 +415,57 @@ Represent the RPC to get the index property. - Info.Index.PropertyDetail - | field | type | label | desc. | - | :-----: | :------------------------------------- | :------- | :---- | - | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | + - Info.Index.PropertyDetail.DetailsEntry - | field | type | label | desc. | - | :---: | :------------------ | :---- | :---- | - | key | string | | | - | value | Info.Index.Property | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Property | | | + - Info.Index.Property - | field | type | label | desc. | - | :--------------------------------: | :----- | :---- | :---- | - | dimension | int32 | | | - | thread_pool_size | int32 | | | - | object_type | string | | | - | distance_type | string | | | - | index_type | string | | | - | database_type | string | | | - | object_alignment | string | | | - | path_adjustment_interval | int32 | | | - | graph_shared_memory_size | int32 | | | - | tree_shared_memory_size | int32 | | | - | object_shared_memory_size | int32 | | | - | prefetch_offset | int32 | | | - | prefetch_size | int32 | | | - | accuracy_table | string | | | - | search_type | string | | | - | max_magnitude | float | | | - | n_of_neighbors_for_insertion_order | int32 | | | - | epsilon_for_insertion_order | float | | | - | refinement_object_type | string | | | - | truncation_threshold | int32 | | | - | edge_size_for_creation | int32 | | | - | edge_size_for_search | int32 | | | - | edge_size_limit_for_creation | int32 | | | - | insertion_radius_coefficient | double | | | - | seed_size | int32 | | | - | seed_type | string | | | - | truncation_thread_pool_size | int32 | | | - | batch_size_for_creation | int32 | | | - | graph_type | string | | | - | dynamic_edge_size_base | int32 | | | - | dynamic_edge_size_rate | int32 | | | - | build_time_limit | float | | | - | outgoing_edge | int32 | | | - | incoming_edge | int32 | | | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | dimension | int32 | | | + | thread_pool_size | int32 | | | + | object_type | string | | | + | distance_type | string | | | + | index_type | string | | | + | database_type | string | | | + | object_alignment | string | | | + | path_adjustment_interval | int32 | | | + | graph_shared_memory_size | int32 | | | + | tree_shared_memory_size | int32 | | | + | object_shared_memory_size | int32 | | | + | prefetch_offset | int32 | | | + | prefetch_size | int32 | | | + | accuracy_table | string | | | + | search_type | string | | | + | max_magnitude | float | | | + | n_of_neighbors_for_insertion_order | int32 | | | + | epsilon_for_insertion_order | float | | | + | refinement_object_type | string | | | + | truncation_threshold | int32 | | | + | edge_size_for_creation | int32 | | | + | edge_size_for_search | int32 | | | + | edge_size_limit_for_creation | int32 | | | + | insertion_radius_coefficient | double | | | + | seed_size | int32 | | | + | seed_type | string | | | + | truncation_thread_pool_size | int32 | | | + | batch_size_for_creation | int32 | | | + | graph_type | string | | | + | dynamic_edge_size_base | int32 | | | + | dynamic_edge_size_rate | int32 | | | + | build_time_limit | float | | | + | outgoing_edge | int32 | | | + | incoming_edge | int32 | | | + + + diff --git a/apis/docs/v1/insert.md b/apis/docs/v1/insert.md index dbaf1b5acb..46f98f025d 100644 --- a/apis/docs/v1/insert.md +++ b/apis/docs/v1/insert.md @@ -2,7 +2,7 @@ ## Overview -Insert service provides ways to add new vectors. +Insert Service is responsible for inserting new vectors into the `vald-agent`. ```rpc service Insert { @@ -13,10 +13,12 @@ service Insert { } ``` - ## Insert RPC -A method to add a new single vector. + +Inset RPC is the method to add a new single vector. + + ### Input @@ -57,39 +59,43 @@ A method to add a new single vector. - Insert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -105,26 +111,55 @@ A method to add a new single vector. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + ### Status Code | code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + + +Please refer to [Response Status Code](../status.md) for more details. + + + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The 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 -A method to add new multiple vectors by bidirectional streaming. + +StreamInsert RPC is the method to add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server. +Each Insert request and response are independent. +It's the recommended method to insert a large number of vectors. + + ### Input @@ -165,39 +200,43 @@ A method to add new multiple vectors by bidirectional streaming. - Insert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -219,33 +258,66 @@ A method to add new multiple vectors by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | | 3 | INVALID_ARGUMENT | | 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | +| 6 | ALREADY_EXISTS | +| 10 | ABORTED | | 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + + + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| 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 -A method to add new multiple vectors in a single request. + +MultiInsert RPC is the method to add multiple new vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ + ### Input @@ -291,45 +363,50 @@ A method to add new multiple vectors in a single request. - Insert.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Insert.Request | repeated | Represent multiple insert request content. | + - Insert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be inserted. | - | config | Insert.Config | | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Insert.Config - | field | type | label | desc. | - | :---------------------: | :------------ | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | - | filters | Filter.Config | | Filter configurations. | - | timestamp | int64 | | Insert timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -350,25 +427,51 @@ A method to add new multiple vectors in a single request. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + ### Status Code -| code | desc. | +| code | name | | :--: | :---------------- | | 0 | OK | | 1 | CANCELLED | | 3 | INVALID_ARGUMENT | | 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | +| 6 | ALREADY_EXISTS | +| 10 | ABORTED | | 13 | INTERNAL | + + +Please refer to [Response Status Code](../status.md) for more details. + + + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| ALREADY_EXISTS | Request ID is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + + + diff --git a/apis/docs/v1/object.md b/apis/docs/v1/object.md index ddc0685a23..53fb086e50 100644 --- a/apis/docs/v1/object.md +++ b/apis/docs/v1/object.md @@ -1,10 +1,6 @@ # Vald Object APIs -## Overview - -Object service provides ways to fetch indexed vectors. - -```rpc +## Overview```rpc service Object { rpc Exists(payload.v1.Object.ID) returns (payload.v1.Object.ID) {} @@ -15,11 +11,8 @@ service Object { } ``` - ## Exists RPC -A method to check whether a specified ID is indexed or not. - ### Input - the scheme of `payload.v1.Object.ID` @@ -32,9 +25,9 @@ A method to check whether a specified ID is indexed or not. - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | ### Output @@ -48,25 +41,14 @@ A method to check whether a specified ID is indexed or not. - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## GetObject RPC -A method to fetch a vector. - ### Input - the scheme of `payload.v1.Object.VectorRequest` @@ -97,29 +79,32 @@ A method to fetch a vector. - Object.VectorRequest - | field | type | label | desc. | - | :-----: | :------------ | :---- | :--------------------------- | - | id | Object.ID | | The vector ID to be fetched. | - | filters | Filter.Config | | Filter configurations. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -135,27 +120,16 @@ A method to fetch a vector. - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamGetObject RPC -A method to fetch vectors by bidirectional streaming. - ### Input - the scheme of `payload.v1.Object.VectorRequest` @@ -186,29 +160,32 @@ A method to fetch vectors by bidirectional streaming. - Object.VectorRequest - | field | type | label | desc. | - | :-----: | :------------ | :---- | :--------------------------- | - | id | Object.ID | | The vector ID to be fetched. | - | filters | Filter.Config | | Filter configurations. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -230,34 +207,24 @@ A method to fetch vectors by bidirectional streaming. - Object.StreamVector - | field | type | label | desc. | - | :----: | :---------------- | :---- | :-------------------- | - | vector | Object.Vector | | The vector. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamListObject RPC -A method to get all the vectors with server streaming - ### Input - the scheme of `payload.v1.Object.List.Request` @@ -292,34 +259,24 @@ A method to get all the vectors with server streaming - Object.List.Response - | field | type | label | desc. | - | :----: | :---------------- | :---- | :-------------------- | - | vector | Object.Vector | | The vector | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector | + | status | google.rpc.Status | | The RPC error status. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## GetTimestamp RPC -Represent the RPC to get the vector metadata. This RPC is mainly used for index correction process - ### Input - the scheme of `payload.v1.Object.TimestampRequest` @@ -337,15 +294,16 @@ Represent the RPC to get the vector metadata. This RPC is mainly used for index - Object.TimestampRequest - | field | type | label | desc. | - | :---: | :-------- | :---- | :--------------------------- | - | id | Object.ID | | The vector ID to be fetched. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | ### Output @@ -360,18 +318,10 @@ Represent the RPC to get the vector metadata. This RPC is mainly used for index - Object.Timestamp - | field | type | label | desc. | - | :-------: | :----- | :---- | :---------------------------------------------- | - | id | string | | The vector ID. | - | timestamp | int64 | | timestamp represents when this vector inserted. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + + diff --git a/apis/docs/v1/payload.md.tmpl b/apis/docs/v1/payload.md.tmpl index 10852851bf..ff9d846236 100644 --- a/apis/docs/v1/payload.md.tmpl +++ b/apis/docs/v1/payload.md.tmpl @@ -95,7 +95,6 @@ | targets | Filter.Target | repeated | Represent the filter target configuration. | {{ template "field.payload.v1.Filter.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Filter.Target" }} @@ -167,7 +166,6 @@ | annotations | Info.Annotations.AnnotationsEntry | repeated | | {{ template "field.payload.v1.Info.Annotations.AnnotationsEntry" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Annotations.AnnotationsEntry" }} @@ -271,7 +269,6 @@ | live_agents | uint32 | | live agent replica of vald cluster | {{ template "field.payload.v1.Info.Index.Detail.CountsEntry" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.Detail.CountsEntry" }} @@ -293,7 +290,6 @@ | value | Info.Index.Count | | | {{ template "field.payload.v1.Info.Index.Count" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.Property" }} @@ -393,7 +389,6 @@ | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | {{ template "field.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} @@ -415,7 +410,6 @@ | value | Info.Index.Property | | | {{ template "field.payload.v1.Info.Index.Property" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.Statistics" }} @@ -513,7 +507,6 @@ | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | {{ template "field.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} @@ -535,7 +528,6 @@ | value | Info.Index.Statistics | | | {{ template "field.payload.v1.Info.Index.Statistics" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Index.UUID" }} @@ -595,7 +587,6 @@ | labels | Info.Labels.LabelsEntry | repeated | | {{ template "field.payload.v1.Info.Labels.LabelsEntry" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Labels.LabelsEntry" }} @@ -666,12 +657,9 @@ {{ template "field.payload.v1.Info.CPU" }} - {{ template "field.payload.v1.Info.Memory" }} - {{ template "field.payload.v1.Info.Pods" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Nodes" }} @@ -691,7 +679,6 @@ | nodes | Info.Node | repeated | The multiple node information. | {{ template "field.payload.v1.Info.Node" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Pod" }} @@ -730,12 +717,9 @@ {{ template "field.payload.v1.Info.CPU" }} - {{ template "field.payload.v1.Info.Memory" }} - {{ template "field.payload.v1.Info.Node" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Pods" }} @@ -755,7 +739,6 @@ | pods | Info.Pod | repeated | The multiple pod information. | {{ template "field.payload.v1.Info.Pod" }} - {{- end -}} {{- define "scheme.payload.v1.Info.Service" }} @@ -792,12 +775,9 @@ {{ template "field.payload.v1.Info.ServicePort" }} - {{ template "field.payload.v1.Info.Labels" }} - {{ template "field.payload.v1.Info.Annotations" }} - {{- end -}} {{- define "scheme.payload.v1.Info.ServicePort" }} @@ -833,7 +813,6 @@ | services | Info.Service | repeated | The multiple service information. | {{ template "field.payload.v1.Info.Service" }} - {{- end -}} {{- define "scheme.payload.v1.Insert" }} @@ -869,7 +848,6 @@ | timestamp | int64 | | Insert timestamp. | {{ template "field.payload.v1.Filter.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Insert.MultiObjectRequest" }} @@ -889,7 +867,6 @@ | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | {{ template "field.payload.v1.Insert.ObjectRequest" }} - {{- end -}} {{- define "scheme.payload.v1.Insert.MultiRequest" }} @@ -909,7 +886,6 @@ | requests | Insert.Request | repeated | Represent multiple insert request content. | {{ template "field.payload.v1.Insert.Request" }} - {{- end -}} {{- define "scheme.payload.v1.Insert.ObjectRequest" }} @@ -940,12 +916,9 @@ {{ template "field.payload.v1.Object.Blob" }} - {{ template "field.payload.v1.Insert.Config" }} - {{ template "field.payload.v1.Filter.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Insert.Request" }} @@ -971,9 +944,7 @@ {{ template "field.payload.v1.Object.Vector" }} - {{ template "field.payload.v1.Insert.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Meta" }} @@ -1025,9 +996,7 @@ {{ template "field.payload.v1.Meta.Key" }} - {{ template "field.payload.v1.Meta.Value" }} - {{- end -}} {{- define "scheme.payload.v1.Meta.Value" }} @@ -1089,7 +1058,6 @@ | targets | Mirror.Target | repeated | The multiple target information. | {{ template "field.payload.v1.Mirror.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Object" }} @@ -1207,7 +1175,6 @@ | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Object.Vector" }} - {{- end -}} {{- define "scheme.payload.v1.Object.Location" }} @@ -1245,7 +1212,6 @@ | locations | Object.Location | repeated | | {{ template "field.payload.v1.Object.Location" }} - {{- end -}} {{- define "scheme.payload.v1.Object.ReshapeVector" }} @@ -1283,7 +1249,6 @@ | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Object.Blob" }} - {{- end -}} {{- define "scheme.payload.v1.Object.StreamDistance" }} @@ -1305,7 +1270,6 @@ | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Object.Distance" }} - {{- end -}} {{- define "scheme.payload.v1.Object.StreamLocation" }} @@ -1327,7 +1291,6 @@ | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Object.Location" }} - {{- end -}} {{- define "scheme.payload.v1.Object.StreamVector" }} @@ -1349,7 +1312,6 @@ | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Object.Vector" }} - {{- end -}} {{- define "scheme.payload.v1.Object.Timestamp" }} @@ -1385,7 +1347,6 @@ | id | Object.ID | | The vector ID to be fetched. | {{ template "field.payload.v1.Object.ID" }} - {{- end -}} {{- define "scheme.payload.v1.Object.Vector" }} @@ -1429,9 +1390,7 @@ {{ template "field.payload.v1.Object.ID" }} - {{ template "field.payload.v1.Filter.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Object.Vectors" }} @@ -1451,7 +1410,6 @@ | vectors | Object.Vector | repeated | | {{ template "field.payload.v1.Object.Vector" }} - {{- end -}} {{- define "scheme.payload.v1.Remove" }} @@ -1499,7 +1457,6 @@ | requests | Remove.Request | repeated | Represent the multiple remove request content. | {{ template "field.payload.v1.Remove.Request" }} - {{- end -}} {{- define "scheme.payload.v1.Remove.Request" }} @@ -1525,9 +1482,7 @@ {{ template "field.payload.v1.Object.ID" }} - {{ template "field.payload.v1.Remove.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Remove.Timestamp" }} @@ -1535,6 +1490,9 @@ int64 timestamp = 1; Remove.Timestamp.Operator operator = 2; } + +{{ template "scheme.payload.v1.Remove.Timestamp.Operator" }} + {{- end -}} {{- define "field.payload.v1.Remove.Timestamp" }} @@ -1544,6 +1502,8 @@ | :---: | :--- | :---- | :---- | | timestamp | int64 | | The timestamp. | | operator | Remove.Timestamp.Operator | | The conditional operator. | + +{{ template "field.payload.v1.Remove.Timestamp.Operator" }} {{- end -}} {{- define "scheme.payload.v1.Remove.TimestampRequest" }} @@ -1564,7 +1524,6 @@ search is applied. | {{ template "field.payload.v1.Remove.Timestamp" }} - {{- end -}} {{- define "scheme.payload.v1.Search" }} @@ -1599,6 +1558,9 @@ search is applied. | {{ template "scheme.payload.v1.Filter.Config" }} + +{{ template "scheme.payload.v1.Search.AggregationAlgorithm" }} + {{- end -}} {{- define "field.payload.v1.Search.Config" }} @@ -1620,9 +1582,9 @@ search is applied. | {{ template "field.payload.v1.Filter.Config" }} - {{ template "field.payload.v1.Filter.Config" }} +{{ template "field.payload.v1.Search.AggregationAlgorithm" }} {{- end -}} {{- define "scheme.payload.v1.Search.IDRequest" }} @@ -1644,7 +1606,6 @@ search is applied. | | config | Search.Config | | The configuration of the search request. | {{ template "field.payload.v1.Search.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Search.MultiIDRequest" }} @@ -1664,7 +1625,6 @@ search is applied. | | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | {{ template "field.payload.v1.Search.IDRequest" }} - {{- end -}} {{- define "scheme.payload.v1.Search.MultiObjectRequest" }} @@ -1684,7 +1644,6 @@ search is applied. | | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | {{ template "field.payload.v1.Search.ObjectRequest" }} - {{- end -}} {{- define "scheme.payload.v1.Search.MultiRequest" }} @@ -1704,7 +1663,6 @@ search is applied. | | requests | Search.Request | repeated | Represent the multiple search request content. | {{ template "field.payload.v1.Search.Request" }} - {{- end -}} {{- define "scheme.payload.v1.Search.ObjectRequest" }} @@ -1732,9 +1690,7 @@ search is applied. | {{ template "field.payload.v1.Search.Config" }} - {{ template "field.payload.v1.Filter.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Search.Request" }} @@ -1756,7 +1712,6 @@ search is applied. | | config | Search.Config | | The configuration of the search request. | {{ template "field.payload.v1.Search.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Search.Response" }} @@ -1778,7 +1733,6 @@ search is applied. | | results | Object.Distance | repeated | Search results. | {{ template "field.payload.v1.Object.Distance" }} - {{- end -}} {{- define "scheme.payload.v1.Search.Responses" }} @@ -1798,7 +1752,6 @@ search is applied. | | responses | Search.Response | repeated | Represent the multiple search response content. | {{ template "field.payload.v1.Search.Response" }} - {{- end -}} {{- define "scheme.payload.v1.Search.StreamResponse" }} @@ -1820,7 +1773,6 @@ search is applied. | | status | google.rpc.Status | | The RPC error status. | {{ template "field.payload.v1.Search.Response" }} - {{- end -}} {{- define "scheme.payload.v1.Update" }} @@ -1859,7 +1811,6 @@ search is applied. | during update operation. | {{ template "field.payload.v1.Filter.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Update.MultiObjectRequest" }} @@ -1879,7 +1830,6 @@ during update operation. | | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | {{ template "field.payload.v1.Update.ObjectRequest" }} - {{- end -}} {{- define "scheme.payload.v1.Update.MultiRequest" }} @@ -1899,7 +1849,6 @@ during update operation. | | requests | Update.Request | repeated | Represent the multiple update request content. | {{ template "field.payload.v1.Update.Request" }} - {{- end -}} {{- define "scheme.payload.v1.Update.ObjectRequest" }} @@ -1930,12 +1879,9 @@ during update operation. | {{ template "field.payload.v1.Object.Blob" }} - {{ template "field.payload.v1.Update.Config" }} - {{ template "field.payload.v1.Filter.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Update.Request" }} @@ -1961,9 +1907,7 @@ during update operation. | {{ template "field.payload.v1.Object.Vector" }} - {{ template "field.payload.v1.Update.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Update.TimestampRequest" }} @@ -2020,7 +1964,6 @@ during update operation. | during update operation. | {{ template "field.payload.v1.Filter.Config" }} - {{- end -}} {{- define "scheme.payload.v1.Upsert.MultiObjectRequest" }} @@ -2040,7 +1983,6 @@ during update operation. | | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | {{ template "field.payload.v1.Upsert.ObjectRequest" }} - {{- end -}} {{- define "scheme.payload.v1.Upsert.MultiRequest" }} @@ -2060,7 +2002,6 @@ during update operation. | | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | {{ template "field.payload.v1.Upsert.Request" }} - {{- end -}} {{- define "scheme.payload.v1.Upsert.ObjectRequest" }} @@ -2091,12 +2032,9 @@ during update operation. | {{ template "field.payload.v1.Object.Blob" }} - {{ template "field.payload.v1.Upsert.Config" }} - {{ template "field.payload.v1.Filter.Target" }} - {{- end -}} {{- define "scheme.payload.v1.Upsert.Request" }} @@ -2122,8 +2060,35 @@ during update operation. | {{ template "field.payload.v1.Object.Vector" }} - {{ template "field.payload.v1.Upsert.Config" }} +{{- end -}} + +{{ define "scheme.payload.v1.Remove.Timestamp.Operator" }} + enum Remove.Timestamp.Operator { + Eq = 0; + Ne = 1; + Ge = 2; + Gt = 3; + Le = 4; + Lt = 5; + } +{{- end -}} + +{{ define "field.payload.v1.Remove.Timestamp.Operator" }} + +{{- end -}} + +{{ define "scheme.payload.v1.Search.AggregationAlgorithm" }} + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } +{{- end -}} + +{{ define "field.payload.v1.Search.AggregationAlgorithm" }} {{- end -}} diff --git a/apis/docs/v1/payload.tmpl b/apis/docs/v1/payload.tmpl index 3fef7a141d..2709dd3377 100644 --- a/apis/docs/v1/payload.tmpl +++ b/apis/docs/v1/payload.tmpl @@ -1,4 +1,4 @@ -{{- $skip_types := list "Search.AggregationAlgorithm" "Remove.Timestamp.Operator" -}} +{{- $skip_types := list -}} {{- range .Scalars -}} {{- $skip_types = append $skip_types .ProtoType -}} {{- end -}} @@ -8,7 +8,7 @@ {{ printf "{{- define \"scheme.%s\" }}" .FullName }} message {{ .LongName }} { {{- range $i, $ := .Fields }} - {{if $.Label}}{{ $.Label }} {{end}}{{ $.LongType }} {{ $.Name }} = {{ add1 $i }}; + {{ if $.Label }}{{ $.Label }} {{end}}{{ $.LongType }} {{ $.Name }} = {{ add1 $i }}; {{- else }} // empty {{- end }} @@ -31,7 +31,7 @@ {{- range $i, $ := .Fields -}} {{- if not (or (has $.LongType $skip_types) (hasPrefix "google" $.FullType)) -}} - {{- printf "\n\n{{ template \"field.%s\" }}\n" $.FullType -}} + {{- printf "\n\n{{ template \"field.%s\" }}" $.FullType -}} {{- end -}} {{- end -}} {{- else }} @@ -39,4 +39,15 @@ {{- end -}} {{- println "\n{{- end -}}\n" -}} {{- end -}} + {{- range .Enums -}} + {{- printf "{{ define \"scheme.%s\" }}" .FullName }} + enum {{ .LongName }} { + {{- range .Values }} + {{ .Name }} = {{ .Number }}; + {{- end }} + } + {{- println "\n{{- end -}}\n" -}} + {{- printf "{{ define \"field.%s\" }}\n" .FullName -}} + {{- println "\n{{- end -}}\n" -}} + {{- end -}} {{- end -}} diff --git a/apis/docs/v1/remove.md b/apis/docs/v1/remove.md index 65681d1ab0..2972f114a1 100644 --- a/apis/docs/v1/remove.md +++ b/apis/docs/v1/remove.md @@ -1,10 +1,6 @@ # Vald Remove APIs -## Overview - -Remove service provides ways to remove indexed vectors. - -```rpc +## Overview```rpc service Remove { rpc Remove(payload.v1.Remove.Request) returns (payload.v1.Object.Location) {} @@ -14,11 +10,8 @@ service Remove { } ``` - ## Remove RPC -A method to remove an indexed vector. - ### Input - the scheme of `payload.v1.Remove.Request` @@ -44,23 +37,25 @@ A method to remove an indexed vector. - Remove.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | Object.ID | | The object ID to be removed. | - | config | Remove.Config | | The configuration of the remove request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + - Remove.Config - | field | type | label | desc. | - | :---------------------: | :---- | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | timestamp | int64 | | Remove timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output @@ -76,27 +71,16 @@ A method to remove an indexed vector. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## RemoveByTimestamp RPC -A method to remove an indexed vector based on timestamp. - ### Input - the scheme of `payload.v1.Remove.TimestampRequest` @@ -111,22 +95,34 @@ A method to remove an indexed vector based on timestamp. int64 timestamp = 1; Remove.Timestamp.Operator operator = 2; } + + + enum Remove.Timestamp.Operator { + Eq = 0; + Ne = 1; + Ge = 2; + Gt = 3; + Le = 4; + Lt = 5; + } ``` - Remove.TimestampRequest - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` +search is applied. | - search is applied. | - Remove.Timestamp - | field | type | label | desc. | - | :-------: | :------------------------ | :---- | :------------------------ | - | timestamp | int64 | | The timestamp. | - | operator | Remove.Timestamp.Operator | | The conditional operator. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | timestamp | int64 | | The timestamp. | + | operator | Remove.Timestamp.Operator | | The conditional operator. | + + ### Output @@ -147,33 +143,23 @@ A method to remove an indexed vector based on timestamp. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamRemove RPC -A method to remove multiple indexed vectors by bidirectional streaming. - ### Input - the scheme of `payload.v1.Remove.Request` @@ -199,23 +185,25 @@ A method to remove multiple indexed vectors by bidirectional streaming. - Remove.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | Object.ID | | The object ID to be removed. | - | config | Remove.Config | | The configuration of the remove request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + - Remove.Config - | field | type | label | desc. | - | :---------------------: | :---- | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | timestamp | int64 | | Remove timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output @@ -237,34 +225,24 @@ A method to remove multiple indexed vectors by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiRemove RPC -A method to remove multiple indexed vectors in a single request. - ### Input - the scheme of `payload.v1.Remove.MultiRequest` @@ -295,29 +273,32 @@ A method to remove multiple indexed vectors in a single request. - Remove.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :--------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Remove.Request | repeated | Represent the multiple remove request content. | + - Remove.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | Object.ID | | The object ID to be removed. | - | config | Remove.Config | | The configuration of the remove request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + - Object.ID - | field | type | label | desc. | - | :---: | :----- | :---- | :---- | - | id | string | | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + - Remove.Config - | field | type | label | desc. | - | :---------------------: | :---- | :---- | :-------------------------------------------------- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | timestamp | int64 | | Remove timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output @@ -338,25 +319,18 @@ A method to remove multiple indexed vectors in a single request. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + + diff --git a/apis/docs/v1/search.md b/apis/docs/v1/search.md index 01d3cab7aa..019b2332c7 100644 --- a/apis/docs/v1/search.md +++ b/apis/docs/v1/search.md @@ -1,10 +1,6 @@ # Vald Search APIs -## Overview - -Search service provides ways to search indexed vectors. - -```rpc +## Overview```rpc service Search { rpc Search(payload.v1.Search.Request) returns (payload.v1.Search.Response) {} @@ -22,11 +18,8 @@ service Search { } ``` - ## Search RPC -A method to search indexed vectors by a raw vector. - ### Input - the scheme of `payload.v1.Search.Request` @@ -74,56 +67,73 @@ A method to search indexed vectors by a raw vector. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -144,33 +154,23 @@ A method to search indexed vectors by a raw vector. - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## SearchByID RPC -A method to search indexed vectors by ID. - ### Input - the scheme of `payload.v1.Search.IDRequest` @@ -218,56 +218,73 @@ A method to search indexed vectors by ID. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -288,33 +305,23 @@ A method to search indexed vectors by ID. - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamSearch RPC -A method to search indexed vectors by multiple vectors. - ### Input - the scheme of `payload.v1.Search.Request` @@ -362,56 +369,73 @@ A method to search indexed vectors by multiple vectors. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -438,40 +462,31 @@ A method to search indexed vectors by multiple vectors. - Search.StreamResponse - | field | type | label | desc. | - | :------: | :---------------- | :---- | :----------------------------- | - | response | Search.Response | | Represent the search response. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamSearchByID RPC -A method to search indexed vectors by multiple IDs. - ### Input - the scheme of `payload.v1.Search.IDRequest` @@ -519,56 +534,73 @@ A method to search indexed vectors by multiple IDs. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -595,40 +627,31 @@ A method to search indexed vectors by multiple IDs. - Search.StreamResponse - | field | type | label | desc. | - | :------: | :---------------- | :---- | :----------------------------- | - | response | Search.Response | | Represent the search response. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiSearch RPC -A method to search indexed vectors by multiple vectors in a single request. - ### Input - the scheme of `payload.v1.Search.MultiRequest` @@ -681,62 +704,80 @@ A method to search indexed vectors by multiple vectors in a single request. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :--------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Search.Request | repeated | Represent the multiple search request content. | + - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -762,39 +803,30 @@ A method to search indexed vectors by multiple vectors in a single request. - Search.Responses - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | responses | Search.Response | repeated | Represent the multiple search response content. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiSearchByID RPC -A method to search indexed vectors by multiple IDs in a single request. - ### Input - the scheme of `payload.v1.Search.MultiIDRequest` @@ -847,62 +879,80 @@ A method to search indexed vectors by multiple IDs in a single request. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.MultiIDRequest - | field | type | label | desc. | - | :------: | :--------------- | :------- | :--------------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -928,39 +978,30 @@ A method to search indexed vectors by multiple IDs in a single request. - Search.Responses - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | responses | Search.Response | repeated | Represent the multiple search response content. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## LinearSearch RPC -A method to linear search indexed vectors by a raw vector. - ### Input - the scheme of `payload.v1.Search.Request` @@ -1008,56 +1049,73 @@ A method to linear search indexed vectors by a raw vector. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1078,33 +1136,23 @@ A method to linear search indexed vectors by a raw vector. - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## LinearSearchByID RPC -A method to linear search indexed vectors by ID. - ### Input - the scheme of `payload.v1.Search.IDRequest` @@ -1152,56 +1200,73 @@ A method to linear search indexed vectors by ID. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1222,33 +1287,23 @@ A method to linear search indexed vectors by ID. - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamLinearSearch RPC -A method to linear search indexed vectors by multiple vectors. - ### Input - the scheme of `payload.v1.Search.Request` @@ -1296,56 +1351,73 @@ A method to linear search indexed vectors by multiple vectors. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1372,40 +1444,31 @@ A method to linear search indexed vectors by multiple vectors. - Search.StreamResponse - | field | type | label | desc. | - | :------: | :---------------- | :---- | :----------------------------- | - | response | Search.Response | | Represent the search response. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamLinearSearchByID RPC -A method to linear search indexed vectors by multiple IDs. - ### Input - the scheme of `payload.v1.Search.IDRequest` @@ -1453,56 +1516,73 @@ A method to linear search indexed vectors by multiple IDs. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1529,41 +1609,31 @@ A method to linear search indexed vectors by multiple IDs. - Search.StreamResponse - | field | type | label | desc. | - | :------: | :---------------- | :---- | :----------------------------- | - | response | Search.Response | | Represent the search response. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiLinearSearch RPC -A method to linear search indexed vectors by multiple vectors in a single -request. - ### Input - the scheme of `payload.v1.Search.MultiRequest` @@ -1616,62 +1686,80 @@ request. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :--------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Search.Request | repeated | Represent the multiple search request content. | + - Search.Request - | field | type | label | desc. | - | :----: | :------------ | :------- | :--------------------------------------- | - | vector | float | repeated | The vector to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1697,40 +1785,30 @@ request. - Search.Responses - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | responses | Search.Response | repeated | Represent the multiple search response content. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiLinearSearchByID RPC -A method to linear search indexed vectors by multiple IDs in a single -request. - ### Input - the scheme of `payload.v1.Search.MultiIDRequest` @@ -1783,62 +1861,80 @@ request. string host = 1; uint32 port = 2; } + + + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } ``` - Search.MultiIDRequest - | field | type | label | desc. | - | :------: | :--------------- | :------- | :--------------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + - Search.IDRequest - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | id | string | | The vector ID to be searched. | - | config | Search.Config | | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | desc. | - | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | - | request_id | string | | Unique request ID. | - | num | uint32 | | Maximum number of result to be returned. | - | radius | float | | Search radius. | - | epsilon | float | | Search coefficient. | - | timeout | int64 | | Search timeout in nanoseconds. | - | ingress_filters | Filter.Config | | Ingress filter configurations. | - | egress_filters | Filter.Config | | Egress filter configurations. | - | min_num | uint32 | | Minimum number of result to be returned. | - | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | - | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | - | nprobe | uint32 | | Search nprobe. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + ### Output @@ -1864,31 +1960,25 @@ request. - Search.Responses - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | responses | Search.Response | repeated | Represent the multiple search response content. | + - Search.Response - | field | type | label | desc. | - | :--------: | :-------------- | :------- | :--------------------- | - | request_id | string | | The unique request ID. | - | results | Object.Distance | repeated | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + - Object.Distance - | field | type | label | desc. | - | :------: | :----- | :---- | :------------- | - | id | string | | The vector ID. | - | distance | float | | The distance. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + + + diff --git a/apis/docs/v1/update.md b/apis/docs/v1/update.md index 00e04c28b4..954d2bbaa4 100644 --- a/apis/docs/v1/update.md +++ b/apis/docs/v1/update.md @@ -1,10 +1,6 @@ # Vald Update APIs -## Overview - -Update service provides ways to update indexed vectors. - -```rpc +## Overview```rpc service Update { rpc Update(payload.v1.Update.Request) returns (payload.v1.Object.Location) {} @@ -14,11 +10,8 @@ service Update { } ``` - ## Update RPC -A method to update an indexed vector. - ### Input - the scheme of `payload.v1.Update.Request` @@ -59,42 +52,45 @@ A method to update an indexed vector. - Update.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be updated. | - | config | Update.Config | | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -110,27 +106,16 @@ A method to update an indexed vector. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamUpdate RPC -A method to update multiple indexed vectors by bidirectional streaming. - ### Input - the scheme of `payload.v1.Update.Request` @@ -171,42 +156,45 @@ A method to update multiple indexed vectors by bidirectional streaming. - Update.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be updated. | - | config | Update.Config | | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -228,34 +216,24 @@ A method to update multiple indexed vectors by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiUpdate RPC -A method to update multiple indexed vectors in a single request. - ### Input - the scheme of `payload.v1.Update.MultiRequest` @@ -301,48 +279,52 @@ A method to update multiple indexed vectors in a single request. - Update.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :--------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Update.Request | repeated | Represent the multiple update request content. | + - Update.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be updated. | - | config | Update.Config | | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Update.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Update timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -363,33 +345,23 @@ A method to update multiple indexed vectors in a single request. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## UpdateTimestamp RPC -A method to update timestamp an indexed vector. - ### Input - the scheme of `payload.v1.Update.TimestampRequest` @@ -404,11 +376,11 @@ A method to update timestamp an indexed vector. - Update.TimestampRequest - | field | type | label | desc. | - | :-------: | :----- | :---- | :------------------------------------------------ | - | id | string | | The vector ID. | - | timestamp | int64 | | timestamp represents when this vector inserted. | - | force | bool | | force represents forcefully update the timestamp. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + | force | bool | | force represents forcefully update the timestamp. | ### Output @@ -424,19 +396,11 @@ A method to update timestamp an indexed vector. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + + diff --git a/apis/docs/v1/upsert.md b/apis/docs/v1/upsert.md index 1e58f06308..b7f3e5d061 100644 --- a/apis/docs/v1/upsert.md +++ b/apis/docs/v1/upsert.md @@ -1,10 +1,6 @@ # Vald Upsert APIs -## Overview - -Upsert service provides ways to insert/update vectors. - -```rpc +## Overview```rpc service Upsert { rpc Upsert(payload.v1.Upsert.Request) returns (payload.v1.Object.Location) {} @@ -13,11 +9,8 @@ service Upsert { } ``` - ## Upsert RPC -A method to insert/update a vector. - ### Input - the scheme of `payload.v1.Upsert.Request` @@ -58,42 +51,45 @@ A method to insert/update a vector. - Upsert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -109,27 +105,16 @@ A method to insert/update a vector. - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## StreamUpsert RPC -A method to insert/update multiple vectors by bidirectional streaming. - ### Input - the scheme of `payload.v1.Upsert.Request` @@ -170,42 +155,45 @@ A method to insert/update multiple vectors by bidirectional streaming. - Upsert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -227,34 +215,24 @@ A method to insert/update multiple vectors by bidirectional streaming. - Object.StreamLocation - | field | type | label | desc. | - | :------: | :---------------- | :---- | :-------------------- | - | location | Object.Location | | The vector location. | - | status | google.rpc.Status | | The RPC error status. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | -### Status Code -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | ## MultiUpsert RPC -A method to insert/update multiple vectors in a single request. - ### Input - the scheme of `payload.v1.Upsert.MultiRequest` @@ -300,48 +278,52 @@ A method to insert/update multiple vectors in a single request. - Upsert.MultiRequest - | field | type | label | desc. | - | :------: | :------------- | :------- | :--------------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | + - Upsert.Request - | field | type | label | desc. | - | :----: | :------------ | :---- | :--------------------------------------- | - | vector | Object.Vector | | The vector to be upserted. | - | config | Upsert.Config | | The configuration of the upsert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + - Object.Vector - | field | type | label | desc. | - | :-------: | :----- | :------- | :---------------------------------------------- | - | id | string | | The vector ID. | - | vector | float | repeated | The vector. | - | timestamp | int64 | | timestamp represents when this vector inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + - Upsert.Config - | field | type | label | desc. | - | :---: | :--- | :---- | :---- | - | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | - | filters | Filter.Config | | Filter configuration. | - | timestamp | int64 | | Upsert timestamp. | - | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - during update operation. | - Filter.Config - | field | type | label | desc. | - | :-----: | :------------ | :------- | :----------------------------------------- | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | | targets | Filter.Target | repeated | Represent the filter target configuration. | + - Filter.Target - | field | type | label | desc. | - | :---: | :----- | :---- | :------------------- | - | host | string | | The target hostname. | - | port | uint32 | | The target port. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output @@ -362,25 +344,18 @@ A method to insert/update multiple vectors in a single request. - Object.Locations - | field | type | label | desc. | - | :-------: | :-------------- | :------- | :---- | - | locations | Object.Location | repeated | | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | desc. | - | :---: | :----- | :------- | :------------------------ | - | name | string | | The name of the location. | - | uuid | string | | The UUID of the vector. | - | ips | string | repeated | The IP list. | - -### Status Code - -| code | desc. | -| :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + + + diff --git a/apis/proto/v1/vald/flush.proto b/apis/proto/v1/vald/flush.proto index c745b841a3..e90065852c 100644 --- a/apis/proto/v1/vald/flush.proto +++ b/apis/proto/v1/vald/flush.proto @@ -26,9 +26,9 @@ option java_multiple_files = true; option java_outer_classname = "ValdFlush"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Flush service provides ways to flush all indexed vectors. +// Flush Service is responsible for removing all vectors that are indexed and uncommitted in the `vald-agent`. service Flush { - // A method to flush all indexed vector. + // Flush RPC is the method to remove all vectors. rpc Flush(payload.v1.Flush.Request) returns (payload.v1.Info.Index.Count) { option (google.api.http) = {delete: "/flush"}; } diff --git a/apis/proto/v1/vald/insert.proto b/apis/proto/v1/vald/insert.proto index 6cb99533e5..6c057fb646 100644 --- a/apis/proto/v1/vald/insert.proto +++ b/apis/proto/v1/vald/insert.proto @@ -26,9 +26,34 @@ option java_multiple_files = true; option java_outer_classname = "ValdInsert"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Insert service provides ways to add new vectors. +// Overview +// Insert Service is responsible for inserting new vectors into the `vald-agent`. service Insert { - // A method to add a new single vector. + // Overview + // Inset RPC is the method to add a new single vector. + // --- + // Status Code + // | code | desc. | + // | :--: | :---------------- | + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 13 | INTERNAL | + // --- + // 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. | rpc Insert(payload.v1.Insert.Request) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/insert" @@ -36,10 +61,68 @@ service Insert { }; } - // A method to add new multiple vectors by bidirectional streaming. + // Overview + // StreamInsert RPC is the method to add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server. + // Each Insert request and response are independent. + // It's the recommended method to insert a large number of vectors. + // --- + // Status Code + // | code | name | + // | :--: | :---------------- | + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 10 | ABORTED | + // | 13 | INTERNAL | + // --- + // 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. | rpc StreamInsert(stream payload.v1.Insert.Request) returns (stream payload.v1.Object.StreamLocation) {} - // A method to add new multiple vectors in a single request. + // Overview + // MultiInsert RPC is the method to add multiple new vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | code | name | + // | :--: | :---------------- | + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 10 | ABORTED | + // | 13 | INTERNAL | + // --- + // 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. | rpc MultiInsert(payload.v1.Insert.MultiRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/insert/multiple"