Cómo consultar colecciones para obtener objetos de datos

El propósito de la API de Query es recuperar objetos de datos de una colección con un filtro. Esto es similar a consultar una tabla de base de datos y usar una cláusula WHERE de SQL. También puedes usar la agregación para obtener un recuento de los objetos de datos que coinciden con un filtro.

Lenguaje de expresión de filtro

Además de la funcionalidad de búsqueda de KNN/ANN, la recuperación de agentes proporciona capacidades de consulta versátiles con un lenguaje de consulta personalizado. El lenguaje de consultas se explica en la siguiente tabla.

Filtro Descripción Tipos compatibles Ejemplo
$eq Coincide con los objetos de datos con valores de campo que son iguales a un valor especificado. Número, cadena, booleano {"genre": {"$eq": "documentary"}}
$ne Coincide con los objetos de datos con valores de campo que no son iguales a un valor especificado. Número, cadena, booleano {"genre": {"$ne": "drama"}}
$gt Coincide con los objetos de datos con valores de campo que son mayores que un valor especificado. Número {"year": {"$gt": 2019}}
$gte Coincide con los objetos de datos que tienen valores de campo mayores o iguales a un valor especificado. Número {"year": {"$gte": 2020}}
$lt Coincide con los objetos de datos que tienen valores de campo inferiores a un valor especificado. Número {"year": {"$lt": 2020}}
$lte Coincide con los objetos de datos que tienen valores de campo menores o iguales a un valor especificado. Número {"year": {"$lte": 2020}}
$in Coincide con los objetos de datos que tienen valores de campo en un array especificado. String {"genre": {"$in": ["comedy", "documentary"]}}
$nin Coincide con los objetos de datos con valores de campo que no están en un array especificado. String {"genre": {"$nin": ["comedy", "documentary"]}}
$and Une las cláusulas de la consulta con un AND lógico. - {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$or Une cláusulas de consulta con un OR lógico. - {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$all Selecciona los documentos en los que el valor del array de un campo contiene todos los valores especificados. - {"colors": {"$all": ["red", "blue"]}}
$search Coincide con los objetos de datos que tienen valores de campo que contienen un token que coincide con un valor especificado. Este operador solo está disponible en la multirregión de EE.UU. cuando se usa como parte de la búsqueda vectorial en un índice. String {"content": {"$search": "blue"}}

Consultar colecciones

En el siguiente ejemplo, se muestra cómo usar un filtro para consultar objetos de datos 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: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Es el Cloud de Confiance by S3NS ID del proyecto.

Método HTTP y URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Es el Cloud de Confiance by S3NS ID del proyecto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud 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 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 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

Deberías recibir una respuesta similar a la que figura a continuación:

---
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_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1.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 una agregación, usa el extremo aggregate y especifica el tipo de agregación en el cuerpo de la solicitud.

En el siguiente ejemplo, se muestra cómo contar todos los objetos de datos 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: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Es el Cloud de Confiance by S3NS ID del proyecto.

Método HTTP y URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate

Cuerpo JSON de la solicitud:

{
  "aggregate": "count"
}

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "aggregateResults": [
    {
      "count": 1000
    }
  ]
}

gcloud

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Es el Cloud de Confiance by S3NS ID del proyecto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud vector-search collections data-objects aggregate \
  --aggregation-method=count \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects aggregate `
  --aggregation-method=count `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects aggregate ^
  --aggregation-method=count ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

Deberías recibir una respuesta similar a la que figura a continuación:

aggregateResults:
- count: 1000

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1.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)

Próximos pasos