jq: xử lý JSON ngay trong terminal với mười cú pháp cần biết

API trả về JSON, file cấu hình là JSON, log là JSON. Mỗi lần cần lấy một trường hay lọc vài phần tử, nhiều người mở trình duyệt, dán vào công cụ online, hoặc viết script Python ngắn. jq làm việc đó ngay trong terminal: một ngôn ngữ truy vấn nhỏ gọn để đọc, lọc, biến đổi JSON, ghép tự nhiên với curl và các lệnh khác. Học khoảng mười cú pháp là đủ cho hầu hết việc hằng ngày.

GitHub: https://github.com/jqlang/jq · khoảng 36 nghìn sao · C · MIT

Cài đặt

brew install jq          # macOS
sudo apt install jq      # Ubuntu/Debian
# Hoặc dùng Docker, theo README:
docker run --rm -i ghcr.io/jqlang/jq:latest < package.json '.version'

Mười cú pháp dùng nhiều nhất

Ví dụ với file users.json là một mảng các object {"id", "name", "age", "team"}:

Ví dụ thực tế

# Lấy tên và số sao các repo của một tổ chức trên GitHub
curl -s "https://api.github.com/orgs/astral-sh/repos?per_page=100" \
  | jq -r '.[] | "\(.stargazers_count)\t\(.name)"' | sort -rn | head

# Lấy version trong package.json để dùng trong script
VERSION=$(jq -r .version package.json)

# Truyền biến từ shell vào jq một cách an toàn
jq --arg env "prod" '.[] | select(.env == $env)' deployments.json

# Sửa một trường và ghi ra file mới
jq '.scripts.test = "vitest run"' package.json > tmp.json && mv tmp.json package.json

# Lọc log JSON theo mức lỗi
cat app.log | jq -c 'select(.level == "error") | {time, msg}'

Cờ quan trọng

• -r: in chuỗi không có dấu ngoặc kép, cần khi gán vào biến shell.
• -c: mỗi kết quả một dòng, gọn để pipe tiếp.
• -s: gom nhiều JSON đầu vào thành một mảng (hữu ích với log JSON mỗi dòng một object).
• -n: không đọc đầu vào, dùng để tạo JSON mới.
• -e: trả mã thoát khác 0 nếu kết quả là null/false, tiện dùng trong điều kiện của script.

Lưu ý

• Không ghi đè trực tiếp jq ... file > file: shell xoá file trước khi jq đọc. Luôn ghi ra file tạm rồi đổi tên.
• Dùng --arg thay vì ghép chuỗi shell vào biểu thức jq để tránh lỗi trích dẫn và injection.
• Với JSON rất lớn, jq đọc cả vào bộ nhớ; cân nhắc chế độ --stream.

Áp dụng thế nào?

• Dev: Dùng jq để khám phá response API khi debug, và trong script build để đọc phiên bản, cấu hình.
• Tech Lead: Chuẩn hoá log dạng JSON để cả team truy vấn được bằng jq khi có sự cố, không cần công cụ nặng.
• PM: Một dòng jq có thể trả lời nhanh câu hỏi số liệu từ API (bao nhiêu bản ghi, nhóm theo trạng thái) mà không chờ dashboard.