Memperbarui skema

Anda dapat memperbarui skema data terstruktur dan data tidak terstruktur dengan metadata yang mendukung skema.

Anda dapat memperbarui skema di Google Cloud konsol atau menggunakan metode schemas.patch 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.

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 memeriksa apakah pembaruan skema Anda valid.

  2. Jika Anda memperbarui anotasi kolom (menetapkan kolom sebagai dapat diindeks, dapat diambil, dapat difaset 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 Google Cloud konsol, buka halaman Gemini Enterprise.

    Gemini Enterprise

  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 Gemini Enterprise. Lihat Menggunakan embedding kustom dalam dokumentasi Penelusuran Agen.

    • Memperbarui anotasi kolom: Untuk memperbarui anotasi 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 Gemini Enterprise 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.

  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 dan bagian Contoh batasan (khusus REST) untuk memeriksa apakah perubahan skema Anda valid.

    Untuk memperbarui skema penyimpanan data dengan 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, 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 Gemini Enterprise dan 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 project Anda.
    • DATA_STORE_ID: ID penyimpanan data.

    • 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#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai Gemini Enterprise menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Gemini Enterprise C# API dokumentasi referensi.

Untuk melakukan autentikasi ke Gemini Enterprise, 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Gemini Enterprise menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Gemini Enterprise Go API dokumentasi referensi.

Untuk melakukan autentikasi ke Gemini Enterprise, 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Gemini Enterprise menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Gemini Enterprise Java API dokumentasi referensi.

Untuk melakukan autentikasi ke Gemini Enterprise, 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Gemini Enterprise menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Gemini Enterprise Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Gemini Enterprise, 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai Gemini Enterprise menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Gemini Enterprise Ruby API.

Untuk melakukan autentikasi ke Gemini Enterprise, 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 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. Pengindeksan ulang penyimpanan data besar dapat memerlukan waktu berjam-jam atau berhari-hari.

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.

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