Kueri dan Opsi Pengurutan

API ini didukung untuk runtime generasi pertama dan dapat digunakan saat mengupgrade ke runtime generasi kedua yang sesuai. Jika Anda mengupdate ke runtime App Engine Java 11/17, lihat panduan migrasi guna mempelajari opsi migrasi untuk layanan paket lama.

Saat Anda memanggil metode search() hanya dengan string kueri, hasilnya akan ditampilkan sesuai dengan opsi kueri default:

• Dokumen ditampilkan dengan urutan menurun
• Dokumen ditampilkan dalam kelompok yang terdiri dari 20 dokumen sekaligus
• Dokumen yang diambil berisi semua kolom aslinya

Anda dapat menggunakan instance class Query sebagai argumen untuk search() guna mengubah opsi ini.

Class Query memungkinkan Anda menentukan jumlah dokumen yang ditampilkan sekaligus. Selain itu, Anda juga dapat menyesuaikan konten dokumen yang diambil. Anda dapat meminta ID dokumen saja, atau meminta agar dokumen hanya berisi subset kolomnya. Anda juga dapat membuat kolom kustom dalam dokumen yang diambil: cuplikan (fragmen kolom teks yang menunjukkan teks yang mengelilingi string yang cocok), dan kolom ekspresi (kolom dengan nilai yang berasal dari kolom lain dalam dokumen).

Selain opsi kueri, class Kueri juga dapat menyertakan instance class SortOptions. Dengan opsi pengurutan, Anda dapat mengubah tata urutan dan mengurutkan hasil dengan beberapa kunci.

Menelusuri dengan class Query

Saat melakukan penelusuran dengan instance class Kueri, Anda harus membuat instance class dalam beberapa langkah. Berikut ini urutan umumnya:

1. Buat string kueri.
2. Buat SortOptions jika perlu.
3. Buat QueryOptions.
4. Buat objek Kueri yang menyertakan string kueri dan QueryOptions (opsional).
5. Panggil metode penelusuran pada objek Query.

Berbagai opsi kueri dan pengurutan ditentukan dengan memanggil metode penyetel pada instance class QueryOptions.Builder dan SortOptions.Builder, seperti dalam contoh ini:

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

Anda harus menggunakan QueryOptions.Builder untuk menetapkan opsi kueri. Anda tidak memiliki akses langsung ke properti ini.

Properti ini mengontrol berapa banyak hasil yang ditampilkan dan urutannya. Opsi offset dan kursor, yang sama-sama eksklusif, mendukung penomoran halaman. Kolom ini menentukan dokumen terpilih mana yang akan ditampilkan dalam hasil.

Properti	Deskripsi	Default	Maksimum
Limit	Jumlah dokumen maksimum yang akan ditampilkan dalam hasil.	20	1000
NumberFoundAccuracy	Properti ini menentukan akurasi hasil yang ditampilkan oleh Results.getNumberFound(). Batas ini menetapkan batas jumlah kecocokan yang benar-benar dihitung, sehingga menghentikan penelusuran saat batas tersebut tercapai. Jika jumlah kecocokan dalam indeks kurang dari atau sama dengan batas, jumlah yang ditampilkan adalah akurat. Jika tidak, jumlahnya adalah perkiraan berdasarkan kecocokan yang ditemukan dan ukuran serta struktur indeks. Perhatikan bahwa menetapkan nilai tinggi untuk properti ini dapat memengaruhi kompleksitas operasi penelusuran dan dapat menyebabkan waktu tunggu habis.	Jika akurasi yang tidak ditentukan disetel ke nilai yang sama dengan Limit	25000
Offset	Offset dokumen pertama dalam hasil yang ditampilkan.	0. Hasil akan berisi semua dokumen yang cocok (hingga batas).	1.000
Cursor	Kursor dapat digunakan sebagai pengganti offset untuk mengambil kelompok dokumen secara urut. Kursor diperbarui saat diteruskan ke dan keluar dari kueri berturut-turut, sehingga setiap penelusuran baru dilanjutkan dari akhir penelusuran sebelumnya. Kursor dan offset dibahas di halaman Menangani Hasil.	Null. Hasil akan berisi semua dokumen yang cocok (hingga batas).	-
SortOptions	Tetapkan objek SortOptions untuk mengontrol urutan hasil penelusuran. Instance SortOptions memiliki kumpulan propertinya sendiri yang dijelaskan di bawah.	Null. Urutkan dengan menurunkan peringkat dokumen.	-

Properti ini mengontrol kolom dokumen yang muncul dalam hasil.

Properti	Deskripsi	Default
ReturningIdsOnly	Tetapkan ke True atau False. Jika True, dokumen yang ditampilkan dalam hasil hanya akan berisi ID, tanpa kolom.	False (menampilkan semua kolom).
FieldsToReturn	Menentukan kolom dokumen yang akan disertakan dalam hasil. Maksimal 100 kolom dapat ditentukan.	Tampilkan semua kolom dokumen (hingga 100 kolom).
ExpressionsToReturn	Ekspresi kolom yang menjelaskan kolom komputasi yang ditambahkan ke setiap dokumen yang ditampilkan di hasil penelusuran. Kolom ini ditambahkan ke properti ekspresi dokumen. Nilai kolom ditentukan dengan menulis ekspresi yang dapat mencakup satu atau beberapa kolom dokumen.	Tidak ada
FieldsToSnippet	Daftar nama kolom teks. Cuplikan dibuat untuk setiap kolom. Ini adalah kolom komputasi yang ditambahkan ke properti ekspresi dari dokumen di hasil penelusuran. Kolom cuplikan memiliki nama yang sama dengan kolom sumbernya. Opsi ini secara implisit menggunakan fungsi cuplikan dengan hanya dua argumen, sehingga membuat cuplikan dengan maksimal satu string yang cocok, berdasarkan string kueri yang sama dengan penelusuran yang digunakan untuk mengambil hasil: snippet("query-string", field-name). Anda juga dapat membuat cuplikan yang disesuaikan menggunakan opsi ExpressionsToReturn dengan menambahkan ekspresi kolom yang secara eksplisit memanggil fungsi cuplikan ini.	Tidak ada

SortOptions

Properti SortOptions mengontrol pengurutan dan penskoran hasil penelusuran. Anda harus menggunakan SortOptions.Builder untuk menetapkan opsi pengurutan. Anda tidak memiliki akses langsung ke properti ini.

Properti SortOptions mengontrol pengurutan dan penskoran hasil penelusuran.

Properti	Deskripsi	Default
SortExpressions	Daftar SortExpressions yang menampilkan jenis Dokumen multi-dimensi.	Tidak ada
MatchScorer	Objek MatchScorer opsional. Jika ada, atribut ini akan menyebabkan dokumen diberi skor sesuai dengan frekuensi istilah penelusuran. Skor akan tersedia sebagai kolom _score. Penskoran dokumen mungkin saja mahal (baik dalam operasi yang ditagih maupun waktu eksekusi) dan dapat memperlambat penelusuran Anda. Gunakan penskoran seperlunya.	Tidak ada
Limit	Jumlah maksimum objek yang akan dinilai dan/atau diurutkan. Tidak boleh lebih dari 10.000.	1.000

Mengurutkan pada beberapa kunci

Anda dapat mengurutkan hasil penelusuran di beberapa kunci pengurutan. Setiap kunci dapat berupa nama kolom sederhana, atau nilai yang dihitung dari beberapa kolom. Perlu diperhatikan bahwa istilah 'ekspresi' digunakan dengan beberapa arti saat berbicara tentang opsi pengurutan: SortOption sendiri memiliki atribut ekspresi. Atribut ini adalah daftar objek SortExpression yang sesuai dengan kunci pengurutan. Terakhir, setiap objek SortExpression berisi atribut ekspresi yang menentukan cara menghitung nilai kunci pengurutan. Ekspresi ini dibuat sesuai dengan aturan di bagian berikutnya.

SortExpression juga menentukan arah pengurutan dan nilai kunci default yang akan digunakan jika ekspresi tidak dapat dihitung untuk sebuah dokumen. Berikut daftar lengkap properti:

Properti	Deskripsi	Default
Expression	Ekspresi yang akan dievaluasi saat mengurutkan hasil untuk setiap dokumen yang cocok.	Tidak ada
Direction	Perintah untuk mengurutkan hasil penelusuran, baik ASCENDING atau DESCENDING.	DESCENDING
DefaultValue DefaultValueDate DefaultValueNumber	Nilai default ekspresi, jika tidak ada kolom dan tidak dapat dihitung untuk dokumen. Nilai teks harus ditentukan untuk pengurutan teks. Nilai numerik harus ditetapkan untuk urutan numerik.	Tidak ada

Mengurutkan di kolom multinilai

Saat Anda mengurutkan di kolom multinilai dari jenis tertentu, hanya nilai pertama yang ditetapkan ke kolom tersebut yang digunakan. Misalnya, pertimbangkan dua dokumen, DocA dan DocB yang keduanya memiliki kolom teks bernama "color". Dua nilai ditetapkan untuk kolom "color" DocA dalam urutan (red, blue), dan dua nilai untuk DocB dalam urutan (green, red). Saat Anda melakukan pengurutan yang menentukan kolom teks "color", DocA diurutkan pada nilai "red" dan DocB pada nilai "green". Nilai kolom lainnya tidak digunakan dalam pengurutan.

Mengurutkan atau tidak mengurutkan

Jika Anda tidak menentukan opsi pengurutan apa pun, hasil penelusuran akan otomatis ditampilkan berdasarkan peringkat menurun. Tidak ada batasan jumlah dokumen yang ditampilkan dalam kasus ini. Jika Anda menentukan opsi pengurutan, pengurutan akan dilakukan setelah semua dokumen yang cocok dipilih. Ada properti eksplisit, `SortOptions.limit`, yang mengontrol ukuran pengurutan. Anda tidak pernah bisa mengurutkan lebih dari 10.000 dokumen, defaultnya adalah 1.000. Jika ada lebih banyak dokumen yang cocok daripada jumlah yang ditentukan oleh `SortOptions.limit`, penelusuran hanya akan mengambil, mengurutkan, dan menampilkan angka terbatas tersebut. Opsi ini memilih dokumen untuk diurutkan dari daftar semua dokumen yang cocok, dalam urutan peringkat menurun. Ada kemungkinan bahwa kueri akan memilih lebih banyak dokumen yang cocok daripada yang dapat Anda urutkan. Jika menggunakan opsi pengurutan dan penting untuk mengambil setiap dokumen yang cocok, Anda harus memastikan bahwa kueri tidak akan menampilkan lebih banyak dokumen daripada yang bisa Anda urutkan.

Menulis ekspresi

Ekspresi digunakan untuk menentukan ekspresi kolom (yang ditetapkan dalam `QueryOptions`) dan mengurutkan ekspresi, yang ditetapkan di SortOptions. Fungsi tersebut ditulis sebagai string:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

Ekspresi yang melibatkan kolom Angka dapat menggunakan operator aritmatika (+, -, *, /) dan fungsi numerik bawaan yang tercantum di bawah. Ekspresi yang melibatkan kolom geopoint dapat menggunakan fungsi geopoint dan jarak. Ekspresi untuk kolom Teks dan HTML dapat menggunakan fungsi cuplikan.

Ekspresi juga dapat mencakup istilah khusus berikut:

Masa Berlaku	Deskripsi
_rank	Properti peringkat dokumen. Ini dapat digunakan dalam ekspresi kolom dan ekspresi pengurutan.
_score	Skor yang ditetapkan ke dokumen saat Anda menyertakan MatchScorer di SortOptions. Istilah ini hanya dapat muncul dalam ekspresi pengurutan; tidak dapat digunakan dalam ekspresi kolom.

Fungsi numerik

Ekspresi untuk menentukan nilai numerik untuk FieldExpressions dan SortExpressions dapat menggunakan fungsi bawaan ini. Argumen harus berupa angka, nama kolom, atau ekspresi yang menggunakan angka dan nama kolom.

Fungsi	Deskripsi	Contoh
max	Menampilkan argumen terbesarnya.	max(recommended_retail_price, discount_price, wholesale_price)
min	Menampilkan argumen terkecil darinya.	min(height, width, length)
log	Menampilkan logaritma natural.	log(x)
abs	Menampilkan nilai absolut.	abs(x)
pow	Dibutuhkan dua argumen numerik. Panggilan pow(x, y) menghitung nilai x yang dipangkatkan y.	pow(x, 2)
count	Menggunakan nama kolom sebagai argumennya. Menampilkan jumlah kolom dalam dokumen dengan nama tersebut. Perlu diingat bahwa dokumen dapat berisi beberapa kolom dari berbagai jenis dengan nama yang sama. Catatan: count hanya dapat digunakan di FieldExpressions. Pesan tidak dapat muncul di SortExpressions.	count(user)

Fungsi geopoint

Fungsi ini dapat digunakan untuk ekspresi yang melibatkan kolom geopoint.

Fungsi	Deskripsi	Contoh
geopoint	Menentukan geopoint berdasarkan lintang dan bujur.	geopoint(-31.3, 151.4)
distance	Menghitung jarak antara dua geopoint dalam satuan meter. Perhatikan bahwa salah satu dari kedua argumen tersebut dapat berupa nama kolom geopoint atau pemanggilan fungsi geopoint Namun, hanya satu argumen yang dapat menjadi nama kolom.	distance(geopoint(23, 134), store_location)

Cuplikan

Cuplikan adalah fragmen kolom teks yang cocok dengan string kueri dan menyertakan teks di sekitarnya. Cuplikan dibuat dengan memanggil fungsi snippet:

snippet(query, body, [max_chars])

query

String kueri yang dikutip yang menentukan teks yang akan ditemukan di kolom.

body

Nama kolom teks, HTML, atau atom.

max_chars

Jumlah karakter maksimum untuk ditampilkan dalam cuplikan. Argumen ini bersifat opsional; panjang defaultnya adalah 160 karakter.

Fungsi ini menampilkan string HTML. String berisi cuplikan nilai kolom isi, dengan teks yang cocok dengan kueri yang dicetak tebal.