query()
Queries a collection with a scalar filter and returns the matching entities.
pub async fn query(&self, request: QueryRequest) -> Result<QueryResponse>
Request Syntax
let request = QueryRequest::builder()
.collection_name("books")
.filter("id > 0")
.output_fields(["genre", "count(*)"])
.group_by_fields(["genre"])
.limit(10)
.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 query. Required.
partition_names: Vec<String>Partition names to restrict the query to; queries the whole collection when empty.
ids: IdsPrimary keys of the entities to retrieve. Mutually exclusive with
filter. See Ids.filter: StringScalar filter expression that selects the entities. Mutually exclusive with
ids.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 fields returned for each row.
limit: Option<i64>Maximum number of rows to return.
Nonereturns all matching rows.offset: Option<i64>Number of leading rows to skip. For
element_filterqueries the offset counts matched elements (the server and the query iterator seek both skip matched elements, mirroring pymilvus); otherwise it counts rows.ignore_growing: boolWhether to ignore growing segments during the query. Defaults to
false.timezone: StringTimezone applied when querying or filtering Timestamptz fields.
consistency_level: Option<ConsistencyLevel>Consistency guarantee for the query; the collection default is used when unset. See ConsistencyLevel.
order_by_fields: Vec<OrderByField>Scalar fields used to order the query results. See OrderByField.
extra_params: HashMap<String, String>Additional query parameters.
group_by_fields: Vec<String>Scalar fields used to group aggregation results. Combine them with aggregate expressions such as
count(*)orsum(field)inoutput_fields; the server returns one row per group. Useadd_group_by_field()to add one.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 QueryResponse containing the rows matched by the query. Returns an Error if the operation fails.
QueryResponse
results() // -> &QueryResults
session_timestamp() // -> u64
cost() // -> i64
scanned_remote_bytes() // -> i64
scanned_total_bytes() // -> i64
cache_hit_ratio() // -> f32
METHODS:
results()(&QueryResults) -The rows matched by the query.
get_output_fields()(&[FieldData]) -The output field values of the returned rows. See FieldData.
get_output_field_names()(&[String]) -The names of the output fields.
get_output_field()(Option<&FieldData>) -The value of the named output field for the returned rows, when present. See FieldData.
get_row_count()(u64) -The number of rows returned. This counts the entity rows backing the columnar field data. When the result came from an
element_filterquery, the row materializers instead yield one row per matched element; useget_element_row_count()to count the matched elements those rows address.get_element_row_count()(u64) -The number of rows yielded by the row materializers. For
element_filterresults this is the number of matched elements (each entity may match several); otherwise it equalsget_row_count().get_element_indices()(&[Vec] ) -The element indices of the matched rows, one inner list per entity when an
element_filteriterator is used.is_empty()(bool) -Whether no rows were returned.
get_output_rows()(Result> ) -The returned rows as entity values. See EntityRow.
get_output_row()(Result) - The row at the given index as an entity value. See EntityRow.
rows()(Result) - Returns a borrowing iterator over the matched rows, reading values directly from the column-oriented result data.
session_timestamp()(u64) -The session timestamp of the query.
cost()(i64) -The execution cost reported by the server.
scanned_remote_bytes()(i64) -The number of bytes scanned remotely.
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 = QueryRequest::builder()
.collection_name("books")
.filter("id > 0")
.output_fields(["id", "title"])
.limit(10)
.build()?;
let resp = client.query(request).await?;