diff --git a/Makefile.d/proto.mk b/Makefile.d/proto.mk index 9db5951ffb..d93232d80e 100644 --- a/Makefile.d/proto.mk +++ b/Makefile.d/proto.mk @@ -64,14 +64,25 @@ proto/gen/code: \ buf generate make proto/replace -proto/gen/api/docs: $(PROTO_API_DOCS) +proto/gen/api/docs: \ + proto/gen/api/docs/payload \ + $(PROTO_API_DOCS) -$(ROOTDIR)/apis/docs/v1/%.md: $(ROOTDIR)/apis/proto/v1/vald/%.proto +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 --path apis/proto/v1/payload/payload.proto + +$(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...") - buf generate --template=buf.gen.doc.yaml --path $(subst $(ROOTDIR)/,,$<) + buf generate --template=apis/docs/buf.gen.tmpl.yaml --path $(subst $(ROOTDIR)/,,$<) + cat apis/docs/v1/payload.md.tmpl apis/docs/v1/_doc.md.tmpl > apis/docs/v1/doc.md.tmpl + @sleep 1 + buf generate --template=apis/docs/buf.gen.doc.yaml @sleep 1 - mv $(ROOTDIR)/apis/docs/v1/vald/tmp.md $@ - rmdir $(ROOTDIR)/apis/docs/v1/vald + mv $(ROOTDIR)/apis/docs/v1/doc.md $@ + rm apis/docs/v1/*doc.md.tmpl 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" diff --git a/buf.gen.doc.yaml b/apis/docs/buf.gen.doc.yaml similarity index 91% rename from buf.gen.doc.yaml rename to apis/docs/buf.gen.doc.yaml index e5f1739e8b..ccbec0497b 100644 --- a/buf.gen.doc.yaml +++ b/apis/docs/buf.gen.doc.yaml @@ -23,5 +23,5 @@ managed: value: github.com/vdaas/vald/apis/grpc plugins: - local: protoc-gen-doc - out: apis/docs - opt: apis/docs/v1/docs.md.tmpl,tmp.md,source_relative + 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..5d37757323 --- /dev/null +++ b/apis/docs/buf.gen.payload.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/payload.tmpl,payload.md.tmpl 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..eee7c0504d --- /dev/null +++ b/apis/docs/v1/doc.tmpl @@ -0,0 +1,53 @@ +{{ range .Files -}} +{{ range .Services -}} +# Vald {{ .Name }} APIs + +## Overview + +{{.Description}} + +```rpc +service {{.Name}} { + +{{ range .Methods }} rpc {{ .Name }}({{ .RequestFullType }}) returns ({{ .ResponseFullType }}) {} +{{ end }} +} +``` + +{{ range .Methods -}} +## {{ .Name }} RPC + +{{ .Description }} + +### Input + +- the scheme of `{{ .RequestFullType }}` + + ```rpc +{{ printf "{{- template \"scheme.%s\" }}" .RequestFullType }} + ``` +{{ printf "{{ template \"field.%s\" }}" .RequestFullType }} + +### Output + +- the scheme of `{{ .ResponseFullType }}` + + ```rpc +{{ printf "{{- template \"scheme.%s\" }}" .ResponseFullType }} + ``` +{{ printf "{{ template \"field.%s\" }}" .ResponseFullType }} + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +{{ end -}} +{{- end -}} +{{- end -}} diff --git a/apis/docs/v1/docs.md b/apis/docs/v1/docs.md index e0a8cde5e7..5d27307831 100644 --- a/apis/docs/v1/docs.md +++ b/apis/docs/v1/docs.md @@ -1,1377 +1,1977 @@ # Protocol Documentation - ## Table of Contents - [v1/payload/payload.proto](#v1_payload_payload-proto) - - - [Control](#payload-v1-Control) - - [Control.CreateIndexRequest](#payload-v1-Control-CreateIndexRequest) - - [Discoverer](#payload-v1-Discoverer) - - [Discoverer.Request](#payload-v1-Discoverer-Request) - - [Empty](#payload-v1-Empty) - - [Filter](#payload-v1-Filter) - - [Filter.Config](#payload-v1-Filter-Config) - - [Filter.Target](#payload-v1-Filter-Target) - - [Flush](#payload-v1-Flush) - - [Flush.Request](#payload-v1-Flush-Request) - - [Info](#payload-v1-Info) - - [Info.Annotations](#payload-v1-Info-Annotations) - - [Info.Annotations.AnnotationsEntry](#payload-v1-Info-Annotations-AnnotationsEntry) - - [Info.CPU](#payload-v1-Info-CPU) - - [Info.IPs](#payload-v1-Info-IPs) - - [Info.Index](#payload-v1-Info-Index) - - [Info.Index.Count](#payload-v1-Info-Index-Count) - - [Info.Index.Detail](#payload-v1-Info-Index-Detail) - - [Info.Index.Detail.CountsEntry](#payload-v1-Info-Index-Detail-CountsEntry) - - [Info.Index.Property](#payload-v1-Info-Index-Property) - - [Info.Index.PropertyDetail](#payload-v1-Info-Index-PropertyDetail) - - [Info.Index.PropertyDetail.DetailsEntry](#payload-v1-Info-Index-PropertyDetail-DetailsEntry) - - [Info.Index.Statistics](#payload-v1-Info-Index-Statistics) - - [Info.Index.StatisticsDetail](#payload-v1-Info-Index-StatisticsDetail) - - [Info.Index.StatisticsDetail.DetailsEntry](#payload-v1-Info-Index-StatisticsDetail-DetailsEntry) - - [Info.Index.UUID](#payload-v1-Info-Index-UUID) - - [Info.Index.UUID.Committed](#payload-v1-Info-Index-UUID-Committed) - - [Info.Index.UUID.Uncommitted](#payload-v1-Info-Index-UUID-Uncommitted) - - [Info.Labels](#payload-v1-Info-Labels) - - [Info.Labels.LabelsEntry](#payload-v1-Info-Labels-LabelsEntry) - - [Info.Memory](#payload-v1-Info-Memory) - - [Info.Node](#payload-v1-Info-Node) - - [Info.Nodes](#payload-v1-Info-Nodes) - - [Info.Pod](#payload-v1-Info-Pod) - - [Info.Pods](#payload-v1-Info-Pods) - - [Info.Service](#payload-v1-Info-Service) - - [Info.ServicePort](#payload-v1-Info-ServicePort) - - [Info.Services](#payload-v1-Info-Services) - - [Insert](#payload-v1-Insert) - - [Insert.Config](#payload-v1-Insert-Config) - - [Insert.MultiObjectRequest](#payload-v1-Insert-MultiObjectRequest) - - [Insert.MultiRequest](#payload-v1-Insert-MultiRequest) - - [Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) - - [Insert.Request](#payload-v1-Insert-Request) - - [Meta](#payload-v1-Meta) - - [Meta.Key](#payload-v1-Meta-Key) - - [Meta.KeyValue](#payload-v1-Meta-KeyValue) - - [Meta.Value](#payload-v1-Meta-Value) - - [Mirror](#payload-v1-Mirror) - - [Mirror.Target](#payload-v1-Mirror-Target) - - [Mirror.Targets](#payload-v1-Mirror-Targets) - - [Object](#payload-v1-Object) - - [Object.Blob](#payload-v1-Object-Blob) - - [Object.Distance](#payload-v1-Object-Distance) - - [Object.ID](#payload-v1-Object-ID) - - [Object.IDs](#payload-v1-Object-IDs) - - [Object.List](#payload-v1-Object-List) - - [Object.List.Request](#payload-v1-Object-List-Request) - - [Object.List.Response](#payload-v1-Object-List-Response) - - [Object.Location](#payload-v1-Object-Location) - - [Object.Locations](#payload-v1-Object-Locations) - - [Object.ReshapeVector](#payload-v1-Object-ReshapeVector) - - [Object.StreamBlob](#payload-v1-Object-StreamBlob) - - [Object.StreamDistance](#payload-v1-Object-StreamDistance) - - [Object.StreamLocation](#payload-v1-Object-StreamLocation) - - [Object.StreamVector](#payload-v1-Object-StreamVector) - - [Object.Timestamp](#payload-v1-Object-Timestamp) - - [Object.TimestampRequest](#payload-v1-Object-TimestampRequest) - - [Object.Vector](#payload-v1-Object-Vector) - - [Object.VectorRequest](#payload-v1-Object-VectorRequest) - - [Object.Vectors](#payload-v1-Object-Vectors) - - [Remove](#payload-v1-Remove) - - [Remove.Config](#payload-v1-Remove-Config) - - [Remove.MultiRequest](#payload-v1-Remove-MultiRequest) - - [Remove.Request](#payload-v1-Remove-Request) - - [Remove.Timestamp](#payload-v1-Remove-Timestamp) - - [Remove.TimestampRequest](#payload-v1-Remove-TimestampRequest) - - [Search](#payload-v1-Search) - - [Search.Config](#payload-v1-Search-Config) - - [Search.IDRequest](#payload-v1-Search-IDRequest) - - [Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) - - [Search.MultiObjectRequest](#payload-v1-Search-MultiObjectRequest) - - [Search.MultiRequest](#payload-v1-Search-MultiRequest) - - [Search.ObjectRequest](#payload-v1-Search-ObjectRequest) - - [Search.Request](#payload-v1-Search-Request) - - [Search.Response](#payload-v1-Search-Response) - - [Search.Responses](#payload-v1-Search-Responses) - - [Search.StreamResponse](#payload-v1-Search-StreamResponse) - - [Update](#payload-v1-Update) - - [Update.Config](#payload-v1-Update-Config) - - [Update.MultiObjectRequest](#payload-v1-Update-MultiObjectRequest) - - [Update.MultiRequest](#payload-v1-Update-MultiRequest) - - [Update.ObjectRequest](#payload-v1-Update-ObjectRequest) - - [Update.Request](#payload-v1-Update-Request) - - [Update.TimestampRequest](#payload-v1-Update-TimestampRequest) - - [Upsert](#payload-v1-Upsert) - - [Upsert.Config](#payload-v1-Upsert-Config) - - [Upsert.MultiObjectRequest](#payload-v1-Upsert-MultiObjectRequest) - - [Upsert.MultiRequest](#payload-v1-Upsert-MultiRequest) - - [Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) - - [Upsert.Request](#payload-v1-Upsert-Request) - - [Remove.Timestamp.Operator](#payload-v1-Remove-Timestamp-Operator) - - [Search.AggregationAlgorithm](#payload-v1-Search-AggregationAlgorithm) - + - [Control](#payload-v1-Control) + - [Control.CreateIndexRequest](#payload-v1-Control-CreateIndexRequest) + - [Discoverer](#payload-v1-Discoverer) + - [Discoverer.Request](#payload-v1-Discoverer-Request) + - [Empty](#payload-v1-Empty) + - [Filter](#payload-v1-Filter) + - [Filter.Config](#payload-v1-Filter-Config) + - [Filter.Target](#payload-v1-Filter-Target) + - [Flush](#payload-v1-Flush) + - [Flush.Request](#payload-v1-Flush-Request) + - [Info](#payload-v1-Info) + - [Info.Annotations](#payload-v1-Info-Annotations) + - [Info.Annotations.AnnotationsEntry](#payload-v1-Info-Annotations-AnnotationsEntry) + - [Info.CPU](#payload-v1-Info-CPU) + - [Info.IPs](#payload-v1-Info-IPs) + - [Info.Index](#payload-v1-Info-Index) + - [Info.Index.Count](#payload-v1-Info-Index-Count) + - [Info.Index.Detail](#payload-v1-Info-Index-Detail) + - [Info.Index.Detail.CountsEntry](#payload-v1-Info-Index-Detail-CountsEntry) + - [Info.Index.Property](#payload-v1-Info-Index-Property) + - [Info.Index.PropertyDetail](#payload-v1-Info-Index-PropertyDetail) + - [Info.Index.PropertyDetail.DetailsEntry](#payload-v1-Info-Index-PropertyDetail-DetailsEntry) + - [Info.Index.Statistics](#payload-v1-Info-Index-Statistics) + - [Info.Index.StatisticsDetail](#payload-v1-Info-Index-StatisticsDetail) + - [Info.Index.StatisticsDetail.DetailsEntry](#payload-v1-Info-Index-StatisticsDetail-DetailsEntry) + - [Info.Index.UUID](#payload-v1-Info-Index-UUID) + - [Info.Index.UUID.Committed](#payload-v1-Info-Index-UUID-Committed) + - [Info.Index.UUID.Uncommitted](#payload-v1-Info-Index-UUID-Uncommitted) + - [Info.Labels](#payload-v1-Info-Labels) + - [Info.Labels.LabelsEntry](#payload-v1-Info-Labels-LabelsEntry) + - [Info.Memory](#payload-v1-Info-Memory) + - [Info.Node](#payload-v1-Info-Node) + - [Info.Nodes](#payload-v1-Info-Nodes) + - [Info.Pod](#payload-v1-Info-Pod) + - [Info.Pods](#payload-v1-Info-Pods) + - [Info.Service](#payload-v1-Info-Service) + - [Info.ServicePort](#payload-v1-Info-ServicePort) + - [Info.Services](#payload-v1-Info-Services) + - [Insert](#payload-v1-Insert) + - [Insert.Config](#payload-v1-Insert-Config) + - [Insert.MultiObjectRequest](#payload-v1-Insert-MultiObjectRequest) + - [Insert.MultiRequest](#payload-v1-Insert-MultiRequest) + - [Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) + - [Insert.Request](#payload-v1-Insert-Request) + - [Meta](#payload-v1-Meta) + - [Meta.Key](#payload-v1-Meta-Key) + - [Meta.KeyValue](#payload-v1-Meta-KeyValue) + - [Meta.Value](#payload-v1-Meta-Value) + - [Mirror](#payload-v1-Mirror) + - [Mirror.Target](#payload-v1-Mirror-Target) + - [Mirror.Targets](#payload-v1-Mirror-Targets) + - [Object](#payload-v1-Object) + - [Object.Blob](#payload-v1-Object-Blob) + - [Object.Distance](#payload-v1-Object-Distance) + - [Object.ID](#payload-v1-Object-ID) + - [Object.IDs](#payload-v1-Object-IDs) + - [Object.List](#payload-v1-Object-List) + - [Object.List.Request](#payload-v1-Object-List-Request) + - [Object.List.Response](#payload-v1-Object-List-Response) + - [Object.Location](#payload-v1-Object-Location) + - [Object.Locations](#payload-v1-Object-Locations) + - [Object.ReshapeVector](#payload-v1-Object-ReshapeVector) + - [Object.StreamBlob](#payload-v1-Object-StreamBlob) + - [Object.StreamDistance](#payload-v1-Object-StreamDistance) + - [Object.StreamLocation](#payload-v1-Object-StreamLocation) + - [Object.StreamVector](#payload-v1-Object-StreamVector) + - [Object.Timestamp](#payload-v1-Object-Timestamp) + - [Object.TimestampRequest](#payload-v1-Object-TimestampRequest) + - [Object.Vector](#payload-v1-Object-Vector) + - [Object.VectorRequest](#payload-v1-Object-VectorRequest) + - [Object.Vectors](#payload-v1-Object-Vectors) + - [Remove](#payload-v1-Remove) + - [Remove.Config](#payload-v1-Remove-Config) + - [Remove.MultiRequest](#payload-v1-Remove-MultiRequest) + - [Remove.Request](#payload-v1-Remove-Request) + - [Remove.Timestamp](#payload-v1-Remove-Timestamp) + - [Remove.TimestampRequest](#payload-v1-Remove-TimestampRequest) + - [Search](#payload-v1-Search) + - [Search.Config](#payload-v1-Search-Config) + - [Search.IDRequest](#payload-v1-Search-IDRequest) + - [Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) + - [Search.MultiObjectRequest](#payload-v1-Search-MultiObjectRequest) + - [Search.MultiRequest](#payload-v1-Search-MultiRequest) + - [Search.ObjectRequest](#payload-v1-Search-ObjectRequest) + - [Search.Request](#payload-v1-Search-Request) + - [Search.Response](#payload-v1-Search-Response) + - [Search.Responses](#payload-v1-Search-Responses) + - [Search.StreamResponse](#payload-v1-Search-StreamResponse) + - [Update](#payload-v1-Update) + - [Update.Config](#payload-v1-Update-Config) + - [Update.MultiObjectRequest](#payload-v1-Update-MultiObjectRequest) + - [Update.MultiRequest](#payload-v1-Update-MultiRequest) + - [Update.ObjectRequest](#payload-v1-Update-ObjectRequest) + - [Update.Request](#payload-v1-Update-Request) + - [Update.TimestampRequest](#payload-v1-Update-TimestampRequest) + - [Upsert](#payload-v1-Upsert) + - [Upsert.Config](#payload-v1-Upsert-Config) + - [Upsert.MultiObjectRequest](#payload-v1-Upsert-MultiObjectRequest) + - [Upsert.MultiRequest](#payload-v1-Upsert-MultiRequest) + - [Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) + - [Upsert.Request](#payload-v1-Upsert-Request) + + - [Remove.Timestamp.Operator](#payload-v1-Remove-Timestamp-Operator) + - [Search.AggregationAlgorithm](#payload-v1-Search-AggregationAlgorithm) + - [v1/agent/core/agent.proto](#v1_agent_core_agent-proto) - - [Agent](#core-v1-Agent) + - [Agent](#core-v1-Agent) + - [v1/agent/sidecar/sidecar.proto](#v1_agent_sidecar_sidecar-proto) - - [Sidecar](#sidecar-v1-Sidecar) + - [Sidecar](#sidecar-v1-Sidecar) + - [v1/discoverer/discoverer.proto](#v1_discoverer_discoverer-proto) - - [Discoverer](#discoverer-v1-Discoverer) + - [Discoverer](#discoverer-v1-Discoverer) + - [v1/filter/egress/egress_filter.proto](#v1_filter_egress_egress_filter-proto) - - [Filter](#filter-egress-v1-Filter) + - [Filter](#filter-egress-v1-Filter) + - [v1/filter/ingress/ingress_filter.proto](#v1_filter_ingress_ingress_filter-proto) - - [Filter](#filter-ingress-v1-Filter) + - [Filter](#filter-ingress-v1-Filter) + - [v1/meta/meta.proto](#v1_meta_meta-proto) - - [Meta](#meta-v1-Meta) + - [Meta](#meta-v1-Meta) + - [v1/mirror/mirror.proto](#v1_mirror_mirror-proto) - - [Mirror](#mirror-v1-Mirror) + - [Mirror](#mirror-v1-Mirror) + - [v1/rpc/errdetails/error_details.proto](#v1_rpc_errdetails_error_details-proto) - - [BadRequest](#rpc-v1-BadRequest) - - [BadRequest.FieldViolation](#rpc-v1-BadRequest-FieldViolation) - - [DebugInfo](#rpc-v1-DebugInfo) - - [ErrorInfo](#rpc-v1-ErrorInfo) - - [ErrorInfo.MetadataEntry](#rpc-v1-ErrorInfo-MetadataEntry) - - [Help](#rpc-v1-Help) - - [Help.Link](#rpc-v1-Help-Link) - - [LocalizedMessage](#rpc-v1-LocalizedMessage) - - [PreconditionFailure](#rpc-v1-PreconditionFailure) - - [PreconditionFailure.Violation](#rpc-v1-PreconditionFailure-Violation) - - [QuotaFailure](#rpc-v1-QuotaFailure) - - [QuotaFailure.Violation](#rpc-v1-QuotaFailure-Violation) - - [RequestInfo](#rpc-v1-RequestInfo) - - [ResourceInfo](#rpc-v1-ResourceInfo) - - [RetryInfo](#rpc-v1-RetryInfo) + - [BadRequest](#rpc-v1-BadRequest) + - [BadRequest.FieldViolation](#rpc-v1-BadRequest-FieldViolation) + - [DebugInfo](#rpc-v1-DebugInfo) + - [ErrorInfo](#rpc-v1-ErrorInfo) + - [ErrorInfo.MetadataEntry](#rpc-v1-ErrorInfo-MetadataEntry) + - [Help](#rpc-v1-Help) + - [Help.Link](#rpc-v1-Help-Link) + - [LocalizedMessage](#rpc-v1-LocalizedMessage) + - [PreconditionFailure](#rpc-v1-PreconditionFailure) + - [PreconditionFailure.Violation](#rpc-v1-PreconditionFailure-Violation) + - [QuotaFailure](#rpc-v1-QuotaFailure) + - [QuotaFailure.Violation](#rpc-v1-QuotaFailure-Violation) + - [RequestInfo](#rpc-v1-RequestInfo) + - [ResourceInfo](#rpc-v1-ResourceInfo) + - [RetryInfo](#rpc-v1-RetryInfo) + - [v1/vald/filter.proto](#v1_vald_filter-proto) - - [Filter](#vald-v1-Filter) + - [Filter](#vald-v1-Filter) + - [v1/vald/flush.proto](#v1_vald_flush-proto) - - [Flush](#vald-v1-Flush) + - [Flush](#vald-v1-Flush) + - [v1/vald/index.proto](#v1_vald_index-proto) - - [Index](#vald-v1-Index) + - [Index](#vald-v1-Index) + - [v1/vald/insert.proto](#v1_vald_insert-proto) - - [Insert](#vald-v1-Insert) + - [Insert](#vald-v1-Insert) + - [v1/vald/object.proto](#v1_vald_object-proto) - - [Object](#vald-v1-Object) + - [Object](#vald-v1-Object) + - [v1/vald/remove.proto](#v1_vald_remove-proto) - - [Remove](#vald-v1-Remove) + - [Remove](#vald-v1-Remove) + - [v1/vald/search.proto](#v1_vald_search-proto) - - [Search](#vald-v1-Search) + - [Search](#vald-v1-Search) + - [v1/vald/update.proto](#v1_vald_update-proto) - - [Update](#vald-v1-Update) + - [Update](#vald-v1-Update) + - [v1/vald/upsert.proto](#v1_vald_upsert-proto) - - [Upsert](#vald-v1-Upsert) + - [Upsert](#vald-v1-Upsert) + - [Scalar Value Types](#scalar-value-types) - + +

Top

## v1/payload/payload.proto + + ### Control - Control related messages. + + + + + ### Control.CreateIndexRequest - Represent the create index request. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | -------------------------------------------- | -| pool_size | [uint32](#uint32) | | The pool size of the create index operation. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| pool_size | [uint32](#uint32) | | The pool size of the create index operation. | + + + + + ### Discoverer - Discoverer related messages. + + + + + ### Discoverer.Request - Represent the dicoverer request. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | -------------------------------- | -| name | [string](#string) | | The agent name to be discovered. | -| namespace | [string](#string) | | The namespace to be discovered. | -| node | [string](#string) | | The node to be discovered. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The agent name to be discovered. | +| namespace | [string](#string) | | The namespace to be discovered. | +| node | [string](#string) | | The node to be discovered. | + + + + + ### Empty - Represent an empty message. + + + + + ### Filter - Filter related messages. + + + + + ### Filter.Config - Represent filter configuration. -| Field | Type | Label | Description | -| ------- | ------------------------------------------ | -------- | ------------------------------------------ | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | targets | [Filter.Target](#payload-v1-Filter-Target) | repeated | Represent the filter target configuration. | + + + + + ### Filter.Target - Represent the target filter server. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | -------------------- | -| host | [string](#string) | | The target hostname. | -| port | [uint32](#uint32) | | The target port. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| host | [string](#string) | | The target hostname. | +| port | [uint32](#uint32) | | The target port. | -### Flush -Flush related messages. - -### Flush.Request - -### Info + -Info related messages. +### Flush +Flush related messages. - -### Info.Annotations -Represent the kubernetes annotations. -| Field | Type | Label | Description | -| ----------- | ---------------------------------------------------------------------------------- | -------- | ----------- | -| annotations | [Info.Annotations.AnnotationsEntry](#payload-v1-Info-Annotations-AnnotationsEntry) | repeated | | - -### Info.Annotations.AnnotationsEntry + -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | +### Flush.Request - -### Info.CPU -Represent the CPU information message. -| Field | Type | Label | Description | -| ------- | ----------------- | ----- | --------------------------- | -| limit | [double](#double) | | The CPU resource limit. | -| request | [double](#double) | | The CPU resource requested. | -| usage | [double](#double) | | The CPU usage. | - -### Info.IPs -Represent the multiple IP message. + -| Field | Type | Label | Description | -| ----- | ----------------- | -------- | ----------- | -| ip | [string](#string) | repeated | | +### Info +Info related messages. - -### Info.Index -Represent the index information messages. - -### Info.Index.Count -Represent the index count message. + -| Field | Type | Label | Description | -| ----------- | ----------------- | ----- | ---------------------------- | -| stored | [uint32](#uint32) | | The stored index count. | -| uncommitted | [uint32](#uint32) | | The uncommitted index count. | -| indexing | [bool](#bool) | | The indexing index count. | -| saving | [bool](#bool) | | The saving index count. | +### Info.Annotations +Represent the kubernetes annotations. - -### Info.Index.Detail +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| annotations | [Info.Annotations.AnnotationsEntry](#payload-v1-Info-Annotations-AnnotationsEntry) | repeated | | -Represent the index count for each Agents message. -| Field | Type | Label | Description | -| ----------- | -------------------------------------------------------------------------- | -------- | ---------------------------------- | -| counts | [Info.Index.Detail.CountsEntry](#payload-v1-Info-Index-Detail-CountsEntry) | repeated | count infos for each agents | -| replica | [uint32](#uint32) | | index replica of vald cluster | -| live_agents | [uint32](#uint32) | | live agent replica of vald cluster | - -### Info.Index.Detail.CountsEntry -| Field | Type | Label | Description | -| ----- | ------------------------------------------------ | ----- | ----------- | -| key | [string](#string) | | | -| value | [Info.Index.Count](#payload-v1-Info-Index-Count) | | | - + -### Info.Index.Property +### Info.Annotations.AnnotationsEntry -Represents index Property -| Field | Type | Label | Description | -| ---------------------------------- | ----------------- | ----- | ----------- | -| dimension | [int32](#int32) | | | -| thread_pool_size | [int32](#int32) | | | -| object_type | [string](#string) | | | -| distance_type | [string](#string) | | | -| index_type | [string](#string) | | | -| database_type | [string](#string) | | | -| object_alignment | [string](#string) | | | -| path_adjustment_interval | [int32](#int32) | | | -| graph_shared_memory_size | [int32](#int32) | | | -| tree_shared_memory_size | [int32](#int32) | | | -| object_shared_memory_size | [int32](#int32) | | | -| prefetch_offset | [int32](#int32) | | | -| prefetch_size | [int32](#int32) | | | -| accuracy_table | [string](#string) | | | -| search_type | [string](#string) | | | -| max_magnitude | [float](#float) | | | -| n_of_neighbors_for_insertion_order | [int32](#int32) | | | -| epsilon_for_insertion_order | [float](#float) | | | -| refinement_object_type | [string](#string) | | | -| truncation_threshold | [int32](#int32) | | | -| edge_size_for_creation | [int32](#int32) | | | -| edge_size_for_search | [int32](#int32) | | | -| edge_size_limit_for_creation | [int32](#int32) | | | -| insertion_radius_coefficient | [double](#double) | | | -| seed_size | [int32](#int32) | | | -| seed_type | [string](#string) | | | -| truncation_thread_pool_size | [int32](#int32) | | | -| batch_size_for_creation | [int32](#int32) | | | -| graph_type | [string](#string) | | | -| dynamic_edge_size_base | [int32](#int32) | | | -| dynamic_edge_size_rate | [int32](#int32) | | | -| build_time_limit | [float](#float) | | | -| outgoing_edge | [int32](#int32) | | | -| incoming_edge | [int32](#int32) | | | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | -### Info.Index.PropertyDetail -Represents index Properties for each Agents -| Field | Type | Label | Description | -| ------- | -------------------------------------------------------------------------------------------- | -------- | ----------- | -| details | [Info.Index.PropertyDetail.DetailsEntry](#payload-v1-Info-Index-PropertyDetail-DetailsEntry) | repeated | | - -### Info.Index.PropertyDetail.DetailsEntry -| Field | Type | Label | Description | -| ----- | ------------------------------------------------------ | ----- | ----------- | -| key | [string](#string) | | | -| value | [Info.Index.Property](#payload-v1-Info-Index-Property) | | | + - +### Info.CPU +Represent the CPU information message. -### Info.Index.Statistics -Represents index Statistics +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| limit | [double](#double) | | The CPU resource limit. | +| request | [double](#double) | | The CPU resource requested. | +| usage | [double](#double) | | The CPU usage. | -| Field | Type | Label | Description | -| ------------------------------------ | ----------------- | -------- | ----------- | -| valid | [bool](#bool) | | | -| median_indegree | [int32](#int32) | | | -| median_outdegree | [int32](#int32) | | | -| max_number_of_indegree | [uint64](#uint64) | | | -| max_number_of_outdegree | [uint64](#uint64) | | | -| min_number_of_indegree | [uint64](#uint64) | | | -| min_number_of_outdegree | [uint64](#uint64) | | | -| mode_indegree | [uint64](#uint64) | | | -| mode_outdegree | [uint64](#uint64) | | | -| nodes_skipped_for_10_edges | [uint64](#uint64) | | | -| nodes_skipped_for_indegree_distance | [uint64](#uint64) | | | -| number_of_edges | [uint64](#uint64) | | | -| number_of_indexed_objects | [uint64](#uint64) | | | -| number_of_nodes | [uint64](#uint64) | | | -| number_of_nodes_without_edges | [uint64](#uint64) | | | -| number_of_nodes_without_indegree | [uint64](#uint64) | | | -| number_of_objects | [uint64](#uint64) | | | -| number_of_removed_objects | [uint64](#uint64) | | | -| size_of_object_repository | [uint64](#uint64) | | | -| size_of_refinement_object_repository | [uint64](#uint64) | | | -| variance_of_indegree | [double](#double) | | | -| variance_of_outdegree | [double](#double) | | | -| mean_edge_length | [double](#double) | | | -| mean_edge_length_for_10_edges | [double](#double) | | | -| mean_indegree_distance_for_10_edges | [double](#double) | | | -| mean_number_of_edges_per_node | [double](#double) | | | -| c1_indegree | [double](#double) | | | -| c5_indegree | [double](#double) | | | -| c95_outdegree | [double](#double) | | | -| c99_outdegree | [double](#double) | | | -| indegree_count | [int64](#int64) | repeated | | -| outdegree_histogram | [uint64](#uint64) | repeated | | -| indegree_histogram | [uint64](#uint64) | repeated | | - -### Info.Index.StatisticsDetail -Represents index Statistics for each Agents -| Field | Type | Label | Description | -| ------- | ------------------------------------------------------------------------------------------------ | -------- | --------------------------- | -| details | [Info.Index.StatisticsDetail.DetailsEntry](#payload-v1-Info-Index-StatisticsDetail-DetailsEntry) | repeated | count infos for each agents | - + -### Info.Index.StatisticsDetail.DetailsEntry +### Info.IPs +Represent the multiple IP message. -| Field | Type | Label | Description | -| ----- | ---------------------------------------------------------- | ----- | ----------- | -| key | [string](#string) | | | -| value | [Info.Index.Statistics](#payload-v1-Info-Index-Statistics) | | | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ip | [string](#string) | repeated | | -### Info.Index.UUID -Represent the UUID message. - -### Info.Index.UUID.Committed -The committed UUID. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| uuid | [string](#string) | | | + - +### Info.Index +Represent the index information messages. -### Info.Index.UUID.Uncommitted -The uncommitted UUID. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| uuid | [string](#string) | | | - -### Info.Labels -Represent the kubernetes labels. + -| Field | Type | Label | Description | -| ------ | -------------------------------------------------------------- | -------- | ----------- | -| labels | [Info.Labels.LabelsEntry](#payload-v1-Info-Labels-LabelsEntry) | repeated | | +### Info.Index.Count +Represent the index count message. - -### Info.Labels.LabelsEntry +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| stored | [uint32](#uint32) | | The stored index count. | +| uncommitted | [uint32](#uint32) | | The uncommitted index count. | +| indexing | [bool](#bool) | | The indexing index count. | +| saving | [bool](#bool) | | The saving index count. | -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | - -### Info.Memory -Represent the memory information message. -| Field | Type | Label | Description | -| ------- | ----------------- | ----- | --------------------- | -| limit | [double](#double) | | The memory limit. | -| request | [double](#double) | | The memory requested. | -| usage | [double](#double) | | The memory usage. | - + -### Info.Node +### Info.Index.Detail +Represent the index count for each Agents message. -Represent the node information message. -| Field | Type | Label | Description | -| ------------- | -------------------------------------- | ----- | ------------------------------------ | -| name | [string](#string) | | The name of the node. | -| internal_addr | [string](#string) | | The internal IP address of the node. | -| external_addr | [string](#string) | | The external IP address of the node. | -| cpu | [Info.CPU](#payload-v1-Info-CPU) | | The CPU information of the node. | -| memory | [Info.Memory](#payload-v1-Info-Memory) | | The memory information of the node. | -| Pods | [Info.Pods](#payload-v1-Info-Pods) | | The pod information of the node. | +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| counts | [Info.Index.Detail.CountsEntry](#payload-v1-Info-Index-Detail-CountsEntry) | repeated | count infos for each agents | +| replica | [uint32](#uint32) | | index replica of vald cluster | +| live_agents | [uint32](#uint32) | | live agent replica of vald cluster | - -### Info.Nodes -Represent the multiple node information message. -| Field | Type | Label | Description | -| ----- | ---------------------------------- | -------- | ------------------------------ | -| nodes | [Info.Node](#payload-v1-Info-Node) | repeated | The multiple node information. | - -### Info.Pod + -Represent the pod information message. +### Info.Index.Detail.CountsEntry -| Field | Type | Label | Description | -| --------- | -------------------------------------- | ----- | ------------------------------------- | -| app_name | [string](#string) | | The app name of the pod on the label. | -| name | [string](#string) | | The name of the pod. | -| namespace | [string](#string) | | The namespace of the pod. | -| ip | [string](#string) | | The IP of the pod. | -| cpu | [Info.CPU](#payload-v1-Info-CPU) | | The CPU information of the pod. | -| memory | [Info.Memory](#payload-v1-Info-Memory) | | The memory information of the pod. | -| node | [Info.Node](#payload-v1-Info-Node) | | The node information of the pod. | - -### Info.Pods +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Info.Index.Count](#payload-v1-Info-Index-Count) | | | -Represent the multiple pod information message. -| Field | Type | Label | Description | -| ----- | -------------------------------- | -------- | ----------------------------- | -| pods | [Info.Pod](#payload-v1-Info-Pod) | repeated | The multiple pod information. | - -### Info.Service -Represent the service information message. -| Field | Type | Label | Description | -| ----------- | ------------------------------------------------ | -------- | ------------------------------- | -| name | [string](#string) | | The name of the svc. | -| cluster_ip | [string](#string) | | The cluster ip of the svc. | -| cluster_ips | [string](#string) | repeated | The cluster ips of the svc. | -| ports | [Info.ServicePort](#payload-v1-Info-ServicePort) | repeated | The port of the svc. | -| labels | [Info.Labels](#payload-v1-Info-Labels) | | The labels of the service. | -| annotations | [Info.Annotations](#payload-v1-Info-Annotations) | | The annotations of the service. | + - +### Info.Index.Property +Represents index Property -### Info.ServicePort -Represets the service port information message. +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| dimension | [int32](#int32) | | | +| thread_pool_size | [int32](#int32) | | | +| object_type | [string](#string) | | | +| distance_type | [string](#string) | | | +| index_type | [string](#string) | | | +| database_type | [string](#string) | | | +| object_alignment | [string](#string) | | | +| path_adjustment_interval | [int32](#int32) | | | +| graph_shared_memory_size | [int32](#int32) | | | +| tree_shared_memory_size | [int32](#int32) | | | +| object_shared_memory_size | [int32](#int32) | | | +| prefetch_offset | [int32](#int32) | | | +| prefetch_size | [int32](#int32) | | | +| accuracy_table | [string](#string) | | | +| search_type | [string](#string) | | | +| max_magnitude | [float](#float) | | | +| n_of_neighbors_for_insertion_order | [int32](#int32) | | | +| epsilon_for_insertion_order | [float](#float) | | | +| refinement_object_type | [string](#string) | | | +| truncation_threshold | [int32](#int32) | | | +| edge_size_for_creation | [int32](#int32) | | | +| edge_size_for_search | [int32](#int32) | | | +| edge_size_limit_for_creation | [int32](#int32) | | | +| insertion_radius_coefficient | [double](#double) | | | +| seed_size | [int32](#int32) | | | +| seed_type | [string](#string) | | | +| truncation_thread_pool_size | [int32](#int32) | | | +| batch_size_for_creation | [int32](#int32) | | | +| graph_type | [string](#string) | | | +| dynamic_edge_size_base | [int32](#int32) | | | +| dynamic_edge_size_rate | [int32](#int32) | | | +| build_time_limit | [float](#float) | | | +| outgoing_edge | [int32](#int32) | | | +| incoming_edge | [int32](#int32) | | | -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | --------------------- | -| name | [string](#string) | | The name of the port. | -| port | [int32](#int32) | | The port number | - -### Info.Services -Represent the multiple service information message. -| Field | Type | Label | Description | -| -------- | ---------------------------------------- | -------- | --------------------------------- | -| services | [Info.Service](#payload-v1-Info-Service) | repeated | The multiple service information. | - + -### Insert +### Info.Index.PropertyDetail +Represents index Properties for each Agents -Insert related messages. - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| details | [Info.Index.PropertyDetail.DetailsEntry](#payload-v1-Info-Index-PropertyDetail-DetailsEntry) | repeated | | -### Insert.Config -Represent insert configurations. -| Field | Type | Label | Description | -| ----------------------- | ------------------------------------------ | ----- | --------------------------------------------------- | -| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during insert operation. | -| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configurations. | -| timestamp | [int64](#int64) | | Insert timestamp. | - -### Insert.MultiObjectRequest -Represent the multiple insert by binary object request. + -| Field | Type | Label | Description | -| -------- | -------------------------------------------------------- | -------- | -------------------------------------------- | -| requests | [Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) | repeated | Represent multiple insert by object content. | +### Info.Index.PropertyDetail.DetailsEntry - -### Insert.MultiRequest -Represent the multiple insert request. +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Info.Index.Property](#payload-v1-Info-Index-Property) | | | -| Field | Type | Label | Description | -| -------- | -------------------------------------------- | -------- | ------------------------------------------ | -| requests | [Insert.Request](#payload-v1-Insert-Request) | repeated | Represent multiple insert request content. | - -### Insert.ObjectRequest -Represent the insert by binary object request. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------ | ----- | ---------------------------------------- | -| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be inserted. | -| config | [Insert.Config](#payload-v1-Insert-Config) | | The configuration of the insert request. | -| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter configurations. | - + -### Insert.Request +### Info.Index.Statistics +Represents index Statistics -Represent the insert request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | ---------------------------------------- | -| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be inserted. | -| config | [Insert.Config](#payload-v1-Insert-Config) | | The configuration of the insert request. | +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| valid | [bool](#bool) | | | +| median_indegree | [int32](#int32) | | | +| median_outdegree | [int32](#int32) | | | +| max_number_of_indegree | [uint64](#uint64) | | | +| max_number_of_outdegree | [uint64](#uint64) | | | +| min_number_of_indegree | [uint64](#uint64) | | | +| min_number_of_outdegree | [uint64](#uint64) | | | +| mode_indegree | [uint64](#uint64) | | | +| mode_outdegree | [uint64](#uint64) | | | +| nodes_skipped_for_10_edges | [uint64](#uint64) | | | +| nodes_skipped_for_indegree_distance | [uint64](#uint64) | | | +| number_of_edges | [uint64](#uint64) | | | +| number_of_indexed_objects | [uint64](#uint64) | | | +| number_of_nodes | [uint64](#uint64) | | | +| number_of_nodes_without_edges | [uint64](#uint64) | | | +| number_of_nodes_without_indegree | [uint64](#uint64) | | | +| number_of_objects | [uint64](#uint64) | | | +| number_of_removed_objects | [uint64](#uint64) | | | +| size_of_object_repository | [uint64](#uint64) | | | +| size_of_refinement_object_repository | [uint64](#uint64) | | | +| variance_of_indegree | [double](#double) | | | +| variance_of_outdegree | [double](#double) | | | +| mean_edge_length | [double](#double) | | | +| mean_edge_length_for_10_edges | [double](#double) | | | +| mean_indegree_distance_for_10_edges | [double](#double) | | | +| mean_number_of_edges_per_node | [double](#double) | | | +| c1_indegree | [double](#double) | | | +| c5_indegree | [double](#double) | | | +| c95_outdegree | [double](#double) | | | +| c99_outdegree | [double](#double) | | | +| indegree_count | [int64](#int64) | repeated | | +| outdegree_histogram | [uint64](#uint64) | repeated | | +| indegree_histogram | [uint64](#uint64) | repeated | | - -### Meta - -### Meta.Key -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| key | [string](#string) | | | - + -### Meta.KeyValue +### Info.Index.StatisticsDetail +Represents index Statistics for each Agents -| Field | Type | Label | Description | -| ----- | ------------------------------------ | ----- | ----------- | -| key | [Meta.Key](#payload-v1-Meta-Key) | | | -| value | [Meta.Value](#payload-v1-Meta-Value) | | | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| details | [Info.Index.StatisticsDetail.DetailsEntry](#payload-v1-Info-Index-StatisticsDetail-DetailsEntry) | repeated | count infos for each agents | -### Meta.Value -| Field | Type | Label | Description | -| ----- | ------------------------------------------- | ----- | ----------- | -| value | [google.protobuf.Any](#google-protobuf-Any) | | | - -### Mirror -Mirror related messages. - + -### Mirror.Target +### Info.Index.StatisticsDetail.DetailsEntry -Represent server information. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | -------------------- | -| host | [string](#string) | | The target hostname. | -| port | [uint32](#uint32) | | The target port. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Info.Index.Statistics](#payload-v1-Info-Index-Statistics) | | | -### Mirror.Targets -Represent the multiple Target message. -| Field | Type | Label | Description | -| ------- | ------------------------------------------ | -------- | -------------------------------- | -| targets | [Mirror.Target](#payload-v1-Mirror-Target) | repeated | The multiple target information. | - -### Object -Common messages. + - +### Info.Index.UUID +Represent the UUID message. -### Object.Blob -Represent the binary object. -| Field | Type | Label | Description | -| ------ | ----------------- | ----- | ------------------ | -| id | [string](#string) | | The object ID. | -| object | [bytes](#bytes) | | The binary object. | - -### Object.Distance -Represent the ID and distance pair. + -| Field | Type | Label | Description | -| -------- | ----------------- | ----- | -------------- | -| id | [string](#string) | | The vector ID. | -| distance | [float](#float) | | The distance. | +### Info.Index.UUID.Committed +The committed UUID. - -### Object.ID +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| uuid | [string](#string) | | | -Represent the vector ID. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| id | [string](#string) | | | - -### Object.IDs -Represent multiple vector IDs. -| Field | Type | Label | Description | -| ----- | ----------------- | -------- | ----------- | -| ids | [string](#string) | repeated | | + - +### Info.Index.UUID.Uncommitted +The uncommitted UUID. -### Object.List -Represent the list object vector stream request and response. +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| uuid | [string](#string) | | | - -### Object.List.Request - + + + + + +### Info.Labels +Represent the kubernetes labels. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| labels | [Info.Labels.LabelsEntry](#payload-v1-Info-Labels-LabelsEntry) | repeated | | + + + + + + + + +### Info.Labels.LabelsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + + + + +### Info.Memory +Represent the memory information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| limit | [double](#double) | | The memory limit. | +| request | [double](#double) | | The memory requested. | +| usage | [double](#double) | | The memory usage. | + + + + + + + + +### Info.Node +Represent the node information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The name of the node. | +| internal_addr | [string](#string) | | The internal IP address of the node. | +| external_addr | [string](#string) | | The external IP address of the node. | +| cpu | [Info.CPU](#payload-v1-Info-CPU) | | The CPU information of the node. | +| memory | [Info.Memory](#payload-v1-Info-Memory) | | The memory information of the node. | +| Pods | [Info.Pods](#payload-v1-Info-Pods) | | The pod information of the node. | + + + + + + + + +### Info.Nodes +Represent the multiple node information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| nodes | [Info.Node](#payload-v1-Info-Node) | repeated | The multiple node information. | + + + + + + + + +### Info.Pod +Represent the pod information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| app_name | [string](#string) | | The app name of the pod on the label. | +| name | [string](#string) | | The name of the pod. | +| namespace | [string](#string) | | The namespace of the pod. | +| ip | [string](#string) | | The IP of the pod. | +| cpu | [Info.CPU](#payload-v1-Info-CPU) | | The CPU information of the pod. | +| memory | [Info.Memory](#payload-v1-Info-Memory) | | The memory information of the pod. | +| node | [Info.Node](#payload-v1-Info-Node) | | The node information of the pod. | + + + + + + + + +### Info.Pods +Represent the multiple pod information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| pods | [Info.Pod](#payload-v1-Info-Pod) | repeated | The multiple pod information. | + + + + + + + + +### Info.Service +Represent the service information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The name of the svc. | +| cluster_ip | [string](#string) | | The cluster ip of the svc. | +| cluster_ips | [string](#string) | repeated | The cluster ips of the svc. | +| ports | [Info.ServicePort](#payload-v1-Info-ServicePort) | repeated | The port of the svc. | +| labels | [Info.Labels](#payload-v1-Info-Labels) | | The labels of the service. | +| annotations | [Info.Annotations](#payload-v1-Info-Annotations) | | The annotations of the service. | + + + + + + + + +### Info.ServicePort +Represets the service port information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The name of the port. | +| port | [int32](#int32) | | The port number | + + + + + + + + +### Info.Services +Represent the multiple service information message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| services | [Info.Service](#payload-v1-Info-Service) | repeated | The multiple service information. | + + + + + + + + +### Insert +Insert related messages. + + + + + + + + +### Insert.Config +Represent insert configurations. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during insert operation. | +| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configurations. | +| timestamp | [int64](#int64) | | Insert timestamp. | + + + + + + + + +### Insert.MultiObjectRequest +Represent the multiple insert by binary object request. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| requests | [Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) | repeated | Represent multiple insert by object content. | + + + + + + + + +### Insert.MultiRequest +Represent the multiple insert request. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| requests | [Insert.Request](#payload-v1-Insert-Request) | repeated | Represent multiple insert request content. | + + + + + + + + +### Insert.ObjectRequest +Represent the insert by binary object request. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be inserted. | +| config | [Insert.Config](#payload-v1-Insert-Config) | | The configuration of the insert request. | +| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter configurations. | + + + + + + + + +### Insert.Request +Represent the insert request. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be inserted. | +| config | [Insert.Config](#payload-v1-Insert-Config) | | The configuration of the insert request. | + + + + + + + + +### Meta + + + + + + + + + +### Meta.Key + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | + + + + + + + + +### Meta.KeyValue + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [Meta.Key](#payload-v1-Meta-Key) | | | +| value | [Meta.Value](#payload-v1-Meta-Value) | | | + + + + + + + + +### Meta.Value + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [google.protobuf.Any](#google-protobuf-Any) | | | + + + + + + + + +### Mirror +Mirror related messages. + + + + + + + + +### Mirror.Target +Represent server information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| host | [string](#string) | | The target hostname. | +| port | [uint32](#uint32) | | The target port. | + + + + + + + + +### Mirror.Targets +Represent the multiple Target message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| targets | [Mirror.Target](#payload-v1-Mirror-Target) | repeated | The multiple target information. | + + + + + + + + +### Object +Common messages. + + + + + + + + +### Object.Blob +Represent the binary object. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The object ID. | +| object | [bytes](#bytes) | | The binary object. | + + + + + + + + +### Object.Distance +Represent the ID and distance pair. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The vector ID. | +| distance | [float](#float) | | The distance. | + + + + + + + + +### Object.ID +Represent the vector ID. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | | + + + + + + + + +### Object.IDs +Represent multiple vector IDs. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ids | [string](#string) | repeated | | + + + + + + + + +### Object.List +Represent the list object vector stream request and response. + + + + + + + + +### Object.List.Request + + + + + + + + ### Object.List.Response -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | --------------------- | -| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Object.Location - Represent the vector location. -| Field | Type | Label | Description | -| ----- | ----------------- | -------- | ------------------------- | -| name | [string](#string) | | The name of the location. | -| uuid | [string](#string) | | The UUID of the vector. | -| ips | [string](#string) | repeated | The IP list. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The name of the location. | +| uuid | [string](#string) | | The UUID of the vector. | +| ips | [string](#string) | repeated | The IP list. | + + + + + ### Object.Locations - Represent multiple vector locations. -| Field | Type | Label | Description | -| --------- | ---------------------------------------------- | -------- | ----------- | -| locations | [Object.Location](#payload-v1-Object-Location) | repeated | | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| locations | [Object.Location](#payload-v1-Object-Location) | repeated | | + + + + + ### Object.ReshapeVector - Represent reshape vector. -| Field | Type | Label | Description | -| ------ | --------------- | -------- | ------------------ | -| object | [bytes](#bytes) | | The binary object. | -| shape | [int32](#int32) | repeated | The new shape. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [bytes](#bytes) | | The binary object. | +| shape | [int32](#int32) | repeated | The new shape. | + + + + + ### Object.StreamBlob - Represent stream response of binary objects. -| Field | Type | Label | Description | -| ------ | --------------------------------------- | ----- | --------------------- | -| blob | [Object.Blob](#payload-v1-Object-Blob) | | The binary object. | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| blob | [Object.Blob](#payload-v1-Object-Blob) | | The binary object. | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Object.StreamDistance - Represent stream response of distances. -| Field | Type | Label | Description | -| -------- | ---------------------------------------------- | ----- | --------------------- | -| distance | [Object.Distance](#payload-v1-Object-Distance) | | The distance. | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| distance | [Object.Distance](#payload-v1-Object-Distance) | | The distance. | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Object.StreamLocation - Represent the stream response of the vector location. -| Field | Type | Label | Description | -| -------- | ---------------------------------------------- | ----- | --------------------- | -| location | [Object.Location](#payload-v1-Object-Location) | | The vector location. | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| location | [Object.Location](#payload-v1-Object-Location) | | The vector location. | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Object.StreamVector - Represent stream response of the vector. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | --------------------- | -| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector. | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector. | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Object.Timestamp - Represent a vector meta data. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | ----------------------------------------------- | -| id | [string](#string) | | The vector ID. | -| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The vector ID. | +| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | + + + + + ### Object.TimestampRequest - Represent a request to fetch vector meta data. -| Field | Type | Label | Description | -| ----- | ---------------------------------- | ----- | ---------------------------- | -| id | [Object.ID](#payload-v1-Object-ID) | | The vector ID to be fetched. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [Object.ID](#payload-v1-Object-ID) | | The vector ID to be fetched. | + + + + + ### Object.Vector - Represent a vector. -| Field | Type | Label | Description | -| --------- | ----------------- | -------- | ----------------------------------------------- | -| id | [string](#string) | | The vector ID. | -| vector | [float](#float) | repeated | The vector. | -| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The vector ID. | +| vector | [float](#float) | repeated | The vector. | +| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | + + + + + ### Object.VectorRequest - Represent a request to fetch raw vector. -| Field | Type | Label | Description | -| ------- | ------------------------------------------ | ----- | ---------------------------- | -| id | [Object.ID](#payload-v1-Object-ID) | | The vector ID to be fetched. | -| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configurations. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [Object.ID](#payload-v1-Object-ID) | | The vector ID to be fetched. | +| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configurations. | + + + + + -### Object.Vectors +### Object.Vectors +Represent multiple vectors. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vectors | [Object.Vector](#payload-v1-Object-Vector) | repeated | | + + + -Represent multiple vectors. -| Field | Type | Label | Description | -| ------- | ------------------------------------------ | -------- | ----------- | -| vectors | [Object.Vector](#payload-v1-Object-Vector) | repeated | | ### Remove - Remove related messages. + + + + + ### Remove.Config - Represent the remove configuration. -| Field | Type | Label | Description | -| ----------------------- | --------------- | ----- | --------------------------------------------------- | -| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during upsert operation. | -| timestamp | [int64](#int64) | | Remove timestamp. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during upsert operation. | +| timestamp | [int64](#int64) | | Remove timestamp. | + + + + + ### Remove.MultiRequest - Represent the multiple remove request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------- | -------- | ---------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Remove.Request](#payload-v1-Remove-Request) | repeated | Represent the multiple remove request content. | + + + + + ### Remove.Request - Represent the remove request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | ---------------------------------------- | -| id | [Object.ID](#payload-v1-Object-ID) | | The object ID to be removed. | -| config | [Remove.Config](#payload-v1-Remove-Config) | | The configuration of the remove request. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [Object.ID](#payload-v1-Object-ID) | | The object ID to be removed. | +| config | [Remove.Config](#payload-v1-Remove-Config) | | The configuration of the remove request. | + + + + + ### Remove.Timestamp - Represent the timestamp comparison. -| Field | Type | Label | Description | -| --------- | ------------------------------------------------------------------ | ----- | ------------------------- | -| timestamp | [int64](#int64) | | The timestamp. | -| operator | [Remove.Timestamp.Operator](#payload-v1-Remove-Timestamp-Operator) | | The conditional operator. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| timestamp | [int64](#int64) | | The timestamp. | +| operator | [Remove.Timestamp.Operator](#payload-v1-Remove-Timestamp-Operator) | | The conditional operator. | + + + + + ### Remove.TimestampRequest - Represent the remove request based on timestamp. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------ | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | timestamps | [Remove.Timestamp](#payload-v1-Remove-Timestamp) | repeated | The timestamp comparison list. If more than one is specified, the `AND` search is applied. | + + + + + ### Search - Search related messages. + + + + + ### Search.Config - Represent search configuration. -| Field | Type | Label | Description | -| --------------------- | ---------------------------------------------------------------------- | ----- | -------------------------------------------- | -| request_id | [string](#string) | | Unique request ID. | -| num | [uint32](#uint32) | | Maximum number of result to be returned. | -| radius | [float](#float) | | Search radius. | -| epsilon | [float](#float) | | Search coefficient. | -| timeout | [int64](#int64) | | Search timeout in nanoseconds. | -| ingress_filters | [Filter.Config](#payload-v1-Filter-Config) | | Ingress filter configurations. | -| egress_filters | [Filter.Config](#payload-v1-Filter-Config) | | Egress filter configurations. | -| min_num | [uint32](#uint32) | | Minimum number of result to be returned. | -| aggregation_algorithm | [Search.AggregationAlgorithm](#payload-v1-Search-AggregationAlgorithm) | | Aggregation Algorithm | -| ratio | [google.protobuf.FloatValue](#google-protobuf-FloatValue) | | Search ratio for agent return result number. | -| nprobe | [uint32](#uint32) | | Search nprobe. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| request_id | [string](#string) | | Unique request ID. | +| num | [uint32](#uint32) | | Maximum number of result to be returned. | +| radius | [float](#float) | | Search radius. | +| epsilon | [float](#float) | | Search coefficient. | +| timeout | [int64](#int64) | | Search timeout in nanoseconds. | +| ingress_filters | [Filter.Config](#payload-v1-Filter-Config) | | Ingress filter configurations. | +| egress_filters | [Filter.Config](#payload-v1-Filter-Config) | | Egress filter configurations. | +| min_num | [uint32](#uint32) | | Minimum number of result to be returned. | +| aggregation_algorithm | [Search.AggregationAlgorithm](#payload-v1-Search-AggregationAlgorithm) | | Aggregation Algorithm | +| ratio | [google.protobuf.FloatValue](#google-protobuf-FloatValue) | | Search ratio for agent return result number. | +| nprobe | [uint32](#uint32) | | Search nprobe. | + + + + + ### Search.IDRequest - Represent a search by ID request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | ---------------------------------------- | -| id | [string](#string) | | The vector ID to be searched. | -| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The vector ID to be searched. | +| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | + + + + + ### Search.MultiIDRequest - Represent the multiple search by ID request. -| Field | Type | Label | Description | -| -------- | ------------------------------------------------ | -------- | ---------------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Search.IDRequest](#payload-v1-Search-IDRequest) | repeated | Represent the multiple search by ID request content. | + + + + + ### Search.MultiObjectRequest - Represent the multiple search by binary object request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------------------- | -------- | --------------------------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Search.ObjectRequest](#payload-v1-Search-ObjectRequest) | repeated | Represent the multiple search by binary object request content. | + + + + + ### Search.MultiRequest - Represent the multiple search request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------- | -------- | ---------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Search.Request](#payload-v1-Search-Request) | repeated | Represent the multiple search request content. | + + + + + ### Search.ObjectRequest - Represent a search by binary object request. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------ | ----- | ---------------------------------------- | -| object | [bytes](#bytes) | | The binary object to be searched. | -| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | -| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter configuration. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [bytes](#bytes) | | The binary object to be searched. | +| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | +| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter configuration. | + + + + + ### Search.Request - Represent a search request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | -------- | ---------------------------------------- | -| vector | [float](#float) | repeated | The vector to be searched. | -| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [float](#float) | repeated | The vector to be searched. | +| config | [Search.Config](#payload-v1-Search-Config) | | The configuration of the search request. | + + + + + ### Search.Response - Represent a search response. -| Field | Type | Label | Description | -| ---------- | ---------------------------------------------- | -------- | ---------------------- | -| request_id | [string](#string) | | The unique request ID. | -| results | [Object.Distance](#payload-v1-Object-Distance) | repeated | Search results. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| request_id | [string](#string) | | The unique request ID. | +| results | [Object.Distance](#payload-v1-Object-Distance) | repeated | Search results. | + + + + + ### Search.Responses - Represent multiple search responses. -| Field | Type | Label | Description | -| --------- | ---------------------------------------------- | -------- | ----------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | responses | [Search.Response](#payload-v1-Search-Response) | repeated | Represent the multiple search response content. | + + + + + ### Search.StreamResponse - Represent stream search response. -| Field | Type | Label | Description | -| -------- | ---------------------------------------------- | ----- | ------------------------------ | -| response | [Search.Response](#payload-v1-Search-Response) | | Represent the search response. | -| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| response | [Search.Response](#payload-v1-Search-Response) | | Represent the search response. | +| status | [google.rpc.Status](#google-rpc-Status) | | The RPC error status. | + + + + + ### Update - Update related messages + + + + + ### Update.Config - Represent the update configuration. -| Field | Type | Label | Description | -| ----------------------- | ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------ | -| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during update operation. | -| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configuration. | -| timestamp | [int64](#int64) | | Update timestamp. | -| disable_balanced_update | [bool](#bool) | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during update operation. | +| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configuration. | +| timestamp | [int64](#int64) | | Update timestamp. | +| disable_balanced_update | [bool](#bool) | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + + + + + ### Update.MultiObjectRequest - Represent the multiple update binary object request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------------------- | -------- | ----------------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Update.ObjectRequest](#payload-v1-Update-ObjectRequest) | repeated | Represent the multiple update object request content. | + + + + + ### Update.MultiRequest - Represent the multiple update request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------- | -------- | ---------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Update.Request](#payload-v1-Update-Request) | repeated | Represent the multiple update request content. | + + + + + ### Update.ObjectRequest - Represent the update binary object request. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------ | ----- | ---------------------------------------- | -| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be updated. | -| config | [Update.Config](#payload-v1-Update-Config) | | The configuration of the update request. | -| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter target. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be updated. | +| config | [Update.Config](#payload-v1-Update-Config) | | The configuration of the update request. | +| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter target. | + + + + + ### Update.Request - Represent the update request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | ---------------------------------------- | -| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be updated. | -| config | [Update.Config](#payload-v1-Update-Config) | | The configuration of the update request. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be updated. | +| config | [Update.Config](#payload-v1-Update-Config) | | The configuration of the update request. | + + + + + ### Update.TimestampRequest - Represent a vector meta data. -| Field | Type | Label | Description | -| --------- | ----------------- | ----- | ------------------------------------------------- | -| id | [string](#string) | | The vector ID. | -| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | -| force | [bool](#bool) | | force represents forcefully update the timestamp. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| id | [string](#string) | | The vector ID. | +| timestamp | [int64](#int64) | | timestamp represents when this vector inserted. | +| force | [bool](#bool) | | force represents forcefully update the timestamp. | + + + + + ### Upsert - Upsert related messages. + + + + + ### Upsert.Config - Represent the upsert configuration. -| Field | Type | Label | Description | -| ----------------------- | ------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------ | -| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during upsert operation. | -| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configuration. | -| timestamp | [int64](#int64) | | Upsert timestamp. | -| disable_balanced_update | [bool](#bool) | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| skip_strict_exist_check | [bool](#bool) | | A flag to skip exist check during upsert operation. | +| filters | [Filter.Config](#payload-v1-Filter-Config) | | Filter configuration. | +| timestamp | [int64](#int64) | | Upsert timestamp. | +| disable_balanced_update | [bool](#bool) | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + + + + + ### Upsert.MultiObjectRequest - Represent the multiple upsert binary object request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------------------- | -------- | ----------------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) | repeated | Represent the multiple upsert object request content. | + + + + + ### Upsert.MultiRequest - Represent mthe ultiple upsert request. -| Field | Type | Label | Description | -| -------- | -------------------------------------------- | -------- | ---------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | requests | [Upsert.Request](#payload-v1-Upsert-Request) | repeated | Represent the multiple upsert request content. | + + + + + ### Upsert.ObjectRequest - Represent the upsert binary object request. -| Field | Type | Label | Description | -| ---------- | ------------------------------------------ | ----- | ---------------------------------------- | -| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be upserted. | -| config | [Upsert.Config](#payload-v1-Upsert-Config) | | The configuration of the upsert request. | -| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter target. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| object | [Object.Blob](#payload-v1-Object-Blob) | | The binary object to be upserted. | +| config | [Upsert.Config](#payload-v1-Upsert-Config) | | The configuration of the upsert request. | +| vectorizer | [Filter.Target](#payload-v1-Filter-Target) | | Filter target. | + + + + + ### Upsert.Request - Represent the upsert request. -| Field | Type | Label | Description | -| ------ | ------------------------------------------ | ----- | ---------------------------------------- | -| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be upserted. | -| config | [Upsert.Config](#payload-v1-Upsert-Config) | | The configuration of the upsert request. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| vector | [Object.Vector](#payload-v1-Object-Vector) | | The vector to be upserted. | +| config | [Upsert.Config](#payload-v1-Upsert-Config) | | The configuration of the upsert request. | + + + + + + + ### Remove.Timestamp.Operator - Operator is enum of each conditional operator. -| Name | Number | Description | -| ---- | ------ | ----------------------------------------------------------------------------- | -| Eq | 0 | The timestamp is equal to the specified value in the request. | -| Ne | 1 | The timestamp is not equal to the specified value in the request. | -| Ge | 2 | The timestamp is greater than or equal to the specified value in the request. | -| Gt | 3 | The timestamp is greater than the specified value in the request. | -| Le | 4 | The timestamp is less than or equal to the specified value in the request. | -| Lt | 5 | The timestamp is less than the specified value in the request. | +| Name | Number | Description | +| ---- | ------ | ----------- | +| Eq | 0 | The timestamp is equal to the specified value in the request. | +| Ne | 1 | The timestamp is not equal to the specified value in the request. | +| Ge | 2 | The timestamp is greater than or equal to the specified value in the request. | +| Gt | 3 | The timestamp is greater than the specified value in the request. | +| Le | 4 | The timestamp is less than or equal to the specified value in the request. | +| Lt | 5 | The timestamp is less than the specified value in the request. | + + ### Search.AggregationAlgorithm - AggregationAlgorithm is enum of each aggregation algorithms -| Name | Number | Description | -| --------------- | ------ | ----------- | -| Unknown | 0 | | -| ConcurrentQueue | 1 | | -| SortSlice | 2 | | -| SortPoolSlice | 3 | | -| PairingHeap | 4 | | +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | | +| ConcurrentQueue | 1 | | +| SortSlice | 2 | | +| SortPoolSlice | 3 | | +| PairingHeap | 4 | | - + + + + + + + + +

Top

## v1/agent/core/agent.proto + + + + + + + + ### Agent - Represent the agent service. -| Method Name | Request Type | Response Type | Description | -| ------------------ | -------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------- | -| CreateIndex | [.payload.v1.Control.CreateIndexRequest](#payload-v1-Control-CreateIndexRequest) | [.payload.v1.Empty](#payload-v1-Empty) | Represent the creating index RPC. | -| SaveIndex | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Empty](#payload-v1-Empty) | Represent the saving index RPC. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| CreateIndex | [.payload.v1.Control.CreateIndexRequest](#payload-v1-Control-CreateIndexRequest) | [.payload.v1.Empty](#payload-v1-Empty) | Represent the creating index RPC. | +| SaveIndex | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Empty](#payload-v1-Empty) | Represent the saving index RPC. | | CreateAndSaveIndex | [.payload.v1.Control.CreateIndexRequest](#payload-v1-Control-CreateIndexRequest) | [.payload.v1.Empty](#payload-v1-Empty) | Represent the creating and saving index RPC. | - + + + +

Top

## v1/agent/sidecar/sidecar.proto + + + + + + + + ### Sidecar - Represent the agent sidecar service. | Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ----------- | +| ----------- | ------------ | ------------- | ------------| + + + - +

Top

## v1/discoverer/discoverer.proto + + + + + + + + ### Discoverer +Represent the discoverer service. + +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Pods | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Pods](#payload-v1-Info-Pods) | Represent the RPC to get the agent pods information. | +| Nodes | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Nodes](#payload-v1-Info-Nodes) | Represent the RPC to get the node information. | +| Services | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Services](#payload-v1-Info-Services) | Represent the RPC to get the readreplica svc information. | + + + + + + +

Top

+ +## v1/filter/egress/egress_filter.proto -Represent the discoverer service. -| Method Name | Request Type | Response Type | Description | -| ----------- | ---------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- | -| Pods | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Pods](#payload-v1-Info-Pods) | Represent the RPC to get the agent pods information. | -| Nodes | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Nodes](#payload-v1-Info-Nodes) | Represent the RPC to get the node information. | -| Services | [.payload.v1.Discoverer.Request](#payload-v1-Discoverer-Request) | [.payload.v1.Info.Services](#payload-v1-Info-Services) | Represent the RPC to get the readreplica svc information. | + - + -

Top

+ -## v1/filter/egress/egress_filter.proto ### Filter - Represent the egress filter service. -| Method Name | Request Type | Response Type | Description | -| -------------- | ---------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------- | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| | FilterDistance | [.payload.v1.Object.Distance](#payload-v1-Object-Distance) | [.payload.v1.Object.Distance](#payload-v1-Object-Distance) | Represent the RPC to filter the distance. | -| FilterVector | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to filter the vector. | +| FilterVector | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to filter the vector. | - + + + +

Top

## v1/filter/ingress/ingress_filter.proto + + + + + + + + ### Filter - Represent the ingress filter service. -| Method Name | Request Type | Response Type | Description | -| ------------ | ------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------- | -| GenVector | [.payload.v1.Object.Blob](#payload-v1-Object-Blob) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to generate the vector. | -| FilterVector | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to filter the vector. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| GenVector | [.payload.v1.Object.Blob](#payload-v1-Object-Blob) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to generate the vector. | +| FilterVector | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | Represent the RPC to filter the vector. | + + - + +

Top

## v1/meta/meta.proto + + + + + + + + ### Meta -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------------------------------------------------ | ------------------------------------------------ | ----------- | -| Get | [.payload.v1.Meta.Key](#payload-v1-Meta-Key) | [.payload.v1.Meta.Value](#payload-v1-Meta-Value) | | -| Set | [.payload.v1.Meta.KeyValue](#payload-v1-Meta-KeyValue) | [.payload.v1.Empty](#payload-v1-Empty) | | -| Delete | [.payload.v1.Meta.Key](#payload-v1-Meta-Key) | [.payload.v1.Empty](#payload-v1-Empty) | | - +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Get | [.payload.v1.Meta.Key](#payload-v1-Meta-Key) | [.payload.v1.Meta.Value](#payload-v1-Meta-Value) | | +| Set | [.payload.v1.Meta.KeyValue](#payload-v1-Meta-KeyValue) | [.payload.v1.Empty](#payload-v1-Empty) | | +| Delete | [.payload.v1.Meta.Key](#payload-v1-Meta-Key) | [.payload.v1.Empty](#payload-v1-Empty) | | + + + + +

Top

## v1/mirror/mirror.proto - Copyright (C) 2019-2024 vdaas.org vald team <vald@vdaas.org> 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 + 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, @@ -1379,75 +1979,100 @@ 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. + + + + + + + ### Mirror - Represent the mirror service. -| Method Name | Request Type | Response Type | Description | -| ----------- | -------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------- | -| Register | [.payload.v1.Mirror.Targets](#payload-v1-Mirror-Targets) | [.payload.v1.Mirror.Targets](#payload-v1-Mirror-Targets) | Register is the RPC to register other mirror servers. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Register | [.payload.v1.Mirror.Targets](#payload-v1-Mirror-Targets) | [.payload.v1.Mirror.Targets](#payload-v1-Mirror-Targets) | Register is the RPC to register other mirror servers. | + + - + +

Top

## v1/rpc/errdetails/error_details.proto + + ### BadRequest - Describes violations in a client request. This error type focuses on the syntactic aspects of the request. -| Field | Type | Label | Description | -| ---------------- | -------------------------------------------------------------- | -------- | --------------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | field_violations | [BadRequest.FieldViolation](#rpc-v1-BadRequest-FieldViolation) | repeated | Describes all violations in a client request. | + + + + + ### BadRequest.FieldViolation - A message type used to describe a single bad request field. -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| field | [string](#string) | | A path that leads to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| field | [string](#string) | | A path that leads to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. Consider the following: -message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } + message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } -optional string email = 1; repeated EmailType type = 2; } + optional string email = 1; repeated EmailType type = 2; } -string full_name = 1; repeated EmailAddress email_addresses = 2; } + string full_name = 1; repeated EmailAddress email_addresses = 2; } In this example, in proto `field` could take one of the following values: -- `full_name` for a violation in the `full_name` value _ `email_addresses[1].email` for a violation in the `email` field of the first `email_addresses` message _ `email_addresses[3].type[2]` for a violation in the second `type` value in the third `email_addresses` message. +* `full_name` for a violation in the `full_name` value * `email_addresses[1].email` for a violation in the `email` field of the first `email_addresses` message * `email_addresses[3].type[2]` for a violation in the second `type` value in the third `email_addresses` message. In JSON, the same values are represented as: -- `fullName` for a violation in the `fullName` value _ `emailAddresses[1].email` for a violation in the `email` field of the first `emailAddresses` message _ `emailAddresses[3].type[2]` for a violation in the second `type` value in the third `emailAddresses` message. | - | description | [string](#string) | | A description of why the request element is bad. | +* `fullName` for a violation in the `fullName` value * `emailAddresses[1].email` for a violation in the `email` field of the first `emailAddresses` message * `emailAddresses[3].type[2]` for a violation in the second `type` value in the third `emailAddresses` message. | +| description | [string](#string) | | A description of why the request element is bad. | + + + + + ### DebugInfo - Describes additional debugging info. -| Field | Type | Label | Description | -| ------------- | ----------------- | -------- | ------------------------------------------------------------ | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | stack_entries | [string](#string) | repeated | The stack trace entries indicating where the error occurred. | -| detail | [string](#string) | | Additional debugging information provided by the server. | +| detail | [string](#string) | | Additional debugging information provided by the server. | + + + + + ### ErrorInfo - Describes the cause of the error with structured details. Example of an error when contacting the "pubsub.googleapis.com" API when it @@ -1473,97 +2098,134 @@ instance in a region that is out of stock: } } -| Field | Type | Label | Description | -| -------- | ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| reason | [string](#string) | | The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique within a particular domain of errors. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. | -| domain | [string](#string) | | The logical grouping to which the "reason" belongs. The error domain is typically the registered service name of the tool or product that generates the error. Example: "pubsub.googleapis.com". If the error is generated by some common infrastructure, the error domain must be a globally unique value that identifies the infrastructure. For Google API infrastructure, the error domain is "googleapis.com". | -| metadata | [ErrorInfo.MetadataEntry](#rpc-v1-ErrorInfo-MetadataEntry) | repeated | Additional structured details about this error. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| reason | [string](#string) | | The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique within a particular domain of errors. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. | +| domain | [string](#string) | | The logical grouping to which the "reason" belongs. The error domain is typically the registered service name of the tool or product that generates the error. Example: "pubsub.googleapis.com". If the error is generated by some common infrastructure, the error domain must be a globally unique value that identifies the infrastructure. For Google API infrastructure, the error domain is "googleapis.com". | +| metadata | [ErrorInfo.MetadataEntry](#rpc-v1-ErrorInfo-MetadataEntry) | repeated | Additional structured details about this error. Keys should match /[a-zA-Z0-9-_]/ and be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than {"instanceLimit": "100/request"}, should be returned as, {"instanceLimitPerRequest": "100"}, if the client exceeds the number of instances that can be created in a single (batch) request. | + + + + + ### ErrorInfo.MetadataEntry -| Field | Type | Label | Description | -| ----- | ----------------- | ----- | ----------- | -| key | [string](#string) | | | -| value | [string](#string) | | | + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [string](#string) | | | + + + + + ### Help - Provides links to documentation or for performing an out of band action. For example, if a quota check failed with an error indicating the calling project hasn't enabled the accessed service, this can contain a URL pointing directly to the right place in the developer console to flip the bit. -| Field | Type | Label | Description | -| ----- | ------------------------------ | -------- | ------------------------------------------------------------------------ | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | links | [Help.Link](#rpc-v1-Help-Link) | repeated | URL(s) pointing to additional information on handling the current error. | + + + + + ### Help.Link - Describes a URL link. -| Field | Type | Label | Description | -| ----------- | ----------------- | ----- | ------------------------------- | -| description | [string](#string) | | Describes what the link offers. | -| url | [string](#string) | | The URL of the link. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| description | [string](#string) | | Describes what the link offers. | +| url | [string](#string) | | The URL of the link. | + + + + + ### LocalizedMessage - Provides a localized error message that is safe to return to the user which can be attached to an RPC error. -| Field | Type | Label | Description | -| ------- | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| locale | [string](#string) | | The locale used following the specification defined at https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Examples are: "en-US", "fr-CH", "es-MX" | -| message | [string](#string) | | The localized error message in the above locale. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| locale | [string](#string) | | The locale used following the specification defined at https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Examples are: "en-US", "fr-CH", "es-MX" | +| message | [string](#string) | | The localized error message in the above locale. | + + + + + ### PreconditionFailure - Describes what preconditions have failed. For example, if an RPC failed because it required the Terms of Service to be acknowledged, it could list the terms of service violation in the PreconditionFailure message. -| Field | Type | Label | Description | -| ---------- | ---------------------------------------------------------------------- | -------- | -------------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | violations | [PreconditionFailure.Violation](#rpc-v1-PreconditionFailure-Violation) | repeated | Describes all precondition violations. | + + + + + ### PreconditionFailure.Violation - A message type used to describe a single precondition failure. -| Field | Type | Label | Description | -| ----------- | ----------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | [string](#string) | | The type of PreconditionFailure. We recommend using a service-specific enum type to define the supported precondition violation subjects. For example, "TOS" for "Terms of Service violation". | -| subject | [string](#string) | | The subject, relative to the type, that failed. For example, "google.com/cloud" relative to the "TOS" type would indicate which terms of service is being referenced. | -| description | [string](#string) | | A description of how the precondition failed. Developers can use this description to understand how to fix the failure. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type | [string](#string) | | The type of PreconditionFailure. We recommend using a service-specific enum type to define the supported precondition violation subjects. For example, "TOS" for "Terms of Service violation". | +| subject | [string](#string) | | The subject, relative to the type, that failed. For example, "google.com/cloud" relative to the "TOS" type would indicate which terms of service is being referenced. | +| description | [string](#string) | | A description of how the precondition failed. Developers can use this description to understand how to fix the failure. For example: "Terms of service not accepted". | + + + + + ### QuotaFailure - Describes how a quota check failed. For example if a daily limit was exceeded for the calling project, a service could respond with a QuotaFailure detail containing the project -id and the description of the quota limit that was exceeded. If the +id and the description of the quota limit that was exceeded. If the calling project hasn't enabled the service in the developer console, then a service could respond with the project id and set `service_disabled` to true. @@ -1571,53 +2233,73 @@ to true. Also see RetryInfo and Help types for other details about handling a quota failure. -| Field | Type | Label | Description | -| ---------- | -------------------------------------------------------- | -------- | ------------------------------- | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | | violations | [QuotaFailure.Violation](#rpc-v1-QuotaFailure-Violation) | repeated | Describes all quota violations. | + + + + + ### QuotaFailure.Violation - -A message type used to describe a single quota violation. For example, a +A message type used to describe a single quota violation. For example, a daily quota or a custom quota that was exceeded. -| Field | Type | Label | Description | -| ----------- | ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| subject | [string](#string) | | The subject on which the quota check failed. For example, "clientip:<ip address of client>" or "project:<Google developer project id>". | -| description | [string](#string) | | A description of how the quota check failed. Clients can use this description to find more about the quota configuration in the service's public documentation, or find the relevant quota limit to adjust through developer console. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| subject | [string](#string) | | The subject on which the quota check failed. For example, "clientip:<ip address of client>" or "project:<Google developer project id>". | +| description | [string](#string) | | A description of how the quota check failed. Clients can use this description to find more about the quota configuration in the service's public documentation, or find the relevant quota limit to adjust through developer console. For example: "Service disabled" or "Daily Limit for read operations exceeded". | + + + + + ### RequestInfo - Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. -| Field | Type | Label | Description | -| ------------ | ----------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| request_id | [string](#string) | | An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. | -| serving_data | [string](#string) | | Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| request_id | [string](#string) | | An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. | +| serving_data | [string](#string) | | Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. | + + + + + ### ResourceInfo - Describes the resource that is being accessed. -| Field | Type | Label | Description | -| ------------- | ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| resource_type | [string](#string) | | A name for the type of resource being accessed, e.g. "sql table", "cloud storage bucket", "file", "Google calendar"; or the type URL of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". | -| resource_name | [string](#string) | | The name of the resource being accessed. For example, a shared calendar name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED]. | -| owner | [string](#string) | | The owner of the resource (optional). For example, "user:<owner email>" or "project:<Google developer project id>". | -| description | [string](#string) | | Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the `writer` permission on the developer console project. | + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| resource_type | [string](#string) | | A name for the type of resource being accessed, e.g. "sql table", "cloud storage bucket", "file", "Google calendar"; or the type URL of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". | +| resource_name | [string](#string) | | The name of the resource being accessed. For example, a shared calendar name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED]. | +| owner | [string](#string) | | The owner of the resource (optional). For example, "user:<owner email>" or "project:<Google developer project id>". | +| description | [string](#string) | | Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the `writer` permission on the developer console project. | + + + + + ### RetryInfo - Describes when the clients can retry a failed request. Clients could ignore the recommendation here or retry when this information is missing from error responses. @@ -1626,216 +2308,322 @@ It's always recommended that clients should use exponential backoff when retrying. Clients should wait until `retry_delay` amount of time has passed since -receiving the error response before retrying. If retrying requests also +receiving the error response before retrying. If retrying requests also fail, clients should use an exponential backoff scheme to gradually increase the delay between retries based on `retry_delay`, until either a maximum number of retries have been reached or a maximum retry delay cap has been reached. -| Field | Type | Label | Description | -| ----------- | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------- | -| retry_delay | [google.protobuf.Duration](#google-protobuf-Duration) | | Clients should wait at least this long between retrying the same request. | - +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| retry_delay | [google.protobuf.Duration](#google-protobuf-Duration) | | Clients should wait at least this long between retrying the same request. | + + + + + + + + + + + + + + +

Top

## v1/vald/filter.proto + + + + + + + + ### Filter - Filter service provides ways to connect to Vald through filter. -| Method Name | Request Type | Response Type | Description | -| ------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| SearchObject | [.payload.v1.Search.ObjectRequest](#payload-v1-Search-ObjectRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search object. | -| MultiSearchObject | [.payload.v1.Search.MultiObjectRequest](#payload-v1-Search-MultiObjectRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search multiple objects. | -| StreamSearchObject | [.payload.v1.Search.ObjectRequest](#payload-v1-Search-ObjectRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search object by bidirectional streaming. | -| InsertObject | [.payload.v1.Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method insert object. | -| StreamInsertObject | [.payload.v1.Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | Represent the streaming RPC to insert object by bidirectional streaming. | -| MultiInsertObject | [.payload.v1.Insert.MultiObjectRequest](#payload-v1-Insert-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to insert multiple objects. | -| UpdateObject | [.payload.v1.Update.ObjectRequest](#payload-v1-Update-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update object. | -| StreamUpdateObject | [.payload.v1.Update.ObjectRequest](#payload-v1-Update-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to update object by bidirectional streaming. | -| MultiUpdateObject | [.payload.v1.Update.MultiObjectRequest](#payload-v1-Update-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to update multiple objects. | -| UpsertObject | [.payload.v1.Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to upsert object. | -| StreamUpsertObject | [.payload.v1.Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to upsert object by bidirectional streaming. | -| MultiUpsertObject | [.payload.v1.Upsert.MultiObjectRequest](#payload-v1-Upsert-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to upsert multiple objects. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| SearchObject | [.payload.v1.Search.ObjectRequest](#payload-v1-Search-ObjectRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search object. | +| MultiSearchObject | [.payload.v1.Search.MultiObjectRequest](#payload-v1-Search-MultiObjectRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search multiple objects. | +| StreamSearchObject | [.payload.v1.Search.ObjectRequest](#payload-v1-Search-ObjectRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search object by bidirectional streaming. | +| InsertObject | [.payload.v1.Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method insert object. | +| StreamInsertObject | [.payload.v1.Insert.ObjectRequest](#payload-v1-Insert-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | Represent the streaming RPC to insert object by bidirectional streaming. | +| MultiInsertObject | [.payload.v1.Insert.MultiObjectRequest](#payload-v1-Insert-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to insert multiple objects. | +| UpdateObject | [.payload.v1.Update.ObjectRequest](#payload-v1-Update-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update object. | +| StreamUpdateObject | [.payload.v1.Update.ObjectRequest](#payload-v1-Update-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to update object by bidirectional streaming. | +| MultiUpdateObject | [.payload.v1.Update.MultiObjectRequest](#payload-v1-Update-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to update multiple objects. | +| UpsertObject | [.payload.v1.Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to upsert object. | +| StreamUpsertObject | [.payload.v1.Upsert.ObjectRequest](#payload-v1-Upsert-ObjectRequest) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to upsert object by bidirectional streaming. | +| MultiUpsertObject | [.payload.v1.Upsert.MultiObjectRequest](#payload-v1-Upsert-MultiObjectRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to upsert multiple objects. | + + - + +

Top

## v1/vald/flush.proto + + + + + + + + ### Flush - Flush service provides ways to flush all indexed vectors. -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------- | -| Flush | [.payload.v1.Flush.Request](#payload-v1-Flush-Request) | [.payload.v1.Info.Index.Count](#payload-v1-Info-Index-Count) | A method to flush all indexed vector. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Flush | [.payload.v1.Flush.Request](#payload-v1-Flush-Request) | [.payload.v1.Info.Index.Count](#payload-v1-Info-Index-Count) | A method to flush all indexed vector. | - + + + +

Top

## v1/vald/index.proto + + + + + + + + ### Index - Represent the index manager service. -| Method Name | Request Type | Response Type | Description | -| --------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------- | -| IndexInfo | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Count](#payload-v1-Info-Index-Count) | Represent the RPC to get the index information. | -| IndexDetail | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Detail](#payload-v1-Info-Index-Detail) | Represent the RPC to get the index information for each agents. | -| IndexStatistics | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Statistics](#payload-v1-Info-Index-Statistics) | Represent the RPC to get the index statistics. | -| IndexStatisticsDetail | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.StatisticsDetail](#payload-v1-Info-Index-StatisticsDetail) | Represent the RPC to get the index statistics for each agents. | -| IndexProperty | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.PropertyDetail](#payload-v1-Info-Index-PropertyDetail) | Represent the RPC to get the index property. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| IndexInfo | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Count](#payload-v1-Info-Index-Count) | Represent the RPC to get the index information. | +| IndexDetail | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Detail](#payload-v1-Info-Index-Detail) | Represent the RPC to get the index information for each agents. | +| IndexStatistics | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.Statistics](#payload-v1-Info-Index-Statistics) | Represent the RPC to get the index statistics. | +| IndexStatisticsDetail | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.StatisticsDetail](#payload-v1-Info-Index-StatisticsDetail) | Represent the RPC to get the index statistics for each agents. | +| IndexProperty | [.payload.v1.Empty](#payload-v1-Empty) | [.payload.v1.Info.Index.PropertyDetail](#payload-v1-Info-Index-PropertyDetail) | Represent the RPC to get the index property. | + + - + +

Top

## v1/vald/insert.proto + + + + + + + + ### Insert - Insert service provides ways to add new vectors. -| Method Name | Request Type | Response Type | Description | -| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| Insert | [.payload.v1.Insert.Request](#payload-v1-Insert-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to add a new single vector. | -| StreamInsert | [.payload.v1.Insert.Request](#payload-v1-Insert-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to add new multiple vectors by bidirectional streaming. | -| MultiInsert | [.payload.v1.Insert.MultiRequest](#payload-v1-Insert-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to add new multiple vectors in a single request. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Insert | [.payload.v1.Insert.Request](#payload-v1-Insert-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to add a new single vector. | +| StreamInsert | [.payload.v1.Insert.Request](#payload-v1-Insert-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to add new multiple vectors by bidirectional streaming. | +| MultiInsert | [.payload.v1.Insert.MultiRequest](#payload-v1-Insert-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to add new multiple vectors in a single request. | + + + - +

Top

## v1/vald/object.proto + + + + + + + + ### Object - Object service provides ways to fetch indexed vectors. -| Method Name | Request Type | Response Type | Description | -| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| Exists | [.payload.v1.Object.ID](#payload-v1-Object-ID) | [.payload.v1.Object.ID](#payload-v1-Object-ID) | A method to check whether a specified ID is indexed or not. | -| GetObject | [.payload.v1.Object.VectorRequest](#payload-v1-Object-VectorRequest) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | A method to fetch a vector. | -| StreamGetObject | [.payload.v1.Object.VectorRequest](#payload-v1-Object-VectorRequest) stream | [.payload.v1.Object.StreamVector](#payload-v1-Object-StreamVector) stream | A method to fetch vectors by bidirectional streaming. | -| StreamListObject | [.payload.v1.Object.List.Request](#payload-v1-Object-List-Request) | [.payload.v1.Object.List.Response](#payload-v1-Object-List-Response) stream | A method to get all the vectors with server streaming | -| GetTimestamp | [.payload.v1.Object.TimestampRequest](#payload-v1-Object-TimestampRequest) | [.payload.v1.Object.Timestamp](#payload-v1-Object-Timestamp) | Represent the RPC to get the vector metadata. This RPC is mainly used for index correction process | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Exists | [.payload.v1.Object.ID](#payload-v1-Object-ID) | [.payload.v1.Object.ID](#payload-v1-Object-ID) | A method to check whether a specified ID is indexed or not. | +| GetObject | [.payload.v1.Object.VectorRequest](#payload-v1-Object-VectorRequest) | [.payload.v1.Object.Vector](#payload-v1-Object-Vector) | A method to fetch a vector. | +| StreamGetObject | [.payload.v1.Object.VectorRequest](#payload-v1-Object-VectorRequest) stream | [.payload.v1.Object.StreamVector](#payload-v1-Object-StreamVector) stream | A method to fetch vectors by bidirectional streaming. | +| StreamListObject | [.payload.v1.Object.List.Request](#payload-v1-Object-List-Request) | [.payload.v1.Object.List.Response](#payload-v1-Object-List-Response) stream | A method to get all the vectors with server streaming | +| GetTimestamp | [.payload.v1.Object.TimestampRequest](#payload-v1-Object-TimestampRequest) | [.payload.v1.Object.Timestamp](#payload-v1-Object-Timestamp) | Represent the RPC to get the vector metadata. This RPC is mainly used for index correction process | + + - + +

Top

## v1/vald/remove.proto + + + + + + + + ### Remove - Remove service provides ways to remove indexed vectors. -| Method Name | Request Type | Response Type | Description | -| ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| Remove | [.payload.v1.Remove.Request](#payload-v1-Remove-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to remove an indexed vector. | -| RemoveByTimestamp | [.payload.v1.Remove.TimestampRequest](#payload-v1-Remove-TimestampRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to remove an indexed vector based on timestamp. | -| StreamRemove | [.payload.v1.Remove.Request](#payload-v1-Remove-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to remove multiple indexed vectors by bidirectional streaming. | -| MultiRemove | [.payload.v1.Remove.MultiRequest](#payload-v1-Remove-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to remove multiple indexed vectors in a single request. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Remove | [.payload.v1.Remove.Request](#payload-v1-Remove-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to remove an indexed vector. | +| RemoveByTimestamp | [.payload.v1.Remove.TimestampRequest](#payload-v1-Remove-TimestampRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to remove an indexed vector based on timestamp. | +| StreamRemove | [.payload.v1.Remove.Request](#payload-v1-Remove-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to remove multiple indexed vectors by bidirectional streaming. | +| MultiRemove | [.payload.v1.Remove.MultiRequest](#payload-v1-Remove-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to remove multiple indexed vectors in a single request. | - + + + +

Top

## v1/vald/search.proto + + + + + + + + ### Search - Search service provides ways to search indexed vectors. -| Method Name | Request Type | Response Type | Description | -| ---------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| Search | [.payload.v1.Search.Request](#payload-v1-Search-Request) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search indexed vectors by a raw vector. | -| SearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search indexed vectors by ID. | -| StreamSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search indexed vectors by multiple vectors. | -| StreamSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search indexed vectors by multiple IDs. | -| MultiSearch | [.payload.v1.Search.MultiRequest](#payload-v1-Search-MultiRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search indexed vectors by multiple vectors in a single request. | -| MultiSearchByID | [.payload.v1.Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search indexed vectors by multiple IDs in a single request. | -| LinearSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to linear search indexed vectors by a raw vector. | -| LinearSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to linear search indexed vectors by ID. | -| StreamLinearSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to linear search indexed vectors by multiple vectors. | -| StreamLinearSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to linear search indexed vectors by multiple IDs. | -| MultiLinearSearch | [.payload.v1.Search.MultiRequest](#payload-v1-Search-MultiRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to linear search indexed vectors by multiple vectors in a single request. | -| MultiLinearSearchByID | [.payload.v1.Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to linear search indexed vectors by multiple IDs in a single request. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Search | [.payload.v1.Search.Request](#payload-v1-Search-Request) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search indexed vectors by a raw vector. | +| SearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to search indexed vectors by ID. | +| StreamSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search indexed vectors by multiple vectors. | +| StreamSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to search indexed vectors by multiple IDs. | +| MultiSearch | [.payload.v1.Search.MultiRequest](#payload-v1-Search-MultiRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search indexed vectors by multiple vectors in a single request. | +| MultiSearchByID | [.payload.v1.Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to search indexed vectors by multiple IDs in a single request. | +| LinearSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to linear search indexed vectors by a raw vector. | +| LinearSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) | [.payload.v1.Search.Response](#payload-v1-Search-Response) | A method to linear search indexed vectors by ID. | +| StreamLinearSearch | [.payload.v1.Search.Request](#payload-v1-Search-Request) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to linear search indexed vectors by multiple vectors. | +| StreamLinearSearchByID | [.payload.v1.Search.IDRequest](#payload-v1-Search-IDRequest) stream | [.payload.v1.Search.StreamResponse](#payload-v1-Search-StreamResponse) stream | A method to linear search indexed vectors by multiple IDs. | +| MultiLinearSearch | [.payload.v1.Search.MultiRequest](#payload-v1-Search-MultiRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to linear search indexed vectors by multiple vectors in a single request. | +| MultiLinearSearchByID | [.payload.v1.Search.MultiIDRequest](#payload-v1-Search-MultiIDRequest) | [.payload.v1.Search.Responses](#payload-v1-Search-Responses) | A method to linear search indexed vectors by multiple IDs in a single request. | + + - + +

Top

## v1/vald/update.proto + + + + + + + + ### Update - Update service provides ways to update indexed vectors. -| Method Name | Request Type | Response Type | Description | -| --------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| Update | [.payload.v1.Update.Request](#payload-v1-Update-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update an indexed vector. | -| StreamUpdate | [.payload.v1.Update.Request](#payload-v1-Update-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to update multiple indexed vectors by bidirectional streaming. | -| MultiUpdate | [.payload.v1.Update.MultiRequest](#payload-v1-Update-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to update multiple indexed vectors in a single request. | -| UpdateTimestamp | [.payload.v1.Update.TimestampRequest](#payload-v1-Update-TimestampRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update timestamp an indexed vector. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Update | [.payload.v1.Update.Request](#payload-v1-Update-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update an indexed vector. | +| StreamUpdate | [.payload.v1.Update.Request](#payload-v1-Update-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to update multiple indexed vectors by bidirectional streaming. | +| MultiUpdate | [.payload.v1.Update.MultiRequest](#payload-v1-Update-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to update multiple indexed vectors in a single request. | +| UpdateTimestamp | [.payload.v1.Update.TimestampRequest](#payload-v1-Update-TimestampRequest) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to update timestamp an indexed vector. | + + + - +

Top

## v1/vald/upsert.proto + + + + + + + + ### Upsert - Upsert service provides ways to insert/update vectors. -| Method Name | Request Type | Response Type | Description | -| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| Upsert | [.payload.v1.Upsert.Request](#payload-v1-Upsert-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to insert/update a vector. | -| StreamUpsert | [.payload.v1.Upsert.Request](#payload-v1-Upsert-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to insert/update multiple vectors by bidirectional streaming. | -| MultiUpsert | [.payload.v1.Upsert.MultiRequest](#payload-v1-Upsert-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to insert/update multiple vectors in a single request. | +| Method Name | Request Type | Response Type | Description | +| ----------- | ------------ | ------------- | ------------| +| Upsert | [.payload.v1.Upsert.Request](#payload-v1-Upsert-Request) | [.payload.v1.Object.Location](#payload-v1-Object-Location) | A method to insert/update a vector. | +| StreamUpsert | [.payload.v1.Upsert.Request](#payload-v1-Upsert-Request) stream | [.payload.v1.Object.StreamLocation](#payload-v1-Object-StreamLocation) stream | A method to insert/update multiple vectors by bidirectional streaming. | +| MultiUpsert | [.payload.v1.Upsert.MultiRequest](#payload-v1-Upsert-MultiRequest) | [.payload.v1.Object.Locations](#payload-v1-Object-Locations) | A method to insert/update multiple vectors in a single request. | + + + + ## Scalar Value Types -| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------- | ----------- | ------- | ---------- | -------------- | ------------------------------ | -| double | | double | double | float | float64 | double | float | Float | -| float | | float | float | float | float32 | float | float | Float | -| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | -| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | +| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | +| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | +| double | | double | double | float | float64 | double | float | Float | +| float | | float | float | float | float32 | float | float | Float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | +| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | +| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | +| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) | + diff --git a/apis/docs/v1/docs.md.tmpl b/apis/docs/v1/docs.md.tmpl deleted file mode 100644 index dcbd5f9096..0000000000 --- a/apis/docs/v1/docs.md.tmpl +++ /dev/null @@ -1,19 +0,0 @@ -{{range .Files}} - -# {{.Name}} document - -## Table of Contents -{{if .HasServices}} -- Services -{{range .Services}} - - [{{.Name}}]({{.Name}}) -{{end}} -{{end}} - -{{if .HasMessages}} -{{end}} - -{{if .HasEnums}} -{{end}} - -{{end}} \ No newline at end of file diff --git a/apis/docs/v1/filter.md b/apis/docs/v1/filter.md new file mode 100644 index 0000000000..31c3ff92a1 --- /dev/null +++ b/apis/docs/v1/filter.md @@ -0,0 +1,1863 @@ +# Vald Filter APIs + +## Overview + +Filter service provides ways to connect to Vald through filter. + +```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 + +A method to search 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Search.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + + + - Search.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + + - Object.Distance + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiSearchObject RPC + +A method to search multiple objects. + +### 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Search.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | + + + - Search.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + + + - Search.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + + + - Search.Response + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + + - Object.Distance + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## StreamSearchObject RPC + +A method to search object by bidirectional streaming. + +### 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Search.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + + + - Search.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + + + - Search.Response + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + + + - Object.Distance + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## InsertObject RPC + +A method insert object. + +### 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Insert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Insert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## StreamInsertObject RPC + +Represent the streaming RPC to insert object by bidirectional streaming. + +### Input + +- the scheme of `payload.v1.Insert.ObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Insert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Insert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiInsertObject RPC + +A method to insert multiple objects. + +### Input + +- the scheme of `payload.v1.Insert.MultiObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Insert.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | + + + - Insert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Insert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## UpdateObject RPC + +A method to update object. + +### 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Update.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Update.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## StreamUpdateObject RPC + +A method to update object by bidirectional streaming. + +### Input + +- the scheme of `payload.v1.Update.ObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Update.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Update.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiUpdateObject RPC + +A method to update multiple objects. + +### Input + +- the scheme of `payload.v1.Update.MultiObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Update.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | + + + - Update.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Update.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## UpsertObject RPC + +A method to upsert 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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Upsert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Upsert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## StreamUpsertObject RPC + +A method to upsert object by bidirectional streaming. + +### Input + +- the scheme of `payload.v1.Upsert.ObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Upsert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Upsert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiUpsertObject RPC + +A method to upsert multiple objects. + +### Input + +- the scheme of `payload.v1.Upsert.MultiObjectRequest` + + ```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.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + ``` + + - Upsert.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | + + + - Upsert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + + + - Object.Blob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The object ID. | + | object | bytes | | The binary object. | + + + + - Upsert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + + + - Object.Location + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + diff --git a/apis/docs/v1/flush.md b/apis/docs/v1/flush.md index fb5b4478bf..237c5f91c3 100644 --- a/apis/docs/v1/flush.md +++ b/apis/docs/v1/flush.md @@ -2,7 +2,7 @@ ## Overview -Flush Service is responsible for removing all vectors that are indexed and uncommitted in the `vald-agent`. +Flush service provides ways to flush all indexed vectors. ```rpc service Flush { @@ -14,16 +14,15 @@ service Flush { ## Flush RPC -Flush RPC is the method to remove all vectors. +A method to flush all indexed vector. ### Input - the scheme of `payload.v1.Flush.Request` ```rpc - message Flush { - message Request { - } + message Flush.Request { + // empty } ``` @@ -36,32 +35,31 @@ Flush RPC is the method to remove all vectors. - the scheme of `payload.v1.Info.Index.Count` ```rpc - message Object { - message Info_Index_Count { - uint32 stored = 0; - uint32 uncommitted = 0; - bool indexing = false; - bool saving = false; - } + message Info.Index.Count { + uint32 stored = 1; + uint32 uncommitted = 2; + bool indexing = 3; + bool saving = 4; } ``` - Object.Info_Index_Count + - Info.Index.Count - | field | type | label | desc. | - | :---------: | :----- | :---- | :------------------------------------------------------------------------- | - | stored | uint32 | | count of indices. | - | uncommitted | uint32 | | count of uncommitted indices. | - | indexing | bool | | the state indicating whether `vald-agent` pods is present in the indexing. | - | saving | bool | | the state indicating whether `vald-agent` pods is present in the saving. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | ### Status Code | code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + diff --git a/apis/docs/v1/index.md b/apis/docs/v1/index.md new file mode 100644 index 0000000000..194c979a66 --- /dev/null +++ b/apis/docs/v1/index.md @@ -0,0 +1,531 @@ +# 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 | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## IndexDetail RPC + +Represent the RPC to get the index information for each agents. + +### Input + +- the scheme of `payload.v1.Empty` + + ```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 | desc. | + | :---: | :--- | :---- | :---- | + | counts | Info.Index.Detail.CountsEntry | repeated | count infos for each agents | + | replica | uint32 | | index replica of vald cluster | + | live_agents | uint32 | | live agent replica of vald cluster | + + + - Info.Index.Detail.CountsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Count | | | + + + - Info.Index.Count + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## 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 | desc. | + | :---: | :--- | :---- | :---- | + | valid | bool | | | + | median_indegree | int32 | | | + | median_outdegree | int32 | | | + | max_number_of_indegree | uint64 | | | + | max_number_of_outdegree | uint64 | | | + | min_number_of_indegree | uint64 | | | + | min_number_of_outdegree | uint64 | | | + | mode_indegree | uint64 | | | + | mode_outdegree | uint64 | | | + | nodes_skipped_for_10_edges | uint64 | | | + | nodes_skipped_for_indegree_distance | uint64 | | | + | number_of_edges | uint64 | | | + | number_of_indexed_objects | uint64 | | | + | number_of_nodes | uint64 | | | + | number_of_nodes_without_edges | uint64 | | | + | number_of_nodes_without_indegree | uint64 | | | + | number_of_objects | uint64 | | | + | number_of_removed_objects | uint64 | | | + | size_of_object_repository | uint64 | | | + | size_of_refinement_object_repository | uint64 | | | + | variance_of_indegree | double | | | + | variance_of_outdegree | double | | | + | mean_edge_length | double | | | + | mean_edge_length_for_10_edges | double | | | + | mean_indegree_distance_for_10_edges | double | | | + | mean_number_of_edges_per_node | double | | | + | c1_indegree | double | | | + | c5_indegree | double | | | + | c95_outdegree | double | | | + | c99_outdegree | double | | | + | indegree_count | int64 | repeated | | + | outdegree_histogram | uint64 | repeated | | + | indegree_histogram | uint64 | repeated | | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## 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 | desc. | + | :---: | :--- | :---- | :---- | + | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | + + + - Info.Index.StatisticsDetail.DetailsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Statistics | | | + + + - Info.Index.Statistics + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | valid | bool | | | + | median_indegree | int32 | | | + | median_outdegree | int32 | | | + | max_number_of_indegree | uint64 | | | + | max_number_of_outdegree | uint64 | | | + | min_number_of_indegree | uint64 | | | + | min_number_of_outdegree | uint64 | | | + | mode_indegree | uint64 | | | + | mode_outdegree | uint64 | | | + | nodes_skipped_for_10_edges | uint64 | | | + | nodes_skipped_for_indegree_distance | uint64 | | | + | number_of_edges | uint64 | | | + | number_of_indexed_objects | uint64 | | | + | number_of_nodes | uint64 | | | + | number_of_nodes_without_edges | uint64 | | | + | number_of_nodes_without_indegree | uint64 | | | + | number_of_objects | uint64 | | | + | number_of_removed_objects | uint64 | | | + | size_of_object_repository | uint64 | | | + | size_of_refinement_object_repository | uint64 | | | + | variance_of_indegree | double | | | + | variance_of_outdegree | double | | | + | mean_edge_length | double | | | + | mean_edge_length_for_10_edges | double | | | + | mean_indegree_distance_for_10_edges | double | | | + | mean_number_of_edges_per_node | double | | | + | c1_indegree | double | | | + | c5_indegree | double | | | + | c95_outdegree | double | | | + | c99_outdegree | double | | | + | indegree_count | int64 | repeated | | + | outdegree_histogram | uint64 | repeated | | + | indegree_histogram | uint64 | repeated | | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## 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 | desc. | + | :---: | :--- | :---- | :---- | + | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | + + + - Info.Index.PropertyDetail.DetailsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Property | | | + + + - Info.Index.Property + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | dimension | int32 | | | + | thread_pool_size | int32 | | | + | object_type | string | | | + | distance_type | string | | | + | index_type | string | | | + | database_type | string | | | + | object_alignment | string | | | + | path_adjustment_interval | int32 | | | + | graph_shared_memory_size | int32 | | | + | tree_shared_memory_size | int32 | | | + | object_shared_memory_size | int32 | | | + | prefetch_offset | int32 | | | + | prefetch_size | int32 | | | + | accuracy_table | string | | | + | search_type | string | | | + | max_magnitude | float | | | + | n_of_neighbors_for_insertion_order | int32 | | | + | epsilon_for_insertion_order | float | | | + | refinement_object_type | string | | | + | truncation_threshold | int32 | | | + | edge_size_for_creation | int32 | | | + | edge_size_for_search | int32 | | | + | edge_size_limit_for_creation | int32 | | | + | insertion_radius_coefficient | double | | | + | seed_size | int32 | | | + | seed_type | string | | | + | truncation_thread_pool_size | int32 | | | + | batch_size_for_creation | int32 | | | + | graph_type | string | | | + | dynamic_edge_size_base | int32 | | | + | dynamic_edge_size_rate | int32 | | | + | build_time_limit | float | | | + | outgoing_edge | int32 | | | + | incoming_edge | int32 | | | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + diff --git a/apis/docs/v1/insert.md b/apis/docs/v1/insert.md index eae2bd7dce..5b72778a81 100644 --- a/apis/docs/v1/insert.md +++ b/apis/docs/v1/insert.md @@ -2,365 +2,392 @@ ## Overview -Insert Service is responsible for inserting new vectors into the `vald-agent`. +Insert service provides ways to add new vectors. ```rpc service Insert { - rpc Insert(payload.v1.Insert.Request) returns (payload.v1.Object.Location) {} - rpc StreamInsert(stream payload.v1.Insert.Request) returns (stream payload.v1.Object.Location) {} + 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) {} - rpc MultiInsert(payload.v1.Insert.MultiRequest) returns (payload.v1.Object.Locations) {} } ``` ## Insert RPC -Inset RPC is the method to add a new single vector. +A method to add a new single vector. ### Input - the scheme of `payload.v1.Insert.Request` ```rpc - message Insert { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 2; - int64 timestamp = 3; - } + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; } - message Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 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 | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.Location` ```rpc - message Object { - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; } ``` - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is inserted. | - | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamInsert RPC -### Troubleshooting +A method to add new multiple vectors by bidirectional streaming. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Insert.Request` -| 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 + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } -## 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. + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -### Input -- the scheme of `payload.v1.Insert.Request stream` - ```rpc - message Insert { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 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 Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Insert.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for the filter targets. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :--------------------------------------------------------------- | - | id | string | | \* | The ID of the vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.StreamLocation` ```rpc - message Object { - message StreamLocation { - oneof payload { - Location location = 1; - google.rpc.Status status = 2; - } - } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 information of `Object.Location` data. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 vald agent pod where the request vector is inserted. | - | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. | - - - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) + - Object.Location - | field | type | label | description | - | :-----: | :------------------ | :------------------- | :-------------------------------------- | - | code | int32 | | Status code (code list is next section) | - | message | string | | Error message | - | details | google.protobuf.Any | repeated(Array[any]) | The details error message list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiInsert RPC + +A method to add new multiple vectors in a single request. -Please refer to [Response Status Code](../status.md) for more details. +### Input -### Troubleshooting +- the scheme of `payload.v1.Insert.MultiRequest` -The request process may not be completed when the response code is NOT `0 (OK)`. + ```rpc + message Insert.MultiRequest { + repeated Insert.Request requests = 1; + } -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. | + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } -## MultiInsert RPC -MultiInsert RPC is the method to add multiple new vectors in **1** request. + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -
-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` + message Insert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + } - ```rpc - message Insert { - message MultiRequest { repeated Request requests = 1; } - - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 2; - int64 timestamp = 3; - } + + message Filter.Config { + repeated Filter.Target targets = 1; } - message Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Insert.MultiRequest - | field | type | label | required | description | - | :------: | :------------- | :------------------------------ | :------: | :---------------- | - | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | The request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Insert.Request | repeated | Represent multiple insert request content. | + - Insert.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the insert request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Insert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for the filter targets. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Object.Locations`. +- the scheme of `payload.v1.Object.Locations` ```rpc - message Object { - message Locations { repeated Location locations = 1; } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 | - | :------: | :-------------- | :------------------------------- | :----------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :--------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is inserted. | - | uuid | string | | The ID of the inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -| name | common reason | how to resolve | -| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | -| CANCELLED | Executed cancel() of rpc from client/server-side or network problems between client and server. | Check the code, especially around timeout and connection management, and fix if needed. | -| INVALID_ARGUMENT | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. | Check Agent config, request payload, and fix request payload or Agent config. | -| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side. | Check the gRPC timeout setting on both the client and server sides and fix it if needed. | -| ALREADY_EXISTS | Request ID is already inserted. | Change request ID. | -| INTERNAL | Target Vald cluster or network route has some critical error. | Check target Vald cluster first and check network route including ingress as second. | diff --git a/apis/docs/v1/object.md b/apis/docs/v1/object.md index a9e37ea9d0..e5839377e6 100644 --- a/apis/docs/v1/object.md +++ b/apis/docs/v1/object.md @@ -2,258 +2,388 @@ ## Overview -Object Service is responsible for getting inserted vectors and checking whether vectors are inserted into the `vald-agent`. +Object service provides ways to fetch indexed vectors. ```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 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) {} - rpc StreamGetObject(stream payload.v1.Object.VectorRequest) - returns (stream payload.v1.Object.StreamVector) {} } ``` ## Exists RPC -Exists RPC is the method to check that a vector exists in the `vald-agent`. +A method to check whether a specified ID is indexed or not. ### Input - the scheme of `payload.v1.Object.ID` ```rpc - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + message Object.ID { + string id = 1; } ``` - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | ### Output - the scheme of `payload.v1.Object.ID` ```rpc - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + message Object.ID { + string id = 1; } ``` - Object.ID - | field | type | label | description | - | :---: | :----- | :---- | :------------------------------------------------------------- | - | id | string | | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## GetObject RPC -### Troubleshooting +A method to fetch a vector. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Object.VectorRequest` -| 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 + message Object.VectorRequest { + Object.ID id = 1; + Filter.Config filters = 2; + } -## GetObject RPC -GetObject RPC is the method to get the metadata of a vector inserted into the `vald-agent`. + message Object.ID { + string id = 1; + } -### Input -- the scheme of `payload.v1.Object.VectorRequest` - ```rpc - message Object { - message VectorRequest { - ID id = 1 [ (validate.rules).repeated .min_items = 2 ]; - Filter.Config filters = 2; - } - - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Object.VectorRequest - | field | type | label | required | description | - | :-----: | :------------ | :---- | :------: | :------------------------------------------------------------- | - | id | Object.ID | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | filters | Filter.Config | | | Configuration for filter. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.Vector` ```rpc - message Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; } ``` - Object.Vector - | field | type | label | description | - | :----: | :----- | :--------------------- | :------------------------------------------------------------- | - | id | string | | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | The vector data. Its dimension is between 2 and 65,536. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamGetObject RPC -### Troubleshooting +A method to fetch vectors by bidirectional streaming. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Object.VectorRequest` -| 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 + message Object.VectorRequest { + Object.ID id = 1; + Filter.Config filters = 2; + } -## 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. + message Object.ID { + string id = 1; + } -- the scheme of `payload.v1.Object.VectorRequest stream` - ```rpc - message Object { - message VectorRequest { - ID id = 1 [ (validate.rules).repeated .min_items = 2 ]; - Filter.Config filters = 2; - } - - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Object.VectorRequest - | field | type | label | required | description | - | :-----: | :------------ | :---- | :------: | :------------------------------------------------------------- | - | id | Object.ID | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | filters | Filter.Config | | | Configuration for the filter targets. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.StreamVector` ```rpc - message Object { - message StreamVector { - oneof payload { - Vector vector = 1; - google.rpc.Status status = 2; - } - } - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + 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 | Vector | | The information of Object.Vector data. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector. | + | status | google.rpc.Status | | The RPC error status. | + - Object.Vector - | field | type | label | description | - | :----: | :----- | :--------------------- | :------------------------------------------------------------- | - | id | string | | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | The vector data. Its dimension is between 2 and 65,536. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamListObject RPC -### Troubleshooting +A method to get all the vectors with server streaming -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input + +- the scheme of `payload.v1.Object.List.Request` + + ```rpc + message Object.List.Request { + // empty + } + ``` -Here are some common reasons and how to resolve each error. + - 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 | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector | + | status | google.rpc.Status | | The RPC error status. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## GetTimestamp RPC + +Represent the RPC to get the vector metadata. This RPC is mainly used for index correction process + +### Input + +- the scheme of `payload.v1.Object.TimestampRequest` + + ```rpc + message Object.TimestampRequest { + Object.ID id = 1; + } + + + message Object.ID { + string id = 1; + } + ``` + + - Object.TimestampRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + + + - Object.ID + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -| 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/payload.md.tmpl b/apis/docs/v1/payload.md.tmpl new file mode 100644 index 0000000000..10852851bf --- /dev/null +++ b/apis/docs/v1/payload.md.tmpl @@ -0,0 +1,2129 @@ +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Filter.Config" }} + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + +{{ template "field.payload.v1.Filter.Target" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Info.Annotations.AnnotationsEntry" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Annotations" }} + - Info.Annotations + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | annotations | Info.Annotations.AnnotationsEntry | repeated | | + +{{ template "field.payload.v1.Info.Annotations.AnnotationsEntry" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | stored | uint32 | | The stored index count. | + | uncommitted | uint32 | | The uncommitted index count. | + | indexing | bool | | The indexing index count. | + | saving | bool | | The saving index count. | +{{- 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; + } + +{{ template "scheme.payload.v1.Info.Index.Detail.CountsEntry" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.Detail" }} + - Info.Index.Detail + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | counts | Info.Index.Detail.CountsEntry | repeated | count infos for each agents | + | replica | uint32 | | index replica of vald cluster | + | live_agents | uint32 | | live agent replica of vald cluster | + +{{ template "field.payload.v1.Info.Index.Detail.CountsEntry" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Info.Index.Detail.CountsEntry" }} + message Info.Index.Detail.CountsEntry { + string key = 1; + Info.Index.Count value = 2; + } + +{{ template "scheme.payload.v1.Info.Index.Count" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.Detail.CountsEntry" }} + - Info.Index.Detail.CountsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Count | | | + +{{ template "field.payload.v1.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 | desc. | + | :---: | :--- | :---- | :---- | + | dimension | int32 | | | + | thread_pool_size | int32 | | | + | object_type | string | | | + | distance_type | string | | | + | index_type | string | | | + | database_type | string | | | + | object_alignment | string | | | + | path_adjustment_interval | int32 | | | + | graph_shared_memory_size | int32 | | | + | tree_shared_memory_size | int32 | | | + | object_shared_memory_size | int32 | | | + | prefetch_offset | int32 | | | + | prefetch_size | int32 | | | + | accuracy_table | string | | | + | search_type | string | | | + | max_magnitude | float | | | + | n_of_neighbors_for_insertion_order | int32 | | | + | epsilon_for_insertion_order | float | | | + | refinement_object_type | string | | | + | truncation_threshold | int32 | | | + | edge_size_for_creation | int32 | | | + | edge_size_for_search | int32 | | | + | edge_size_limit_for_creation | int32 | | | + | insertion_radius_coefficient | double | | | + | seed_size | int32 | | | + | seed_type | string | | | + | truncation_thread_pool_size | int32 | | | + | batch_size_for_creation | int32 | | | + | graph_type | string | | | + | dynamic_edge_size_base | int32 | | | + | dynamic_edge_size_rate | int32 | | | + | build_time_limit | float | | | + | outgoing_edge | int32 | | | + | incoming_edge | int32 | | | +{{- end -}} + +{{- define "scheme.payload.v1.Info.Index.PropertyDetail" }} + message Info.Index.PropertyDetail { + repeated Info.Index.PropertyDetail.DetailsEntry details = 1; + } + +{{ template "scheme.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.PropertyDetail" }} + - Info.Index.PropertyDetail + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | details | Info.Index.PropertyDetail.DetailsEntry | repeated | | + +{{ template "field.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + message Info.Index.PropertyDetail.DetailsEntry { + string key = 1; + Info.Index.Property value = 2; + } + +{{ template "scheme.payload.v1.Info.Index.Property" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.PropertyDetail.DetailsEntry" }} + - Info.Index.PropertyDetail.DetailsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Property | | | + +{{ template "field.payload.v1.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 | desc. | + | :---: | :--- | :---- | :---- | + | valid | bool | | | + | median_indegree | int32 | | | + | median_outdegree | int32 | | | + | max_number_of_indegree | uint64 | | | + | max_number_of_outdegree | uint64 | | | + | min_number_of_indegree | uint64 | | | + | min_number_of_outdegree | uint64 | | | + | mode_indegree | uint64 | | | + | mode_outdegree | uint64 | | | + | nodes_skipped_for_10_edges | uint64 | | | + | nodes_skipped_for_indegree_distance | uint64 | | | + | number_of_edges | uint64 | | | + | number_of_indexed_objects | uint64 | | | + | number_of_nodes | uint64 | | | + | number_of_nodes_without_edges | uint64 | | | + | number_of_nodes_without_indegree | uint64 | | | + | number_of_objects | uint64 | | | + | number_of_removed_objects | uint64 | | | + | size_of_object_repository | uint64 | | | + | size_of_refinement_object_repository | uint64 | | | + | variance_of_indegree | double | | | + | variance_of_outdegree | double | | | + | mean_edge_length | double | | | + | mean_edge_length_for_10_edges | double | | | + | mean_indegree_distance_for_10_edges | double | | | + | mean_number_of_edges_per_node | double | | | + | c1_indegree | double | | | + | c5_indegree | double | | | + | c95_outdegree | double | | | + | c99_outdegree | double | | | + | indegree_count | int64 | repeated | | + | outdegree_histogram | uint64 | repeated | | + | indegree_histogram | uint64 | repeated | | +{{- end -}} + +{{- define "scheme.payload.v1.Info.Index.StatisticsDetail" }} + message Info.Index.StatisticsDetail { + repeated Info.Index.StatisticsDetail.DetailsEntry details = 1; + } + +{{ template "scheme.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.StatisticsDetail" }} + - Info.Index.StatisticsDetail + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | details | Info.Index.StatisticsDetail.DetailsEntry | repeated | count infos for each agents | + +{{ template "field.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + message Info.Index.StatisticsDetail.DetailsEntry { + string key = 1; + Info.Index.Statistics value = 2; + } + +{{ template "scheme.payload.v1.Info.Index.Statistics" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Index.StatisticsDetail.DetailsEntry" }} + - Info.Index.StatisticsDetail.DetailsEntry + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | + | value | Info.Index.Statistics | | | + +{{ template "field.payload.v1.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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | uuid | string | | | +{{- end -}} + +{{- define "scheme.payload.v1.Info.Labels" }} + message Info.Labels { + repeated Info.Labels.LabelsEntry labels = 1; + } + +{{ template "scheme.payload.v1.Info.Labels.LabelsEntry" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Labels" }} + - Info.Labels + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | labels | Info.Labels.LabelsEntry | repeated | | + +{{ template "field.payload.v1.Info.Labels.LabelsEntry" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Info.CPU" }} + + +{{ template "scheme.payload.v1.Info.Memory" }} + + +{{ template "scheme.payload.v1.Info.Pods" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Node" }} + - Info.Node + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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. | + +{{ template "field.payload.v1.Info.CPU" }} + + +{{ template "field.payload.v1.Info.Memory" }} + + +{{ template "field.payload.v1.Info.Pods" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Info.Nodes" }} + message Info.Nodes { + repeated Info.Node nodes = 1; + } + +{{ template "scheme.payload.v1.Info.Node" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Nodes" }} + - Info.Nodes + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | nodes | Info.Node | repeated | The multiple node information. | + +{{ template "field.payload.v1.Info.Node" }} + +{{- 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; + } + +{{ 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" }} + - Info.Pod + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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. | + +{{ 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" }} + message Info.Pods { + repeated Info.Pod pods = 1; + } + +{{ template "scheme.payload.v1.Info.Pod" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Pods" }} + - Info.Pods + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | pods | Info.Pod | repeated | The multiple pod information. | + +{{ template "field.payload.v1.Info.Pod" }} + +{{- 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; + } + +{{ template "scheme.payload.v1.Info.ServicePort" }} + + +{{ template "scheme.payload.v1.Info.Labels" }} + + +{{ template "scheme.payload.v1.Info.Annotations" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Service" }} + - Info.Service + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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. | + +{{ template "field.payload.v1.Info.ServicePort" }} + + +{{ template "field.payload.v1.Info.Labels" }} + + +{{ template "field.payload.v1.Info.Annotations" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Info.ServicePort" }} + message Info.ServicePort { + string name = 1; + int32 port = 2; + } +{{- end -}} + +{{- define "field.payload.v1.Info.ServicePort" }} + - Info.ServicePort + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Info.Service" }} + +{{- end -}} + +{{- define "field.payload.v1.Info.Services" }} + - Info.Services + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | services | Info.Service | repeated | The multiple service information. | + +{{ template "field.payload.v1.Info.Service" }} + +{{- 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; + } + +{{ template "scheme.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Insert.Config" }} + - Insert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during insert operation. | + | filters | Filter.Config | | Filter configurations. | + | timestamp | int64 | | Insert timestamp. | + +{{ template "field.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Insert.MultiObjectRequest" }} + message Insert.MultiObjectRequest { + repeated Insert.ObjectRequest requests = 1; + } + +{{ template "scheme.payload.v1.Insert.ObjectRequest" }} + +{{- end -}} + +{{- define "field.payload.v1.Insert.MultiObjectRequest" }} + - Insert.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Insert.ObjectRequest | repeated | Represent multiple insert by object content. | + +{{ template "field.payload.v1.Insert.ObjectRequest" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Insert.MultiRequest" }} + message Insert.MultiRequest { + repeated Insert.Request requests = 1; + } + +{{ template "scheme.payload.v1.Insert.Request" }} + +{{- end -}} + +{{- define "field.payload.v1.Insert.MultiRequest" }} + - Insert.MultiRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Insert.Request | repeated | Represent multiple insert request content. | + +{{ template "field.payload.v1.Insert.Request" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Insert.ObjectRequest" }} + message Insert.ObjectRequest { + Object.Blob object = 1; + Insert.Config config = 2; + Filter.Target vectorizer = 3; + } + +{{ template "scheme.payload.v1.Object.Blob" }} + + +{{ template "scheme.payload.v1.Insert.Config" }} + + +{{ template "scheme.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Insert.ObjectRequest" }} + - Insert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + | vectorizer | Filter.Target | | Filter configurations. | + +{{ template "field.payload.v1.Object.Blob" }} + + +{{ template "field.payload.v1.Insert.Config" }} + + +{{ template "field.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Insert.Request" }} + message Insert.Request { + Object.Vector vector = 1; + Insert.Config config = 2; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + + +{{ template "scheme.payload.v1.Insert.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Insert.Request" }} + - Insert.Request + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be inserted. | + | config | Insert.Config | | The configuration of the insert request. | + +{{ template "field.payload.v1.Object.Vector" }} + + +{{ template "field.payload.v1.Insert.Config" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | key | string | | | +{{- end -}} + +{{- define "scheme.payload.v1.Meta.KeyValue" }} + message Meta.KeyValue { + Meta.Key key = 1; + Meta.Value value = 2; + } + +{{ template "scheme.payload.v1.Meta.Key" }} + + +{{ template "scheme.payload.v1.Meta.Value" }} + +{{- end -}} + +{{- define "field.payload.v1.Meta.KeyValue" }} + - Meta.KeyValue + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | key | Meta.Key | | | + | value | Meta.Value | | | + +{{ template "field.payload.v1.Meta.Key" }} + + +{{ template "field.payload.v1.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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Mirror.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Mirror.Targets" }} + - Mirror.Targets + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Mirror.Target | repeated | The multiple target information. | + +{{ template "field.payload.v1.Mirror.Target" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.List.Response" }} + - Object.List.Response + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Object.Vector" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Object.Location" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.Locations" }} + - Object.Locations + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + +{{ template "field.payload.v1.Object.Location" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Object.Blob" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.StreamBlob" }} + - Object.StreamBlob + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | blob | Object.Blob | | The binary object. | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Object.Blob" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Object.StreamDistance" }} + message Object.StreamDistance { + Object.Distance distance = 1; + google.rpc.Status status = 2; + } + +{{ template "scheme.payload.v1.Object.Distance" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.StreamDistance" }} + - Object.StreamDistance + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | distance | Object.Distance | | The distance. | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Object.Distance" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Object.StreamLocation" }} + message Object.StreamLocation { + Object.Location location = 1; + google.rpc.Status status = 2; + } + +{{ template "scheme.payload.v1.Object.Location" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.StreamLocation" }} + - Object.StreamLocation + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Object.Location" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Object.StreamVector" }} + message Object.StreamVector { + Object.Vector vector = 1; + google.rpc.Status status = 2; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.StreamVector" }} + - Object.StreamVector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector. | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Object.Vector" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Object.ID" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.TimestampRequest" }} + - Object.TimestampRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + +{{ template "field.payload.v1.Object.ID" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Object.ID" }} + + +{{ template "scheme.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.VectorRequest" }} + - Object.VectorRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The vector ID to be fetched. | + | filters | Filter.Config | | Filter configurations. | + +{{ template "field.payload.v1.Object.ID" }} + + +{{ template "field.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Object.Vectors" }} + message Object.Vectors { + repeated Object.Vector vectors = 1; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + +{{- end -}} + +{{- define "field.payload.v1.Object.Vectors" }} + - Object.Vectors + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vectors | Object.Vector | repeated | | + +{{ template "field.payload.v1.Object.Vector" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Remove.Request" }} + +{{- end -}} + +{{- define "field.payload.v1.Remove.MultiRequest" }} + - Remove.MultiRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Remove.Request | repeated | Represent the multiple remove request content. | + +{{ template "field.payload.v1.Remove.Request" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Remove.Request" }} + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + +{{ template "scheme.payload.v1.Object.ID" }} + + +{{ template "scheme.payload.v1.Remove.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Remove.Request" }} + - Remove.Request + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | + +{{ template "field.payload.v1.Object.ID" }} + + +{{ template "field.payload.v1.Remove.Config" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Remove.Timestamp" }} + +{{- end -}} + +{{- define "field.payload.v1.Remove.TimestampRequest" }} + - Remove.TimestampRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` +search is applied. | + +{{ template "field.payload.v1.Remove.Timestamp" }} + +{{- 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; + } + +{{ template "scheme.payload.v1.Filter.Config" }} + + +{{ template "scheme.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.Config" }} + - Search.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + +{{ template "field.payload.v1.Filter.Config" }} + + +{{ template "field.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.IDRequest" }} + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } + +{{ template "scheme.payload.v1.Search.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.IDRequest" }} + - Search.IDRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + +{{ template "field.payload.v1.Search.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.MultiIDRequest" }} + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } + +{{ template "scheme.payload.v1.Search.IDRequest" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.MultiIDRequest" }} + - Search.MultiIDRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + +{{ template "field.payload.v1.Search.IDRequest" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.MultiObjectRequest" }} + message Search.MultiObjectRequest { + repeated Search.ObjectRequest requests = 1; + } + +{{ template "scheme.payload.v1.Search.ObjectRequest" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.MultiObjectRequest" }} + - Search.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.ObjectRequest | repeated | Represent the multiple search by binary object request content. | + +{{ template "field.payload.v1.Search.ObjectRequest" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.MultiRequest" }} + message Search.MultiRequest { + repeated Search.Request requests = 1; + } + +{{ template "scheme.payload.v1.Search.Request" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.MultiRequest" }} + - Search.MultiRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.Request | repeated | Represent the multiple search request content. | + +{{ template "field.payload.v1.Search.Request" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.ObjectRequest" }} + message Search.ObjectRequest { + bytes object = 1; + Search.Config config = 2; + Filter.Target vectorizer = 3; + } + +{{ template "scheme.payload.v1.Search.Config" }} + + +{{ template "scheme.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.ObjectRequest" }} + - Search.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | bytes | | The binary object to be searched. | + | config | Search.Config | | The configuration of the search request. | + | vectorizer | Filter.Target | | Filter configuration. | + +{{ template "field.payload.v1.Search.Config" }} + + +{{ template "field.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.Request" }} + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } + +{{ template "scheme.payload.v1.Search.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.Request" }} + - Search.Request + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + +{{ template "field.payload.v1.Search.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.Response" }} + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; + } + +{{ template "scheme.payload.v1.Object.Distance" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.Response" }} + - Search.Response + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | The unique request ID. | + | results | Object.Distance | repeated | Search results. | + +{{ template "field.payload.v1.Object.Distance" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.Responses" }} + message Search.Responses { + repeated Search.Response responses = 1; + } + +{{ template "scheme.payload.v1.Search.Response" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.Responses" }} + - Search.Responses + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | responses | Search.Response | repeated | Represent the multiple search response content. | + +{{ template "field.payload.v1.Search.Response" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Search.StreamResponse" }} + message Search.StreamResponse { + Search.Response response = 1; + google.rpc.Status status = 2; + } + +{{ template "scheme.payload.v1.Search.Response" }} + +{{- end -}} + +{{- define "field.payload.v1.Search.StreamResponse" }} + - Search.StreamResponse + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | response | Search.Response | | Represent the search response. | + | status | google.rpc.Status | | The RPC error status. | + +{{ template "field.payload.v1.Search.Response" }} + +{{- 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; + } + +{{ template "scheme.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Update.Config" }} + - Update.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + +{{ template "field.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Update.MultiObjectRequest" }} + message Update.MultiObjectRequest { + repeated Update.ObjectRequest requests = 1; + } + +{{ template "scheme.payload.v1.Update.ObjectRequest" }} + +{{- end -}} + +{{- define "field.payload.v1.Update.MultiObjectRequest" }} + - Update.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Update.ObjectRequest | repeated | Represent the multiple update object request content. | + +{{ template "field.payload.v1.Update.ObjectRequest" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Update.MultiRequest" }} + message Update.MultiRequest { + repeated Update.Request requests = 1; + } + +{{ template "scheme.payload.v1.Update.Request" }} + +{{- end -}} + +{{- define "field.payload.v1.Update.MultiRequest" }} + - Update.MultiRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Update.Request | repeated | Represent the multiple update request content. | + +{{ template "field.payload.v1.Update.Request" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Update.ObjectRequest" }} + message Update.ObjectRequest { + Object.Blob object = 1; + Update.Config config = 2; + Filter.Target vectorizer = 3; + } + +{{ template "scheme.payload.v1.Object.Blob" }} + + +{{ template "scheme.payload.v1.Update.Config" }} + + +{{ template "scheme.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Update.ObjectRequest" }} + - Update.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be updated. | + | config | Update.Config | | The configuration of the update request. | + | vectorizer | Filter.Target | | Filter target. | + +{{ template "field.payload.v1.Object.Blob" }} + + +{{ template "field.payload.v1.Update.Config" }} + + +{{ template "field.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Update.Request" }} + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + + +{{ template "scheme.payload.v1.Update.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Update.Request" }} + - Update.Request + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + +{{ template "field.payload.v1.Object.Vector" }} + + +{{ template "field.payload.v1.Update.Config" }} + +{{- 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 | desc. | + | :---: | :--- | :---- | :---- | + | 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; + } + +{{ template "scheme.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Upsert.Config" }} + - Upsert.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + +{{ template "field.payload.v1.Filter.Config" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Upsert.MultiObjectRequest" }} + message Upsert.MultiObjectRequest { + repeated Upsert.ObjectRequest requests = 1; + } + +{{ template "scheme.payload.v1.Upsert.ObjectRequest" }} + +{{- end -}} + +{{- define "field.payload.v1.Upsert.MultiObjectRequest" }} + - Upsert.MultiObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Upsert.ObjectRequest | repeated | Represent the multiple upsert object request content. | + +{{ template "field.payload.v1.Upsert.ObjectRequest" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Upsert.MultiRequest" }} + message Upsert.MultiRequest { + repeated Upsert.Request requests = 1; + } + +{{ template "scheme.payload.v1.Upsert.Request" }} + +{{- end -}} + +{{- define "field.payload.v1.Upsert.MultiRequest" }} + - Upsert.MultiRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | + +{{ template "field.payload.v1.Upsert.Request" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Upsert.ObjectRequest" }} + message Upsert.ObjectRequest { + Object.Blob object = 1; + Upsert.Config config = 2; + Filter.Target vectorizer = 3; + } + +{{ template "scheme.payload.v1.Object.Blob" }} + + +{{ template "scheme.payload.v1.Upsert.Config" }} + + +{{ template "scheme.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "field.payload.v1.Upsert.ObjectRequest" }} + - Upsert.ObjectRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | object | Object.Blob | | The binary object to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + | vectorizer | Filter.Target | | Filter target. | + +{{ template "field.payload.v1.Object.Blob" }} + + +{{ template "field.payload.v1.Upsert.Config" }} + + +{{ template "field.payload.v1.Filter.Target" }} + +{{- end -}} + +{{- define "scheme.payload.v1.Upsert.Request" }} + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } + +{{ template "scheme.payload.v1.Object.Vector" }} + + +{{ template "scheme.payload.v1.Upsert.Config" }} + +{{- end -}} + +{{- define "field.payload.v1.Upsert.Request" }} + - Upsert.Request + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + +{{ template "field.payload.v1.Object.Vector" }} + + +{{ template "field.payload.v1.Upsert.Config" }} + +{{- end -}} + diff --git a/apis/docs/v1/payload.tmpl b/apis/docs/v1/payload.tmpl new file mode 100644 index 0000000000..3fef7a141d --- /dev/null +++ b/apis/docs/v1/payload.tmpl @@ -0,0 +1,42 @@ +{{- $skip_types := list "Search.AggregationAlgorithm" "Remove.Timestamp.Operator" -}} +{{- range .Scalars -}} + {{- $skip_types = append $skip_types .ProtoType -}} +{{- end -}} + +{{- range .Files -}} + {{- range .Messages -}} + {{ printf "{{- define \"scheme.%s\" }}" .FullName }} + message {{ .LongName }} { + {{- range $i, $ := .Fields }} + {{if $.Label}}{{ $.Label }} {{end}}{{ $.LongType }} {{ $.Name }} = {{ add1 $i }}; + {{- else }} + // empty + {{- end }} + } + {{- range $i, $ := .Fields -}} + {{- if not (or (has $.LongType $skip_types) (hasPrefix "google" $.FullType)) -}} + {{- printf "\n\n{{ template \"scheme.%s\" }}\n" $.FullType -}} + {{- end -}} + {{- end }} + {{- println "\n{{- end -}}\n" -}} + + {{- printf "{{- define \"field.%s\" }}\n" .FullName -}} + {{- printf " - %s\n" .LongName -}} + {{- if .HasFields }} + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + {{- range .Fields }} + | {{ .Name }} | {{ .LongType }} | {{.Label }} | {{ .Description }} | + {{- end }} + + {{- range $i, $ := .Fields -}} + {{- if not (or (has $.LongType $skip_types) (hasPrefix "google" $.FullType)) -}} + {{- printf "\n\n{{ template \"field.%s\" }}\n" $.FullType -}} + {{- end -}} + {{- end -}} + {{- else }} + empty + {{- end -}} + {{- println "\n{{- end -}}\n" -}} + {{- end -}} +{{- end -}} diff --git a/apis/docs/v1/remove.md b/apis/docs/v1/remove.md index 2846ea08ee..987ce9edc6 100644 --- a/apis/docs/v1/remove.md +++ b/apis/docs/v1/remove.md @@ -2,481 +2,375 @@ ## Overview -Remove Service is responsible for removing vectors indexed in the `vald-agent`. +Remove service provides ways to remove indexed vectors. ```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) {} - rpc StreamRemove(stream payload.v1.Remove.Request) - returns (stream 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. +A method to remove an indexed vector. ### Input - the scheme of `payload.v1.Remove.Request` ```rpc - message Remove { - message Request { - Object.ID id = 1; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - int64 timestamp = 3; - } + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + + + message Object.ID { + string id = 1; } - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + + + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; } ``` - Remove.Request - | field | type | label | required | description | - | :----: | :-------- | :---- | :------: | :--------------------------------------- | - | id | Object.ID | | \* | The ID of vector. | - | config | Config | | \* | The configuration of the remove request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | - - Remove.Config - - | field | type | label | required | description | - | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. | - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + + + + - Remove.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output - the scheme of `payload.v1.Object.Location` ```rpc - message Object { - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; } ``` - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is removed. | - | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | ## RemoveByTimestamp RPC -RemoveByTimestamp RPC is the method to remove vectors based on timestamp. +A method to remove an indexed vector based on timestamp. ### Input - the scheme of `payload.v1.Remove.TimestampRequest` ```rpc - message Remove { - message TimestampRequest { - repeated Timestamp timestamps = 1; - } - - message Timestamp { - enum Operator { - Eq = 0; - Ne = 1; - Ge = 2; - Gt = 3; - Le = 4; - Lt = 5; - } - int64 timestamp = 1; - Operator operator = 2; - } + message Remove.TimestampRequest { + repeated Remove.Timestamp timestamps = 1; } - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + + message Remove.Timestamp { + int64 timestamp = 1; + Remove.Timestamp.Operator operator = 2; } ``` - Remove.TimestampRequest - | field | type | label | required | description | - | :--------: | :--------------- | :-------------------------------- | :------: | :-------------------------------------------------------------------------------------------- | - | timestamps | Remove.Timestamp | repeated(Array[Remove.Timestamp]) | \* | The timestamp comparison list.
If more than one is specified, the `AND` search is applied. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | timestamps | Remove.Timestamp | repeated | The timestamp comparison list. If more than one is specified, the `AND` +search is applied. | - - Remove.Timestamp - - | field | type | label | required | description | - | :-------: | :------------------------ | :---- | :------: | :------------------------------------------------- | - | timestamp | int64 | | \* | The timestamp. | - | operator | Remove.Timestamp.Operator | | | The conditional operator. (default value is `Eq`). | - - - Remove.Timestamp.Operator - | value | description | - | :---: | :--------------------- | - | Eq | Equal. | - | Ne | Not Equal. | - | Ge | Greater than or Equal. | - | Gt | Greater than. | - | Le | Less than or Equal. | - | Lt | Less than. | + - Remove.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. -
+ | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | timestamp | int64 | | The timestamp. | + | operator | Remove.Timestamp.Operator | | The conditional operator. | ### Output -- the scheme of `payload.v1.Object.Locations`. +- the scheme of `payload.v1.Object.Locations` ```rpc - message Object { - message Locations { repeated Location locations = 1; } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 | - | :------: | :-------------- | :------------------------------- | :----------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is removed. | - | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | ## StreamRemove RPC -StreamRemove RPC is the method to remove multiple vectors using the [bidirectional streaming RPC](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc).
-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. +A method to remove multiple indexed vectors by bidirectional streaming. ### Input -- the scheme of `payload.v1.Remove.Request stream` +- the scheme of `payload.v1.Remove.Request` ```rpc - message Remove { - message Request { - Object.ID id = 1; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - int64 timestamp = 3; - } + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } + + + message Object.ID { + string id = 1; } - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + + + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; } ``` - Remove.Request - | field | type | label | required | description | - | :----: | :-------- | :---- | :------: | :--------------------------------------- | - | id | Object.ID | | \* | The ID of vector. | - | config | Config | | \* | The configuration of the insert request. | - - - Remove.Config + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | - | field | type | label | required | description | - | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. | - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + + + + - Remove.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output - the scheme of `payload.v1.Object.StreamLocation` ```rpc - message Object { - message StreamLocation { - oneof payload { - Location location = 1; - google.rpc.Status status = 2; - } - } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 information of `Object.Location` data. | - | status | google.rpc.Status | | The status of Google RPC | - - - Object.Location + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | location | Object.Location | | The vector location. | + | status | google.rpc.Status | | The RPC error status. | - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is removed. | - | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. | - - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) + - Object.Location - | field | type | label | description | - | :-----: | :------------------ | :------------------- | :-------------------------------------- | - | code | int32 | | Status code (code list is next section) | - | message | string | | Error message | - | details | google.protobuf.Any | repeated(Array[any]) | The details error message list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiRemove RPC -### Troubleshooting +A method to remove multiple indexed vectors in a single request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Remove.MultiRequest` -| 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 + message Remove.MultiRequest { + repeated Remove.Request requests = 1; + } -## MultiRemove RPC -MultiRemove is the method to remove multiple vectors in **1** request. + message Remove.Request { + Object.ID id = 1; + Remove.Config config = 2; + } -
-gRPC has a message size limitation.
-Please be careful that the size of the request exceeds the limit. -
-### Input + message Object.ID { + string id = 1; + } -- the scheme of `payload.v1.Remove.MultiRequest` - ```rpc - message Remove { - message MultiRequest { - repeated Request requests = 1; - } - - message Request { - Object.ID id = 1; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - int64 timestamp = 3; - } - } - message Object { - message ID { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - } + message Remove.Config { + bool skip_strict_exist_check = 1; + int64 timestamp = 2; } ``` - Remove.MultiRequest - | field | type | label | required | description | - | :------: | :------------- | :------------------------------ | :------: | :--------------- | - | requests | Remove.Request | repeated(Array[Insert.Request]) | \* | the request list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Remove.Request | repeated | Represent the multiple remove request content. | - - Remove.Request - | field | type | label | required | description | - | :----: | :-------- | :---- | :------: | :--------------------------------------- | - | id | Object.ID | | \* | The ID of vector. | - | config | Config | | \* | The configuration of the remove request. | + - Remove.Request - - Remove.Config + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | Object.ID | | The object ID to be removed. | + | config | Remove.Config | | The configuration of the remove request. | - | field | type | label | required | description | - | :---------------------: | :---- | :---- | :------: | :----------------------------------------------------------------------------------------------------------- | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector removed.
If it is N/A, the current time will be used. | - Object.ID - | field | type | label | required | description | - | :---: | :----- | :---- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | | + + + + - Remove.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | timestamp | int64 | | Remove timestamp. | ### Output -- the scheme of `payload.v1.Object.Locations`. +- the scheme of `payload.v1.Object.Locations` ```rpc - message Object { - message Locations { repeated Location locations = 1; } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 | - | :------: | :-------------- | :------------------------------- | :----------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is removed. | - | uuid | string | | The ID of the removed vector. It is the same as an `Object.ID`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is removed. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -| 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 index ccec2863d0..b3d42216eb 100644 --- a/apis/docs/v1/search.md +++ b/apis/docs/v1/search.md @@ -2,1627 +2,1990 @@ ## Overview -Search Service is responsible for searching vectors similar to the user request vector from `vald-agent`. +Search service provides ways to search indexed vectors. ```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) {} - rpc SearchByID(payload.v1.Search.IDRequest) - returns (payload.v1.Search.Response) {} +} +``` - rpc StreamSearch(stream payload.v1.Search.Request) - returns (stream payload.v1.Search.StreamResponse) {} +## Search RPC - rpc StreamSearchByID(stream payload.v1.Search.IDRequest) - returns (stream payload.v1.Search.StreamResponse) {} +A method to search indexed vectors by a raw vector. - rpc MultiSearch(payload.v1.Search.MultiRequest) - returns (payload.v1.Search.Responses) {} +### Input - rpc MultiSearchByID(payload.v1.Search.MultiIDRequest) - returns (payload.v1.Search.Responses) {} +- the scheme of `payload.v1.Search.Request` - rpc LinearSearch(payload.v1.Search.Request) returns (payload.v1.Search.Response) {} + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } - rpc LinearSearchByID(payload.v1.Search.IDRequest) - returns (payload.v1.Search.Response) {} - rpc StreamLinearSearch(stream payload.v1.Search.Request) - returns (stream payload.v1.Search.StreamResponse) {} + 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; + } - rpc StreamLinearSearchByID(stream payload.v1.Search.IDRequest) - returns (stream payload.v1.Search.StreamResponse) {} - rpc MultiLinearSearch(payload.v1.Search.MultiRequest) - returns (payload.v1.Search.Responses) {} + message Filter.Config { + repeated Filter.Target targets = 1; + } - rpc MultiLinearSearchByID(payload.v1.Search.MultiIDRequest) - returns (payload.v1.Search.Responses) {} -} -``` -## Search RPC + message Filter.Target { + string host = 1; + uint32 port = 2; + } -Search RPC is the method to search vector(s) similar to the request vector. -### Input -- the scheme of `payload.v1.Search.Request` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum 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 | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Response`. +- the scheme of `payload.v1.Search.Response` ```rpc - message Search { - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## SearchByID RPC -### Troubleshooting +A method to search indexed vectors by ID. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.IDRequest` -| 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 + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -## 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. + 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; + } -### Input -- the scheme of `payload.v1.Search.IDRequest` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Response`. +- the scheme of `payload.v1.Search.Response` ```rpc - message Search { - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamSearch RPC -### Troubleshooting +A method to search indexed vectors by multiple vectors. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.Request` -| 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 + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } -## 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. + 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; + } -### Input -- the scheme of `payload.v1.Search.Request stream` + message Filter.Config { + repeated Filter.Target targets = 1; + } + - ```rpc - message Search { - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.Request - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.StreamResponse`. +- the scheme of `payload.v1.Search.StreamResponse` ```rpc - message Search { - message StreamResponse { - oneof payload { - Response response = 1; - google.rpc.Status status = 2; - } - } - - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } - } - - message Object { - message Distance { - string id = 1; - float distance = 2; - } + 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 | Response | | The search result response. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamSearchByID RPC -### Troubleshooting +A method to search indexed vectors by multiple IDs. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.IDRequest` -| 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 + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -## 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. + 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; + } + -### Input + message Filter.Config { + repeated Filter.Target targets = 1; + } -- the scheme of `payload.v1.Search.IDRequest stream` - ```rpc - message Search { - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.StreamResponse`. +- the scheme of `payload.v1.Search.StreamResponse` ```rpc - message Search { - message StreamResponse { - oneof payload { - Response response = 1; - google.rpc.Status status = 2; - } - } - - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } - } - - message Object { - message Distance { - string id = 1; - float distance = 2; - } + 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 | Response | | The search result response. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiSearch RPC -### Troubleshooting +A method to search indexed vectors by multiple vectors in a single request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.MultiRequest` -| 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 + message Search.MultiRequest { + repeated Search.Request requests = 1; + } -## MultiSearch RPC -MultiSearch RPC is the method to search vectors with multiple vectors in **1** request. + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } -
-gRPC has a message size limitation.
-Please be careful that the size of the request exceeds the limit. -
-### Input + 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; + } -- the scheme of `payload.v1.Search.MultiRequest` - ```rpc - message Search { - message MultiRequest { - repeated Request requests = 1; - } - - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.MultiRequest - | field | type | label | required | description | - | :------: | :----------------------- | :---- | :------: | :----------------------- | - | requests | repeated(Array[Request]) | | \* | The search request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.Request | repeated | Represent the multiple search request content. | + - Search.Request - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Responses`. +- the scheme of `payload.v1.Search.Responses` ```rpc - message Search { - message Responses { - repeated Response responses = 1; - } + message Search.Responses { + repeated Search.Response responses = 1; + } + - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 2; - } + + message Object.Distance { + string id = 1; + float distance = 2; } ``` - Search.Responses - | field | type | label | description | - | :-------: | :------- | :------------------------ | :----------------------------------- | - | responses | Response | repeated(Array[Response]) | The list of search results response. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiSearchByID RPC -### Troubleshooting +A method to search indexed vectors by multiple IDs in a single request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input + +- the scheme of `payload.v1.Search.MultiIDRequest` -Here are some common reasons and how to resolve each error. + ```rpc + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } -| 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 + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -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. -
+ 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; + } -### Input -- the scheme of `payload.v1.Search.MultiIDRequest stream` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - - message MultiIDRequest { - repeated IDRequest requests = 1; - } - - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - float radius = 3; - float epsilon = 4; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.MultiIDRequest - | field | type | label | required | description | - | :------: | :-------- | :------------------------- | :------: | :--------------------------- | - | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | radius | float | | \* | The search radius. | - | epsilon | float | | \* | The search coefficient (default value is `0.1`). | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Responses`. +- the scheme of `payload.v1.Search.Responses` ```rpc - message Search { - message Responses { - repeated Response responses = 1; - } + message Search.Responses { + repeated Search.Response responses = 1; + } - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 2; - } + + message Object.Distance { + string id = 1; + float distance = 2; } ``` - Search.Responses - | field | type | label | description | - | :-------: | :------- | :------------------------ | :----------------------------------- | - | responses | Response | repeated(Array[Response]) | The list of search results response. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## LinearSearch RPC -Please refer to [Response Status Code](../status.md) for more details. +A method to linear search indexed vectors by a raw vector. -### Troubleshooting +### Input -The request process may not be completed when the response code is NOT `0 (OK)`. +- the scheme of `payload.v1.Search.Request` -Here are some common reasons and how to resolve each error. + ```rpc + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } -| 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 + 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; + } -LinearSearch RPC is the method to linear search vector(s) similar to the request vector. -### Input + message Filter.Config { + repeated Filter.Target targets = 1; + } -- the scheme of `payload.v1.Search.Request` - ```rpc - message Search { - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.Request - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Response`. +- the scheme of `payload.v1.Search.Response` ```rpc - message Search { - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## LinearSearchByID RPC -### Troubleshooting +A method to linear search indexed vectors by ID. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.IDRequest` -| 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 + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -## 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. + 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; + } -### Input -- the scheme of `payload.v1.Search.IDRequest` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Response`. +- the scheme of `payload.v1.Search.Response` ```rpc - message Search { - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamLinearSearch RPC -### Troubleshooting +A method to linear search indexed vectors by multiple vectors. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.Request` -| 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 + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } -## 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. + 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; + } -### Input -- the scheme of `payload.v1.Search.Request stream` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.Request - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.StreamResponse`. +- the scheme of `payload.v1.Search.StreamResponse` ```rpc - message Search { - message StreamResponse { - oneof payload { - Response response = 1; - google.rpc.Status status = 2; - } - } - - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } - } - - message Object { - message Distance { - string id = 1; - float distance = 2; - } + 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 | Response | | The search result response. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamLinearSearchByID RPC -### Troubleshooting +A method to linear search indexed vectors by multiple IDs. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.IDRequest` -| 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 + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -## 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. + 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; + } -### Input -- the scheme of `payload.v1.Search.IDRequest stream` + message Filter.Config { + repeated Filter.Target targets = 1; + } - ```rpc - message Search { - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.StreamResponse`. +- the scheme of `payload.v1.Search.StreamResponse` ```rpc - message Search { - message StreamResponse { - oneof payload { - Response response = 1; - google.rpc.Status status = 2; - } - } - - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } - } - - message Object { - message Distance { - string id = 1; - float distance = 2; - } + 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 | Response | | The search result response. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiLinearSearch RPC -### Troubleshooting +A method to linear search indexed vectors by multiple vectors in a single +request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.MultiRequest` -| 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 + message Search.MultiRequest { + repeated Search.Request requests = 1; + } -## MultiLinearSearch RPC -MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in **1** request. + message Search.Request { + repeated float vector = 1; + Search.Config config = 2; + } -
-gRPC has a message size limitation.
-Please be careful that the size of the request exceeds the limit. -
-### Input + 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; + } -- the scheme of `payload.v1.Search.MultiRequest` - ```rpc - message Search { - message MultiRequest { - repeated Request requests = 1; - } - - message Request { - repeated float vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.MultiRequest - | field | type | label | required | description | - | :------: | :----------------------- | :---- | :------: | :---------------------- | - | requests | repeated(Array[Request]) | | \* | The search request list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.Request | repeated | Represent the multiple search request content. | + - Search.Request - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------ | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | float | repeated | The vector to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Responses`. +- the scheme of `payload.v1.Search.Responses` ```rpc - message Search { - message Responses { - repeated Response responses = 1; - } + message Search.Responses { + repeated Search.Response responses = 1; + } + - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 2; - } + + message Object.Distance { + string id = 1; + float distance = 2; } ``` - Search.Responses - | field | type | label | description | - | :-------: | :------- | :------------------------ | :---------------------------------- | - | responses | Response | repeated(Array[Response]) | The list of search results response | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiLinearSearchByID RPC -### Troubleshooting +A method to linear search indexed vectors by multiple IDs in a single +request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Search.MultiIDRequest` -| 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 + message Search.MultiIDRequest { + repeated Search.IDRequest requests = 1; + } -## MultiLinearSearchByID RPC -MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request. + message Search.IDRequest { + string id = 1; + Search.Config config = 2; + } -
-gRPC has a message size limitation.
-Please be careful that the size of the request exceeds the limit. -
-### Input + 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; + } -- the scheme of `payload.v1.Search.MultiIDRequest stream` - ```rpc - message Search { - - message MultiIDRequest { - repeated IDRequest requests = 1; - } - - message IDRequest { - string id = 1; - Config config = 2; - } - - message Config { - string request_id = 1; - uint32 num = 2 [ (validate.rules).uint32.gte = 1 ]; - int64 timeout = 5; - Filter.Config ingress_filters = 6; - Filter.Config egress_filters = 7; - uint32 min_num = 8; - AggregationAlgorithm aggregation_algorithm = 9; - } - } - - enum AggregationAlgorithm { - Unknown = 0; - ConcurrentQueue = 1; - SortSlice = 2; - SortPoolSlice = 3; - PairingHeap = 4; + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; + } + + + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Search.MultiIDRequest - | field | type | label | required | description | - | :------: | :-------- | :------------------------- | :------: | :--------------------------- | - | requests | IDRequest | repeated(Array[IDRequest]) | \* | The searchByID request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Search.IDRequest | repeated | Represent the multiple search by ID request content. | + - Search.IDRequest - | field | type | label | required | description | - | :----: | :----- | :---- | :------: | :--------------------------------------- | - | id | string | | \* | The vector ID to be searched. | - | config | Config | | \* | The configuration of the search request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID to be searched. | + | config | Search.Config | | The configuration of the search request. | + - Search.Config - | field | type | label | required | description | - | :-------------------: | :------------------- | :---- | :------: | :---------------------------------------------------------------------------- | - | request_id | string | | | Unique request ID. | - | num | uint32 | | \* | The maximum number of results to be returned. | - | timeout | int64 | | | Search timeout in nanoseconds (default value is `5s`). | - | ingress_filters | Filter.Config | | | Ingress Filter configuration. | - | egress_filters | Filter.Config | | | Egress Filter configuration. | - | min_num | uint32 | | | The minimum number of results to be returned. | - | aggregation_algorithm | AggregationAlgorithm | | | The search aggregation algorithm option (default value is `ConcurrentQueue`). | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | request_id | string | | Unique request ID. | + | num | uint32 | | Maximum number of result to be returned. | + | radius | float | | Search radius. | + | epsilon | float | | Search coefficient. | + | timeout | int64 | | Search timeout in nanoseconds. | + | ingress_filters | Filter.Config | | Ingress filter configurations. | + | egress_filters | Filter.Config | | Egress filter configurations. | + | min_num | uint32 | | Minimum number of result to be returned. | + | aggregation_algorithm | Search.AggregationAlgorithm | | Aggregation Algorithm | + | ratio | google.protobuf.FloatValue | | Search ratio for agent return result number. | + | nprobe | uint32 | | Search nprobe. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | + + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Search.Responses`. +- the scheme of `payload.v1.Search.Responses` ```rpc - message Search { - message Responses { - repeated Response responses = 1; - } + message Search.Responses { + repeated Search.Response responses = 1; + } + - message Response { - string request_id = 1; - repeated Object.Distance results = 2; - } + message Search.Response { + string request_id = 1; + repeated Object.Distance results = 2; } - message Object { - message Distance { - string id = 1; - float distance = 2; - } + + message Object.Distance { + string id = 1; + float distance = 2; } ``` - Search.Responses - | field | type | label | description | - | :-------: | :------- | :------------------------ | :----------------------------------- | - | responses | Response | repeated(Array[Response]) | The list of search results response. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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(Array[Object.Distance]) | Search results. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 between the result vector and the request vector. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | distance | float | | The distance. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -| 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 index 2fb68b05f7..bda44822dc 100644 --- a/apis/docs/v1/update.md +++ b/apis/docs/v1/update.md @@ -2,374 +2,457 @@ ## Overview -Update Service updates to new vector from inserted vector in the `vald-agent` components. +Update service provides ways to update indexed vectors. ```rpc service Update { - rpc Update(payload.v1.Update.Request) returns (payload.v1.Object.Location) {} - rpc StreamUpdate(stream payload.v1.Update.Request) returns (stream payload.v1.Object.Location) {} + 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) {} - rpc MultiUpdate(payload.v1.Update.MultiRequest) returns (stream payload.v1.Object.Locations) {} } ``` ## Update RPC -Update RPC is the method to update a single vector. +A method to update an indexed vector. ### Input - the scheme of `payload.v1.Update.Request` ```rpc - message Update { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 2; - int64 timestamp = 3; - } + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; } - message Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated.min_items = 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 | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | + + + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.Location` ```rpc - message Object { - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; } ``` - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is updated. | - | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamUpdate RPC -### Troubleshooting +A method to update multiple indexed vectors by bidirectional streaming. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Update.Request` -| 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 + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } -## 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. + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -### Input -- the scheme of `payload.v1.Update.Request stream` - ```rpc - message Update { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 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 Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Update.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.StreamLocation` ```rpc - message Object { - message StreamLocation { - oneof payload { - Location location = 1; - google.rpc.Status status = 2; - } - } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 information of Object.Location data. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 vald agent pod where the request vector is updated. | - | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | - - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) + - Object.Location - | field | type | label | description | - | :-----: | :------------------ | :------------------- | :-------------------------------------- | - | code | int32 | | Status code (code list is next section) | - | message | string | | Error message | - | details | google.protobuf.Any | repeated(Array[any]) | The details error message list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 5 | NOT_FOUND | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## MultiUpdate RPC -### Troubleshooting +A method to update multiple indexed vectors in a single request. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Update.MultiRequest` -| 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 + message Update.MultiRequest { + repeated Update.Request requests = 1; + } -## MultiUpdate RPC -MultiUpdate is the method to update multiple vectors in **1** request. + message Update.Request { + Object.Vector vector = 1; + Update.Config config = 2; + } -
-gRPC has a message size limitation.
-Please be careful that the size of the request exceeds the limit. -
-### Input + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -- the scheme of `payload.v1.Update.MultiRequest` - ```rpc - message Update { - message MultiRequest { repeated Request requests = 1; } - - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 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 Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Config { + repeated Filter.Target targets = 1; + } + + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Update.MultiRequest - | field | type | label | required | description | - | :------: | :------------- | :------------------------------ | :------: | :---------------- | - | requests | Insert.Request | repeated(Array[Insert.Request]) | \* | The request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Update.Request | repeated | Represent the multiple update request content. | + - Update.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be updated. | + | config | Update.Config | | The configuration of the update request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Update.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during update operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Update timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Object.Locations`. +- the scheme of `payload.v1.Object.Locations` ```rpc - message Object { - message Locations { repeated Location locations = 1; } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 | - | :------: | :-------------- | :------------------------------- | :----------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :-------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is updated. | - | uuid | string | | The ID of the updated vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## UpdateTimestamp RPC + +A method to update timestamp an indexed vector. + +### Input + +- the scheme of `payload.v1.Update.TimestampRequest` + + ```rpc + message Update.TimestampRequest { + string id = 1; + int64 timestamp = 2; + bool force = 3; + } + ``` + + - Update.TimestampRequest + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + | force | bool | | force represents forcefully update the timestamp. | + +### 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 | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | + +### Status Code + +| code | desc. | +| :--: | :---------------- | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + diff --git a/apis/docs/v1/upsert.md b/apis/docs/v1/upsert.md index 9ed9f6572c..5fcd8e735d 100644 --- a/apis/docs/v1/upsert.md +++ b/apis/docs/v1/upsert.md @@ -2,372 +2,401 @@ ## 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. +Upsert service provides ways to insert/update vectors. ```rpc service Upsert { - rpc Upsert(payload.v1.Upsert.Request) - returns (payload.v1.Object.Location) {} + 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) {} - rpc StreamUpsert(stream payload.v1.Upsert.Request) - returns (stream 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. +A method to insert/update a vector. ### Input - the scheme of `payload.v1.Upsert.Request` ```rpc - message Upsert { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 2; - int64 timestamp = 3; - } + 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 Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Upsert.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.Location` ```rpc - message Object { - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + message Object.Location { + string name = 1; + string uuid = 2; + repeated string ips = 3; } ``` - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :----------------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is updated/inserted. | - | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -Please refer to [Response Status Code](../status.md) for more details. +## StreamUpsert RPC -### Troubleshooting +A method to insert/update multiple vectors by bidirectional streaming. -The request process may not be completed when the response code is NOT `0 (OK)`. +### Input -Here are some common reasons and how to resolve each error. +- the scheme of `payload.v1.Upsert.Request` -| 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 + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } -## 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. + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -### Input -- the scheme of `payload.v1.Upsert.Request stream` - ```rpc - message Upsert { - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 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 Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Upsert.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output - the scheme of `payload.v1.Object.StreamLocation` ```rpc - message Object { - message StreamLocation { - oneof payload { - Location location = 1; - google.rpc.Status status = 2; - } - } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 information of Object.Location data. | - | status | google.rpc.Status | | The status of Google RPC. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | 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 vald agent pod where the request vector is updated/inserted. | - | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | - - - [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) + - Object.Location - | field | type | label | description | - | :-----: | :------------------ | :------------------- | :-------------------------------------- | - | code | int32 | | Status code (code list is next section) | - | message | string | | Error message | - | details | google.protobuf.Any | repeated(Array[any]) | The details error message list | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 0 | OK | -| 1 | CANCELLED | -| 3 | INVALID_ARGUMENT | -| 4 | DEADLINE_EXCEEDED | -| 6 | ALREADY_EXISTS | -| 10 | ABORTED | -| 13 | INTERNAL | +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | + +## MultiUpsert RPC + +A method to insert/update multiple vectors in a single request. -Please refer to [Response Status Code](../status.md) for more details. +### Input -### Troubleshooting +- the scheme of `payload.v1.Upsert.MultiRequest` -The request process may not be completed when the response code is NOT `0 (OK)`. + ```rpc + message Upsert.MultiRequest { + repeated Upsert.Request requests = 1; + } -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. | + message Upsert.Request { + Object.Vector vector = 1; + Upsert.Config config = 2; + } -## MultiUpsert RPC -MultiUpsert is the method to update existing multiple vectors and add new multiple vectors in **1** request. + message Object.Vector { + string id = 1; + repeated float vector = 2; + int64 timestamp = 3; + } -
-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` + message Upsert.Config { + bool skip_strict_exist_check = 1; + Filter.Config filters = 2; + int64 timestamp = 3; + bool disable_balanced_update = 4; + } - ```rpc - message Upsert { - message MultiRequest { repeated Request requests = 1; } - - message Request { - Object.Vector vector = 1 [ (validate.rules).repeated .min_items = 2 ]; - Config config = 2; - } - - message Config { - bool skip_strict_exist_check = 1; - Filter.Config filters = 2; - int64 timestamp = 3; - } + + message Filter.Config { + repeated Filter.Target targets = 1; } - message Object { - message Vector { - string id = 1 [ (validate.rules).string.min_len = 1 ]; - repeated float vector = 2 [ (validate.rules).repeated .min_items = 2 ]; - } + + message Filter.Target { + string host = 1; + uint32 port = 2; } ``` - Upsert.MultiRequest - | field | type | label | required | description | - | :------: | :------------- | :------------------------------ | :------: | :---------------- | - | requests | Upsert.Request | repeated(Array[Insert.Request]) | \* | The request list. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | requests | Upsert.Request | repeated | Represent the multiple upsert request content. | + - Upsert.Request - | field | type | label | required | description | - | :----: | :------------ | :---- | :------: | :--------------------------------------- | - | vector | Object.Vector | | \* | The information of vector. | - | config | Config | | \* | The configuration of the update request. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | vector | Object.Vector | | The vector to be upserted. | + | config | Upsert.Config | | The configuration of the upsert request. | + + + - Object.Vector + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | id | string | | The vector ID. | + | vector | float | repeated | The vector. | + | timestamp | int64 | | timestamp represents when this vector inserted. | + + - Upsert.Config - | field | type | label | required | description | - | :---------------------: | :------------ | :---- | :------: | :------------------------------------------------------------------------------------------------------------ | - | skip_strict_exist_check | bool | | | Check whether the same vector is already inserted or not.
The ID should be unique if the value is `true`. | - | timestamp | int64 | | | The timestamp of the vector inserted.
If it is N/A, the current time will be used. | - | filters | Filter.Config | | | Configuration for filter. | - | disable_balanced_update | bool | | | A flag to disable balanced update (split remove -> insert operation) during update operation. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | skip_strict_exist_check | bool | | A flag to skip exist check during upsert operation. | + | filters | Filter.Config | | Filter configuration. | + | timestamp | int64 | | Upsert timestamp. | + | disable_balanced_update | bool | | A flag to disable balanced update (split remove -> insert operation) +during update operation. | - - Object.Vector - | field | type | label | required | description | - | :----: | :----- | :--------------------- | :------: | :------------------------------------------------------------- | - | id | string | | \* | The ID of a vector. ID should consist of 1 or more characters. | - | vector | float | repeated(Array[float]) | \* | The vector data. Its dimension is between 2 and 65,536. | + - Filter.Config + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | targets | Filter.Target | repeated | Represent the filter target configuration. | + + + - Filter.Target + + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | host | string | | The target hostname. | + | port | uint32 | | The target port. | ### Output -- the scheme of `payload.v1.Object.Locations`. +- the scheme of `payload.v1.Object.Locations` ```rpc - message Object { - message Locations { repeated Location locations = 1; } - - message Location { - string name = 1; - string uuid = 2; - repeated string ips = 3; - } + 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 | - | :------: | :-------------- | :------------------------------- | :----------------------------- | - | location | Object.Location | repeated(Array[Object.Location]) | The list of `Object.Location`. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | locations | Object.Location | repeated | | + - Object.Location - | field | type | label | description | - | :---: | :----- | :---------------------- | :----------------------------------------------------------------------------- | - | name | string | | The name of vald agent pod where the request vector is updated/inserted. | - | uuid | string | | The ID of the updated/inserted vector. It is the same as an `Object.Vector`. | - | ips | string | repeated(Array[string]) | The IP list of `vald-agent` pods where the request vector is updated/inserted. | + | field | type | label | desc. | + | :---: | :--- | :---- | :---- | + | name | string | | The name of the location. | + | uuid | string | | The UUID of the vector. | + | ips | string | repeated | The IP list. | ### Status Code -| code | name | +| code | desc. | | :--: | :---------------- | -| 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. +| 0 | OK | +| 1 | CANCELLED | +| 3 | INVALID_ARGUMENT | +| 4 | DEADLINE_EXCEEDED | +| 5 | NOT_FOUND | +| 13 | INTERNAL | -| 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. |