Skip to main content

Query

In addition to ANN searches, Zilliz Cloud also supports metadata filtering through queries. This page introduces how to use Query, Get, and QueryIterators to perform metadata filtering.

Notes

If you add new fields after the collection has been created, queries that include these fields return the defined default values or NULL for entities that have not explicitly set values. For details, refer to Alter Collection Schema.

Overview​

A Collection can store various types of scalar fields. You can have Zilliz Cloud filter Entities based on one or more scalar fields. Zilliz Cloud offers three types of queries: Query, Get, and QueryIterator. The table below compares these three query types.

Get

Query

QueryIterator

Applicable scenarios

To find entities that hold the specified primary keys.

To find all or a specified number of entities that meet the custom filtering conditions

To find all entities that meet the custom filtering conditions in paginated queries.

Filtering method

By primary keys

By filtering expressions.

By filtering expressions.

Mandatory parameters

  • Collection name

  • Primary keys

  • Collection name

  • Filtering expressions

  • Collection name

  • Filtering expressions

  • Number of entities to return per query

Optional parameters

  • Partition name

  • Output fields

  • Partition name

  • Number of entities to return

  • Output fields

  • Partition name

  • Number of entities to return in total

  • Output fields

Returns

Returns entities that hold the specified primary keys in the specified collection or partition.

Returns all or a specified number of entities that meet the custom filtering conditions in the specified collection or partition.

Returns all entities that meet the custom filtering conditions in the specified collection or partition through paginated queries.

For more on metadata filtering, refer to Filtering ExplainedFiltering Explained.

Use Get​

When you need to find entities by their primary keys, you can use the Get method. The following code examples assume that there are three fields named id, vector, and color in your collection.

plaintext
[
        {"id": 0, "vector": [0.3580376395471989, -0.6023495712049978, 0.18414012509913835, -0.26286205330961354, 0.9029438446296592], "color": "pink_8682"},
        {"id": 1, "vector": [0.19886812562848388, 0.06023560599112088, 0.6976963061752597, 0.2614474506242501, 0.838729485096104], "color": "red_7025"},
        {"id": 2, "vector": [0.43742130801983836, -0.5597502546264526, 0.6457887650909682, 0.7894058910881185, 0.20785793220625592], "color": "orange_6781"},
        {"id": 3, "vector": [0.3172005263489739, 0.9719044792798428, -0.36981146090600725, -0.4860894583077995, 0.95791889146345], "color": "pink_9298"},
        {"id": 4, "vector": [0.4452349528804562, -0.8757026943054742, 0.8220779437047674, 0.46406290649483184, 0.30337481143159106], "color": "red_4794"},
        {"id": 5, "vector": [0.985825131989184, -0.8144651566660419, 0.6299267002202009, 0.1206906911183383, -0.1446277761879955], "color": "yellow_4222"},
        {"id": 6, "vector": [0.8371977790571115, -0.015764369584852833, -0.31062937026679327, -0.562666951622192, -0.8984947637863987], "color": "red_9392"},
        {"id": 7, "vector": [-0.33445148015177995, -0.2567135004164067, 0.8987539745369246, 0.9402995886420709, 0.5378064918413052], "color": "grey_8510"},
        {"id": 8, "vector": [0.39524717779832685, 0.4000257286739164, -0.5890507376891594, -0.8650502298996872, -0.6140360785406336], "color": "white_9381"},
        {"id": 9, "vector": [0.5718280481994695, 0.24070317428066512, -0.3737913482606834, -0.06726932177492717, -0.6980531615588608], "color": "purple_4976"},
]

You can get entities by their IDs as follows.

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

res = client.get(
    collection_name="my_collection",
    ids=[0, 1, 2],
    output_fields=["vector", "color"]
)

print(res)

Use Query​

Basic Query​

When you need to find entities by custom filtering conditions, use the Query method. The following code examples assume there are three fields named id, vector, and color and return the specified number of entities that hold a color value starting with red.

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

res = client.query(
    collection_name="my_collection",
    filter="color like \"red%\"",
    output_fields=["vector", "color"],
    limit=3
)

Sort Query Results​

By default, Query returns results in an unspecified order. Use the order_by parameter to sort results by one or more scalar fields. When using order_by, note that:

  • order_by must be used together with limit.

  • Supported field types: INT8, INT16, INT32, INT64, FLOAT, DOUBLE, and VARCHAR. Sorting by vector, JSON, or ARRAY fields is not supported.

  • When sorting by a nullable field, NULL values are placed at the end for ascending order (NULLS LAST) and at the beginning for descending order (NULLS FIRST).

Basic Sort​

Pass a list of "field_name:direction" strings to the order_by parameter, where direction is either asc (ascending) or desc (descending). Note that asc and desc are case-sensitive.

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

# Sort results by id in ascending order
res = client.query(
    collection_name="my_collection",
    filter="color like \"red%\"",
    output_fields=["vector", "color"],
    limit=3,
    order_by=["id:asc"],
)

Multi-field Sort​

You can sort by multiple fields at once. Results are first ordered by the first field in the list. When two rows have the same value in that field, the second field determines their order, and so on.

python
# Sort by rating descending, then by price ascending for ties
res = client.query(
    collection_name="my_collection",
    filter="",
    output_fields=["color", "rating", "price"],
    limit=10,
    order_by=["rating:desc", "price:asc"],
)

Pagination with Sort​

Use order_by together with limit and offset to paginate through sorted results. For example, to display a product list sorted by price across multiple pages, each page shows the next batch of items in the correct price order without duplicates or gaps.

python
# Page 1
page1 = client.query(
    collection_name="my_collection",
    filter="color like \"red%\"",
    output_fields=["color", "price"],
    limit=5,
    offset=0,
    order_by=["price:asc"],
)

# Page 2
page2 = client.query(
    collection_name="my_collection",
    filter="color like \"red%\"",
    output_fields=["color", "price"],
    limit=5,
    offset=5,
    order_by=["price:asc"],
)

Aggregate Query Results​

You can group query results by one or more scalar fields and compute aggregations per group. The supported aggregation operators are count, min, max, sum, and avg.

When using group_by_fields, note that:

  • Supported field types for group_by_fields: INT8, INT16, INT32, INT64, VARCHAR, and TIMESTAMPTZ. Grouping by FLOAT, DOUBLE, vector, JSON, or ARRAY fields returns an error.

  • sum and avg are numeric only — applying them to a VARCHAR field returns an error.

To enable aggregation, pass group_by_fields to query() and add aggregation expressions (count(*), count(<field>), min(<field>), max(<field>), sum(<field>), avg(<field>)) to output_fields.

The following example groups entities by the color field and returns the number of entities in each color group:

python
from pymilvus import MilvusClient

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

res = client.query(
    collection_name="my_collection",
    filter="",
    group_by_fields=["color"],
    output_fields=["color", "count(*)"],
)

# [{'color': 'red',    'count(*)': 10},
#  {'color': 'orange', 'count(*)': 10},
#  {'color': 'yellow', 'count(*)': 10},
#  {'color': 'green',  'count(*)': 10},
#  {'color': 'blue',   'count(*)': 10}]

You can request several aggregation expressions in a single call. The following example groups by color and returns the row count, average price, and maximum rating for each group:

python
res = client.query(
    collection_name="my_collection",
    filter="",
    group_by_fields=["color"],
    output_fields=["color", "count(*)", "avg(price)", "max(rating)"],
)

# [{'color': 'red',    'count(*)': 10, 'avg(price)': 65.22, 'max(rating)': 5},
#  {'color': 'orange', 'count(*)': 10, 'avg(price)': 48.67, 'max(rating)': 5},
#  {'color': 'yellow', 'count(*)': 10, 'avg(price)': 64.15, 'max(rating)': 3},
#  {'color': 'green',  'count(*)': 10, 'avg(price)': 58.28, 'max(rating)': 5},
#  {'color': 'blue',   'count(*)': 10, 'avg(price)': 50.20, 'max(rating)': 5}]

Pass more than one field to group_by_fields to compute composite groups. The following example groups by (color, rating) and computes the price range in each bucket:

python
res = client.query(
    collection_name="my_collection",
    filter="",
    group_by_fields=["color", "rating"],
    output_fields=["color", "rating", "min(price)", "max(price)"],
)

# [{'color': 'red',    'rating': 5, 'min(price)': 34.51, 'max(price)': 70.90},
#  {'color': 'orange', 'rating': 2, 'min(price)': 12.39, 'max(price)': 81.99},
#  {'color': 'yellow', 'rating': 2, 'min(price)': 22.62, 'max(price)': 88.24},
#  {'color': 'green',  'rating': 1, 'min(price)': 18.35, 'max(price)': 59.53},
#  {'color': 'blue',   'rating': 4, 'min(price)': 21.23, 'max(price)': 82.45},
#  ...]

You can also combine group_by_fields with limit to cap how many groups come back — useful when a field has high cardinality and you only need a sample of buckets:

python
res = client.query(
    collection_name="my_collection",
    filter="",
    group_by_fields=["color"],
    output_fields=["color", "avg(price)", "count(*)"],
    limit=5,
)

# [{'color': 'red',    'avg(price)': 65.22, 'count(*)': 10},
#  {'color': 'orange', 'avg(price)': 48.67, 'count(*)': 10},
#  {'color': 'yellow', 'avg(price)': 64.15, 'count(*)': 10},
#  {'color': 'green',  'avg(price)': 58.28, 'count(*)': 10},
#  {'color': 'blue',   'avg(price)': 50.20, 'count(*)': 10}]

Use QueryIterator​

When you need to find entities by custom filtering conditions through paginated queries, create a QueryIterator and use its next() method to iterate over all entities to find those meeting the filtering conditions. The following code examples assume that there are three fields named id, vector, and color and return all entities that hold a color value starting with red.

python
iterator = client.query_iterator(
    "my_collection",
    batch_size=10,
    filter="color like \"red%\"",
    output_fields=["color"]
)

results = []

while True:
    result = iterator.next()
    if not result:
        iterator.close()
        break

    print(result)
    results += result

Queries in Partitions​

You can also perform queries within one or multiple partitions by including the partition names in the Get, Query, or QueryIterator request. The following code examples assume that there is a partition named PartitionA in the collection.

python
res = client.get(
    collection_name="my_collection",
    partition_names=["partitionA"],
    ids=[10, 11, 12],
    output_fields=["vector", "color"]
)

res = client.query(
    collection_name="my_collection",
    partition_names=["partitionA"],
    filter="color like \"red%\"",
    output_fields=["vector", "color"],
    limit=3
)

# Use QueryIterator
iterator = client.query_iterator(
    "my_collection",
    partition_names=["partitionA"],
    batch_size=10,
    filter="color like \"red%\"",
    output_fields=["color"]
)

results = []
while True:
    result = iterator.next()
    if not result:
        iterator.close()
        break

    print(result)
    results += result

Random Sampling with Query​

To extract a representative subset of data from your collection for data exploration or development testing, use the RANDOM_SAMPLE(sampling_factor) expression, where the sampling_factor is a float between 0 and 1 representing the percentage of data to sample.

Notes

For detailed usage, advanced examples, and best practices, refer to Random Sampling.

python
# Sample 1% of the entire collection
res = client.query(
    collection_name="my_collection",
    filter="RANDOM_SAMPLE(0.01)",
    output_fields=["vector", "color"]
)

print(f"Sampled {len(res)} entities from collection")

# Combine with other filters - first filter, then sample
res = client.query(
    collection_name="my_collection", 
    filter="color like \"red%\" AND RANDOM_SAMPLE(0.005)",
    output_fields=["vector", "color"],
    limit=10
)

print(f"Found {len(res)} red items in sample")

Temporarily Set a Timezone for a Query​

If your collection has a TIMESTAMPTZ field, you can temporarily override the database or collection default timezone for a single operation by setting the timezone parameter in the query call. This controls how TIMESTAMPTZ values are displayed and compared during the operation.

The value of timezone must be a valid IANA time zone identifier (for example, Asia/Shanghai, America/Chicago, or UTC). For details on how to use a TIMESTAMPTZ field, refer to TIMESTAMPTZ Field.

The example below shows how to temporarily set a timezone for a query operation:

python
# Query data and display the tsz field converted to "America/Havana"
results = client.query(
    "my_collection",
    filter="id <= 10",
    output_fields=["id", "tsz", "vec"],
    limit=2,
    timezone="America/Havana",
)
Was this page helpful?
Ctrl I