API · ข้อมูล
ส่งระเบียนเข้ามา
เพิ่มหรือเขียนทับระเบียนในชุดข้อมูลที่คีย์นี้ผูกอยู่ แล้วพักไว้จนกว่าจะเรียก sync
ทุกเส้นอยู่ใต้ https://api.intent-search.dev และยืนยันตัวตนด้วย Authorization: Bearer nsk_… · คีย์บอกเองว่าชุดข้อมูลไหน
เนื้อคำขอ
| ฟิลด์ | ความหมาย |
|---|---|
documentsต้องมีarray | 1 ถึง 5,000 ระเบียนต่อคำขอ และเนื้อคำขอไม่เกิน 32 MB · ไฟล์ที่ใหญ่กว่านั้นแบ่งส่งหลายรอบ แล้วค่อย sync ครั้งเดียว |
documents[].idต้องมีstring | number | id ของระเบียน · ชื่อคอลัมน์เปลี่ยนได้ด้วย id_field ของ PUT /v1/schema ก่อนเขียนครั้งแรก เช่นข้อมูลที่ใช้ itemId · ส่ง id เดิมซ้ำคือเขียนทับ · ตัวเลขใช้ได้ถึง 2^53 เกินกว่านั้นให้ส่งเป็นสตริง |
documents[].*any | ฟิลด์อื่นเป็นของคุณทั้งหมด เก็บไว้ครบและส่งกลับมาทั้งระเบียนพร้อมผลค้นหา รวมถึงฟิลด์ที่ซ้อนกันและฟิลด์ที่ไม่ได้ลงดัชนี · ชื่อที่ขึ้นต้นด้วย ns_ สงวนไว้ให้ระบบ |
ตัวอย่าง
curl -X POST "https://api.intent-search.dev/v1/documents" \
-H "Authorization: Bearer $NS_KEY" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"id": "sku-1042",
"product_name": "เซรั่มวิตามินซี ลดริ้วรอย",
"brand": "Aurora",
"price": 890,
"in_stock": true,
"raw": {
"supplier": "S-12",
"rank": 4
}
},
{
"id": "sku-1043",
"product_name": "ครีมกันแดดเนื้อบางเบา SPF50",
"brand": "Aurora",
"price": 450,
"in_stock": false
},
{
"id": "sku-2001",
"product_name": "กระถางต้นไม้ดินเผา ขนาดกลาง",
"brand": "Terra",
"price": 120,
"in_stock": true
}
]
}'คำตอบ
{
"received": 3,
"stored": 3,
"changed": 3,
"schema": {
"inferred": true,
"id_field": "id",
"fields": [
{
"name": "product_name",
"type": "text",
"search": {
"weight": 2
},
"filter": false,
"sort": false
},
{
"name": "brand",
"type": "text",
"search": {
"weight": 1
},
"filter": {
"kind": "terms"
},
"sort": false
},
{
"name": "price",
"type": "number",
"search": false,
"filter": false,
"sort": true
},
{
"name": "in_stock",
"type": "boolean",
"search": false,
"filter": {
"kind": "terms"
},
"sort": true
}
],
"stored_only": [
{
"name": "raw",
"reason": "its values are objects, which no field type holds"
}
],
"note": "read from this batch; change any of it with PUT /v1/schema without sending the documents again"
},
"report": {
"product_name": {
"types": {
"string": 3,
"number": 0,
"boolean": 0,
"object": 0,
"empty": 0
},
"indexed_as": "text",
"not_indexed": 0
},
"price": {
"types": {
"string": 0,
"number": 3,
"boolean": 0,
"object": 0,
"empty": 0
},
"indexed_as": "number",
"not_indexed": 0
}
},
"note": "staged — call POST /v1/sync to publish"
}สิ่งที่ควรรู้
ส่งแล้วยังค้นไม่เจอ — ระเบียนถูกพักไว้ก่อน แล้ว POST /v1/sync เป็นตัวส่งเข้าดัชนีทีเดียว แยกกันเพราะไฟล์หนึ่งไฟล์คือหลายคำขอ และคุณไม่อยากให้ร้านเห็นสินค้าครึ่งไฟล์ ของที่ส่งผ่านเส้นนี้ขึ้นดัชนีเมื่อคุณเรียก sync เท่านั้น ตัวส่งอัตโนมัติไม่แตะ
ครั้งแรกไม่ต้องตั้งอะไรก่อน — ถ้าชุดข้อมูลยังไม่มีโครง ระบบอ่านทั้ง batch แรกแล้วตัดสินให้ว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้ (คอลัมน์ที่ค่าซ้ำกันอย่างยี่ห้อเป็นทั้งตัวกรองและค้นด้วยคำได้ น้ำหนักรองจากชื่อสินค้า) แล้วตอบโครงนั้นกลับมาในคีย์ schema พร้อมเหตุผลของฟิลด์ที่เก็บไว้เฉย ๆ ไม่ลงดัชนี (ลิงก์ ออบเจกต์) · ไม่ถูกใจแก้ได้ด้วย PUT /v1/schema โดยไม่ต้องส่งข้อมูลใหม่
report บอกทุกฟิลด์ว่าค่าที่มาเป็นชนิดอะไรบ้างกี่ค่า ลงดัชนีเป็นอะไร และกี่ค่าที่เก็บไว้ในระเบียนแต่ไม่ได้ลงดัชนีเพราะไม่เข้ากับชนิดของฟิลด์ — เช่น brand ที่เป็นสตริงเกือบทุกแถวแต่เป็นออบเจกต์อยู่ 21 แถว · ค่าที่ไม่เข้าชนิดไม่ทำให้ทั้ง batch ถูกปฏิเสธ
stored คือจำนวน id ที่ไม่ซ้ำ changed คือที่ใหม่หรือเปลี่ยนจากที่เก็บไว้ ซึ่งเป็นสิ่งที่ sync ครั้งถัดไปจะส่ง · id ที่มาซ้ำในคำขอเดียวเก็บตัวสุดท้าย และบอกจำนวนใน duplicates
เพดานจำนวนระเบียนเป็นของแพ็กเกจ ถ้าคำขอนี้จะทำให้เกิน ทั้งก้อนถูกปฏิเสธก่อนเขียนอะไรลงไป
ข้อผิดพลาดของเส้นนี้
| ฟิลด์ | ความหมาย |
|---|---|
400 | เนื้อคำขอผิดรูป · ระเบียนไม่มี id (ข้อความบอกชื่อคอลัมน์ที่น่าจะเป็น id) · มีฟิลด์ที่ขึ้นต้นด้วย ns_ · มีอักขระ NUL |
402 | จำนวนระเบียนจะเกินเพดานของแพ็กเกจ |
403 | ใช้ client key — เส้นนี้ต้องใช้ service key |
413 | เนื้อคำขอเกิน 32 MB |
รูปของข้อผิดพลาด อัตราต่อวินาที และการลดทอน (degraded) อยู่ที่ ข้อผิดพลาดและเพดาน
POST /v1/documents/removeลบหลายระเบียน