jq 指令：JSON 資料的命令列處理

在現代運維與開發工作中，JSON 已經成為數據交換的標準格式。從 Kubernetes 的資源定義、Docker 容器的配置，到 RESTful API 的回應資料，我們幾乎每天都在與 JSON 打交道。雖然 Python 或 Node.js 能輕鬆處理 JSON，但在 Linux 終端機中，我們往往需要快速篩選、轉換或修改資料，這時 jq 就顯得尤為重要。

jq 被譽為「命令列的 sed、awk、grep 和 grep 的 JSON 版本」。它不僅能將 JSON 格式化輸出，更能透過強大的查詢語言進行資料的提取與轉換。本文將帶領你深入解析 jq 的核心用法，讓你成為 JSON 處理的高手。

安裝與基礎格式化

在 Ubuntu 22.04 或 Debian 12 上，安裝 jq 非常簡單：

sudo apt update
sudo apt install jq

假設我們有一個名為 data.json 的檔案，內容如下：

{
  "name": "John Doe",
  "age": 30,
  "skills": ["Linux", "Python", "Go"],
  "address": {
    "city": "Taipei",
    "zip": "100"
  }
}

最基礎的用法是將 JSON 格式化（Pretty Print），讓雜亂的單行 JSON 變為易讀的多行結構：

jq . data.json

輸出結果將自動縮排，清晰呈現資料結構。這在除錯 API 回應時極具幫助。

篩選特定欄位

實際應用中，我們通常只需要 JSON 中的特定欄位。jq 使用類似路徑的語法來訪問資料。

1. 訪問頂層欄位

若要取得 name 欄位：

jq '.name' data.json

輸出：

"John Doe"

注意：jq 預設會輸出字串帶雙引號。若需去除引號，可加上 -r (raw output) 參數：

jq -r '.name' data.json

輸出：

John Doe

2. 巢狀物件訪問

對於巢狀結構，使用 . 連接子欄位：

jq -r '.address.city' data.json

輸出：

Taipei

3. 陣列索引

jq 的陣列索引從 0 開始。若要取得 skills 陣列的第一個元素：

jq '.skills[0]' data.json

輸出：

"Linux"

若要取得最後一個元素，可使用負索引：

jq '.skills[-1]' data.json

輸出：

"Go"

進階過濾與地圖操作

當處理大型 JSON 資料或需要條件篩選時，jq 的過濾器（Filter）功能強大且靈活。

1. 條件篩選

假設我們想篩選出年齡大於 25 歲的人，可以使用 select 函數：

# 假設 data.json 是包含多個物件的陣列
[
  {"name": "John", "age": 30},
  {"name": "Jane", "age": 25},
  {"name": "Bob", "age": 20}
] | jq '.[] | select(.age > 25)'

輸出：

{
  "name": "John",
  "age": 30
}

2. 地圖操作（Map）

若要将陣列中的每個元素進行轉換，可使用 map。例如，將所有技能名稱轉為大寫：

jq '.skills | map(ascii_upcase)' data.json

輸出：

[
  "LINUX",
  "PYTHON",
  "GO"
]

3. 建立新物件

你可以使用 {key: value} 語法從現有資料建構新物件。例如，提取姓名與城市，並新增一個自訂欄位：

jq '{fullName: .name, location: .address.city, isSenior: (.age > 25)}' data.json

輸出：

{
  "fullName": "John Doe",
  "location": "Taipei",
  "isSenior": true
}

常見問題與解決方法

Q1: 遇到 "parse error: Invalid numeric literal at line 1, column 11" 錯誤？

這通常發生在嘗試對非 JSON 格式的純文字執行 jq 時。請確保輸入資料確實是合法的 JSON。若資料來自 API 回應，請檢查是否包含額外的 HTML 標籤或無效字元。此外，確保檔案編碼為 UTF-8，避免特殊字元導致解析失敗。

Q2: 如何處理大型 JSON 檔案而不耗盡記憶體？

jq 預設會將整個 JSON 載入記憶體。對於 GB 級別的大型檔案，建議使用 --stream 參數進行流式處理，或結合 grep 先進行初步篩選。例如，先利用 grep 找出包含特定關鍵字的行，再交給 jq 解析，可大幅降低資源消耗。

小結

jq 是 Linux 系統管理員與開發者不可或缺的利器。它不僅能簡化 JSON 的格式化工作，更能透過直觀的查詢語言完成複雜的資料轉換。掌握 ., [], select, map 等核心語法，你將能輕鬆應對各種 JSON 處理需求。建議在實際工作中多嘗試組合這些過濾器，並善用 jq 的官方文件以探索更多進階功能。