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
6. Mengindeks data
7. Menguji skema
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. Evaluasi berbagai kueri dari pengguna yang berbeda.
2. Identifikasi kumpulan data logis, atau objek, seperti "film."
3. Identifikasi 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 peringkat, seperti urutan kronologis atau rating penonton.
6. Identifikasi properti konteks, seperti peran pekerjaan, untuk meningkatkan saran pelengkapan otomatis.
7. Buat daftar objek, properti, dan nilai contoh ini. Gunakan daftar ini untuk menentukan opsi operator.

Menginisialisasi sumber data

Sumber data mewakili data repositori yang diindeks dan 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 contoh dengan dua objek dan satu sub-objek.

Sebuah 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 ini sebagai kunci. Lihat ObjectDefinition.

Catatan: Anda dapat mengabaikan operationIds yang ditampilkan saat meminta skema terdaftar ; ID tersebut merujuk ke 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 suatu objek harus unik, terlepas dari huruf besar kecilnya.

PropertyDefinition mencakup:

• String name.
• Opsi jenis agnostik (mis., isReturnable).
• Jenis dan opsi khusus jenis (mis., 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 akan 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 ditetapkan ke false dan harus ditetapkan ke true agar dapat digunakan.

• isReturnable: Tetapkan 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: Tetapkan ke true jika properti dapat memiliki beberapa nilai. Misalnya, sebuah film memiliki satu tanggal rilis, tetapi beberapa aktor.
• isSortable: Tetapkan ke true jika properti dapat digunakan untuk pengurutan. Tidak dapat ditetapkan ke true jika isRepeatable ditetapkan ke true atau jika properti berada di dalam sub-objek berulang.
• isFacetable: Tetapkan ke true jika properti dapat digunakan untuk membuat facet (atribut yang digunakan untuk memfilter hasil penelusuran).
  • Memerlukan isReturnable untuk ditetapkan ke true.
  • Hanya didukung untuk properti enum, boolean, dan teks.
• isWildcardSearchable: Tetapkan ke true untuk mengizinkan pengguna melakukan penelusuran karakter pengganti pada properti ini. Opsi ini hanya tersedia pada properti teks dan perilakunya bergantung pada setelan exactMatchWithOperator:
  • Jika exactMatchWithOperator ditetapkan ke true: Nilai teks akan diperlakukan sebagai satu token. Kueri seperti science-* cocok dengan nilai science-fiction.
  • Jika exactMatchWithOperator ditetapkan ke false: Nilai teks akan di-tokenisasi. Kueri seperti sci* atau fi* cocok dengan science-fiction, tetapi science-* tidak.

Menentukan jenis

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

Menentukan opsi operator

operatorOptions menjelaskan fungsi properti sebagai operator penelusuran.

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

Setiap operatorOptions memerlukan operatorName (mis., title). Ini adalah parameter yang diketik pengguna dalam kueri (mis., 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 dalam hasil penelusuran.

Menambahkan operator pemfilteran saran

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

Mendaftarkan skema

Daftarkan skema Anda dengan layanan skema menggunakan ID sumber data. 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 Indeks panggilan, 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

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

• Kueri umum: Telusuri string (mis., "titanic") untuk melihat semua item yang cocok.
• Kueri operator: Gunakan operator (mis., 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 untuk 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 data atau nama properti.
• Setelan exactMatchWithOperator atau retrievalImportance.

Membuat perubahan skema yang kompleks

Untuk membuat 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 menggunakan properti baru saja.
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. Membuat antarmuka penelusuran.
2. Meningkatkan kualitas penelusuran.
3. Buat struktur skema untuk mendapatkan interpretasi kueri yang optimal.
4. Menentukan sinonim.