Membuat dan mendaftarkan skema

Skema Google Cloud Search adalah struktur JSON yang menentukan objek, properti, dan opsi untuk mengindeks dan membuat kueri data. Konektor konten Anda menggunakan skema terdaftar untuk menyusun dan mengindeks data repositori.

Anda membuat skema dengan memberikan objek skema JSON ke API. Anda harus mendaftarkan skema untuk setiap repositori sebelum mengindeks data.

Catatan: Anda tidak memerlukan skema untuk data tidak terstruktur, seperti sistem berbagi file dasar tanpa jenis file yang telah ditentukan. Anda juga dapat menggunakan SDK untuk membuat objek skema.

Dokumen ini membahas dasar-dasar pembuatan skema. Untuk mengoptimalkan pengalaman penelusuran, lihat Meningkatkan kualitas penelusuran.

Membuat skema

Ikuti langkah-langkah berikut untuk membuat skema Cloud Search:

1. Mengidentifikasi perilaku pengguna yang diharapkan
2. Menginisialisasi sumber data
3. Menentukan objek Anda
4. Menentukan properti objek
5. Mendaftarkan skema Anda
6. Mengindeks data Anda
7. Menguji skema Anda
8. Menyesuaikan skema

Catatan: Dokumen ini menggunakan skema database film hipotetis. Lihat schema.json untuk contoh lengkapnya.

Mengidentifikasi perilaku pengguna yang diharapkan

Mengantisipasi cara pengguna melakukan penelusuran akan membantu menentukan strategi skema Anda. Untuk database film, pengguna mungkin menelusuri "film yang dibintangi Robert Redford". Skema Anda harus mendukung kueri untuk film dengan aktor tertentu.

Untuk menyelaraskan skema Anda dengan perilaku pengguna:

1. Mengevaluasi beragam kueri dari pengguna yang berbeda.
2. Identifikasi set data logis, atau objek, seperti "film".
3. Mengidentifikasi properti (atribut) seperti judul atau tanggal rilis.
4. Identifikasi nilai yang valid untuk properti, seperti "Raiders of the Lost Ark".
5. Tentukan kebutuhan pengurutan dan pembuatan peringkat, seperti urutan kronologis atau peringkat audiens.
6. Mengidentifikasi properti konteks, seperti peran pekerjaan, untuk meningkatkan kualitas saran pelengkapan otomatis.
7. Buat daftar objek, properti, dan nilai contoh ini. Gunakan daftar ini untuk menentukan opsi operator.

Menginisialisasi sumber data Anda

Sumber data mewakili data repositori terindeks yang disimpan di Google Cloud. Lihat Mengelola sumber data pihak ketiga. Saat pengguna mengklik hasil, Cloud Search akan mengarahkannya ke item menggunakan URL dari permintaan pengindeksan.

Menentukan objek Anda

Objek adalah unit dasar skema. Struktur logis seperti "film" atau "orang" adalah objek. Setiap objek memiliki properti seperti judul, durasi, atau nama.

Gambar 1. Skema sampel dengan dua objek dan satu sub-objek.

Skema adalah daftar definisi objek dalam tag objectDefinitions.

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

Gunakan nama unik untuk setiap objek, seperti movie. Layanan skema menggunakan nama-nama ini sebagai kunci. Lihat ObjectDefinition.

Catatan: Anda dapat mengabaikan operationIds yang ditampilkan saat meminta skema terdaftar; operationIds tersebut merujuk pada operasi yang tertunda.

Menentukan properti objek

Tentukan properti, seperti judul dan tanggal rilis, di bagian propertyDefinitions. Gunakan options untuk freshnessOptions (peringkat) dan displayOptions (label UI).

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

Catatan: Nama properti dalam objek harus unik, terlepas dari huruf besar/kecilnya.

PropertyDefinition mencakup:

• String name.
• Opsi agnostik jenis (misalnya, isReturnable).
• Jenis dan opsi khusus jenis (misalnya, textPropertyOptions).
• operatorOptions untuk operator penelusuran.
• displayOptions untuk label UI.

Anda dapat menggunakan kembali nama properti di berbagai objek. Misalnya, movieTitle dapat muncul di objek movie dan filmografi objek person.

Catatan: Cloud Search menghapus kolom yang tidak terdaftar selama pengindeksan dan menolak permintaan dengan jenis data yang salah.

Menambahkan opsi jenis agnostik

PropertyDefinition mencakup opsi boolean untuk mengonfigurasi fungsi penelusuran untuk properti, terlepas dari jenisnya. Opsi ini secara default adalah false dan harus disetel ke true agar dapat digunakan.

• isReturnable: Setel ke true jika data properti harus ditampilkan dalam hasil penelusuran menggunakan Query API. Properti yang tidak dapat ditampilkan dapat digunakan untuk menelusuri atau memberi peringkat tanpa muncul di hasil.
• isRepeatable: Setel ke true jika properti dapat memiliki beberapa nilai. Misalnya, suatu film memiliki satu tanggal rilis tetapi beberapa aktor.
• isSortable: Tetapkan ke true jika properti dapat digunakan untuk penyortiran. Tidak boleh berupa true jika isRepeatable adalah true atau jika properti berada di dalam sub-objek berulang.
• isFacetable: Setel ke true jika properti dapat digunakan untuk membuat aspek (atribut yang digunakan untuk mempertajam hasil penelusuran).
  • Memerlukan isReturnable menjadi true.
  • Hanya didukung untuk properti enumerasi, boolean, dan teks.
• isWildcardSearchable: Setel ke true untuk mengizinkan pengguna melakukan penelusuran karakter pengganti pada properti ini. Opsi ini hanya tersedia di properti teks dan perilakunya bergantung pada setelan exactMatchWithOperator:
  • Jika exactMatchWithOperator adalah true: Nilai teks diperlakukan sebagai satu token. Kueri seperti science-* cocok dengan nilai science-fiction.
  • Jika exactMatchWithOperator adalah false: Nilai teks di-tokenisasi. Kueri seperti sci* atau fi* cocok dengan science-fiction, tetapi science-* tidak cocok.

Menentukan jenis

Tetapkan jenis data dengan menentukan objek opsi properti yang sesuai (misalnya, textPropertyOptions). Gunakan enum (enumPropertyOptions) jika Anda mengetahui semua kemungkinan nilai. Properti hanya dapat memiliki satu jenis data.

Menentukan opsi operator

operatorOptions menjelaskan cara kerja properti sebagai operator penelusuran.

Peringatan: Tetapkan retrievalImportance ke DEFAULT kecuali jika Anda yakin bahwa properti memerlukan peringkat yang lebih tinggi. Anda tidak dapat mengubah setelan ini nanti.

Setiap operatorOptions memerlukan operatorName (misalnya, title). Ini adalah parameter yang dimasukkan pengguna dalam kueri (misalnya, title:titanic). Gunakan nama yang intuitif dan tampilkan kepada pengguna.

Anda dapat membagikan operatorName di seluruh properti dengan jenis yang sama. Kueri yang menggunakan nama tersebut akan mengambil hasil dari semua properti yang cocok.

Properti yang dapat diurutkan dapat mencakup lessThanOperatorName dan greaterThanOperatorName untuk kueri perbandingan. Properti teks dapat menggunakan exactMatchWithOperator untuk memperlakukan seluruh nilai sebagai satu token.

Menambahkan opsi tampilan

Bagian displayOptions opsional berisi displayLabel. Ini adalah label yang mudah digunakan dan ditampilkan di hasil penelusuran.

Menambahkan operator pemfilteran saran

Gunakan suggestionFilteringOperators[] untuk menentukan properti yang memfilter saran pelengkapan otomatis (misalnya, memfilter saran film menurut genre pilihan pengguna). Anda hanya dapat menentukan satu filter saran.

Mendaftarkan skema

Daftarkan skema Anda ke layanan skema menggunakan ID sumber data Anda. Kirimkan permintaan UpdateSchema:

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

Gunakan validateOnly: true untuk menguji skema tanpa mendaftarkannya.

Mengindeks data

Setelah pendaftaran, isi sumber data menggunakan panggilan Indeks, biasanya dengan konektor.

Contoh permintaan pengindeksan:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "metadata": {
    "title": "Titanic",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [{
        "name": "movieTitle",
        "textValues": { "values": ["Titanic"] }
      }]
    }
  },
  "itemType": "CONTENT_ITEM"
}

Catatan: objectType harus cocok dengan nama objek skema. Nama properti dalam permintaan harus cocok dengan huruf besar kecil skema.

Menguji skema

Lakukan pengujian dengan repositori kecil sebelum produksi. Buat ACL yang membatasi hasil untuk pengguna uji.

• Kueri umum: Menelusuri string (misalnya, "titanic") untuk melihat semua item yang cocok.
• Kueri operator: Gunakan operator (misalnya, actor:Zane) untuk membatasi hasil.

Menyesuaikan skema

Pantau masukan pengguna dan sesuaikan skema Anda. Anda dapat mengindeks kolom baru atau mengganti nama operator agar lebih intuitif.

Mengindeks ulang setelah perubahan skema

Anda tidak perlu mengindeks ulang agar perubahan pada:

• Nama operator.
• Batas numerik.
• Peringkat berurutan.
• Opsi keaktualan atau tampilan.

Anda harus mengindeks ulang untuk:

• Menambahkan atau menghapus properti atau objek.
• Mengubah isReturnable, isFacetable, atau isSortable menjadi true.
• Menandai properti isSuggestable.

Perubahan properti yang tidak diizinkan

Perubahan yang merusak indeks atau menyebabkan hasil yang tidak konsisten tidak diizinkan, termasuk:

• Jenis atau nama data properti.
• exactMatchWithOperator atau retrievalImportance.

Membuat perubahan skema yang kompleks

Untuk melakukan perubahan yang tidak diizinkan, migrasikan properti dari definisi lama ke definisi baru:

1. Tambahkan properti baru dengan nama yang berbeda ke skema.
2. Daftarkan skema dengan properti baru dan lama.
3. Isi ulang indeks hanya menggunakan properti baru.
4. Hapus properti lama dari skema.
5. Perbarui kode kueri Anda untuk menggunakan nama properti baru.

Cloud Search mencatat item yang dihapus selama 30 hari untuk mencegah masalah penggunaan kembali.

Batasan ukuran

• Maksimum 10 objek tingkat atas.
• Kedalaman maksimum 10 tingkat.
• Maksimum 1.000 kolom per objek (termasuk kolom bertingkat).

Langkah Berikutnya

1. Buat antarmuka penelusuran.
2. Meningkatkan kualitas penelusuran.
3. Buat struktur skema untuk mendapatkan interpretasi kueri yang optimal.
4. Menentukan sinonim.