API · ค้นหา
ค้นหา
ค้นระเบียนด้วยคำ ด้วยความหมาย หรือทั้งสองอย่าง พร้อมตัวกรองและจำนวนของแต่ละค่า
ทุกเส้นอยู่ใต้ https://api.intent-search.dev และยืนยันตัวตนด้วย Authorization: Bearer nsk_… · คีย์บอกเองว่าชุดข้อมูลไหน
พารามิเตอร์ใน URL
| ฟิลด์ | ความหมาย |
|---|---|
broadenboolean | ให้คำที่พิมพ์เจอคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำนั้นด้วย และถามใหม่ให้กว้างขึ้นเมื่อไม่เจออะไรเลย · ค่าเริ่มต้นคือเปิด · false, 0, no, off คือปิด ตัวพิมพ์ไม่สำคัญ · ใส่ในเนื้อคำขอก็ได้ |
เนื้อคำขอ
| ฟิลด์ | ความหมาย |
|---|---|
querystring | object | สตริงคือคำที่คนพิมพ์ ตามตัวอักษร — ทุกคำต้องเจอ (AND) ไม่มีไวยากรณ์ อักขระอย่าง : ( - " เป็นแค่อักขระ จึงไม่มีวันได้ 400 · วัตถุคือ DSL เต็ม (bool, match, term, range, match_phrase_prefix, query_string …) · ไม่ใส่เลยคือทั้งชุดข้อมูล |
mode"auto" | "keyword" | "vector" | "hybrid" | `auto` เลือกให้ทีละคำค้น — ชื่อสินค้า ยี่ห้อ และรหัส (มีตัวเลข หรือไม่เกิน 3 คำ) ตอบด้วยคำ ส่วนคำค้นที่อ่านเหมือนความต้องการ (มีคำอย่าง “สำหรับ” “อยาก” “for” หรือตั้งแต่ 4 คำ เช่น “รองเท้าใส่วิ่งสำหรับคนเท้าแบน”) ตอบด้วยความหมาย และบอกใน answered ว่าตอบด้วยอะไรเพราะอะไร · keyword vector hybrid บังคับแบบเดียว · ไม่ใส่คือค้นด้วยคำ · ความหมายใช้ได้เมื่อเปิดด้วย PUT /v1/vectors แล้ว ก่อนหน้านั้นได้ผลด้วยคำ · นับโควตาค้นด้วยความหมายเฉพาะครั้งที่ตอบด้วยความหมายจริง (Free 1,000 ครั้งต่อเดือน) ไม่ว่าจะมาจาก auto vector หรือ hybrid · เมื่อโควตาหมด ผลยังมาด้วยคำพร้อม degraded |
filtersobject | ค่าที่ผู้ใช้ติ๊ก {"brand": ["Aurora"]} — ค่าของแต่ละตัวกรองเป็นรายการเสมอ หลายค่าในตัวเดียวคือ OR หลายตัวคือ AND · ชื่อที่ไม่ใช่ตัวกรองได้ 400 พร้อมรายชื่อที่มี · ตัวกรองวันที่เลือกด้วย key ของช่องตามที่ได้มา เช่น {"released": ["2026-03-02T00:00:00Z"]} ได้ทั้งช่องตั้งแต่ต้นจนก่อนช่องถัดไป (สัปดาห์เริ่มวันจันทร์ เวลาเป็น UTC) · ค่าที่ไม่ใช่จุดเริ่มของช่องได้ 400 ที่บอกจุดเริ่มของช่องที่มีเวลานั้น |
sizenumber | จำนวนผลต่อหน้า 0 ถึง 200 · ค่าเริ่มต้น 10 · เจ้าของชุดข้อมูลตั้งเพดานต่ำกว่านี้ได้ |
fromnumber | ข้ามไปกี่รายการ สำหรับเลขหน้า · from + size ไปได้ไกลสุดตำแหน่งที่ 10,000 เมื่อค้นด้วยคำ และ 1,000 เมื่อค้นด้วยความหมาย · ลึกกว่านั้น หรือให้แต่ละหน้าถูกกว่า ใช้เคอร์เซอร์ |
search_afterarray | ค่า next ของหน้าก่อน หรือค่าใน pages ของหน้าที่ต้องการ ส่งกลับมาตามที่ได้ · ใช้คู่กับ from ไม่ได้ |
pagesnumber | เลขหน้าสุดท้ายที่แถบเลขหน้าจะชี้ไป · คำตอบมี pages เป็นเคอร์เซอร์ของหน้า 2 ถึงหน้านั้น คีย์คือเลขหน้า ค่าคือ search_after ที่เริ่มหน้านั้น · ไปได้ไกลสุดหน้าที่ตำแหน่งแรกไม่เกิน 10,000 (250 หน้า ที่ 40 ต่อหน้า) ไกลกว่านั้นได้ degraded pages_capped · ค้นด้วยความหมายไม่มีเคอร์เซอร์ ได้ degraded no_page_cursors |
sortstring | array | "price", "-price", "price:desc", {"price":"desc"} หรือรายการของสิ่งเหล่านี้ · เรียงได้ด้วย _score (มากไปน้อยเป็นค่าเริ่มต้น) และฟิลด์ตัวเลข วันที่ true/false ที่โครงบอกว่า sort: true · การค้นด้วยความหมายเรียงตามความใกล้อย่างเดียว จึงรับ sort ได้แค่ {"_score":"desc"} · mode vector หรือ hybrid หรือ knn ที่ส่งมาเอง คู่กับ sort อื่นได้ 400 ที่บอกทางออก ก่อนเรียกโมเดลและไม่นับโควตา · auto ที่มี sort อื่นตอบด้วยคำเสมอ (answered.reason เป็น sort_asked) |
_sourceboolean | array | ["product_name","price"] เลือกฟิลด์ของระเบียนที่จะส่งกลับ · false ได้แค่ id และคะแนน · ไม่ใส่คือทั้งระเบียน |
aggsobject | นับเองแบบ terms, range, stats, histogram, cardinality, filter, filters (ซ้อนกันได้) · terms บนฟิลด์ข้อความที่เป็นตัวกรองใช้ได้ |
post_filterobject | กรองผลโดยไม่กระทบตัวเลขที่นับ — สิ่งที่ filters ทำให้อยู่แล้ว |
highlightobject | ทำไฮไลต์คำที่ตรง {"fields":{"product_name":{}}} · มาในคีย์ highlight ของแต่ละผล |
track_total_hitsboolean | นับ total ให้ตรงทุกหน้า · ค่าเริ่มต้นคือเปิด |
rerank"candidates" | "inline" | จัดลำดับใหม่ด้วยโมเดล — candidates ส่งข้อความของผลกลับไปให้คุณจัดเอง · inline ให้ระบบจัดให้ (ตามแพ็กเกจ) |
explainboolean | อธิบายว่าแต่ละผลได้คะแนนเท่าไหร่เพราะอะไร · ใช้ได้กับ service key เท่านั้น |
ตัวอย่าง
curl -X POST "https://api.intent-search.dev/v1/search" \
-H "Authorization: Bearer $NS_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "เซรั่ม",
"filters": {
"brand": [
"Aurora"
]
},
"size": 20
}'คำตอบ
{
"total": 1,
"total_is_exact": true,
"took_us": 412,
"hits": [
{
"id": "sku-1042",
"score": 3.18,
"matched": "words",
"words": "typed",
"sort": [
3.18,
"sku-1042"
],
"document": {
"product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
"brand": "Aurora",
"price": 890,
"in_stock": true,
"raw": {
"supplier": "S-12",
"rank": 4
}
}
}
],
"counted_over": 1,
"counted_from": "matches",
"aggregations": {
"brand": {
"buckets": [
{
"key": "Aurora",
"count": 1
}
],
"other": 0,
"missing": 0,
"other_values": 0
},
"in_stock": {
"buckets": [
{
"key": "true",
"count": 1
}
],
"other": 0,
"missing": 0,
"other_values": 0
}
},
"filters": [
{
"field": "brand",
"kind": "terms"
},
{
"field": "in_stock",
"kind": "terms"
}
],
"answered": {
"by": "words",
"reason": "no_mode",
"message": "no \"mode\" was sent, so the words answered; send mode \"auto\" to let each query choose"
}
}สิ่งที่ควรรู้
สตริงคือคำที่คนพิมพ์ ส่งข้อความจากกล่องค้นหาตรง ๆ ได้เลย ไม่ต้องกรองอักขระ iphone 15:9 ครีม 50ml) AND ได้ 200 ทั้งหมด หลายคำคือทุกคำต้องเจอ ถ้าต้องการไวยากรณ์ (field:คำ, OR, "วลี", -ไม่เอา) ให้ขอชัด ๆ ด้วย {"query": {"query_string": {"query": "…"}}}
ภาษาไทยไม่ต้องเว้นวรรค บิกินี่ลายดอก เจอชื่อที่มีข้อความนี้ติดกันก่อน แล้วค่อยเป็นชื่อที่เขียนแยกด้วยช่องว่าง · คำที่พิมพ์ยังไม่จบอย่าง กระถา เจอ กระถาง · ำ กับ ํ + า และ เเ กับ แ ถือเป็นตัวเดียวกัน
broaden ทำงานเฉพาะกับคำค้นที่เป็นสตริง และทำสองอย่าง · ทุกครั้ง: คำที่พิมพ์เจอคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำนั้นในชุดข้อมูลนี้ด้วย — รองเท้า เจอ รองเท้าแตะ และ รองเท้าผ้าใบ โดยผลที่มีคำที่พิมพ์ตรง ๆ ขึ้นก่อน · บอกไว้ในคีย์ reached ของคำตอบ (word, compounds และ left_out เมื่อเกิน 32 คำต่อคำที่พิมพ์) · ทุกผลบอกว่าคำเจอมันอย่างไร ในคีย์ words ของผลนั้น: typed คำที่พิมพ์เจอตรง ๆ · compound เจอเพราะคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำที่พิมพ์เท่านั้น · widened คำที่พิมพ์ไม่เจออะไรเลย ผลนี้มาจากคำถามที่กว้างกว่า · ไม่มี words เมื่อความหมายอย่างเดียวเจอผลนั้น (matched: "meaning") · คำไทยที่สั้นกว่า 4 ตัวอักษรขยายเฉพาะเมื่อชุดข้อมูลเขียนคำนั้นแยกไว้ (ผ้า เจอ ผ้าห่ม แต่ กก ไม่เจอ กกธูป) · เมื่อไม่เจออะไรเลย: ลองให้เจอเกือบทุกคำก่อน แล้วค่อยคำใดคำหนึ่ง แล้วค่อยคำขึ้นต้น และบอกว่าทำอะไรไปในคีย์ broadened (required คือ most หรือ any) · เงื่อนไขใน DSL อย่าง term ไม่ถูกขยายเด็ดขาด · ผลที่ broaden แล้วไล่หน้าต่อด้วย next ได้ และ aggregations นับจากคำถามเดียวกับผล
ไม่เจอ หรือเจอแล้วได้เพิ่ม: มีคีย์ broadened แปลว่าคำที่พิมพ์ไม่เจออะไรเลย ผลที่เห็นตอบคำถามที่กว้างกว่า ขึ้นข้อความอย่าง “ไม่พบผลที่ตรงกับคำค้น แสดงผลที่ใกล้เคียง” ได้ · มีแค่ reached แปลว่าคำที่พิมพ์เจอแล้ว และได้คำที่ยาวกว่ามาเพิ่ม ผลที่ตรงยังอยู่ครบและขึ้นก่อน อย่าขึ้นข้อความว่าไม่พบ · ทั้งสองมาด้วยกันได้ เมื่อคำที่พิมพ์ไม่เจอแต่คำหนึ่งในนั้นเจอคำที่ยาวกว่า · ดูจากว่ามีคีย์ broadened หรือไม่ ไม่ใช่จากคีย์ข้างใน เพราะ split prefixed required มาไม่ครบทุกตัวก็ได้ (Down ได้แค่ prefixed)
next มีเมื่อยังมีผลต่อเท่านั้น — ไม่มีคีย์นี้แปลว่าหน้านี้คือหน้าสุดท้าย · ค่าตัวสุดท้ายของ next คือ id ของผลสุดท้ายในหน้า จึงไม่หมดอายุเพราะดัชนีถูกจัดใหม่ · เคอร์เซอร์ที่ใช้ไม่ได้ได้ 400 ไม่ใช่หน้าว่าง
แถบเลขหน้า: หน้าแรกส่ง pages เท่าเลขหน้าสุดท้ายของแถบ แล้วเก็บ pages ที่ได้ไว้กับหน้าที่วาด · คลิกหน้า k ส่ง search_after: pages[k] · เคอร์เซอร์คือตำแหน่งในลำดับ ไม่ใช่เลขที่นับ — ระเบียนที่เพิ่มหรือลบก่อนหน้านั้นเลื่อนเลขหน้า ไม่เลื่อนเคอร์เซอร์ · ส่ง size เหมือนกันทุกหน้าของแถบเดียวกัน เพราะมันกำหนดว่าหน้าเริ่มตรงไหน
ค้นด้วยคำ total คือจำนวนที่คำค้นเจอ นับตรงทุกหน้า (total_is_exact: true) และเท่าเดิมไม่ว่าจะไล่ด้วย from หรือ search_after · vector ได้ total เป็นจำนวนระเบียนที่มีเวกเตอร์และผ่านตัวกรอง ซึ่งคือทุกระเบียนที่จัดลำดับได้ นับตรงและเท่าเดิมทุกหน้าเช่นกัน จึงใช้นับเลขหน้าได้ตั้งแต่หน้าแรก · hybrid เป็นค่าขั้นต่ำ ได้ total_is_exact: false เมื่อฝั่งความหมายพาระเบียนที่ฝั่งคำไม่เจอมาด้วย และอาจเพิ่มเมื่อไล่ลึกขึ้น · total คือจำนวนหลังตัวกรองที่ผู้ใช้ติ๊ก ส่วน counted_over คือฐานที่ตัวเลขใน aggregations ถูกนับมา ติ๊กแบรนด์หนึ่งแล้วแบรนด์อื่นในแถบยังมีตัวเลขให้เลือก
counted_from มาคู่กับ counted_over และบอกว่าฐานนั้นคืออะไร · matches ค้นด้วยคำ นับจากระเบียนที่คำค้นเจอ · words ค้นแบบ hybrid นับเฉพาะระเบียนที่ฝั่งคำเจอ ผลที่ตรงความหมายอย่างเดียวไม่อยู่ในตัวเลข และ counted_over: 0 แปลว่าฝั่งคำไม่เจออะไร ทุกผลตรงความหมาย · all ค้นแบบ vector ไม่มีชุดระเบียนที่ตรงให้นับ จึงนับทุกระเบียนในชุดข้อมูล ไม่ใช่เฉพาะผลที่ได้ · การค้นด้วยความหมายที่ไม่ได้นับอะไร (ชุดข้อมูลไม่มีตัวกรองและไม่ได้ส่ง aggs) ไม่มีทั้งสองคีย์ · ก่อนขึ้นข้อความว่าตัวเลขนับจากอะไร ให้ดู counted_from
filters มาทุกครั้ง: ตัวกรองที่ชุดข้อมูลนี้มี (ว่างเมื่อไม่มี) ตัวเลขของแต่ละค่าอยู่ใน aggregations ภายใต้ชื่อฟิลด์เดียวกัน
ตัวกรองวันที่ใน aggregations มีเฉพาะช่องที่มีสินค้า เรียงจากเก่าไปใหม่ แต่ละช่องมี key (จุดเริ่ม) from และ to (มิลลิวินาที) · มีได้ไม่เกิน 200 ช่อง ถ้าสินค้าเพิ่มจนเกินหลังบันทึกขั้นไว้ ได้ 200 ช่องล่าสุด สินค้าในช่องที่เก่ากว่านับรวมใน other ของตัวกรองนั้น และ degraded มี facet_buckets_capped
matched มากับทุกผล — words ตรงคำ meaning ตรงความหมาย both ทั้งสอง เอาไปขึ้นป้ายบนหน้าร้านได้ · sort คือตำแหน่งของผลนั้นในลำดับ (คะแนนหรือค่าที่เรียง แล้วตามด้วย id) ส่งเป็น search_after เพื่อไล่ต่อจากผลใดก็ได้
degraded มาพร้อมผลเมื่อคำตอบเล็กกว่าที่ขอ ไม่ใช่แทนที่ผล · reason เป็นค่าคงที่ให้แตกสาขาได้ และถ้าเสียหลายอย่าง ตัวที่เหลืออยู่ใน degraded.also — รายการทั้งหมดอยู่ที่หน้า ข้อผิดพลาดและเพดาน
answered มากับทุกคำตอบ ทุก `mode` เป็น { by, reason, message } — by คือ words หรือ meaning และนับโควตาค้นด้วยความหมายเฉพาะครั้งที่ได้ meaning · reason เป็นค่าคงที่: mode_asked (mode ที่ส่งมาเลือกเอง — keyword ได้ words ส่วน vector และ hybrid ได้ meaning) no_mode (ไม่ได้ส่ง mode จึงตอบด้วยคำ) vector_supplied (ส่ง knn มาเอง) meaning_withheld (ขอความหมายแต่ครั้งนี้ตอบด้วยคำ — degraded บอกเหตุ) และที่ auto เลือก: looks_like_a_code (มีตัวเลข) looks_like_a_name (ไม่เกิน 3 คำและไม่มีคำบอกความต้องการ) reads_like_a_need meaning_not_enabled (ชุดข้อมูลยังไม่เปิดความหมาย ไม่มี degraded) no_query_text (ไม่มีข้อความที่พิมพ์) sort_asked (ส่ง sort ที่ไม่ใช่ {"_score":"desc"} ซึ่งการค้นด้วยความหมายทำไม่ได้ จึงตอบด้วยคำโดยไม่อ่านคำค้น) · ชุดข้อมูลที่ยังไม่เปิดความหมายบอกได้สองแบบตาม `mode`: vector และ hybrid ขอความหมายแล้วไม่ได้ จึงได้ meaning_withheld คู่กับ degraded.reason เป็น not_enabled ส่วน auto ไม่ได้ขอตั้งแต่แรก จึงได้ meaning_not_enabled และไม่มี degraded — หน้าที่จะบอกว่า "ยังไม่ได้เปิดความหมาย" ให้ดูทั้ง answered.reason และ degraded.reason · ถ้าได้ looks_like_a_name กับ total เป็น 0 และอยากลองด้วยความหมาย ส่งคำเดิมด้วย mode: "hybrid"
ข้อผิดพลาดของเส้นนี้
| ฟิลด์ | ความหมาย |
|---|---|
400 | เนื้อคำขอผิดรูป, DSL ผิด, ค่า size/from ไม่ใช่จำนวนเต็มตั้งแต่ 0, filters ที่ไม่ใช่รายการหรือไม่ใช่ตัวกรอง, เรียงด้วยฟิลด์ที่เรียงไม่ได้, sort อื่นนอกจาก {"_score":"desc"} คู่กับ mode vector หรือ hybrid หรือกับ knn ที่ส่งมาเอง (ก่อนเรียกโมเดล ไม่นับโควตา), เคอร์เซอร์ที่ใช้ไม่ได้ |
403 | explain ด้วย client key หรือ client key จากหน้าเว็บที่ไม่อยู่ในรายการ |
429 | ยิงถี่เกินอัตราของแพ็กเกจ · ดู Retry-After |
รูปของข้อผิดพลาด อัตราต่อวินาที และการลดทอน (degraded) อยู่ที่ ข้อผิดพลาดและเพดาน
POST /v1/similarสินค้าใกล้เคียง