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

Interroger des collections pour obtenir des objets de données

L'objectif de l'API Query est de récupérer des objets de données à partir d'une collection à l'aide d'un filtre. Cela revient à interroger une table de base de données et à utiliser une clause SQL WHERE. Vous pouvez également utiliser l'agrégation pour obtenir le nombre d'objets de données correspondant à un filtre.

Langage d'expression des filtres

En plus de la fonctionnalité de recherche KNN/ANN, Vector Search 2.0 offre des capacités de requête polyvalentes à l'aide d'un langage de requête personnalisé. Le langage de requête est expliqué dans le tableau suivant.

Filtre	Description	Types compatibles	Exemple
$eq	Fait correspondre les objets de données dont les valeurs de champ sont égales à une valeur spécifiée.	Nombre, chaîne, booléen	`{"genre": {"$eq": "documentary"}}`
$ne	Fait correspondre les objets de données dont les valeurs de champ sont différentes d'une valeur spécifiée.	Nombre, chaîne, booléen	`{"genre": {"$ne": "drama"}}`
$gt	Fait correspondre les objets de données dont les valeurs de champ sont supérieures à une valeur spécifiée.	Nombre	`{"year": {"$gt": 2019}}`
$gte	Correspond aux objets de données dont les valeurs de champ sont supérieures ou égales à une valeur spécifiée.	Nombre	`{"year": {"$gte": 2020}}`
$lt	Fait correspondre les objets de données dont les valeurs de champ sont inférieures à une valeur spécifiée.	Nombre	`{"year": {"$lt": 2020}}`
$lte	Correspond aux objets de données dont les valeurs de champ sont inférieures ou égales à une valeur spécifiée.	Nombre	`{"year": {"$lte": 2020}}`
$in	Fait correspondre les objets de données dont les valeurs de champ figurent dans un tableau spécifié.	Chaîne	`{"genre": {"$in": ["comedy", "documentary"]}}`
$nin	Fait correspondre les objets de données dont les valeurs de champ ne figurent pas dans un tableau spécifié.	Chaîne	`{"genre": {"$nin": ["comedy", "documentary"]}}`
$et	Associe les clauses de requête avec un ET logique.	-	`{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`
$ou	Joint les clauses de requête avec un OR logique.	-	`{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}`
$all	Sélectionne les documents dont la valeur de tableau d'un champ contient toutes les valeurs spécifiées.	-	`{"colors": {"$all": ["red", "blue"]}}`

Interroger les collections

L'exemple suivant montre comment utiliser un filtre pour interroger des objets de données dans une collection dont l'ID est COLLECTION_ID.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Agent Platform.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "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": "*"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

{
  "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

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Agent Platform.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou 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)

Remarque : Si cette commande utilise ' pour citer un contenu, remplacez ces guillemets simples par des guillemets doubles. Si les guillemets sont imbriqués, utilisez \" pour échapper les guillemets internes.

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

Vous devriez obtenir un résultat semblable à celui-ci :

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

Pour effectuer une agrégation, vous devez utiliser le point de terminaison aggregate et spécifier le type d'agrégation dans le corps de la requête.

L'exemple suivant montre comment compter tous les objets de données d'une collection avec l'ID COLLECTION_ID.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Agent Platform.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "aggregate": "count"
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Agent Platform.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou 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

Vous devriez obtenir un résultat semblable à celui-ci :

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)

Étape suivante

Découvrez comment rechercher des objets de données.

Interroger des collections pour obtenir des objets de données Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Langage d'expression des filtres

Interroger les collections

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Étape suivante

Interroger des collections pour obtenir des objets de données