jq로 JSON 다루기 — 터미널에서 API 응답 파싱 | 기술노트

Q: jq '.field'에서 왜 앞에 점을 찍나요?

점( . )은 "현재 입력"을 뜻하는 항등 필터입니다. .field 는 "현재 입력의 field 속성"이라는 의미죠. 그냥 jq '.' 만 쓰면 입력 전체를 예쁘게 출력합니다.

Q: -r 옵션은 언제 쓰나요?

결과를 셸 변수나 다른 명령에 넘길 때입니다. jq 기본 출력은 문자열에 따옴표를 붙이는데, -r (raw)은 이를 제거해 abc123 처럼 순수 값으로 내보냅니다. 토큰 추출 같은 스크립트에서 필수입니다.

Q: 중첩이 깊은 값을 안전하게 꺼내려면요?

경로 중간이 null일 수 있으면 ? ( .a.b? )로 에러를 무시하거나 // 기본값 으로 대체하세요. jq '.user.address.city // "미상"' 처럼 쓰면 값이 없어도 안전합니다.

핵심 요약

jq는 커맨드라인 JSON 프로세서다. curl ... | jq만 붙여도 응답이 색상·들여쓰기로 예뻐지고, jq '.data[].name'처럼 필드를 뽑거나 select로 필터링·가공까지 한 줄로 된다. API 디버깅·셸 스크립트의 필수 도구다.

1. 예쁘게 보기 · 필드 추출

curl -s API | jq                 # 정렬·색상
curl -s API | jq '.name'         # 최상위 name
curl -s API | jq '.user.email'   # 중첩 접근
curl -s API | jq '.items[0]'     # 배열 첫 요소
curl -s API | jq '.items[].id'   # 모든 요소의 id

2. 배열 필터·변형

# 조건에 맞는 요소만
jq '.users[] | select(.age > 20)'

# 필요한 필드만 골라 새 객체로
jq '.users[] | {name, email}'

# 배열을 map으로 변형
jq '[.users[] | .name]'

# 개수 세기
jq '.users | length'

3. 자주 쓰는 조합

목적	표현
키 목록	`jq 'keys'`
값만 배열로	`jq '[.[].price]'`
정렬	`jq '.items \| sort_by(.date)'`
합계	`jq '[.items[].price] \| add'`
CSV로	`jq -r '.users[] \| [.name,.email] \| @csv'`

4. 원시 출력 -r

# 기본은 문자열에 따옴표가 붙음 → 셸에서 쓰기 불편
curl -s API | jq '.token'        # "abc..."
curl -s API | jq -r '.token'     # abc...  (따옴표 제거)

# 셸 변수에 담기
TOKEN=$(curl -s API | jq -r '.access_token')

5. 함정

필드가 없으면 null이 나온다 — // "기본값"으로 대체 가능(.name // "무명")
따옴표 없는 값이 필요하면 반드시 -r
거대한 JSON 스트림은 --stream 옵션으로 메모리 절약

자주 묻는 질문

jq '.field'에서 왜 앞에 점을 찍나요?

점(.)은 "현재 입력"을 뜻하는 항등 필터입니다. .field는 "현재 입력의 field 속성"이라는 의미죠. 그냥 jq '.'만 쓰면 입력 전체를 예쁘게 출력합니다.

-r 옵션은 언제 쓰나요?

결과를 셸 변수나 다른 명령에 넘길 때입니다. jq 기본 출력은 문자열에 따옴표를 붙이는데, -r(raw)은 이를 제거해 abc123처럼 순수 값으로 내보냅니다. 토큰 추출 같은 스크립트에서 필수입니다.

중첩이 깊은 값을 안전하게 꺼내려면요?

경로 중간이 null일 수 있으면 ?(.a.b?)로 에러를 무시하거나 // 기본값으로 대체하세요. jq '.user.address.city // "미상"'처럼 쓰면 값이 없어도 안전합니다.