Sintaks pencarian yang kaya mendukung berbagai jenis kueri.
URL
/v3/openapi/apps/$app_name/search?fetch_fields=name&query=config=format:fulljson&&query=name:'testuser'&&sort=id
-
$app_name: Nama aplikasi. Edisi Advanced dan Standard mendukung beberapa aplikasi, sehingga Anda harus menentukan nama aplikasi untuk menargetkan versi tertentu. Misalnya, Anda dapat menggunakan ID aplikasi untuk mengakses layanan pencarian dari aplikasi offline.
-
URL di atas tidak mencakup detail seperti request headers dan encoding.
-
URL di atas menghilangkan alamat host.
-
Untuk detail tentang parameter kueri dalam URL di atas, termasuk definisi, penggunaan, dan contohnya, lihat bagian "Parameter kueri" di bawah ini.
Protokol permintaan
HTTP
Metode permintaan
GET
Format yang didukung
JSON
Parameter kueri
Untuk detail cara menggabungkan parameter kueri, lihat mekanisme signature API V3.
|
Parameter |
Type |
Wajib |
Default |
Deskripsi |
|
query |
string |
Ya |
Kueri pencarian. Parameter ini tidak boleh kosong. Edisi Industry Algorithm mendukung pencarian kosong, yang memungkinkan Anda melakukan pencarian tanpa menentukan istilah pencarian dalam klausa |
|
|
fetch_fields |
string |
Tidak |
Semua bidang displayable. |
Menentukan bidang mana yang akan dikembalikan dalam hasil pencarian. Pisahkan beberapa bidang dengan titik koma |
|
qp |
string |
Tidak |
Aturan aktif |
Menentukan aturan analisis query yang akan digunakan. Pisahkan beberapa aturan dengan koma |
|
disable |
string |
Tidak |
Menonaktifkan parameter yang ditentukan. |
|
|
first_rank_name |
string |
Tidak |
Nama ekspresi pengurutan dasar default |
Menentukan nama ekspresi pengurutan dasar. Anda hanya dapat menentukan satu nama. |
|
second_rank_name |
string |
Tidak |
Nama ekspresi pengurutan layanan default |
Menentukan nama ekspresi pengurutan layanan. Anda hanya dapat menentukan satu nama. |
|
user_id |
string |
Tidak |
Identifikasi unik untuk end user. Tetapkan parameter ini ke salah satu berikut, diurutkan berdasarkan prioritas menurun: 1. ID login persisten end user. 2. IMEI perangkat seluler end user. |
|
|
abtest |
string |
Tidak |
Parameter ini diperlukan untuk menggunakan fitur A/B test. |
|
|
raw_query |
string |
Tidak |
Digunakan untuk pelatihan algoritma, seperti untuk prediksi kategori. Kami merekomendasikan agar Anda menyetel parameter ini untuk semua kueri. |
|
|
search_strategy |
string |
Tidak |
Menentukan nama strategi kueri untuk pencarian multi-path. |
|
|
re_search |
string |
Tidak |
Menentukan kebijakan retry. Saat ini, kebijakan hanya dapat didasarkan pada ambang batas total hits. |
|
|
biz |
string |
Tidak |
Menjelaskan konteks bisnis permintaan, seperti origin atau tujuannya. |
|
|
summary |
string |
Tidak |
Konfigurasi ringkasan default |
Mengonfigurasi ringkasan hasil pencarian. Anda dapat menentukan bidang untuk operasi seperti highlighting dan pemotongan. |
|
from_request_id |
string |
Tidak |
Menentukan sumber permintaan pencarian. Jika kueri berasal dari fitur seperti saran pencarian, kueri populer, atau saran kueri, tetapkan parameter ini ke |
|
|
vector_search |
string |
Tidak |
||
|
|
string |
Ya |
Menentukan kriteria pencarian. |
|
|
|
string |
Tidak |
Menentukan format respons dan jumlah dokumen yang akan dikembalikan. |
|
|
|
string |
Tidak |
Menentukan kriteria filter. |
|
|
|
string |
Tidak |
Menentukan kondisi pengurutan dokumen. Hanya bidang integer yang didukung. Klausa ini hanya tersedia untuk API V3 dan SDK. |
Parameter kueri
-
query: Anda dapat menggabungkan beberapa klausa untuk memenuhi berbagai kebutuhan pencarian. Klausa dalam parameter kueri dihubungkan oleh
&&. Edisi Industry Algorithm mendukung pencarian kosong. Jika Anda memberikan string kosong''sebagai istilah pencarian dalam klausa kueri, sistem akan mengembalikan hasil lengkap. Error 2112 mungkin terjadi selama pencarian kosong, tetapi ini merupakan masalah tampilan dan tidak memengaruhi hasil pencarian aktual. -
fetch_fields: Untuk menghindari dampak pada performa kueri, ambil hanya bidang yang diperlukan. Jika Anda mengonfigurasi parameter ini di SDK/API, pengaturan ini akan menggantikan pengaturan yang sesuai di Konsol.
-
qp: Jika Anda mengonfigurasi parameter ini di SDK/API, pengaturan ini akan menggantikan pengaturan yang sesuai di Konsol.
Catatan: Halaman Search Test di Konsol menampilkan efek dari qp dan hasilnya. Informasi ini saat ini tidak tersedia melalui API atau SDK.
-
disable: Menonaktifkan fitur tertentu selama kueri. Anda dapat menonaktifkan fitur seperti analisis kueri (
qp), highlighting (summary), peringkat coarse-to-fine (first_rank,second_rank), dan re-search (re_search).Deskripsi
-
Menentukan fitur mana yang akan dinonaktifkan selama kueri.
-
Saat ini mendukung penonaktifan analisis kueri, highlighting, peringkat coarse-to-fine, dan re-search.
Format:
disable=function[;function] function=function_name[:function_param]-
Contoh:
-
Untuk menonaktifkan analisis kueri, tetapkan
disable=qp. -
Untuk menonaktifkan fitur
spell_checkdalam analisis kueri, tetapkandisable=qp:spell_check. Formatnya adalahdisable=qp:$qp_processor_name. Untuk informasi lebih lanjut, lihat QueryProcessor. -
Untuk menonaktifkan re-search, tetapkan
disable=re_search.
-
-
-
first_rank_name: Ketika ditetapkan dalam panggilan SDK atau API, parameter ini akan menggantikan pengaturan yang sesuai di Konsol.
-
second_rank_name: Ketika ditetapkan dalam panggilan SDK atau API, parameter ini akan menggantikan pengaturan yang sesuai di Konsol.
-
user_id:
-
Nilai
user_idharus di-URL-encode dalam permintaan pencarian. -
Fitur statistik data menggunakan parameter ini untuk menghitung unique visitors (UVs).
-
Jika Anda telah mengintegrasikan pengumpulan data, pastikan bahwa
user_idyang digunakan untuk melaporkan data perilaku sesuai denganuser_iddalam permintaan pencarian.
-
-
abtest:
abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value)), di manaurlencodeadalah fungsi encoding URL.-
Tetapkan
flow_dividerke ID end user. Jika ID tidak tersedia, Anda dapat menggunakan ID perangkat atau alamat IP end user. Parameter ini wajib. -
scene_tag: Jika Anda tidak mengonfigurasi tag scene di Konsol, A/B test berlaku untuk traffic dari semua scene, dan Anda tidak perlu menyetelscene_tagdalam kueri.
-
-
raw_query:
Deskripsi
-
Parameter ini digunakan untuk prediksi kategori. Prediksi kategori, yang dikonfigurasi dalam analisis kueri, hanya berjalan ketika parameter
querydanraw_queryidentik. -
Parameter ini juga digunakan untuk pelatihan algoritma, seperti untuk prediksi kategori. Karena alasan ini, tetapkan parameter ini dalam semua kueri.
-
Tetapkan parameter ini ke kueri asli yang dimasukkan oleh end user.
Format:
raw_query=content-
content: Kueri asli.
-
-
re_search:
Deskripsi
-
Menentukan strategi re-search. Saat ini, hanya strategi berbasis ambang batas
total_hitsyang didukung. -
Fitur ini memerlukan konfigurasi analisis kueri.
-
Re-search tidak dipicu jika semua istilah dari kueri yang telah ditokenisasi memiliki bobot pengenalan entitas yang sama. Untuk memicu re-search, Anda harus menyesuaikan bobot kategori dalam pengenalan entitas.
Format:
re_search=strategy:threshold,params:total_hits#${COUNT}-
COUNT: Ambang batastotal_hits. Sistem memicu re-search jika jumlah total hits kurang dariCOUNT. -
Contoh:
-
re_search=url_encode(strategy:threshold,params:total_hits#6)
-
-
-
biz:
Deskripsi
-
Menentukan informasi bisnis untuk permintaan, seperti jenis bisnis dari sumber traffic.
Format:
biz=type:$TYPE -
type: Jenis traffic, yang dapat Anda definisikan sendiri. Gunakan nilai ini untuk membedakan traffic dari sumber berbeda dalam laporan. -
Contoh:
-
biz=type:home_page
-
-
-
vector_search:
Parameter
Type
Default
Deskripsi
namespace
list<string>
Namespace tempat pencarian dilakukan.
threshold
float
Ambang batas skor minimum untuk pengambilan vektor.
top_n
uint32
Jumlah hasil teratas yang dikembalikan dari pengambilan vektor.
search_params.qc_scan_ratio
float
0,01
Rasio yang digunakan untuk menghitung
max_scan_num. Rumusnya: jumlah total dokumen *scan_ratio.search_params.hnsw_ef
uint32
500
Menentukan presisi pencarian. Nilai yang lebih besar meningkatkan jumlah dokumen yang dipindai dan meningkatkan tingkat recall.
-
vector_threshold:
-
Deskripsi
-
Mengontrol ambang batas skor vektor untuk recall vektor. Sistem hanya mengembalikan dokumen dengan skor vektor yang lebih rendah dari ambang batas ini.
-
-
Format
vector_threshold=14.0 -
Nilainya harus berupa float.
-
Parameter ini opsional. Jika dihilangkan, sistem menggunakan ambang batas bawaan.
-
Summary:
-
Parameter
summary_element_prefixdansummary_element_postfixharus ditetapkan bersama. -
Parameter
summary_elementberinteraksi dengan parametersummary_element_prefixdansummary_element_postfix. Yang terakhir ditentukan akan mengambil prioritas. -
Summary dan highlighting tidak dapat dikonfigurasi secara terpisah.
-
Pengaturan parameter melalui SDK atau API akan menggantikan pengaturan yang sesuai di Konsol.
-
|
Parameter |
Type |
Wajib |
Nilai |
Default |
Deskripsi |
|
summary_field |
string |
Ya |
Bidang yang digunakan untuk menghasilkan ringkasan. |
||
|
summary_element |
string |
Tidak |
em |
Tag highlight, ditentukan sebagai nama tag HTML tanpa tanda kurung sudut. |
|
|
summary_ellipsis |
string |
Tidak |
… |
Tanda elipsis yang ditambahkan ke ringkasan yang dipotong. |
|
|
summary_snippets |
int |
Tidak |
1 |
Jumlah snippet ringkasan yang dikembalikan. |
|
|
summary_len |
string |
Tidak |
Panjang perkiraan setiap snippet ringkasan. |
||
|
summary_element_prefix |
string |
Tidak |
Awalan untuk istilah yang di-highlight. Ini harus berupa tag HTML lengkap, seperti <em>. |
||
|
summary_element_postfix |
string |
Tidak |
Akhiran untuk istilah yang di-highlight. Ini harus berupa tag HTML lengkap, seperti </em>. |
Hasil
|
Parameter |
Type |
Deskripsi |
|
status |
string |
Hasil eksekusi. |
|
request_id |
string |
ID permintaan unik untuk kueri ini. Gunakan untuk troubleshooting. |
|
result |
JSON |
Berisi hasil pencarian dan metadata. Objek ini mencakup waktu pencarian ( |
|
errors |
list |
Daftar kesalahan. Setiap objek kesalahan berisi |
-
searchtime: Waktu pemrosesan engine untuk kueri, dalam detik.
-
Perbedaan antara total, viewtotal, dan num: total adalah jumlah hasil di engine yang cocok dengan kueri, mengabaikan klausa config. Nilai ini dioptimalkan untuk set hasil besar. Namun, karena alasan performa dan relevansi, engine hanya mengembalikan maksimal viewtotal hasil. Untuk pagination,
start+hitharus kurang dari viewtotal. Nilai total umumnya digunakan untuk tampilan. Sementara itu, num adalah jumlah aktual item yang dikembalikan dalam permintaan kueri saat ini, yang dibatasi oleh parameter start dan hit dalam klausa config serta tidak akan melebihi nilai hit. -
compute_cost: Array yang berisi satu objek. Dalam objek ini,
index_namemerepresentasikan ID aplikasi, danvaluemerepresentasikan LCUs yang dikonsumsi oleh kueri. -
items: Berisi dokumen yang diambil. Di dalam setiap objek dokumen, objek fields berisi konten yang diambil.
-
variableValue: Merepresentasikan hasil dari parameter kustom, seperti nilai
distance. Node ini hanya dikembalikan ketika parameter format dalam klausa config diatur kexmlataufulljson. Formatjsontidak mengembalikan node ini secara default. -
sortExprValues: Merepresentasikan skor pengurutan dokumen.
-
facet: Berisi informasi yang dikembalikan oleh klausa aggregate.
-
Tipe bidang array: Dalam format JSON dan fulljson, nilai dalam array dipisahkan oleh karakter tab (\t). Dalam format XML, nilai-nilai ini dipisahkan oleh spasi.
Contoh pencarian
Respons JSON
{
"result": {
"searchtime": 0.009554,
"total": 1,
"compute_cost": [
{
"index_name": "110247758",
"value": 0.304
}
],
"num": 1,
"viewtotal": 1,
"items": [
{
"variableValue": {
},
"sortExprValues": [
"10000"
],
"property": {
},
"attribute": {
},
"fields": {
"size": "XL",
"discount_price": "9.9",
"pid": "950",
"range_age": "18\t25",
"detail": "Men's Lapel Jacket, New 2021 Spring & Fall Style, Lightweight Casual Zip-Up Youth Outerwear",
"index_name": "110247758"
}
}
],
"facet": []
},
"ops_request_misc": "%7B%22request%5Fid%22%3A%22162642700916781929257960%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
"tracer": "",
"request_id": "162642700916781929257960",
"errors": [],
"status": "OK"
}
Respons error
{
"result": {
"searchtime": 0.003999,
"total": 0,
"compute_cost": [
{
"index_name": "110247758",
"value": 0.232
}
],
"num": 0,
"viewtotal": 0,
"items": [],
"facet": []
},
"ops_request_misc": "%7B%22request%5Fid%22%3A%22162642716516781913069826%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
"tracer": "",
"request_id": "162642716516781913069826",
"errors": [
{
"code": 6127,
"message": "Attribute does not exist."
}
],
"status": "FAIL"
}
-
Catatan:
statusbernilaiFAILmenunjukkan bahwa terjadierrordan tidak adaresultyang dikembalikan. Namun,errortetap dapat terjadi meskipunstatusbernilaiOKdan hasil dikembalikan. Misalnya, Anda mungkin tetap menerima hasil meskipun terjadierror server 1000(timeout pencarian) atau error2112(tidak adaindexyang ditentukan untukfine ranking).
Troubleshooting hasil kueri
Jika hasil yang dikembalikan oleh panggilan API pencarian tidak sesuai harapan, seperti hasil tidak konsisten, tidak ada hasil, atau jumlah hasil yang tidak terduga, gunakan metode berikut untuk troubleshooting:
-
Bandingkan pernyataan kueri yang digunakan oleh API dan halaman Search Test: Jika hasil dari panggilan API berbeda dari hasil yang ditampilkan di halaman Search Test di Konsol, bandingkan pernyataan kueri yang sebenarnya dikirim oleh masing-masing, dan periksa perbedaan dalam
klausa query. -
Verifikasi bahwa data ada: Lakukan kueri langsung ke data berdasarkan kunci primernya
iduntuk memastikan apakah data tersebut ada. Hal ini membantu Anda mengesampingkan masalah yang disebabkan oleh keterlambatan sinkronisasi data. -
Atasi masalah tokenisasi: Jika Anda menduga bahwa tokenisasi menyebabkan hasil yang tidak terduga, Anda dapat menambahkan intervensi tokenisasi kustom untuk mengoptimalkan hasil.
-
Sesuaikan presisi kueri vektor: Untuk kueri vektor, jika hasilnya tidak sesuai harapan, coba bulatkan nilai kueri ke 5 tempat desimal dan ulangi kueri.
-
Urutan troubleshooting ketika tidak ada hasil yang dikembalikan:
-
Pertama periksa apakah
totaldalam respons bernilai0.totalmerepresentasikan jumlah total hasil di engine yang cocok dengan kriteria kueri. Nilai ini dioptimalkan ketika jumlah hasil besar (lihat deskripsi perbedaan antara total, viewtotal, dan num di bagian "Respons" dokumen ini). -
Jika
totaltidak0tetapi tidak adaitemsyang dikembalikan, periksa parameterstartdanhitdalamklausa config.
-
Pencarian gulir
Untuk mengoptimalkan kecepatan, pencarian tradisional mengembalikan jumlah terbatas hasil yang paling relevan. Misalnya, metode search dapat mengambil maksimal 5.000 dokumen. Ketika Anda memerlukan lebih banyak hasil untuk analisis, gunakan scroll API untuk mengambil set hasil yang lebih besar.
Klausa yang didukung
-
klausa query
-
klausa config (parameter start tidak berpengaruh)
-
klausa filter
-
klausa sort (hanya mendukung satu bidang tipe INT; hanya untuk API v3 dan SDK)
URL
Kueri awal
/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&[parameter kueri]
Kueri berikutnya
/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&[parameter-kueri]
-
$app_name: Nama aplikasi.
-
URL di atas tidak mencantumkan alamat Host aplikasi.
-
Dua URL permintaan scroll di atas menghilangkan header permintaan, parameter kueri, dan encoding. Untuk contoh URL lengkap, lihat deskripsi di bawah.
-
Metode scroll memiliki dukungan terbatas untuk banyak fitur. Untuk daftar lengkap keterbatasan, lihat catatan di bawah.
Protokol permintaan
HTTP
Metode permintaan HTTP
GET
Format yang didukung
JSON
Parameter kueri
|
Parameter |
Type |
Wajib |
Nilai |
Default |
Deskripsi |
|
scroll |
string |
Ya |
week, day, hour, minute, second |
Menentukan berapa lama konteks pencarian tetap aktif untuk permintaan scroll berikutnya. Anda harus menyetel parameter ini untuk setiap permintaan. Misalnya, gunakan |
|
|
search_type |
string |
Ya |
scan |
Wajib untuk kueri awal. Untuk kueri berikutnya, hilangkan parameter ini dan gunakan |
|
|
scroll_id |
string |
Ya |
Permintaan awal mengembalikan |
||
|
query clause |
string |
Ya |
Menentukan kriteria pencarian. |
||
|
config clause |
string |
Ya |
Menentukan format respons dan jumlah dokumen yang akan dikembalikan. |
||
|
filter clause |
string |
Tidak |
Menentukan kriteria filter. |
||
|
sort clause |
string |
Tidak |
Menentukan kondisi pengurutan dokumen. Hanya mendukung pengurutan pada satu bidang integer. Klausa ini hanya tersedia di API V3 dan SDK. |
||
|
fetch_fields parameter |
string |
Tidak |
Menentukan bidang aplikasi mana yang akan dikembalikan dalam hasil. |
Respons
|
Parameter |
Type |
Deskripsi |
|
status |
string |
Status permintaan. |
|
request_id |
string |
ID permintaan untuk kueri, terutama digunakan untuk troubleshooting. |
|
result |
string |
Muatan respons, yang mencakup waktu pencarian ( |
|
errors |
string |
Berisi informasi kesalahan, termasuk pesan kesalahan di bidang |
Operasi scroll hanya mengembalikan hasil dalam format fulljson atau JSON.
Scroll
Catatan: Dalam klausa config, start diabaikan. Gunakan nilai hit untuk menentukan jumlah dokumen yang dikembalikan per permintaan. Fitur seperti aggregate, distinct, dan ekspresi peringkat coarse-to-fine tidak didukung. Klausa sort hanya mendukung pengurutan pada satu bidang INT. Anda tidak dapat melakukan kueri scroll lintas beberapa aplikasi. Memberikan scroll_id yang tidak valid akan mengembalikan error. Satu-satunya format respons yang didukung adalah fulljson dan JSON. Kueri pertama hanya mengembalikan scroll_id dan tidak ada data dokumen. Untuk mengambil data, Anda harus mengirim kueri berikutnya dengan scroll_id dari respons sebelumnya.
Permintaan pertama
Contoh ini menghilangkan detail seperti header permintaan dan encoding.
http://$host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&search_type=scan&scroll=1m&fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id
Respons sukses
{
"status": "OK",
"request_id": "150150574119953661605242",
"result": {
"searchtime": 0.005029,
"total": 1,
"num": 0,
"viewtotal": 1,
"scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
"items": [],
"facet": []
},
"errors": [],
"tracer": ""
}
Permintaan berikutnya
Contoh ini menghilangkan detail header permintaan dan encoding.
http://$host/v3/openapi/apps/app_schema_demo/search?fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id&query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=
Hasil
{
"status": "OK",
"request_id": "150150574119952551519970",
"result": {
"searchtime": 0.006293,
"total": 1,
"num": 1,
"viewtotal": 1,
"scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
"items": [
{
"fields": {
"cate_id": "0",
"float_arr": "0",
"id": "1",
"int_arr": "0",
"literal_arr": "search",
"name": "search",
"phone": "123****5678",
"index_name": "app_schema_demo"
},
"property": {},
"attribute": {},
"variableValue": {},
"sortExprValues": [
"1"
]
}
],
"facet": []
},
"errors": [],
"tracer": ""
}