Consulta

Para além das pesquisas ANN, o Milvus também suporta a filtragem de metadados através de consultas. Esta página apresenta como utilizar as funções Query, Get e QueryIterators para recuperar entidades, filtrar metadados, ordenar resultados de consultas e agregar valores escalares.

Visão geral

Uma coleção pode armazenar vários tipos de campos escalares. Pode fazer com que o Milvus filtre entidades com base num ou mais campos escalares. O Milvus oferece três tipos de consultas: Query, Get e QueryIterator. A tabela abaixo compara estes três tipos de consultas.

	Get	Query	QueryIterator
Cenários aplicáveis	Para encontrar entidades que possuam as chaves primárias especificadas.	Para encontrar todas as entidades ou um número especificado de entidades que cumpram as condições de filtragem personalizadas	Para encontrar todas as entidades que cumprem as condições de filtragem personalizadas em consultas paginadas.
Método de filtragem	Por chaves primárias	Por expressões de filtragem.	Por expressões de filtragem.
Parâmetros obrigatórios	Nome da coleção Chaves primárias	Nome da coleção Expressões de filtragem	Nome da coleção Expressões de filtragem Número de entidades a devolver por consulta
Parâmetros opcionais	Nome da partição Campos de saída	Nome da partição Número de entidades a devolver Campos de saída	Nome da partição Número total de entidades a devolver Campos de saída
Resultados	Devolve as entidades que contêm as chaves primárias especificadas na coleção ou partição indicada.	Devolve todas as entidades ou um número especificado de entidades que cumprem as condições de filtragem personalizadas na coleção ou partição especificada.	Devolve todas as entidades que cumprem as condições de filtragem personalizadas na coleção ou partição especificada, através de consultas paginadas.

Para mais informações sobre a filtragem de metadados, consulte Regras de expressões booleanas.

Utilizar Get

Quando precisar de encontrar entidades pelas suas chaves primárias, pode utilizar o método Get. Os exemplos de código seguintes partem do princípio de que existem três campos denominados id, vector e color na sua coleção.

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

Pode obter entidades pelas suas IDs da seguinte forma.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

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

print(res)

import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.service.vector.request.GetReq
import io.milvus.v2.service.vector.request.GetResp
import io.milvus.v2.service.vector.response.QueryResp;
import java.util.*;

MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
        .uri("http://localhost:19530")
        .token("root:Milvus")
        .build());
        
GetReq getReq = GetReq.builder()
        .collectionName("my_collection")
        .ids(Arrays.asList(0, 1, 2))
        .outputFields(Arrays.asList("vector", "color"))
        .build();

GetResp getResp = client.get(getReq);

List<QueryResp.QueryResult> results = getResp.getGetResults();
for (QueryResp.QueryResult result : results) {
    System.out.println(result.getEntity());
}

// Output
// {color=pink_8682, vector=[0.35803765, -0.6023496, 0.18414013, -0.26286206, 0.90294385], id=0}
// {color=red_7025, vector=[0.19886813, 0.060235605, 0.6976963, 0.26144746, 0.8387295], id=1}
// {color=orange_6781, vector=[0.43742132, -0.55975026, 0.6457888, 0.7894059, 0.20785794], id=2}

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/column"
    "github.com/milvus-io/milvus/client/v2/entity"
    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

milvusAddr := "localhost:19530"
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

resultSet, err := client.Get(ctx, milvusclient.NewQueryOption("my_collection").
    WithConsistencyLevel(entity.ClStrong).
    WithIDs(column.NewColumnInt64("id", []int64{0, 1, 2})).
    WithOutputFields("vector", "color"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println("id: ", resultSet.GetColumn("id").FieldData().GetScalars())
fmt.Println("vector: ", resultSet.GetColumn("vector").FieldData().GetVectors())
fmt.Println("color: ", resultSet.GetColumn("color").FieldData().GetScalars())

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "http://localhost:19530";
const token = "root:Milvus";
const client = new MilvusClient({address, token});

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

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/get" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "id": [0, 1, 2],
    "outputFields": ["vector", "color"]
}'

# {"code":0,"cost":0,"data":[{"color":"pink_8682","id":0,"vector":[0.35803765,-0.6023496,0.18414013,-0.26286206,0.90294385]},{"color":"red_7025","id":1,"vector":[0.19886813,0.060235605,0.6976963,0.26144746,0.8387295]},{"color":"orange_6781","id":2,"vector":[0.43742132,-0.55975026,0.6457888,0.7894059,0.20785794]}]}

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::GetRequest()
                   .WithCollectionName("my_collection")
                   .WithIDs({0, 1, 2})
                   .AddOutputField("vector")
                   .AddOutputField("color");

milvus::GetResponse response;
status = client->Get(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Utilizar a consulta

Consulta básica

Quando precisar de encontrar entidades através de condições de filtragem personalizadas, utilize o método «Query ». Os exemplos de código seguintes partem do princípio de que existem três campos denominados « id », « vector » e « color » e devolvem o número especificado de entidades que contêm um valor « color » que comece por « red ».

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

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

import io.milvus.v2.service.vector.request.QueryReq
import io.milvus.v2.service.vector.request.QueryResp

QueryReq queryReq = QueryReq.builder()
        .collectionName("my_collection")
        .filter("color like \"red%\"")
        .outputFields(Arrays.asList("vector", "color"))
        .limit(3)
        .build();

QueryResp queryResp = client.query(queryReq);

List<QueryResp.QueryResult> results = queryResp.getQueryResults();
for (QueryResp.QueryResult result : results) {
    System.out.println(result.getEntity());
}

// Output
// {color=red_7025, vector=[0.19886813, 0.060235605, 0.6976963, 0.26144746, 0.8387295], id=1}
// {color=red_4794, vector=[0.44523495, -0.8757027, 0.82207793, 0.4640629, 0.3033748], id=4}
// {color=red_9392, vector=[0.8371978, -0.015764369, -0.31062937, -0.56266695, -0.8984948], id=6}

resultSet, err := client.Query(ctx, milvusclient.NewQueryOption("my_collection").
    WithFilter("color like \"red%\"").
    WithOutputFields("vector", "color"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println("id: ", resultSet.GetColumn("id").FieldData().GetScalars())
fmt.Println("vector: ", resultSet.GetColumn("vector").FieldData().GetVectors())
fmt.Println("color: ", resultSet.GetColumn("color").FieldData().GetScalars())

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "http://localhost:19530";
const token = "root:Milvus";
const client = new MilvusClient({address, token});

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

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/query" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "filter": "color like \"red%\"",
    "limit": 3,
    "outputFields": ["vector", "color"]
}'
#{"code":0,"cost":0,"data":[{"color":"red_7025","id":1,"vector":[0.19886813,0.060235605,0.6976963,0.26144746,0.8387295]},{"color":"red_4794","id":4,"vector":[0.44523495,-0.8757027,0.82207793,0.4640629,0.3033748]},{"color":"red_9392","id":6,"vector":[0.8371978,-0.015764369,-0.31062937,-0.56266695,-0.8984948]}]}

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("color like \"red%\"")
                   .WithLimit(3)
                   .AddOutputField("vector")
                   .AddOutputField("color");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Ordenar os resultados da consultaCompatible with Milvus 3.0.x

Por predefinição, a função Query devolve os resultados numa ordem não especificada. Utilize o parâmetro order_by para ordenar os resultados por um ou mais campos escalares. Ao utilizar order_by, tenha em atenção que:

• order_by deve ser utilizado em conjunto com limit.

• Tipos de campo suportados: ` INT8`, ` INT16`, ` INT32`, ` INT64`, ` FLOAT`, ` DOUBLE` e ` VARCHAR`. A ordenação por campos vetoriais, ` JSON` ou ` ARRAY ` não é suportada.

• Ao ordenar por um campo que pode conter valores nulos, os valores NULL são colocados no final na ordem ascendente (NULLS LAST) e no início na ordem descendente (NULLS FIRST).

Ordenação básica

Passe uma lista de cadeias de caracteres do tipo « "field_name:direction" » para o parâmetro « order_by », em que « direction » pode ser « asc » (ascendente) ou « desc » (descendente). Note-se que « asc » e « desc » distinguem maiúsculas de minúsculas.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

# 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"],
)

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Sort results by id in ascending order
auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("color like \"red%\"")
                   .WithLimit(3)
                   .WithOrderBy("id:asc")
                   .AddOutputField("vector")
                   .AddOutputField("color");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Ordenação por vários campos

Pode ordenar por vários campos ao mesmo tempo. Os resultados são primeiro ordenados pelo primeiro campo da lista. Quando duas linhas têm o mesmo valor nesse campo, o segundo campo determina a sua ordem, e assim sucessivamente.

# 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"],
)

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Sort by rating descending, then by price ascending for ties
auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("")
                   .WithLimit(10)
                   .WithOrderBy("rating:desc")
                   .WithOrderBy("price:asc")
                   .AddOutputField("color")
                   .AddOutputField("rating")
                   .AddOutputField("price");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Paginação com ordenação

Utilize order_by em conjunto com limit e offset para paginar os resultados ordenados. Por exemplo, para apresentar uma lista de produtos ordenada por preço em várias páginas, cada página mostra o lote seguinte de itens na ordem correta de preço, sem duplicados nem lacunas.

# 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"],
)

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Page 1
auto request1 = milvus::QueryRequest()
                    .WithCollectionName("my_collection")
                    .WithFilter("color like \"red%\"")
                    .WithLimit(5)
                    .WithOffset(0)
                    .WithOrderBy("price:asc")
                    .AddOutputField("color")
                    .AddOutputField("price");

milvus::QueryResponse response1;
status = client->Query(request1, response1);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Page 2
auto request2 = milvus::QueryRequest()
                    .WithCollectionName("my_collection")
                    .WithFilter("color like \"red%\"")
                    .WithLimit(5)
                    .WithOffset(5)
                    .WithOrderBy("price:asc")
                    .AddOutputField("color")
                    .AddOutputField("price");

milvus::QueryResponse response2;
status = client->Query(request2, response2);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Agregar resultados de consultasCompatible with Milvus 3.0.x

Pode agrupar os resultados da consulta por um ou mais campos escalares e calcular agregações por grupo. Os operadores de agregação suportados são count, min, max, sum e avg.

Ao utilizar ` group_by_fields`, tenha em atenção que:

• Tipos de campo suportados para group_by_fields: INT8, INT16, INT32, INT64, VARCHAR e TIMESTAMPTZ. O agrupamento por campos FLOAT, DOUBLE, vector, JSON ou ARRAY devolve um erro.

• sum e avg são exclusivamente numéricos. Pode aplicá-los a campos numéricos, incluindo FLOAT e DOUBLE, mas a sua aplicação a um campo VARCHAR devolve um erro.

Para ativar a agregação, passe group_by_fields para query() e adicione expressões de agregação (count(*), count(<field>), min(<field>), max(<field>), sum(<field>), avg(<field>)) a output_fields.

O exemplo seguinte agrupa as entidades pelo campo « color » e devolve o número de entidades em cada grupo de cores:

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

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}]

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("")
                   .WithGroupByFields({"color"})
                   .AddOutputField("color")
                   .AddOutputField("count(*)");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

É possível solicitar várias expressões de agregação numa única chamada. O exemplo seguinte agrupa por « color » e devolve a contagem de entidades, o preço médio e a classificação máxima para cada grupo:

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}]

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("")
                   .WithGroupByFields({"color"})
                   .AddOutputField("color")
                   .AddOutputField("count(*)")
                   .AddOutputField("avg(price)")
                   .AddOutputField("max(rating)");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Passe mais do que um campo para ` group_by_fields ` para calcular grupos compostos. O exemplo seguinte agrupa por ` (color, rating) ` e calcula o intervalo de preços em cada grupo:

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},
#  ...]

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("")
                   .WithGroupByFields({"color", "rating"})
                   .AddOutputField("color")
                   .AddOutputField("rating")
                   .AddOutputField("min(price)")
                   .AddOutputField("max(price)");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Também pode combinar ` group_by_fields ` com ` limit ` para limitar o número de grupos devolvidos. Isto é útil quando um campo tem elevada cardinalidade e apenas necessita de uma amostra de grupos:

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}]

// java

// go

// nodejs

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("")
                   .WithGroupByFields({"color"})
                   .AddOutputField("color")
                   .AddOutputField("avg(price)")
                   .AddOutputField("count(*)")
                   .WithLimit(5);

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Utilizar o QueryIterator

Quando precisar de encontrar entidades através de condições de filtragem personalizadas por meio de consultas paginadas, crie um QueryIterator e utilize o seu método next() para percorrer todas as entidades e encontrar aquelas que cumprem as condições de filtragem. Os exemplos de código seguintes partem do princípio de que existem três campos denominados id, vector e color e devolvem todas as entidades que contêm um valor color que comece por red.

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

import io.milvus.orm.iterator.QueryIterator;
import io.milvus.response.QueryResultsWrapper;
import io.milvus.v2.common.ConsistencyLevel;
import io.milvus.v2.service.vector.request.QueryIteratorReq;

QueryIteratorReq req = QueryIteratorReq.builder()
        .collectionName("my_collection")
        .expr("color like \"red%\"")
        .batchSize(10L)
        .outputFields(Collections.singletonList("color"))
        .build();
QueryIterator queryIterator = client.queryIterator(req);

while (true) {
    List<QueryResultsWrapper.RowRecord> res = queryIterator.next();
    if (res.isEmpty()) {
        queryIterator.close();
        break;
    }

    for (QueryResultsWrapper.RowRecord record : res) {
        System.out.println(record);
    }
}

// Output
// [color:red_7025, id:1]
// [color:red_4794, id:4]
// [color:red_9392, id:6]

// go

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const iterator = await milvusClient.queryIterator({
  collection_name: 'my_collection',
  batchSize: 10,
  expr: 'color like "red%"',
  output_fields: ['color'],
});

const results = [];
for await (const value of iterator) {
  results.push(...value);
  page += 1;
}

# Not available

// C++ QueryIterator is not supported in the current SDK.

Consultas em partições

Também é possível efetuar consultas numa ou em várias partições, incluindo os nomes das partições no pedido Get, Query ou QueryIterator. Os exemplos de código seguintes partem do princípio de que existe uma partição denominada PartitionA na coleção.

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

GetReq getReq = GetReq.builder()
        .collectionName("my_collection")
        .partitionName("partitionA")
        .ids(Arrays.asList(10, 11, 12))
        .outputFields(Collections.singletonList("color"))
        .build();

GetResp getResp = client.get(getReq);

QueryReq queryReq = QueryReq.builder()
        .collectionName("my_collection")
        .partitionNames(Collections.singletonList("partitionA"))
        .filter("color like \"red%\"")
        .outputFields(Collections.singletonList("color"))
        .limit(3)
        .build();

QueryResp getResp = client.query(queryReq);

QueryIteratorReq req = QueryIteratorReq.builder()
        .collectionName("my_collection")
        .partitionNames(Collections.singletonList("partitionA"))
        .expr("color like \"red%\"")
        .batchSize(50L)
        .outputFields(Collections.singletonList("color"))
        .consistencyLevel(ConsistencyLevel.BOUNDED)
        .build();
QueryIterator queryIterator = client.queryIterator(req);

resultSet, err := client.Get(ctx, milvusclient.NewQueryOption("my_collection").
    WithPartitions("partitionA").
    WithIDs(column.NewColumnInt64("id", []int64{10, 11, 12})).
    WithOutputFields("vector", "color"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println("id: ", resultSet.GetColumn("id").FieldData().GetScalars())
fmt.Println("vector: ", resultSet.GetColumn("vector").FieldData().GetVectors())
fmt.Println("color: ", resultSet.GetColumn("color").FieldData().GetScalars())

resultSet, err := client.Query(ctx, milvusclient.NewQueryOption("my_collection").
    WithPartitions("partitionA").
    WithFilter("color like \"red%\"").
    WithOutputFields("vector", "color"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println("id: ", resultSet.GetColumn("id").FieldData().GetScalars())
fmt.Println("vector: ", resultSet.GetColumn("vector").FieldData().GetVectors())
fmt.Println("color: ", resultSet.GetColumn("color").FieldData().GetScalars())

// Use get
var res = client.get({
    collection_name="my_collection",
    partition_names=["partitionA"],
    ids=[10,11,12],
    output_fields=["vector", "color"]
})

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

// Use queryiterator
const iterator = await milvusClient.queryIterator({
  collection_name: 'my_collection',
  partition_names: ['partitionA'],
  batchSize: 10,
  expr: 'color like "red%"',
  output_fields: ['vector', 'color'],
});

const results = [];
for await (const value of iterator) {
  results.push(...value);
  page += 1;
}

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

# Use get
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/get" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"],
    "id": [10, 11, 12],
    "outputFields": ["vector", "color"]
}'

# Use query
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/get" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "partitionNames": ["partitionA"],
    "filter": "color like \"red%\"",
    "limit": 3,
    "outputFields": ["vector", "color"],
    "id": [0, 1, 2]
}'

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Get entities from a partition
auto getRequest = milvus::GetRequest()
                      .WithCollectionName("my_collection")
                      .WithPartitionNames({"partitionA"})
                      .WithIDs({10, 11, 12})
                      .AddOutputField("vector")
                      .AddOutputField("color");

milvus::GetResponse getResponse;
status = client->Get(getRequest, getResponse);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Query a partition
auto queryRequest = milvus::QueryRequest()
                        .WithCollectionName("my_collection")
                        .WithPartitionNames({"partitionA"})
                        .WithFilter("color like \"red%\"")
                        .WithLimit(3)
                        .AddOutputField("vector")
                        .AddOutputField("color");

milvus::QueryResponse queryResponse;
status = client->Query(queryRequest, queryResponse);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Amostragem aleatória com a função «Query»

Para extrair um subconjunto representativo de dados da sua coleção para exploração de dados ou testes de desenvolvimento, utilize a expressão « RANDOM_SAMPLE(sampling_factor) », em que « sampling_factor » é um valor flutuante entre 0 e 1 que representa a percentagem de dados a amostrar.

# 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")

import io.milvus.v2.service.vector.request.GetReq
import io.milvus.v2.service.vector.request.GetResp
import io.milvus.v2.service.vector.request.QueryReq
import io.milvus.v2.service.vector.request.QueryResp
import java.util.*;

QueryReq queryReq = QueryReq.builder()
        .collectionName("my_collection")
        .filter("RANDOM_SAMPLE(0.01)")
        .outputFields(Arrays.asList("vector", "color"))
        .build();

QueryResp getResp = client.query(queryReq);
for (QueryResp.QueryResult result : getResp.getQueryResults()) {
    System.out.println(result.getEntity());
}

queryReq = QueryReq.builder()
        .collectionName("my_collection")
        .filter("color like \"red%\" AND RANDOM_SAMPLE(0.005)")
        .outputFields(Arrays.asList("vector", "color"))
        .limit(10)
        .build();

getResp = client.query(queryReq);
for (QueryResp.QueryResult result : getResp.getQueryResults()) {
    System.out.println(result.getEntity());
}

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/column"
    "github.com/milvus-io/milvus/client/v2/entity"
    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

resultSet, err := client.Query(ctx, milvusclient.NewQueryOption("my_collection").
    WithFilter("RANDOM_SAMPLE(0.01)").
    WithOutputFields("vector", "color"))
if err != nil {
    return err
}

resultSet, err = client.Query(ctx, milvusclient.NewQueryOption("my_collection").
    WithFilter("color like \"red%\" AND RANDOM_SAMPLE(0.005)").
    WithLimit(10).
    WithOutputFields("vector", "color"))
if err != nil {
    return err
}

// node

# restful

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Sample 1% of the entire collection
auto request1 = milvus::QueryRequest()
                    .WithCollectionName("my_collection")
                    .WithFilter("RANDOM_SAMPLE(0.01)")
                    .AddOutputField("vector")
                    .AddOutputField("color");

milvus::QueryResponse response1;
status = client->Query(request1, response1);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Combine with other filters - first filter, then sample
auto request2 = milvus::QueryRequest()
                    .WithCollectionName("my_collection")
                    .WithFilter("color like \"red%\" AND RANDOM_SAMPLE(0.005)")
                    .WithLimit(10)
                    .AddOutputField("vector")
                    .AddOutputField("color");

milvus::QueryResponse response2;
status = client->Query(request2, response2);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

Definir temporariamente um fuso horário para uma consulta

Se a sua coleção tiver um campo « TIMESTAMPTZ », pode substituir temporariamente o fuso horário predefinido da base de dados ou da coleção para uma única operação, definindo o parâmetro « timezone » na chamada da consulta. Isto controla a forma como os valores « TIMESTAMPTZ » são apresentados e comparados durante a operação.

O valor de timezone deve ser um identificador de fuso horário IANA válido (por exemplo, Asia/Shanghai, America/Chicago ou UTC). Para obter detalhes sobre como utilizar o campo TIMESTAMPTZ, consulte o campo TIMESTAMPTZ.

O exemplo abaixo mostra como definir temporariamente um fuso horário para uma operação de consulta:

# 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",
)

import io.milvus.v2.service.vector.request.QueryReq
import io.milvus.v2.service.vector.request.QueryResp
import java.util.*;

// Query data and display the tsz field converted to "America/Havana"
QueryReq queryReq = QueryReq.builder()
        .collectionName("my_collection")
        .filter("id <= 10")
        .outputFields(Arrays.asList("id", "tsz", "vec"))
        .limit(2)
        .timeZone("America/Havana")
        .build();

QueryResp queryResp = client.query(queryReq);

List<QueryResp.QueryResult> results = queryResp.getQueryResults();
for (QueryResp.QueryResult result : results) {
    System.out.println(result.getEntity());
}

import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";

const address = "http://localhost:19530";
const token = "root:Milvus";
const client = new MilvusClient({address, token});

// Query data and display the tsz field converted to "America/Havana"
const res = await client.query({
    collection_name: "my_collection",
    filter: 'id <= 10',
    output_fields: ["id", "tsz", "vec"],
    limit: 2,
    timezone: "America/Havana"
});

import (
    "context"
    "fmt"

    "github.com/milvus-io/milvus/client/v2/milvusclient"
)

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

milvusAddr := "localhost:19530"
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
    Address: milvusAddr,
})
if err != nil {
    fmt.Println(err.Error())
    // handle error
}
defer client.Close(ctx)

// Query data and display the tsz field converted to "America/Havana"
resultSet, err := client.Query(ctx, milvusclient.NewQueryOption("my_collection").
    WithFilter("id <= 10").
    WithLimit(2).
    WithTimeZone("America/Havana").
    WithOutputFields("id", "tsz", "vec"))
if err != nil {
    fmt.Println(err.Error())
    // handle error
}

fmt.Println("id: ", resultSet.GetColumn("id").FieldData().GetScalars())
fmt.Println("tsz: ", resultSet.GetColumn("tsz").FieldData().GetScalars())
fmt.Println("vec: ", resultSet.GetColumn("vec").FieldData().GetVectors())

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

# Query data and display the tsz field converted to "America/Havana"
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/query" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "my_collection",
    "filter": "id <= 10",
    "limit": 2,
    "outputFields": ["id", "tsz", "vec"],
    "timezone": "America/Havana"
}'

#include "milvus/MilvusClientV2.h"
#include <iostream>

auto client = milvus::MilvusClientV2::Create();

milvus::ConnectParam connect_param{"http://localhost:19530", "root:Milvus"};
auto status = client->Connect(connect_param);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}

// Query data and display the tsz field converted to "America/Havana"
auto request = milvus::QueryRequest()
                   .WithCollectionName("my_collection")
                   .WithFilter("id <= 10")
                   .WithLimit(2)
                   .WithTimeZone("America/Havana")
                   .AddOutputField("id")
                   .AddOutputField("tsz")
                   .AddOutputField("vec");

milvus::QueryResponse response;
status = client->Query(request, response);
if (!status.IsOk()) {
    std::cout << status.Message() << std::endl;
}