Penelusuran dengan Faset

Penelusuran dengan faset memungkinan Anda dapat melampirkan informasi berkategori ke dokumen. Faset merupakan pasangan atribut/nilai. Misalnya, faset bernama "size" dapat memiliki nilai "small", "medium", dan "large".

Dengan menggunakan faset pada penelusuran, Anda dapat mengambil informasi ringkasan untuk membantu menyaring kueri dan "melihat perincian" hasil dalam serangkaian langkah.

Hal ini berguna untuk aplikasi seperti situs belanja, tempat Anda ingin menawarkan serangkaian filter bagi pelanggan untuk mempersempit produk yang ingin mereka lihat.

Data gabungan untuk suatu faset menunjukkan kepada Anda bagaimana nilai sebuah faset didistribusikan. Misalnya, faset "size" dapat muncul di banyak dokumen dalam kumpulan hasil. Data gabungan untuk faset tersebut mungkin menunjukkan bahwa nilai "small" muncul 100 kali, "medium" 300 kali, dan "large" 250 kali. Setiap pasangan faset/nilai mewakili sebagian dokumen dalam hasil kueri. Kunci, yang disebut penajaman, dikaitkan dengan setiap pasangan. Anda dapat menyertakan penajaman dalam kueri untuk mengambil dokumen yang cocok dengan string kueri dan yang memiliki nilai faset yang terkait dengan satu atau beberapa penajaman.

Saat melakukan penelusuran, Anda dapat memilih faset yang akan dikumpulkan dan ditampilkan bersama hasilnya, atau Anda dapat mengaktifkan penemuan faset untuk secara otomatis memilih faset yang paling sering muncul dalam dokumen.

Menambahkan faset ke dokumen

Tambahkan faset ke dokumen sebelum menambahkan dokumen ke indeks. Lakukan hal ini bersamaan dengan menentukan kolom dokumen:

package app

import (
    "appengine"
    "appengine/search"
    "net/http"
)

type ComputerDoc struct {
    Name      search.Atom
    Type      search.Atom `search:",facet"`
    RAMSizeGB float64     `search:",facet"`
}

func handlePut(w http.ResponseWriter, r *http.Request) {
    c := appengine.NewContext(r)
    index, err := search.Open("products")
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    _, err = index.Put(c, "doc1", &ComputerDoc{
        Name:      "x86",
        Type:      "computer",
        RAMSizeGB: 8.0,
    })
    // Handle err and write HTTP response.
}

Faset mirip dengan kolom dokumen; memiliki nama, dan mengambil satu nilai.

Nama faset mengikuti aturan yang sama dengan kolom dokumen: Nama peka huruf besar/kecil dan hanya boleh berisi karakter ASCII. Nama ini harus diawali dengan huruf dan dapat berisi huruf, angka, atau garis bawah. Nama tidak boleh lebih dari 500 karakter.

Nilai faset dapat berupa string atom (maksimal 500 karakter) atau angka (nilai floating point presisi ganda antara -2.147.483.647 dan 2.147.483.647).

Anda dapat menetapkan beberapa nilai ke suatu faset di satu dokumen dengan menambahkan faset yang berisi nama dan jenis yang sama berkali-kali, dengan menggunakan nilai yang berbeda setiap saat.

Tidak ada batasan jumlah nilai yang dapat dimiliki oleh faset. Selain itu, tidak ada batasan jumlah faset yang dapat Anda tambahkan ke dokumen atau jumlah faset yang diberi nama unik dalam indeks.

Perhatikan bahwa setiap kali Anda menggunakan faset, faset dapat mengambil nilai atomik atau numerik. Faset dengan nama "size" dapat dilampirkan ke satu dokumen dengan nilai string "small" dan dokumen lainnya dengan nilai numerik 8. Bahkan, faset yang sama dapat muncul beberapa kali dalam dokumen yang sama dengan kedua jenis nilai. Sebaiknya jangan gunakan nilai atom dan angka untuk faset yang sama meskipun diperbolehkan.

Meskipun faset memiliki jenis tertentu saat Anda menambahkannya ke dokumen, hasil penelusuran mengumpulkan semua nilainya bersama-sama. Misalnya, hasil untuk faset "size" mungkin menunjukkan bahwa ada 100 instance nilai "small", 150 instance "medium", dan 135 instance nilai numerik dalam rentang [4, 8 ). Nilai numerik yang tepat dan distribusi frekuensinya tidak ditampilkan.

Saat mengambil dokumen menggunakan kueri, Anda tidak dapat langsung mengakses faset dan nilainya. Anda harus mengajukan permintaan agar informasi faset ditampilkan dengan kueri, seperti yang dijelaskan di bagian berikutnya.

Menggunakan penelusuran dengan faset untuk mengambil informasi faset

Anda dapat meminta backend penelusuran untuk menemukan faset yang paling sering digunakan. Hal ini disebut penemuan faset otomatis. Anda juga dapat mengambil informasi faset secara eksplisit dengan memilih faset berdasarkan nama, atau berdasarkan nama dan nilai. Anda dapat memadupadankan ketiga jenis pengambilan faset dalam satu kueri.

Meminta informasi faset tidak akan memengaruhi dokumen yang ditampilkan oleh kueri. Hal ini dapat memengaruhi performa. Melakukan penelusuran dengan faset dengan kedalaman default 1000 memiliki efek yang sama dengan menetapkan batas pencetak opsi pengurutan ke 1000.

Penemuan faset otomatis

Penemuan faset otomatis mencari faset yang paling sering muncul dalam agregat di dokumen Anda. Misalnya, dokumen yang cocok dengan kueri Anda berisi faset "color" yang muncul 5 kali dengan nilai "red", 5 kali dengan nilai "white", dan 5 kali dengan warna "blue". Faset ini memiliki jumlah total 15. Untuk tujuan penemuan, maka akan diberi peringkat lebih tinggi daripada faset "shade" lain yang muncul dalam dokumen pencocokan yang sama dengan nilai "dark" sebanyak 6 kali dan nilai "light" 7 kali.

Anda harus mengaktifkan penemuan faset dengan menyetelnya di Kueri Anda:

func handleSearch(w http.ResponseWriter, r *http.Request) {
    index, err := search.Open("products")
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    it := index.Search(c, "name:x86", &search.SearchOptions{
        Facets: {
            search.AutoFacetDiscovery(0, 0),
        },
    })
    facets, err := it.Facets()
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    for _, results := range facets {
        for i, facet := range result {
            // The facet results are grouped by facet name.
            // Print the name of each group before its values.
            if i == 0 {
                fmt.Fprintf(w, "Facet %s:\n", facet.Name)
            }
            fmt.Fprintf(w, "    %v: count=%d", facet.Value, facet.Count)
        }
    }
}

Ketika Anda mengambil faset dengan penemuan, secara default hanya 10 nilai yang paling sering digunakan untuk sebuah faset yang akan ditampilkan. Anda dapat meningkatkan batas ini hingga 100 menggunakan parameter pertama menjadi AutoFacetDiscovery.

Perlu diperhatikan bahwa penemuan faset otomatis tidak dimaksudkan untuk menampilkan semua kemungkinan faset dan nilainya. Faset yang ditampilkan dari penemuan dapat bervariasi dari tiap dilakukan penemuan. Jika menginginkan kumpulan faset tetap, gunakan parameter return_facets pada kueri Anda.

Nilai string akan ditampilkan satu per satu. Nilai numerik dari faset yang ditemukan ditampilkan dalam satu rentang [min maks). Anda dapat memeriksa rentang ini dan membuat subrentang yang lebih kecil untuk kueri berikutnya.

Memilih faset berdasarkan nama

Untuk mengambil informasi tentang faset berdasarkan namanya saja, tambahkan FacetDiscovery dengan nama faset tersebut ke opsi penelusuran untuk kueri Anda:

it := index.Search(c, "name:x86", &search.SearchOptions{
    Facets: {
        FacetDiscovery("Type"),
        FacetDiscovery("RAMSizeGB"),
    },
})

Ketika Anda mengambil faset berdasarkan nama, hanya 10 nilai yang paling sering muncul untuk sebuah faset yang akan ditampilkan.

Memilih faset berdasarkan nama dan nilai

Untuk mengambil informasi hanya tentang nilai tertentu dari sebuah faset, tambahkan FacetDiscovery dengan nama faset dan nilai minatnya:

it := index.Search(c, "name:x86", &search.SearchOptions{
    Facets: {
        // Fetch the "Type" facet with Values "computer" and "printer"
        FacetDiscovery("Type",
            search.Atom("computer"),
            search.Atom("printer"),
        ),
        // Fetch the "RAMSizeGB" facet with values in the ranges [0, 4), [4, 8), and [8, max]
        FacetDiscovery("RAMSizeGB",
            search.Range{Start: 0, End: 4},
            search.Range{Start: 4, End: 8},
            search.AtLeast(8),
        ),
    },
})

Semua nilai dalam satu FacetDiscovery harus berjenis sama, baik daftar nilai search.Atom maupun untuk angka, daftar search.Range yang merupakan interval yang ditutup di kiri (awal), dan buka di kanan (akhir). Jika faset Anda memiliki campuran nilai string dan angka, tambahkan opsi FacetDisovery terpisah untuk masing-masing.

Opsi

Anda dapat mengontrol jumlah minimum dokumen yang akan dievaluasi untuk mengumpulkan informasi faset dengan menambahkan opsi FacetDocumentDepth di SearchOptions untuk kueri Anda. Jika tidak ditentukan, kedalaman ini akan ditetapkan secara default ke 1000.

Perhatikan bahwa kedalaman faset biasanya jauh lebih besar dari batas kueri. Hasil faset dihitung berdasarkan setidaknya jumlah kedalaman dokumen. Jika Anda telah menetapkan batas penskoran opsi pengurutan lebih tinggi dari kedalaman, batas penskoran akan digunakan.

Mengambil hasil faset

Saat Anda menggunakan parameter penelusuran dengan faset dalam kueri, informasi faset yang digabungkan akan muncul bersama hasil kueri itu sendiri.

Penelusuran Iterator memiliki metode Facets, yang menampilkan informasi faset gabungan sebagai [][]FacetResult. Hasilnya diatur sehingga ada satu bagian hasil faset untuk setiap faset yang muncul dalam dokumen yang cocok dengan kueri Anda. Untuk setiap hasil, Anda akan mendapatkan:

  • Nama faset
  • Satu nilai untuk faset dari daftar nilai yang paling sering digunakan
  • Perkiraan jumlah frekuensi munculnya nilai tersebut

Perhatikan bahwa daftar nilai akan menyertakan string dan nilai numerik faset. Jika faset ditemukan secara otomatis, nilai numeriknya akan ditampilkan sebagai satu interval [min maks). Jika Anda secara eksplisit meminta faset numerik dengan satu atau beberapa rentang dalam kueri, daftar akan berisi satu interval tertutup-terbuka [awal akhir) untuk setiap rentang.

Daftar nilai faset mungkin tidak menyertakan semua nilai yang ditemukan dalam dokumen Anda, karena opsi kueri menentukan berapa banyak dokumen yang akan diperiksa dan berapa banyak nilai yang akan ditampilkan.

Informasi gabungan untuk setiap faset dapat dibaca dari iterator:

it := index.Search(...)
facets, err := it.Facets()  // And check err != nil.
for _, results := range facets {
    for _, facet := range results {
        ...
    }
}

Misalnya, suatu kueri dapat menemukan dokumen yang menyertakan faset "size" dengan nilai string dan nilai numerik. Hasil untuk faset ini akan disusun seperti ini:

[][]search.FacetResult{
    {
        {Name: "size", Value: search.Range{Start: 8, End: 10}, Count: 22},
        {Name: "size", Value: search.Atom("small"), Count: 100},
        {Name: "size", Value: search.Atom("medium"), Count: 300},
        {Name: "size", Value: search.Atom("large"), Count: 250},
    },
}

Menggunakan faset untuk menyaring/memfilter kueri

Setiap FacetResult dapat digunakan untuk lebih mempersempit hasil agar hanya menyertakan dokumen yang memiliki nilai faset tersebut. Untuk menyaring kueri dengan satu atau beberapa kunci ini, teruskan sebagai opsi penelusuran:

it := index.Search(c, "...", &search.SearchOptions{
    Refinements: []search.Facet{
        facetResult1.Facet,
        facetResult2.Facet,
    },
})

Anda dapat menggabungkan penajaman untuk satu atau beberapa faset yang berbeda dalam permintaan yang sama. Semua penajaman yang dimiliki faset yang sama digabungkan dengan OR. Penajaman untuk faset yang berbeda digabungkan dengan AND.

Anda juga dapat membuat Facet kustom secara manual untuk digunakan sebagai penajaman. Lihat referensi untuk informasi selengkapnya.