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

Jedes Datenobjekt, das von Agent Retrieval aufgenommen wird, wird anhand einer festen Reihe von Regeln geprüft. Wenn eine Regel für einen Datensatz fehlschlägt, wird dieser Datensatz abgelehnt und mit code = INVALID_ARGUMENT an das Fehlersink gesendet. Spätere Prüfungen werden für diesen Datensatz nicht ausgeführt. Um den Zyklus „einen Fehler beheben, Daten noch einmal aufnehmen, auf den nächsten Fehler stoßen“ zu vermeiden, sollten Sie Ihr Dataset anhand aller Datenvalidierungsregeln validieren, bevor Sie mit der Aufnahme oder dem Indexaufbau beginnen.

Die Pipeline wendet die Validierungen in dieser Reihenfolge an:

Phase Was wird geprüft?
1. Parsen JSON ist wohlgeformt; erforderliche Felder der obersten Ebene sind vorhanden; Feldtypen sind korrekt
2. Bestätigung per Ausweis Das Feld id ist vorhanden und entspricht dem dokumentierten ID-Format.
3. Schema für Datenfelder Die data-Nutzlast entspricht dem JSON-Schema, das in der CollectionConfig der Sammlung deklariert ist.
4. Validierungen von Einbettungen Jeder dichte/spärliche Vektor entspricht dem Vektorschema der Sammlung (Name, Typ, Dimension, endliche Werte, Sparsity und Eindeutigkeit).
5. Suchfelder Felder, die im Schema als durchsuchbar gekennzeichnet sind, können erfolgreich aus data extrahiert werden.

1. Parsing-Validierungen

Die Parsing-Validierungen werden zuerst ausgeführt, während jede Eingabezeile in ein internes Datenobjekt umgewandelt wird. Sie gelten für beide unterstützten JSON-Formate: 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 parsierbar 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 einen nicht leeren id-Wert enthalten. 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 „Voll besetzte 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.

2. Bestätigung per Ausweis

Datenobjekt-IDs müssen RFC 1035 entsprechen. Das bedeutet in der Praxis:

  • 1–63 Zeichen lang
  • Nur Kleinbuchstaben, Ziffern und Bindestriche (-) Keine Großbuchstaben, Unterstriche, Leerzeichen, Symbole oder Unicode-Zeichen.
  • Muss mit einem Kleinbuchstaben beginnen (a-z).
  • Muss mit einem Kleinbuchstaben oder einer Ziffer enden (keine nachgestellten -).

Regulärer Ausdruck: [a-z]([-a-z0-9]{0,61}[a-z0-9])?

Die folgende Tabelle enthält einige Beispiele:

ID Gültig? Warum
doc-123 Ja Beginnt mit einem Buchstaben, enthält nur Kleinbuchstaben, Ziffern und Bindestriche und endet mit einer Ziffer
a Ja Mindestens ein Kleinbuchstabe
product-sku-42 Ja Alle Regeln erfüllt
Doc-123 Nein Großbuchstaben in D nicht zulässig
123-doc Nein Muss mit einem Buchstaben und nicht mit einer Ziffer beginnen
doc_123 Nein Unterstrich nicht zulässig
doc-123- Nein Darf nicht mit einem Bindestrich enden
my doc Nein Leerzeichen sind nicht zulässig
64 Zeichen oder mehr Nein Die maximale Länge beträgt 63 Zeichen.

Diese Form ist die DNS-Label-Regel (der Teil zwischen Punkten in einem Hostnamen wie my-service.example.com). Sie wird hier wiederverwendet, damit IDs ohne Escaping sicher durch URLs, Dateinamen, Logs und CLIs übertragen werden können.

3. Validierungen von Datenfeldern (JSON-Schema)

Die Validierungsphase für Datenfelder wird nur ausgeführt, wenn für die Sammlung ein dataSchema in der CollectionConfig deklariert ist. Wenn kein Schema konfiguriert ist, wird diese Phase ü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.

4. Validierungen von Einbettungsfeldern

In der Phase der Validierung von Einbettungsfeldern 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)

5. Suchfelder

Nachdem die Einbettungsvalidierung erfolgreich war, durchläuft die Pipeline 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 entsprechen dem regulären Ausdruck [a-z]([-a-z0-9]{0,61}[a-z0-9])? gemäß RFC 1035 und sind im gesamten Dataset 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. Sparse-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 die Vektoren 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 mit jeweils mehreren Datenobjekten 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.

Im Folgenden finden Sie ein Beispiel für die JSONL-Datei mit den erforderlichen Attributen.

{
  "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 Datenobjekte gleichzeitig löschen möchten, verwenden Sie batchDelete mit einer Liste von vollqualifizierten Ressourcennamen für Datenobjekte. 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