Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

データオブジェクト

エージェント検索（以前の Vector Search 2.0）では、コレクションはデータをデータオブジェクトと呼ばれる個々の JSON オブジェクトとして保存します。このページでは、データオブジェクトが満たす必要のある検証ルールと、データオブジェクトを個別にまたはバッチで作成、読み取り、更新、インポート、エクスポート、削除する方法について説明します。

データの検証

エージェント取得（以前の Vector Search 2.0）は、データオブジェクトを保存する前に検証します。検証は、同じコアルールを適用するが、失敗の報告方法が異なる 2 つのコンテキストで行われます。

コンテキスト	対象	障害発生時の動作
データオブジェクトの検証	個々の書き込みとバッチ書き込み: `create`、`batchCreate`、`update`、`batchUpdate`	リクエストは `INVALID_ARGUMENT` で直ちに失敗します。バッチ書き込みはアトミックです。無効なレコードがある場合、リクエスト内のレコードは書き込まれません。
インポートの検証	Cloud Storage からの `import`	各レコードは個別に検証されます。無効なレコードは `code = INVALID_ARGUMENT` でエラーシンクに書き込まれてスキップされ、残りのインポートは続行されます。レコードがチェックに失敗すると、それ以降のチェックは実行されません。

どちらのコンテキストでも、同じコアルール（ID ルール、データフィールドルール（コレクションが dataSchema を宣言している場合）、埋め込みルール）が適用されます。入力が構造化された API リクエストではなく、未加工のファイルであるため、各レコードを解析し、検索可能なフィールドを抽出します。

「1 つのエラーを修正して再取り込みし、次のエラーが発生する」というループを回避するには、インポートまたはインデックスのビルドを開始する前に、次のすべてのルールに対してデータセットを検証します。

解析（インポートのみ）

解析はインポートにのみ適用されます。インポートでは、各未加工の入力行またはレコードが内部データオブジェクトに変換されます。個々の API 書き込みとバッチ API 書き込みでは、入力がすでに構造化されているため、このステップはスキップされます。解析では、サポートされている JSON 形式（最上位の vectors/data オブジェクトを含むデフォルト形式と、embedding、sparse_embedding、restricts、numeric_restricts を含む v1 形式）の両方が処理されます。形式はレコードごとに自動検出されます。

JSON は解析可能である必要があります。各行は JSON オブジェクトとして解析される必要があります。最上位のキーがデフォルト形式または v1 形式のいずれにも一致しない行は、Unknown JSON format for string: <line> で拒否されます。
id は必須です。すべてのレコードに null 以外の id が含まれている必要があります。それ以外の場合: 'id' field is missing or null。
エンベディングが存在する必要があります（v1 形式のみ）。v1 形式のレコードには、embedding または sparse_embedding のいずれかを少なくとも 1 つ含める必要があります。それ以外の場合: 'embedding' or 'sparse_embedding' fields are missing。
密エンベディングの型チェック。密なエンベディングフィールド（v1 の embedding、またはデフォルト形式の vectors の任意の配列値）は、数値の JSON 配列である必要があります。float に強制変換できない値は、'<field>' field contains non-float values で拒否されます。
疎エンベディング構造のチェック。すべてのスパースベクトルについて、次の操作を行います。
- JSON オブジェクトである必要があります。
- values（浮動小数点数）と indices（長整数）の両方の配列を含む必要があります。v1 では、これらは values と dimensions です。
- values を空にすることはできません。
- インデックスは負でない値にする必要があります。
- values.length は indices.length（または v1 の dimensions.length）と等しくなければなりません。
data フィールドタイプ。存在する場合、data は配列、文字列、スカラーではなく、JSON オブジェクトである必要があります。それ以外の場合: 'data' field is not a JSON object。
numeric_restricts シェイプ（v1 形式）。numeric_restricts はオブジェクトの JSON 配列である必要があります。各エントリには文字列 namespace が必要です。また、value_int、value_float、value_double のいずれか 1 つを正確に設定する必要があります。

「最初の失敗」の問題のほとんどはこのステージで発生します。一般的なエラーとしては、エンベディング配列内の文字列化された数値、id の欠落、values と indices の長さが異なることなどがあります。

ID ルール

データオブジェクト ID は 1 ～ 63 文字にする必要があります。長さは、エージェント取得が ID に適用する唯一の制約です。すべての文字が受け入れられます。

次の表に、一般的な例を示します。

ID	有効か？	理由
`movie-789`	○	1 ～ 63 文字
`a`	○	最小文字数は 1 文字です
`Doc_123`	○	大文字とアンダースコアを使用できます
`my doc`	○	文字数制限内であれば、任意の文字を使用できます
（空の文字列）	×	1 文字以上で指定してください
64 文字以上	×	最大文字数は 63 文字です

データフィールドのルール（JSON スキーマ）

データフィールドの検証は、Collection の CollectionConfig で dataSchema が宣言されている場合にのみ実行されます。スキーマが構成されていない場合、このチェックはスキップされます。

スキーマのコンプライアンス。データオブジェクトの data ペイロードは JSON にシリアル化され、構成された JSON スキーマ（ドラフト 7）に対して検証されます。検証ツールはスキーマ違反ごとに 1 つのエラーを報告するため、3 つの無効なフィールドを含むレコードでは 3 つのエラーメッセージが生成されます。
- メッセージ: DataObject with id <id> failed schema validation: <error>。
スキーマ処理エラー。スキーマバリデータ自体が例外をスローした場合（サポートされていないドラフト機能など）、レコードは DataObject with id <id> failed schema validation processing: <exception> で拒否されます。

埋め込みルール

エンベディングの検証では、まず密ベクトルが反復処理され、次にスパースベクトルが反復処理されます。単一の共有されたベクトル名のセットは両方のリストにまたがるため、名前を 2 回使用することはできません（密とスパースの境界を越えても同様です）。

共有ルール（密と疎の両方に適用）

ルール	利点	エラーメッセージ
同じデータオブジェクトの密ベクトルとスパースベクトルで重複するベクトル名がない	同じベクトル名を持つ 2 つのエントリは同じストレージキーをターゲットとし、未定義の last-write-wins 動作を生成します。	`... 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)`

検索可能なフィールドの抽出（インポートのみ）

インポート中、埋め込みの検証が成功すると、パイプラインは Collection の dataSchema を使用して data ペイロードをウォークし、スキーマで宣言されたフィールド（文字列、整数/数値、ブール値、文字列の配列、ネストされたオブジェクト）を検索可能なフィールドインデックスにコピーします。次の 2 つの障害モードでもレコードが拒否されます。

構造体であるべきパスにスカラーが含まれている（たとえば、スキーマでは author.name は文字列だが、ドキュメントでは author 自体が文字列である）。
文字列の配列フィールドに文字列以外の要素が含まれています。

これらは通常、ドキュメントの形状が宣言されたスキーマから逸脱していることを示します。JSON スキーマの段階で必ずしも検出されるとは限りません。

フライト前のチェックリスト

取り込みまたはインデックスの作成を開始する前に、次のルールに照らしてデータセット全体を検証します。これは、パイプラインが適用するチェックと同じセットです。単一のクライアントサイドパスで各問題が表面化するように順序付けられています。

形式 - 各行が JSON として解析され、デフォルトまたは v1 のシェイプのいずれかに一致します。
ID - 1 ～ 63 文字で、データセット全体で一意です。
エンベディングが存在する - レコードごとに少なくとも 1 つのベクトル。ベクトル名は、正しい密型またはスパース型で CollectionConfig ベクトルスキーマにリストされています。
密ベクトル - 正しいディメンション。NaN、+Inf、-Inf の値はありません。
スパースベクトル - values.length == indices.length。すべてのインデックスは 0 以上で一意です。非有限値は使用できません。
密ベクトルとスパースベクトルで、レコード内のベクトル名が重複していない。
データスキーマ - dataSchema が構成されている場合、data ペイロードはそれに対して検証され（ドラフト 7）、すべてのフィールドの実際の JSON 型が宣言された型と一致します（特にネストされたオブジェクトと文字列の配列の場合）。
v1 numeric_restricts - 各エントリには文字列 namespace と、value_int、value_float、value_double のいずれか 1 つが含まれます。

データオブジェクトを作成する

次の例は、ID が COLLECTION_ID のコレクションに単一のデータオブジェクトを追加する方法を示しています。

REST

リクエストのデータを使用する前に、次のように置き換えます。

DATA_OBJECT_ID: データオブジェクトの ID。
COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID" | Select-Object -Expand Content

次のような 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）を使用して、自動的に入力されないベクトルフィールドの値を設定することもできます。

データオブジェクトを一括作成する

少数のレコード（リクエストあたり最大 1,000 個のデータオブジェクト）を一括で効率的に取り込むには、batchCreate を使用します。バッチ全体がアトミックです。すべてのデータオブジェクトが作成されるか、リクエスト全体が失敗します。大きなデータセットの場合は、Cloud Storage からデータオブジェクトをインポートすることをおすすめします。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchCreate"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchCreate" | Select-Object -Expand Content

次のような 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 メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID" | Select-Object -Expand Content

次のような 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 メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID" | Select-Object -Expand Content

次のような 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 回のバッチで更新できるデータオブジェクトは最大 1,000 個です。レコードごとの各リクエストでは、dataObject（完全なリソース name と変更するフィールドを含む）と、上書きするフィールドを一覧表示する updateMask を指定します。マスクにリストされていないフィールドは変更されません。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchUpdate"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchUpdate" | Select-Object -Expand Content

次のような 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 のコレクションにデータオブジェクトをインポートする方法を示しています。大きなデータセットにはインポートを使用します。小さな一括取り込み（最大 1,000 レコード）の場合は、バッチでデータオブジェクトを作成することを検討してください。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:importDataObjects"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:importDataObjects" | Select-Object -Expand Content

次のような 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/ には、複数のデータオブジェクトを含む 1 つ以上のファイルを含めることができます。この構造は、複数のファイルに分散された大規模なデータセットに使用します。エージェント検索でサポートされているファイル形式は次のとおりです。

JSONL。各行は、id、data、vectors の 3 つの最上位プロパティを持つ JSON オブジェクトです。手動で検査および編集するための人間が読める形式の入力を必要とする場合は、新しいエージェント取得データセットにこの形式を使用します。
AVRO: コンパクトでスキーマ検証済みのバイナリ形式が必要な新しいエージェント取得データセットには、この形式を使用します。通常、Dataflow、Beam、Spark などのデータパイプラインツールによって生成された大規模なデータセットに使用されます。
ベクトル検索 JSON: この形式は、既存のベクトル検索（ベクトル検索 1.0）JSON データセットを移行し、そのまま再利用する場合にのみ使用します。
ベクトル検索 AVRO: この形式は、既存のベクトル検索（ベクトル検索 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、デフォルトは {}）。各エントリはベクトル名でキー設定され、値は float（密ベクトル）の array、または values（float の配列）と indices（long の配列）を含む SparseVector レコードのいずれかです。
data（null 許容 map、デフォルト null）。キーはデータフィールド名です。各値は DataValue レコードです。その value フィールドは、サポートされているプリミティブ型（boolean、int、long、float、double、string）と、ネストされた構造の DataValue の array と string から DataValue の map の和集合です。
etag（null 許容 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
    }
  ]
}

次のスニペットは、上記の JSONL の例と一致する単一の AVRO レコードの概念的な内容を示しています。このスキーマでは、data の各エントリが DataValue レコード（単一の value フィールドを含む）でラップされます。これは、AVRO が 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 }
      }
    }
  }
}

データオブジェクトをエクスポートする

次の例は、コレクション内のすべてのデータオブジェクトを JSONL 形式で Cloud Storage にエクスポートする方法を示しています。転送先バケットは、コレクションと同じリージョンに存在する必要があります。エクスポートは長時間実行オペレーションです。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:exportDataObjects"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:exportDataObjects" | Select-Object -Expand Content

次のような 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 メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID"

PowerShell（Windows）

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID" | Select-Object -Expand Content

次のような 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 つのバッチで削除できるデータオブジェクトの最大数は 1,000 個です。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchDelete"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchDelete" | Select-Object -Expand Content

次のような 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)

データオブジェクトの数を取得する

コレクションに含まれるデータオブジェクトの数をカウントするには、COUNT 集計メソッドで aggregate オペレーションを使用します。同じ呼び出しでオプションの JSON フィルタ式を受け入れるため、述語（genre == "sci-fi" など）に一致するデータオブジェクトのみをカウントできます。

コレクション内のすべてのデータオブジェクトをカウントするには、フィルタを省略します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

COLLECTION_ID: コレクションの ID。
LOCATION: Agent Platform を使用しているリージョン。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。

HTTP メソッドと URL:

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

リクエストの本文（JSON）:

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

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate" | Select-Object -Expand Content

次のような 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 を使用する方法を確認する。
コレクションインデックスについて学習する。
データオブジェクトをクエリして検索する方法を確認する。

データ オブジェクト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

データの検証

解析（インポートのみ）

ID ルール

データフィールドのルール（JSON スキーマ）

埋め込みルール

共有ルール（密と疎の両方に適用）

密ベクトルのみのルール

スパース ベクトルのみのルール

検索可能なフィールドの抽出（インポートのみ）

フライト前のチェックリスト

データ オブジェクトを作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトを一括作成する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトを取得する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトを更新する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトをバッチ アップデートする

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトをインポートする

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

JSONL

AVRO

データ オブジェクトをエクスポートする

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

Python

データ オブジェクトを削除する

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

データオブジェクト

スパースベクトルのみのルール

データオブジェクトを作成する

データオブジェクトを一括作成する

データオブジェクトを取得する

データオブジェクトを更新する

データオブジェクトをバッチアップデートする

データオブジェクトをインポートする

データオブジェクトをエクスポートする

データオブジェクトを削除する

データオブジェクトをバッチで削除する

データオブジェクトの数を取得する