Datenobjekte

In Agent Retrieval (früher Vector Search 2.0) werden Daten in Sammlungen als einzelne JSON-Objekte gespeichert, die als Datenobjekte bezeichnet werden. Auf dieser Seite werden die Validierungsregeln beschrieben, die ein Datenobjekt erfüllen muss, und es wird erläutert, wie Sie Datenobjekte einzeln oder im Batch erstellen, lesen, aktualisieren, importieren, exportieren und löschen.

Datenvalidierung

Bei Agent Retrieval (früher Vector Search 2.0) wird jedes Datenobjekt vor dem Speichern validiert. Die Validierung erfolgt in zwei Kontexten, in denen dieselben grundlegenden Regeln gelten, sich aber darin unterscheiden, wie Fehler gemeldet werden:

Kontext Gilt für Verhalten bei Fehler
Validierung von Datenobjekten Einzel- und Batch-Schreibvorgänge: create, batchCreate, update und batchUpdate Die Anfrage schlägt sofort mit INVALID_ARGUMENT fehl. Batch-Schreibvorgänge sind atomar: Wenn ein Datensatz ungültig ist, wird kein Datensatz in der Anfrage geschrieben.
Importvalidierung import aus Cloud Storage Jeder Datensatz wird unabhängig validiert. Ein ungültiger Datensatz wird mit code = INVALID_ARGUMENT in die Fehlersenke geschrieben und übersprungen. Der Rest des Imports wird fortgesetzt. Wenn ein Datensatz eine Prüfung nicht besteht, werden keine weiteren Prüfungen für ihn ausgeführt.

In beiden Kontexten gelten dieselben grundlegenden Regeln: ID-Regeln, Regeln für Datenfelder (wenn in der Sammlung ein dataSchema deklariert ist) und Einbettungsregeln. Beim Import wird jeder Datensatz geparst und durchsuchbare Felder werden extrahiert, da die Eingabe Rohdateien und keine strukturierten API-Anfragen sind.

Damit Sie nicht in eine Schleife geraten, in der Sie immer wieder einen Fehler beheben, die Daten neu aufnehmen und dann auf den nächsten Fehler stoßen, sollten Sie Ihren Datensatz vor dem Import oder dem Erstellen eines Index anhand aller folgenden Regeln validieren.

Parsing (nur Import)

Das Parsen gilt nur für den Import, bei dem jede Rohdatenzeile oder jeder Datensatz in ein internes Datenobjekt umgewandelt wird. Bei einzelnen und Batch-API-Schreibvorgängen wird dieser Schritt übersprungen, da die Eingabe bereits strukturiert ist. Beim Parsen werden beide unterstützten JSON-Formate verarbeitet: das Standardformat (mit einem vectors-/data-Objekt auf oberster Ebene) und das v1-Format (mit embedding, sparse_embedding, restricts oder numeric_restricts). Das Format wird automatisch pro Datensatz erkannt.

  • JSON muss analysierbar sein. Jede Zeile muss als JSON-Objekt geparst werden. Eine Zeile, deren Schlüssel der obersten Ebene weder dem Standard- noch dem V1-Format entsprechen, wird mit Unknown JSON format for string: <line> abgelehnt.
  • id ist erforderlich. Jeder Datensatz muss eine id enthalten, die nicht null ist. Andernfalls: 'id' field is missing or null.
  • Einbettungen müssen vorhanden sein (nur v1-Format). Ein Datensatz im V1-Format muss mindestens einen der Werte embedding oder sparse_embedding enthalten. Andernfalls: 'embedding' or 'sparse_embedding' fields are missing.
  • Prüfungen des Typs „Vollbesetzte Einbettung“: Das Feld für dichte Einbettungen (embedding in Version 1 oder ein beliebiger Arraywert unter vectors im Standardformat) muss ein JSON-Array mit Zahlen sein. Ein Wert, der nicht in einen float-Wert umgewandelt werden kann, wird mit '<field>' field contains non-float values abgelehnt.
  • Prüfungen der Struktur dünnbesetzter Einbettungen: Für jeden dünnbesetzten Vektor:
    • Muss ein JSON-Objekt sein.
    • Muss beide Arrays enthalten: values (Gleitkommazahlen) und indices (Ganzzahlen). In Version 1 sind das values und dimensions.
    • values darf nicht leer sein.
    • Die Indexe müssen nicht negativ sein.
    • values.length muss gleich indices.length (oder v1 dimensions.length) sein.
  • Feldtyp data. Falls vorhanden, muss data ein JSON-Objekt und kein Array, String oder Skalar sein. Andernfalls: 'data' field is not a JSON object.
  • numeric_restricts-Form (V1-Format) numeric_restricts muss ein JSON-Array von Objekten sein. Jeder Eintrag muss einen String namespace haben und genau einen der Werte value_int, value_float oder value_double festlegen.

Die meisten Probleme mit dem „ersten Fehler“ treten in dieser Phase auf. Häufige Fehler sind eine als String formatierte Zahl in einem Einbettungs-Array, ein fehlendes id oder values/indices mit unterschiedlichen Längen.

ID-Regeln

Eine Datenobjekt-ID muss zwischen 1 und 63 Zeichen lang sein. Die Länge ist die einzige Einschränkung, die für eine ID durch „Agent Retrieval“ erzwungen wird. Alle Zeichen sind zulässig.

Die folgende Tabelle enthält einige Beispiele:

ID Gültig? Warum
movie-789 Ja Zwischen 1 und 63 Zeichen
a Ja Mindestens ein Zeichen
Doc_123 Ja Großbuchstaben und Unterstriche sind zulässig.
my doc Ja Es sind alle Zeichen zulässig, sofern die Längenbeschränkung eingehalten wird.
(leerer String) Nein Mindestens ein Zeichen ist erforderlich
Mindestens 64 Zeichen Nein Die maximale Länge beträgt 63 Zeichen.

Regeln für Datenfelder (JSON-Schema)

Die Validierung von Datenfeldern wird nur ausgeführt, wenn in der Sammlung ein dataSchema im CollectionConfig deklariert ist. Wenn kein Schema konfiguriert ist, wird diese Prüfung übersprungen.

  • Schema-Compliance: Die data-Nutzlast des Datenobjekts wird in JSON serialisiert und anhand des konfigurierten JSON-Schemas (Draft 7) validiert. Der Validator meldet einen Fehler pro Schemaschwerwiegendem Fehler. Ein Datensatz mit drei fehlerhaften Feldern führt also zu drei Fehlermeldungen.
    • Nachricht: DataObject with id <id> failed schema validation: <error>.
  • Fehler bei der Schemabearbeitung: Wenn der Schemavalidator selbst eine Ausnahme auslöst (z. B. bei nicht unterstützten Draft-Funktionen), wird der Datensatz mit DataObject with id <id> failed schema validation processing: <exception> abgelehnt.

Regeln für das Einbetten

Bei der Einbettungsvalidierung werden zuerst dichte und dann spärliche Vektoren durchlaufen. Für beide Listen wird ein gemeinsamer Satz von gesehenen Vektornamen verwendet. Ein Name kann also nicht zweimal verwendet werden, auch nicht über die Grenze zwischen dicht und spärlich hinweg.

Gemeinsame Regeln (gelten sowohl für dichte als auch für spärliche Daten)

Regel Die Vorteile Fehlermeldung
Keine doppelten Vektornamen für dichte und spärliche Vektoren für dasselbe Datenobjekt Zwei Einträge mit demselben Vektornamen würden auf denselben Speicherschlüssel verweisen, was zu einem undefinierten Verhalten des Last-Write-Wins-Verfahrens führen würde. ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
Vektorname muss im CollectionConfig-Vektorschema deklariert werden Ein unbekannter Vektorname kann nicht an eine Spalte weitergeleitet werden. ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Regeln nur mit voll besetzten Vektoren

Regel Fehlermeldung
Das Feld muss im Sammlungsschema als dense konfiguriert sein. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
Die Dimension muss mit der konfigurierten Dimension übereinstimmen. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Alle Werte müssen endlich sein – keine NaN, +Infinity oder -Infinity. Nicht endliche Werte würden die Distanzberechnungen verfälschen. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Regeln nur für dünn besetzte Vektoren

Regel Fehlermeldung
Das Feld muss im Sammlungsschema als sparse konfiguriert sein. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Parität von Index-/Wertlänge: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Nicht negative Indexe: Jeder Index ist >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Eindeutige Indexwerte innerhalb desselben dünnbesetzten Vektors. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Alle Werte müssen endlich sein. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

Extrahierung durchsuchbarer Felder (nur Import)

Während des Imports durchläuft die Pipeline nach erfolgreicher Einbettungsvalidierung die data-Nutzlast mithilfe von dataSchema der Sammlung und kopiert Felder, die im Schema deklariert sind (String, Ganzzahl/Zahl, boolescher Wert, String-Array und verschachtelte Objekte), in einen Index für durchsuchbare Felder. In zwei Fehlermodi wird ein Datensatz ebenfalls abgelehnt:

  • Ein Pfad, der ein struct sein sollte, enthält einen Skalar (z. B. ist author.name laut Schema ein String, aber author ist im Dokument selbst ein String).
  • Ein Feld vom Typ „Array von Strings“ enthält ein Element, das kein String ist.

Diese weisen in der Regel darauf hin, dass sich die Form des Dokuments vom deklarierten Schema entfernt hat. Sie werden nicht immer in der JSON-Schema-Phase erkannt.

Checkliste vor dem Flug

Bevor Sie mit der Aufnahme oder dem Indexaufbau beginnen, müssen Sie den gesamten Datensatz anhand der folgenden Regeln validieren. Dies ist dieselbe Reihe von Prüfungen, die von der Pipeline angewendet werden. Sie sind so angeordnet, dass jedes Problem durch einen einzelnen clientseitigen Durchlauf erkannt wird:

  1. Format: Jede Zeile wird als JSON geparst und entspricht entweder der Standardform oder der Form von Version 1.
  2. IDs: Sie sind zwischen 1 und 63 Zeichen lang und im gesamten Datensatz eindeutig.
  3. Einbettungen vorhanden: Mindestens ein Vektor pro Datensatz; Vektornamen sind in Ihrem CollectionConfig-Vektorschema mit dem richtigen Typ „dense“ oder „sparse“ aufgeführt.
  4. Dichte Vektoren: korrekte Dimension, keine NaN-, +Inf- oder -Inf-Werte.
  5. Dünn besetzte Vektoren: values.length == indices.length; alle Indexe größer oder gleich 0 und eindeutig. Nicht endliche Werte sind nicht zulässig.
  6. Keine doppelten Vektornamen in einem Datensatz für dichte und spärliche Vektoren.
  7. Datenschema: Wenn ein dataSchema konfiguriert ist, wird die data-Nutzlast anhand des Schemas validiert (Draft 7). Der tatsächliche JSON-Typ jedes Felds muss mit dem deklarierten Typ übereinstimmen (insbesondere bei verschachtelten Objekten und Arrays von Strings).
  8. v1 numeric_restricts: Jeder Eintrag enthält einen String namespace und genau einen der Werte value_int / value_float / value_double.

Datenobjekt erstellen

Im folgenden Beispiel wird einer Sammlung mit der ID COLLECTION_ID ein einzelnes Datenobjekt hinzugefügt.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • DATA_FILE: Der lokale Pfad zu einer JSON-Datei mit dem Datenteil des Datenobjekts.

    Beispiel für Dateiinhalte:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: Der lokale Pfad zu einer JSON-Datei, die den Vektorteil des Datenobjekts enthält.

    Beispiel für Dateiinhalte:

    {
  "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: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

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)

Felder, für die im Sammlungsschema eine automatische Einbettung angegeben ist, werden automatisch ausgefüllt. Sie können auch Ihre eigenen Einbettungen (BYOE) verwenden, um Vektorfeldwerte festzulegen, die nicht automatisch eingefügt werden.

Datenobjekte im Batch erstellen

Für die effiziente Bulk-Aufnahme einer kleinen Anzahl von Datensätzen (bis zu 1.000 DataObjects pro Anfrage) verwenden Sie batchCreate. Der gesamte Batch ist atomar: Entweder werden alle Datenobjekte erstellt oder die gesamte Anfrage schlägt fehl. Bei größeren Datasets sollten Sie Datenobjekte aus Cloud Storage importieren.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Datenobjekt abrufen

Das folgende Beispiel zeigt, wie Sie ein Datenobjekt mit der ID DATA_OBJECT_ID aus einer Sammlung mit der ID COLLECTION_ID abrufen.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

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)

Datenobjekt aktualisieren

Im folgenden Beispiel wird gezeigt, wie das Datenfeld title und die Vektorwerte plot_embedding im Datenobjekt mit der ID DATA_OBJECT_ID in einer Sammlung mit der ID COLLECTION_ID aktualisiert werden.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

Linux, macOS oder 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]}}}'

Sie sollten eine Antwort ähnlich der folgenden erhalten:

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)

Datenobjekte im Batch aktualisieren

Wenn Sie viele Datenobjekte gleichzeitig aktualisieren möchten, verwenden Sie batchUpdate. In einem einzelnen Batch können maximal 1.000 Datenobjekte aktualisiert werden. In jeder Anfrage pro Datensatz wird die dataObject angegeben (die die vollständige Ressourcen-name sowie die Felder enthalten muss, die Sie ändern möchten) und eine updateMask, in der die zu überschreibenden Felder aufgeführt sind. Felder, die nicht in der Maske aufgeführt sind, bleiben unverändert.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{}

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Datenobjekte importieren

Im folgenden Beispiel wird gezeigt, wie Sie Datenobjekte aus Cloud Storage in eine Sammlung mit der ID COLLECTION_ID importieren. Verwenden Sie den Import für große Datasets. Für kleinere Bulk-Aufnahmen (bis zu 1.000 Datensätze) sollten Sie Data-Objekte im Batch erstellen.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Der Ordner gs://your-bucket/path/to/your-data/ kann eine oder mehrere Dateien enthalten, die jeweils mehrere Datenobjekte enthalten. Verwenden Sie diese Struktur für große Datasets, die auf mehrere Dateien verteilt sind. Die folgenden Dateiformate werden in Agent Retrieval unterstützt:

  • JSONL, wobei jede Zeile ein JSON-Objekt mit drei Eigenschaften der obersten Ebene ist: id, data und vectors. Verwenden Sie dieses Format für neue Datasets für die Agent-Abfrage, wenn Sie menschenlesbare Eingaben für die manuelle Überprüfung und Bearbeitung benötigen.
  • AVRO: Verwenden Sie dieses Format für neue Agent Retrieval-Datasets, wenn Sie ein kompaktes, schemavalidiertes Binärformat benötigen – in der Regel für große Datasets, die von Datenpipeline-Tools wie Dataflow, Beam oder Spark erstellt werden.
  • Vector Search JSON: Verwenden Sie dieses Format nur, wenn Sie ein vorhandenes JSON-Dataset für Vector Search (Vector Search 1.0) migrieren und es unverändert wiederverwenden möchten.
  • AVRO für die Vektorsuche: Verwenden Sie dieses Format nur, wenn Sie ein vorhandenes AVRO-Dataset für die Vektorsuche (Vektorsuche 1.0) migrieren und es unverändert wiederverwenden möchten.

JSONL

Das folgende Beispiel zeigt das JSONL-Format mit den erforderlichen Attributen. Jede Zeile in der Eingabedatei ist ein einzelnes Datenobjekt mit den Properties id, data und vectors auf oberster Ebene.

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

Bei AVRO-Dateien muss jeder Datensatz dem gezeigten DataObject-Avro-Schema entsprechen. Die Felder entsprechen dem JSONL-Format:

  • id (erforderlich string).
  • vectors (map, Standardwert {}): Jeder Eintrag wird mit dem Vektornamen als Schlüssel versehen. Der Wert ist entweder ein array von float (dichter Vektor) oder ein SparseVector-Datensatz mit values (Array von float) und indices (Array von long).
  • data (nullable map, Standardwert null). Schlüssel sind Datenfeldnamen. Jeder Wert ist ein DataValue-Datensatz, dessen Feld value eine Vereinigung der unterstützten einfachen Typen (boolean, int, long, float, double, string) sowie array von DataValue und map von string bis DataValue für verschachtelte Strukturen ist.
  • etag (nullable string, Standard 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
    }
  ]
}

Das folgende Snippet zeigt den konzeptionellen Inhalt eines einzelnen AVRO-Datensatzes, der dem vorherigen JSONL-Beispiel entspricht. Beachten Sie, dass in diesem Schema jeder Eintrag in data in einem DataValue-Datensatz (mit einem einzelnen value-Feld) eingeschlossen ist. So stellt AVRO die heterogenen Typen in data dar:

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

Datenobjekte exportieren

Im folgenden Beispiel wird gezeigt, wie jedes Datenobjekt in einer Sammlung im JSONL-Format in Cloud Storage exportiert wird. Der Ziel-Bucket muss sich in derselben Region wie die Sammlung befinden. Der Export ist ein Vorgang mit langer Ausführungszeit.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Datenobjekt löschen

Im folgenden Beispiel wird gezeigt, wie ein einzelnes Datenobjekt DATA_OBJECT_ID aus einer Sammlung mit der ID COLLECTION_ID gelöscht wird.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • DATA_OBJECT_ID: Die ID des Datenobjekts.
  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

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)

Datenobjekte im Batch löschen

Wenn Sie viele Data Objects gleichzeitig löschen möchten, verwenden Sie batchDelete mit einer Liste von voll qualifizierten Ressourcennamen für Data Objects. In einem einzelnen Batch können maximal 1.000 Datenobjekte gelöscht werden.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{}

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Datenobjekte zählen

Wenn Sie zählen möchten, wie viele Datenobjekte eine Sammlung enthält, verwenden Sie den Vorgang aggregate mit der Aggregationsmethode COUNT. Derselbe Aufruf akzeptiert einen optionalen JSON-Filterausdruck, sodass Sie nur die Datenobjekte zählen können, die einem Prädikat entsprechen (z. B. genre == "sci-fi").

Wenn Sie alle Datenobjekte in der Sammlung zählen möchten, lassen Sie den Filter weg.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

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

Nächste Schritte