このページは Cloud Translation API によって翻訳されました。

スキーマを指定する、またはスキーマを自動検出する

Google Cloud コンソールを使用して構造化データをインポートすると、Vertex AI Search はスキーマを自動的に検出します。この自動検出されたスキーマをエンジンで使用するか、API を使用してデータの構造を示すスキーマを指定できます。

スキーマを指定した後で新しいスキーマで更新する場合、新しいスキーマは元のスキーマと下位互換性がある必要があります。そうでない場合、スキーマの更新は失敗します。

スキーマのリファレンス情報については、dataStores.schemas をご覧ください。

データストアのスキーマを提供するアプローチ

構造化データのスキーマを決定するには、さまざまなアプローチがあります。

自動検出と編集。Vertex AI Search に初期スキーマを自動検出して提案させます。次に、コンソールインターフェースでスキーマを調整します。フィールドが自動検出された後、キープロパティをすべての重要なフィールドにマッピングすることを強くおすすめします。

これは、検索データストアを作成するとカスタムレコメンデーションデータストアを作成するで、構造化データに対する Google Cloud コンソール手順に沿って使用するアプローチです。
スキーマを JSON オブジェクトとして指定します。スキーマを JSON オブジェクトとして Vertex AI Search に提供します。正しい JSON オブジェクトを準備しておく必要があります。JSON オブジェクトの例については、JSON オブジェクトとしてのスキーマの例をご覧ください。スキーマを作成したら、そのスキーマに従ってデータをアップロードします。

これは、curl コマンド（またはプログラム）を使用して API 経由でデータストアを作成するときに使用できるアプローチです。たとえば、BigQuery から 1 回だけインポートするをご覧ください。独自のスキーマを指定するの手順もご覧ください。
メディア: Google 定義のスキーマでデータを提供します。メディア用のデータストアを作成する場合は、Google の事前定義スキーマを使用できます。このオプションを選択すると、メディアドキュメントとデータストアについてで説明した形式で JSON オブジェクトが構造化されていると見なされます。デフォルトでは、自動検出では、データ取り込み中に検出された新しいフィールドがスキーマに追加されます。

これは、メディアアプリとデータストアを作成するの手順に沿って使用するアプローチです。これは、メディアレコメンデーションを使ってみるとメディア検索を使ってみるのチュートリアルでも使用されているアプローチです。これらのチュートリアルでは、サンプルデータが Google の事前定義スキーマで提供されています。
メディア: 自動検索と編集。必要なメディアプロパティが含まれていることを確認します。メディアデータの場合、自動検出を使用してスキーマを提案し、編集して調整できます。JSON オブジェクトには、メディアのキープロパティ（title、uri、category、media_duration、media_available_time）にマッピングできるフィールドを含める必要があります。

これは、メディアデータが Google 定義のスキーマにない場合に、Google Cloud コンソールからメディアデータをインポートするときに使用するアプローチです。
メディア: 独自のスキーマを JSON オブジェクトとして指定します。スキーマを JSON オブジェクトとして Vertex AI Search に提供します。正しい JSON オブジェクトを準備しておく必要があります。スキーマには、メディアのキープロパティ（title、uri、category、media_duration、media_available_time）にマッピングできるフィールドを含める必要があります。

JSON オブジェクトの例については、JSON オブジェクトとしてのスキーマの例をご覧ください。スキーマを作成したら、そのスキーマに従ってメディアデータをアップロードします。

このアプローチでは、curl コマンド（またはプログラム）を使用して API を使用します。独自のスキーマを指定するの手順をご覧ください。

自動検出と編集について

データのインポートを開始すると、Vertex AI Search はインポートされた最初の数個のドキュメントをサンプリングします。これらのドキュメントに基づいて、データのスキーマが提案されます。このスキーマは、後で確認または編集できます。

キープロパティにマッピングするフィールドがサンプリングされたドキュメントにない場合は、スキーマを確認するときにこれらのフィールドを手動で追加できます。

Vertex AI Search は、データインポートの後半で追加のフィールドを検出した場合でも、これらのフィールドをインポートしてスキーマに追加します。すべてのデータをインポートした後にスキーマを編集する場合は、スキーマを更新するをご覧ください。

JSON オブジェクトとしてのスキーマの例

独自のスキーマは、JSON スキーマ形式を使用して定義できます。これは、JSON ドキュメントの定義、アノテーション、検証を行うオープンソースの宣言型言語です。たとえば、次の JSON スキーマアノテーションが有効です。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

メディアスキーマを定義する場合は、メディアのキープロパティにマッピングできるフィールドを含める必要があります。これらのキープロパティを次の例で示します。

次のスキーマの例でフィールドの一部を示します。

dynamic。dynamic が文字列値 "true" に設定されている場合、インポートされたデータで見つかった新しいプロパティがスキーマに追加されます。 dynamic が "false" に設定されている場合、インポートされたデータで見つかった新しいプロパティは無視されます。プロパティはスキーマに追加されず、値もインポートされません。

たとえば、スキーマに title と description の 2 つのプロパティがあり、title、description、rating のプロパティを含むデータをアップロードします。dynamic が "true" の場合、ratings プロパティとデータがインポートされます。dynamic が "false" の場合、title と description はインポートされますが、rating プロパティはインポートされません。

デフォルトは "true" です。
datetime_detection。datetime_detection がブール値 true に設定されている場合、日時形式のデータがインポートされると、スキーマタイプは datetime に設定されます。サポートされている形式は、RFC 3339 と ISO 8601 です。

例:
- 2024-08-05 08:30:00 UTC
- 2024-08-05T08:30:00Z
- 2024-08-05T01:30:00-07:00
- 2024-08-05
- 2024-08-05T08:30:00+00:00
datatime_detection がブール値 false に設定されている場合、日時形式のデータがインポートされると、スキーマタイプは string に設定されます。

デフォルトは true です。
geolocation_detection。geolocation_detection がブール値 true に設定されている場合、位置情報形式のデータがインポートされると、スキーマタイプは geolocation に設定されます。緯度と経度の数値を含むオブジェクト、または住所の文字列を含むオブジェクトは、位置情報として検出されます。

例:
- "myLocation": {"latitude":37.42, "longitude":-122.08}
- "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}
geolocation_detection がブール値 false に設定されている場合、位置情報形式のデータがインポートされると、スキーマタイプは object に設定されます。

デフォルトは true です。
keyPropertyMapping。事前定義されたキーワードをドキュメント内の重要なフィールドにマッピングし、セマンティックな意味を明確にするのに役立つフィールド。値は、title、description、uri、category です。フィールド名は keyPropertyValues 値と一致する必要はありません。たとえば、my_title という名前のフィールドに、値が title の keyPropertyValues フィールドを含めることができます。

検索データストアの場合、keyPropertyMapping でマークされたフィールドは、デフォルトでインデックス登録可能で検索可能ですが、取得可能、補完可能、動的ファセット可能ではありません。つまり、期待されるデフォルトの動作を得るために、keyPropertyValues フィールドを含む indexable フィールドまたは searchable フィールドを含める必要はありません。

注: キープロパティを使用すると、検索とレコメンデーションの結果の品質と、検索の自動補完の精度を高めることができます。スキーマの自動検出を使用する場合、キープロパティは自動的に追加されません。schemas.patch メソッドを使用して、データフィールドをキープロパティ（特に title、uri、description）としてマークすることを強くおすすめします。
type。フィールドのタイプ。これは、datetime、geolocation、またはプリミティブ型（integer、boolean、object、array、number、string）のいずれかの文字列値です。

次のプロパティフィールドは、検索アプリにのみ適用されます。

retrievable。このフィールドを検索レスポンスで返すことができるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。取得可能として設定できるフィールドは最大 50 個です。ユーザー定義フィールドと keyPropertyValues フィールドは、デフォルトでは取得できません。フィールドを取得可能にするには、フィールドに "retrievable": true を含めます。
indexable。このフィールドを servingConfigs.search メソッドでフィルタ、ファセット、ブースト、並べ替えできるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。インデックス登録可能として設定できるフィールドは最大 50 個です。keyPropertyMapping フィールドを含むフィールドを除き、ユーザー定義フィールドはデフォルトでインデックスに登録できません。フィールドをインデックス可能にするには、フィールドに "indexable": true を含めます。
dynamicFacetable。フィールドを動的ファセットとして使用できることを示します。これは、number、string、boolean、integer タイプのフィールドに設定できます。フィールドを動的にファセット化するには、インデックス登録可能にする必要があります。フィールドに "dynamicFacetable": true と "indexable": true を含めます。
searchable。このフィールドを逆インデックスに登録して、非構造化テキストクエリと照合できるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。検索可能として設定できるフィールドは最大 50 個です。keyPropertyMapping フィールドを含むフィールドを除き、ユーザー定義フィールドはデフォルトで検索できません。フィールドを検索可能にするには、フィールドに "searchable": true を含めます。
completable。このフィールドを予測入力の候補として返すことができるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。フィールドを補完可能にするには、フィールドに "completable": true を含めます。

また、次のフィールドはレコメンデーションアプリにのみ適用されます。

recommendationsFilterable。このフィールドをレコメンデーションのフィルタ式で使用できることを示します。レコメンデーションのフィルタリングに関する一般的な情報については、レコメンデーションをフィルタリングするをご覧ください。
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },
```

独自のスキーマを JSON オブジェクトとして指定する

独自のスキーマを指定するには、空のスキーマを含むデータストアを作成し、スキーマを更新して、スキーマを JSON オブジェクトとして指定します。手順は次のとおりです。

JSON オブジェクトとしてのスキーマの例を参考に、スキーマを JSON オブジェクトとして準備します。
データストアを作成します。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'
```
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- DATA_STORE_ID: 作成する Vertex AI Search データストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
- DATA_STORE_DISPLAY_NAME: 作成する Vertex AI Search データストアの表示名。
- INDUSTRY_VERTICAL: GENERIC または MEDIA

schemas.patch API メソッドを使用して、新しい JSON スキーマを JSON オブジェクトとして指定します。

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID。
DATA_STORE_ID: Vertex AI Search データストアの ID。

JSON_SCHEMA_OBJECT: JSON オブジェクトとする新しい JSON スキーマ。例:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

コマンドの例と結果

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"title": {
"type": "string",
"keyPropertyMapping": "title"
},
"categories": {
"type": "array",
"items": {
"type": "string",
"keyPropertyMapping": "category"
}
},
"uri": {
"type": "string",
"keyPropertyMapping": "uri"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

省略可: スキーマ定義を表示するの手順に沿って、スキーマを確認します。