A API Query tem como objetivo recuperar objetos de dados de uma coleção usando um filtro. Isso é semelhante a consultar uma tabela de banco de dados e usar uma cláusula SQL
WHERE. Também é possível usar a agregação para receber uma contagem de objetos de dados que correspondem a um filtro.
Linguagem de expressão de filtro
Além da funcionalidade de pesquisa KNN/ANN, a Pesquisa de vetor 2.0 oferece recursos de consulta versáteis usando uma linguagem de consulta personalizada. A linguagem de consulta é explicada na tabela a seguir.
| Filtro | Descrição | Tipos compatíveis | Exemplo |
|---|---|---|---|
| $eq | Corresponde a objetos de dados com valores de campo que são iguais a um valor especificado. | Número, string, booleano | {"genre": {"$eq": "documentary"}} |
| $ne | Corresponde a objetos de dados com valores de campo que não são iguais a um valor especificado. | Número, string, booleano | {"genre": {"$ne": "drama"}} |
| $gt | Corresponde a objetos de dados com valores de campo maiores que um valor especificado. | Número | {"year": {"$gt": 2019}} |
| $gte | Faz correspondência com objetos de dados com valores de campo maiores ou iguais a um valor especificado. | Número | {"year": {"$gte": 2020}} |
| $lt | Corresponde a objetos de dados com valores de campo menores que um valor especificado. | Número | {"year": {"$lt": 2020}} |
| $lte | Faz correspondência com objetos de dados que têm valores de campo menores ou iguais a um valor especificado. | Número | {"year": {"$lte": 2020}} |
| $in | Corresponde a objetos de dados com valores de campo que estão em uma matriz especificada. | String | {"genre": {"$in": ["comedy", "documentary"]}} |
| $nin | Corresponde a objetos de dados com valores de campo que não estão em uma matriz especificada. | String | {"genre": {"$nin": ["comedy", "documentary"]}} |
| $and | Combina cláusulas de consulta com um AND lógico. | - | {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $or | Combina cláusulas de consulta com um OR lógico. | - | {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} |
| $all | Seleciona os documentos em que o valor da matriz de um campo contém todos os valores especificados. | - | {"colors": {"$all": ["red", "blue"]}} |
Consultar coleções
O exemplo a seguir demonstra como usar um filtro para consultar objetos de dados
em uma coleção com o ID COLLECTION_ID.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- COLLECTION_ID: o ID da coleção.
- LOCATION: a região em que você está usando a plataforma de agentes.
- PROJECT_ID: o ID do projeto do Google Cloud .
Método HTTP e URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query
Corpo JSON da solicitação:
{
"page_size": 10,
"page_token": "",
"filter": {
"$or": [
{
"director": {
"$eq": "Akira Kurosawa"
}
},
{
"$and": [
{
"director": {
"$eq": "David Fincher"
}
},
{
"genre": {
"$ne": "Thriller"
}
}
]
}
]
},
"output_fields": {
"data_fields": "*",
"vector_fields": "*",
"metadata_fields": "*"
}
}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{
"dataObjects": [
{
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
"createTime": "2026-02-04T14:35:29Z",
"updateTime": "2026-02-04T14:37:29Z",
"data": {
"title": "Seven Samurai",
"director": "Akira Kurosawa",
"genre": "Action",
"year": 1954
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
{
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
"createTime": "2026-02-04T15:35:29Z",
"updateTime": "2026-02-04T15:37:29Z",
"data": {
"title": "The Social Network",
"director": "David Fincher",
"genre": "Drama",
"year": 2010
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.1,
0.2,
0.3,
0.4
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1
],
"indices": [
1000
]
}
},
"plot_embedding": {
"dense": {
"values": [
0.1,
0.1,
0.1
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.1,
0.2,
0.3,
0.4,
0.5
]
}
}
}
}
]
}
gcloud
Antes de usar os dados do comando abaixo, faça estas substituições:
- COLLECTION_ID: o ID da coleção.
- LOCATION: a região em que você está usando a plataforma de agentes.
- PROJECT_ID: o ID do projeto do Google Cloud .
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud beta vector-search collections data-objects query \ --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' \ --output-data-fields='*' \ --output-vector-fields='*' \ --output-metadata-fields='*' \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud beta vector-search collections data-objects query ` --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ` --output-data-fields='*' ` --output-vector-fields='*' ` --output-metadata-fields='*' ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud beta vector-search collections data-objects query ^ --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ^ --output-data-fields='*' ^ --output-vector-fields='*' ^ --output-metadata-fields='*' ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
Você receberá uma resposta semelhante a esta:
---
createTime: '2026-02-04T14:35:29Z'
data:
director: Akira Kurosawa
genre: Action
title: Seven Samurai
year: 1954
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-04T14:37:29Z'
vectors:
genre_embedding:
dense:
values:
- 0.38638
- 0.739343
- 0.161891
- 0.527137
plot_embedding:
dense:
values:
- 1.0
- 1.0
- 1.0
soundtrack_embedding:
dense:
values:
- 0.592045
- 0.0830164
- 0.126473
- 0.619643
- 0.492583
sparse_embedding:
sparse:
indices:
- 4065
- 13326
- 17377
- 25918
- 28105
- 32683
- 42998
values:
- 1.0
- 6.0
- 3.0
- 2.0
- 8.0
- 5.0
- 2.0
---
createTime: '2026-02-04T15:35:29Z'
data:
director: David Fincher
genre: Drama
title: The Social Network
year: 2010
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
updateTime: '2026-02-04T15:37:29Z'
vectors:
genre_embedding:
dense:
values:
- 0.1
- 0.2
- 0.3
- 0.4
plot_embedding:
dense:
values:
- 0.1
- 0.1
- 0.1
soundtrack_embedding:
dense:
values:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
sparse_embedding:
sparse:
indices:
- 1000
values:
- 1.0
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1beta.QueryDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
filter={
"$or": [
{"director": {"$eq": "Akira Kurosawa"}},
{
"$and": [
{"director": {"$eq": "David Fincher"}},
{"genre": {"$ne": "Thriller"}},
]
},
]
},
)
# Make the request
page_result = data_object_search_service_client.query_data_objects(request=request)
# Handle the response
for response in page_result:
print(response)
Para realizar uma agregação, use o endpoint aggregate e especifique o tipo de agregação no corpo da solicitação.
O exemplo a seguir demonstra como contar todos os objetos de dados em uma
coleção com o ID COLLECTION_ID.
REST
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- COLLECTION_ID: o ID da coleção.
- LOCATION: a região em que você está usando a plataforma de agentes.
- PROJECT_ID: o ID do projeto do Google Cloud .
Método HTTP e URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate
Corpo JSON da solicitação:
{
"aggregate": "count"
}
Para enviar a solicitação, expanda uma destas opções:
Você receberá uma resposta JSON semelhante a esta:
{
"aggregateResults": [
{
"count": 1000
}
]
}
gcloud
Antes de usar os dados do comando abaixo, faça estas substituições:
- COLLECTION_ID: o ID da coleção.
- LOCATION: a região em que você está usando a plataforma de agentes.
- PROJECT_ID: o ID do projeto do Google Cloud .
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud beta vector-search collections data-objects aggregate \ --aggregation-method=count \ --collection=COLLECTION_ID \ --location=LOCATION \ --project=PROJECT_ID
Windows (PowerShell)
gcloud beta vector-search collections data-objects aggregate ` --aggregation-method=count ` --collection=COLLECTION_ID ` --location=LOCATION ` --project=PROJECT_ID
Windows (cmd.exe)
gcloud beta vector-search collections data-objects aggregate ^ --aggregation-method=count ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
Você receberá uma resposta semelhante a esta:
aggregateResults: - count: 1000
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
request = vectorsearch_v1beta.AggregateDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
aggregate="COUNT",
)
# Make the request
response = data_object_search_service_client.aggregate_data_objects(request=request)
# Handle the response
print(response)
A seguir
- Saiba como pesquisar objetos de dados.