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 konsol Google Cloud atau dengan menggunakan metode API schemas.patch. Memperbarui skema untuk situs hanya didukung melalui REST API.

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

Memperbarui skema

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

Konsol

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

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

  2. Jika Anda memperbarui anotasi kolom (menetapkan kolom sebagai dapat diindeks, dapat diambil, tabel wajah dinamis, dapat ditelusuri, atau dapat diselesaikan), 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 konsol Google Cloud, buka halaman Agent Builder.

    Agent Builder

  5. Di menu navigasi, klik Penyimpanan Data.

  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:

    • Pemetaan properti kunci: Di kolom Properti kunci skema Anda, pilih properti kunci yang akan dipetakan ke kolom. Misalnya, jika kolom bernama details selalu berisi deskripsi dokumen, petakan kolom tersebut ke properti kunci Deskripsi.

    • Perbarui jumlah dimensi (Lanjutan): Anda dapat memperbarui setelan ini jika menggunakan penyematan vektor kustom dengan Vertex AI Search. Lihat Lanjutan: Menggunakan penyematan kustom.

    • Memperbarui anotasi kolom: Untuk memperbarui anotasi kolom, pilih atau batalkan pilihan setelan anotasi kolom. Anotasi yang tersedia adalah Dapat Diambil, Dapat Diindeks, Dapat Dibuat Tabel Dinamis, Dapat Ditelusuri, dan Dapat Diisi. Beberapa setelan kolom memiliki batasan. Lihat Mengonfigurasi setelan kolom untuk mengetahui deskripsi dan persyaratan untuk setiap jenis anotasi.

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

      1. Klik Tambahkan kolom baru untuk meluaskan bagian tersebut.

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

        Untuk menunjukkan array, tetapkan Array ke Ya. 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 Simpan untuk menerapkan perubahan skema.

    Mengubah skema akan memicu pengindeksan ulang. Untuk penyimpanan data yang 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 memeriksa apakah perubahan skema Anda valid.

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

  2. Jika Anda memperbarui anotasi kolom (menetapkan kolom sebagai dapat diindeks, dapat diambil, tabel wajah 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 konsol Google Cloud, buka halaman Agent Builder dan di menu navigasi, klik Data Stores.

      Buka halaman Data Store

    2. Klik nama penyimpanan data Anda.

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

  5. Gunakan metode API schemas.patch untuk memberikan skema JSON baru 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 project Google Cloud Anda.
    • DATA_STORE_ID: ID penyimpanan data Vertex AI 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 Dokumentasi referensi API C# Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, 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 API Go Vertex AI Agent Builder.

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


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 Dokumentasi referensi API Java Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, 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 Dokumentasi referensi API Python Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, 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 API Ruby Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, 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

Persyaratan dan batasan

Saat memperbarui skema, pastikan skema baru kompatibel dengan skema yang Anda perbarui. Untuk memperbarui skema dengan skema baru yang tidak kompatibel dengan versi sebelumnya, 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 mengalami biaya tambahan:

  • Waktu. Membuat kembali indeks penyimpanan data yang besar dapat memerlukan waktu berjam-jam atau berhari-hari.

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

Pembaruan skema tidak mendukung hal berikut:

  • Mengubah jenis kolom. Update skema tidak mendukung perubahan jenis kolom. Misalnya, kolom yang dipetakan ke bilangan bulat 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.

Contoh batasan (khusus REST)

Bagian ini menunjukkan 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 update yang didukung

Pembaruan berikut pada skema contoh 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 utama 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. Tindakan 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. Tindakan 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 selanjutnya