คู่มือ jq Playground: เรียนรู้การเขียน jq Filter บน JSON แบบทดสอบได้ทันทีในเบราว์เซอร์

ถ้าคุณทำงานสาย developer มาสักระยะ คงเคยเจอ jq อย่างน้อยหนึ่งครั้ง ไม่ว่าจะเป็นสคริปต์ใน CI ที่ใช้สรุปผลการทดสอบ, shell one-liner ที่ใช้จัดรูปผลลัพธ์จาก curl, ผลลัพธ์จาก AWS CLI ที่มาเป็น JSON ซ้อนกันหลายชั้น หรือ log ใน GitHub Actions ที่ถูกกรองด้วย expression อย่าง .jobs[].name jq คือเครื่องมือมาตรฐานสำหรับดึงค่าที่ต้องการออกจาก JSON ใน command line ซึ่งแปลว่า developer เกือบทุกคนต้องเคยใช้มันสักครั้ง

จุดที่ต้องฝึกฝนคือไวยากรณ์ของ jq ค่อนข้างกระชับ วงเล็บหลุดแค่ตัวเดียวหรือลืม pipe ก็ error ทันที และวิธีเรียนรู้ที่ได้ผลที่สุดคือการลงมือทดลอง: วาง JSON ลงไป เขียน filter ดูผลลัพธ์ แล้วปรับต่อ ซึ่งถ้าทำในเทอร์มินัล คุณต้องติดตั้ง jq ก่อน เตรียมไฟล์ตัวอย่าง และรันคำสั่งซ้ำไปมาหลายรอบ

jq Playground ช่วยตัดขั้นตอนเหล่านี้ออกทั้งหมด เพียงวาง JSON พิมพ์ filter expression แล้วคุณจะเห็นผลลัพธ์ที่จัดรูปแล้วทันที ไม่ต้องติดตั้ง ไม่ต้องสมัครบัญชี และข้อมูลไม่ออกจากเบราว์เซอร์ของคุณเลย บทความนี้จะพาทำความรู้จักเครื่องมือนี้ พร้อมสอนชุด jq filter ที่ใช้บ่อยที่สุดในงานจริง

ทำไมต้องใช้ jq Playground?

• ไม่ต้องติดตั้งอะไรเลย — jq รองรับ Linux, macOS และ Windows แต่เครื่องบริษัทที่ล็อกสิทธิ์มักไม่มีให้ติดตั้ง Playground ต้องแค่เปิดแท็บเบราว์เซอร์ จึงฝึกและ prototype ได้ทุกที่
• Feedback loop ที่ไวมาก — ทุกครั้งที่พิมพ์ filter จะถูกประมวลผลกับ JSON ของคุณทันที ซึ่งเป็นสิ่งจำเป็นในการเรียน query language การวนกลับไปแก้ไฟล์แล้วรันใหม่ในเทอร์มินัลช้ากว่าหลายเท่า
• Syntax error พร้อมตำแหน่ง — เมื่อ filter ไม่ถูกต้อง เครื่องมือจะบอกข้อผิดพลาดและตำแหน่งที่เกิดขึ้น ทำให้แก้วงเล็บได้ตรงจุดแทนการจ้องข้อความ error ทั่วไปในเชลล์
• ตัวอย่าง query ที่นำกลับมาใช้ได้ — มีชุด preset expression ตั้งแต่ identity filter ไปจนถึง select() และการรวมค่า กดคลิกเดียวก็เห็นไวยากรณ์ที่ถูกต้องพร้อมปรับใช้
• ประมวลผลฝั่ง client ทั้งหมด — การประเมินผลเกิดในเบราว์เซอร์ล้วน ๆ วาง response จาก API ภายใน ตัวอย่าง config หรือ log ได้อย่างปลอดภัยโดยไม่มีข้อมูลส่งออกไปไหน
• ผลลัพธ์จัดรูปให้สวยงาม — output ถูก pretty-print ทำให้เห็นรูปร่างของผลลัพธ์ได้ชัดเจนทันทีว่าเป็นค่าเดียวหรือเป็น stream ของหลายค่า

ฟีเจอร์หลัก

จุดที่น่าสังเกตเพิ่มเติมมีดังนี้

• ใส่ JSON แบบยุบบรรทัดเดียวได้ — payload ที่คัดลอกมาจาก curl หรือ API log มักเป็นบรรทัดยาวเส้นเดียว เครื่องมือจัดการได้เทียบเท่า JSON แบบจัดรูปแล้ว
• Error ถูกระบุตำแหน่ง ไม่ใช่แค่หยุดทำงาน — แก้ข้อมูลเสร็จ filter จะประเมินผลใหม่ทันที ไม่ต้องรีโหลดอะไรเลย
• แผง output แสดง stream ให้เห็นจริง — เมื่อ filter ปล่อยค่าออกมาหลายค่า คุณจะเห็นทีละค่า ซึ่งช่วยสร้าง mental model ที่ถูกต้องว่า jq ทำงานอย่างไร

วิธีการใช้งาน jq Playground

1. วาง JSON ของคุณ — คัดลอก response จาก API call, CI log หรือไฟล์ config มาวางในพื้นที่ input ถ้าข้อมูลเสียหายจะถูกแจ้งเตือนทันที
2. เริ่มจาก identity filter — พิมพ์ . แล้วดูว่าเอกสารที่ parse แล้วปรากฏใน output วิธีนี้ยืนยันว่า JSON ถูกต้องก่อนเริ่มกรองข้อมูล
3. ลดขอบเขตด้วย field access — เปลี่ยน . เป็น .repo หรือ .items[] เพื่อดึง field เดียวหรือวนซ้ำ array
4. ต่อขั้นตอนด้วย pipe — โยงหลาย operation เข้าด้วยกัน เช่น iterate, select, transform แล้วเช็ก output ทีละขั้น ถ้าเจอ syntax error ตำแหน่งที่รายงานจะบอกว่าขั้นไหนพัง
5. คัดลอก filter ที่ใช้งานได้กลับไปใส่สคริปต์ — เมื่อ expression คืนค่าตรงตามต้องการแล้ว นำไปวางใน shell one-liner, CI step หรือ runbook ของคุณได้เลย

jq Filters ที่ควรจำขึ้นใจ

ก่อนเข้าตัวอย่าง ขอแนะนำแนวคิดที่อธิบายเกือบทุกอย่างของ jq ได้: filter ทุกตัวแปลง stream ของค่า input ให้กลายเป็น stream ของค่า output เอกสาร JSON หนึ่งชิ้นคือ stream ที่มีค่าเดียว ส่วน suffix แบบ [] จะระเบิด array ออกเป็นค่าละหนึ่งชิ้น และ pipe จะส่งแต่ละค่าที่ผลิตได้ไปต่อในขั้นถัดไป พออ่าน filter ด้วยมุมมองนี้ expression ที่ซับซ้อนจะดูน่ากลัวน้อยลงทันที

ใช้ผลการรัน CI จริงด้านล่างนี้เป็น payload หลักสำหรับทั้งสามตัวอย่าง

{
  "repo": "forge/web-tools",
  "branch": "main",
  "items": [
    { "name": "build-api", "status": "passed", "duration_ms": 1840 },
    { "name": "build-web", "status": "passed", "duration_ms": 2210 },
    { "name": "e2e-suite", "status": "failed", "duration_ms": 9870 }
  ]
}

Identity และ field access — filter . คืนค่า input ตามเดิม .repo คืนค่า "forge/web-tools" และ .items[0].name คืนค่า "build-api" ส่วน field ที่ไม่มีอยู่จะคืนค่า null แทนการ error ซึ่งสะดวกมากเวลา payload ต่างเวอร์ชันกัน

Iteration — .items[] เปลี่ยน input หนึ่งค่าให้กลายเป็นสามค่าตามจำนวน check ต่อท้ายด้วย field access: .items[] | .name จะ stream ค่า build-api, build-web และ e2e-suite ออกมาเป็นสามผลลัพธ์แยกกัน

ตัวอย่างที่ 1 — หา check ที่ล้มเหลว ส่ง stream เข้า select() ซึ่งปล่อยผ่านเฉพาะค่าที่เงื่อนไขเป็นจริง

.items[] | select(.status == "failed") | .name

ผลลัพธ์คือค่าเดียวคือ e2e-suite ลองเปลี่ยนเงื่อนไขเป็น .status != "passed" ก็ตอบคำถามอีกแบบด้วยรูปแบบเดิม

ตัวอย่างที่ 2 — สร้างบรรทัดสรุปที่อ่านง่าย string interpolation ฝังค่าลงในข้อความด้วย \(...)

.items[] | "\(.name) finished in \(.duration_ms / 1000) seconds"

แต่ละค่าใน stream จะผลิตประโยคที่อ่านเข้าใจง่ายหนึ่งประโยค ซึ่งเป็นบรรทัดที่เอาไปวางใน notification หรือ build report ได้พอดี

ตัวอย่างที่ 3 — รวมค่ากลับเป็นค่าเดียว stream ดีมาก แต่สคริปต์มักต้องการผลลัพธ์เดียว ครอบ iteration ด้วยวงเล็บเหลี่ยมเพื่อเก็บ stream เป็น array แล้วค่อยรวมค่า

[.items[].duration_ms] | add / 1000

ได้ผลลัพธ์เป็นเวลารวม 13.92 วินาที รูปแบบ iterate, transform, collect แบบ [.items[] | ...] เป็นหนึ่งในโครงสร้างที่ถูกใช้ซ้ำมากที่สุดใน jq โค้ดจริง

Builtins ที่ควรรู้จัก — keys แสดงรายชื่อ field ของ object, values แสดงค่าทั้งหมด และ length นับสมาชิกของ array, จำนวน key ของ object หรือจำนวนตัวอักษรของ string expression อย่าง .items | length ตอบคำถามว่า "มี check รันไปกี่ตัว" ได้ในสี่ตัวอักษร

กรณีการใช้งานจริงของ jq

Parse JSON จาก GitHub และ API ใน Shell Script

การใช้ jq ส่วนใหญ่เกิดใน pipeline: curl -s https://api.example.com/runs | jq '.items[] | select(.status == "failed") | .name' การเขียน expression แบบเดาสุ่มกับ endpoint จริงเสี่ยงมาก ทางที่ดีคือเซฟ response ตัวอย่างหนึ่งชุด วางลง playground ยืนยันผลลัพธ์ แล้วค่อยฝัง filter ลงในสคริปต์ CI step ของคุณจะไม่พังเพราะพิมพ์ filter ผิดอีกต่อไป

ดึงข้อมูลจาก Log และ Event

แพลตฟอร์มยุคใหม่ปล่อย log ในรูปแบบ JSON ไม่ว่าจะเป็นสรุป job ของ GitHub Actions, event ของบริการ cloud หรือ application log เวลาเกิด incident ให้วาง log ช่วงหนึ่งลงไปแล้วใช้ filter ข้างต้นตอบคำถาม triage ได้ในไม่กี่วินาที ว่า step ไหนล้มเหลว แต่ละ step ใช้เวลาเท่าไร และค่าที่สนใจปรากฏตรงไหนของ payload

สำรวจ Config และ Manifest

Lockfile, Kubernetes manifest และไฟล์ state ของ infrastructure ล้วนเป็น JSON แทนการเลื่อนดูหลายพันบรรทัด ให้รัน keys เพื่อดูโครงสร้างระดับบนสุด ใช้ length วัดขนาด array และใช้ field access แบบเจาะจงเพื่อดึง entry เดียวที่คุณต้องการจริง ๆ

สอน jq ให้เพื่อนร่วมทีม

Playground ทำหน้าที่เป็นพื้นที่สอนได้ด้วย ใน code review หรือ session จับคู่ programming ให้วาง payload จริง สร้าง filter สด ๆ ต่อหน้า แล้วใช้ตัวอย่าง preset ชี้รูปแบบมาตรฐาน เพื่อนร่วมทีมที่เห็น stream และ select() สาธิตครั้งเดียวมักเลิกเขียนสคริปต์ Python ชั่วคราวมาทำงานเดียวกันเสียก่อน

Best Practices สำหรับการเขียน jq

• Prototype ที่นี่ก่อน แล้วค่อยเอาไปใส่สคริปต์ — การวนลูปใน playground เร็วและปลอดภัยกว่าการทดสอบ filter กับ endpoint จริงหรือ cron job
• ใส่เครื่องหมายคำพูดครอบ key ที่มีอักขระพิเศษ — field อย่าง user-id หรือ content-type ต้องใช้รูปแบบ .["user-id"] เพราะ .user-id จะถูกแปลว่าเป็นการลบ
• จำเรื่อง stream ไว้เสมอ — filter ที่ปล่อยค่าออกมาหลายค่าไม่ใช่ความผิดพลาด แต่เป็น iteration ครอบด้วย [...] เฉพาะเมื่อต้องการ array เดียวจริง ๆ
• เก็บ payload ตัวอย่างที่ใกล้เคียงของจริงไว้ — filter ที่เวิร์กกับข้อมูลสวยงามมักพังกับรูปร่างจริงที่มี optional field จึงควรเซฟ response ตัวแทนหนึ่งชุดต่อ API ที่คุณ query
• ใช้ builtins สำรวจก่อนเจาะลึก — keys, length และ identity filter กับ payload ใหม่ให้ข้อมูลมากกว่าการเดา field path อยู่ห้าวินาทีแน่นอน
• ดูตำแหน่ง error ไม่ใช่แค่ข้อความ — error ของ jq ชี้บริเวณใกล้ตัวอักษรที่ผิด playground แสดงตำแหน่งนั้นให้ ทำให้มักรู้ว่าต้องแก้ตรงไหนทันที

พร้อมฝึก jq Filter กับข้อมูลจริงหรือยัง?

เปิด jq Playground วาง JSON response ที่น่าเกลียดที่สุดที่คุณเจอสัปดาห์นี้ แล้วเขียน filter หนึ่งตัวที่คุณใช้แบบ copy มาทั้งดุ้นใหม่ตั้งแต่ต้น สิบนาทีของการฝึกกับข้อมูลจริงจะช่วยทักษะ jq ของคุณได้มากกว่า cheat sheet หลายแผ่น และทุกอย่างรันในเบราว์เซอร์ของคุณล้วน ๆ

เครื่องมือที่เกี่ยวข้องที่คุณอาจสนใจ:

• JSON Formatter — จัดรูปและตรวจ JSON ที่ยุ่งเหยิงให้อ่านง่ายก่อนเขียน filter
• JMESPath Tester — ฝึก JMESPath ภาษา query ที่อยู่เบื้องหลังพารามิเตอร์ --query ของ AWS CLI
• GraphQL Formatter — จัดรูปและตรวจ GraphQL query และ response ควบคู่กับเครื่องมือ JSON ของคุณ

ขอให้สนุกกับการกรองข้อมูล

คำถามที่พบบ่อย

ถ: ข้อมูล JSON ของฉันถูกอัปโหลดขึ้นเซิร์ฟเวอร์หรือไม่?

ตอบ: ไม่ครับ jq Playground ประมวลผล filter ทั้งหมดในเบราว์เซอร์ด้วย JavaScript สิ่งที่คุณวางไม่ถูกส่ง เก็บ หรือ log ที่ใดเลย จึงปลอดภัยกับ payload ภายในและตัวอย่าง config

ถ: ต้องติดตั้ง jq ก่อนใช้ playground หรือเปล่า?

ตอบ: ไม่ต้อง เครื่องมือนี้รันการประเมิน jq filter ฝั่ง client คุณจึงเรียนรู้และ prototype ในเบราว์เซอร์ได้เลย และค่อยติดตั้ง jq ภายหลังเมื่อสคริปต์ต้องใช้จริง

ถ: สิ่งที่เรียนที่นี่ใช้กับ jq บน command line ได้จริงไหม?

ตอบ: ได้ครับ ไวยากรณ์ทั้งหมด ไม่ว่าจะเป็น field access, iteration แบบ [], pipe, select() และ builtins อย่าง length กับ keys เป็น jq มาตรฐาน filter ที่เวิร์กใน playground จะทำงานเหมือนกันในเทอร์มินัลหรือ CI script

ถ: output แสดงหลายค่าแทนที่จะเป็น array เดียว เป็นบั๊กหรือเปล่า?

ตอบ: ไม่ใช่ครับ iteration ด้วย [] ผลิต stream ของค่าออกมา ถ้าต้องการ array เดียวให้ครอบ expression ด้วยวงเล็บเหลี่ยม เช่น [.items[] | .name] ส่วนถ้า JSON ตั้งต้นเสีย พื้นที่ input จะรายงาน syntax error พร้อมตำแหน่งให้ก่อน filter ใด ๆ รัน