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:
String query = "blue";
String query = "NOT white";
String query = "blue OR red";
String query = "blue guitar";
Penelusuran kolom menggunakan string kueri yang berisi satu atau beberapa ekspresi yang menentukan nama kolom dan nilai kolom:
String query = "model:gibson date < 1965-01-01";
String query = "title:\"Harry Potter\" AND pages<500";
String 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"
|
Bentuk operator kesetaraan mana pun valid. Mengambil dokumen dengan kolom weather yang sama dengan "stormy". |
"Title: \"Tom&Jerry\""
|
Jika Anda menelusuri kolom atom yang berisi spasi kosong atau karakter khusus, masukkan nilai ke dalam tanda kutip. |
"Color = (red OR 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" |
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)"
|
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"
|
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. |