Objek Data

Di Pengambilan Agen (sebelumnya Vector Search 2.0), Kumpulan Data menyimpan data sebagai objek JSON individual yang disebut Objek Data. Halaman ini menjelaskan aturan validasi yang harus dipenuhi Objek Data, dan cara membuat, membaca, memperbarui, mengimpor, mengekspor, dan menghapus Objek Data satu per satu atau dalam batch.

Validasi data

Pengambilan Agen (sebelumnya Vector Search 2.0) memvalidasi setiap Objek Data sebelum menyimpannya. Validasi terjadi dalam dua konteks yang menerapkan aturan inti yang sama, tetapi berbeda dalam cara kegagalan dilaporkan:

Konteks Berlaku untuk Perilaku saat terjadi kegagalan
Validasi Objek Data Operasi tulis individu dan batch: create, batchCreate, update, dan batchUpdate Permintaan akan langsung gagal dengan INVALID_ARGUMENT. Operasi tulis batch bersifat atomik: jika ada kumpulan data yang tidak valid, tidak ada kumpulan data dalam permintaan yang ditulis.
Validasi impor import dari Cloud Storage Setiap data divalidasi secara terpisah. Kumpulan data yang tidak valid ditulis ke sink error dengan code = INVALID_ARGUMENT dan dilewati, dan impor lainnya akan dilanjutkan. Setelah suatu catatan gagal dalam pemeriksaan, pemeriksaan berikutnya tidak dijalankan untuk catatan tersebut.

Kedua konteks menerapkan aturan inti yang sama: aturan ID, aturan kolom data (saat Kumpulan Data mendeklarasikan dataSchema), dan aturan penyematan. Impor tambahan mengurai setiap data dan mengekstraksi kolom yang dapat ditelusuri, karena inputnya adalah file mentah, bukan permintaan API terstruktur.

Untuk menghindari loop "perbaiki satu error, muat ulang, temukan error berikutnya", validasi set data Anda terhadap semua aturan berikut sebelum Anda memulai impor atau pembuatan indeks.

Penguraian (khusus impor)

Penguraian hanya berlaku untuk impor, yang mengubah setiap baris atau rekaman input mentah menjadi Objek Data internal. Penulisan API perorangan dan batch melewati langkah ini karena inputnya sudah terstruktur. Penguraian menangani kedua bentuk JSON yang didukung: format default (dengan objek vectors/data tingkat teratas) dan format v1 (dengan embedding, sparse_embedding, restricts, atau numeric_restricts). Format terdeteksi otomatis per data.

  • JSON harus dapat diuraikan. Setiap baris harus diuraikan sebagai objek JSON. Baris yang kunci tingkat atasnya tidak cocok dengan format default maupun v1 akan ditolak dengan Unknown JSON format for string: <line>.
  • id wajib diisi. Setiap data harus berisi id yang tidak boleh null. Jika tidak: 'id' field is missing or null.
  • Penyematan harus ada (hanya format v1). Rekaman format v1 harus berisi setidaknya salah satu dari embedding atau sparse_embedding. Jika tidak: 'embedding' or 'sparse_embedding' fields are missing.
  • Pemeriksaan jenis sematan padat. Kolom sematan padat (embedding di v1, atau nilai array apa pun di vectors dalam format default) harus berupa array JSON angka. Nilai yang tidak dapat dikonversi menjadi float akan ditolak dengan '<field>' field contains non-float values.
  • Pemeriksaan struktur embedding renggang. Untuk setiap vektor renggang:
    • Harus berupa objek JSON.
    • Harus berisi kedua array: values (float) dan indices (long); di v1, array ini adalah values dan dimensions.
    • values tidak boleh kosong.
    • Indeks tidak boleh negatif.
    • values.length harus sama dengan indices.length (atau dimensions.length v1).
  • Jenis kolom data. Jika ada, data harus berupa objek JSON, bukan array, string, atau skalar. Atau: 'data' field is not a JSON object.
  • numeric_restricts bentuk (format v1). numeric_restricts harus berupa array objek JSON. Setiap entri harus memiliki string namespace dan harus menetapkan tepat satu dari value_int, value_float, atau value_double.

Sebagian besar masalah "kegagalan pertama" berasal dari tahap ini. Kesalahan umum mencakup angka yang di-stringifikasi dalam array sematan, id yang tidak ada, atau values/indices dengan panjang yang berbeda.

Aturan ID

ID Objek Data harus berisi antara 1 dan 63 karakter. Panjang adalah satu-satunya batasan yang diterapkan Agent Retrieval pada ID; semua karakter diterima.

Tabel berikut menunjukkan contoh umum:

ID Valid? Mengapa
movie-789 Ya Antara 1 dan 63 karakter
a Ya Satu karakter adalah minimum
Doc_123 Ya Huruf besar dan garis bawah diperbolehkan
my doc Ya Karakter apa pun diterima, dalam batas panjang
(string kosong) Tidak Diperlukan minimal satu karakter
64 karakter atau lebih Tidak Panjang maksimum adalah 63

Aturan kolom data (Skema JSON)

Validasi kolom data hanya berjalan jika Koleksi mendeklarasikan dataSchema di CollectionConfig-nya. Jika tidak ada skema yang dikonfigurasi, pemeriksaan ini akan dilewati.

  • Kepatuhan terhadap skema. Payload data Objek Data diserialisasi ke JSON dan divalidasi terhadap Skema JSON yang dikonfigurasi (Draf 7). Validator melaporkan satu error per pelanggaran skema, sehingga satu rekaman dengan tiga kolom yang salah akan menghasilkan tiga pesan error.
    • Pesan: DataObject with id <id> failed schema validation: <error>.
  • Error pemrosesan skema. Jika validator skema itu sendiri menampilkan error (misalnya, fitur draf yang tidak didukung), rekaman akan ditolak dengan DataObject with id <id> failed schema validation processing: <exception>.

Aturan penyematan

Validasi penyematan melakukan iterasi terlebih dahulu pada vektor padat, lalu vektor jarang. Satu set nama vektor yang terlihat bersama mencakup kedua daftar, sehingga nama tidak dapat digunakan dua kali -- bahkan di seluruh batas padat dan jarang.

Aturan bersama (berlaku untuk padat dan jarang)

Aturan Mengapa hal ini penting Pesan error
Tidak ada nama vektor duplikat di seluruh vektor padat dan jarang untuk Objek Data yang sama Dua entri dengan nama vektor yang sama akan menargetkan kunci penyimpanan yang sama, sehingga menghasilkan perilaku last-write-wins yang tidak ditentukan ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
Nama vektor harus dideklarasikan dalam skema vektor CollectionConfig Nama vektor yang tidak diketahui tidak dapat diarahkan ke kolom ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Aturan khusus vektor padat

Aturan Pesan error
Kolom harus dikonfigurasi sebagai padat dalam skema Kumpulan. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
Dimensi harus cocok dengan dimensi yang dikonfigurasi. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Semua nilai harus berhingga -- tidak ada NaN, +Infinity, atau -Infinity. Nilai non-finite akan merusak komputasi jarak. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Aturan khusus vektor jarang

Aturan Pesan error
Kolom harus dikonfigurasi sebagai sparse dalam skema Kumpulan. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Paritas panjang indeks/nilai: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Indeks non-negatif: setiap indeks >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Indeks unik dalam vektor renggang yang sama. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Semua nilai harus terbatas. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

Ekstraksi kolom yang dapat ditelusuri (khusus impor)

Selama impor, setelah validasi penyematan berhasil, pipeline menelusuri payload data menggunakan dataSchema Koleksi dan menyalin kolom yang dideklarasikan skema (string, bilangan bulat/angka, boolean, array string, dan objek bertingkat) ke dalam indeks kolom yang dapat ditelusuri. Dua mode kegagalan di sini juga akan menolak rekaman:

  • Jalur yang seharusnya berupa struktur berisi skalar (misalnya, skema mengatakan bahwa author.name adalah string, tetapi author itu sendiri adalah string dalam dokumen).
  • Kolom array string berisi elemen non-string.

Error ini biasanya menunjukkan bahwa bentuk dokumen telah menyimpang dari skema yang dideklarasikan dan tidak selalu terdeteksi pada tahap Skema JSON.

Checklist pra-penerbangan

Sebelum memulai penyerapan atau pembuatan indeks, validasi seluruh set data terhadap aturan berikut. Ini adalah kumpulan pemeriksaan yang sama yang diterapkan pipeline, diurutkan sehingga satu lintasan sisi klien memunculkan setiap masalah:

  1. Format -- setiap baris diuraikan sebagai JSON dan cocok dengan bentuk default atau v1.
  2. ID -- panjangnya antara 1 dan 63 karakter serta unik di seluruh set data.
  3. Embedding ada -- minimal satu vektor per rekaman; nama vektor tercantum dalam skema vektor CollectionConfig dengan jenis padat atau jarang yang benar.
  4. Vektor padat -- dimensi yang benar; tidak ada nilai NaN, +Inf, atau -Inf.
  5. Vektor sparse -- values.length == indices.length; semua indeks lebih besar atau sama dengan 0 dan unik. Nilai non-hingga tidak diizinkan.
  6. Tidak ada nama vektor duplikat dalam satu rekaman di seluruh data padat dan jarang.
  7. Skema data -- jika dataSchema dikonfigurasi, payload data Anda divalidasi terhadapnya (Draf 7), dan setiap jenis JSON aktual kolom cocok dengan jenis yang dinyatakan (terutama untuk objek bertingkat dan array string).
  8. v1 numeric_restricts -- setiap entri memiliki string namespace dan tepat satu dari value_int / value_float / value_double.

Membuat Objek Data

Contoh berikut menunjukkan penambahan satu Objek Data ke Koleksi dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • DATA_FILE: Jalur lokal ke file JSON yang berisi bagian data dari objek data.

    Contoh konten file:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: Jalur lokal ke file JSON yang berisi bagian vektor objek data.

    Contoh konten 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: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Anda akan melihat respons seperti berikut:

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)

Kolom yang memiliki penyematan otomatis yang ditentukan dalam Skema Kumpulan Data akan otomatis diisi. Anda juga dapat menggunakan embedding Anda sendiri (BYOE) untuk menetapkan nilai kolom vektor yang tidak diisi secara otomatis.

Membuat Objek Data secara Batch

Untuk penyerapan massal yang efisien dalam jumlah kecil (hingga 1.000 Objek Data per permintaan), gunakan batchCreate. Seluruh batch bersifat atomik: baik semua Objek Data dibuat, atau seluruh permintaan gagal. Untuk set data yang lebih besar, sebaiknya impor Objek Data dari Cloud Storage.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Mendapatkan Objek Data

Contoh berikut menunjukkan cara mendapatkan Objek Data dengan ID DATA_OBJECT_ID dari Kumpulan dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Anda akan melihat respons seperti berikut:

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)

Memperbarui Objek Data

Contoh berikut menunjukkan cara memperbarui kolom data title dan nilai vektor plot_embedding di Objek Data dengan ID DATA_OBJECT_ID dalam Kumpulan dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Anda akan melihat respons seperti berikut:

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)

Memperbarui Objek Data secara Batch

Untuk memperbarui banyak Objek Data sekaligus, gunakan batchUpdate. Maksimum 1.000 Objek Data dapat diperbarui dalam satu batch. Setiap permintaan per-data menentukan dataObject (yang harus menyertakan name resource lengkapnya ditambah kolom yang ingin Anda ubah) dan daftar updateMask yang mencantumkan kolom yang akan ditimpa. Kolom yang tidak tercantum dalam mask dibiarkan tidak berubah.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{}

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Mengimpor Objek Data

Contoh berikut menunjukkan cara mengimpor Objek Data dari Cloud Storage ke dalam Kumpulan dengan ID COLLECTION_ID. Gunakan impor untuk set data besar; untuk penyerapan massal yang lebih kecil (hingga 1.000 record), pertimbangkan untuk membuat Objek Data dalam batch.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Folder gs://your-bucket/path/to/your-data/ dapat berisi satu atau beberapa file, yang masing-masing berisi beberapa Objek Data. Gunakan struktur ini untuk set data besar yang tersebar di beberapa file. Format file berikut didukung di Agent Retrieval:

  • JSONL, dengan setiap baris adalah objek JSON yang memiliki tiga properti tingkat teratas: id, data, dan vectors. Gunakan format ini untuk set data Pengambilan Agen baru jika Anda menginginkan input yang mudah dibaca untuk diperiksa dan diedit secara manual.
  • AVRO: Gunakan format ini untuk set data Pengambilan Agen baru jika Anda memerlukan format biner yang ringkas dan divalidasi skemanya -- biasanya untuk set data besar yang dihasilkan oleh alat pipeline data seperti Dataflow, Beam, atau Spark.
  • JSON Vector Search: Gunakan format ini hanya saat Anda memigrasikan set data JSON Vector Search (Vector Search 1.0) yang ada dan ingin menggunakannya kembali apa adanya.
  • AVRO Vector Search: Gunakan format ini hanya saat Anda memigrasikan set data AVRO Vector Search (Vector Search 1.0) yang ada dan ingin menggunakannya kembali apa adanya.

JSONL

Contoh berikut menunjukkan format JSONL dengan properti yang diperlukan. Setiap baris dalam file input adalah satu Objek Data dengan properti id, data, dan vectors tingkat teratas.

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

Untuk file AVRO, setiap data harus sesuai dengan skema Avro DataObject yang ditampilkan. Kolom mencerminkan format JSONL:

  • id (wajib string).
  • vectors (map, {} default). Setiap entri diberi kunci berdasarkan nama vektor dan nilainya berupa array float (vektor padat) atau SparseVector dengan values (array float) dan indices (array long).
  • data (dapat bernilai null map, default null). Kuncinya adalah nama kolom data. Setiap nilai adalah rekaman DataValue yang kolom value-nya adalah gabungan dari jenis primitif yang didukung (boolean, int, long, float, double, string) ditambah array dari DataValue dan map dari string ke DataValue untuk struktur bertingkat.
  • etag (nullable string, default 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
    }
  ]
}

Cuplikan berikut menunjukkan konten konseptual satu rekaman AVRO yang cocok dengan contoh JSONL sebelumnya. Perhatikan bahwa dalam skema ini, setiap entri di data di-wrap dalam rekaman DataValue (dengan satu kolom value), yang merupakan cara AVRO merepresentasikan jenis heterogen di 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 }
      }
    }
  }
}

Mengekspor Objek Data

Contoh berikut menunjukkan cara mengekspor setiap Objek Data dalam Koleksi ke Cloud Storage dalam format JSONL. Bucket tujuan harus berada di region yang sama dengan Koleksi. Ekspor adalah operasi yang berjalan lama.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Menghapus Objek Data

Contoh berikut menunjukkan cara menghapus satu Objek Data DATA_OBJECT_ID dari Kumpulan dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • DATA_OBJECT_ID: ID objek data.
  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Anda akan melihat respons seperti berikut:

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)

Menghapus Objek Data secara Batch

Untuk menghapus banyak Objek Data sekaligus, gunakan batchDelete dengan daftar nama resource Objek Data yang sepenuhnya memenuhi syarat. Maksimum 1.000 Objek Data dapat dihapus dalam satu batch.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{}

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Menghitung Objek Data

Untuk menghitung jumlah Objek Data yang ada dalam Koleksi, gunakan operasi aggregate dengan metode agregasi COUNT. Panggilan yang sama menerima ekspresi filter JSON opsional sehingga Anda hanya dapat menghitung Objek Data yang cocok dengan predikat (misalnya, genre == "sci-fi").

Untuk menghitung setiap Objek Data dalam Kumpulan, hapus filter.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • COLLECTION_ID: ID koleksi.
  • LOCATION: Region tempat Anda menggunakan Agent Platform.
  • PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

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

Apa langkah selanjutnya?