跳到主要内容
版本：Cloud 开发指南

Query

Zilliz Cloud 除了支持 ANN Search 外，还提供基于标量的过滤查询功能。本节将介绍如何使用 Query、Get 和 QueryIterator 进行标量查询以及进行标量查询时的注意事项。

概述​

Collection 中可以存储多种类型的标量字段。您可以让 Milvus 基于一个或多个标量字段进行过滤查询，找出符合指定条件的部分或所有 Entity。Zilliz Cloud 提供了三种过滤查询的方法，分别为 Query、Get 和 QueryIterator。下表对这三种过滤查询方法进行了比较。

Get

Query

QueryIterator

适用场景

要求根据主键值查询，返回指定 Entity。

要求根据自定义条件查询，且返回所有或指定数量的符合条件的 Entity。

要求根据自定义条件查询，且分页返回所有符合条件的 Entity。

过滤方法

基于主键字段过滤。

基于过滤条件表达式过滤。

基于过滤条件表达式过滤。

必选参数

  • Collection 名称

  • 主键值

  • Collection 名称

  • 过滤条件表达式

  • Collection 名称

  • 过滤条件表达式

  • 单页返回 Entity 数量

可选参数

  • Partition 名称

  • 返回 Entity 携带字段名称

  • Partition 名称

  • 返回 Entity 数量

  • 返回 Entity 携带字段名称

  • Partition 名称

  • 返回 Entity 总数量

  • 返回 Entity 携带字段名称

返回结果

返回 Collection 或指定 Partition 中符合指定主键值的 Entity。

返回 Collection 或指定 Partition 中所有或指定数量的符合指定过滤条件的 Entity。

分页返回 Collection 或指定 Partition 中所有符合指定过滤条件的 Entity。

关于过滤条件表达式的更多细节，可参考过滤表达式概览。

使用 Get​

当您需要根据 Entity 主键从 Collection 或 Partition 中查询 Entity 时，可以使用 Get 方法。如下代码示例中假设 Collection 有 id、vector 和 color 三个字段。

[
        {"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"},
]

您可以参考如下代码示例获取主键值为 0、1、2 的三个 Entity。

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)

使用 Query​

当您需要根据自定义条件查询，且返回所有或指定数量的符合条件的 Entity 时，可以使用 Query 方法。如下代码示例中假设 Collection 有 id、vector 和 color 三个字段。要求返回三个 color 以 red 开头的 Entity。

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
)

使用 QueryIterator​

当您需要根据自定义条件查询，且分页返回所有符合条件的 Entity，可以使用 QueryIterator 创建一个迭代器。然后使用迭代器的 next() 方法循环遍历所有符合条件的 Entity。如下代码示例中假设 Collection 有 id、vector 和 color 三个字段。要求返回所有 color 以 red 开头的 Entity。

from pymilvus import MilvusClient

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

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

在 Partition 中过滤查询​

除了在 Collection 中进行过滤查询外，还可以在指定的一个或多个 Partition 中进行过滤查询，只需要在上面的 Get、Query 和 QueryIterator 方法中增加 Partition 名称即可。如下示例代码中假设 Collection 中存在一个名为 PartitionA 的 Partition。

from pymilvus import MilvusClient
client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

res = client.get(
    collection_name="my_collection",
    # highlight-next-line
    partitionNames=["partitionA"],
    ids=[10, 11, 12],
    output_fields=["vector", "color"]
)

res = client.query(
    collection_name="my_collection",
    # highlight-next-line
    partitionNames=["partitionA"],
    filter="color like \"red%\"",
    output_fields=["vector", "color"],
    limit=3
)

# Use QueryIterator
from pymilvus import connections, Collection

connections.connect(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN"
)

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

使用 Query 进行随机取样​

若要从数据集中提取具有代表性的数据子集用于数据探索或开发测试，请使用 RANDOM_SAMPLE(sampling_factor) 表达式，其中 sampling_factor 是一个介于 0 和 1 之间的浮点数，表示要采样的数据百分比。

📘说明

关于随机采样的详细使用方法、高级示例和最佳实践，可参考随机采样。

from pymilvus import MilvusClient

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

# Sample 1% of the entire collection
res = client.query(
    collection_name="my_collection",
    # highlight-next-line
    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", 
    # highlight-next-line
    filter="color like \"red%\" AND RANDOM_SAMPLE(0.005)",
    output_fields=["vector", "color"],
    limit=10
)

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

为 Query 临时设置一个时区​

如果你的 Collection 包含 TIMESTAMPTZ 字段，你可以在一次操作中通过在 query 调用中设置 timezone 参数，临时覆盖 Database 或 Collection 的默认时区。这会控制在该次操作中 TIMESTAMPTZ 值的显示和比较方式。

以下示例展示了如何为 query 操作设置临时时区：

# 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,
    # highlight-next-line
    timezone="America/Havana",
)

参数 timezone 的值必须是有效的 IANA 时区标识符，例如 Asia/Shanghai、America/Chicago 或 UTC。关于如何使用 TIMESTAMPTZ 字段的详细信息，请参见TIMESTAMPTZ 类型。