Memberikan atau mendeteksi skema secara otomatis

Saat Anda mengimpor data terstruktur menggunakan Google Cloud konsol, Penelusuran Agen akan otomatis mendeteksi skema. Anda dapat menggunakan skema yang terdeteksi otomatis ini di mesin atau menggunakan API untuk memberikan skema guna menunjukkan struktur data.

Jika Anda memberikan skema dan kemudian memperbaruinya dengan skema baru, skema baru tersebut harus kompatibel dengan versi lama skema aslinya. Jika tidak, pembaruan skema akan gagal.

Untuk informasi referensi tentang skema, lihat dataStores.schemas.

Pendekatan untuk memberikan skema bagi penyimpanan data Anda

Ada berbagai pendekatan untuk menentukan skema data terstruktur.

  • Deteksi otomatis dan edit. Izinkan Penelusuran Agen mendeteksi otomatis dan menyarankan skema awal. Kemudian, Anda dapat menyempurnakan skema melalui antarmuka konsol. Google sangat merekomendasikan agar, setelah kolom Anda terdeteksi otomatis, Anda memetakan properti utama ke semua kolom penting.

    Ini adalah pendekatan yang akan Anda gunakan saat mengikuti petunjuk konsol untuk data terstruktur di Membuat penyimpanan data penelusuran dan Membuat penyimpanan data rekomendasi kustom. Google Cloud

  • Memberikan skema sebagai objek JSON. Berikan skema ke Penelusuran Agen sebagai objek JSON. Anda harus menyiapkan objek JSON yang benar. Untuk contoh objek JSON, lihat Contoh skema sebagai objek JSON. Setelah membuat skema, Anda mengupload data sesuai dengan skema tersebut.

    Ini adalah pendekatan yang dapat Anda gunakan saat membuat penyimpanan data melalui API menggunakan perintah curl (atau program). Misalnya, lihat Mengimpor sekali dari BigQuery. Lihat juga petunjuk berikut, Menyediakan skema Anda sendiri.

  • Media: Berikan data Anda dalam skema yang ditentukan Google. Jika membuat penyimpanan data untuk media, Anda dapat memilih untuk menggunakan skema yang telah ditentukan Google. Memilih opsi ini berarti Anda telah menyusun objek JSON dalam format yang diberikan di Tentang dokumen media dan penyimpanan data. Secara default, deteksi otomatis akan menambahkan kolom baru yang ditemukan selama penyerapan data ke skema.

    Ini adalah pendekatan yang Anda gunakan saat mengikuti petunjuk di Membuat aplikasi media dan penyimpanan data. Pendekatan ini juga digunakan dalam tutorial, Memulai rekomendasi media dan Memulai penelusuran media, yang menyediakan data contoh dalam skema yang telah ditentukan Google.

  • Media: Deteksi otomatis dan edit, pastikan untuk menyertakan properti media yang diperlukan. Untuk data media, Anda dapat menggunakan deteksi otomatis untuk menyarankan skema dan mengedit untuk menyempurnakannya. Dalam objek JSON, Anda harus menyertakan kolom yang dapat dipetakan ke properti kunci media: title, uri, category, media_duration, dan media_available_time.

    Ini adalah pendekatan yang akan Anda gunakan saat mengimpor data media melalui Google Cloud konsol jika data media tidak berada dalam skema yang ditentukan Google.

  • Media: Berikan skema Anda sendiri sebagai objek JSON. Berikan skema ke Penelusuran Agen sebagai objek JSON. Anda harus menyiapkan objek JSON yang benar. Skema harus menyertakan kolom yang dapat dipetakan ke properti kunci media: title, uri, category, media_duration, dan media_available_time.

    Untuk contoh objek JSON, lihat Contoh skema sebagai objek JSON. Setelah membuat skema, Anda mengupload data media sesuai dengan skema tersebut.

    Untuk pendekatan ini, Anda menggunakan API melalui perintah curl (atau program). Lihat petunjuk berikut, Menyediakan skema Anda sendiri.

Tentang deteksi otomatis dan edit

Saat Anda mulai mengimpor data, Penelusuran Agen akan mengambil sampel beberapa dokumen pertama yang diimpor. Berdasarkan dokumen ini, Penelusuran Agen akan mengusulkan skema untuk data, yang kemudian dapat Anda tinjau atau edit.

Jika kolom yang ingin Anda petakan ke properti utama tidak ada dalam dokumen yang diambil sampelnya, Anda dapat menambahkan kolom ini secara manual saat meninjau skema.

Jika Penelusuran Agen menemukan kolom tambahan nanti dalam impor data, kolom ini akan tetap diimpor dan ditambahkan ke skema. Jika Anda ingin mengedit skema setelah semua data diimpor, lihat Memperbarui skema Anda.

Contoh skema sebagai objek JSON

Anda dapat menentukan skema sendiri menggunakan format Skema JSON , yang merupakan bahasa deklaratif open source untuk menentukan, memberi anotasi, dan memvalidasi dokumen JSON. Misalnya, ini adalah anotasi skema JSON yang valid:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Jika Anda menentukan skema media, Anda harus menyertakan kolom yang dapat dipetakan ke properti kunci media. Properti kunci ini ditampilkan dalam contoh ini.

Berikut beberapa kolom dalam contoh skema ini:

  • dynamic. Jika dynamic ditetapkan ke nilai string "true", properti baru yang ditemukan dalam data yang diimpor akan ditambahkan ke skema. Jika dynamic ditetapkan ke "false", properti baru yang ditemukan dalam data yang diimpor akan diabaikan; properti tidak ditambahkan ke skema dan nilainya tidak diimpor.

    Misalnya, skema memiliki dua properti: title dan description, dan Anda mengupload data yang berisi properti untuk title, description, dan rating. Jika dynamic adalah "true", properti dan data rating akan diimpor. Jika dynamic adalah "false", properti rating tidak akan diimpor, meskipun title dan description akan diimpor.

    Nilai default-nya adalah "true".

  • datetime_detection. Jika datetime_detection ditetapkan ke boolean true, saat data dalam format datetime diimpor, jenis skema akan ditetapkan ke datetime. Format yang didukung adalah RFC 3339 dan ISO 8601.

    Contoh:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    Jika datatime_detection ditetapkan ke boolean false, saat data dalam format datetime diimpor, jenis skema akan ditetapkan ke string.

    Nilai default-nya adalah true.

  • geolocation_detection. Jika geolocation_detection ditetapkan ke boolean true, saat data dalam format geolokasi diimpor, jenis skema akan ditetapkan ke geolocation. Data terdeteksi sebagai geolokasi jika merupakan objek yang berisi angka lintang dan angka bujur atau objek yang berisi string alamat.

    Contoh:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    Jika geolocation_detection ditetapkan ke boolean false, saat data dalam format geolokasi diimpor, jenis skema akan ditetapkan ke object.

    Nilai default-nya adalah true.

  • keyPropertyMapping. Kolom yang memetakan kata kunci yang telah ditentukan ke kolom penting dalam dokumen Anda, sehingga membantu memperjelas makna semantiknya. Nilai mencakup title, description, uri, category, update_time, dan create_time. Nama kolom Anda tidak harus cocok dengan nilai keyPropertyValues. Misalnya, untuk kolom yang Anda beri nama my_title, Anda dapat menyertakan keyPropertyValues kolom dengan nilai title.

    Untuk penyimpanan data penelusuran, kolom yang ditandai dengan keyPropertyMapping secara default dapat diindeks dan ditelusuri, tetapi tidak dapat diambil, diselesaikan, atau dynamicFacetable. Artinya, Anda tidak perlu menyertakan kolom indexable atau searchable dengan kolom keyPropertyValues untuk mendapatkan perilaku default yang diharapkan.

    Properti kunci dapat meningkatkan kualitas hasil penelusuran dan rekomendasi serta akurasi pelengkapan otomatis penelusuran. Jika Anda menggunakan deteksi otomatis skema, properti kunci tidak akan otomatis dipetakan dan Anda harus menambahkan pemetaan secara manual.

    Pemetaan kolom dokumen ke update_time (atau create_time sebagai pengganti) diperlukan untuk sinyal peringkat kustom document_age. Untuk mengetahui informasi selengkapnya tentang document_age, lihat Sinyal standar.

  • type. Jenis kolom. Ini adalah nilai string yang berupa datetime, geolocation, atau salah satu jenis primitif (integer, boolean, object, array, number, atau string).

Kolom properti berikut hanya berlaku untuk aplikasi penelusuran:

  • retrievable. Menunjukkan apakah kolom ini dapat ditampilkan dalam respons penelusuran. Kolom ini dapat ditetapkan untuk kolom berjenis number, string, boolean, integer, datetime, dan geolocation. Maksimum 50 kolom dapat ditetapkan sebagai retrievable. Kolom yang ditentukan pengguna dan kolom keyPropertyValues tidak dapat diambil secara default. Untuk membuat kolom dapat diambil, sertakan "retrievable": true dengan kolom tersebut.

  • indexable. Menunjukkan apakah kolom ini dapat difilter, difaset, ditingkatkan, atau diurutkan dalam metode servingConfigs.search. Kolom ini dapat ditetapkan untuk kolom berjenis number, string, boolean, integer, datetime, dan geolocation. Maksimum 50 kolom dapat ditetapkan sebagai indexable. Kolom yang ditentukan pengguna tidak dapat diindeks secara default, kecuali kolom yang berisi kolom keyPropertyMapping. Untuk membuat kolom dapat diindeks, sertakan "indexable": true dengan kolom tersebut.

  • dynamicFacetable. Menunjukkan bahwa kolom dapat digunakan sebagai faset dinamis. Kolom ini dapat ditetapkan untuk kolom berjenis number, string, boolean, dan integer. Agar kolom dapat difaset secara dinamis, kolom tersebut juga harus dapat diindeks: sertakan "dynamicFacetable": true dan "indexable": true dengan kolom tersebut.

  • searchable. Menunjukkan apakah kolom ini dapat diindeks terbalik agar cocok dengan kueri teks tidak terstruktur. Kolom ini hanya dapat ditetapkan untuk kolom berjenis string. Maksimum 50 kolom dapat ditetapkan sebagai searchable. Kolom yang ditentukan pengguna tidak dapat ditelusuri secara default, kecuali kolom yang berisi kolom keyPropertyMapping. Untuk membuat kolom dapat ditelusuri, sertakan "searchable": true dengan kolom tersebut.

  • completable. Menunjukkan apakah kolom ini dapat ditampilkan sebagai saran pelengkapan otomatis. Kolom ini hanya dapat ditetapkan untuk kolom berjenis string. Untuk membuat kolom dapat diselesaikan, sertakan "completable": true dengan kolom tersebut.

Selain itu, kolom berikut hanya berlaku untuk aplikasi rekomendasi:

  • recommendationsFilterable. Menunjukkan bahwa kolom dapat digunakan dalam ekspresi filter rekomendasi. Untuk mengetahui informasi umum tentang rekomendasi pemfilteran, lihat Memfilter rekomendasi.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

Menyediakan skema Anda sendiri sebagai objek JSON

Untuk menyediakan skema Anda sendiri, buat penyimpanan data yang berisi skema kosong, lalu perbarui skema tersebut dengan memberikan skema Anda sebagai objek JSON. Ikuti langkah-langkah berikut:

  1. Siapkan skema sebagai objek JSON, menggunakan Contoh skema sebagai objek JSON sebagai panduan.

  2. Buat penyimpanan data.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

    Ganti kode berikut:

    • PROJECT_ID: ID project Anda. Google Cloud
    • DATA_STORE_ID: ID penyimpanan data Penelusuran Agen yang ingin Anda buat. ID ini hanya dapat berisi huruf kecil, digit, garis bawah, dan tanda hubung.
    • DATA_STORE_DISPLAY_NAME: nama tampilan penyimpanan data Penelusuran Agen yang ingin Anda buat.
    • INDUSTRY_VERTICAL: GENERIC atau MEDIA

  3. Gunakan metode API schemas.patch 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. Google Cloud
    • DATA_STORE_ID: ID penyimpanan data Penelusuran Agen.

    • 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"
    }
  }
}

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

Langkah berikutnya