Vald Search APIs

Overview

Search Service is responsible for searching vectors similar to the user request vector from vald-agent.

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(stream payload.v1.Search.Request)
      returns (stream payload.v1.Search.StreamResponse) {}

  rpc StreamSearchByID(stream payload.v1.Search.IDRequest)
      returns (stream 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(stream payload.v1.Search.Request)
      returns (stream payload.v1.Search.StreamResponse) {}

  rpc StreamLinearSearchByID(stream payload.v1.Search.IDRequest)
      returns (stream payload.v1.Search.StreamResponse) {}

  rpc MultiLinearSearch(payload.v1.Search.MultiRequest)
      returns (payload.v1.Search.Responses) {}

  rpc MultiLinearSearchByID(payload.v1.Search.MultiIDRequest)
      returns (payload.v1.Search.Responses) {}
}

Search RPC

Search RPC is the method to search vector(s) similar to the request vector.

Input

• the scheme of payload.v1.Search.Request

  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;
  }
  

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

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

Output

• the scheme of payload.v1.Search.Response.

  message Search {
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message 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.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

SearchByID RPC

SearchByID RPC is the method to search similar vectors using a user-defined vector ID.
The vector with the same requested ID should be indexed into the vald-agent before searching.

Input

• the scheme of payload.v1.Search.IDRequest

  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;
  }
  

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    radius	float		*	The search radius.
    epsilon	float		*	The search coefficient (default value is 0.1).
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.Response.

  message Search {
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message 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.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

StreamSearch RPC

StreamSearch RPC is the method to search vectors with multi queries(vectors) using the bidirectional streaming RPC.
Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. Each Search request and response are independent.

Input

• the scheme of payload.v1.Search.Request stream

  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;
  }
  

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

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

Output

• the scheme of payload.v1.Search.StreamResponse.

  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;
    }
  }
  

  • Search.StreamResponse

    field	type	label	description
    response	Response		The search result response.
    status	google.rpc.Status		The status of Google RPC.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

StreamSearchByID RPC

StreamSearchByID RPC is the method to search vectors with multi queries(IDs) using the bidirectional streaming RPC.
Using the bidirectional streaming RPC, the search request can be communicated in any order between the client and server. Each SearchByID request and response are independent.

Input

• the scheme of payload.v1.Search.IDRequest stream

  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;
  }
  

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    radius	float		*	The search radius.
    epsilon	float		*	The search coefficient (default value is 0.1).
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.StreamResponse.

  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;
    }
  }
  

  • Search.StreamResponse

    field	type	label	description
    response	Response		The search result response.
    status	google.rpc.Status		The status of Google RPC.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

MultiSearch RPC

MultiSearch RPC is the method to search vectors with multiple vectors in 1 request.

Input

• the scheme of payload.v1.Search.MultiRequest

  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;
  }
  

  • Search.MultiRequest

    field	type	label	required	description
    requests	repeated(Array[Request])		*	The search request list.

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

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

Output

• the scheme of payload.v1.Search.Responses.

  message Search {
    message Responses {
      repeated Response responses = 1;
    }
  
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message Distance {
      string id = 1;
      float distance = 2;
    }
  }
  

  • Search.Responses

    field	type	label	description
    responses	Response	repeated(Array[Response])	The list of search results response.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

MultiSearchByID RPC

MultiSearchByID RPC is the method to search vectors with multiple IDs in 1 request.

Input

• the scheme of payload.v1.Search.MultiIDRequest stream

  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;
  }
  

  • Search.MultiIDRequest

    field	type	label	required	description
    requests	IDRequest	repeated(Array[IDRequest])	*	The searchByID request list.

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    radius	float		*	The search radius.
    epsilon	float		*	The search coefficient (default value is 0.1).
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.Responses.

  message Search {
    message Responses {
      repeated Response responses = 1;
    }
  
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message Distance {
      string id = 1;
      float distance = 2;
    }
  }
  

  • Search.Responses

    field	type	label	description
    responses	Response	repeated(Array[Response])	The list of search results response.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

LinearSearch RPC

LinearSearch RPC is the method to linear search vector(s) similar to the request vector.

Input

• the scheme of payload.v1.Search.Request

  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;
  }
  

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

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

Output

• the scheme of payload.v1.Search.Response.

  message Search {
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message 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.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

LinearSearchByID RPC

LinearSearchByID RPC is the method to linear search similar vectors using a user-defined vector ID.
The vector with the same requested ID should be indexed into the vald-agent before searching. You will get a NOT_FOUND error if the vector isn’t stored.

Input

• the scheme of payload.v1.Search.IDRequest

  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;
  }
  

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.Response.

  message Search {
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message 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.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

StreamLinearSearch RPC

StreamLinearSearch RPC is the method to linear search vectors with multi queries(vectors) using the bidirectional streaming RPC.
Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. Each LinearSearch request and response are independent.

Input

• the scheme of payload.v1.Search.Request stream

  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;
  }
  

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

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

Output

• the scheme of payload.v1.Search.StreamResponse.

  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;
    }
  }
  

  • Search.StreamResponse

    field	type	label	description
    response	Response		The search result response.
    status	google.rpc.Status		The status of Google RPC.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

StreamLinearSearchByID RPC

StreamLinearSearchByID RPC is the method to linear search vectors with multi queries(IDs) using the bidirectional streaming RPC.
Using the bidirectional streaming RPC, the linear search request can be communicated in any order between the client and server. Each LinearSearchByID request and response are independent.

Input

• the scheme of payload.v1.Search.IDRequest stream

  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;
  }
  

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.StreamResponse.

  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;
    }
  }
  

  • Search.StreamResponse

    field	type	label	description
    response	Response		The search result response.
    status	google.rpc.Status		The status of Google RPC.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

MultiLinearSearch RPC

MultiLinearSearch RPC is the method to linear search vectors with multiple vectors in 1 request.

Input

• the scheme of payload.v1.Search.MultiRequest

  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;
  }
  

  • Search.MultiRequest

    field	type	label	required	description
    requests	repeated(Array[Request])		*	The search request list

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

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

Output

• the scheme of payload.v1.Search.Responses.

  message Search {
    message Responses {
      repeated Response responses = 1;
    }
  
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message Distance {
      string id = 1;
      float distance = 2;
    }
  }
  

  • Search.Responses

    field	type	label	description
    responses	Response	repeated(Array[Response])	The list of search results response

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

MultiLinearSearchByID RPC

MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in 1 request.

Input

• the scheme of payload.v1.Search.MultiIDRequest stream

  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;
  }
  

  • Search.MultiIDRequest

    field	type	label	required	description
    requests	IDRequest	repeated(Array[IDRequest])	*	The searchByID request list.

  • Search.IDRequest

    field	type	label	required	description
    id	string		*	The vector ID to be searched.
    config	Config		*	The configuration of the search request.

  • Search.Config

    field	type	label	required	description
    request_id	string			Unique request ID.
    num	uint32		*	The maximum number of results to be returned.
    timeout	int64			Search timeout in nanoseconds (default value is 5s).
    ingress_filters	Filter.Config			Ingress Filter configuration.
    egress_filters	Filter.Config			Egress Filter configuration.
    min_num	uint32			The minimum number of results to be returned.
    aggregation_algorithm	AggregationAlgorithm			The search aggregation algorithm option (default value is ConcurrentQueue).

Output

• the scheme of payload.v1.Search.Responses.

  message Search {
    message Responses {
      repeated Response responses = 1;
    }
  
    message Response {
      string request_id = 1;
      repeated Object.Distance results = 2;
    }
  }
  
  message Object {
    message Distance {
      string id = 1;
      float distance = 2;
    }
  }
  

  • Search.Responses

    field	type	label	description
    responses	Response	repeated(Array[Response])	The list of search results response.

  • Search.Response

    field	type	label	description
    request_id	string		The unique request ID.
    results	Object.Distance	repeated(Array[Object.Distance])	Search results.

  • Object.Distance

    field	type	label	description
    id	string		The vector ID.
    distance	float		The distance between the result vector and the request vector.

Status Code

Please refer to Response Status Code 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.

See also