Memperbarui skema

Anda dapat memperbarui skema untuk data apa pun yang berisi data yang mendukung skema, seperti data terstruktur, data situs dengan data terstruktur, atau data tidak terstruktur lainnya dengan metadata.

Anda dapat memperbarui skema di Google Cloud konsol atau menggunakan schemas.patch metode API. Memperbarui skema untuk situs hanya didukung melalui REST API.

Untuk memperbarui skema, Anda dapat menambahkan kolom baru, mengubah anotasi yang dapat diindeks, dapat ditelusuri, dan dapat diambil untuk kolom, atau menandai kolom sebagai properti kunci, seperti title, uri, dan description.

Sebelum memulai

Sebelum memperbarui skema, pahami konsep utama yang dijelaskan di bagian ini.

Pentingnya properti kunci

Berikut beberapa alasan mengapa Anda perlu memetakan kolom skema ke properti kunci:

  • Google sangat merekomendasikan agar Anda memperbarui skema dengan pemetaan properti kunci, terutama untuk title. Hal ini memastikan hasil Anda ditampilkan dengan benar dan membantu Penelusuran Agen mengidentifikasi informasi penting yang memungkinkannya menghasilkan hasil yang lebih baik.

  • Di penyimpanan data terstruktur, untuk mendapatkan sinyal keywordSimilarityScore dalam respons penelusuran, Anda harus memperbarui skema untuk melakukan hal berikut:

    • Memetakan kolom teks yang penting untuk pencocokan kata kunci ke properti kunci title dan description
    • Memperbarui anotasi untuk kolom teks sebagai Searchable

Persyaratan

Saat memperbarui skema, pastikan skema baru kompatibel dengan versi lama skema yang Anda perbarui. Untuk memperbarui skema dengan skema baru yang tidak kompatibel dengan versi lama, Anda harus menghapus semua dokumen di penyimpanan data, menghapus skema, dan membuat skema baru.

Memperbarui skema akan memicu pengindeksan ulang semua dokumen. Hal ini dapat memerlukan waktu dan menimbulkan biaya tambahan:

  • Waktu. Pengindeksan ulang penyimpanan data besar dapat memerlukan waktu berjam-jam atau berhari-hari.

  • Biaya. Pengindeksan ulang dapat menimbulkan biaya, bergantung pada parser. Misalnya, pengindeksan ulang penyimpanan data yang menggunakan parser OCR atau parser tata letak akan dikenai biaya. Untuk mengetahui informasi selengkapnya, lihat Harga fitur Document AI.

  • Dampak layanan. Pengindeksan ulang dapat menyebabkan layanan menjadi lambat atau tidak tersedia, terutama untuk penyimpanan data besar. Google merekomendasikan agar Anda merencanakan pembaruan skema dengan tepat—dengan mempertimbangkan potensi waktu nonaktif untuk aplikasi penting.

Pembaruan skema tidak mendukung hal berikut:

  • Mengubah jenis kolom. Pembaruan skema tidak mendukung perubahan jenis kolom. Misalnya, kolom yang dipetakan ke integer tidak dapat diubah menjadi string.
  • Menghapus kolom. Setelah ditentukan, kolom tidak dapat dihapus. Anda dapat terus menambahkan kolom baru, tetapi tidak dapat menghapus kolom yang ada.

Memperbarui skema

Anda dapat memperbarui skema di Google Cloud konsol atau menggunakan API.

Konsol

Untuk memperbarui skema di Google Cloud konsol, ikuti langkah-langkah berikut:

  1. Tinjau bagian Persyaratan dan batasan untuk memastikan pembaruan skema Anda valid.

  2. Jika Anda memperbarui anotasi kolom (menetapkan kolom sebagai dapat diindeks, dapat diambil, dapat difaset dinamis, dapat ditelusuri, atau dapat dilengkapi), tinjau Mengonfigurasi setelan kolom untuk mengetahui batasan dan persyaratan setiap jenis anotasi.

  3. Pastikan Anda telah menyelesaikan penyerapan data. Jika tidak, skema mungkin belum tersedia untuk diedit.

  4. Di Google Cloud konsol, buka halaman AI Applications.

    AI Applications

  5. Di menu navigasi, klik Data Stores.

  6. Di kolom Name, klik penyimpanan data dengan skema yang ingin Anda perbarui.

  7. Klik tab Schema untuk melihat skema data Anda.

    Tab ini mungkin kosong jika ini adalah pertama kalinya Anda mengedit kolom.

  8. Klik tombol Edit.

  9. Perbarui skema Anda:

    • Memetakan properti kunci: Di kolom Key properties skema Anda, pilih properti kunci untuk memetakan kolom. Misalnya, jika kolom bernama details selalu berisi deskripsi dokumen, petakan kolom tersebut ke properti kunci Description.

    • Memperbarui jumlah dimensi (Lanjutan): Anda dapat memperbarui setelan ini jika menggunakan embedding vektor kustom dengan Penelusuran Agen. Lihat Lanjutan: Menggunakan embedding kustom.

    • Memperbarui anotasi kolom: Untuk memperbarui anotasi untuk kolom, pilih atau batalkan pilihan setelan anotasi kolom. Anotasi yang tersedia adalah Retrievable, Indexable, Dynamic Facetable, Searchable, dan Completable. Beberapa setelan kolom memiliki batasan. Lihat Mengonfigurasi setelan kolom untuk mengetahui deskripsi dan persyaratan setiap jenis anotasi.

    • Menambahkan kolom baru: Menambahkan kolom baru ke skema sebelum mengimpor dokumen baru dengan kolom tersebut dapat mempersingkat waktu yang diperlukan Penelusuran Agen untuk mengindeks ulang data Anda setelah impor.

      1. Klik Add new fields untuk meluaskan bagian tersebut.

      2. Klik add_box Add node dan tentukan setelan untuk kolom baru.

        Untuk menunjukkan array, tetapkan Array ke Yes. Misalnya, untuk menambahkan array string, tetapkan type ke string dan Array ke Yes.

        Untuk indeks penyimpanan data situs, semua kolom yang Anda tambahkan adalah array secara default.

  10. Klik Save untuk menerapkan perubahan skema.

    Mengubah skema akan memicu pengindeksan ulang. Untuk penyimpanan data besar, pengindeksan ulang dapat memerlukan waktu berjam-jam.

REST

Untuk menggunakan API guna memperbarui skema, ikuti langkah-langkah berikut:

  1. Tinjau bagian Persyaratan dan batasan serta Contoh batasan (khusus REST) untuk memastikan perubahan skema Anda valid.

    Untuk memperbarui skema penyimpanan data dengan situs atau data tidak terstruktur dengan metadata, lewati ke Langkah 5 untuk memanggil metode schema.patch.

  2. Jika Anda memperbarui anotasi kolom (menetapkan kolom sebagai dapat diindeks, dapat diambil, dapat difaset dinamis, atau dapat ditelusuri), tinjau Mengonfigurasi setelan kolom untuk mengetahui batasan dan persyaratan setiap jenis anotasi.

  3. Jika Anda mengedit skema yang terdeteksi otomatis, pastikan Anda telah menyelesaikan penyerapan data. Jika tidak, skema mungkin belum tersedia untuk diedit.

  4. Temukan ID penyimpanan data Anda. Jika Anda sudah memiliki ID penyimpanan data, lanjutkan ke langkah berikutnya.

    1. Di Google Cloud konsol, buka halaman AI Applications , lalu di menu navigasi, klik Data Stores.

      Buka halaman Data Stores

    2. Klik nama penyimpanan data Anda.

    3. Di halaman Data untuk penyimpanan data Anda, dapatkan ID penyimpanan data.

  5. Gunakan metode schemas.patch API untuk memberikan skema JSON baru Anda sebagai objek 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
}'

    Ganti kode berikut:

    • PROJECT_ID: ID proyek Anda Google Cloud .
    • DATA_STORE_ID: ID penyimpanan data Agent Search.

    • JSON_SCHEMA_OBJECT: skema JSON baru Anda sebagai objek JSON. Contoh:

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

  6. Opsional: Tinjau skema dengan mengikuti prosedur Melihat definisi skema.

C#

Untuk mengetahui informasi selengkapnya, lihat Agent Search C# API dokumentasi referensi.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Agent Search Go API.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Untuk mengetahui informasi selengkapnya, lihat Agent Search Java API dokumentasi referensi.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk mengetahui informasi selengkapnya, lihat Agent Search Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

# 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

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Agent Search Ruby API.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Contoh batasan (khusus REST)

Bagian ini menampilkan contoh jenis pembaruan skema yang valid dan tidak valid. Contoh ini menggunakan contoh skema JSON berikut:

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

Contoh pembaruan yang didukung

Pembaruan berikut pada contoh skema didukung.

  • Menambahkan kolom. Dalam contoh ini, kolom properties.uri telah ditambahkan ke skema.

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

  • Menambahkan atau menghapus anotasi properti kunci untuk title, description atau uri. Dalam contoh ini, keyPropertyMapping telah ditambahkan ke kolom 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"
      }
    }
  }
}

Contoh pembaruan skema yang tidak valid

Pembaruan berikut pada contoh skema tidak didukung.

  • Mengubah jenis kolom. Dalam contoh ini, jenis kolom title telah diubah dari string menjadi angka. Hal ini tidak didukung.

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

  • Menghapus kolom. Dalam contoh ini, kolom title telah dihapus. Hal ini tidak didukung.

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

Langkah berikutnya