search()
Searches vector fields and returns ranked hits for each query vector.
pub async fn search(&self, request: SearchRequest) -> Result<SearchResponse>
Request Syntax
let request = SearchRequest::builder()
.collection_name("books")
.vector_field("embedding")
.vectors(SearchVectors::Float(vec![vec![0.1, 0.2, 0.3, 0.4]]))
.output_fields(["id", "title"])
.limit(5)
.build()?;
REQUEST FIELDS:
database_name: Option<String>Name of the target database; uses the default database when empty.
collection_name: StringName of the collection to search. Required.
ids: IdsPrimary keys whose stored vectors are used as search targets. Mutually exclusive with
vectors; when set, no query vectors or vector field are needed. See Ids.vector_field: StringName of the vector field to search (the ANN field). Not required when the request targets primary-key IDs via
ids.vectors: SearchVectorsQuery vectors, one per query. Supports dense float, binary, float16, bfloat16, sparse, int8, embedded-text, and struct embedding-list inputs. See SearchVectors.
partition_names: Vec<String>Partition names to restrict the search to; searches the whole collection when empty.
filter: StringScalar filter expression applied before the vector search.
filter_templates: HashMap<String, FilterTemplateValue>Placeholder values referenced by the filter expression. Use
add_filter_template()to add one. See FilterTemplateValue.output_fields: Vec<String>Names of the scalar fields returned for each hit.
limit: i64Number of hits returned per query vector. Defaults to
10.offset: i64Number of leading hits to skip per query vector. Defaults to
0.round_decimal: i64Number of decimal places for the returned scores;
-1disables rounding. Defaults to-1.ignore_growing: boolWhether to ignore growing segments during the search. Defaults to
false.group_by_field: StringScalar field used to group the search results.
group_size: i64Number of results to return per group. Defaults to
1.strict_group_size: boolWhether each group must return exactly
group_sizeresults. Defaults tofalse.radius: Option<f64>Range-search radius that filters the returned distances.
range_filter: Option<f64>Lower or upper distance bound used together with
radius.metric_type: Option<MetricType>Distance or similarity metric for the search; the server default is used when unset. See MetricType.
order_by_fields: Vec<OrderByField>Scalar fields used to order the search results. See OrderByField.
extra_params: HashMap<String, String>Additional search parameters, such as
nprobeoref.rerank: Option<FunctionScore>Reranking configuration for single-vector search. Mutually exclusive with
function_chains.This struct carries reranking functions and combination settings used by search.
pub struct FunctionScorePARAMETERS:
functions: Vec<Function>Reranking functions applied to the candidate set. See Function.
params: HashMap<String, serde_json::Value>Combination settings for the reranking functions.
METHODS:
new()- Creates a value initialized with its SDK defaults.functions(value)/set_functions(value)/get_functions()- Sets or returns the functions.add_function(value)- Adds one function to the existing values.params(value)/set_params(value)/get_params()- Sets or returns the params.
timezone: StringTimezone applied when searching or filtering Timestamptz fields.
highlighter: Option<Highlighter>Text-highlighting configuration for full-text search.
This struct configures text highlighting for search results.
pub struct HighlighterPARAMETERS:
highlight_type: HighlightTypeHighlighting strategy,
LexicalorSemantic. Defaults toLexical.params: HashMap<String, String>Highlighting parameters, such as pre-tags, post-tags, and fragment settings.
METHODS:
new()- Creates a value initialized with its SDK defaults.highlight_type(value)/set_highlight_type(value)/get_highlight_type()- Sets or returns the highlight type.params(value)/set_params(value)/get_params()- Sets or returns the highlighting parameters.
Highlighteralso implementsFrom<LexicalHighlighter>andFrom<SemanticHighlighter>to convert a typed highlighter into its parameterized form.consistency_level: Option<ConsistencyLevel>Consistency guarantee for the search; the collection default is used when unset. See ConsistencyLevel.
function_chains: Vec<FunctionChain>Function chains used to post-process the search results. Mutually exclusive with
rerank. Useadd_function_chain()to add one. See FunctionChain.search_aggregation: Option<SearchAggregation>Hierarchical bucket aggregation settings for the search.
This struct describes one level of hierarchical bucket aggregation for a search request, recursively nestable. Attach it to a search request with
SearchRequestBuilder::search_aggregation. It is mutually exclusive withgroup_by_field; when set, the searchlimitis ignored andsizecontrols the top-level bucket count.pub struct SearchAggregationPARAMETERS:
fields: Vec<String>Group-by fields. Must contain at least one field.
size: i64Maximum number of buckets returned at this level. Must be positive.
metrics: HashMap<String, MetricSpec>Metric aggregations keyed by alias.
order: Vec<OrderSpec>Ordering rules applied to the buckets at this level. Each key is a metric alias or one of the special keys
_count/_key.top_hits: Option<TopHitsSpec>Document snapshot returned for each bucket at this level.
sub_aggregation: Option<Box<SearchAggregation>>Nested recursive aggregation level.
METHODS:
new()- Creates a value initialized with its SDK defaults.fields(value)/set_fields(value)/get_fields()- Sets or returns the group-by fields.add_field(value)- Appends a group-by field.size(value)/set_size(value)/get_size()- Sets or returns the maximum bucket count.metrics(value)/set_metrics(value)/get_metrics()- Sets or returns the metric aggregations.add_metric(alias, value)- Adds a metric aggregation by alias.order(value)/set_order(value)/get_order()- Sets or returns the ordering rules.add_order(value)- Appends an ordering rule.top_hits(value)/set_top_hits(value)/get_top_hits()- Sets or returns the top-hits snapshot.sub_aggregation(value)/set_sub_aggregation(value)/get_sub_aggregation()- Sets or returns the nested level.validate()- Validates that the aggregation can be attached to a search request.
MetricOp
Avg- Average of the grouped values. Default operator forMetricSpec::new().Sum- Sum of the grouped values.Count- Number of retained candidates in each group;NULLvalues are skipped when a field is specified.Min- Minimum of the grouped values.Max- Maximum of the grouped values.
AggDirection
Asc- Sort aggregation buckets in ascending order.Desc- Sort aggregation buckets in descending order. This is the default direction.
SortDirectionis a deprecated alias forAggDirection, retained for compatibility with Rust SDK 3.0.0.MetricSpec
A metric aggregation over a field, keyed by alias in
SearchAggregation.MetricSpec::new() .op(MetricOp::Avg) .field_name("price")METHODS:
op(value)/set_op(value)/get_op()- Sets or returnsMetricOp.field_name(value)/set_field_name(value)/get_field_name()- Sets or returns the target field.
OrderSpec
An ordering rule applied to buckets at an aggregation level.
OrderSpec::new() .key("avg_price") .direction(AggDirection::Desc) .null_first(false)METHODS:
key(value)/set_key(value)/get_key()- Sets or returns the metric alias,"_count", or"_key".direction(value)/set_direction(value)/get_direction()- Sets or returnsAggDirection.null_first(value)/set_null_first(value)/is_null_first()- Sets or returns whether null values sort first.
TopHitsSpec
A document snapshot returned for each bucket at an aggregation level.
TopHitsSpec::new() .size(3) .sort([SortSpec::new().field_name("price").direction(AggDirection::Desc)])METHODS:
size(value)/set_size(value)/get_size()- Sets or returns the number of top hits per bucket.sort(values)/set_sort(values)/get_sort()- Sets or returnsSortSpecrules.add_sort(value)- Appends aSortSpecrule.
SortSpec
A top-hits sort criterion.
SortSpec::new() .field_name("price") .direction(AggDirection::Desc) .null_first(false)METHODS:
field_name(value)/set_field_name(value)/get_field_name()- Sets or returns the field to sort by.direction(value)/set_direction(value)/get_direction()- Sets or returnsAggDirection.null_first(value)/set_null_first(value)/is_null_first()- Sets or returns whether null values sort first.
rls_principal: Option<String>Principal name used to enforce row-level security. Required for requests against an RLS-enabled collection unless
skip_rlsis set.skip_rls: boolWhether the request explicitly bypasses row-level security. Defaults to
false.
RETURN TYPE:
Result
RETURNS:
A SearchResponse containing the ranked hits for each query vector. Returns an Error if the operation fails.
SearchResponse
results() // -> &SearchResults
session_timestamp() // -> u64
cost() // -> i64
scanned_remote_bytes() // -> i64
scanned_total_bytes() // -> i64
cache_hit_ratio() // -> f32
METHODS:
results()(&SearchResults) -The ranked hits, one group per query vector.
get_results()(&[SingleResult]) -The hits, one per query vector.
get_ids()(&Ids) -The IDs of the hits for one query vector. See Ids.
get_scores()(&[f32]) -The similarity scores of the hits.
get_element_indices()(Option<&[i64]>) -The element indices of the hits, when present.
get_output_fields()(&[FieldData]) -The output field values of the hits. See FieldData.
get_output_field_names()(&[String]) -The names of the output fields.
get_primary_field_name()(&str) -The name of the primary-key field.
get_score_field_name()(&str) -The name of the score field.
get_highlight_results()(&[HashMap] ) -The text-highlighting results per hit, when full-text search highlighting was requested.
get_field_name()(&str) -The name of the highlighted field.
get_fragments()(&[String]) -The highlighted text fragments.
get_scores()(&[f32]) -The relevance scores of the fragments.
len()(usize) -The number of hits for one query vector.
is_empty()(bool) -Whether no hits were returned for the query vector.
get_output_field()(Option<&FieldData>) -The value of the named output field for the hit, when present. See FieldData.
get_output_rows()(Result> ) -The hits as entity rows. See EntityRow.
get_output_row()(Result) - The hit at the given index as an entity row. See EntityRow.
rows()(Result) - Returns a borrowing iterator over the matched rows, reading values directly from the column-oriented result data.
get_recalls()(&[f32]) -The recall rate per query vector.
len()(usize) -The number of hit groups returned.
is_empty()(bool) -Whether no hits were returned.
iter()(std::slice::Iter) - Iterates over the result associated with each query vector.
get_agg_buckets()(&[Vec] ) -The aggregation buckets produced by the search.
get_key()(&[BucketKeyEntry]) -The bucket keys, one entry per grouped field.
get_field_id()(i64) -The ID of the field the key belongs to.
get_field_name()(&str) -The name of the field the key belongs to.
get_value()(&AggregationBucketValue) -The value of the bucket key.
get_count()(i64) -The number of rows in the bucket.
get_metrics()(&HashMap) - The metric values computed for the bucket. See AggregationMetricValue.
get_hits()(&[AggregationHit]) -The representative hits of the bucket.
get_pk()(Option<&AggregationHitPk>) -The primary key of the representative hit.
get_score()(f32) -The score of the representative hit.
get_fields()(&[AggregationHitField]) -The field values of the representative hit.
get_field_id()(i64) -The ID of the field.
get_field_name()(&str) -The name of the field.
get_value()(&AggregationHitFieldValue) -The value of the field.
get_sub_groups()(&[AggregationBucket]) -The nested sub-buckets of the bucket.
session_timestamp()(u64) -The session timestamp of the search.
cost()(i64) -The execution cost reported by the server.
scanned_remote_bytes()(i64) -The number of bytes scanned from remote storage.
scanned_total_bytes()(i64) -The total number of bytes scanned.
cache_hit_ratio()(f32) -The ratio of scanned bytes served from the cache.
Example
let request = SearchRequest::builder()
.collection_name("books")
.vector_field("embedding")
.vectors(SearchVectors::Float(vec![vec![0.1, 0.2, 0.3, 0.4]]))
.output_fields(["id", "title"])
.limit(5)
.build()?;
let resp = client.search(request).await?;