Oggetti dati

In Recupero dell'agente (precedentemente Vector Search 2.0), le raccolte archiviano i dati come singoli oggetti JSON chiamati oggetti di dati. Questa pagina descrive le regole di convalida che un oggetto dati deve soddisfare e come creare, leggere, aggiornare, importare, esportare ed eliminare gli oggetti dati singolarmente o in batch.

Convalida dei dati

Ogni oggetto dati importato da Agent Retrieval viene controllato in base a un insieme fisso di regole. Se una regola non viene superata per un record, questo viene rifiutato e inviato al sink degli errori con code = INVALID_ARGUMENT; i controlli successivi non vengono eseguiti per quel record. Per evitare il ciclo "correggi un errore, esegui nuovamente l'importazione, riscontri l'errore successivo", convalida il set di dati in base a tutte le regole di convalida dei dati prima di avviare un'importazione o una creazione di indice.

La pipeline applica le convalide in questo ordine:

Fase Cosa controlla
1. Analisi Il JSON è ben formato; esistono i campi di primo livello obbligatori; i tipi di campi sono corretti
2. Convalide dell'identità Il campo id è presente e corrisponde al formato ID documentato
3. Schema del campo di dati Il payload data è conforme allo schema JSON dichiarato in CollectionConfig della raccolta
4. Convalide dell'incorporamento Ogni vettore denso/sparso corrisponde allo schema del vettore della raccolta (nome, tipo, dimensione, valori finiti, parità e unicità sparse)
5. Searchable-fields population I campi contrassegnati come ricercabili nello schema possono essere estratti correttamente da data

1. Convalide dell'analisi

Le convalide dell'analisi vengono eseguite per prime, trasformando ogni riga di input in un oggetto dati interno. Si applicano a entrambe le forme JSON supportate, al formato predefinito (con un oggetto vectors/data di primo livello) e al formato v1 (con embedding, sparse_embedding, restricts o numeric_restricts). Il formato viene rilevato automaticamente per ogni record.

  • Il file JSON deve essere analizzabile. Ogni riga deve essere analizzata come oggetto JSON. Una riga le cui chiavi di primo livello non corrispondono al formato predefinito o v1 viene rifiutata con Unknown JSON format for string: <line>.
  • id è obbligatorio.Ogni record deve contenere un valore id non nullo. In caso contrario: 'id' field is missing or null.
  • Gli incorporamenti devono essere presenti (solo formato v1). Un record in formato v1 deve contenere almeno uno tra embedding e sparse_embedding. Altrimenti: 'embedding' or 'sparse_embedding' fields are missing.
  • Controlli del tipo di incorporamento denso.Il campo di incorporamento denso (embedding nella versione 1 o qualsiasi valore di array in vectors nel formato predefinito) deve essere un array JSON di numeri. Un valore che non può essere forzato in modo da corrispondere a float viene rifiutato con '<field>' field contains non-float values.
  • Controlli della struttura di incorporamento sparso. Per ogni vettore sparso:
    • Deve essere un oggetto JSON.
    • Deve contenere entrambi gli array: values (numeri in virgola mobile) e indices (numeri interi lunghi); nella v1 questi sono values e dimensions.
    • values non deve essere vuoto.
    • Gli indici devono essere non negativi.
    • values.length deve essere uguale a indices.length (o v1 dimensions.length).
  • Tipo di campo data.Se presente, data deve essere un oggetto JSON, non un array, una stringa o uno scalare. In caso contrario: 'data' field is not a JSON object.
  • Forma numeric_restricts (formato v1). numeric_restricts deve essere un array JSON di oggetti. Ogni voce deve avere una stringa namespace e deve impostare esattamente uno tra value_int, value_float o value_double.

La maggior parte dei problemi di "primo errore" si verifica in questa fase. Gli errori comuni includono un numero in formato stringa in un array di incorporamento, un id mancante o values/indices di lunghezze diverse.

2. Convalide dell'identità

Gli ID oggetto dati devono essere conformi a RFC 1035. In pratica, questo significa che:

  • Lunghezza compresa tra 1 e 63 caratteri.
  • Solo lettere minuscole, cifre e trattini (-). Nessuna lettera maiuscola, nessun trattino basso, nessun spazio, nessun simbolo, nessun carattere Unicode.
  • Deve iniziare con una lettera minuscola (a-z).
  • Deve terminare con una lettera minuscola o una cifra (nessun - finale).

Espressione regolare: [a-z]([-a-z0-9]{0,61}[a-z0-9])?

La seguente tabella mostra alcuni esempi comuni:

ID Valido? Perché
doc-123 Sì Inizia con una lettera, solo lettere minuscole + cifre + trattino, termina con una cifra
a Sì È richiesta almeno una lettera minuscola
product-sku-42 Sì Tutte le regole soddisfatte
Doc-123 No D in maiuscolo non consentito
123-doc No Deve iniziare con una lettera, non con una cifra
doc_123 No Il carattere di sottolineatura non è consentito
doc-123- No Non può terminare con un trattino
my doc No Gli spazi non sono consentiti
64+ caratteri No La lunghezza massima è 63

Questa forma è la regola dell'etichetta DNS (la parte tra i punti in un nome host come my-service.example.com). Viene riutilizzata qui in modo che gli ID vengano trasferiti in modo sicuro tramite URL, nomi file, log e CLI senza escape.

3. Convalide dei campi di dati (schema JSON)

La fase di convalida del campo dati viene eseguita solo se la raccolta ha un dataSchema dichiarato nel relativo CollectionConfig. Se non è configurato alcuno schema, questa fase viene ignorata.

  • Conformità dello schema. Il payload data dell'oggetto dati viene serializzato in JSON e convalidato in base allo schema JSON configurato (bozza 7). Il validator segnala un errore per ogni violazione dello schema, quindi un record con tre campi non validi genera tre messaggi di errore.
    • Messaggio: DataObject with id <id> failed schema validation: <error>.
  • Errori di elaborazione dello schema.Se lo strumento di convalida dello schema genera un errore (ad esempio, funzionalità bozza non supportate), il record viene rifiutato con DataObject with id <id> failed schema validation processing: <exception>.

4. Convalide dei campi di incorporamento

La fase di convalida del campo di incorporamento scorre prima i vettori densi e poi quelli sparsi. Un unico insieme condiviso di nomi di vettori visualizzati si estende a entrambi gli elenchi, quindi un nome non può essere utilizzato due volte, nemmeno tra il limite denso e quello sparso.

Regole condivise (si applicano sia a quelle dense che a quelle sparse)

Regola Perché è importante Messaggio di errore
Nessun nome di vettore duplicato tra denso e sparso per lo stesso oggetto di dati Due voci con lo stesso nome di vettore avrebbero come target la stessa chiave di archiviazione, producendo un comportamento di priorità dell'ultima scrittura non definito ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
Vector name must be declared nello schema del vettore CollectionConfig Un nome vettore sconosciuto non può essere indirizzato a una colonna ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Regole solo per vettori densi

Regola Messaggio di errore
Il campo deve essere configurato come dense nello schema della raccolta. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
La dimensione deve corrispondere a quella configurata. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Tutti i valori devono essere finiti: non sono ammessi NaN, +Infinity o -Infinity. I valori non finiti danneggerebbero i calcoli della distanza. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Regole solo per vettori sparsi

Regola Messaggio di errore
Il campo deve essere configurato come sparse nello schema della raccolta. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Parità di lunghezza di indici/valori: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Indici non negativi: ogni indice >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Indici univoci all'interno dello stesso vettore sparso. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Tutti i valori devono essere finiti. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

5. Searchable-fields population

Una volta superata la convalida dell'incorporamento, la pipeline analizza il payload data utilizzando dataSchema della raccolta e copia i campi dichiarati dallo schema (stringa, numero intero/numero, booleano, array di stringhe e oggetti nidificati) in un indice di campi ricercabili. Anche due modalità di errore qui rifiuteranno un record:

  • Un percorso che dovrebbe essere una struttura contiene uno scalare (ad esempio, lo schema indica che author.name è una stringa, ma author è una stringa nel documento).
  • Un campo di array di stringhe contiene un elemento non stringa.

In genere indicano che la forma del documento si è discostata dallo schema dichiarato e non vengono sempre rilevati nella fase dello schema JSON.

Elenco di controllo pre-volo

Prima di avviare un'importazione o la creazione di un indice, convalida l'intero set di dati in base alle seguenti regole. Si tratta dello stesso insieme di controlli applicati dalla pipeline, ordinati in modo che un singolo passaggio lato client mostri ogni problema:

  1. Formato: ogni riga viene analizzata come JSON e corrisponde alla forma predefinita o v1.
  2. ID: corrispondono all'espressione regolare RFC 1035 [a-z]([-a-z0-9]{0,61}[a-z0-9])? e sono univoci nel set di dati.
  3. Embedding presenti: almeno un vettore per record; i nomi dei vettori sono elencati nello schema dei vettori CollectionConfig con il tipo dense o sparse corretto.
  4. Vettori densi: dimensione corretta; nessun valore NaN, +Inf o -Inf.
  5. Vettori sparsi: values.length == indices.length; tutti gli indici maggiori o uguali a 0 e univoci. I valori non finiti non sono consentiti.
  6. Nessun nome di vettore duplicato all'interno di un record in formato compatto e sparso.
  7. Schema dei dati: se è configurato un dataSchema, il payload data viene convalidato in base a questo schema (bozza 7) e il tipo JSON effettivo di ogni campo corrisponde al tipo dichiarato (in particolare per oggetti nidificati e array di stringhe).
  8. v1 numeric_restricts: ogni voce ha una stringa namespace e esattamente uno dei valori value_int / value_float / value_double.

Crea un oggetto dati

L'esempio seguente mostra l'aggiunta di un singolo oggetto dati a una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • DATA_FILE: il percorso locale di un file JSON contenente la parte di dati dell'oggetto dati.

    Esempio di contenuti del file:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: il percorso locale di un file JSON contenente i vettori che fanno parte dell'oggetto dati.

    Esempio di contenuti del file:

    {
  "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: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Dovresti ricevere una risposta simile alla seguente:

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)

I campi di incorporamento specificati nello schema della raccolta vengono compilati automaticamente. Puoi anche utilizzare i tuoi incorporamenti (BYOE) per impostare i valori dei campi vettoriali che non vengono compilati automaticamente.

Creare oggetti di dati in batch

Per l'importazione collettiva efficiente di un numero ridotto di record (fino a 1000 oggetti dati per richiesta), utilizza batchCreate. L'intero batch è atomico: vengono creati tutti gli oggetti dati o l'intera richiesta non va a buon fine. Per set di dati più grandi, preferisci l'importazione di oggetti dati da Cloud Storage.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Recupero di un oggetto di dati

L'esempio seguente mostra come ottenere un oggetto dati con l'ID DATA_OBJECT_ID da una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Dovresti ricevere una risposta simile alla seguente:

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)

Aggiorna un oggetto di dati

L'esempio seguente mostra come aggiornare il campo dati title e i valori dei vettori plot_embedding nell'oggetto dati con ID DATA_OBJECT_ID in una raccolta con ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Dovresti ricevere una risposta simile alla seguente:

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)

Aggiornamento batch degli oggetti dati

Per aggiornare più oggetti dati contemporaneamente, utilizza batchUpdate. In un singolo batch è possibile aggiornare un massimo di 1000 oggetti dati. Ogni richiesta per record specifica dataObject (che deve includere la risorsa completa name più i campi che vuoi modificare) e un updateMask che elenca i campi da sovrascrivere. I campi non elencati nella maschera rimangono invariati.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{}

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Importa oggetti dati

Il seguente esempio mostra come importare oggetti dati da Cloud Storage in una raccolta con l'ID COLLECTION_ID. Utilizza l'importazione per set di dati di grandi dimensioni; per importazioni collettive più piccole (fino a 1000 record), valuta la possibilità di creare oggetti dati in batch.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

La cartella gs://your-bucket/path/to/your-data/ può contenere uno o più file ognuno contenente più oggetti dati. Utilizza questa struttura per set di dati di grandi dimensioni distribuiti su più file. In Recupero dell'agente sono supportati i seguenti formati di file:

  • JSONL, in cui ogni riga è un oggetto JSON con tre proprietà di primo livello: id, data e vectors. Utilizza questo formato per i nuovi set di dati di recupero dell'agente quando vuoi un input leggibile da una persona per l'ispezione e la modifica manuale.
  • AVRO: utilizza questo formato per i nuovi set di dati di recupero degli agenti quando hai bisogno di un formato binario compatto e con schema convalidato, in genere per set di dati di grandi dimensioni prodotti da strumenti per pipeline di dati come Dataflow, Beam o Spark.
  • JSON di ricerca vettoriale: utilizza questo formato solo quando esegui la migrazione di un set di dati JSON di ricerca vettoriale (ricerca vettoriale 1.0) esistente e vuoi riutilizzarlo così com'è.
  • AVRO per la ricerca vettoriale: utilizza questo formato solo quando esegui la migrazione di un set di dati AVRO esistente di Vector Search (Vector Search 1.0) e vuoi riutilizzarlo così com'è.

Di seguito è riportato un esempio di JSONL con le proprietà richieste.

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

Per i file AVRO, ogni record deve essere conforme allo schema Avro DataObject mostrato. I campi rispecchiano il formato JSONL:

  • id (obbligatorio string).
  • vectors (map, valore predefinito {}). Ogni voce è indicizzata in base al nome del vettore e il suo valore è un array di float (vettore denso) o un record SparseVector con values (array di float) e indices (array di long).
  • data (map annullabile, valore predefinito null). Le chiavi sono i nomi dei campi di dati. Ogni valore è un record DataValue il cui campo value è un'unione dei tipi primitivi supportati (boolean, int, long, float, double, string) più array di DataValue e map di string a DataValue per le strutture nidificate.
  • etag (accetta valori null string, valore predefinito 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
    }
  ]
}

Il seguente snippet mostra i contenuti concettuali di un singolo record AVRO che corrisponde all'esempio JSONL precedente. Tieni presente che in questo schema ogni voce in data è racchiusa in un record DataValue (con un singolo campo value), che è il modo in cui AVRO rappresenta i tipi eterogenei in data:

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

Esporta oggetti di dati

L'esempio seguente mostra come esportare ogni oggetto dati in una raccolta in Cloud Storage in formato JSONL. Il bucket di destinazione deve trovarsi nella stessa regione della raccolta. L'esportazione è un'operazione a lunga esecuzione.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Eliminare un oggetto dati

L'esempio seguente mostra come eliminare un singolo oggetto dati DATA_OBJECT_ID da una raccolta con l'ID COLLECTION_ID.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • DATA_OBJECT_ID: l'ID dell'oggetto dati.
  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Dovresti ricevere una risposta simile alla seguente:

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)

Eliminazione batch degli oggetti di dati

Per eliminare più oggetti dati contemporaneamente, utilizza batchDelete con un elenco di nomi delle risorse degli oggetti dati completi. È possibile eliminare un massimo di 1000 oggetti di dati in un singolo batch.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{}

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Conteggio oggetti di dati

Per conteggiare quanti oggetti dati contiene una raccolta, utilizza l'operazione aggregate con il metodo di aggregazione COUNT. La stessa chiamata accetta un'espressione di filtro JSON facoltativa, in modo da poter conteggiare solo gli oggetti dati che corrispondono a un predicato (ad esempio, genre == "sci-fi").

Per conteggiare ogni oggetto dati nella raccolta, ometti il filtro.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • COLLECTION_ID: l'ID della raccolta.
  • LOCATION: la regione in cui utilizzi Agent Platform.
  • PROJECT_ID: il tuo Google Cloud ID progetto.

Esegui questo comando:

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

Passaggi successivi