Cómo buscar objetos de datos

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.

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)

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.

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, OR y NOT para 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.

  • Unario: Aplica una operación NOT en una sola subconsulta.

  • Combinada: Aplica el operador AND o OR para 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 operador OR implícito.

  • match_type: Es el tipo de coincidencia que se realizará. El tipo de coincidencia puede ser EXACT, 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: Especifica enabled y un languageCode, lo que permite que las coincidencias se realicen con sinónimos, raíces, errores ortográficos y palabras irrelevantes en el idioma especificado para languageCode (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 es 1.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 ser AND o OR.

  • 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 es 1.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 campo Title o Description.

  • La segunda subconsulta coincide con el término quick que no distingue mayúsculas de minúsculas en el campo Description.

  • La tercera subconsulta coincide con los términos que no distinguen mayúsculas de minúsculas forest y predator en cualquiera de los valores del campo de array de cadenas Keywords.

  • 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 ser NOT.

  • 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 es 1.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

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.

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 (number o integer): 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, false se ordena antes que true.

  • 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.sorts reordena la lista combinada y, luego, combine.top_k la trunca.

  • VertexRanker: combine.sorts reordena el resultado top_n del reclasificador antes del truncamiento de combine.top_k. El orden final sigue las entradas de orden, no la puntuación del reclasificador. La respuesta incluye una advertencia en el campo search_response_metadata.warnings con el código FAILED_PRECONDITION y 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.