Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Cómo consultar colecciones para objetos de datos

El propósito de la API de Query es recuperar objetos de datos de una colección mediante 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 expresiones de filtro

Además de la funcionalidad de búsqueda de KNN/ANN, Vector Search 2.0 proporciona capacidades de consulta versátiles con un lenguaje de consulta personalizado. El lenguaje de consulta 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 con valores de campo que son mayores o iguales que un valor especificado.	Número	`{"year": {"$gte": 2020}}`
$lt	Coincide con los objetos de datos con valores de campo que son menores que un valor especificado.	Número	`{"year": {"$lt": 2020}}`
$lte	Coincide con los objetos de datos con valores de campo que son menores o iguales que un valor especificado.	Número	`{"year": {"$lte": 2020}}`
$in	Coincide con los objetos de datos con valores de campo que están en un array especificado.	Cadena	`{"genre": {"$in": ["comedy", "documentary"]}}`
$nin	Coincide con los objetos de datos con valores de campo que no están en un array especificado.	Cadena	`{"genre": {"$nin": ["comedy", "documentary"]}}`
$and	Une las cláusulas de consulta con un AND lógico.	-	`{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`
$or	Une las 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"]}}`

Cómo 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: Es el ID de la colección.
LOCATION: Es la región en la que usas Agent Platform.
PROJECT_ID: Es el ID del Google Cloud proyecto.

Método HTTP y URL:

POST https://vectorsearch.googleapis.com/v1beta/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:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query" | Select-Object -Expand Content

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, 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 Google Cloud proyecto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

gcloud beta vector-search collections data-objects query \
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search collections data-objects query `
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

Nota: Si este comando usa ' para el contenido de comillas, reemplaza estas comillas simples con comillas dobles. Si las comillas están anidadas, usa \" para escapar las comillas internas.

gcloud beta vector-search collections data-objects query ^
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.QueryDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    filter={
        "$or": [
            {"director": {"$eq": "Akira Kurosawa"}},
            {
                "$and": [
                    {"director": {"$eq": "David Fincher"}},
                    {"genre": {"$ne": "Thriller"}},
                ]
            },
        ]
    },
)

# Make the request
page_result = data_object_search_service_client.query_data_objects(request=request)

# Handle the response
for response in page_result:
    print(response)

Para realizar 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: Es el ID de la colección.
LOCATION: Es la región en la que usas Agent Platform.
PROJECT_ID: Es el ID del Google Cloud proyecto.

Método HTTP y URL:

POST https://vectorsearch.googleapis.com/v1beta/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:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate"

PowerShell (Windows)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate" | Select-Object -Expand Content

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, 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 Google Cloud proyecto.

Ejecuta el siguiente comando:

Linux, macOS o Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

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

aggregateResults:
- count: 1000

Python

from google.cloud import vectorsearch_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.AggregateDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    aggregate="COUNT",
)

# Make the request
response = data_object_search_service_client.aggregate_data_objects(request=request)

# Handle the response
print(response)

Próximos pasos

Obtén información para buscar objetos de datos.

Cómo consultar colecciones para objetos de datos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Lenguaje de expresiones de filtro

Cómo consultar colecciones

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Próximos pasos

Cómo consultar colecciones para objetos de datos