O objetivo da API Search é encontrar objetos de dados semelhantes a uma determinada consulta e retornar uma lista de resultados classificados (por semelhança). A API Search também oferece suporte à filtragem.
A API Search oferece várias maneiras de pesquisar objetos de dados: pesquisa vetorial, pesquisa de texto completo e pesquisa semântica. Além disso, várias pesquisas de qualquer tipo podem ser combinadas para realizar uma pesquisa híbrida.
Pesquisa vetorial
A pesquisa vetorial permite que você forneça seu próprio vetor de consulta. Esse é o método necessário para pesquisar campos de embedding que não têm uma embedding-config.
Se vários campos vector_search forem fornecidos, os resultados serão combinados usando pesos iguais.
O exemplo a seguir demonstra como realizar uma pesquisa vetorial 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 Agent Platform.
- PROJECT_ID: o Google Cloud ID do projeto.
Método HTTP e URL:
POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Corpo JSON da solicitação:
{
"vector_search": {
"search_field": "plot_embedding",
"vector": {
"values": [
0.42426406871192845,
0.565685424949238,
0.7071067811865475
]
},
"filter": {
"genre": {
"$eq": "Thriller"
}
},
"top_k": 5,
"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:
{
"results": [
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
"createTime": "2026-01-31T20:05:06Z",
"updateTime": "2026-02-02T13:59:24Z",
"data": {
"year": 1991,
"title": "The Silence of the Lambs",
"director": "Jonathan Demme",
"genre": "Thriller"
},
"vectors": {
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.697
},
{
"dataObject": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
"createTime": "2026-02-04T14:35:29Z",
"updateTime": "2026-02-04T14:37:29Z",
"data": {
"year": 1995,
"title": "Se7en",
"director": "David Fincher",
"genre": "Thriller"
},
"vectors": {
"genre_embedding": {
"dense": {
"values": [
0.3863801,
0.73934346,
0.16189057,
0.5271367
]
}
},
"plot_embedding": {
"dense": {
"values": [
1,
1,
1
]
}
},
"sparse_embedding": {
"sparse": {
"values": [
1,
6,
3,
2,
8,
5,
2
],
"indices": [
4065,
13326,
17377,
25918,
28105,
32683,
42998
]
}
},
"soundtrack_embedding": {
"dense": {
"values": [
0.5920452,
0.08301644,
0.12647335,
0.619643,
0.49258286
]
}
}
}
},
"distance": 1.75
}
]
}
gcloud
Antes de usar os dados do comando abaixo, faça estas substituições:
-
SEARCH_VECTOR_FILE: o caminho local para um arquivo JSON que contém o vetor denso ou esparso para pesquisar.
Exemplo de conteúdo do arquivo para um vetor denso:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Exemplo de conteúdo do arquivo para um vetor esparso:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: o ID da coleção.
- LOCATION: A região em que você está usando a Agent Platform.
- PROJECT_ID: o Google Cloud ID do projeto.
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud beta vector-search collections data-objects search \ --vector-search-field="plot_embedding" \ --vector-from-file=SEARCH_VECTOR_FILE \ --json-filter='{"genre": {"$eq": "Thriller"}}' \ --top-k=5 \ --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 search ` --vector-search-field="plot_embedding" ` --vector-from-file=SEARCH_VECTOR_FILE ` --json-filter='{"genre": {"$eq": "Thriller"}}' ` --top-k=5 ` --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 search ^ --vector-search-field="plot_embedding" ^ --vector-from-file=SEARCH_VECTOR_FILE ^ --json-filter='{"genre": {"$eq": "Thriller"}}' ^ --top-k=5 ^ --output-data-fields='*' ^ --output-vector-fields='*' ^ --output-metadata-fields='*' ^ --collection=COLLECTION_ID ^ --location=LOCATION ^ --project=PROJECT_ID
Você receberá uma resposta semelhante a esta:
---
dataObject:
createTime: '2026-01-31T20:05:06Z'
data:
director: Jonathan Demme
genre: Thriller
title: The Silence of the Lambs
year: 1991
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-02T13:59:24Z'
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
distance: 1.697
---
dataObject:
createTime: '2026-02-04T14:35:29Z'
data:
director: David Fincher
genre: Thriller
title: Se7en
year: 1995
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
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
distance: 1.75
Python
from google.cloud import vectorsearch_v1beta
# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()
# Initialize request
vector_search = vectorsearch_v1beta.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.1, 0.2, 0.3]},
filter={"genre": {"$eq": "Thriller"}},
top_k=5,
)
request = vectorsearch_v1beta.SearchDataObjectsRequest(
parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
vector_search=vector_search,
)
# Make the request
response = data_object_search_service_client.search_data_objects(request=request)
# Handle the response
print(response)
Pesquisa de texto
Isso realiza a pesquisa de texto completo sem vetores esparsos. O dialeto de consulta "palavra" padrão trata toda a entrada como termos de pesquisa individuais com um operador AND implícito. Você pode definir enhanced_query como true para expandir os termos de pesquisa, processar a derivação, remover palavras irrelevantes e permitir outros operadores de pesquisa:
OR: um operador de disjunção que diferencia maiúsculas de minúsculas e corresponde a documentos que contêm pelo menos um dos termos especificados. Ele só se aplica aos dois termos adjacentes.": (aspas duplas) para pesquisa de frases.-: o operador de negação. Ele exclui documentos que contêm qualquer termo antes dele.
Pesquisa semântica
Essa pesquisa converte sua consulta de texto em embeddings para encontrar resultados com base no significado semântico. Ela usa a embedding-config definida no esquema para gerar o embedding de consulta. Se vários campos vector_search forem fornecidos, os resultados serão combinados usando pesos iguais.
Pesquisar usando a pesquisa híbrida
Use batch_search_data_objects para executar várias pesquisas em paralelo (pesquisa vetorial, pesquisa de texto e pesquisa semântica). Os resultados podem ser combinados e classificados usando o classificador ReciprocalRankFusion , que mescla conjuntos de resultados usando o algoritmo de fusão de classificação recíproca (RFF, na sigla em inglês).