在 Agent Retrieval (舊稱 Vector Search 2.0) 中，集合會將資料儲存為稱為「資料物件」的個別 JSON 物件。本頁面說明資料物件必須符合的驗證規則，以及如何個別或批次建立、讀取、更新、匯入、匯出及刪除資料物件。
資料驗證
Agent Retrieval (舊稱 Vector Search 2.0) 會先驗證每個資料物件，再儲存。驗證會在兩種情境中進行，這兩種情境會強制執行相同的核心規則，但回報失敗的方式不同：
| 背景資訊 | 套用對象 | 失敗時的行為 |
|---|---|---|
| 資料物件驗證 | 個別和批次寫入：create、batchCreate、update 和 batchUpdate |
要求會立即失敗並顯示 INVALID_ARGUMENT。批次寫入作業具有不可分割的特性：如果任何記錄無效，系統就不會寫入要求中的任何記錄。 |
| 匯入驗證 | import 從 Cloud Storage |
系統會分別驗證每筆記錄。無效記錄會寫入錯誤接收器 (使用 code = INVALID_ARGUMENT)，並略過該記錄，但匯入作業會繼續進行。如果記錄未通過檢查，系統不會再對該記錄執行檢查。 |
這兩種情境都會強制執行相同的核心規則：ID 規則、資料欄位規則 (當集合宣告 dataSchema 時) 和嵌入規則。因為輸入內容是原始檔案，而非結構化 API 要求，所以匯入作業會剖析每筆記錄，並擷取可搜尋的欄位。
為避免「修正一個錯誤、重新擷取、遇到下一個錯誤」的迴圈，請先根據下列所有規則驗證資料集，再開始匯入或建立索引。
剖析 (僅限匯入)
剖析只適用於匯入，可將每個原始輸入行或記錄轉換為內部資料物件。個別和批次 API 寫入作業會略過這個步驟，因為輸入內容已結構化。剖析作業會處理兩種支援的 JSON 形狀：預設格式 (含有頂層 vectors/data 物件) 和 v1 格式 (含有 embedding、sparse_embedding、restricts 或 numeric_restricts)。系統會為每筆記錄自動偵測格式。
- JSON 必須可剖析。每行都必須剖析為 JSON 物件。如果某行的頂層鍵既不符合預設格式，也不符合 v1 格式，系統會拒絕該行並顯示
Unknown JSON format for string: <line>。 id為必填欄位。每筆記錄都必須包含非空值的id。否則：'id' field is missing or null。- 必須提供嵌入內容 (僅限 v1 格式)。v1 格式的記錄必須包含至少一個
embedding或sparse_embedding。否則：'embedding' or 'sparse_embedding' fields are missing。 - 稠密嵌入類型檢查。密集嵌入欄位 (v1 中的
embedding，或預設格式中vectors下的任何陣列值) 必須是數字的 JSON 陣列。無法強制轉換為float的值會遭到拒絕，並顯示'<field>' field contains non-float values。 - 稀疏嵌入結構檢查。針對每個稀疏向量：
- 必須是 JSON 物件。
- 必須包含兩個陣列：
values(浮點數) 和indices(長整數)；在第 1 版中，這些是values和dimensions。 - 「
values」不得留空。 - 索引不得為負數。
values.length必須等於indices.length(或 v1dimensions.length)。
data欄位類型。如果有的話，data必須是 JSON 物件，而非陣列、字串或純量。否則請說出「'data' field is not a JSON object」。numeric_restricts形狀 (v1 格式)。numeric_restricts必須是物件的 JSON 陣列。每個項目都必須有字串namespace，且只能設定value_int、value_float或value_double其中一個。
大多數「首次失敗」問題都發生在這個階段。常見錯誤包括嵌入陣列中的字串化數字、缺少 id，或 values/indices 長度不同。
ID 規則
資料物件 ID 長度必須介於 1 至 63 個字元之間。長度是 Agent Retrieval 對 ID 施加的唯一限制，所有字元都可接受。
下表列出常見範例：
| ID | 是否有效？ | 原因 |
|---|---|---|
movie-789 |
是 | 長度介於 1 至 63 個字元之間 |
a |
是 | 至少須輸入一個字元 |
Doc_123 |
是 | 可以使用大寫字母和底線 |
my doc |
是 | 接受任何字元，但須符合長度限制 |
| (空字串) | 否 | 至少須輸入一個字元 |
| 64 個字元以上 | 否 | 長度上限為 63 個字元 |
資料欄位規則 (JSON 結構定義)
只有在 Collection 的 CollectionConfig 中宣告 dataSchema 時，系統才會執行資料欄位驗證。如果未設定任何結構定義，系統會略過這項檢查。
- 結構定義遵循狀態。資料物件的
data酬載會序列化為 JSON，並根據設定的 JSON 結構定義 (草案 7) 進行驗證。驗證器會針對每項結構定義違規情形回報一個錯誤，因此如果記錄有三個無效欄位，就會產生三則錯誤訊息。- 訊息：
DataObject with id <id> failed schema validation: <error>。
- 訊息：
- 結構定義處理錯誤。如果結構定義驗證器本身擲回 (例如不支援的草稿功能)，系統會拒絕記錄並顯示
DataObject with id <id> failed schema validation processing: <exception>。
嵌入規則
嵌入驗證會先疊代密集向量，再疊代稀疏向量。兩個清單共用一組已查看的向量名稱，因此名稱不得重複使用，即使是跨越密集和稀疏邊界也一樣。
共用規則 (適用於密集和稀疏)
| 規則 | 重要性解析 | 錯誤訊息 |
|---|---|---|
| 同一資料物件的密集和稀疏向量名稱不得重複 | 如果兩個項目的向量名稱相同，就會以相同的儲存空間金鑰為目標，產生未定義的最後寫入者勝出行為 | ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once |
必須在 CollectionConfig 向量結構定義中宣告向量名稱 |
不明向量名稱無法路由至資料欄 | ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema |
僅限稠密向量的規則
| 規則 | 錯誤訊息 |
|---|---|
| 這個欄位必須在集合結構定義中設定為「dense」。 | ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense |
| 維度必須與設定的維度相符。 | ... field '<name>': expected dense embedding dimension <expected>, but got <actual> |
所有值都必須是有限值，不得為 NaN、+Infinity 或 -Infinity。非有限值會破壞距離計算。 |
... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed) |
僅限稀疏向量的規則
| 規則 | 錯誤訊息 |
|---|---|
| 欄位必須在集合結構定義中設定為 sparse。 | ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse |
索引/值長度同位檢查：indicesCount == valuesCount。 |
... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length |
| 非負數索引：每個索引 >= 0。 | ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative) |
| 同一個稀疏向量中的不重複索引。 | ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once) |
| 所有值都必須是有限值。 | ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed) |
擷取可搜尋的欄位 (僅限匯入)
在匯入期間，嵌入驗證成功後，管道會使用集合的 dataSchema 走訪 data 酬載，並將架構宣告的欄位 (字串、整數/數字、布林值、字串陣列和巢狀物件) 複製到可搜尋的欄位索引。以下兩種故障模式也會拒絕記錄：
- 路徑應為結構體，但包含純量 (例如，結構定義說
author.name是字串，但author本身是文件中的字串)。 - 字串陣列欄位包含非字串元素。
這通常表示文件的形狀已偏離宣告的結構定義，且不一定會在 JSON 結構定義階段遭到攔截。
準備檢查清單
開始擷取或建立索引前，請根據下列規則驗證整個資料集。這與管道套用的檢查相同，但順序經過調整，因此單一用戶端傳遞會顯示每個問題：
- 格式：每行都會剖析為 JSON，並符合預設或 v1 形狀。
- ID：長度介於 1 至 63 個字元之間，且在資料集中不得重複。
- 嵌入呈現 - 每筆記錄至少一個向量；向量名稱會列在
CollectionConfig向量結構定義中，並具有正確的密集或稀疏類型。 - 密集向量：維度正確，沒有
NaN、+Inf或-Inf值。 - 稀疏型向量 -
values.length == indices.length；所有索引皆大於或等於 0，且不得重複。不允許使用非有限值。 - 在密集和稀疏的記錄中，向量名稱不得重複。
- 資料結構定義：如果已設定
dataSchema，系統會根據該結構定義 (草案 7) 驗證data酬載，且每個欄位的實際 JSON 類型都會與宣告的類型相符 (尤其是巢狀物件和字串陣列)。 - v1
numeric_restricts- 每個項目都有字串namespace，以及value_int/value_float/value_double其中之一。
建立資料物件
以下範例示範如何將單一資料物件新增至 ID 為 COLLECTION_ID 的集合。
REST
使用任何要求資料之前，請先修改下列項目的值：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID
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 ]
}
}
}
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
-
DATA_FILE：包含資料物件資料部分的 JSON 檔案本機路徑。
檔案內容範例：
{ "director": "Frank Darabont", "genre": "Drama", "title": "The Shawshank Redemption", "year": 1994 }
-
VECTORS_FILE：包含資料物件向量部分的 JSON 檔案本機路徑。
檔案內容範例：
{ "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。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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
您應該會收到類似以下的回應：
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)
系統會自動填入在集合架構中指定自動嵌入的欄位。您也可以自備嵌入 (BYOE)，設定系統不會自動填入的向量欄位值。
批次建立資料物件
如要有效率地大量擷取少量記錄 (每個要求最多 1000 個資料物件)，請使用 batchCreate。整個批次是不可分割的：要不是建立所有資料物件，就是整個要求失敗。如果是較大的資料集，建議從 Cloud Storage 匯入資料物件。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchCreate
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] }
}
}
}
}
]
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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)
取得資料物件
以下範例說明如何從 ID 為 COLLECTION_ID 的集合中，取得 ID 為 DATA_OBJECT_ID 的資料物件。
REST
使用任何要求資料之前，請先修改下列項目的值：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
GET https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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
您應該會收到類似以下的回應：
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)
更新資料物件
以下範例說明如何更新 ID 為 COLLECTION_ID 的集合中，ID 為 DATA_OBJECT_ID 的資料物件中的 title 資料欄位和 plot_embedding 向量值。
REST
使用任何要求資料之前，請先修改下列項目的值：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
PATCH https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
JSON 要求主體：
{
"data": {
"title": "The Shawshank Redemption (updated)"
},
"vectors": {
"plot_embedding": {
"dense": {
"values": [
1.0,
1.0,
1.0
]
}
}
}
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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]}}}'
您應該會收到類似以下的回應：
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)
批次更新資料物件
如要一次更新多個資料物件，請使用 batchUpdate。單一批次最多可更新 1,000 個資料物件。每項記錄要求都會指定 dataObject (必須包含完整資源 name，以及要變更的欄位)，並列出要覆寫的欄位 updateMask。遮罩中未列出的欄位則保持不變。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchUpdate
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"
}
]
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{}
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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)
匯入資料物件
以下範例說明如何將 Cloud Storage 中的資料物件匯入 ID 為 COLLECTION_ID 的集合。如要匯入大型資料集，請使用匯入功能；如要大量匯入較小的資料集 (最多 1000 筆記錄)，請考慮批次建立資料物件。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:importDataObjects
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/"
}
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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()
資料夾 gs://your-bucket/path/to/your-data/ 可包含一或多個檔案，每個檔案都包含多個資料物件。如果大型資料集分散在多個檔案中，請使用這個結構。
Agent Retrieval 支援下列檔案格式：
- JSONL，其中每行都是一個 JSON 物件，具有三個頂層屬性：
id、data和vectors。如要手動檢查及編輯，請使用這種格式建立新的 Agent Retrieval 資料集。 - AVRO：如果需要經過結構定義驗證的精簡二進位格式，請使用這個格式建立新的 Agent Retrieval 資料集，通常適用於由 Dataflow、Beam 或 Spark 等資料管道工具產生的大型資料集。
- 向量搜尋 JSON：只有在遷移現有的向量搜尋 (向量搜尋 1.0) JSON 資料集，並想直接重複使用時，才使用這個格式。
- Vector Search AVRO：只有在遷移現有的 Vector Search (Vector Search 1.0) AVRO 資料集，並想直接重複使用時，才使用這個格式。
JSONL
下列範例顯示 JSONL 格式，其中包含必要屬性。輸入檔中的每一行都是單一資料物件，具有頂層的 id、data 和 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
如果是 AVRO 檔案，每筆記錄都必須符合顯示的 DataObject Avro 結構定義。這些欄位會反映 JSONL 格式：
id(必要string)。vectors(map，預設為{})。每個項目都以向量名稱做為鍵，值則為array的float(密集向量) 或具有values(float陣列) 和indices(long陣列) 的SparseVector記錄。data(可為空值map，預設值為null)。鍵是資料欄位名稱。每個值都是DataValue記錄，其value欄位是支援的原始型別 (boolean、int、long、float、double、string) 的聯集，加上array的DataValue和map的string至DataValue，適用於巢狀結構。etag(可為空值string，預設值為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
}
]
}
下列程式碼片段顯示單一 AVRO 記錄的概念內容，與先前的 JSONL 範例相符。請注意，在這個結構定義下，data 中的每個項目都會包裝在 DataValue 記錄中 (只有一個欄位)，這就是 AVRO 在 data 中表示異質類型的方式：value
{
"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 }
}
}
}
}
匯出資料物件
以下範例說明如何將集合中的每個資料物件匯出至 Cloud Storage，並採用 JSONL 格式。目的地 bucket 必須與集合位於相同區域。匯出作業是長時間執行的作業。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:exportDataObjects
JSON 要求主體：
{
"gcsDestination": {
"exportUri": "gs://your-bucket/path/to/export-dir/",
"format": "JSONL"
}
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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()
刪除資料物件
以下範例說明如何從 ID 為 COLLECTION_ID 的集合中刪除單一資料物件 DATA_OBJECT_ID。
REST
使用任何要求資料之前，請先修改下列項目的值：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
DELETE https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"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
使用下方的任何指令資料之前，請先替換以下項目：
- DATA_OBJECT_ID：資料物件的 ID。
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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
您應該會收到類似以下的回應：
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)
批次刪除資料物件
如要一次刪除多個資料物件，請使用 batchDelete 和完整合格的資料物件資源名稱清單。單一批次最多可刪除 1,000 個資料物件。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchDelete
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" }
]
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{}
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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)
計算資料物件
如要計算集合包含的資料物件數量，請使用 aggregate 作業和 COUNT 匯總方法。這個呼叫接受選用的 JSON 篩選運算式，因此您只能計算符合述詞的資料物件 (例如 genre == "sci-fi")。
如要計算集合中的每個資料物件，請省略篩選器。
REST
使用任何要求資料之前，請先修改下列項目的值：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
HTTP 方法和網址：
POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate
JSON 要求主體：
{
"aggregate": "COUNT",
"filter": { "genre": { "$eq": "sci-fi" } }
}
請展開以下其中一個選項，以傳送要求：
您應該會收到如下的 JSON 回覆：
{
"aggregateResults": [
{ "count": "42" }
]
}
gcloud
使用下方的任何指令資料之前，請先替換以下項目：
- COLLECTION_ID：集合的 ID。
- LOCATION：您使用 Agent Platform 的區域。
- PROJECT_ID：您的 Google Cloud 專案 ID。
執行下列指令：
Linux、macOS 或 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)
後續步驟
- 瞭解如何使用 ETag 控制資料物件的並行作業。
- 瞭解集合索引。
- 瞭解如何查詢及搜尋資料物件。