更新結構定義

你可以更新支援結構定義的結構化資料和含中繼資料的非結構化資料。

您可以在 Google Cloud 控制台中更新結構定義，或使用 schemas.patch API 方法。

如要更新結構定義，請新增欄位、變更欄位的可建立索引、可供搜尋和可擷取註解，或是將欄位標示為主要屬性，例如 title、uri 和 description。

重要事項： Google 強烈建議您更新結構化資料，加入重要屬性對應，尤其是 title。確保結果正確顯示，並協助 Gemini Enterprise 找出重要資訊，進而生成更優質的結果。

更新結構定義

您可以在 Google Cloud 控制台或使用 API 更新結構定義。

注意： 編輯結構定義會重新為資料儲存庫建立索引。 如果資料儲存庫較大，建立索引作業可能需要數小時。

控制台

如要在 Google Cloud 控制台中更新結構定義，請按照下列步驟操作：

1. 請參閱「需求條件和限制」一節，確認結構定義更新是否有效。

2. 如要更新欄位註解 (將欄位設為可建立索引、可擷取、動態可切面、可搜尋或可完成)，請參閱「設定欄位設定」，瞭解各註解類型的限制和規定。

3. 確認您已完成資料匯入。否則可能還無法編輯結構定義。

4. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

   Gemini Enterprise

5. 點按導覽選單中的「Data Stores」(資料儲存庫)。

6. 在「Name」(名稱) 欄中，按一下要更新架構的資料儲存庫。

7. 按一下「結構定義」分頁標籤，查看資料的結構定義。

   如果您是第一次編輯欄位，這個分頁可能不會顯示任何內容。

8. 按一下 [Edit] (編輯) 按鈕。

9. 更新結構定義：

   • 對應主要屬性：在結構定義的「主要屬性」欄中，選取要對應欄位的主要屬性。舉例來說，如果名為 details 的欄位一律包含文件說明，請將該欄位對應至 Description 鍵屬性。

   • 更新維度數量 (進階)：如果您搭配 Gemini Enterprise 使用自訂向量嵌入，可以更新這項設定。請參閱「進階：使用自訂嵌入」。

   • 更新欄位註解：如要更新欄位的註解，請選取或取消選取欄位的註解設定。可用的註解包括「可擷取」、「可建立索引」、「可做為動態 facet」、「可供搜尋」和「可完成」。部分欄位設定有其限制。如要瞭解各註解類型的說明和規定，請參閱「設定欄位設定」。

   • 新增欄位：在匯入含有這些欄位的新文件前，先將新欄位新增至結構定義，可縮短 Gemini Enterprise 在匯入後重新編製資料索引的時間。

     1. 按一下「新增欄位」展開該部分。

     2. 按一下「add_box」add_box「新增節點」，然後指定新欄位的設定。

        如要指出陣列，請將「陣列」設為「是」。舉例來說，如要新增字串陣列，請將 type 設為 string，並將 Array 設為 Yes。

10. 按一下「儲存」，套用結構定義變更。

    變更結構定義會觸發重新建立索引。以大型資料儲存庫來說，重新建立索引的作業可能需要數小時才能完成。

REST

如要使用 API 更新結構定義，請按照下列步驟操作：

1. 請參閱「需求和限制」和「限制範例 (僅限 REST)」部分，確認結構定義變更有效。

   如要更新含中繼資料的非結構化資料的資料儲存庫結構定義，請跳至步驟 5，呼叫 schema.patch 方法。

2. 如要更新欄位註解 (將欄位設為可建立索引、可擷取、動態可切面或可搜尋)，請參閱「設定欄位設定」一文，瞭解各註解類型的限制和規定。

3. 如要編輯自動偵測到的結構定義，請務必先完成資料擷取作業。否則，您可能還無法編輯結構定義。

4. 找出資料儲存庫 ID。如果已有資料商店 ID，請跳到下一個步驟。

   1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面，然後點按導覽選單中的「Data Stores」(資料儲存庫)。

      前往「資料儲存庫」頁面

   2. 點按資料儲存庫的名稱。

   3. 在資料儲存庫的「資料」頁面中，取得資料儲存庫 ID。

5. 使用 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：專案 ID。
   • DATA_STORE_ID：資料儲存庫的 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"
     }
     }
     

6. 選用：按照「查看結構定義」一節的程序，檢查結構定義。

C#

在試用這個範例之前，請先按照C#使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程中的操作說明進行設定。詳情請參閱 Gemini Enterprise C# API 參考說明文件。

如要驗證 Gemini Enterprise，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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

在試用這個範例之前，請先按照Go使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程中的操作說明進行設定。詳情請參閱 Gemini Enterprise Go API 參考說明文件。

如要驗證 Gemini Enterprise，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程中的操作說明進行設定。詳情請參閱 Gemini Enterprise Java API 參考說明文件。

如要驗證 Gemini Enterprise，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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

在試用這個範例之前，請先按照Python使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程中的操作說明進行設定。詳情請參閱 Gemini Enterprise Python API 參考說明文件。

如要驗證 Gemini Enterprise，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

# 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

在試用這個範例之前，請先按照Ruby使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程中的操作說明進行設定。詳情請參閱 Gemini Enterprise Ruby API 參考說明文件。

如要驗證 Gemini Enterprise，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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

需求條件和限制

更新結構定義時，請務必確認新結構定義與要更新的結構定義回溯相容。如要使用不回溯相容的新結構定義更新結構定義，您必須刪除資料儲存庫中的所有文件、刪除結構定義，然後建立新的結構定義。

更新結構定義會觸發所有文件的重新建立索引作業。 重新建立大型資料儲存庫的索引可能需要數小時或數天。

結構定義更新不支援下列項目：

• 變更欄位類型。結構定義更新不支援變更欄位類型。舉例來說，如果欄位已對應至 integer，就無法變更為 string。
• 移除欄位。定義欄位後就無法移除，您可以繼續新增欄位，但無法移除現有欄位。

限制示例 (僅限 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"
          }
        }
      }
    }
  

後續步驟

• 查看結構化資料的結構定義
• 刪除結構化資料的結構定義
• 預覽搜尋結果