From 699961c973a1f7d48e85f7531e24e7eaa7510e75 Mon Sep 17 00:00:00 2001 From: Kosuke Morimoto Date: Fri, 13 Dec 2024 14:41:10 +0900 Subject: [PATCH] change symlink API documents (#2741) * copy API documents * Automated generation for API documents (#2742) * init auto generatation for API documents * auto-generated API documents * style: format code with Gofumpt and Prettier This commit fixes the style issues introduced in 7a36dd8 according to the output from Gofumpt and Prettier. Details: https://github.com/vdaas/vald/pull/2742 * update * style: format code with Gofumpt and Prettier This commit fixes the style issues introduced in 74dc4d6 according to the output from Gofumpt and Prettier. Details: https://github.com/vdaas/vald/pull/2742 * update * update * style: format code with Gofumpt and Prettier This commit fixes the style issues introduced in 384fc7e according to the output from Gofumpt and Prettier. Details: https://github.com/vdaas/vald/pull/2742 * update * fix * style: format code with Gofumpt and Prettier This commit fixes the style issues introduced in fa4ba75 according to the output from Gofumpt and Prettier. Details: https://github.com/vdaas/vald/pull/2742 --------- Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com> * add mirror document * style: format code with Gofumpt and Prettier This commit fixes the style issues introduced in df4d79e according to the output from Gofumpt and Prettier. Details: https://github.com/vdaas/vald/pull/2741 --------- Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com> Co-authored-by: Kiichiro YUKAWA --- Makefile | 4 + Makefile.d/functions.mk | 8 + Makefile.d/proto.mk | 31 +- apis/docs/buf.gen.doc.yaml | 27 + apis/docs/buf.gen.payload.yaml | 29 + apis/docs/buf.gen.tmpl.yaml | 27 + apis/docs/v1/doc.tmpl | 66 + apis/docs/v1/filter.md | 1552 +++++++++++++++++ apis/docs/v1/flush.md | 68 + apis/docs/v1/index.md | 473 ++++++ apis/docs/v1/insert.md | 420 +++++ apis/docs/v1/mirror.md | 87 + apis/docs/v1/object.md | 430 +++++ apis/docs/v1/payload.md.tmpl | 2626 +++++++++++++++++++++++++++++ apis/docs/v1/payload.tmpl | 100 ++ apis/docs/v1/remove.md | 446 +++++ apis/docs/v1/search.md | 1888 +++++++++++++++++++++ apis/docs/v1/update.md | 499 ++++++ apis/docs/v1/upsert.md | 436 +++++ apis/proto/v1/mirror/mirror.proto | 13 +- apis/proto/v1/vald/filter.proto | 162 +- apis/proto/v1/vald/flush.proto | 14 +- apis/proto/v1/vald/index.proto | 8 + apis/proto/v1/vald/insert.proto | 85 +- apis/proto/v1/vald/object.proto | 91 +- apis/proto/v1/vald/remove.proto | 114 +- apis/proto/v1/vald/search.proto | 336 +++- apis/proto/v1/vald/update.proto | 99 +- apis/proto/v1/vald/upsert.proto | 89 +- 29 files changed, 10173 insertions(+), 55 deletions(-) create mode 100644 apis/docs/buf.gen.doc.yaml create mode 100644 apis/docs/buf.gen.payload.yaml create mode 100644 apis/docs/buf.gen.tmpl.yaml create mode 100644 apis/docs/v1/doc.tmpl create mode 100644 apis/docs/v1/filter.md create mode 100644 apis/docs/v1/flush.md create mode 100644 apis/docs/v1/index.md create mode 100644 apis/docs/v1/insert.md create mode 100644 apis/docs/v1/mirror.md create mode 100644 apis/docs/v1/object.md create mode 100644 apis/docs/v1/payload.md.tmpl create mode 100644 apis/docs/v1/payload.tmpl create mode 100644 apis/docs/v1/remove.md create mode 100644 apis/docs/v1/search.md create mode 100644 apis/docs/v1/update.md create mode 100644 apis/docs/v1/upsert.md diff --git a/Makefile b/Makefile index 4e317a97fa..47acef0862 100644 --- a/Makefile +++ b/Makefile @@ -153,6 +153,10 @@ PROTOS_V1 := $(eval PROTOS_V1 := $(filter apis/proto/v1/%.proto,$(PROTOS)))$(PRO PBGOS = $(PROTOS:apis/proto/%.proto=apis/grpc/%.pb.go) SWAGGERS = $(PROTOS:apis/proto/%.proto=apis/swagger/%.swagger.json) PBDOCS = $(ROOTDIR)/apis/docs/v1/docs.md +PROTO_VALD_APIS := $(eval PROTO_VALD_APIS := $(filter $(ROOTDIR)/apis/proto/v1/vald/%.proto,$(PROTOS)))$(PROTO_VALD_APIS) +PROTO_VALD_API_DOCS := $(PROTO_VALD_APIS:$(ROOTDIR)/apis/proto/v1/vald/%.proto=$(ROOTDIR)/apis/docs/v1/%.md) +PROTO_MIRROR_APIS := $(eval PROTO_MIRROR_APIS := $(filter $(ROOTDIR)/apis/proto/v1/mirror/%.proto,$(PROTOS)))$(PROTO_MIRROR_APIS) +PROTO_MIRROR_API_DOCS := $(PROTO_MIRROR_APIS:$(ROOTDIR)/apis/proto/v1/mirror/%.proto=$(ROOTDIR)/apis/docs/v1/%.md) LDFLAGS = -static -fPIC -pthread -std=gnu++23 -lstdc++ -lm -z relro -z now -flto=auto -march=native -mtune=native -fno-plt -Ofast -fvisibility=hidden -ffp-contract=fast -fomit-frame-pointer -fmerge-all-constants -funroll-loops -falign-functions=32 -ffunction-sections -fdata-sections diff --git a/Makefile.d/functions.mk b/Makefile.d/functions.mk index fa794ee769..1802d7d7b6 100644 --- a/Makefile.d/functions.mk +++ b/Makefile.d/functions.mk @@ -446,3 +446,11 @@ define gen-deadlink-checker $$BIN_PATH -path $3 -ignore-path $4 -format $5 $1; \ rm -rf $$BIN_PATH endef + +define gen-api-document + buf generate --template=apis/docs/buf.gen.tmpl.yaml --path $2 + cat apis/docs/v1/payload.md.tmpl apis/docs/v1/_doc.md.tmpl > apis/docs/v1/doc.md.tmpl; \ + buf generate --template=apis/docs/buf.gen.doc.yaml --path $2; \ + mv $(ROOTDIR)/apis/docs/v1/doc.md $1; \ + rm apis/docs/v1/*doc.md.tmpl +endef diff --git a/Makefile.d/proto.mk b/Makefile.d/proto.mk index 1870f8aa72..5ca6902ea6 100644 --- a/Makefile.d/proto.mk +++ b/Makefile.d/proto.mk @@ -17,7 +17,8 @@ ## build protobufs proto/all: \ proto/deps \ - proto/gen + proto/gen/code \ + proto/gen/api/docs .PHONY: proto/clean ## clean proto artifacts @@ -34,23 +35,28 @@ proto/paths/print: .PHONY: proto/deps ## install protobuf dependencies proto/deps: \ - $(GOBIN)/buf + $(GOBIN)/buf \ + $(GOBIN)/protoc-gen-doc .PHONY: proto/clean/deps ## uninstall all protobuf dependencies proto/clean/deps: rm -rf $(GOBIN)/buf + rm -rf $(GOBIN)/protoc-gen-doc $(GOBIN)/buf: $(call go-install, github.com/bufbuild/buf/cmd/buf) +$(GOBIN)/protoc-gen-doc: + $(call go-install, github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc) + $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto: curl -fsSL https://raw.githubusercontent.com/googleapis/googleapis/master/google/rpc/error_details.proto -o $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto sed -i -e "s/package google.rpc/package rpc.v1/" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto sed -i -e "s%google.golang.org/genproto/googleapis/rpc/errdetails;errdetails%$(GOPKG)/apis/grpc/v1/rpc/errdetails%" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto sed -i -e "s/com.google.rpc/org.vdaas.vald.api.v1.rpc/" $(ROOTDIR)/apis/proto/v1/rpc/errdetails/error_details.proto -proto/gen: \ +proto/gen/code: \ $(PROTOS) \ proto/deps @$(call green, "generating pb.go and swagger.json files and documents for API v1...") @@ -58,6 +64,25 @@ proto/gen: \ buf generate make proto/replace +proto/gen/api/docs: \ + proto/gen/api/docs/payload \ + $(PROTO_VALD_API_DOCS) \ + $(PROTO_MIRROR_API_DOCS) + +proto/gen/api/docs/payload: $(ROOTDIR)/apis/docs/v1/payload.md.tmpl + +$(ROOTDIR)/apis/docs/v1/payload.md.tmpl: $(ROOTDIR)/apis/proto/v1/payload/payload.proto $(ROOTDIR)/apis/docs/v1/payload.tmpl + @$(call green,"generating payload v1...") + buf generate --template=apis/docs/buf.gen.payload.yaml + +$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto $(ROOTDIR)/apis/docs/v1/payload.md.tmpl $(ROOTDIR)/apis/docs/v1/doc.tmpl + @$(call green,"generating documents for API v1...") + @$(call gen-api-document,$@,$(subst $(ROOTDIR)/,,$<)) + +$(ROOTDIR)/apis/docs/v1/mirror.md: $(ROOTDIR)/apis/proto/v1/mirror/mirror.proto $(ROOTDIR)/apis/docs/v1/payload.md.tmpl $(ROOTDIR)/apis/docs/v1/doc.tmpl + @$(call green,"generating documents for API v1...") + @$(call gen-api-document,$@,$(subst $(ROOTDIR)/,,$<)) + proto/replace: find $(ROOTDIR)/apis/grpc/* -name '*.go' | xargs -P$(CORES) sed -i -E "s%google.golang.org/grpc/codes%$(GOPKG)/internal/net/grpc/codes%g" find $(ROOTDIR)/apis/grpc/* -name '*.go' | xargs -P$(CORES) sed -i -E "s%google.golang.org/grpc/status%$(GOPKG)/internal/net/grpc/status%g" diff --git a/apis/docs/buf.gen.doc.yaml b/apis/docs/buf.gen.doc.yaml new file mode 100644 index 0000000000..ccbec0497b --- /dev/null +++ b/apis/docs/buf.gen.doc.yaml @@ -0,0 +1,27 @@ +# +# Copyright (C) 2019-2024 vdaas.org vald team +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# You may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +version: v2 +managed: + disable: + - file_option: go_package + module: buf.build/googleapis/googleapis + override: + - file_option: go_package_prefix + value: github.com/vdaas/vald/apis/grpc +plugins: + - local: protoc-gen-doc + out: apis/docs/v1 + opt: apis/docs/v1/doc.md.tmpl,doc.md diff --git a/apis/docs/buf.gen.payload.yaml b/apis/docs/buf.gen.payload.yaml new file mode 100644 index 0000000000..8dd7f45c7c --- /dev/null +++ b/apis/docs/buf.gen.payload.yaml @@ -0,0 +1,29 @@ +# +# Copyright (C) 2019-2024 vdaas.org vald team +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# You may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +version: v2 +managed: + disable: + - file_option: go_package + module: buf.build/googleapis/googleapis + override: + - file_option: go_package_prefix + value: github.com/vdaas/vald/apis/grpc +plugins: + - local: protoc-gen-doc + out: apis/docs/v1 + opt: apis/docs/v1/payload.tmpl,payload.md.tmpl +inputs: + - proto_file: apis/proto/v1/payload/payload.proto diff --git a/apis/docs/buf.gen.tmpl.yaml b/apis/docs/buf.gen.tmpl.yaml new file mode 100644 index 0000000000..78c007a5dd --- /dev/null +++ b/apis/docs/buf.gen.tmpl.yaml @@ -0,0 +1,27 @@ +# +# Copyright (C) 2019-2024 vdaas.org vald team +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# You may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +version: v2 +managed: + disable: + - file_option: go_package + module: buf.build/googleapis/googleapis + override: + - file_option: go_package_prefix + value: github.com/vdaas/vald/apis/grpc +plugins: + - local: protoc-gen-doc + out: apis/docs/v1 + opt: apis/docs/v1/doc.tmpl,_doc.md.tmpl diff --git a/apis/docs/v1/doc.tmpl b/apis/docs/v1/doc.tmpl new file mode 100644 index 0000000000..243c951243 --- /dev/null +++ b/apis/docs/v1/doc.tmpl @@ -0,0 +1,66 @@ +{{- 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" }}{{ $descs.Overview | trim }}{{ end }} + +```rpc +service {{.Name}} { + +{{ range .Methods }} rpc {{ .Name }}({{ .RequestFullType }}) returns ({{ .ResponseFullType }}) {} +{{ end }} +} +``` + +{{ 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" }}{{ $descs.Overview | trim }}{{ end }} + +### Input + +- the scheme of `{{ .RequestFullType }}` + + ```rpc +{{ printf "{{- template \"scheme:%s\" }}\n" .RequestFullType }} + ``` +{{ printf "{{ template \"field:%s\" }}" .RequestFullType }} +### Output + +- the scheme of `{{ .ResponseFullType }}` + + ```rpc +{{ printf "{{- template \"scheme:%s\" }}\n" .ResponseFullType }} + ``` +{{ printf "{{ template \"field:%s\" }}" .ResponseFullType }} +{{ if hasKey $descs "Status Code" }} +### Status Code + +| code | description | +| :--: | :---------------- | +{{ pluck "Status Code" $descs | first | trim }} + +Please refer to [Response Status Code](../status.md) for more details. +{{ end }} +{{ if hasKey $descs "Troubleshooting" }} +### Troubleshooting + +{{ pluck "Troubleshooting" $descs | first | trim }} +{{ end }} + +{{- end -}} +{{- end -}} +{{- end -}} diff --git a/apis/docs/v1/filter.md b/apis/docs/v1/filter.md new file mode 100644 index 0000000000..fa4b1643f6 --- /dev/null +++ b/apis/docs/v1/filter.md @@ -0,0 +1,1552 @@ +# Vald Filter APIs + +## Overview + +Filter Server is responsible for providing insert, update, upsert and search interface for `Vald Filter Gateway`. + +Vald Filter Gateway forward user request to user-defined ingress/egress filter components allowing user to run custom logic. + +```rpc +service Filter { + + rpc SearchObject(payload.v1.Search.ObjectRequest) returns (payload.v1.Search.Response) {} + rpc MultiSearchObject(payload.v1.Search.MultiObjectRequest) returns (payload.v1.Search.Responses) {} + rpc StreamSearchObject(payload.v1.Search.ObjectRequest) returns (payload.v1.Search.StreamResponse) {} + rpc InsertObject(payload.v1.Insert.ObjectRequest) returns (payload.v1.Object.Location) {} + rpc StreamInsertObject(payload.v1.Insert.ObjectRequest) returns (payload.v1.Object.StreamLocation) {} + rpc MultiInsertObject(payload.v1.Insert.MultiObjectRequest) returns (payload.v1.Object.Locations) {} + rpc UpdateObject(payload.v1.Update.ObjectRequest) returns (payload.v1.Object.Location) {} + rpc StreamUpdateObject(payload.v1.Update.ObjectRequest) returns (payload.v1.Object.StreamLocation) {} + rpc MultiUpdateObject(payload.v1.Update.MultiObjectRequest) returns (payload.v1.Object.Locations) {} + rpc UpsertObject(payload.v1.Upsert.ObjectRequest) returns (payload.v1.Object.Location) {} + rpc StreamUpsertObject(payload.v1.Upsert.ObjectRequest) returns (payload.v1.Object.StreamLocation) {} + rpc MultiUpsertObject(payload.v1.Upsert.MultiObjectRequest) returns (payload.v1.Object.Locations) {} + +} +``` + +## SearchObject RPC + +SearchObject RPC is the method to search object(s) similar to request object. + +### Input + +- the scheme of `payload.v1.Search.ObjectRequest` + + ```rpc + message Search.ObjectRequest { + bytes object = 1; + Search.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + ``` + + - Search.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Search.Response` + + ```rpc + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## MultiSearchObject RPC + +StreamSearchObject RPC is the method to search vectors with multi queries(objects) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+By using the bidirectional streaming RPC, the search request can be communicated in any order between client and server. +Each Search request and response are independent. + +### Input + +- the scheme of `payload.v1.Search.MultiObjectRequest` + + ```rpc + message Search.MultiObjectRequest { + repeated Search.ObjectRequest requests = 1; + } + + message Search.ObjectRequest { + bytes object = 1; + Search.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + ``` + + - Search.MultiObjectRequest + + | field | type | label | description | + | :------: | :------------------- | :------- | :-------------------------------------------------------------- | + | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | + + - Search.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Search.Responses` + + ```rpc + message Search.Responses { + repeated Search.Response responses = 1; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Responses + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------------------------------------------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## StreamSearchObject RPC + +MultiSearchObject RPC is the method to search objects with multiple objects in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Search.ObjectRequest` + + ```rpc + message Search.ObjectRequest { + bytes object = 1; + Search.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + ``` + + - Search.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Search.StreamResponse` + + ```rpc + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.StreamResponse + + | field | type | label | description | + | :------: | :---------------- | :---- | :----------------------------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## InsertObject RPC + +InsertObject RPC is the method to insert object through Vald Filter Gateway. + +### Input + +- the scheme of `payload.v1.Insert.ObjectRequest` + + ```rpc + message Insert.ObjectRequest { + Object.Blob object = 1; + Insert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Insert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## StreamInsertObject RPC + +StreamInsertObject RPC is the method to add new multiple object using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc). + +By using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server. +Each Insert request and response are independent. +It's the recommended method to insert a large number of objects. + +### Input + +- the scheme of `payload.v1.Insert.ObjectRequest` + + ```rpc + message Insert.ObjectRequest { + Object.Blob object = 1; + Insert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Insert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## MultiInsertObject RPC + +MultiInsertObject RPC is the method to add multiple new objects in **1** request. + +### Input + +- the scheme of `payload.v1.Insert.MultiObjectRequest` + + ```rpc + message Insert.MultiObjectRequest { + repeated Insert.ObjectRequest requests = 1; + } + + message Insert.ObjectRequest { + Object.Blob object = 1; + Insert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Insert.MultiObjectRequest + + | field | type | label | description | + | :------: | :------------------- | :------- | :------------------------------------------- | + | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | + + - Insert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## UpdateObject RPC + +UpdateObject RPC is the method to update a single vector. + +### Input + +- the scheme of `payload.v1.Update.ObjectRequest` + + ```rpc + message Update.ObjectRequest { + Object.Blob object = 1; + Update.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Update.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## StreamUpdateObject RPC + +StreamUpdateObject RPC is the method to update multiple objects using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+By using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. +Each Update request and response are independent. +It's the recommended method to update the large amount of objects. + +### Input + +- the scheme of `payload.v1.Update.ObjectRequest` + + ```rpc + message Update.ObjectRequest { + Object.Blob object = 1; + Update.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Update.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## MultiUpdateObject RPC + +MultiUpdateObject is the method to update multiple objects in **1** request. + +
+gRPC has the message size limitation.
+Please be careful that the size of the request exceed the limit. +
+ +### Input + +- the scheme of `payload.v1.Update.MultiObjectRequest` + + ```rpc + message Update.MultiObjectRequest { + repeated Update.ObjectRequest requests = 1; + } + + message Update.ObjectRequest { + Object.Blob object = 1; + Update.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Update.MultiObjectRequest + + | field | type | label | description | + | :------: | :------------------- | :------- | :---------------------------------------------------- | + | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | + + - Update.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## UpsertObject RPC + +UpsertObject RPC is the method to update a single object and add a new single object. + +### Input + +- the scheme of `payload.v1.Upsert.ObjectRequest` + + ```rpc + message Upsert.ObjectRequest { + Object.Blob object = 1; + Upsert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Upsert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## StreamUpsertObject RPC + +UpsertObject RPC is the method to update a single object and add a new single object. + +### Input + +- the scheme of `payload.v1.Upsert.ObjectRequest` + + ```rpc + message Upsert.ObjectRequest { + Object.Blob object = 1; + Upsert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Upsert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +## MultiUpsertObject RPC + +MultiUpsertObject is the method to update existing multiple objects and add new multiple objects in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Upsert.MultiObjectRequest` + + ```rpc + message Upsert.MultiObjectRequest { + repeated Upsert.ObjectRequest requests = 1; + } + + message Upsert.ObjectRequest { + Object.Blob object = 1; + Upsert.Config config = 2; + Filter.Target vectorizer = 3; + } + + message Object.Blob { + string id = 1; + bytes object = 2; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + ``` + + - Upsert.MultiObjectRequest + + | field | type | label | description | + | :------: | :------------------- | :------- | :---------------------------------------------------- | + | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | + + - Upsert.ObjectRequest + + | field | type | label | description | + | :--------: | :------------ | :---- | :--------------------------------------- | + | 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 | description | + | :----: | :----- | :---- | :----------------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 6 | ALREADY_EXISTS | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. diff --git a/apis/docs/v1/flush.md b/apis/docs/v1/flush.md new file mode 100644 index 0000000000..504c14ef51 --- /dev/null +++ b/apis/docs/v1/flush.md @@ -0,0 +1,68 @@ +# Vald Flush APIs + +## Overview + +Flush Service is responsible for removing all vectors that are indexed and uncommitted in the `vald-agent`. + +```rpc +service Flush { + + rpc Flush(payload.v1.Flush.Request) returns (payload.v1.Info.Index.Count) {} + +} +``` + +## Flush RPC + +Flush RPC is the method to remove all vectors. + +### Input + +- the scheme of `payload.v1.Flush.Request` + + ```rpc + message Flush.Request { + // empty + } + + ``` + + - Flush.Request + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.Count` + + ```rpc + message Info.Index.Count { + uint32 stored = 1; + uint32 uncommitted = 2; + bool indexing = 3; + bool saving = 4; + } + + ``` + + - Info.Index.Count + + | field | type | label | description | + | :---------: | :----- | :---- | :--------------------------- | + | 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 | description | +| :--: | :---------------- | +| 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. diff --git a/apis/docs/v1/index.md b/apis/docs/v1/index.md new file mode 100644 index 0000000000..5379f4efb5 --- /dev/null +++ b/apis/docs/v1/index.md @@ -0,0 +1,473 @@ +# Vald Index APIs + +## Overview + +Represent the index manager service. + +```rpc +service Index { + + rpc IndexInfo(payload.v1.Empty) returns (payload.v1.Info.Index.Count) {} + rpc IndexDetail(payload.v1.Empty) returns (payload.v1.Info.Index.Detail) {} + rpc IndexStatistics(payload.v1.Empty) returns (payload.v1.Info.Index.Statistics) {} + rpc IndexStatisticsDetail(payload.v1.Empty) returns (payload.v1.Info.Index.StatisticsDetail) {} + rpc IndexProperty(payload.v1.Empty) returns (payload.v1.Info.Index.PropertyDetail) {} + +} +``` + +## IndexInfo RPC + +Represent the RPC to get the index information. + +### Input + +- the scheme of `payload.v1.Empty` + + ```rpc + message Empty { + // empty + } + + ``` + + - Empty + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.Count` + + ```rpc + message Info.Index.Count { + uint32 stored = 1; + uint32 uncommitted = 2; + bool indexing = 3; + bool saving = 4; + } + + ``` + + - Info.Index.Count + + | field | type | label | description | + | :---------: | :----- | :---- | :--------------------------- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | + +## IndexDetail RPC + +Represent the RPC to get the index information for each agents. + +### Input + +- the scheme of `payload.v1.Empty` + + ```rpc + message Empty { + // empty + } + + ``` + + - Empty + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.Detail` + + ```rpc + message Info.Index.Detail { + repeated Info.Index.Detail.CountsEntry counts = 1; + uint32 replica = 2; + uint32 live_agents = 3; + } + + message Info.Index.Detail.CountsEntry { + string key = 1; + Info.Index.Count value = 2; + } + + message Info.Index.Count { + uint32 stored = 1; + uint32 uncommitted = 2; + bool indexing = 3; + bool saving = 4; + } + + ``` + + - Info.Index.Detail + + | field | type | label | description | + | :---------: | :---------------------------- | :------- | :--------------------------------- | + | 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 | description | + | :---: | :--------------- | :---- | :---------- | + | key | string | | | + | value | Info.Index.Count | | | + + - Info.Index.Count + + | field | type | label | description | + | :---------: | :----- | :---- | :--------------------------- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | + +## IndexStatistics RPC + +Represent the RPC to get the index statistics. + +### Input + +- the scheme of `payload.v1.Empty` + + ```rpc + message Empty { + // empty + } + + ``` + + - Empty + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.Statistics` + + ```rpc + message Info.Index.Statistics { + bool valid = 1; + int32 median_indegree = 2; + int32 median_outdegree = 3; + uint64 max_number_of_indegree = 4; + uint64 max_number_of_outdegree = 5; + uint64 min_number_of_indegree = 6; + uint64 min_number_of_outdegree = 7; + uint64 mode_indegree = 8; + uint64 mode_outdegree = 9; + uint64 nodes_skipped_for_10_edges = 10; + uint64 nodes_skipped_for_indegree_distance = 11; + uint64 number_of_edges = 12; + uint64 number_of_indexed_objects = 13; + uint64 number_of_nodes = 14; + uint64 number_of_nodes_without_edges = 15; + uint64 number_of_nodes_without_indegree = 16; + uint64 number_of_objects = 17; + uint64 number_of_removed_objects = 18; + uint64 size_of_object_repository = 19; + uint64 size_of_refinement_object_repository = 20; + double variance_of_indegree = 21; + double variance_of_outdegree = 22; + double mean_edge_length = 23; + double mean_edge_length_for_10_edges = 24; + double mean_indegree_distance_for_10_edges = 25; + double mean_number_of_edges_per_node = 26; + double c1_indegree = 27; + double c5_indegree = 28; + double c95_outdegree = 29; + double c99_outdegree = 30; + repeated int64 indegree_count = 31; + repeated uint64 outdegree_histogram = 32; + repeated uint64 indegree_histogram = 33; + } + + ``` + + - Info.Index.Statistics + + | field | type | label | description | + | :----------------------------------: | :----- | :------- | :---------- | + | 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. + +### Input + +- the scheme of `payload.v1.Empty` + + ```rpc + message Empty { + // empty + } + + ``` + + - Empty + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.StatisticsDetail` + + ```rpc + message Info.Index.StatisticsDetail { + repeated Info.Index.StatisticsDetail.DetailsEntry details = 1; + } + + message Info.Index.StatisticsDetail.DetailsEntry { + string key = 1; + Info.Index.Statistics value = 2; + } + + message Info.Index.Statistics { + bool valid = 1; + int32 median_indegree = 2; + int32 median_outdegree = 3; + uint64 max_number_of_indegree = 4; + uint64 max_number_of_outdegree = 5; + uint64 min_number_of_indegree = 6; + uint64 min_number_of_outdegree = 7; + uint64 mode_indegree = 8; + uint64 mode_outdegree = 9; + uint64 nodes_skipped_for_10_edges = 10; + uint64 nodes_skipped_for_indegree_distance = 11; + uint64 number_of_edges = 12; + uint64 number_of_indexed_objects = 13; + uint64 number_of_nodes = 14; + uint64 number_of_nodes_without_edges = 15; + uint64 number_of_nodes_without_indegree = 16; + uint64 number_of_objects = 17; + uint64 number_of_removed_objects = 18; + uint64 size_of_object_repository = 19; + uint64 size_of_refinement_object_repository = 20; + double variance_of_indegree = 21; + double variance_of_outdegree = 22; + double mean_edge_length = 23; + double mean_edge_length_for_10_edges = 24; + double mean_indegree_distance_for_10_edges = 25; + double mean_number_of_edges_per_node = 26; + double c1_indegree = 27; + double c5_indegree = 28; + double c95_outdegree = 29; + double c99_outdegree = 30; + repeated int64 indegree_count = 31; + repeated uint64 outdegree_histogram = 32; + repeated uint64 indegree_histogram = 33; + } + + ``` + + - Info.Index.StatisticsDetail + + | field | type | label | description | + | :-----: | :--------------------------------------- | :------- | :-------------------------- | + | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | + + - Info.Index.StatisticsDetail.DetailsEntry + + | field | type | label | description | + | :---: | :-------------------- | :---- | :---------- | + | key | string | | | + | value | Info.Index.Statistics | | | + + - Info.Index.Statistics + + | field | type | label | description | + | :----------------------------------: | :----- | :------- | :---------- | + | 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. + +### Input + +- the scheme of `payload.v1.Empty` + + ```rpc + message Empty { + // empty + } + + ``` + + - Empty + + empty + +### Output + +- the scheme of `payload.v1.Info.Index.PropertyDetail` + + ```rpc + message Info.Index.PropertyDetail { + repeated Info.Index.PropertyDetail.DetailsEntry details = 1; + } + + message Info.Index.PropertyDetail.DetailsEntry { + string key = 1; + Info.Index.Property value = 2; + } + + message Info.Index.Property { + int32 dimension = 1; + int32 thread_pool_size = 2; + string object_type = 3; + string distance_type = 4; + string index_type = 5; + string database_type = 6; + string object_alignment = 7; + int32 path_adjustment_interval = 8; + int32 graph_shared_memory_size = 9; + int32 tree_shared_memory_size = 10; + int32 object_shared_memory_size = 11; + int32 prefetch_offset = 12; + int32 prefetch_size = 13; + string accuracy_table = 14; + string search_type = 15; + float max_magnitude = 16; + int32 n_of_neighbors_for_insertion_order = 17; + float epsilon_for_insertion_order = 18; + string refinement_object_type = 19; + int32 truncation_threshold = 20; + int32 edge_size_for_creation = 21; + int32 edge_size_for_search = 22; + int32 edge_size_limit_for_creation = 23; + double insertion_radius_coefficient = 24; + int32 seed_size = 25; + string seed_type = 26; + int32 truncation_thread_pool_size = 27; + int32 batch_size_for_creation = 28; + string graph_type = 29; + int32 dynamic_edge_size_base = 30; + int32 dynamic_edge_size_rate = 31; + float build_time_limit = 32; + int32 outgoing_edge = 33; + int32 incoming_edge = 34; + } + + ``` + + - Info.Index.PropertyDetail + + | field | type | label | description | + | :-----: | :------------------------------------- | :------- | :---------- | + | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | + + - Info.Index.PropertyDetail.DetailsEntry + + | field | type | label | description | + | :---: | :------------------ | :---- | :---------- | + | key | string | | | + | value | Info.Index.Property | | | + + - Info.Index.Property + + | field | type | label | description | + | :--------------------------------: | :----- | :---- | :---------- | + | 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 new file mode 100644 index 0000000000..40e91e84cc --- /dev/null +++ b/apis/docs/v1/insert.md @@ -0,0 +1,420 @@ +# Vald Insert APIs + +## Overview + +Insert Service is responsible for inserting new vectors into the `vald-agent`. + +```rpc +service Insert { + + rpc Insert(payload.v1.Insert.Request) returns (payload.v1.Object.Location) {} + rpc StreamInsert(payload.v1.Insert.Request) returns (payload.v1.Object.StreamLocation) {} + rpc MultiInsert(payload.v1.Insert.MultiRequest) returns (payload.v1.Object.Locations) {} + +} +``` + +## Insert RPC + +Inset RPC is the method to add a new single vector. + +### Input + +- the scheme of `payload.v1.Insert.Request` + + ```rpc + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Insert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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 + +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 + +- the scheme of `payload.v1.Insert.Request` + + ```rpc + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Insert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 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 + +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 + +- the scheme of `payload.v1.Insert.MultiRequest` + + ```rpc + message Insert.MultiRequest { + repeated Insert.Request requests = 1; + } + + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Insert.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :----------------------------------------- | + | requests | Insert.Request | repeated | Represent multiple insert request content. | + + - Insert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config + + | field | type | label | description | + | :---------------------: | :------------ | :---- | :-------------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 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/mirror.md b/apis/docs/v1/mirror.md new file mode 100644 index 0000000000..cdb0d1cff8 --- /dev/null +++ b/apis/docs/v1/mirror.md @@ -0,0 +1,87 @@ +# Vald Mirror APIs + +## Overview + +Mirror Service is responsible for providing the `Register` interface for the Vald Mirror Gateway. + +```rpc +service Mirror { + + rpc Register(payload.v1.Mirror.Targets) returns (payload.v1.Mirror.Targets) {} + +} +``` + +## Register RPC + +Register RPC is the method to register other Vald Mirror Gateway targets. + +### Input + +- the scheme of `payload.v1.Mirror.Targets` + + ```rpc + message Mirror.Targets { + repeated Mirror.Target targets = 1; + } + + message Mirror.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Mirror.Targets + + | field | type | label | description | + | :-----: | :------------ | :------- | :------------------------------- | + | targets | Mirror.Target | repeated | The multiple target information. | + + - Mirror.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Mirror.Targets` + + ```rpc + message Mirror.Targets { + repeated Mirror.Target targets = 1; + } + + message Mirror.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Mirror.Targets + + | field | type | label | description | + | :-----: | :------------ | :------- | :------------------------------- | + | targets | Mirror.Target | repeated | The multiple target information. | + + - Mirror.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. diff --git a/apis/docs/v1/object.md b/apis/docs/v1/object.md new file mode 100644 index 0000000000..aee45109cb --- /dev/null +++ b/apis/docs/v1/object.md @@ -0,0 +1,430 @@ +# Vald Object APIs + +## Overview + +Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent`. + +```rpc +service Object { + + rpc Exists(payload.v1.Object.ID) returns (payload.v1.Object.ID) {} + rpc GetObject(payload.v1.Object.VectorRequest) returns (payload.v1.Object.Vector) {} + rpc StreamGetObject(payload.v1.Object.VectorRequest) returns (payload.v1.Object.StreamVector) {} + rpc StreamListObject(payload.v1.Object.List.Request) returns (payload.v1.Object.List.Response) {} + rpc GetTimestamp(payload.v1.Object.TimestampRequest) returns (payload.v1.Object.Timestamp) {} + +} +``` + +## Exists RPC + +Exists RPC is the method to check that a vector exists in the `vald-agent`. + +### Input + +- the scheme of `payload.v1.Object.ID` + + ```rpc + message Object.ID { + string id = 1; + } + + ``` + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + +### Output + +- the scheme of `payload.v1.Object.ID` + + ```rpc + message Object.ID { + string id = 1; + } + + ``` + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## GetObject RPC + +GetObject RPC is the method to get the metadata of a vector inserted into the `vald-agent`. + +### Input + +- the scheme of `payload.v1.Object.VectorRequest` + + ```rpc + message Object.VectorRequest { + Object.ID id = 1; + Filter.Config filters = 2; + } + + message Object.ID { + string id = 1; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Object.VectorRequest + + | field | type | label | description | + | :-----: | :------------ | :---- | :--------------------------- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Vector` + + ```rpc + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + ``` + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamGetObject RPC + +StreamGetObject RPC is the method to get the metadata of multiple existing vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the GetObject request can be communicated in any order between client and server. +Each Upsert request and response are independent. + +### Input + +- the scheme of `payload.v1.Object.VectorRequest` + + ```rpc + message Object.VectorRequest { + Object.ID id = 1; + Filter.Config filters = 2; + } + + message Object.ID { + string id = 1; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Object.VectorRequest + + | field | type | label | description | + | :-----: | :------------ | :---- | :--------------------------- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.StreamVector` + + ```rpc + message Object.StreamVector { + Object.Vector vector = 1; + google.rpc.Status status = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + ``` + + - Object.StreamVector + + | field | type | label | description | + | :----: | :---------------- | :---- | :-------------------- | + | vector | Object.Vector | | The vector. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +The request process may not be completed when the response code is NOT `0 (OK)`. + +Here are some common reasons and how to resolve each error. + +| name | common reason | how to resolve | +| :---------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | +| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | +| INVALID_ARGUMENT | The Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamListObject RPC + +A method to get all the vectors with server streaming + +### Input + +- the scheme of `payload.v1.Object.List.Request` + + ```rpc + message Object.List.Request { + // empty + } + + ``` + + - Object.List.Request + + empty + +### Output + +- the scheme of `payload.v1.Object.List.Response` + + ```rpc + message Object.List.Response { + Object.Vector vector = 1; + google.rpc.Status status = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + ``` + + - Object.List.Response + + | field | type | label | description | + | :----: | :---------------- | :---- | :-------------------- | + | vector | Object.Vector | | The vector | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | description | +| :--: | :---------- | + +TODO + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +TODO + +## 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` + + ```rpc + message Object.TimestampRequest { + Object.ID id = 1; + } + + message Object.ID { + string id = 1; + } + + ``` + + - Object.TimestampRequest + + | field | type | label | description | + | :---: | :-------- | :---- | :--------------------------- | + | id | Object.ID | | The vector ID to be fetched. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + +### Output + +- the scheme of `payload.v1.Object.Timestamp` + + ```rpc + message Object.Timestamp { + string id = 1; + int64 timestamp = 2; + } + + ``` + + - Object.Timestamp + + | field | type | label | description | + | :-------: | :----- | :---- | :---------------------------------------------- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | description | +| :--: | :---------- | + +TODO + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +TODO diff --git a/apis/docs/v1/payload.md.tmpl b/apis/docs/v1/payload.md.tmpl new file mode 100644 index 0000000000..769f09b1e6 --- /dev/null +++ b/apis/docs/v1/payload.md.tmpl @@ -0,0 +1,2626 @@ +{{- define "scheme:payload.v1.Control" -}} +{{ template "_scheme:payload.v1.Control" }} +{{- end -}} +{{- define "field:payload.v1.Control" -}} +{{ template "_field:payload.v1.Control" }} +{{- end -}} +{{- define "scheme:payload.v1.Control.CreateIndexRequest" -}} +{{ template "_scheme:payload.v1.Control.CreateIndexRequest" }} +{{- end -}} +{{- define "field:payload.v1.Control.CreateIndexRequest" -}} +{{ template "_field:payload.v1.Control.CreateIndexRequest" }} +{{- end -}} +{{- define "scheme:payload.v1.Discoverer" -}} +{{ template "_scheme:payload.v1.Discoverer" }} +{{- end -}} +{{- define "field:payload.v1.Discoverer" -}} +{{ template "_field:payload.v1.Discoverer" }} +{{- end -}} +{{- define "scheme:payload.v1.Discoverer.Request" -}} +{{ template "_scheme:payload.v1.Discoverer.Request" }} +{{- end -}} +{{- define "field:payload.v1.Discoverer.Request" -}} +{{ template "_field:payload.v1.Discoverer.Request" }} +{{- end -}} +{{- define "scheme:payload.v1.Empty" -}} +{{ template "_scheme:payload.v1.Empty" }} +{{- end -}} +{{- define "field:payload.v1.Empty" -}} +{{ template "_field:payload.v1.Empty" }} +{{- end -}} +{{- define "scheme:payload.v1.Filter" -}} +{{ template "_scheme:payload.v1.Filter" }} +{{- end -}} +{{- define "field:payload.v1.Filter" -}} +{{ template "_field:payload.v1.Filter" }} +{{- end -}} +{{- define "scheme:payload.v1.Filter.Config" -}} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Filter.Config" -}} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Filter.Target" -}} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Filter.Target" -}} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Flush" -}} +{{ template "_scheme:payload.v1.Flush" }} +{{- end -}} +{{- define "field:payload.v1.Flush" -}} +{{ template "_field:payload.v1.Flush" }} +{{- end -}} +{{- define "scheme:payload.v1.Flush.Request" -}} +{{ template "_scheme:payload.v1.Flush.Request" }} +{{- end -}} +{{- define "field:payload.v1.Flush.Request" -}} +{{ template "_field:payload.v1.Flush.Request" }} +{{- end -}} +{{- define "scheme:payload.v1.Info" -}} +{{ template "_scheme:payload.v1.Info" }} +{{- end -}} +{{- define "field:payload.v1.Info" -}} +{{ template "_field:payload.v1.Info" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Annotations" -}} +{{ template "_scheme:payload.v1.Info.Annotations" }} +{{ template "_scheme:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Annotations" -}} +{{ template "_field:payload.v1.Info.Annotations" }} +{{ template "_field:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Annotations.AnnotationsEntry" -}} +{{ template "_scheme:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Annotations.AnnotationsEntry" -}} +{{ template "_field:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.CPU" -}} +{{ template "_scheme:payload.v1.Info.CPU" }} +{{- end -}} +{{- define "field:payload.v1.Info.CPU" -}} +{{ template "_field:payload.v1.Info.CPU" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.IPs" -}} +{{ template "_scheme:payload.v1.Info.IPs" }} +{{- end -}} +{{- define "field:payload.v1.Info.IPs" -}} +{{ template "_field:payload.v1.Info.IPs" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index" -}} +{{ template "_scheme:payload.v1.Info.Index" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index" -}} +{{ template "_field:payload.v1.Info.Index" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.Count" -}} +{{ template "_scheme:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.Count" -}} +{{ template "_field:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.Detail" -}} +{{ template "_scheme:payload.v1.Info.Index.Detail" }} +{{ template "_scheme:payload.v1.Info.Index.Detail.CountsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.Detail" -}} +{{ template "_field:payload.v1.Info.Index.Detail" }} +{{ template "_field:payload.v1.Info.Index.Detail.CountsEntry" }} +{{ template "_field:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.Detail.CountsEntry" -}} +{{ template "_scheme:payload.v1.Info.Index.Detail.CountsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.Detail.CountsEntry" -}} +{{ template "_field:payload.v1.Info.Index.Detail.CountsEntry" }} +{{ template "_field:payload.v1.Info.Index.Count" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.Property" -}} +{{ template "_scheme:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.Property" -}} +{{ template "_field:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.PropertyDetail" -}} +{{ template "_scheme:payload.v1.Info.Index.PropertyDetail" }} +{{ template "_scheme:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.PropertyDetail" -}} +{{ template "_field:payload.v1.Info.Index.PropertyDetail" }} +{{ template "_field:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} +{{ template "_field:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.PropertyDetail.DetailsEntry" -}} +{{ template "_scheme:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.PropertyDetail.DetailsEntry" -}} +{{ template "_field:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} +{{ template "_field:payload.v1.Info.Index.Property" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.Statistics" -}} +{{ template "_scheme:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.Statistics" -}} +{{ template "_field:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.StatisticsDetail" -}} +{{ template "_scheme:payload.v1.Info.Index.StatisticsDetail" }} +{{ template "_scheme:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.StatisticsDetail" -}} +{{ template "_field:payload.v1.Info.Index.StatisticsDetail" }} +{{ template "_field:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} +{{ template "_field:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" -}} +{{ template "_scheme:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} +{{ template "_scheme:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" -}} +{{ template "_field:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} +{{ template "_field:payload.v1.Info.Index.Statistics" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.UUID" -}} +{{ template "_scheme:payload.v1.Info.Index.UUID" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.UUID" -}} +{{ template "_field:payload.v1.Info.Index.UUID" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.UUID.Committed" -}} +{{ template "_scheme:payload.v1.Info.Index.UUID.Committed" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.UUID.Committed" -}} +{{ template "_field:payload.v1.Info.Index.UUID.Committed" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Index.UUID.Uncommitted" -}} +{{ template "_scheme:payload.v1.Info.Index.UUID.Uncommitted" }} +{{- end -}} +{{- define "field:payload.v1.Info.Index.UUID.Uncommitted" -}} +{{ template "_field:payload.v1.Info.Index.UUID.Uncommitted" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Labels" -}} +{{ template "_scheme:payload.v1.Info.Labels" }} +{{ template "_scheme:payload.v1.Info.Labels.LabelsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Labels" -}} +{{ template "_field:payload.v1.Info.Labels" }} +{{ template "_field:payload.v1.Info.Labels.LabelsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Labels.LabelsEntry" -}} +{{ template "_scheme:payload.v1.Info.Labels.LabelsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Labels.LabelsEntry" -}} +{{ template "_field:payload.v1.Info.Labels.LabelsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Memory" -}} +{{ template "_scheme:payload.v1.Info.Memory" }} +{{- end -}} +{{- define "field:payload.v1.Info.Memory" -}} +{{ template "_field:payload.v1.Info.Memory" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Node" -}} +{{ template "_scheme:payload.v1.Info.Node" }} +{{ template "_scheme:payload.v1.Info.CPU" }} +{{ template "_scheme:payload.v1.Info.Memory" }} +{{ template "_scheme:payload.v1.Info.Pods" }} +{{ template "_scheme:payload.v1.Info.Pod" }} +{{- end -}} +{{- define "field:payload.v1.Info.Node" -}} +{{ template "_field:payload.v1.Info.Node" }} +{{ template "_field:payload.v1.Info.CPU" }} +{{ template "_field:payload.v1.Info.Memory" }} +{{ template "_field:payload.v1.Info.Pods" }} +{{ template "_field:payload.v1.Info.Pod" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Nodes" -}} +{{ template "_scheme:payload.v1.Info.Nodes" }} +{{ template "_scheme:payload.v1.Info.Node" }} +{{ template "_scheme:payload.v1.Info.CPU" }} +{{ template "_scheme:payload.v1.Info.Memory" }} +{{ template "_scheme:payload.v1.Info.Pods" }} +{{ template "_scheme:payload.v1.Info.Pod" }} +{{- end -}} +{{- define "field:payload.v1.Info.Nodes" -}} +{{ template "_field:payload.v1.Info.Nodes" }} +{{ template "_field:payload.v1.Info.Node" }} +{{ template "_field:payload.v1.Info.CPU" }} +{{ template "_field:payload.v1.Info.Memory" }} +{{ template "_field:payload.v1.Info.Pods" }} +{{ template "_field:payload.v1.Info.Pod" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Pod" -}} +{{ template "_scheme:payload.v1.Info.Pod" }} +{{ template "_scheme:payload.v1.Info.CPU" }} +{{ template "_scheme:payload.v1.Info.Memory" }} +{{ template "_scheme:payload.v1.Info.Node" }} +{{- end -}} +{{- define "field:payload.v1.Info.Pod" -}} +{{ template "_field:payload.v1.Info.Pod" }} +{{ 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" -}} +{{ template "_scheme:payload.v1.Info.Pods" }} +{{ template "_scheme:payload.v1.Info.Pod" }} +{{ template "_scheme:payload.v1.Info.CPU" }} +{{ template "_scheme:payload.v1.Info.Memory" }} +{{ template "_scheme:payload.v1.Info.Node" }} +{{- end -}} +{{- define "field:payload.v1.Info.Pods" -}} +{{ template "_field:payload.v1.Info.Pods" }} +{{ template "_field:payload.v1.Info.Pod" }} +{{ template "_field:payload.v1.Info.CPU" }} +{{ template "_field:payload.v1.Info.Memory" }} +{{ template "_field:payload.v1.Info.Node" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Service" -}} +{{ template "_scheme:payload.v1.Info.Service" }} +{{ template "_scheme:payload.v1.Info.ServicePort" }} +{{ template "_scheme:payload.v1.Info.Labels" }} +{{ template "_scheme:payload.v1.Info.Annotations" }} +{{ template "_scheme:payload.v1.Info.Labels.LabelsEntry" }} +{{ template "_scheme:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Service" -}} +{{ template "_field:payload.v1.Info.Service" }} +{{ template "_field:payload.v1.Info.ServicePort" }} +{{ template "_field:payload.v1.Info.Labels" }} +{{ template "_field:payload.v1.Info.Annotations" }} +{{ template "_field:payload.v1.Info.Labels.LabelsEntry" }} +{{ template "_field:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.ServicePort" -}} +{{ template "_scheme:payload.v1.Info.ServicePort" }} +{{- end -}} +{{- define "field:payload.v1.Info.ServicePort" -}} +{{ template "_field:payload.v1.Info.ServicePort" }} +{{- end -}} +{{- define "scheme:payload.v1.Info.Services" -}} +{{ template "_scheme:payload.v1.Info.Services" }} +{{ template "_scheme:payload.v1.Info.Service" }} +{{ template "_scheme:payload.v1.Info.ServicePort" }} +{{ template "_scheme:payload.v1.Info.Labels" }} +{{ template "_scheme:payload.v1.Info.Annotations" }} +{{ template "_scheme:payload.v1.Info.Labels.LabelsEntry" }} +{{ template "_scheme:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "field:payload.v1.Info.Services" -}} +{{ template "_field:payload.v1.Info.Services" }} +{{ template "_field:payload.v1.Info.Service" }} +{{ template "_field:payload.v1.Info.ServicePort" }} +{{ template "_field:payload.v1.Info.Labels" }} +{{ template "_field:payload.v1.Info.Annotations" }} +{{ template "_field:payload.v1.Info.Labels.LabelsEntry" }} +{{ template "_field:payload.v1.Info.Annotations.AnnotationsEntry" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert" -}} +{{ template "_scheme:payload.v1.Insert" }} +{{- end -}} +{{- define "field:payload.v1.Insert" -}} +{{ template "_field:payload.v1.Insert" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert.Config" -}} +{{ template "_scheme:payload.v1.Insert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Insert.Config" -}} +{{ template "_field:payload.v1.Insert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert.MultiObjectRequest" -}} +{{ template "_scheme:payload.v1.Insert.MultiObjectRequest" }} +{{ template "_scheme:payload.v1.Insert.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Insert.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Insert.MultiObjectRequest" -}} +{{ template "_field:payload.v1.Insert.MultiObjectRequest" }} +{{ template "_field:payload.v1.Insert.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Insert.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert.MultiRequest" -}} +{{ template "_scheme:payload.v1.Insert.MultiRequest" }} +{{ template "_scheme:payload.v1.Insert.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Insert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Insert.MultiRequest" -}} +{{ template "_field:payload.v1.Insert.MultiRequest" }} +{{ template "_field:payload.v1.Insert.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Insert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert.ObjectRequest" -}} +{{ template "_scheme:payload.v1.Insert.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Insert.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Insert.ObjectRequest" -}} +{{ template "_field:payload.v1.Insert.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Insert.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Insert.Request" -}} +{{ template "_scheme:payload.v1.Insert.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Insert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Insert.Request" -}} +{{ template "_field:payload.v1.Insert.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Insert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Meta" -}} +{{ template "_scheme:payload.v1.Meta" }} +{{- end -}} +{{- define "field:payload.v1.Meta" -}} +{{ template "_field:payload.v1.Meta" }} +{{- end -}} +{{- define "scheme:payload.v1.Meta.Key" -}} +{{ template "_scheme:payload.v1.Meta.Key" }} +{{- end -}} +{{- define "field:payload.v1.Meta.Key" -}} +{{ template "_field:payload.v1.Meta.Key" }} +{{- end -}} +{{- define "scheme:payload.v1.Meta.KeyValue" -}} +{{ template "_scheme:payload.v1.Meta.KeyValue" }} +{{ template "_scheme:payload.v1.Meta.Key" }} +{{ template "_scheme:payload.v1.Meta.Value" }} +{{- end -}} +{{- define "field:payload.v1.Meta.KeyValue" -}} +{{ template "_field:payload.v1.Meta.KeyValue" }} +{{ template "_field:payload.v1.Meta.Key" }} +{{ template "_field:payload.v1.Meta.Value" }} +{{- end -}} +{{- define "scheme:payload.v1.Meta.Value" -}} +{{ template "_scheme:payload.v1.Meta.Value" }} +{{- end -}} +{{- define "field:payload.v1.Meta.Value" -}} +{{ template "_field:payload.v1.Meta.Value" }} +{{- end -}} +{{- define "scheme:payload.v1.Mirror" -}} +{{ template "_scheme:payload.v1.Mirror" }} +{{- end -}} +{{- define "field:payload.v1.Mirror" -}} +{{ template "_field:payload.v1.Mirror" }} +{{- end -}} +{{- define "scheme:payload.v1.Mirror.Target" -}} +{{ template "_scheme:payload.v1.Mirror.Target" }} +{{- end -}} +{{- define "field:payload.v1.Mirror.Target" -}} +{{ template "_field:payload.v1.Mirror.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Mirror.Targets" -}} +{{ template "_scheme:payload.v1.Mirror.Targets" }} +{{ template "_scheme:payload.v1.Mirror.Target" }} +{{- end -}} +{{- define "field:payload.v1.Mirror.Targets" -}} +{{ template "_field:payload.v1.Mirror.Targets" }} +{{ template "_field:payload.v1.Mirror.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Object" -}} +{{ template "_scheme:payload.v1.Object" }} +{{- end -}} +{{- define "field:payload.v1.Object" -}} +{{ template "_field:payload.v1.Object" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Blob" -}} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{- end -}} +{{- define "field:payload.v1.Object.Blob" -}} +{{ template "_field:payload.v1.Object.Blob" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Distance" -}} +{{ template "_scheme:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "field:payload.v1.Object.Distance" -}} +{{ template "_field:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.ID" -}} +{{ template "_scheme:payload.v1.Object.ID" }} +{{- end -}} +{{- define "field:payload.v1.Object.ID" -}} +{{ template "_field:payload.v1.Object.ID" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.IDs" -}} +{{ template "_scheme:payload.v1.Object.IDs" }} +{{- end -}} +{{- define "field:payload.v1.Object.IDs" -}} +{{ template "_field:payload.v1.Object.IDs" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.List" -}} +{{ template "_scheme:payload.v1.Object.List" }} +{{- end -}} +{{- define "field:payload.v1.Object.List" -}} +{{ template "_field:payload.v1.Object.List" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.List.Request" -}} +{{ template "_scheme:payload.v1.Object.List.Request" }} +{{- end -}} +{{- define "field:payload.v1.Object.List.Request" -}} +{{ template "_field:payload.v1.Object.List.Request" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.List.Response" -}} +{{ template "_scheme:payload.v1.Object.List.Response" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "field:payload.v1.Object.List.Response" -}} +{{ template "_field:payload.v1.Object.List.Response" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Location" -}} +{{ template "_scheme:payload.v1.Object.Location" }} +{{- end -}} +{{- define "field:payload.v1.Object.Location" -}} +{{ template "_field:payload.v1.Object.Location" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Locations" -}} +{{ template "_scheme:payload.v1.Object.Locations" }} +{{ template "_scheme:payload.v1.Object.Location" }} +{{- end -}} +{{- define "field:payload.v1.Object.Locations" -}} +{{ template "_field:payload.v1.Object.Locations" }} +{{ template "_field:payload.v1.Object.Location" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.ReshapeVector" -}} +{{ template "_scheme:payload.v1.Object.ReshapeVector" }} +{{- end -}} +{{- define "field:payload.v1.Object.ReshapeVector" -}} +{{ template "_field:payload.v1.Object.ReshapeVector" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.StreamBlob" -}} +{{ template "_scheme:payload.v1.Object.StreamBlob" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{- end -}} +{{- define "field:payload.v1.Object.StreamBlob" -}} +{{ template "_field:payload.v1.Object.StreamBlob" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.StreamDistance" -}} +{{ template "_scheme:payload.v1.Object.StreamDistance" }} +{{ template "_scheme:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "field:payload.v1.Object.StreamDistance" -}} +{{ template "_field:payload.v1.Object.StreamDistance" }} +{{ template "_field:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.StreamLocation" -}} +{{ template "_scheme:payload.v1.Object.StreamLocation" }} +{{ template "_scheme:payload.v1.Object.Location" }} +{{- end -}} +{{- define "field:payload.v1.Object.StreamLocation" -}} +{{ template "_field:payload.v1.Object.StreamLocation" }} +{{ template "_field:payload.v1.Object.Location" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.StreamVector" -}} +{{ template "_scheme:payload.v1.Object.StreamVector" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "field:payload.v1.Object.StreamVector" -}} +{{ template "_field:payload.v1.Object.StreamVector" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Timestamp" -}} +{{ template "_scheme:payload.v1.Object.Timestamp" }} +{{- end -}} +{{- define "field:payload.v1.Object.Timestamp" -}} +{{ template "_field:payload.v1.Object.Timestamp" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.TimestampRequest" -}} +{{ template "_scheme:payload.v1.Object.TimestampRequest" }} +{{ template "_scheme:payload.v1.Object.ID" }} +{{- end -}} +{{- define "field:payload.v1.Object.TimestampRequest" -}} +{{ template "_field:payload.v1.Object.TimestampRequest" }} +{{ template "_field:payload.v1.Object.ID" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Vector" -}} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "field:payload.v1.Object.Vector" -}} +{{ template "_field:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.VectorRequest" -}} +{{ template "_scheme:payload.v1.Object.VectorRequest" }} +{{ template "_scheme:payload.v1.Object.ID" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Object.VectorRequest" -}} +{{ template "_field:payload.v1.Object.VectorRequest" }} +{{ template "_field:payload.v1.Object.ID" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Object.Vectors" -}} +{{ template "_scheme:payload.v1.Object.Vectors" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "field:payload.v1.Object.Vectors" -}} +{{ template "_field:payload.v1.Object.Vectors" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove" -}} +{{ template "_scheme:payload.v1.Remove" }} +{{- end -}} +{{- define "field:payload.v1.Remove" -}} +{{ template "_field:payload.v1.Remove" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove.Config" -}} +{{ template "_scheme:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "field:payload.v1.Remove.Config" -}} +{{ template "_field:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove.MultiRequest" -}} +{{ template "_scheme:payload.v1.Remove.MultiRequest" }} +{{ template "_scheme:payload.v1.Remove.Request" }} +{{ template "_scheme:payload.v1.Object.ID" }} +{{ template "_scheme:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "field:payload.v1.Remove.MultiRequest" -}} +{{ template "_field:payload.v1.Remove.MultiRequest" }} +{{ template "_field:payload.v1.Remove.Request" }} +{{ template "_field:payload.v1.Object.ID" }} +{{ template "_field:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove.Request" -}} +{{ template "_scheme:payload.v1.Remove.Request" }} +{{ template "_scheme:payload.v1.Object.ID" }} +{{ template "_scheme:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "field:payload.v1.Remove.Request" -}} +{{ template "_field:payload.v1.Remove.Request" }} +{{ template "_field:payload.v1.Object.ID" }} +{{ template "_field:payload.v1.Remove.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove.Timestamp" -}} +{{ template "_scheme:payload.v1.Remove.Timestamp" }} +{{ template "_scheme:payload.v1.Remove.Timestamp.Operator" }} +{{- end -}} +{{- define "field:payload.v1.Remove.Timestamp" -}} +{{ template "_field:payload.v1.Remove.Timestamp" }} +{{ template "_field:payload.v1.Remove.Timestamp.Operator" }} +{{- end -}} +{{- define "scheme:payload.v1.Remove.TimestampRequest" -}} +{{ template "_scheme:payload.v1.Remove.TimestampRequest" }} +{{ template "_scheme:payload.v1.Remove.Timestamp" }} +{{ template "_scheme:payload.v1.Remove.Timestamp.Operator" }} +{{- end -}} +{{- define "field:payload.v1.Remove.TimestampRequest" -}} +{{ template "_field:payload.v1.Remove.TimestampRequest" }} +{{ template "_field:payload.v1.Remove.Timestamp" }} +{{ template "_field:payload.v1.Remove.Timestamp.Operator" }} +{{- end -}} +{{- define "scheme:payload.v1.Search" -}} +{{ template "_scheme:payload.v1.Search" }} +{{- end -}} +{{- define "field:payload.v1.Search" -}} +{{ template "_field:payload.v1.Search" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.Config" -}} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Search.Config" -}} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.IDRequest" -}} +{{ template "_scheme:payload.v1.Search.IDRequest" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Search.IDRequest" -}} +{{ template "_field:payload.v1.Search.IDRequest" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.MultiIDRequest" -}} +{{ template "_scheme:payload.v1.Search.MultiIDRequest" }} +{{ template "_scheme:payload.v1.Search.IDRequest" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Search.MultiIDRequest" -}} +{{ template "_field:payload.v1.Search.MultiIDRequest" }} +{{ template "_field:payload.v1.Search.IDRequest" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.MultiObjectRequest" -}} +{{ template "_scheme:payload.v1.Search.MultiObjectRequest" }} +{{ template "_scheme:payload.v1.Search.ObjectRequest" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{- end -}} +{{- define "field:payload.v1.Search.MultiObjectRequest" -}} +{{ template "_field:payload.v1.Search.MultiObjectRequest" }} +{{ template "_field:payload.v1.Search.ObjectRequest" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.MultiRequest" -}} +{{ template "_scheme:payload.v1.Search.MultiRequest" }} +{{ template "_scheme:payload.v1.Search.Request" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Search.MultiRequest" -}} +{{ template "_field:payload.v1.Search.MultiRequest" }} +{{ template "_field:payload.v1.Search.Request" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.ObjectRequest" -}} +{{ template "_scheme:payload.v1.Search.ObjectRequest" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{- end -}} +{{- define "field:payload.v1.Search.ObjectRequest" -}} +{{ template "_field:payload.v1.Search.ObjectRequest" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.Request" -}} +{{ template "_scheme:payload.v1.Search.Request" }} +{{ template "_scheme:payload.v1.Search.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Search.Request" -}} +{{ template "_field:payload.v1.Search.Request" }} +{{ template "_field:payload.v1.Search.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Search.AggregationAlgorithm" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.Response" -}} +{{ template "_scheme:payload.v1.Search.Response" }} +{{ template "_scheme:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "field:payload.v1.Search.Response" -}} +{{ template "_field:payload.v1.Search.Response" }} +{{ template "_field:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.Responses" -}} +{{ template "_scheme:payload.v1.Search.Responses" }} +{{ template "_scheme:payload.v1.Search.Response" }} +{{ template "_scheme:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "field:payload.v1.Search.Responses" -}} +{{ template "_field:payload.v1.Search.Responses" }} +{{ template "_field:payload.v1.Search.Response" }} +{{ template "_field:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "scheme:payload.v1.Search.StreamResponse" -}} +{{ template "_scheme:payload.v1.Search.StreamResponse" }} +{{ template "_scheme:payload.v1.Search.Response" }} +{{ template "_scheme:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "field:payload.v1.Search.StreamResponse" -}} +{{ template "_field:payload.v1.Search.StreamResponse" }} +{{ template "_field:payload.v1.Search.Response" }} +{{ template "_field:payload.v1.Object.Distance" }} +{{- end -}} +{{- define "scheme:payload.v1.Update" -}} +{{ template "_scheme:payload.v1.Update" }} +{{- end -}} +{{- define "field:payload.v1.Update" -}} +{{ template "_field:payload.v1.Update" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.Config" -}} +{{ template "_scheme:payload.v1.Update.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Update.Config" -}} +{{ template "_field:payload.v1.Update.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.MultiObjectRequest" -}} +{{ template "_scheme:payload.v1.Update.MultiObjectRequest" }} +{{ template "_scheme:payload.v1.Update.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Update.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Update.MultiObjectRequest" -}} +{{ template "_field:payload.v1.Update.MultiObjectRequest" }} +{{ template "_field:payload.v1.Update.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Update.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.MultiRequest" -}} +{{ template "_scheme:payload.v1.Update.MultiRequest" }} +{{ template "_scheme:payload.v1.Update.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Update.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Update.MultiRequest" -}} +{{ template "_field:payload.v1.Update.MultiRequest" }} +{{ template "_field:payload.v1.Update.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Update.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.ObjectRequest" -}} +{{ template "_scheme:payload.v1.Update.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Update.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Update.ObjectRequest" -}} +{{ template "_field:payload.v1.Update.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Update.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.Request" -}} +{{ template "_scheme:payload.v1.Update.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Update.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Update.Request" -}} +{{ template "_field:payload.v1.Update.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Update.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Update.TimestampRequest" -}} +{{ template "_scheme:payload.v1.Update.TimestampRequest" }} +{{- end -}} +{{- define "field:payload.v1.Update.TimestampRequest" -}} +{{ template "_field:payload.v1.Update.TimestampRequest" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert" -}} +{{ template "_scheme:payload.v1.Upsert" }} +{{- end -}} +{{- define "field:payload.v1.Upsert" -}} +{{ template "_field:payload.v1.Upsert" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert.Config" -}} +{{ template "_scheme:payload.v1.Upsert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Upsert.Config" -}} +{{ template "_field:payload.v1.Upsert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert.MultiObjectRequest" -}} +{{ template "_scheme:payload.v1.Upsert.MultiObjectRequest" }} +{{ template "_scheme:payload.v1.Upsert.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Upsert.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Upsert.MultiObjectRequest" -}} +{{ template "_field:payload.v1.Upsert.MultiObjectRequest" }} +{{ template "_field:payload.v1.Upsert.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Upsert.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert.MultiRequest" -}} +{{ template "_scheme:payload.v1.Upsert.MultiRequest" }} +{{ template "_scheme:payload.v1.Upsert.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Upsert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Upsert.MultiRequest" -}} +{{ template "_field:payload.v1.Upsert.MultiRequest" }} +{{ template "_field:payload.v1.Upsert.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Upsert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert.ObjectRequest" -}} +{{ template "_scheme:payload.v1.Upsert.ObjectRequest" }} +{{ template "_scheme:payload.v1.Object.Blob" }} +{{ template "_scheme:payload.v1.Upsert.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "field:payload.v1.Upsert.ObjectRequest" -}} +{{ template "_field:payload.v1.Upsert.ObjectRequest" }} +{{ template "_field:payload.v1.Object.Blob" }} +{{ template "_field:payload.v1.Upsert.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{- end -}} +{{- define "scheme:payload.v1.Upsert.Request" -}} +{{ template "_scheme:payload.v1.Upsert.Request" }} +{{ template "_scheme:payload.v1.Object.Vector" }} +{{ template "_scheme:payload.v1.Upsert.Config" }} +{{ template "_scheme:payload.v1.Filter.Config" }} +{{ template "_scheme:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "field:payload.v1.Upsert.Request" -}} +{{ template "_field:payload.v1.Upsert.Request" }} +{{ template "_field:payload.v1.Object.Vector" }} +{{ template "_field:payload.v1.Upsert.Config" }} +{{ template "_field:payload.v1.Filter.Config" }} +{{ template "_field:payload.v1.Filter.Target" }} +{{- end -}} +{{- define "_scheme:payload.v1.Control" }} + message Control { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Control" }} + - Control + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Control.CreateIndexRequest" }} + message Control.CreateIndexRequest { + uint32 pool_size = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Control.CreateIndexRequest" }} + - Control.CreateIndexRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | pool_size | uint32 | | The pool size of the create index operation. | +{{- end -}} + +{{- define "_scheme:payload.v1.Discoverer" }} + message Discoverer { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Discoverer" }} + - Discoverer + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Discoverer.Request" }} + message Discoverer.Request { + string name = 1; + string namespace = 2; + string node = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Discoverer.Request" }} + - Discoverer.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | name | string | | The agent name to be discovered. | + | namespace | string | | The namespace to be discovered. | + | node | string | | The node to be discovered. | +{{- end -}} + +{{- define "_scheme:payload.v1.Empty" }} + message Empty { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Empty" }} + - Empty + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Filter" }} + message Filter { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Filter" }} + - Filter + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Filter.Config" }} + message Filter.Config { + repeated Filter.Target targets = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Filter.Config" }} + - Filter.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | +{{- end -}} + +{{- define "_scheme:payload.v1.Filter.Target" }} + message Filter.Target { + string host = 1; + uint32 port = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Filter.Target" }} + - Filter.Target + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | +{{- end -}} + +{{- define "_scheme:payload.v1.Flush" }} + message Flush { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Flush" }} + - Flush + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Flush.Request" }} + message Flush.Request { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Flush.Request" }} + - Flush.Request + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Info" }} + message Info { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Info" }} + - Info + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Annotations" }} + message Info.Annotations { + repeated Info.Annotations.AnnotationsEntry annotations = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Annotations" }} + - Info.Annotations + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | annotations | Info.Annotations.AnnotationsEntry | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Annotations.AnnotationsEntry" }} + message Info.Annotations.AnnotationsEntry { + string key = 1; + string value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Annotations.AnnotationsEntry" }} + - Info.Annotations.AnnotationsEntry + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | + | value | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.CPU" }} + message Info.CPU { + double limit = 1; + double request = 2; + double usage = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.CPU" }} + - Info.CPU + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | limit | double | | The CPU resource limit. | + | request | double | | The CPU resource requested. | + | usage | double | | The CPU usage. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.IPs" }} + message Info.IPs { + repeated string ip = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.IPs" }} + - Info.IPs + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | ip | string | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index" }} + message Info.Index { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index" }} + - Info.Index + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.Count" }} + message Info.Index.Count { + uint32 stored = 1; + uint32 uncommitted = 2; + bool indexing = 3; + bool saving = 4; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.Count" }} + - Info.Index.Count + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.Detail" }} + message Info.Index.Detail { + repeated Info.Index.Detail.CountsEntry counts = 1; + uint32 replica = 2; + uint32 live_agents = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.Detail" }} + - Info.Index.Detail + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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 | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.Detail.CountsEntry" }} + message Info.Index.Detail.CountsEntry { + string key = 1; + Info.Index.Count value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.Detail.CountsEntry" }} + - Info.Index.Detail.CountsEntry + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | + | value | Info.Index.Count | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.Property" }} + message Info.Index.Property { + int32 dimension = 1; + int32 thread_pool_size = 2; + string object_type = 3; + string distance_type = 4; + string index_type = 5; + string database_type = 6; + string object_alignment = 7; + int32 path_adjustment_interval = 8; + int32 graph_shared_memory_size = 9; + int32 tree_shared_memory_size = 10; + int32 object_shared_memory_size = 11; + int32 prefetch_offset = 12; + int32 prefetch_size = 13; + string accuracy_table = 14; + string search_type = 15; + float max_magnitude = 16; + int32 n_of_neighbors_for_insertion_order = 17; + float epsilon_for_insertion_order = 18; + string refinement_object_type = 19; + int32 truncation_threshold = 20; + int32 edge_size_for_creation = 21; + int32 edge_size_for_search = 22; + int32 edge_size_limit_for_creation = 23; + double insertion_radius_coefficient = 24; + int32 seed_size = 25; + string seed_type = 26; + int32 truncation_thread_pool_size = 27; + int32 batch_size_for_creation = 28; + string graph_type = 29; + int32 dynamic_edge_size_base = 30; + int32 dynamic_edge_size_rate = 31; + float build_time_limit = 32; + int32 outgoing_edge = 33; + int32 incoming_edge = 34; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.Property" }} + - Info.Index.Property + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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 | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.PropertyDetail" }} + message Info.Index.PropertyDetail { + repeated Info.Index.PropertyDetail.DetailsEntry details = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.PropertyDetail" }} + - Info.Index.PropertyDetail + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + message Info.Index.PropertyDetail.DetailsEntry { + string key = 1; + Info.Index.Property value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + - Info.Index.PropertyDetail.DetailsEntry + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | + | value | Info.Index.Property | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.Statistics" }} + message Info.Index.Statistics { + bool valid = 1; + int32 median_indegree = 2; + int32 median_outdegree = 3; + uint64 max_number_of_indegree = 4; + uint64 max_number_of_outdegree = 5; + uint64 min_number_of_indegree = 6; + uint64 min_number_of_outdegree = 7; + uint64 mode_indegree = 8; + uint64 mode_outdegree = 9; + uint64 nodes_skipped_for_10_edges = 10; + uint64 nodes_skipped_for_indegree_distance = 11; + uint64 number_of_edges = 12; + uint64 number_of_indexed_objects = 13; + uint64 number_of_nodes = 14; + uint64 number_of_nodes_without_edges = 15; + uint64 number_of_nodes_without_indegree = 16; + uint64 number_of_objects = 17; + uint64 number_of_removed_objects = 18; + uint64 size_of_object_repository = 19; + uint64 size_of_refinement_object_repository = 20; + double variance_of_indegree = 21; + double variance_of_outdegree = 22; + double mean_edge_length = 23; + double mean_edge_length_for_10_edges = 24; + double mean_indegree_distance_for_10_edges = 25; + double mean_number_of_edges_per_node = 26; + double c1_indegree = 27; + double c5_indegree = 28; + double c95_outdegree = 29; + double c99_outdegree = 30; + repeated int64 indegree_count = 31; + repeated uint64 outdegree_histogram = 32; + repeated uint64 indegree_histogram = 33; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.Statistics" }} + - Info.Index.Statistics + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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 | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.StatisticsDetail" }} + message Info.Index.StatisticsDetail { + repeated Info.Index.StatisticsDetail.DetailsEntry details = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.StatisticsDetail" }} + - Info.Index.StatisticsDetail + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + message Info.Index.StatisticsDetail.DetailsEntry { + string key = 1; + Info.Index.Statistics value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + - Info.Index.StatisticsDetail.DetailsEntry + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | + | value | Info.Index.Statistics | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.UUID" }} + message Info.Index.UUID { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.UUID" }} + - Info.Index.UUID + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.UUID.Committed" }} + message Info.Index.UUID.Committed { + string uuid = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.UUID.Committed" }} + - Info.Index.UUID.Committed + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | uuid | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Index.UUID.Uncommitted" }} + message Info.Index.UUID.Uncommitted { + string uuid = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Index.UUID.Uncommitted" }} + - Info.Index.UUID.Uncommitted + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | uuid | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Labels" }} + message Info.Labels { + repeated Info.Labels.LabelsEntry labels = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Labels" }} + - Info.Labels + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | labels | Info.Labels.LabelsEntry | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Labels.LabelsEntry" }} + message Info.Labels.LabelsEntry { + string key = 1; + string value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Labels.LabelsEntry" }} + - Info.Labels.LabelsEntry + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | + | value | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Memory" }} + message Info.Memory { + double limit = 1; + double request = 2; + double usage = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Memory" }} + - Info.Memory + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | limit | double | | The memory limit. | + | request | double | | The memory requested. | + | usage | double | | The memory usage. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Node" }} + message Info.Node { + string name = 1; + string internal_addr = 2; + string external_addr = 3; + Info.CPU cpu = 4; + Info.Memory memory = 5; + Info.Pods Pods = 6; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Node" }} + - Info.Node + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | name | string | | The name of the node. | + | internal_addr | string | | The internal IP address of the node. | + | external_addr | string | | The external IP address of the node. | + | cpu | Info.CPU | | The CPU information of the node. | + | memory | Info.Memory | | The memory information of the node. | + | Pods | Info.Pods | | The pod information of the node. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Nodes" }} + message Info.Nodes { + repeated Info.Node nodes = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Nodes" }} + - Info.Nodes + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | nodes | Info.Node | repeated | The multiple node information. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Pod" }} + message Info.Pod { + string app_name = 1; + string name = 2; + string namespace = 3; + string ip = 4; + Info.CPU cpu = 5; + Info.Memory memory = 6; + Info.Node node = 7; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Pod" }} + - Info.Pod + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | app_name | string | | The app name of the pod on the label. | + | name | string | | The name of the pod. | + | namespace | string | | The namespace of the pod. | + | ip | string | | The IP of the pod. | + | cpu | Info.CPU | | The CPU information of the pod. | + | memory | Info.Memory | | The memory information of the pod. | + | node | Info.Node | | The node information of the pod. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Pods" }} + message Info.Pods { + repeated Info.Pod pods = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Pods" }} + - Info.Pods + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | pods | Info.Pod | repeated | The multiple pod information. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Service" }} + message Info.Service { + string name = 1; + string cluster_ip = 2; + repeated string cluster_ips = 3; + repeated Info.ServicePort ports = 4; + Info.Labels labels = 5; + Info.Annotations annotations = 6; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Service" }} + - Info.Service + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | name | string | | The name of the svc. | + | cluster_ip | string | | The cluster ip of the svc. | + | cluster_ips | string | repeated | The cluster ips of the svc. | + | ports | Info.ServicePort | repeated | The port of the svc. | + | labels | Info.Labels | | The labels of the service. | + | annotations | Info.Annotations | | The annotations of the service. | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.ServicePort" }} + message Info.ServicePort { + string name = 1; + int32 port = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.ServicePort" }} + - Info.ServicePort + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | name | string | | The name of the port. | + | port | int32 | | The port number | +{{- end -}} + +{{- define "_scheme:payload.v1.Info.Services" }} + message Info.Services { + repeated Info.Service services = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Info.Services" }} + - Info.Services + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | services | Info.Service | repeated | The multiple service information. | +{{- end -}} + +{{- define "_scheme:payload.v1.Insert" }} + message Insert { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Insert" }} + - Insert + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Insert.Config" }} + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Insert.Config" }} + - Insert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | +{{- end -}} + +{{- define "_scheme:payload.v1.Insert.MultiObjectRequest" }} + message Insert.MultiObjectRequest { + repeated Insert.ObjectRequest requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Insert.MultiObjectRequest" }} + - Insert.MultiObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Insert.MultiRequest" }} + message Insert.MultiRequest { + repeated Insert.Request requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Insert.MultiRequest" }} + - Insert.MultiRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Insert.Request | repeated | Represent multiple insert request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Insert.ObjectRequest" }} + message Insert.ObjectRequest { + Object.Blob object = 1; + Insert.Config config = 2; + Filter.Target vectorizer = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Insert.ObjectRequest" }} + - Insert.ObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | +{{- end -}} + +{{- define "_scheme:payload.v1.Insert.Request" }} + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Insert.Request" }} + - Insert.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | +{{- end -}} + +{{- define "_scheme:payload.v1.Meta" }} + message Meta { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Meta" }} + - Meta + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Meta.Key" }} + message Meta.Key { + string key = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Meta.Key" }} + - Meta.Key + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Meta.KeyValue" }} + message Meta.KeyValue { + Meta.Key key = 1; + Meta.Value value = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Meta.KeyValue" }} + - Meta.KeyValue + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | key | Meta.Key | | | + | value | Meta.Value | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Meta.Value" }} + message Meta.Value { + google.protobuf.Any value = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Meta.Value" }} + - Meta.Value + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | value | google.protobuf.Any | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Mirror" }} + message Mirror { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Mirror" }} + - Mirror + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Mirror.Target" }} + message Mirror.Target { + string host = 1; + uint32 port = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Mirror.Target" }} + - Mirror.Target + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | +{{- end -}} + +{{- define "_scheme:payload.v1.Mirror.Targets" }} + message Mirror.Targets { + repeated Mirror.Target targets = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Mirror.Targets" }} + - Mirror.Targets + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | targets | Mirror.Target | repeated | The multiple target information. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object" }} + message Object { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Object" }} + - Object + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Blob" }} + message Object.Blob { + string id = 1; + bytes object = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Blob" }} + - Object.Blob + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Distance" }} + message Object.Distance { + string id = 1; + float distance = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Distance" }} + - Object.Distance + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.ID" }} + message Object.ID { + string id = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.ID" }} + - Object.ID + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.IDs" }} + message Object.IDs { + repeated string ids = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.IDs" }} + - Object.IDs + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | ids | string | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.List" }} + message Object.List { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Object.List" }} + - Object.List + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Object.List.Request" }} + message Object.List.Request { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Object.List.Request" }} + - Object.List.Request + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Object.List.Response" }} + message Object.List.Response { + Object.Vector vector = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.List.Response" }} + - Object.List.Response + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | Object.Vector | | The vector | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Location" }} + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Location" }} + - Object.Location + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Locations" }} + message Object.Locations { + repeated Object.Location locations = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Locations" }} + - Object.Locations + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | locations | Object.Location | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.ReshapeVector" }} + message Object.ReshapeVector { + bytes object = 1; + repeated int32 shape = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.ReshapeVector" }} + - Object.ReshapeVector + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | object | bytes | | The binary object. | + | shape | int32 | repeated | The new shape. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.StreamBlob" }} + message Object.StreamBlob { + Object.Blob blob = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.StreamBlob" }} + - Object.StreamBlob + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | blob | Object.Blob | | The binary object. | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.StreamDistance" }} + message Object.StreamDistance { + Object.Distance distance = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.StreamDistance" }} + - Object.StreamDistance + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | distance | Object.Distance | | The distance. | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.StreamLocation" }} + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.StreamLocation" }} + - Object.StreamLocation + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.StreamVector" }} + message Object.StreamVector { + Object.Vector vector = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.StreamVector" }} + - Object.StreamVector + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | Object.Vector | | The vector. | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Timestamp" }} + message Object.Timestamp { + string id = 1; + int64 timestamp = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Timestamp" }} + - Object.Timestamp + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.TimestampRequest" }} + message Object.TimestampRequest { + Object.ID id = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.TimestampRequest" }} + - Object.TimestampRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | Object.ID | | The vector ID to be fetched. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Vector" }} + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Vector" }} + - Object.Vector + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.VectorRequest" }} + message Object.VectorRequest { + Object.ID id = 1; + Filter.Config filters = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.VectorRequest" }} + - Object.VectorRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | +{{- end -}} + +{{- define "_scheme:payload.v1.Object.Vectors" }} + message Object.Vectors { + repeated Object.Vector vectors = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Object.Vectors" }} + - Object.Vectors + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vectors | Object.Vector | repeated | | +{{- end -}} + +{{- define "_scheme:payload.v1.Remove" }} + message Remove { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Remove" }} + - Remove + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Remove.Config" }} + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Remove.Config" }} + - Remove.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | +{{- end -}} + +{{- define "_scheme:payload.v1.Remove.MultiRequest" }} + message Remove.MultiRequest { + repeated Remove.Request requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Remove.MultiRequest" }} + - Remove.MultiRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Remove.Request | repeated | Represent the multiple remove request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Remove.Request" }} + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Remove.Request" }} + - Remove.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | +{{- end -}} + +{{- define "_scheme:payload.v1.Remove.Timestamp" }} + message Remove.Timestamp { + int64 timestamp = 1; + Remove.Timestamp.Operator operator = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Remove.Timestamp" }} + - Remove.Timestamp + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | timestamp | int64 | | The timestamp. | + | operator | Remove.Timestamp.Operator | | The conditional operator. | +{{- end -}} + +{{- define "_scheme:payload.v1.Remove.TimestampRequest" }} + message Remove.TimestampRequest { + repeated Remove.Timestamp timestamps = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Remove.TimestampRequest" }} + - Remove.TimestampRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` +search is applied. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search" }} + message Search { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Search" }} + - Search + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Search.Config" }} + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.Config" }} + - Search.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.IDRequest" }} + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.IDRequest" }} + - Search.IDRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.MultiIDRequest" }} + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.MultiIDRequest" }} + - Search.MultiIDRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.MultiObjectRequest" }} + message Search.MultiObjectRequest { + repeated Search.ObjectRequest requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.MultiObjectRequest" }} + - Search.MultiObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.MultiRequest" }} + message Search.MultiRequest { + repeated Search.Request requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.MultiRequest" }} + - Search.MultiRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Search.Request | repeated | Represent the multiple search request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.ObjectRequest" }} + message Search.ObjectRequest { + bytes object = 1; + Search.Config config = 2; + Filter.Target vectorizer = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.ObjectRequest" }} + - Search.ObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.Request" }} + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.Request" }} + - Search.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.Response" }} + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.Response" }} + - Search.Response + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.Responses" }} + message Search.Responses { + repeated Search.Response responses = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.Responses" }} + - Search.Responses + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Search.StreamResponse" }} + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Search.StreamResponse" }} + - Search.StreamResponse + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update" }} + message Update { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Update" }} + - Update + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Update.Config" }} + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.Config" }} + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update.MultiObjectRequest" }} + message Update.MultiObjectRequest { + repeated Update.ObjectRequest requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.MultiObjectRequest" }} + - Update.MultiObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update.MultiRequest" }} + message Update.MultiRequest { + repeated Update.Request requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.MultiRequest" }} + - Update.MultiRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Update.Request | repeated | Represent the multiple update request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update.ObjectRequest" }} + message Update.ObjectRequest { + Object.Blob object = 1; + Update.Config config = 2; + Filter.Target vectorizer = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.ObjectRequest" }} + - Update.ObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update.Request" }} + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.Request" }} + - Update.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | +{{- end -}} + +{{- define "_scheme:payload.v1.Update.TimestampRequest" }} + message Update.TimestampRequest { + string id = 1; + int64 timestamp = 2; + bool force = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Update.TimestampRequest" }} + - Update.TimestampRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + | force | bool | | force represents forcefully update the timestamp. | +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert" }} + message Upsert { + // empty + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert" }} + - Upsert + + empty +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert.Config" }} + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert.Config" }} + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert.MultiObjectRequest" }} + message Upsert.MultiObjectRequest { + repeated Upsert.ObjectRequest requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert.MultiObjectRequest" }} + - Upsert.MultiObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert.MultiRequest" }} + message Upsert.MultiRequest { + repeated Upsert.Request requests = 1; + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert.MultiRequest" }} + - Upsert.MultiRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert.ObjectRequest" }} + message Upsert.ObjectRequest { + Object.Blob object = 1; + Upsert.Config config = 2; + Filter.Target vectorizer = 3; + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert.ObjectRequest" }} + - Upsert.ObjectRequest + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | +{{- end -}} + +{{- define "_scheme:payload.v1.Upsert.Request" }} + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } +{{- end -}} + +{{- define "_field:payload.v1.Upsert.Request" }} + - Upsert.Request + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | +{{- 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 new file mode 100644 index 0000000000..1735a7cc69 --- /dev/null +++ b/apis/docs/v1/payload.tmpl @@ -0,0 +1,100 @@ +{{- $skip_types := list -}} +{{- range .Scalars -}} + {{- $skip_types = append $skip_types .ProtoType -}} +{{- end -}} + +{{- define "_bfs" -}} + {{- $g := .args.g -}} + {{- $q := .args.q -}} + {{- $v := .args.v -}} + {{- if $q -}} + {{- $head := first $q -}} + {{- if not (has $head $v) -}} + {{- $q = rest $q -}} + {{- range $e := (pluck $head .args.g | first) -}} + {{- $q = append $q $e -}} + {{- end -}} + {{- $v = append $v $head -}} + {{- $_ := set .args "q" $q -}} + {{- $_ := set .args "v" $v -}} + {{- if $q -}} + {{- template "_bfs" . -}} + {{- end -}} + {{- end -}} + {{- end -}} +{{- end -}} + +{{- define "bfs" -}} + {{- $_ := set .args "q" (list .args.start) -}} + {{- $_ := set .args "v" (list) -}} + {{- template "_bfs" . -}} + {{- $visited := list -}} + {{- range .args.v -}} + {{- $visited = append $visited . -}} + {{- end -}} + {{- $_ := set . "visited" $visited -}} +{{- end -}} + +{{- range .Files -}} + {{- $deps := dict -}} + {{- range .Messages -}} + {{- $fields := list -}} + {{- range .Fields -}} + {{- if not (or (has .LongType $skip_types) (hasPrefix "google" .FullType)) -}} + {{- $fields = append $fields .FullType -}} + {{- end -}} + {{- end -}} + {{- $_ := set $deps .FullName (uniq $fields) -}} + {{- end -}} + + {{- range .Messages -}} + {{- with $d := dict "args" (dict "g" $deps "start" .FullName) -}} + {{- template "bfs" $d -}} + {{- printf "{{- define \"scheme:%s\" -}}" $d.args.start -}} + {{- range $d.visited -}} + {{- printf "\n{{ template \"_scheme:%s\" }}" . -}} + {{- end -}} + {{- println "\n{{- end -}}" -}} + {{- printf "{{- define \"field:%s\" -}}" $d.args.start -}} + {{- range $d.visited -}} + {{- printf "\n{{ template \"_field:%s\" }}" . -}} + {{- end -}} + {{- println "\n{{- end -}}" -}} + {{- end -}} + {{- end -}} + + {{- range .Messages -}} + {{ printf "{{- define \"_scheme:%s\" }}" .FullName }} + message {{ .LongName }} { + {{- range $i, $ := .Fields }} + {{ if $.Label }}{{ $.Label }} {{end}}{{ $.LongType }} {{ $.Name }} = {{ add1 $i }}; + {{- else }} + // empty + {{- end }} + } + {{- println "\n{{- end -}}\n" -}} + + {{- printf "{{- define \"_field:%s\" }}\n" .FullName -}} + {{- printf " - %s\n" .LongName -}} + {{- if .HasFields }} + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + {{- range .Fields }} + | {{ .Name }} | {{ .LongType }} | {{.Label }} | {{ .Description }} | + {{- end }} + {{- else }} + empty + {{- 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\" -}}{{- end -}}\n" .FullName -}} + {{- end -}} +{{- end -}} diff --git a/apis/docs/v1/remove.md b/apis/docs/v1/remove.md new file mode 100644 index 0000000000..d2bd05b071 --- /dev/null +++ b/apis/docs/v1/remove.md @@ -0,0 +1,446 @@ +# Vald Remove APIs + +## Overview + +Remove Service is responsible for removing vectors indexed in the `vald-agent`. + +```rpc +service Remove { + + rpc Remove(payload.v1.Remove.Request) returns (payload.v1.Object.Location) {} + rpc RemoveByTimestamp(payload.v1.Remove.TimestampRequest) returns (payload.v1.Object.Locations) {} + rpc StreamRemove(payload.v1.Remove.Request) returns (payload.v1.Object.StreamLocation) {} + rpc MultiRemove(payload.v1.Remove.MultiRequest) returns (payload.v1.Object.Locations) {} + +} +``` + +## Remove RPC + +Remove RPC is the method to remove a single vector. + +### Input + +- the scheme of `payload.v1.Remove.Request` + + ```rpc + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + + message Object.ID { + string id = 1; + } + + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; + } + + ``` + + - Remove.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + + - Remove.Config + + | field | type | label | description | + | :---------------------: | :---- | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## RemoveByTimestamp RPC + +RemoveByTimestamp RPC is the method to remove vectors based on timestamp. + +
+In the TimestampRequest message, the 'timestamps' field is repeated, allowing the inclusion of multiple Timestamp.
+When multiple Timestamps are provided, it results in an `AND` condition, enabling the realization of deletions with specified ranges.
+This design allows for versatile deletion operations, facilitating tasks such as removing data within a specific time range. +
+ +### Input + +- the scheme of `payload.v1.Remove.TimestampRequest` + + ```rpc + message Remove.TimestampRequest { + repeated Remove.Timestamp timestamps = 1; + } + + message Remove.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 | description | + | :---: | :--- | :---- | :---------- | + | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` + + search is applied. | + + - Remove.Timestamp + + | field | type | label | description | + | :-------: | :------------------------ | :---- | :------------------------ | + | timestamp | int64 | | The timestamp. | + | operator | Remove.Timestamp.Operator | | The conditional operator. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 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. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | No vectors in the system match the specified timestamp conditions. | Check whether vectors matching the specified timestamp conditions exist in the system, and fix conditions if needed. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamRemove RPC + +A method to remove multiple indexed vectors by bidirectional streaming. + +StreamRemove RPC is the method to remove multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the remove request can be communicated in any order between client and server. +Each Remove request and response are independent. +It's the recommended method to remove a large number of vectors. + +### Input + +- the scheme of `payload.v1.Remove.Request` + + ```rpc + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + + message Object.ID { + string id = 1; + } + + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; + } + + ``` + + - Remove.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + + - Remove.Config + + | field | type | label | description | + | :---------------------: | :---- | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiRemove RPC + +MultiRemove is the method to remove multiple vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Remove.MultiRequest` + + ```rpc + message Remove.MultiRequest { + repeated Remove.Request requests = 1; + } + + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + + message Object.ID { + string id = 1; + } + + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; + } + + ``` + + - Remove.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :--------------------------------------------- | + | requests | Remove.Request | repeated | Represent the multiple remove request content. | + + - Remove.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + + - Object.ID + + | field | type | label | description | + | :---: | :----- | :---- | :---------- | + | id | string | | | + + - Remove.Config + + | field | type | label | description | + | :---------------------: | :---- | :---- | :-------------------------------------------------- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/apis/docs/v1/search.md b/apis/docs/v1/search.md new file mode 100644 index 0000000000..58d3a267f0 --- /dev/null +++ b/apis/docs/v1/search.md @@ -0,0 +1,1888 @@ +# Vald Search APIs + +## Overview + +Search Service is responsible for searching vectors similar to the user request vector from `vald-agent`. + +```rpc +service Search { + + rpc Search(payload.v1.Search.Request) returns (payload.v1.Search.Response) {} + rpc SearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.Response) {} + rpc StreamSearch(payload.v1.Search.Request) returns (payload.v1.Search.StreamResponse) {} + rpc StreamSearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.StreamResponse) {} + rpc MultiSearch(payload.v1.Search.MultiRequest) returns (payload.v1.Search.Responses) {} + rpc MultiSearchByID(payload.v1.Search.MultiIDRequest) returns (payload.v1.Search.Responses) {} + rpc LinearSearch(payload.v1.Search.Request) returns (payload.v1.Search.Response) {} + rpc LinearSearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.Response) {} + rpc StreamLinearSearch(payload.v1.Search.Request) returns (payload.v1.Search.StreamResponse) {} + rpc StreamLinearSearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.StreamResponse) {} + rpc MultiLinearSearch(payload.v1.Search.MultiRequest) returns (payload.v1.Search.Responses) {} + rpc MultiLinearSearchByID(payload.v1.Search.MultiIDRequest) returns (payload.v1.Search.Responses) {} + +} +``` + +## Search RPC + +Search RPC is the method to search vector(s) similar to the request vector. + +### Input + +- the scheme of `payload.v1.Search.Request` + + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Response` + + ```rpc + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## SearchByID RPC + +SearchByID RPC is the method to search similar vectors using a user-defined vector ID.
+The vector with the same requested ID should be indexed into the `vald-agent` before searching. + +### Input + +- the scheme of `payload.v1.Search.IDRequest` + + ```rpc + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Response` + + ```rpc + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamSearch RPC + +StreamSearch RPC is the method to search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. +Each Search request and response are independent. + +### Input + +- the scheme of `payload.v1.Search.Request` + + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.StreamResponse` + + ```rpc + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.StreamResponse + + | field | type | label | description | + | :------: | :---------------- | :---- | :----------------------------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamSearchByID RPC + +StreamSearchByID RPC is the method to search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. +Each SearchByID request and response are independent. + +### Input + +- the scheme of `payload.v1.Search.IDRequest` + + ```rpc + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.StreamResponse` + + ```rpc + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.StreamResponse + + | field | type | label | description | + | :------: | :---------------- | :---- | :----------------------------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiSearch RPC + +MultiSearch RPC is the method to search vectors with multiple vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Search.MultiRequest` + + ```rpc + message Search.MultiRequest { + repeated Search.Request requests = 1; + } + + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :--------------------------------------------- | + | requests | Search.Request | repeated | Represent the multiple search request content. | + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Responses` + + ```rpc + message Search.Responses { + repeated Search.Response responses = 1; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Responses + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------------------------------------------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiSearchByID RPC + +MultiSearchByID RPC is the method to search vectors with multiple IDs in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Search.MultiIDRequest` + + ```rpc + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } + + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.MultiIDRequest + + | field | type | label | description | + | :------: | :--------------- | :------- | :--------------------------------------------------- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Responses` + + ```rpc + message Search.Responses { + repeated Search.Response responses = 1; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Responses + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------------------------------------------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## LinearSearch RPC + +LinearSearch RPC is the method to linear search vector(s) similar to the request vector. + +### Input + +- the scheme of `payload.v1.Search.Request` + + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Response` + + ```rpc + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## LinearSearchByID RPC + +LinearSearchByID RPC is the method to linear search similar vectors using a user-defined vector ID.
+The vector with the same requested ID should be indexed into the `vald-agent` before searching. +You will get a `NOT_FOUND` error if the vector isn't stored. + +### Input + +- the scheme of `payload.v1.Search.IDRequest` + + ```rpc + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Response` + + ```rpc + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamLinearSearch RPC + +StreamLinearSearch RPC is the method to linear search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. +Each LinearSearch request and response are independent. + +### Input + +- the scheme of `payload.v1.Search.Request` + + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.StreamResponse` + + ```rpc + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.StreamResponse + + | field | type | label | description | + | :------: | :---------------- | :---- | :----------------------------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamLinearSearchByID RPC + +StreamLinearSearchByID RPC is the method to linear search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. +Each LinearSearchByID request and response are independent. + +### Input + +- the scheme of `payload.v1.Search.IDRequest` + + ```rpc + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.StreamResponse` + + ```rpc + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.StreamResponse + + | field | type | label | description | + | :------: | :---------------- | :---- | :----------------------------- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiLinearSearch RPC + +MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Search.MultiRequest` + + ```rpc + message Search.MultiRequest { + repeated Search.Request requests = 1; + } + + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :--------------------------------------------- | + | requests | Search.Request | repeated | Represent the multiple search request content. | + + - Search.Request + + | field | type | label | description | + | :----: | :------------ | :------- | :--------------------------------------- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Responses` + + ```rpc + message Search.Responses { + repeated Search.Response responses = 1; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Responses + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------------------------------------------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiLinearSearchByID RPC + +MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+// + +### Input + +- the scheme of `payload.v1.Search.MultiIDRequest` + + ```rpc + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } + + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + + message Search.Config { + string request_id = 1; + uint32 num = 2; + float radius = 3; + float epsilon = 4; + int64 timeout = 5; + Filter.Config ingress_filters = 6; + Filter.Config egress_filters = 7; + uint32 min_num = 8; + Search.AggregationAlgorithm aggregation_algorithm = 9; + google.protobuf.FloatValue ratio = 10; + uint32 nprobe = 11; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + enum Search.AggregationAlgorithm { + Unknown = 0; + ConcurrentQueue = 1; + SortSlice = 2; + SortPoolSlice = 3; + PairingHeap = 4; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Search.MultiIDRequest + + | field | type | label | description | + | :------: | :--------------- | :------- | :--------------------------------------------------- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + + - Search.IDRequest + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + + - Search.Config + + | field | type | label | description | + | :-------------------: | :-------------------------- | :---- | :------------------------------------------- | + | 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 | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Search.Responses` + + ```rpc + message Search.Responses { + repeated Search.Response responses = 1; + } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + + message Object.Distance { + string id = 1; + float distance = 2; + } + + ``` + + - Search.Responses + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------------------------------------------- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + - Search.Response + + | field | type | label | description | + | :--------: | :-------------- | :------- | :--------------------- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + - Object.Distance + + | field | type | label | description | + | :------: | :----- | :---- | :------------- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | +| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | +| NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/apis/docs/v1/update.md b/apis/docs/v1/update.md new file mode 100644 index 0000000000..4ecee8eb3d --- /dev/null +++ b/apis/docs/v1/update.md @@ -0,0 +1,499 @@ +# Vald Update APIs + +## Overview + +Update Service updates to new vector from inserted vector in the `vald-agent` components. + +```rpc +service Update { + + rpc Update(payload.v1.Update.Request) returns (payload.v1.Object.Location) {} + rpc StreamUpdate(payload.v1.Update.Request) returns (payload.v1.Object.StreamLocation) {} + rpc MultiUpdate(payload.v1.Update.MultiRequest) returns (payload.v1.Object.Locations) {} + rpc UpdateTimestamp(payload.v1.Update.TimestampRequest) returns (payload.v1.Object.Location) {} + +} +``` + +## Update RPC + +Update RPC is the method to update a single vector. + +### Input + +- the scheme of `payload.v1.Update.Request` + + ```rpc + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Update.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamUpdate RPC + +StreamUpdate RPC is the method to update multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. +Each Update request and response are independent. +It's the recommended method to update the large amount of vectors. + +### Input + +- the scheme of `payload.v1.Update.Request` + + ```rpc + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Update.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiUpdate RPC + +MultiUpdate is the method to update multiple vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Update.MultiRequest` + + ```rpc + message Update.MultiRequest { + repeated Update.Request requests = 1; + } + + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Update.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Update.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :--------------------------------------------- | + | requests | Update.Request | repeated | Represent the multiple update request content. | + + - Update.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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. | +| NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | +| ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## UpdateTimestamp RPC + +A method to update timestamp an indexed vector. + +### Input + +- the scheme of `payload.v1.Update.TimestampRequest` + + ```rpc + message Update.TimestampRequest { + string id = 1; + int64 timestamp = 2; + bool force = 3; + } + + ``` + + - Update.TimestampRequest + + | field | type | label | description | + | :-------: | :----- | :---- | :------------------------------------------------ | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + | force | bool | | force represents forcefully update the timestamp. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------- | + +TODO + +Please refer to [Response Status Code](../status.md) for more details. + +### Troubleshooting + +TODO diff --git a/apis/docs/v1/upsert.md b/apis/docs/v1/upsert.md new file mode 100644 index 0000000000..13de9925b2 --- /dev/null +++ b/apis/docs/v1/upsert.md @@ -0,0 +1,436 @@ +# Vald Upsert APIs + +## Overview + +Upsert Service is responsible for updating existing vectors in the `vald-agent` or inserting new vectors into the `vald-agent` if the vector does not exist. + +```rpc +service Upsert { + + rpc Upsert(payload.v1.Upsert.Request) returns (payload.v1.Object.Location) {} + rpc StreamUpsert(payload.v1.Upsert.Request) returns (payload.v1.Object.StreamLocation) {} + rpc MultiUpsert(payload.v1.Upsert.MultiRequest) returns (payload.v1.Object.Locations) {} + +} +``` + +## Upsert RPC + +Upsert RPC is the method to update the inserted vector to a new single vector or add a new single vector if not inserted before. + +### Input + +- the scheme of `payload.v1.Upsert.Request` + + ```rpc + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Upsert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Location` + + ```rpc + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## StreamUpsert RPC + +StreamUpsert RPC is the method to update multiple existing vectors or add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+Using the bidirectional streaming RPC, the upsert request can be communicated in any order between the client and server. +Each Upsert request and response are independent. +It’s the recommended method to upsert a large number of vectors. + +### Input + +- the scheme of `payload.v1.Upsert.Request` + + ```rpc + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Upsert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.StreamLocation` + + ```rpc + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.StreamLocation + + | field | type | label | description | + | :------: | :---------------- | :---- | :-------------------- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | + +## MultiUpsert RPC + +MultiUpsert is the method to update existing multiple vectors and add new multiple vectors in **1** request. + +
+gRPC has a message size limitation.
+Please be careful that the size of the request exceeds the limit. +
+ +### Input + +- the scheme of `payload.v1.Upsert.MultiRequest` + + ```rpc + message Upsert.MultiRequest { + repeated Upsert.Request requests = 1; + } + + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } + + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } + + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + ``` + + - Upsert.MultiRequest + + | field | type | label | description | + | :------: | :------------- | :------- | :--------------------------------------------- | + | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | + + - Upsert.Request + + | field | type | label | description | + | :----: | :------------ | :---- | :--------------------------------------- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + - Object.Vector + + | field | type | label | description | + | :-------: | :----- | :------- | :---------------------------------------------- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config + + | field | type | label | description | + | :---: | :--- | :---- | :---------- | + | 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. | + + - Filter.Config + + | field | type | label | description | + | :-----: | :------------ | :------- | :----------------------------------------- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + - Filter.Target + + | field | type | label | description | + | :---: | :----- | :---- | :------------------- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + +### Output + +- the scheme of `payload.v1.Object.Locations` + + ```rpc + message Object.Locations { + repeated Object.Location locations = 1; + } + + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; + } + + ``` + + - Object.Locations + + | field | type | label | description | + | :-------: | :-------------- | :------- | :---------- | + | locations | Object.Location | repeated | | + + - Object.Location + + | field | type | label | description | + | :---: | :----- | :------- | :------------------------ | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | description | +| :--: | :---------------- | +| 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | +| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/apis/proto/v1/mirror/mirror.proto b/apis/proto/v1/mirror/mirror.proto index 5275ceb2eb..d5059269de 100644 --- a/apis/proto/v1/mirror/mirror.proto +++ b/apis/proto/v1/mirror/mirror.proto @@ -25,9 +25,18 @@ option java_multiple_files = true; option java_outer_classname = "ValdMirror"; option java_package = "org.vdaas.vald.api.v1.mirror"; -// Represent the mirror service. +// Overview +// Mirror Service is responsible for providing the `Register` interface for the Vald Mirror Gateway. service Mirror { - // Register is the RPC to register other mirror servers. + // Overview + // Register RPC is the method to register other Vald Mirror Gateway targets. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 13 | INTERNAL | rpc Register(payload.v1.Mirror.Targets) returns (payload.v1.Mirror.Targets) { option (google.api.http) = { post: "/mirror/register" diff --git a/apis/proto/v1/vald/filter.proto b/apis/proto/v1/vald/filter.proto index e9b95623ec..d3502fe399 100644 --- a/apis/proto/v1/vald/filter.proto +++ b/apis/proto/v1/vald/filter.proto @@ -26,9 +26,21 @@ option java_multiple_files = true; option java_outer_classname = "ValdFilter"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Filter service provides ways to connect to Vald through filter. +// Overview +// Filter Server is responsible for providing insert, update, upsert and search interface for `Vald Filter Gateway`. +// +// Vald Filter Gateway forward user request to user-defined ingress/egress filter components allowing user to run custom logic. service Filter { - // A method to search object. + // Overview + // SearchObject RPC is the method to search object(s) similar to request object. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc SearchObject(payload.v1.Search.ObjectRequest) returns (payload.v1.Search.Response) { option (google.api.http) = { post: "/search/object" @@ -36,7 +48,18 @@ service Filter { }; } - // A method to search multiple objects. + // Overview + // StreamSearchObject RPC is the method to search vectors with multi queries(objects) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // By using the bidirectional streaming RPC, the search request can be communicated in any order between client and server. + // Each Search request and response are independent. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc MultiSearchObject(payload.v1.Search.MultiObjectRequest) returns (payload.v1.Search.Responses) { option (google.api.http) = { post: "/search/object/multiple" @@ -44,10 +67,33 @@ service Filter { }; } - // A method to search object by bidirectional streaming. + // Overview + // MultiSearchObject RPC is the method to search objects with multiple objects in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc StreamSearchObject(stream payload.v1.Search.ObjectRequest) returns (stream payload.v1.Search.StreamResponse) {} - // A method insert object. + // Overview + // InsertObject RPC is the method to insert object through Vald Filter Gateway. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc InsertObject(payload.v1.Insert.ObjectRequest) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/insert/object" @@ -55,10 +101,32 @@ service Filter { }; } - // Represent the streaming RPC to insert object by bidirectional streaming. + // Overview + // StreamInsertObject RPC is the method to add new multiple object using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc). + // + // By using the bidirectional streaming RPC, the insert request can be communicated in any order between client and server. + // Each Insert request and response are independent. + // It's the recommended method to insert a large number of objects. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc StreamInsertObject(stream payload.v1.Insert.ObjectRequest) returns (stream payload.v1.Object.StreamLocation) {} - // A method to insert multiple objects. + // Overview + // MultiInsertObject RPC is the method to add multiple new objects in **1** request. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc MultiInsertObject(payload.v1.Insert.MultiObjectRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/insert/object/multiple" @@ -66,7 +134,16 @@ service Filter { }; } - // A method to update object. + // Overview + // UpdateObject RPC is the method to update a single vector. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc UpdateObject(payload.v1.Update.ObjectRequest) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/update/object" @@ -74,10 +151,37 @@ service Filter { }; } - // A method to update object by bidirectional streaming. + // Overview + // StreamUpdateObject RPC is the method to update multiple objects using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // By using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. + // Each Update request and response are independent. + // It's the recommended method to update the large amount of objects. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc StreamUpdateObject(stream payload.v1.Update.ObjectRequest) returns (stream payload.v1.Object.StreamLocation) {} - // A method to update multiple objects. + // Overview + // MultiUpdateObject is the method to update multiple objects in **1** request. + // + //
+ // gRPC has the message size limitation.
+ // Please be careful that the size of the request exceed the limit. + //
+ // --- + // Status Code + // + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc MultiUpdateObject(payload.v1.Update.MultiObjectRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/update/object/multiple" @@ -85,7 +189,16 @@ service Filter { }; } - // A method to upsert object. + // Overview + // UpsertObject RPC is the method to update a single object and add a new single object. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc UpsertObject(payload.v1.Upsert.ObjectRequest) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/upsert/object" @@ -93,10 +206,33 @@ service Filter { }; } - // A method to upsert object by bidirectional streaming. + // Overview + // UpsertObject RPC is the method to update a single object and add a new single object. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc StreamUpsertObject(stream payload.v1.Upsert.ObjectRequest) returns (stream payload.v1.Object.StreamLocation) {} - // A method to upsert multiple objects. + // Overview + // MultiUpsertObject is the method to update existing multiple objects and add new multiple objects in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 6 | ALREADY_EXISTS | + // | 13 | INTERNAL | rpc MultiUpsertObject(payload.v1.Upsert.MultiObjectRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/upsert/object/multiple" diff --git a/apis/proto/v1/vald/flush.proto b/apis/proto/v1/vald/flush.proto index c745b841a3..c6fc78def5 100644 --- a/apis/proto/v1/vald/flush.proto +++ b/apis/proto/v1/vald/flush.proto @@ -26,9 +26,19 @@ 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. +// Overview +// 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. + // Overview + // Flush RPC is the method to remove all vectors. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 13 | INTERNAL | 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/index.proto b/apis/proto/v1/vald/index.proto index 4360dc9bbb..ae7eb1a145 100644 --- a/apis/proto/v1/vald/index.proto +++ b/apis/proto/v1/vald/index.proto @@ -26,26 +26,34 @@ option java_multiple_files = true; option java_outer_classname = "ValdIndex"; option java_package = "org.vdaas.vald.api.v1.vald"; +// Overview // Represent the index manager service. service Index { + // Overview // Represent the RPC to get the index information. rpc IndexInfo(payload.v1.Empty) returns (payload.v1.Info.Index.Count) { option (google.api.http).get = "/index/info"; } + + // Overview // Represent the RPC to get the index information for each agents. rpc IndexDetail(payload.v1.Empty) returns (payload.v1.Info.Index.Detail) { option (google.api.http).get = "/index/detail"; } + + // Overview // Represent the RPC to get the index statistics. rpc IndexStatistics(payload.v1.Empty) returns (payload.v1.Info.Index.Statistics) { option (google.api.http).get = "/index/statistics"; } + // Overview // Represent the RPC to get the index statistics for each agents. rpc IndexStatisticsDetail(payload.v1.Empty) returns (payload.v1.Info.Index.StatisticsDetail) { option (google.api.http).get = "/index/statistics/detail"; } + // Overview // Represent the RPC to get the index property. rpc IndexProperty(payload.v1.Empty) returns (payload.v1.Info.Index.PropertyDetail) { option (google.api.http).get = "/index/property"; diff --git a/apis/proto/v1/vald/insert.proto b/apis/proto/v1/vald/insert.proto index 6cb99533e5..80e4e86512 100644 --- a/apis/proto/v1/vald/insert.proto +++ b/apis/proto/v1/vald/insert.proto @@ -26,9 +26,32 @@ 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 + // | 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 +59,64 @@ 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 + // | 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 + // | 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" diff --git a/apis/proto/v1/vald/object.proto b/apis/proto/v1/vald/object.proto index 73e5723381..7805c5eb7d 100644 --- a/apis/proto/v1/vald/object.proto +++ b/apis/proto/v1/vald/object.proto @@ -26,27 +26,110 @@ option java_multiple_files = true; option java_outer_classname = "ValdObject"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Object service provides ways to fetch indexed vectors. +// Overview +// Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent`. service Object { - // A method to check whether a specified ID is indexed or not. + // Overview + // Exists RPC is the method to check that a vector exists in the `vald-agent`. + // --- + // Status Code + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc Exists(payload.v1.Object.ID) returns (payload.v1.Object.ID) { option (google.api.http).get = "/exists/{id}"; } - // A method to fetch a vector. + // Overview + // GetObject RPC is the method to get the metadata of a vector inserted into the `vald-agent`. + // --- + // Status Code + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc GetObject(payload.v1.Object.VectorRequest) returns (payload.v1.Object.Vector) { option (google.api.http).get = "/object/{id.id}"; } - // A method to fetch vectors by bidirectional streaming. + // Overview + // StreamGetObject RPC is the method to get the metadata of multiple existing vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the GetObject request can be communicated in any order between client and server. + // Each Upsert request and response are independent. + // --- + // Status Code + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamGetObject(stream payload.v1.Object.VectorRequest) returns (stream payload.v1.Object.StreamVector) {} + // Overview // A method to get all the vectors with server streaming + // --- + // Status Code + // TODO + // --- + // Troubleshooting + // TODO rpc StreamListObject(payload.v1.Object.List.Request) returns (stream payload.v1.Object.List.Response) { option (google.api.http).get = "/object/list"; } + // Overview // Represent the RPC to get the vector metadata. This RPC is mainly used for index correction process + // --- + // Status Code + // TODO + // --- + // Troubleshooting + // TODO rpc GetTimestamp(payload.v1.Object.TimestampRequest) returns (payload.v1.Object.Timestamp) { option (google.api.http).get = "/object/meta/{id.id}"; } diff --git a/apis/proto/v1/vald/remove.proto b/apis/proto/v1/vald/remove.proto index 54ce8d35e1..a2bbf6eace 100644 --- a/apis/proto/v1/vald/remove.proto +++ b/apis/proto/v1/vald/remove.proto @@ -26,9 +26,33 @@ option java_multiple_files = true; option java_outer_classname = "ValdRemove"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Remove service provides ways to remove indexed vectors. +// Overview +// Remove Service is responsible for removing vectors indexed in the `vald-agent`. service Remove { - // A method to remove an indexed vector. + // Overview + // Remove RPC is the method to remove a single vector. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc Remove(payload.v1.Remove.Request) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/remove" @@ -36,7 +60,33 @@ service Remove { }; } - // A method to remove an indexed vector based on timestamp. + // Overview + // RemoveByTimestamp RPC is the method to remove vectors based on timestamp. + // + //
+ // In the TimestampRequest message, the 'timestamps' field is repeated, allowing the inclusion of multiple Timestamp.
+ // When multiple Timestamps are provided, it results in an `AND` condition, enabling the realization of deletions with specified ranges.
+ // This design allows for versatile deletion operations, facilitating tasks such as removing data within a specific time range. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 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. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | No vectors in the system match the specified timestamp conditions. | Check whether vectors matching the specified timestamp conditions exist in the system, and fix conditions if needed. | + // | 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 RemoveByTimestamp(payload.v1.Remove.TimestampRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/remove/timestamp" @@ -44,10 +94,66 @@ service Remove { }; } + // Overview // A method to remove multiple indexed vectors by bidirectional streaming. + // + // StreamRemove RPC is the method to remove multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the remove request can be communicated in any order between client and server. + // Each Remove request and response are independent. + // It's the recommended method to remove a large number of vectors. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamRemove(stream payload.v1.Remove.Request) returns (stream payload.v1.Object.StreamLocation) {} - // A method to remove multiple indexed vectors in a single request. + // Overview + // MultiRemove is the method to remove multiple vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiRemove(payload.v1.Remove.MultiRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/remove/multiple" diff --git a/apis/proto/v1/vald/search.proto b/apis/proto/v1/vald/search.proto index bc5d348c51..ef1b276619 100644 --- a/apis/proto/v1/vald/search.proto +++ b/apis/proto/v1/vald/search.proto @@ -26,9 +26,33 @@ option java_multiple_files = true; option java_outer_classname = "ValdSearch"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Search service provides ways to search indexed vectors. +// Overview +// Search Service is responsible for searching vectors similar to the user request vector from `vald-agent`. service Search { - // A method to search indexed vectors by a raw vector. + // Overview + // Search RPC is the method to search vector(s) similar to the request vector. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc Search(payload.v1.Search.Request) returns (payload.v1.Search.Response) { option (google.api.http) = { post: "/search" @@ -36,7 +60,31 @@ service Search { }; } - // A method to search indexed vectors by ID. + // Overview + // SearchByID RPC is the method to search similar vectors using a user-defined vector ID.
+ // The vector with the same requested ID should be indexed into the `vald-agent` before searching. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc SearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.Response) { option (google.api.http) = { post: "/search/id" @@ -44,13 +92,91 @@ service Search { }; } - // A method to search indexed vectors by multiple vectors. + // Overview + // StreamSearch RPC is the method to search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. + // Each Search request and response are independent. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamSearch(stream payload.v1.Search.Request) returns (stream payload.v1.Search.StreamResponse) {} - // A method to search indexed vectors by multiple IDs. + // Overview + // StreamSearchByID RPC is the method to search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. + // Each SearchByID request and response are independent. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamSearchByID(stream payload.v1.Search.IDRequest) returns (stream payload.v1.Search.StreamResponse) {} - // A method to search indexed vectors by multiple vectors in a single request. + // Overview + // MultiSearch RPC is the method to search vectors with multiple vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiSearch(payload.v1.Search.MultiRequest) returns (payload.v1.Search.Responses) { option (google.api.http) = { post: "/search/multiple" @@ -58,7 +184,35 @@ service Search { }; } - // A method to search indexed vectors by multiple IDs in a single request. + // Overview + // MultiSearchByID RPC is the method to search vectors with multiple IDs in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiSearchByID(payload.v1.Search.MultiIDRequest) returns (payload.v1.Search.Responses) { option (google.api.http) = { post: "/search/id/multiple" @@ -66,7 +220,30 @@ service Search { }; } - // A method to linear search indexed vectors by a raw vector. + // Overview + // LinearSearch RPC is the method to linear search vector(s) similar to the request vector. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc LinearSearch(payload.v1.Search.Request) returns (payload.v1.Search.Response) { option (google.api.http) = { post: "/linearsearch" @@ -74,7 +251,32 @@ service Search { }; } - // A method to linear search indexed vectors by ID. + // Overview + // LinearSearchByID RPC is the method to linear search similar vectors using a user-defined vector ID.
+ // The vector with the same requested ID should be indexed into the `vald-agent` before searching. + // You will get a `NOT_FOUND` error if the vector isn't stored. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc LinearSearchByID(payload.v1.Search.IDRequest) returns (payload.v1.Search.Response) { option (google.api.http) = { post: "/linearsearch/id" @@ -82,14 +284,91 @@ service Search { }; } - // A method to linear search indexed vectors by multiple vectors. + // Overview + // StreamLinearSearch RPC is the method to linear search vectors with multi queries(vectors) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. + // Each LinearSearch request and response are independent. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamLinearSearch(stream payload.v1.Search.Request) returns (stream payload.v1.Search.StreamResponse) {} - // A method to linear search indexed vectors by multiple IDs. + // Overview + // StreamLinearSearchByID RPC is the method to linear search vectors with multi queries(IDs) using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. + // Each LinearSearchByID request and response are independent. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamLinearSearchByID(stream payload.v1.Search.IDRequest) returns (stream payload.v1.Search.StreamResponse) {} - // A method to linear search indexed vectors by multiple vectors in a single - // request. + // Overview + // MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | Search result is empty or insufficient to request result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiLinearSearch(payload.v1.Search.MultiRequest) returns (payload.v1.Search.Responses) { option (google.api.http) = { post: "/linearsearch/multiple" @@ -97,8 +376,35 @@ service Search { }; } - // A method to linear search indexed vectors by multiple IDs in a single - // request. + // Overview + // MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 Requested vector's ID is empty, or some request payload is invalid. | Check request payload and fix request payload. | + // | DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | + // | NOT_FOUND | The Requested ID is not inserted on the target Vald cluster, or the search result is insufficient to the required result length. | Send a request with another vector or set min_num to a smaller value. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiLinearSearchByID(payload.v1.Search.MultiIDRequest) returns (payload.v1.Search.Responses) { option (google.api.http) = { post: "/linearsearch/id/multiple" diff --git a/apis/proto/v1/vald/update.proto b/apis/proto/v1/vald/update.proto index f2e9598a9d..f67b57b215 100644 --- a/apis/proto/v1/vald/update.proto +++ b/apis/proto/v1/vald/update.proto @@ -26,9 +26,35 @@ option java_multiple_files = true; option java_outer_classname = "ValdUpdate"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Update service provides ways to update indexed vectors. +// Overview +// Update Service updates to new vector from inserted vector in the `vald-agent` components. service Update { - // A method to update an indexed vector. + // Overview + // Update RPC is the method to update a single vector. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc Update(payload.v1.Update.Request) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/update" @@ -36,10 +62,68 @@ service Update { }; } - // A method to update multiple indexed vectors by bidirectional streaming. + // Overview + // StreamUpdate RPC is the method to update multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the update request can be communicated in any order between client and server. + // Each Update request and response are independent. + // It's the recommended method to update the large amount of vectors. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamUpdate(stream payload.v1.Update.Request) returns (stream payload.v1.Object.StreamLocation) {} - // A method to update multiple indexed vectors in a single request. + // Overview + // MultiUpdate is the method to update multiple vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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. | + // | NOT_FOUND | Requested ID is NOT inserted. | Send a request with an ID that is already inserted. | + // | ALREADY_EXISTS | Request pair of ID and vector is already inserted. | Change request ID. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiUpdate(payload.v1.Update.MultiRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/update/multiple" @@ -47,7 +131,14 @@ service Update { }; } + // Overview // A method to update timestamp an indexed vector. + // --- + // Status Code + // TODO + // --- + // Troubleshooting + // TODO rpc UpdateTimestamp(payload.v1.Update.TimestampRequest) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/update/timestamp" diff --git a/apis/proto/v1/vald/upsert.proto b/apis/proto/v1/vald/upsert.proto index 7f779b9c03..0038277d51 100644 --- a/apis/proto/v1/vald/upsert.proto +++ b/apis/proto/v1/vald/upsert.proto @@ -26,9 +26,34 @@ option java_multiple_files = true; option java_outer_classname = "ValdUpsert"; option java_package = "org.vdaas.vald.api.v1.vald"; -// Upsert service provides ways to insert/update vectors. +// Overview +// Upsert Service is responsible for updating existing vectors in the `vald-agent` or inserting new vectors into the `vald-agent` if the vector does not exist. service Upsert { - // A method to insert/update a vector. + // Overview + // Upsert RPC is the method to update the inserted vector to a new single vector or add a new single vector if not inserted before. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc Upsert(payload.v1.Upsert.Request) returns (payload.v1.Object.Location) { option (google.api.http) = { post: "/upsert" @@ -36,10 +61,66 @@ service Upsert { }; } - // A method to insert/update multiple vectors by bidirectional streaming. + // Overview + // StreamUpsert RPC is the method to update multiple existing vectors or add new multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
+ // Using the bidirectional streaming RPC, the upsert request can be communicated in any order between the client and server. + // Each Upsert request and response are independent. + // It’s the recommended method to upsert a large number of vectors. + // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc StreamUpsert(stream payload.v1.Upsert.Request) returns (stream payload.v1.Object.StreamLocation) {} - // A method to insert/update multiple vectors in a single request. + // Overview + // MultiUpsert is the method to update existing multiple vectors and add new multiple vectors in **1** request. + // + //
+ // gRPC has a message size limitation.
+ // Please be careful that the size of the request exceeds the limit. + //
+ // --- + // Status Code + // | 0 | OK | + // | 1 | CANCELLED | + // | 3 | INVALID_ARGUMENT | + // | 4 | DEADLINE_EXCEEDED | + // | 5 | NOT_FOUND | + // | 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 | Requested pair of ID and vector is already inserted | Change request payload or nothing to do if update is unnecessary. | + // | INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | rpc MultiUpsert(payload.v1.Upsert.MultiRequest) returns (payload.v1.Object.Locations) { option (google.api.http) = { post: "/upsert/multiple"