String Kueri

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

String kueri berisi karakter Unicode. Panjang maksimum string kueri adalah 2.000 karakter. Semua string kueri berisi setidaknya satu nilai kolom. Sebaiknya tulis nilai kolom menggunakan huruf kecil, karena penelusuran pada kolom atom, teks, dan HTML tidak peka huruf besar/kecil, dan string kueri juga dapat berisi operator boolean AND, OR, dan NOT, yang dikenali dengan menuliskannya menggunakan huruf besar.

Koma dapat muncul dalam string kueri hanya jika digunakan untuk memisahkan argumen suatu fungsi: distance(home, geopoint(35.2, 40.5)) > 100 atau merupakan bagian dari string dalam tanda petik.

String kueri dapat memiliki berbagai bentuk. Ada dua cara utama untuk mengonstruksi kueri: dengan dan tanpa nama kolom. Penelusuran global menggunakan string kueri yang hanya berisi nilai kolom:

query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"

Penelusuran kolom menggunakan string kueri yang berisi satu atau beberapa ekspresi yang menentukan nama kolom dan nilai kolom:

query = "model:gibson date < 1965-01-01"
query = "title:\"Harry Potter\" AND pages<500"
query = "beverage:wine color:(red OR white) NOT country:france"

Dokumen ini menjelaskan cara mengonstruksi string kueri untuk penelusuran global dan kolom, serta cara kerja logika penelusuran dalam setiap kasus.

Sebaiknya lakukan logging string kueri dalam aplikasi Anda jika Anda ingin menyimpan data kueri yang telah dieksekusi.

Penelusuran global

Penelusuran global menawarkan kemampuan untuk menelusuri dokumen dengan menentukan nilai yang mungkin muncul di kolom dokumen apa pun. Untuk melakukan penelusuran global, tulis string kueri yang berisi satu atau beberapa nilai kolom. Algoritma penelusuran mengenali jenis setiap nilai dan menelusuri semua kolom dokumen yang dapat berisi nilai tersebut.

Kueri satu nilai

Penelusuran dengan string kueri yang berisi satu nilai ditangani sesuai dengan aturan berikut:

Jika string kueri berupa kata (red) atau string dalam tanda petik ("red rose"), penelusuran akan mengambil semua dokumen dalam indeks yang memiliki:

• Teks atau kolom HTML yang berisi kata atau string dalam tanda petik tersebut (pencocokan tidak peka huruf besar/kecil).
• Kolom atom yang nilainya cocok dengan kata atau string yang diberi tanda kutip tersebut (pencocokan tidak peka huruf besar/kecil).

Jika string kueri berupa angka ("3.14159"), penelusuran akan mengambil semua dokumen yang memiliki:

• Kolom angka dengan nilai yang sama dengan angka dalam kueri (kolom angka dengan nilai 5 akan cocok dengan kueri "5" dan "5.0").
• Kolom teks atau HTML yang berisi token yang cocok dengan angka seperti yang muncul dalam kueri (kolom teks "he took 5 minutes" akan cocok dengan kueri "5", tetapi bukan "5.0").
• Kolom atom yang secara literal cocok dengan angka seperti yang muncul dalam kueri.

Jika string kueri berupa tanggal dalam format yyyy-mm-dd, penelusuran akan mengambil semua dokumen yang memiliki:

• Kolom tanggal yang nilainya sama dengan tanggal tersebut (angka nol di depan string kueri bersifat opsional, "2012-07-04" dan "2012-7-4" adalah tanggal yang sama).
• Kolom teks atau HTML berisi token yang secara literal cocok dengan tanggal yang muncul dalam kueri.
• Kolom atom yang secara literal cocok dengan tanggal yang muncul dalam kueri.

Anda dapat menambahkan operator boolean NOT (huruf besar) ke kueri satu kata. Hasilnya adalah daftar dokumen yang tidak memiliki kolom yang cocok dengan nilai kueri, berdasarkan aturan yang sama. Jadi, kueri NOT red akan mengambil semua dokumen yang tidak memiliki kolom HTML atau teks apa pun yang berisi "red", atau kolom atom apa pun dengan nilai red.

Anda mungkin memperhatikan bahwa kolom titik geografis belum disebutkan. Saat ini, Anda tidak dapat menentukan nilai titik geografis mentah sebagai string, sehingga titik geografis tidak dapat muncul dalam penelusuran global.

Kueri multi-nilai

Anda dapat menentukan beberapa nilai (dipisahkan dengan spasi) dalam string penelusuran global. Spasi kosong antara kata, string dalam tanda petik, angka, dan tanggal diperlakukan sebagai operator AND implisit. Kedua string penelusuran di bawah ini hampir sama; string ini berbeda dalam cara penelusuran global memperlakukan kolom atom, yang dijelaskan di bawah:

query = "small red"
query = "small AND red"

Saat melakukan penelusuran global dengan beberapa nilai, pencocokan kolom dilakukan secara independen pada setiap nilai dalam string, dan pencocokan kolom atom ditangani secara berbeda, khususnya:

• Nilai kueri dapat muncul dalam urutan apa pun di kolom teks atau HTML.
• Nilai yang berbeda dapat muncul di kolom yang berbeda.
• Kolom atom ditelusuri hanya jika string kueri tidak berisi operator boolean apa pun (AND, OR, NOT). Seluruh string kueri harus cocok dengan kolom atom.

Perhatikan aturan ketiga yang berkaitan dengan kolom atom. String kueri "red small" tidak berisi boolean AND (meskipun tersirat), sehingga penelusuran akan mencoba menemukan kolom atom yang cocok. String "red AND small" berisi operator boolean, sehingga penelusuran tidak akan mencoba mencocokkan string kueri dengan kolom atom.

Contoh berikut menampilkan empat dokumen yang diambil menggunakan string kueri "rose bud". Setiap dokumen memiliki dua kolom teks dan satu kolom atom. Kolom komentar menjelaskan alasan setiap dokumen memenuhi kueri.

Doc ID	Kolom Teks 1	Kolom Teks 2	Kolom Atom	Komentar
1	mighty like a rose	one bud to bind them all	thorn bush	Nilai yang cocok dapat muncul di kolom yang berbeda.
2	wide like a river	like a bud on a rose	tumble weed	Nilai yang cocok dapat muncul dalam urutan apa pun di kolom teks atau HTML yang sama, dengan teks intervensi
3	deep like the ocean	the rose bud boys	blue bonnet	Nilai yang cocok dapat muncul dalam urutan apa pun di kolom HTML atau teks yang sama
4	tall like a mountain	the beautiful garden	rose bud	Kolom atom cocok karena nilainya sama dengan seluruh string kueri

Perhatikan bahwa jika Anda membalikkan nilai dalam kueri dan menelusuri "bud rose", dokumen 1, 2, dan 3 akan tetap ditampilkan, namun dokumen 4 tidak akan ditampilkan. Untuk mencari string karakter yang sama persis di kolom atom, teks, dan HTML, tempatkan string tersebut dalam tanda petik pada string kueri. Penelusuran untuk "rose bud" hanya akan menampilkan dokumen 3 dan 4 dalam contoh.

Operator Boolean

Anda dapat menentukan penelusuran global yang lebih kompleks menggunakan operator boolean NOT di depan nilai, serta operator AND dan OR di antara nilai. Perhatikan bahwa operator ini harus ditulis dalam huruf besar. Jika muncul pada string dalam tanda petik, operator diperlakukan sebagai bagian dari nilai kolom, bukan sebagai operator. Anda dapat menggunakan tanda kurung di string kueri untuk memperjelas logikanya.

Prioritas operator boolean, dari tertinggi ke terendah, adalah: NOT, OR, AND:

NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses

Stemming

Untuk menelusuri variasi umum sebuah kata, seperti bentuk jamak dan akhiran kata kerja, gunakan operator stem ~ (karakter tilde). Ini adalah operator awalan yang harus mendahului nilai tanpa spasi di antaranya. Nilai ~cat akan cocok dengan "cat" atau "cats", dan juga ~dog akan cocok dengan "dog" atau "dogs". Algoritma stemming tidaklah sempurna. Nilai ~care akan cocok dengan "care" dan "caring", tetapi tidak cocok dengan "cares" atau "cared". Stemming hanya digunakan saat menelusuri kolom teks dan HTML.

Tokenisasi

Saat dokumen diindeks, kolomnya akan ditokenisasi. Demikian pula, nilai dalam string kueri juga ditokenisasi. Ini berarti bahwa yang tampak seperti kueri satu nilai sebenarnya diperlakukan sebagai kueri multi-nilai. Contoh:

"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"

Penelusuran kolom

Penelusuran kolom mencari nilai dalam kolom dokumen tertentu, berdasarkan nama kolom. String kueri penelusuran kolom terdiri dari satu atau beberapa ekspresi yang menentukan nama kolom, operator relasional, dannilai kolom. Operator relasional yang tersedia bergantung pada jenis kolom. Operator kesetaraan, yang diwakili oleh titik dua atau tanda sama dengan, dapat digunakan untuk semua jenis kolom. Berikut ini adalah beberapa string kueri kolom untuk berbagai jenis kolom:

query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"

Perhatikan bahwa penggunaan spasi kosong di kedua sisi operator relasional bersifat opsional. Seperti halnya string kueri penelusuran global, nilai kolom teks, HTML, atau atom dapat diapit tanda kutip untuk menentukan string, dan ekspresi untuk nilai kolom dapat diabaikan dengan menambahkan huruf besar NOT.

Kueri pada kolom atom

Nilai kolom atom adalah string karakter Kueri pada kolom atom tidak peka huruf besar/kecil. Jika kueri Anda menentukan nilai kolom dengan spasi kosong atau tanda baca, pastikan untuk memberi tanda kutip pada nilai dalam string kueri. Satu-satunya operator relasional yang valid untuk kolom atom adalah operator kesetaraan. Isi kolom atom yang lengkap harus cocok dengan nilai kueri; hal ini termasuk Unicode yang menggabungkan karakter atau karakter beraksen dalam kolom. Stemming tidak didukung untuk kolom atom.

String Kueri	Komentar
"weather=stormy" "weather: stormy"	Bentuk operator kesetaraan mana pun valid. Mengambil dokumen dengan kolom weather yang sama dengan "stormy".
"Title: \"Tom&Jerry\"" "Couple: \"Fred and Ethel\"" "Version = \"1HCP(21.3)\""	Jika Anda menelusuri kolom atom yang berisi spasi kosong atau karakter khusus, masukkan nilai ke dalam tanda kutip.
"Color = (red OR blue)" "Color = (\"dark red\" OR \"bright blue\")"	Anda dapat menggunakan tanda kurung dan operator logika OR untuk menentukan daftar nilai kolom alternatif.

Kueri pada kolom teks dan HTML

Satu-satunya operator relasional yang valid untuk kolom teks dan HTML adalah kesetaraan. Dalam hal ini, operator berarti "kolom menyertakan nilai" bukan "kolom sama dengan nilai". Anda dapat menggunakan operator stemming untuk menelusuri varian pada suatu kata. Anda juga dapat menggunakan operator OR dan AND untuk menentukan ekspresi boolean yang kompleks untuk nilai kolom. Jika operator boolean muncul dalam string yang diberi tanda kutip, operator tersebut tidak diperlakukan secara khusus dan hanya dianggap sebagai bagian lain dari string karakter yang akan dicocokkan. Ingat bahwa saat menelusuri kolom HTML, teks dalam tag markup HTML akan diabaikan. Kueri pada kolom teks dan HTML tidak peka huruf besar/kecil. Saat kolom ini diindeks, semua Unicode yang menggabungkan karakter dan karakter beraksen di dalamnya akan "dinormalisasi" ke padanan tanpa aksen. Penggabungan karakter dan aksen juga dinormalisasi di string kueri pada kolom ini, sehingga kueri dapat menyertakan bentuk beraksen atau tidak, dan akan cocok dengan kolom dalam kedua kasus tersebut.

String Kueri	Komentar
"Comment = great" "Comment: great"	Bentuk operator kesetaraan mana pun valid. Mengambil dokumen dengan kolom komentar yang berisi setidaknya satu kemunculan kata "great" di kolom Comment.
"Comment = (great big ball)" "Comment = (great AND big AND ball)"	Untuk menelusuri dua kata atau lebih dalam sebuah kolom, dalam urutan apa pun, masukkan kata dalam tanda kurung. String kueri ini mengambil dokumen dengan kolom Comment yang menyertakan ketiga kata dalam urutan apa pun, berapa pun jumlah kata lain di antaranya. Spasi di antara kata-kata menyiratkan AND logis; bentuk kedua membuatnya eksplisit.
"Comment = \"insanely great\""	Untuk menelusuri string teks tertentu, masukkan string tersebut ke dalam tanda kutip. Kueri ini akan mengambil dokumen dengan kolom Comment berisi frasa "insanely great" (dan juga "insanely-great" yang ditokenisasi untuk hal yang sama).
"pet = ~dog"	Operator stemming akan mencocokkan varian kata "dog" di kolom pet.
"Color = (red OR blue)"	Untuk menelusuri kecocokan dari daftar alternatif, masukkan daftar ini dalam tanda kurung dengan kata kunci OR di antara alternatif. Kueri ini mengambil dokumen dengan kolom Color yang menyertakan "red" atau "blue" atau keduanya.
"weather = ((rain OR snow) AND cold)"	Anda dapat menggunakan operator OR dan AND logis, bersama dengan tanda kurung, untuk menentukan nilai kolom yang lebih kompleks.
"weather = \"rain OR shine\""	Karena OR logis disematkan dalam string yang dikutip, logika tersebut tidak diperlakukan sebagai operator relasional. String kueri ini mengambil dokumen dengan kolom weather yang berisi string "rain or shine"

Kueri pada kolom angka

Nilai kolom angka dapat ditulis sebagai bilangan bulat, desimal, atau eksponensial. Operator relasional yang valid untuk kolom angka adalah operator kesetaraan, beserta operator kurang dari/lebih dari (<, <=, >, >=). Perhatikan bahwa tidak ada operator ketidaksetaraan (!=). Berikut adalah beberapa contoh string kueri untuk kolom angka:

"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"

Kueri pada kolom tanggal

Nilai kolom tanggal harus ditulis dalam format yyyy-mm-dd form. Angka nol di awal bersifat opsional untuk bulan dan tanggal satu digit. Operator relasional yang valid untuk kolom tanggal adalah operator kesetaraan, beserta operator kurang dari/lebih dari (<, <=, >, >=). Perhatikan bahwa tidak ada operator ketidaksetaraan. Anda dapat menambahkan operator NOT ke ekspresi untuk menegasikannya. Berikut adalah beberapa contoh string kueri untuk kolom tanggal:

"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"

Kueri pada kolom titik geografis

Tidak ada operator relasional yang berfungsi dengan kolom titik geografis, sehingga kolom titik geografis tidak dapat diberi nama secara langsung dalam string kueri. API Search menyediakan dua fungsi khusus yang dapat digunakan untuk kueri yang melibatkan kolom titik geografis:

geopoint(lat,long)

Menentukan titik geografis berdasarkan lintang dan bujur.

distance(point1, point2)

Menghitung jarak antara dua titik geografis dalam satuan meter. Setiap titik dapat ditentukan menggunakan nama kolom titik geografis atau pemanggilan fungsi titik geografis. Perlu diperhatikan bahwa Anda tidak dapat memberikan dua nama kolom sebagai argumen untuk fungsi ini. Setidaknya satu argumen harus berupa konstanta.

Fungsi ini dapat digunakan untuk mengonstruksi kueri yang mengambil lokasi yang relatif terhadap posisi konstan. Contoh berikut mengasumsikan bahwa indeks tersebut berisi dokumen dengan kolom titik geografis bernama "survey_marker" dan "home".

String Kueri	Komentar
"distance(survey_marker, geopoint(35.2, 40.5)) < 100"	Menelusuri penanda kurang dari 100 meter dari titik geografis yang diberikan.
"distance(home, geopoint(35.2, 40.5)) > 100"	Menelusuri rumah yang berjarak lebih dari 100 meter dari titik geografis yang diberikan.

Aplikasi yang menggunakan geolokasi biasanya menerima informasi dari browser. Jika pengguna mengizinkan, lokasi dapat disimpulkan dari alamat IP mereka, atau pengguna dapat memasukkan kode pos. Lokasi juga dapat berasal dari API lain seperti API Geolokasi Google Maps.

Kueri pada beberapa kolom

Anda dapat menggabungkan beberapa ekspresi kueri kolom dalam satu kueri dengan mencantumkannya secara berurutan dan dipisahkan oleh spasi kosong. Tindakan ini menempatkan AND tersirat di antara setiap ekspresi, sehingga semuanya harus terpenuhi agar dokumen dapat diambil. Anda dapat menambahkan operator AND dan OR secara eksplisit di antara ekspresi, serta menggunakan tanda kurung untuk memperjelas logika.

String Kueri	Komentar
"product=piano manufacturer=steinway" "product=piano AND manufacturer=steinway"	Kueri ini mengambil semua piano Steinway. Spasi di antara istilah menyiratkan AND logis; bentuk kedua membuatnya eksplisit.
"product=piano AND NOT manufacturer=steinway"	Mengambil semua piano non-Steinway.
"product=piano AND price<2000"	Kueri ini mengambil piano yang murah.

Menggabungkan penelusuran global dan kolom

String kueri dapat berisi berapa pun ekspresi penelusuran global dan ekspresi penelusuran kolom. Spasi di antara ekspresi diperlakukan sebagai AND. Anda juga dapat menggunakan OR dan AND secara eksplisit, bersama dengan tanda kurung. Setiap ekspresi akan ditangani sesuai dengan aturan yang terkait dengan jenis istilah tersebut.

String Kueri	Komentar
"keyboard great price<5000" "keyboard AND great AND price<5000"	Mengambil dokumen dengan kata "great" dan "keyboard" muncul dalam kolom teks, HTML, atau atom, dan terdapat kolom price kurang dari 5.000. AND bersifat tersirat, bentuk yang kedua adalah setara.
"keyboard OR product=piano"	Mengambil dokumen dengan kolom produk yang berisi piano, atau dokumen dengan kolom teks, HTML, atau atom yang berisi keyboard.