El propósito de la API de Search es encontrar objetos de datos que sean similares a una consulta determinada y devolver una lista de resultados clasificados (por similitud). La API de Search también admite el filtrado.
La API de Search ofrece una variedad de formas de buscar objetos de datos: búsqueda de vectores, búsqueda en el texto completo y búsqueda semántica. Además, se pueden combinar varias búsquedas de cualquier tipo para lograr una búsqueda híbrida.
Búsqueda de vectores
Vector Search te permite proporcionar tu propio vector de consulta. Este es el método obligatorio
para buscar campos de embeddings que no tienen un embedding-config.
Si se proporcionan varios campos vector_search, los resultados se combinan con
ponderaciones iguales.
En el siguiente ejemplo, se muestra cómo realizar una búsqueda de vectores en una
colección con el ID COLLECTION_ID.
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- COLLECTION_ID: Es el ID de la colección.
- LOCATION: Es la región en la que usas Agent Platform.
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
Método HTTP y URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Cuerpo JSON de la solicitud:
{
"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 tu solicitud, expande una de estas opciones:
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{
"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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:
-
SEARCH_VECTOR_FILE: Es la ruta de acceso local a un archivo JSON que contiene el vector denso o disperso con el que se realizará la búsqueda.
Ejemplo de contenido de archivo para un vector denso:
{ "dense": { "values": [ 0.42426406871192845, 0.565685424949238, 0.7071067811865475 ] } }
Ejemplo de contenido de archivo para un vector disperso:
{ "sparse": { "indices": [1, 5, 10], "values": [0.1, 0.5, 0.21] } }
- COLLECTION_ID: Es el ID de la colección.
- LOCATION: Es la región en la que usas Agent Platform.
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
Ejecuta el siguiente comando:
Linux, macOS o Cloud Shell
gcloud 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 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 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
Deberías recibir una respuesta similar a la que figura a continuación:
---
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_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.1, 0.2, 0.3]},
filter={"genre": {"$eq": "Thriller"}},
top_k=5,
)
request = vectorsearch_v1.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)
Ajusta la exactitud y el rendimiento de la búsqueda
En el caso de las búsquedas de vectores en índices de ANN densos con más de 100,000 embeddings, Agent Retrieval, de forma predeterminada, intenta proporcionar un equilibrio óptimo entre la recuperación y la latencia. Puedes ajustar este equilibrio para tu caso de uso especificando una tasa de recuperación objetivo.
Los valores deben ser mayores o iguales que 0.00, y menores o iguales que 1.00.
Para obtener información sobre cómo crear un índice de ANN, consulta Crea un índice de ANN.
En el siguiente ejemplo, se muestra cómo realizar una Vector Search en un índice de ANN denso con una tasa de recuperación objetivo de 0.95.
REST
Método HTTP y URL:
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search
Cuerpo JSON de la solicitud:
{
"vectorSearch": {
"searchField": "plot_embedding",
"vector": {
"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
},
"topK": 10,
"searchHint": {
"indexHint": {
"name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/indexes/INDEX_ID",
"denseScannParams": {
"targetRecall": 0.95
}
}
},
"outputFields": {
"dataFields": "*",
"vectorFields": "*",
"metadataFields": "*"
}
}
}
gcloud
Guarda el vector de consulta en un archivo JSON, por ejemplo, vector.json:
{
"dense": {
"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]
}
}
Luego, ejecuta el siguiente comando gcloud vector-search collections data-objects search:
gcloud vector-search collections data-objects search \
--project=PROJECT_ID \
--location=LOCATION \
--collection=COLLECTION_ID \
--vector-search-field=plot_embedding \
--vector-from-file=vector.json \
--use-index=INDEX_ID \
--dense-scann-target-recall=0.95 \
--top-k=10
Python
from google.cloud import vectorsearch_v1
# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()
collection = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"
# Set the target recall rate on the index hint
search_hint = vectorsearch_v1.SearchHint(
index_hint=vectorsearch_v1.SearchHint.IndexHint(
name=f"{collection}/indexes/INDEX_ID",
dense_scann_params=vectorsearch_v1.SearchHint.IndexHint.DenseScannParams(
target_recall=0.95,
),
),
)
# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
search_field="plot_embedding",
vector={"values": [0.42426406871192845, 0.565685424949238, 0.7071067811865475]},
top_k=10,
search_hint=search_hint,
output_fields=vectorsearch_v1.OutputFields(
data_fields=["*"],
vector_fields=["*"],
metadata_fields=["*"],
),
)
request = vectorsearch_v1.SearchDataObjectsRequest(
parent=collection,
vector_search=vector_search,
)
# Make the request
response = data_object_search_service_client.search_data_objects(request=request)
# Handle the response
print(response)
Búsqueda de texto
Esto realiza una búsqueda en el texto completo sin vectores dispersos. El dialecto de consulta predeterminado "word"
trata toda la entrada como términos de búsqueda individuales con un operador
AND implícito. Puedes establecer enhanced_query en true para expandir los términos de búsqueda,
controlar la lematización, quitar palabras irrelevantes y permitir operadores de búsqueda adicionales:
OR: Es un operador de disyunción que distingue mayúsculas de minúsculas y que coincide con los documentos que contienen al menos uno de los términos especificados. Solo se aplica a los dos términos adyacentes."(comillas dobles) para la búsqueda de frases-: Es el operador de negación. Excluye los documentos que contienen los términos que se colocan antes.
Búsqueda de texto avanzada
La API de búsqueda de texto de Agent Retrieval te permite expresar búsquedas de texto a través de consultas estructuradas que contienen una o más subconsultas, lo que te permite hacer lo siguiente:
Busca coincidencias con campos específicos de objetos de datos.
Especifica el tipo de coincidencia que se realizará:
Por término, no distingue mayúsculas de minúsculas
Coincidencia exacta, distingue mayúsculas de minúsculas
Incluye mejoras por idioma para que coincidan con las raíces de los términos, los sinónimos, los errores ortográficos y las palabras irrelevantes (como "un", "una" y "el").
Usa los operadores booleanos
AND,ORyNOTpara combinar subconsultas.Controla el orden de evaluación agrupando las subconsultas.
Aumenta las contribuciones de puntuación para influir en las clasificaciones.
Existen tres tipos de subconsultas:
Texto: Proporciona el texto de búsqueda y uno o más campos con los que se debe comparar.
Combinada: Aplica el operador
ANDoORpara combinar subconsultas y se puede usar para agrupar otras subconsultas combinadas para controlar el orden de evaluación.
En los ejemplos de esta página, se usa la colección
que se muestra en la siguiente tabla. Contiene seis objetos de datos y define
los siguientes campos en su esquema de datos:
las cadenas ID, Title, Description y el array de cadenas Keywords.
| ID | Título | Descripción | Palabras clave |
|---|---|---|---|
| 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 2 | Días de perros perezosos | El perro marrón duerme. | doméstico, mascota, casa, canino, tranquilo, perezoso, obediente |
| 3 | Zorro vs. perro | El ágil zorro supera al perro. | salvaje, doméstico, conflicto, caniformia, mamíferos, interacción |
| 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
| 5 | Una historia astuta | El perro salta alto. | astucia, saltos |
| 6 | Mis días de verano perezosos | Una historia corta sobre relajarse durante las vacaciones de verano. | verano, relajarse, vacaciones, sol |
Subconsultas de texto
Las consultas de texto coinciden con uno o más campos de un objeto de datos. Todas las consultas estructuradas deben contener al menos una consulta de texto.
En el siguiente ejemplo, se define una consulta de texto básica:
"text_search": {
"structured_query": {
"text": {
"text": "fox vs dog"
}
}
}
De forma predeterminada, el texto se divide en términos individuales y cada término se busca
en los campos especificados. En el ejemplo anterior, se buscan los términos "fox", "vs"
y "dog" en el campo Title.
Las consultas de texto tienen los siguientes parámetros opcionales:
fields: Es un array de campos con los que se debe establecer una coincidencia. Si no se especifica, el valor predeterminado es que coincida con todos los campos. Los campos se hacen coincidir con un operadorORimplícito.match_type: Es el tipo de coincidencia que se realizará. El tipo de coincidencia puede serEXACT, que especifica que el campo debe coincidir exactamente con el texto de búsqueda. Si el campo es un array de cadenas, se realiza una coincidencia con cualquier elemento del array.enhancement: Especificaenabledy unlanguageCode, lo que permite que las coincidencias se realicen con sinónimos, raíces, errores ortográficos y palabras irrelevantes en el idioma especificado paralanguageCode(por ejemplo,en-US). La opción predeterminada es sin mejora.boost: Opcional Es un multiplicador que se aplica a la puntuación de la consulta. El valor predeterminado es1.0.
Tipo de coincidencia
El parámetro match_type especifica cómo el texto de búsqueda coincide con el valor de un campo.
El valor del parámetro puede ser el siguiente:
EXACT: El campo debe coincidir exactamente con el término de la consulta. Si el campo es un array de cadenas, se realiza una coincidencia con cualquier elemento del array.
En el siguiente ejemplo, se especifica el tipo de coincidencia EXACT:
"text_search": {
"structured_query": {
"text": {
"text": "Fox vs Dog",
"fields": [ "Title" ],
"match_type": "EXACT"
}
}
}
Tipo de coincidencia para arrays de cadenas
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 1.0000 | 3 | Zorro vs. perro | El ágil zorro supera al perro. | salvaje, doméstico, conflicto, caniformia, mamíferos, interacción |
Cuando el campo es un array de cadenas, el texto de búsqueda se compara con cualquier elemento del array.
En el siguiente ejemplo, se muestra cómo buscar el texto exacto wild en
el array de cadenas Keywords:
"text_search": {
"structured_query": {
"text": {
"text": "wild",
"fields": [ "Keywords" ],
"match_type": "EXACT"
}
}
}
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 1.0000 | 3 | Zorro vs. perro | El ágil zorro supera al perro. | salvaje, doméstico, conflicto, caniformia, mamíferos, interacción |
| 1.0000 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
| 1.0000 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
Mejoras en las búsquedas
Las consultas de búsqueda pueden incluir un parámetro queryEnhancement opcional para especificar
mejoras específicas del idioma. Esto incluye la coincidencia con sinónimos,
raíces (por ejemplo, la raíz "salt" de "saltar"), ortografía incorrecta
y palabras irrelevantes (como "un", "una" y "el").
El parámetro es un objeto con las siguientes propiedades:
enabled: Es un valor booleano que especifica si se deben habilitar las mejoras.languageCode: Es una cadena que especifica el idioma de las mejoras (por ejemplo,en-US).
En el siguiente ejemplo, se habilitan las mejoras para el idioma en-US:
"text_search": {
"structured_query": {
"text": {
"text": {
"text": "jump",
"fields": [ "Description" ],
"queryEnhancement": {
"enabled": true,
"languageCode": "en-US"
}
}
}
}
}
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 0.3419 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 0.3419 | 5 | Una historia astuta | El perro salta alto. | astucia, saltos |
Si no se especificó queryEnhancement o enabled era false,
no se realizaría ninguna coincidencia.
Subconsultas combinadas
Las consultas combinadas aplican una operación booleana a dos o más subconsultas. Las
operaciones admitidas son AND y OR.
Las consultas combinadas tienen las siguientes propiedades:
op: Es el operador booleano que se aplicará a las subconsultas. El valor puede serANDoOR.subQueries: Es un array de subconsultas que se combinarán. Pueden ser cualquiera de los tipos de subconsultas admitidos, incluidas otras consultas combinadas. La profundidad máxima de anidación es de 2.boost: Opcional Es un multiplicador que se aplica a la puntuación de la consulta. El valor predeterminado es1.0.
Conjunción (AND)
El operador AND coincide con los objetos de datos que contienen los términos de todas las subconsultas.
En el siguiente ejemplo, se muestra cómo combinar tres consultas de texto con el
operador AND:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
En el ejemplo, las coincidencias solo se realizan si coinciden las tres subconsultas.
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 5.0587 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
| 5.0587 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
Cuando una subconsulta de texto tiene varios campos para coincidir, se aplica un OR implícito, como se muestra en el siguiente ejemplo:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title", "Description" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
En el ejemplo anterior:
La primera subconsulta coincide con el término
Brown, que no distingue mayúsculas de minúsculas, en el campoTitleoDescription.La segunda subconsulta coincide con el término
quickque no distingue mayúsculas de minúsculas en el campoDescription.La tercera subconsulta coincide con los términos que no distinguen mayúsculas de minúsculas
forestypredatoren cualquiera de los valores del campo de array de cadenasKeywords.Si las tres subconsultas coinciden, se realiza una coincidencia en la consulta combinada.
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 6.3176 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 5.0587 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
Disyunción (OR)
El operador OR hace coincidir los objetos de datos que contienen los términos de, al menos, una de
las subconsultas.
En el siguiente ejemplo, se muestra cómo combinar tres consultas de texto con el
operador OR:
"text_search": {
"structured_query": {
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title", "Description" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
}
]
}
}
}
En el ejemplo, se produce una coincidencia si alguna de las tres subconsultas coincide.
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 6.3176 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 5.0587 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
Agrupación
Las subconsultas combinadas se pueden anidar dentro de otras subconsultas combinadas para controlar el orden de evaluación.
En el siguiente ejemplo, se muestra cómo agrupar subconsultas:
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "Fox",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "jumps",
"fields": [ "Description" ]
}
}
]
}
},
{
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "domestic",
"fields": [ "Keywords" ]
}
}
}
}
]
}
}
}
El ejemplo anterior equivale a lo siguiente:
(Fox que no distingue mayúsculas de minúsculas en Title O jumps que no distingue mayúsculas de minúsculas
en Description) Y NO domestic que no distingue mayúsculas de minúsculas en ninguno de los
elementos Keywords.
En la siguiente tabla, se muestran los resultados de la consulta:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 3.5178 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 2.2589 | 5 | Una historia astuta | El perro salta alto. | astucia, saltos |
Subconsultas unarias
Las subconsultas unarias aplican una operación booleana a una sola subconsulta en una consulta
estructurada. El operador NOT es la única operación unaria admitida.
Las consultas unarias tienen las siguientes propiedades:
op: Es el operador booleano que se aplicará a la subconsulta. El valor puede serNOT.subQuery: Es la subconsulta a la que se aplicará la operación unaria.boost: Opcional Es un multiplicador que se aplica a la puntuación de la consulta. El valor predeterminado es1.0.
Negación (NOT)
El operador NOT coincide con los objetos de datos que no contienen los términos de la
subconsulta.
En el siguiente ejemplo, se muestra cómo usar el operador NOT:
"text_search": {
"structured_query": {
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "dog",
"fields": [ "Description" ]
}
}
}
}
}
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 1.000 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
| 1.000 | 6 | Mis días de verano perezosos | Una historia corta sobre relajarse durante las vacaciones de verano. | verano, relajarse, vacaciones, sol |
Cuando se aplica a un array de cadenas, el operador NOT coincide con un objeto de datos si el
término no está incluido en ninguno de los elementos del array.
En el ejemplo, se realiza una coincidencia si el término orange que no distingue mayúsculas de minúsculas no está
contenido en ningún elemento del array de cadenas Keywords.
"text_search": {
"structured_query": {
"combine": {
"op": "AND",
"subQueries": [
{
"text": {
"text": "Brown",
"fields": [ "Title" ]
}
},
{
"text": {
"text": "quick",
"fields": [ "Description" ]
}
},
{
"text": {
"text": "forest predator",
"fields": [ "Keywords" ]
}
},
{
"unary": {
"op": "NOT",
"subQuery": {
"text": {
"text": "orange",
"fields": [ "Keywords" ]
}
}
}
}
]
}
}
}
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 6.0587 | 4 | Osos pardos | Movimientos rápidos en el bosque. | salvaje, bosque, úrsido, superdepredador, hibernación, gigante |
Boost
Cualquier subconsulta puede tener un parámetro boost para aplicar un multiplicador a la puntuación
de la subconsulta. De forma predeterminada, todas las subconsultas tienen un boost de 1.0.
En el siguiente ejemplo, se muestra cómo aumentar una subconsulta:
"text_search": {
"structured_query": {
"combine": {
"op": "OR",
"subQueries": [
{
"text": {
"text": "fox",
"fields": [ "Title" ]
},
"boost": 1.0
},
{
"text": {
"text": "jumps",
"fields": [ "Description" ]
},
"boost": 1.0
},
{
"text": {
"text": "interaction",
"fields": [ "Keywords" ]
},
"boost": 5.0
}
]
}
}
}
Los resultados de la consulta se muestran en la siguiente tabla:
| Puntuación | ID | Título | Descripción | Palabras clave |
|---|---|---|---|---|
| 7.5534 | 3 | Zorro vs. perro | El ágil zorro supera al perro. | salvaje, doméstico, conflicto, caniformia, mamíferos, interacción |
| 2.5178 | 1 | The Quick Brown Fox | Un zorro pardo rápido salta fácilmente sobre el perro perezoso. | salvaje, bosque, mamífero, naranja, agilidad, depredador |
| 1.2589 | 5 | Una historia astuta | El perro salta alto. | astucia, saltos |
Búsqueda semántica
Esta búsqueda convierte tu consulta de texto en embeddings para encontrar resultados basados en
el significado semántico. Usa el embedding-config definido en tu esquema para
generar la incorporación de consultas. Si se proporcionan varios campos vector_search,
los resultados se combinan con pesos iguales.
Cómo buscar con la búsqueda híbrida
Usa batch_search_data_objects para ejecutar varias búsquedas en paralelo
(búsqueda de vectores, búsqueda de texto y búsqueda semántica). De manera opcional, los resultados se pueden
combinar y clasificar con el clasificador ReciprocalRankFusion,
que combina conjuntos de resultados con el algoritmo de fusión por clasificación recíproca (RRF).
Cómo ordenar los resultados combinados
Usa combine.sorts para reordenar los resultados combinados de una
solicitud de batch_search_data_objects por campos del esquema de datos de tu colección,
por ejemplo, precio ascendente, año descendente o una marca de estado.
combine.sorts está disponible en el método batchSearch de la versión v1beta.
La ordenación se aplica a los resultados combinados después de la RRF y, si se configura,
VertexRanker, y antes del truncamiento de combine.top_k.
Solo se ordenan los candidatos que recuperan las búsquedas, no todos los objetos de datos de la colección. Por ejemplo, puedes solicitar los tres artículos más recientes
entre las coincidencias semánticas principales, con empates en el tiempo de publicación desglosados por
recuento de vistas, en una sola solicitud.
En el ejemplo de esta sección, se usan los siguientes objetos de datos. La hora de publicación se almacena como una cadena ISO 8601 y como un número de tiempo Unix. Ambos formatos se ordenan cronológicamente.
| ID | título | published_at | published_unix | vistas |
|---|---|---|---|---|
| a1 | La Fed mantiene las tasas estables | 2026-09-29T14:00:00Z | 1790690400 | 5200 |
| a2 | Los mercados se recuperan gracias a las ganancias | 2026-09-29T14:00:00Z | 1790690400 | 8100 |
| a3 | Bajan los precios del petróleo | 2026-09-28T09:30:00Z | 1790587800 | 12000 |
| a4 | Repunte de las acciones tecnológicas | 2026-09-30T08:15:00Z | 1790756100 | 3000 |
| a5 | Aumento de los rendimientos de los bonos | 2026-09-27T16:45:00Z | 1790527500 | 9000 |
En el siguiente ejemplo, se muestra el cuerpo de una solicitud al método dataObjects:batchSearch de la versión v1beta
que devuelve los tres artículos más recientes,
con empates resueltos por el recuento de vistas más alto:
{
"searches": [
{
"vector_search": {
"search_field": "embedding",
"vector": { "values": [0.7, 0.3, 0.1] },
"top_k": 5,
"output_fields": { "data_fields": ["title", "published_at", "views"] }
}
}
],
"combine": {
"ranker": { "rrf": { "weights": [1.0] } },
"top_k": 3,
"sorts": [
{ "field": "published_at", "direction": "DESC" },
{ "field": "views", "direction": "DESC" }
]
}
}
Los resultados de la solicitud se muestran en la siguiente tabla. Ordenar por
published_unix en lugar de published_at devuelve el mismo orden.
| ID | título | published_at | vistas |
|---|---|---|---|
| a4 | Repunte de las acciones tecnológicas | 2026-09-30T08:15:00Z | 3000 |
| a2 | Los mercados se recuperan gracias a las ganancias | 2026-09-29T14:00:00Z | 8100 |
| a1 | La Fed mantiene las tasas estables | 2026-09-29T14:00:00Z | 5200 |
Los objetos de datos a2 y a1 tienen el mismo valor de published_at, por lo que views decide su orden. El objeto de datos a3 tiene la mayor cantidad de vistas, pero es más antiguo, por lo que
combine.top_k lo excluye.
Incluye campos de ordenamiento en output_fields para obtener una latencia más baja
Para ordenar los resultados combinados, el servicio necesita el valor de cada campo de ordenamiento
para cada objeto de datos candidato. Lee estos valores de los datos que devuelve cada búsqueda, que se controla con el output_fields de esa búsqueda. Si a algún
candidato le falta algún campo de orden, el servicio recupera los campos faltantes del
almacenamiento en una búsqueda adicional antes de ordenar.
El servicio omite la búsqueda solo cuando cada búsqueda devuelve cada campo de orden. Esto incluye las búsquedas cuyos resultados no conserva el reclasificador, ya que la ordenación se ejecuta en los candidatos de todas las búsquedas. Si una búsqueda en la solicitud omite un campo de orden, la solicitud realiza la búsqueda.
Por ejemplo, la siguiente solicitud ordena por published_at y views. La Vector Search devuelve ambos campos, pero la Text Search solo devuelve title, por lo que el servicio realiza la búsqueda adicional:
{
"searches": [
{
"vector_search": {
"search_field": "embedding",
"vector": { "values": [0.7, 0.3, 0.1] },
"top_k": 5,
"output_fields": { "data_fields": ["title", "published_at", "views"] }
}
},
{
"text_search": {
"search_text": "rates",
"data_field_names": ["title"],
"top_k": 5,
"output_fields": { "data_fields": ["title"] }
}
}
],
"combine": {
"ranker": { "rrf": { "weights": [1.0, 1.0] } },
"top_k": 3,
"sorts": [
{ "field": "published_at", "direction": "DESC" },
{ "field": "views", "direction": "DESC" }
]
}
}
Para evitar la búsqueda, agrega published_at y views a la output_fields de la búsqueda de texto:
"output_fields": { "data_fields": ["title", "published_at", "views"] }
Solicitar todos los campos con "data_fields": ["*"] también evita la búsqueda.
Si no quieres que los campos de ordenamiento aparezcan en la respuesta, puedes excluirlos
de output_fields. La solicitud devuelve los mismos resultados en el mismo orden, solo
que más lentamente. Ordena los campos para que no se quiten de la respuesta las solicitudes de búsqueda en output_fields.
Especificación de ordenamiento
Cada entrada en combine.sorts tiene los siguientes campos:
| Campo | Obligatorio | Descripción |
|---|---|---|
field |
Sí | Es el campo de datos por el que se ordenará. Usa rutas de acceso con puntos para los campos anidados, por ejemplo, product.price. El campo debe existir en el esquema de la colección. |
direction |
Opcional | La dirección de ordenamiento: ASC o DESC. El valor predeterminado es ASC. |
Las entradas se aplican en orden. La primera entrada es la clave de ordenamiento principal, y cada
entrada posterior solo desempata los resultados de las entradas anteriores. Para que el orden
sea predecible cuando los valores suelen colisionar, agrega más entradas, por ejemplo, year
ascendente y, luego, title ascendente.
Cuando los objetos de datos son iguales en cada entrada de orden, el objeto de datos con la puntuación de clasificación más alta aparece primero. La puntuación del clasificador es la puntuación de RRF o la puntuación de VertexRanker si se configura un reclasificador. Si las puntuaciones también son iguales, los objetos de datos se ordenan por ID de objeto de datos en orden ascendente, por lo que la misma solicitud siempre devuelve resultados en el mismo orden.
Tipos de campos ordenables
Puedes ordenar por campos de los siguientes tipos de esquemas:
Número (
numberointeger): Los valores se comparan como números de punto flotante de precisión doble, por lo que los números enteros mayores que 253 podrían compararse como iguales.Booleano: En orden ascendente,
falsese ordena antes quetrue.String: Los valores se comparan en el orden de bytes UTF-8, que distingue mayúsculas de minúsculas. Por ejemplo,
"Apple"se ordena antes de"Zebra", que se ordena antes de"apple". Para ordenar sin distinguir mayúsculas de minúsculas, almacena una copia normalizada del campo, como una copia en minúsculas, y ordena según ese campo.Fechas y marcas de tiempo: No hay un tipo de fecha dedicado. Almacena estos valores como cadenas ISO 8601 UTC en un formato coherente o como números de tiempo Unix.
No puedes ordenar por campos de array ni de objeto.
Los objetos de datos que no tienen un valor para un campo de ordenamiento se colocan después de todos los objetos de datos que sí lo tienen, tanto para ASC como para DESC.
Interacción con los clasificadores
RRF: La RRF combina los resultados de las búsquedas,
combine.sortsreordena la lista combinada y, luego,combine.top_kla trunca.VertexRanker:
combine.sortsreordena el resultadotop_ndel reclasificador antes del truncamiento decombine.top_k. El orden final sigue las entradas de orden, no la puntuación del reclasificador. La respuesta incluye una advertencia en el camposearch_response_metadata.warningscon el códigoFAILED_PRECONDITIONy el mensaje"Both sort and a Vertex reranker were configured. The final order reflects the sort, not the reranker score.". La solicitud se realiza correctamente.
Si la llamada a VertexRanker falla, se aplica combine.sorts a los resultados fusionados con RRF. Para obtener más información, consulta
Manejo de fallas y advertencias.
Errores
| Código de error | Causa |
|---|---|
INVALID_ARGUMENT |
combine.sorts[i].field está vacío o el campo no está definido en el esquema de la colección. |
INVALID_ARGUMENT |
combine.sorts[i].direction no es un valor válido. |
FAILED_PRECONDITION |
combine.sorts[i].field hace referencia a un campo que no se puede ordenar, como un campo de array o de objeto. |