Objets de données

Dans la récupération par l'agent (anciennement Vector Search 2.0), les collections stockent les données sous forme d'objets JSON individuels appelés "objets de données". Cette page décrit les règles de validation qu'un objet de données doit respecter, et explique comment créer, lire, mettre à jour, importer, exporter et supprimer des objets de données individuellement ou par lot.

Validation des données

La récupération d'agent (anciennement Vector Search 2.0) valide chaque objet de données avant de le stocker. La validation s'effectue dans deux contextes qui appliquent les mêmes règles de base, mais diffèrent dans la manière dont les échecs sont signalés :

Contexte Applicable à Comportement en cas d'échec
Validation des objets de données Écritures individuelles et par lot : create, batchCreate, update et batchUpdate La requête échoue immédiatement avec le code d'erreur INVALID_ARGUMENT. Les écritures par lot sont atomiques : si un enregistrement n'est pas valide, aucun enregistrement de la requête n'est écrit.
Validation de l'importation import depuis Cloud Storage Chaque enregistrement est validé indépendamment. Un enregistrement non valide est écrit dans le récepteur d'erreur avec code = INVALID_ARGUMENT et ignoré, et le reste de l'importation se poursuit. Une fois qu'un enregistrement échoue à une vérification, les vérifications ultérieures ne sont pas exécutées pour cet enregistrement.

Les deux contextes appliquent les mêmes règles de base : règles d'ID, règles de champ de données (lorsque la collection déclare un dataSchema) et règles d'intégration. L'importation analyse chaque enregistrement et extrait les champs pouvant faire l'objet d'une recherche, car son entrée est constituée de fichiers bruts plutôt que de requêtes API structurées.

Pour éviter de corriger une erreur, de réingérer les données et de rencontrer une autre erreur, validez votre ensemble de données par rapport à toutes les règles suivantes avant de lancer une importation ou de créer un index.

Analyse (importation uniquement)

L'analyse syntaxique ne s'applique qu'à l'importation, qui transforme chaque ligne ou enregistrement d'entrée brute en objet de données interne. Les écritures d'API individuelles et par lot ignorent cette étape, car leur entrée est déjà structurée. L'analyse gère les deux formes JSON compatibles : le format par défaut (avec un objet vectors/data de premier niveau) et le format v1 (avec embedding, sparse_embedding, restricts ou numeric_restricts). Le format est détecté automatiquement pour chaque enregistrement.

  • Le fichier JSON doit être analysable. Chaque ligne doit être analysée en tant qu'objet JSON. Une ligne dont les clés de premier niveau ne correspondent ni au format par défaut ni au format v1 est rejetée avec Unknown JSON format for string: <line>.
  • id est obligatoire. Chaque enregistrement doit contenir un id non nul. Sinon : 'id' field is missing or null.
  • Les embeddings doivent être présents (format v1 uniquement). Un enregistrement au format v1 doit contenir au moins l'un des éléments embedding ou sparse_embedding. Sinon : 'embedding' or 'sparse_embedding' fields are missing.
  • Vérifications du type d'embedding dense. Le champ d'embedding dense (embedding dans la version 1 ou toute valeur de tableau sous vectors dans le format par défaut) doit être un tableau JSON de nombres. Une valeur qui ne peut pas être forcée en float est refusée avec '<field>' field contains non-float values.
  • Vérifications de la structure des embeddings creux. Pour chaque vecteur creux :
    • Doit être un objet JSON.
    • Doit contenir les deux tableaux : values (floats) et indices (longs). Dans la version 1, il s'agit de values et dimensions.
    • values ne doit pas être vide.
    • Les index ne doivent pas être négatifs.
    • values.length doit être égal à indices.length (ou dimensions.length pour la version v1).
  • Type de champ data Si elle est présente, data doit être un objet JSON, et non un tableau, une chaîne ou un scalaire. Sinon : 'data' field is not a JSON object.
  • Forme numeric_restricts (format v1). numeric_restricts doit être un tableau JSON d'objets. Chaque entrée doit comporter une chaîne namespace et un seul des éléments value_int, value_float ou value_double.

La plupart des problèmes de "premier échec" proviennent de cette étape. Les erreurs courantes incluent un nombre converti en chaîne dans un tableau d'intégration, un id manquant ou des values/indices de différentes longueurs.

Règles d'identification

L'ID d'un objet de données doit comporter entre 1 et 63 caractères. La longueur est la seule contrainte qu'Agent Retrieval applique à un ID. Tous les caractères sont acceptés.

Le tableau suivant présente des exemples courants :

ID Valide ? Pourquoi
movie-789 Oui Entre 1 et 63 caractères
a Oui Un seul caractère est le minimum
Doc_123 Oui Les lettres majuscules et les traits de soulignement sont autorisés.
my doc Oui Tout caractère est accepté, dans la limite du nombre de caractères.
(chaîne vide) Non Veuillez saisir au moins un caractère
64 caractères ou plus Non La longueur maximale est de 63

Règles relatives aux champs de données (schéma JSON)

La validation des champs de données ne s'exécute que si la collection déclare un dataSchema dans son CollectionConfig. Si aucun schéma n'est configuré, cette vérification est ignorée.

  • Conformité du schéma La charge utile data de l'objet de données est sérialisée au format JSON et validée par rapport au schéma JSON configuré (brouillon 7). Le validateur signale une erreur par non-respect du schéma. Par conséquent, un enregistrement comportant trois champs incorrects génère trois messages d'erreur.
    • Message : DataObject with id <id> failed schema validation: <error>.
  • Erreurs de traitement du schéma. Si le validateur de schéma lui-même génère une erreur (par exemple, en raison de fonctionnalités de brouillon non compatibles), l'enregistrement est refusé avec DataObject with id <id> failed schema validation processing: <exception>.

Règles d'intégration

La validation des embeddings itère d'abord sur les vecteurs denses, puis sur les vecteurs creux. Un seul ensemble partagé de noms de vecteurs vus s'étend aux deux listes. Un nom ne peut donc pas être utilisé deux fois, même au-delà de la limite entre les vecteurs denses et creux.

Règles partagées (s'appliquent aux formats dense et sparse)

Règle Pourquoi est-ce important ? Message d'erreur
Aucun nom de vecteur en double pour les vecteurs denses et creux du même objet de données Deux entrées portant le même nom de vecteur cibleraient la même clé de stockage, ce qui produirait un comportement last-write-wins indéfini. ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
Le nom du vecteur doit être déclaré dans le schéma de vecteur CollectionConfig. Un nom de vecteur inconnu ne peut pas être associé à une colonne. ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Règles basées uniquement sur des vecteurs denses

Règle Message d'erreur
Le champ doit être configuré comme dense dans le schéma de la collection. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
La dimension doit correspondre à celle configurée. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Toutes les valeurs doivent être finies : aucune valeur NaN, +Infinity ni -Infinity. Les valeurs non finies corrompraient les calculs de distance. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Règles avec vecteurs creux uniquement

Règle Message d'erreur
Le champ doit être configuré comme sparse dans le schéma de la collection. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Parité de la longueur des index/valeurs : indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Indices non négatifs : tous les indices sont >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Index uniques dans le même vecteur creux. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Toutes les valeurs doivent être finies. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

Extraction des champs pouvant faire l'objet d'une recherche (importation uniquement)

Lors de l'importation, une fois la validation de l'intégration réussie, le pipeline parcourt la charge utile data à l'aide de dataSchema de la collection et copie les champs déclarés par le schéma (chaîne, entier/nombre, booléen, tableau de chaînes et objets imbriqués) dans un index de champs pouvant faire l'objet d'une recherche. Deux modes d'échec peuvent également entraîner le rejet d'un enregistrement :

  • Un chemin d'accès qui devrait être une structure contient un scalaire (par exemple, le schéma indique que author.name est une chaîne, mais author est lui-même une chaîne dans le document).
  • Un champ de tableau de chaînes contient un élément non chaîne.

Elles indiquent généralement que la forme du document s'est éloignée du schéma déclaré et ne sont pas toujours détectées au niveau du schéma JSON.

Checklist avant le vol

Avant de lancer une ingestion ou de créer un index, validez l'ensemble de données par rapport aux règles suivantes. Il s'agit du même ensemble de vérifications que celui appliqué par le pipeline, ordonné de sorte qu'un seul passage côté client fasse apparaître chaque problème :

  1. Format : chaque ligne est analysée en tant que JSON et correspond à la forme par défaut ou à la forme v1.
  2. Les ID comportent entre 1 et 63 caractères et sont uniques dans l'ensemble de données.
  3. Embeddings présents : au moins un vecteur par enregistrement. Les noms de vecteur sont listés dans le schéma de vecteur CollectionConfig avec le type dense ou sparse approprié.
  4. Vecteurs denses : dimension correcte, sans valeurs NaN, +Inf ni -Inf.
  5. Vecteurs creux : values.length == indices.length ; tous les index sont supérieurs ou égaux à 0 et uniques. Les valeurs non finies ne sont pas autorisées.
  6. Aucun nom de vecteur en double dans un enregistrement, qu'il soit dense ou creux.
  7. Schéma de données : si un dataSchema est configuré, votre charge utile data est validée par rapport à celui-ci (brouillon 7), et le type JSON réel de chaque champ correspond au type déclaré (en particulier pour les objets imbriqués et les tableaux de chaînes).
  8. v1 numeric_restricts : chaque entrée comporte une chaîne namespace et exactement l'une des valeurs value_int, value_float ou value_double.

Créer un objet de données

L'exemple suivant montre comment ajouter un seul objet de données à une collection avec l'ID COLLECTION_ID.

REST

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID

Corps JSON de la requête :

{
  "data": {
    "director": "Frank Darabont",
    "genre": "Drama",
    "title": "The Shawshank Redemption",
    "year": 1994
  },
  "vectors":{
    "genre_embedding": {
      "dense": {
        "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
        "values": [ 1, 6, 3, 2, 8, 5, 2 ]
      }
    }
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "director": "Frank Darabont",
    "title": "The Shawshank Redemption",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "genre_embedding": {
      "dense": {
        "values": [
          0.3863801,
          0.73934346,
          0.16189057,
          0.5271367
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "values": [
          1,
          6,
          3,
          2,
          8,
          5,
          2
        ],
        "indices": [
          4065,
          13326,
          17377,
          25918,
          28105,
          32683,
          42998
        ]
      }
    }
  }
}

gcloud

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

  • DATA_FILE : chemin d'accès local à un fichier JSON contenant la partie "data" de l'objet de données.

    Exemple de contenu de fichier :

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE : chemin d'accès local à un fichier JSON contenant les vecteurs de l'objet de données.

    Exemple de contenu de fichier :

    {
  "genre_embedding": {
    "dense": {
      "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
    }
  },
  "plot_embedding": {
    "dense": {
      "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
    }
  },
  "soundtrack_embedding": {
    "dense": {
      "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
    }
  },
  "sparse_embedding": {
    "sparse": {
      "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
      "values": [ 1, 6, 3, 2, 8, 5, 2 ]
    }
  }
}
  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 vector-search collections data-objects create DATA_OBJECT_ID \
  --data=DATA_FILE \
  --vectors=VECTORS_FILE \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects create DATA_OBJECT_ID `
  --data=DATA_FILE `
  --vectors=VECTORS_FILE `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects create DATA_OBJECT_ID ^
  --data=DATA_FILE ^
  --vectors=VECTORS_FILE ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Created dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    data={
        "title": "The Shawshank Redemption",
        "genre": "Drama",
        "year": 1994,
        "director": "Frank Darabont",
    },
    vectors={
        "plot_embedding": {
            "dense": {"values": [0.1, 0.2, 0.3]}
        },
        "genre_embedding": {
            "dense": {"values": [0.4, 0.5, 0.6, 0.7]}
        },
        "soundtrack_embedding": {
            "dense": {"values": [0.8, 0.9, 1.0, 1.1, 1.2]}
        },
        "sparse_embedding": {
            "sparse": {"values": [1.0, 2.0], "indices": [10, 20]}
        },
    },
)
request = vectorsearch_v1.CreateDataObjectRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    data_object_id="DATA_OBJECT_ID",
    data_object=data_object,
)

# Make the request
response = data_object_service_client.create_data_object(request=request)

# Handle the response
print(response)

Les champs d'intégration pour lesquels une intégration automatique est spécifiée dans le schéma de la collection sont renseignés automatiquement. Vous pouvez également apporter vos propres embeddings (BYOE) pour définir des valeurs de champ vectoriel qui ne sont pas renseignées automatiquement.

Créer des objets de données par lot

Pour ingérer efficacement de petits nombres d'enregistrements (jusqu'à 1 000 objets de données par requête) de manière groupée, utilisez batchCreate. L'ensemble du lot est atomique : soit tous les objets de données sont créés, soit l'ensemble de la requête échoue. Pour les ensembles de données plus volumineux, préférez importer des objets de données depuis Cloud Storage.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchCreate

Corps JSON de la requête :

{
  "requests": [
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-1",
      "dataObject": {
        "data": {
          "title": "The Shawshank Redemption",
          "year": 1994
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.47, 0.09, 0.87] }
          }
        }
      }
    },
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-2",
      "dataObject": {
        "data": {
          "title": "The Godfather",
          "year": 1972
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.12, 0.55, 0.31] }
          }
        }
      }
    }
  ]
}

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

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

{
  "dataObjects": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
      "data": {
        "title": "The Shawshank Redemption",
        "year": 1994
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.47, 0.09, 0.87] }
        }
      }
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
      "data": {
        "title": "The Godfather",
        "year": 1972
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.12, 0.55, 0.31] }
        }
      }
    }
  ]
}

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 vector-search collections data-objects batch-create \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Windows (PowerShell)

gcloud vector-search collections data-objects batch-create `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Windows (cmd.exe)

gcloud vector-search collections data-objects batch-create ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Build per-DataObject create requests.
requests = [
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-1",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Shawshank Redemption", "year": 1994},
            vectors={
                "plot_embedding": {"dense": {"values": [0.47, 0.09, 0.87]}},
            },
        ),
    ),
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-2",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Godfather", "year": 1972},
            vectors={
                "plot_embedding": {"dense": {"values": [0.12, 0.55, 0.31]}},
            },
        ),
    ),
]

request = vectorsearch_v1.BatchCreateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
response = data_object_service_client.batch_create_data_objects(request=request)

# Handle the response
for data_object in response.data_objects:
    print(data_object.name)

Obtenir un objet de données

L'exemple suivant montre comment obtenir un objet de données avec l'ID DATA_OBJECT_ID à partir d'une collection avec l'ID COLLECTION_ID.

REST

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 : 

GET https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "createTime": "2026-01-31T20:05:06Z",
  "updateTime": "2026-01-31T20:05:06Z",
  "data": {
    "title": "The Shawshank Redemption",
    "director": "Frank Darabont",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "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
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    }
  }
}

gcloud

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 vector-search collections data-objects describe DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
data:
  director: Frank Darabont
  genre: Drama
  title: The Shawshank Redemption
  year: 1994
vectors:
  genre_embedding:
    dense:
      values:
      - 0.3863801
      - 0.73934346
      - 0.16189057
      - 0.5271367
  plot_embedding:
    dense:
      values:
      - 0.47520825
      - 0.090267465
      - 0.8752308
  soundtrack_embedding:
    dense:
      values:
      - 0.5920452
      - 0.08301644
      - 0.12647335
      - 0.619643
      - 0.49258286
  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

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.GetDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
response = data_object_service_client.get_data_object(request=request)

# Handle the response
print(response)

Mettre à jour un objet de données

L'exemple suivant montre comment mettre à jour le champ de données title et les valeurs vectorielles plot_embedding dans l'objet de données avec l'ID DATA_OBJECT_ID dans une collection avec l'ID COLLECTION_ID.

REST

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 : 

PATCH https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

Corps JSON de la requête :

{
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1.0,
          1.0,
          1.0
        ]
      }
    }
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1,
          1,
          1
        ]
      }
    }
  }
}

gcloud

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 vector-search collections data-objects update DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --data='{"title": "The Shawshank Redemption (updated)"}' \
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

Windows (PowerShell)

gcloud vector-search collections data-objects update DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --data='{"title": "The Shawshank Redemption (updated)"}' `
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

Windows (cmd.exe)

gcloud vector-search collections data-objects update DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --data='{"title": "The Shawshank Redemption (updated)"}' ^
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

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

Updated dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
    data={"title": "The Shawshank Redemption (updated)"},
    vectors={
        "plot_embedding": {
            "dense": {"values": [1., 1., 1.]}
        },
    },
)
request = vectorsearch_v1.UpdateDataObjectRequest(
    data_object=data_object,
)

# Make the request
response = data_object_service_client.update_data_object(request=request)

# Handle the response
print(response)

Mise à jour groupée d'objets de données

Pour mettre à jour plusieurs objets de données à la fois, utilisez batchUpdate. Vous pouvez mettre à jour 1 000 objets de données au maximum dans un même lot. Chaque requête par enregistrement spécifie le dataObject (qui doit inclure son name complet plus les champs que vous souhaitez modifier) et une liste updateMask des champs à remplacer. Les champs non spécifiés dans le masque restent inchangés.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchUpdate

Corps JSON de la requête :

{
  "requests": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
        "data": { "genre": "Thriller" }
      },
      "updateMask": "data.genre"
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.21, 0.34, 0.55] }
          }
        }
      },
      "updateMask": "vectors.plot_embedding"
    }
  ]
}

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

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

{}

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 vector-search collections data-objects batch-update \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Windows (PowerShell)

gcloud vector-search collections data-objects batch-update `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Windows (cmd.exe)

gcloud vector-search collections data-objects batch-update ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import field_mask_pb2

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Each entry specifies the DataObject to update (with its full resource
# name) and an update_mask listing the fields to overwrite. Fields not
# listed in the mask are left unchanged.
requests = [
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-1",
            data={"genre": "Thriller"},
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["data.genre"]),
    ),
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-2",
            vectors={
                "plot_embedding": {"dense": {"values": [0.21, 0.34, 0.55]}},
            },
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["vectors.plot_embedding"]),
    ),
]

request = vectorsearch_v1.BatchUpdateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_update_data_objects(request=request)

Importer des objets de données

L'exemple suivant montre comment importer des objets de données depuis Cloud Storage dans une collection dont l'ID est COLLECTION_ID. Utilisez l'importation pour les grands ensembles de données. Pour les ingestions groupées plus petites (jusqu'à 1 000 enregistrements), envisagez de créer des objets de données par lot.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:importDataObjects

Corps JSON de la requête :

{
  "gcsImport": {
    "contentsUri": "gs://your-bucket/path/to/your-data.json",
    "errorUri": "gs://your-bucket/path/to/import-errors/",
    "outputUri": "gs://your-bucket/path/to/import-output/"
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ImportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

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 vector-search collections import-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" \
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" \
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" \
  --async

Windows (PowerShell)

gcloud vector-search collections import-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" `
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" `
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" `
  --async

Windows (cmd.exe)

gcloud vector-search collections import-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" ^
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" ^
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ImportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_import={
      "contents_uri": "gs://your-bucket/path/to/your-data/",
      "error_uri": "gs://your-bucket/path/to/import-errors/",
    },
)

# Make the request
operation = vector_search_service_client.import_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

Le dossier gs://your-bucket/path/to/your-data/ peut contenir un ou plusieurs fichiers, chacun contenant plusieurs objets de données. Utilisez cette structure pour les grands ensembles de données répartis sur plusieurs fichiers. Les formats de fichiers suivants sont acceptés dans la récupération par l'agent :

  • JSONL, où chaque ligne est un objet JSON comportant trois propriétés de premier niveau : id, data et vectors. Utilisez ce format pour les nouveaux ensembles de données de récupération d'agent lorsque vous souhaitez une entrée lisible par l'homme pour l'inspection et la modification manuelle.
  • AVRO : utilisez ce format pour les nouveaux ensembles de données de récupération d'agent lorsque vous avez besoin d'un format binaire compact et validé par schéma, généralement pour les grands ensembles de données produits par des outils de pipeline de données tels que Dataflow, Beam ou Spark.
  • JSON pour la recherche vectorielle : n'utilisez ce format que si vous migrez un ensemble de données JSON existant pour la recherche vectorielle (recherche vectorielle 1.0) et que vous souhaitez le réutiliser tel quel.
  • AVRO Vector Search : n'utilisez ce format que si vous migrez un ensemble de données AVRO Vector Search (Vector Search 1.0) existant et que vous souhaitez le réutiliser tel quel.

JSONL

L'exemple suivant montre le format JSONL avec les propriétés requises. Chaque ligne du fichier d'entrée est un objet de données unique avec les propriétés de premier niveau id, data et vectors.

{
  "id": "movie-789",
  "data": {
    "title":"The Shawshank Redemption",
    "plot": "...",
    "year":1994,
    "avg_rating": 8.5,
    "movie_runtime_info": {
        "hours": 2,
        "minutes": 5
    },
  },
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11, ...],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27, ...],
      "indices": [23, 83, 131, ...]
    }
  }
}

AVRO

Pour les fichiers AVRO, chaque enregistrement doit être conforme au schéma Avro DataObject indiqué. Les champs reflètent le format JSONL :

  • id (obligatoire string).
  • vectors (map, valeur par défaut : {}). Chaque entrée est associée au nom du vecteur et sa valeur est soit un array de float (vecteur dense), soit un enregistrement SparseVector avec values (tableau de float) et indices (tableau de long).
  • data (valeur nulle possible : map, valeur par défaut : null). Les clés sont des noms de champs de données. Chaque valeur est un enregistrement DataValue dont le champ value est une union sur les types primitifs compatibles (boolean, int, long, float, double, string) plus array de DataValue et map de string à DataValue pour les structures imbriquées.
  • etag (valeur nulle autorisée : string, valeur par défaut : null).
{
  "namespace": "com.google.cloud.ai.vectorsearch",
  "type": "record",
  "name": "DataObject",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "vectors",
      "type": {
        "type": "map",
        "values": [
          {
            "type": "array",
            "items": "float"
          },
          {
            "type": "record",
            "name": "SparseVector",
            "fields": [
              {
                "name": "values",
                "type": { "type": "array", "items": "float" }
              },
              {
                "name": "indices",
                "type": { "type": "array", "items": "long" }
              }
            ]
          }
        ]
      },
      "default": {}
    },
    {
      "name": "data",
      "type": [
        "null",
        {
          "type": "map",
          "values": {
            "type": "record",
            "name": "DataValue",
            "fields": [
              {
                "name": "value",
                "type": [
                  "boolean",
                  "int",
                  "long",
                  "float",
                  "double",
                  "string",
                  {
                    "type": "array",
                    "items": "DataValue"
                  },
                  {
                    "type": "map",
                    "values": "DataValue"
                  }
                ]
              }
            ]
          }
        }
      ],
      "default": null
    },
    {
      "name": "etag",
      "type": [
        "null",
        "string"
      ],
      "default": null
    }
  ]
}

L'extrait suivant montre le contenu conceptuel d'un enregistrement AVRO unique qui correspond à l'exemple JSONL précédent. Notez que, dans ce schéma, chaque entrée de data est encapsulée dans un enregistrement DataValue (avec un seul champ value), ce qui correspond à la façon dont AVRO représente les types hétérogènes dans data :

{
  "id": "movie-789",
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27],
      "indices": [23, 83, 131]
    }
  },
  "data": {
    "title": { "value": "The Shawshank Redemption" },
    "plot": { "value": "..." },
    "year": { "value": 1994 },
    "avg_rating": { "value": 8.5 },
    "movie_runtime_info": {
      "value": {
        "hours":   { "value": 2 },
        "minutes": { "value": 5 }
      }
    }
  }
}

Exporter des objets de données

L'exemple suivant montre comment exporter chaque objet de données d'une collection vers Cloud Storage au format JSONL. Le bucket de destination doit se trouver dans la même région que la collection. L'exportation est une opération de longue durée.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:exportDataObjects

Corps JSON de la requête :

{
  "gcsDestination": {
    "exportUri": "gs://your-bucket/path/to/export-dir/",
    "format": "JSONL"
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

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 vector-search collections export-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" \
  --gcs-destination-format="jsonl" \
  --async

Windows (PowerShell)

gcloud vector-search collections export-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" `
  --gcs-destination-format="jsonl" `
  --async

Windows (cmd.exe)

gcloud vector-search collections export-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" ^
  --gcs-destination-format="jsonl" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ExportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_destination={
        "export_uri": "gs://your-bucket/path/to/export-dir/",
        "format": vectorsearch_v1.ExportDataObjectsRequest.GcsExportDestination.Format.JSONL,
    },
)

# Make the request
operation = vector_search_service_client.export_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

Supprimer un objet de données

L'exemple suivant montre comment supprimer un seul objet de données DATA_OBJECT_ID d'une collection avec l'ID COLLECTION_ID.

REST

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 : 

DELETE https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

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

  • DATA_OBJECT_ID : ID de l'objet de données.
  • 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 vector-search collections data-objects delete DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Deleted dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.DeleteDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
data_object_service_client.delete_data_object(request=request)

Supprimer des objets de données par lot

Pour supprimer plusieurs objets de données à la fois, utilisez batchDelete avec une liste de noms de ressources d'objets de données complets. Vous pouvez supprimer jusqu'à 1 000 objets de données en un seul lot.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchDelete

Corps JSON de la requête :

{
  "requests": [
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1" },
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2" }
  ]
}

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

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

{}

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 vector-search collections data-objects batch-delete \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Windows (PowerShell)

gcloud vector-search collections data-objects batch-delete `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Windows (cmd.exe)

gcloud vector-search collections data-objects batch-delete ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

requests = [
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-1",
    ),
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-2",
    ),
]

request = vectorsearch_v1.BatchDeleteDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_delete_data_objects(request=request)

Compter les objets de données

Pour compter le nombre d'objets de données contenus dans une collection, utilisez l'opération aggregate avec la méthode d'agrégation COUNT. Le même appel accepte une expression de filtre JSON facultative. Vous pouvez ainsi ne compter que les objets de données qui correspondent à un prédicat (par exemple, genre == "sci-fi").

Pour compter chaque objet de données de la collection, omettez le filtre.

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate

Corps JSON de la requête :

{
  "aggregate": "COUNT",
  "filter": { "genre": { "$eq": "sci-fi" } }
}

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

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

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

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 vector-search collections data-objects aggregate \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --aggregation-method=count \
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Windows (PowerShell)

gcloud vector-search collections data-objects aggregate `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --aggregation-method=count `
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Windows (cmd.exe)

gcloud vector-search collections data-objects aggregate ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --aggregation-method=count ^
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import struct_pb2
from google.protobuf import json_format

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Optional: build a JSON filter. Omit `filter=` to count everything.
filter_struct = json_format.ParseDict(
    {"genre": {"$eq": "sci-fi"}}, struct_pb2.Struct()
)

request = vectorsearch_v1.AggregateDataObjectsRequest(
    parent=parent,
    aggregate=vectorsearch_v1.AggregationMethod.COUNT,
    filter=filter_struct,
)

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

# The count value is returned in aggregate_results[0].
for result in response.aggregate_results:
    print(result)

Étape suivante