注: Vertex AI Search は Agent Search に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

スキーマを更新する

スキーマをサポートするデータ（たとえば構造化データ、構造化データを含むウェブサイトデータ、メタデータを含むその他の非構造化データなど）のスキーマを更新できます。

スキーマは、 Google Cloud コンソールまたは schemas.patch API メソッドを使用して更新できます。ウェブサイトのスキーマの更新は、REST API でのみサポートされています。

スキーマを更新するには、新しいフィールドを追加したり、フィールドのインデックス登録可能、検索可能、取得可能のアノテーションを変更したり、フィールドをキープロパティ（title、uri、description など）としてマークしたりします。

始める前に

スキーマを更新する前に、このセクションで説明する主なコンセプトを理解してください。

キープロパティの重要性

スキーマフィールドをキープロパティにマッピングする必要がある理由は次のとおりです。

特に title について、キープロパティマッピングでスキーマを更新することを強くおすすめします。これにより、結果が正しく表示され、Agent Search が重要な情報を特定して、より良い結果を生成するのに役立ちます。
構造化データストアで検索レスポンスに keywordSimilarityScore シグナルを取得するには、スキーマを更新して次の操作を行う必要があります。
- キーワードのマッチタイプに不可欠なテキストフィールドをキープロパティ title と description にマッピングする
- テキストフィールドのアノテーションを Searchable に更新する

要件

スキーマを更新するときは、新しいスキーマが更新対象のスキーマと下位互換性があることを確認してください。下位互換性のない新しいスキーマでスキーマを更新するには、データストア内のすべてのドキュメントを削除し、スキーマを削除して、新しいスキーマを作成する必要があります。

スキーマを更新すると、すべてのドキュメントのインデックスが再作成されます。これには時間がかかり、追加費用が発生する可能性があります。

時間。 大規模なデータストアのインデックスの再作成には、数時間から数日かかることがあります。
コスト。インデックスの再作成には、パーサーに応じて費用が発生する場合があります。たとえば、OCR パーサーまたはレイアウトパーサーを使用するデータストアのインデックスを再作成すると、どちらも費用が発生します。詳細については、Document AI の機能の料金をご覧ください。
サービスへの影響。インデックスの再作成により、特に大規模なデータストアの場合、サービスの速度が低下したり、サービスが利用できなくなったりする可能性があります。重要なアプリケーションのダウンタイムの可能性を考慮して、スキーマの更新を適切に計画することをおすすめします。

スキーマの更新では、次の機能はサポートされていません。

フィールドタイプの変更。スキーマの更新では、フィールドのタイプを変更することはできません。たとえば、integer にマッピングされたフィールドを string に変更することはできません。
フィールドの削除。定義したフィールドは削除できません。新しいフィールドを追加していくことはできますが、既存のフィールドを削除することはできません。

スキーマを更新する

スキーマは、 Google Cloud コンソールまたは API を使用して更新できます。

コンソール

Google Cloud コンソールでスキーマを更新する手順は次のとおりです。

要件と制限事項のセクションを確認して、スキーマの更新が有効であることを確認します。
フィールドアノテーションを更新する場合（フィールドをインデックス登録可能、取得可能、動的ファセット可能、検索可能、補完可能として設定する場合）、フィールド設定を構成するで、各アノテーションタイプの制限と要件を確認してください。
データ取り込みが完了していることを確認します。それ以外の場合、スキーマはまだ編集に利用できない可能性があります。
コンソールで、[AI アプリケーション] ページに移動します。 Google Cloud

AI Applications
ナビゲーションメニューで [データストア] をクリックします。
[名前] 列で、更新するスキーマを含むデータストアをクリックします。
[スキーマ] タブをクリックして、データのスキーマを表示します。

フィールドを初めて編集する場合は、このタブが空になっていることがあります。
[編集] ボタンをクリックします。
スキーマを更新します。
- キープロパティをマッピングする: スキーマの [Key properties] 列で、フィールドをマッピングするキープロパティを選択します。たとえば、details というフィールドに常にドキュメントの説明が含まれている場合は、そのフィールドをキープロパティ [説明] にマッピングします。
- 次元数を更新する（詳細設定）: Agent Search でカスタムベクトルエンベディングを使用している場合は、この設定を更新できます。上級: カスタムエンベディングを使用するをご覧ください。
- フィールドのアノテーションを更新する: フィールドのアノテーションを更新するには、フィールドのアノテーション設定を選択または選択解除します。使用可能なアノテーションは、[取得可能]、[インデックス登録可能]、[動的ファセット可能]、[検索可能]、[補完可能] です。一部のフィールド設定には制限があります。各アノテーションタイプの説明と要件については、フィールド設定を構成するをご覧ください。
- 新しいフィールドを追加する: 新しいフィールドを含む新しいドキュメントをインポートする前に、スキーマに新しいフィールドを追加すると、インポート後に Agent Search がデータを再インデックス登録する時間を短縮できます。
  1. [新しいフィールドを追加する] をクリックして、セクションを開きます。
  2. add_box [ノードを追加] をクリックして、新しいフィールドの設定を指定します。
    
    配列を示すには、[配列] を [はい] に設定します。たとえば、文字列の配列を追加するには、[タイプ] を string、[配列] を Yes に設定します。
    
    ウェブサイトデータストアインデックスの場合、追加するフィールドはすべてデフォルトで配列になります。
[保存] をクリックして、スキーマの変更を適用します。

スキーマを変更すると、インデックスが再作成されます。大規模なデータストアの場合、インデックスの再作成に数時間かかることがあります。

REST

API を使用してスキーマを更新する手順は次のとおりです。

要件と制限事項と制限事項の例（REST のみ）のセクションを確認して、スキーマの変更が有効であることを確認します。

ウェブサイトまたはメタデータを含む非構造化データを含むデータストアのスキーマを更新するには、ステップ 5 にスキップして schema.patch メソッドを呼び出します。
フィールドアノテーションを更新する場合（フィールドをインデックス登録可能、取得可能、動的ファセット可能、検索可能として設定する場合）、フィールド設定を構成するで、各アノテーションタイプの制限と要件を確認してください。
自動検出されたスキーマを編集する場合は、データ取り込みが完了していることを確認してください。それ以外の場合、スキーマはまだ編集に利用できない可能性があります。
データストア ID を確認します。データストア ID がすでにある場合は、次のステップに進みます。
1. コンソールで、[**AI アプリケーション**] ページに移動し、ナビゲーションメニューで [**データストア**] をクリックします。 Google Cloud
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. データストアの [データ] ページで、データストア ID を取得します。

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

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

C#

詳細については、 Agent Search C# API リファレンスドキュメントをご覧ください。

Agent Search への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

詳細については、 Agent Search Go API リファレンスドキュメントをご覧ください。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、 Agent Search Java API リファレンスドキュメントをご覧ください。

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

  public static void main(String[] args) throws Exception {
    syncUpdateSchema();
  }

  public static void syncUpdateSchema() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

詳細については、 Agent Search Python API リファレンスドキュメントをご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest()

    # Make the request
    operation = client.update_schema(request=request)

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

詳細については、 Agent Search Ruby API リファレンスドキュメントをご覧ください。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::UpdateSchemaRequest.new

  # Call the update_schema method.
  result = client.update_schema request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

制限の例（REST のみ）

このセクションでは、有効なスキーマ更新と無効なスキーマ更新の例を示します。これらの例では、次の JSON スキーマの例を使用します。

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

サポートされている更新の例

次の例のスキーマの更新がサポートされています。

フィールドの追加。この例では、フィールド properties.uri がスキーマに追加されています。

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

title、description、uri のキープロパティアノテーションの追加または削除。この例では、keyPropertyMapping が title フィールドに追加されています。

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

無効なスキーマ更新の例

次の例のスキーマの更新はサポートされていません。

フィールドタイプの変更。この例では、title フィールドのタイプが文字列から数値に変更されています。これはサポートされていません。

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "number" // Changed from string. Not allowed.
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }

フィールドの削除。この例では、title フィールドが削除されています。これはサポートされていません。

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

スキーマを更新する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

キープロパティの重要性

要件

スキーマを更新する

コンソール

REST

コマンドの例と結果

C#

Go

Java

Python

Ruby

制限の例（REST のみ）

サポートされている更新の例

無効なスキーマ更新の例

次のステップ

スキーマを更新する