milvus-logo
LFAI
Home
  • User Guide

Conduct a Query

This topic describes how to conduct a query.

Unlike a vector similarity search, a query retrieves vectors via scalar filtering based on boolean expression. Milvus supports many data types in the scalar fields and a variety of boolean expressions. The boolean expression filters on scalar fields or the primary key field, and it retrieves all results that match the filters.

The following example shows how to perform a query on a 2000-row dataset of book ID (primary key), word count (scalar field), and book introduction (vector field), simulating the situation where you query for certain books based on their IDs.

Load collection

All search and query operations within Milvus are executed in memory. Load the collection to memory before conducting a query.

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.load()
await milvusClient.loadCollection({
  collection_name: "book",
});
err := milvusClient.LoadCollection(
  context.Background(),   // ctx
  "book",                 // CollectionName
  false                   // async
)
if err != nil {
  log.Fatal("failed to load collection:", err.Error())
}
milvusClient.loadCollection(
  LoadCollectionParam.newBuilder()
    .withCollectionName("book")
    .build()
);
load -c book
# See the following step.

Conduct a query

The following example filters the vectors with certain book_id values, and returns the book_id field and book_intro of the results.

Milvus supports setting consistency level specifically for a query. The example in this topic sets the consistency level as Strong. You can also set the consistency level as Bounded, Session or Eventually. See Consistency for more information about the four consistency levels in Milvus.

You can also use dynamic fields in the filter expression and output fields in the query requests. For example, refer to Dynamic Schema.

res = collection.query(
  expr = "book_id in [2,4,6,8]",
  offset = 0,
  limit = 10, 
  output_fields = ["book_id", "book_intro"],
)
const results = await milvusClient.query({
  collection_name: "book",
  expr: "book_id in [2,4,6,8]",
  output_fields: ["book_id", "book_intro"],
  limit: 10,
  offset: 0,
});
opt := client.SearchQueryOptionFunc(func(option *client.SearchQueryOption) {
    option.Limit = 3
    option.Offset = 0
    option.ConsistencyLevel = entity.ClStrong
    option.IgnoreGrowing = false
})

queryResult, err := milvusClient.Query(
    context.Background(),                                   // ctx
    "book",                                                 // CollectionName
    "",                                                     // PartitionName
    "book_id in [2,4,6,8]",                                 // expr
    []string{"book_id", "book_intro"},                      // OutputFields
    opt,                                                    // queryOptions
)
if err != nil {
    log.Fatal("fail to query collection:", err.Error())
}
List<String> query_output_fields = Arrays.asList("book_id", "word_count");
QueryParam queryParam = QueryParam.newBuilder()
  .withCollectionName("book")
  .withConsistencyLevel(ConsistencyLevelEnum.STRONG)
  .withExpr("book_id in [2,4,6,8]")
  .withOutFields(query_output_fields)
  .withOffset(0L)
  .withLimit(10L)
  .build();
R<QueryResults> respQuery = milvusClient.query(queryParam);
query

collection_name: book

The query expression: book_id in [2,4,6,8]

Name of partitions that contain entities(split by "," if multiple) []:

A list of fields to return(split by "," if multiple) []: book_id, book_intro

timeout []:
curl --request POST \
     --url '${MILVUS_HOST}:${MILVUS_PORT}/v1/vector/query' \
     --header 'Authorization: Bearer <TOKEN>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{
       "collectionName": "collection1",
       "outputFields": ["id", "name", "feature", "distance"],
       "filter": "id in (1, 2, 3)",
       "limit": 100,
       "offset": 0
     }'
Output:
{
    "code": 200,
    "data": {}
}
Parameter Description
expr Boolean expression used to filter attribute. Find more expression details in Boolean Expression Rules.
limit Number of the most similar results to return. The sum of this value and offset should be less than 16384.
offset Number of results to skip in the returned set. This parameter is available only when limit is specified, and the sum of this value and limit should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
output_fields (optional) Name of the field to return. Milvus supports returning the vector field.
partition_names (optional) List of names of the partitions to query on.
consistency_level (optional) Consistency level of the query.
Parameter Description
collection_name Name of the collection to query.
expr Boolean expression used to filter attribute. Find more expression details in Boolean Expression Rules.
output_fields (optional) Name of the field to return. Milvus supports returning the vector field.
limit (optional) Number of the most similar results to return. The sum of this value and offset should be less than 16384.
offset (optional) Number of results to skip in the returned set. This parameter is available only when limit is specified, and the sum of this value and limit should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
Parameter Description Options
ctx Context to control API invocation process. N/A
CollectionName Name of the collection to query. N/A
partitionName List of names of the partitions to load. All partitions will be queried if it is left empty. N/A
expr Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
OutputFields Name of the field to return. Milvus supports returning the vector field.
opts Query options in the form of entity.SearchQueryOptionFunc.
  • Limit Indicates the number of entities to return.
  • Offset Indicates the number of entities to skip during the search. The sum of this parameter and Limit should be less than 16384.
  • ConsistencyLevel Indicates the consistency level applied during the search.
  • Ignore Growing Indicates whether to ignore growing segments during similarity searches. The value defaults to False, indicating that searches involve growing segments.
Parameter Description Options
CollectionName Name of the collection to load. N/A
OutFields Name of the field to return. Milvus supports returning the vector field.
Expr Boolean expression used to filter attribute. See Boolean Expression Rules for more information.
Limit (optional) Number of the most similar results to return. The sum of this value and offset in WithOffset() should be less than 16384.
Offset (optional) Number of results to skip in the returned set. This parameter is available only when limit is specified, and the sum of this value and limit in WithLimit() should be less than 16384. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
ConsistencyLevel The consistency level used in the query. STRONG, BOUNDED, andEVENTUALLY.
Parameter Description
collectionName (Required) The name of the collection to which this operation applies.
filter The filter used to find matches for the search
limit The maximum number of entities to return.
The sum of this value of that of offset should be less than 1024.
The value defaults to 100.
The value ranges from 1 to 100
offset The number of entities to skip in the search results.
The sum of this value and that of limit should not be greater than 1024.
The maximum value is 1024. For example, if you want the 9th and 10th nearest neighbors to the query vector, set limit to 2 and offset to 8.
outputFields An array of fields to return along with the search results.

Check the returned results.

sorted_res = sorted(res, key=lambda k: k['book_id'])
sorted_res
console.log(results.data)
fmt.Printf("%#v\n", queryResult)
for _, qr := range queryResult {
    for i := 0; i < qr.Len(); i++ {
        value, _ := qr.Get(i)
        fmt.Println(value)
    }
}
QueryResultsWrapper wrapperQuery = new QueryResultsWrapper(respQuery.getData());
System.out.println(wrapperQuery.getFieldWrapper("book_id").getFieldData());
System.out.println(wrapperQuery.getFieldWrapper("word_count").getFieldData());
```shell # Milvus CLI automatically returns the entities with the pre-defined output fields. ```
# See the output of the previous step.

Count entities

When conducting a query, you can append count(*) to output_fields, so Milvus can return the number of entities in the collection. If you want to count entities that meet specific conditions, use expr to define a Boolean expression.

Count all entities in a collection:

res = collection.query(
  expr="", 
  output_fields = ["count(*)"],
)

print(res)
print(res[0])

# Output:
# [{'count(*)': 2996}]
# {'count(*)': 2996}

Count entities that meet specific filter conditions:

res = collection.query(
  # filter entities whose ID is in the specified list
  expr="book_id in [2,4,6,8]", 
  output_fields = ["count(*)"],
)

print(res)
print(res[0])

# Output:
# [{'count(*)': 2996}]
# {'count(*)': 2996}

Limits

When count(*) is used in output_fields, the limit parameter is forbidden.

What's next