Oggetti dati

In Agent Retrieval (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

Agent Retrieval (in precedenza Vector Search 2.0) convalida ogni oggetto dati prima di archiviarlo. La convalida avviene in due contesti che applicano le stesse regole di base, ma differiscono nel modo in cui vengono segnalati gli errori:

Contesto Applicabile a Comportamento in caso di errore
Convalida dell'oggetto dati Scritture individuali e batch: create, batchCreate, update e batchUpdate La richiesta non riesce immediatamente con INVALID_ARGUMENT. Le scritture batch sono atomiche: se un record non è valido, non viene scritto alcun record nella richiesta.
Convalida dell'importazione import da Cloud Storage Ogni record viene convalidato in modo indipendente. Un record non valido viene scritto nel sink degli errori con code = INVALID_ARGUMENT e ignorato e il resto dell'importazione continua. Una volta che un record non supera un controllo, i controlli successivi non vengono eseguiti.

Entrambi i contesti applicano le stesse regole di base: regole ID, regole dei campi di dati (quando la raccolta dichiara un dataSchema) e regole di incorporamento. Importa inoltre analizza ogni record ed estrae i campi ricercabili, perché l'input sono file non elaborati anziché richieste API strutturate.

Per evitare un ciclo di "correggi un errore, esegui nuovamente l'importazione, riscontri l'errore successivo", convalida il set di dati in base a tutte le regole riportate di seguito prima di avviare un'importazione o la creazione di un indice.

Analisi (solo importazione)

L'analisi si applica solo all'importazione, che trasforma ogni riga o record di input non elaborato in un oggetto dati interno. Le scritture API individuali e batch saltano questo passaggio perché l'input è già strutturato. L'analisi gestisce entrambe le forme JSON supportate: il formato predefinito (con un oggetto vectors/data di primo livello) e il formato v1 (con embedding, sparse_embedding, restricts o numeric_restricts). Il formato viene rilevato automaticamente per ogni record.

  • Il JSON deve essere analizzabile. Ogni riga deve essere analizzata come oggetto JSON. Una riga le cui chiavi di primo livello non corrispondono né al formato predefinito né a quello v1 viene rifiutata con Unknown JSON format for string: <line>.
  • id è obbligatorio. Ogni record deve contenere un id non nullo. Altrimenti: '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 in v1 o qualsiasi valore di array in vectors nel formato predefinito) deve essere un array JSON di numeri. Un valore che non può essere forzato 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. Altrimenti: '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.

Regole ID

Un ID oggetto dati deve essere compreso tra 1 e 63 caratteri. La lunghezza è l'unico vincolo che Agent Retrieval impone a un ID; tutti i caratteri sono accettati.

La seguente tabella mostra alcuni esempi comuni:

ID Valido? Perché
movie-789 Sì Da 1 a 63 caratteri
a Sì Il minimo è un solo carattere
Doc_123 Sì Sono consentite lettere maiuscole e trattini bassi
my doc Sì Qualsiasi carattere è accettato, entro il limite di lunghezza
(stringa vuota) No È richiesto almeno un carattere
64 caratteri o più No La lunghezza massima è 63

Regole dei campi di dati (schema JSON)

La convalida del campo dati viene eseguita solo se la raccolta dichiara un dataSchema nel relativo CollectionConfig. Se non è configurato alcuno schema, questo controllo viene ignorato.

  • 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 il validatore 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>.

Regole di incorporamento

La convalida dell'incorporamento viene eseguita prima sui vettori densi e poi su 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 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
Il nome del vettore deve essere dichiarato 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, quindi non devono essere 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)

Estrazione dei campi ricercabili (solo importazione)

Durante l'importazione, dopo la convalida dell'incorporamento, la pipeline percorre 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 uno struct 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: hanno una lunghezza compresa tra 1 e 63 caratteri e sono univoci nel set di dati.
  3. Embedding presenti: almeno un vettore per record; i nomi dei vettori sono elencati nello schema vettoriale CollectionConfig con il tipo denso o sparso 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 con un incorporamento automatico specificato 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 in batch oggetti di dati

Per l'importazione collettiva efficiente di un numero ridotto di record (fino a 1000 oggetti di dati per richiesta), utilizza batchCreate. L'intero batch è atomico: o vengono creati tutti gli oggetti dati oppure l'intera richiesta non va a buon fine. Per i set di dati più grandi, preferisci importare gli 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 molti oggetti di dati contemporaneamente, utilizza batchUpdate. È possibile aggiornare un massimo di 1000 oggetti di dati in un singolo batch. 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 di dati

Il seguente esempio mostra come importare gli oggetti dati da Cloud Storage in una raccolta con l'ID COLLECTION_ID. Utilizza l'importazione per i 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'è.

JSONL

L'esempio seguente mostra il formato JSONL con le proprietà richieste. Ogni riga del file di input è un singolo oggetto dati con le proprietà di primo livello id, data e vectors.

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

AVRO

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 (accetta valori nulli map, 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