更新結構定義

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

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

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

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

更新結構定義

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

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

控制台

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

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

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

3. 確認您已完成資料擷取。否則，結構定義可能尚未開放編輯。

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

   Gemini Enterprise

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

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

7. 點選「結構定義」分頁標籤，查看資料的結構定義。

   如果這是您第一次編輯欄位，這個分頁可能會是空白。

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

9. 更新結構定義：

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

   • 更新維度數量 (進階)：如果您使用 Gemini Enterprise 的自訂向量嵌入，可以更新這項設定。請參閱 Agent Search 說明文件中的「使用自訂嵌入」。

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

   • 新增欄位：在匯入含有新欄位的新文件之前，先在結構定義中新增欄位，可縮短 Gemini Enterprise 在匯入後重新建立資料索引所需的時間。

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

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

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

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

    變更結構定義會觸發重新建立索引。如果資料儲存庫較大，重新建立索引可能需要數小時。

REST

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

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

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

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

3. 如果您要編輯自動偵測的結構定義，請確認已完成資料擷取。否則可能還無法編輯結構定義。

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

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

      前往「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#

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱「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

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

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

//go:build examples

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 Gemini Enterprise 快速入門導覽課程」中的 Ruby 設定說明操作。詳情請參閱「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"
          }
        }
      }
    }
  

後續步驟

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