← 전체 글
업데이트: May 29, 20267 min read

jq 튜토리얼: JSON 필터링과 변환

실용적인 jq 튜토리얼: 설치, 예쁘게 출력과 압축, 필드 선택, select로 배열 필터링, map으로 변환, 바로 쓸 수 있는 명령어 레시피.

jq 는 JSON 을 자르고, 필터링하고, 변환하는 표준 커맨드라인 도구입니다. 한 줄짜리 명령을 API 응답·로그 파일·설정을 다루는 강력한 쿼리 언어로 바꿔 줍니다. 이 튜토리얼에서는 설치, 매일 쓰게 될 핵심 filter, 그리고 가장 흔한 실제 작업을 위한 복붙용 recipe 모음을 다룹니다.

jq 란?

jq 는 파일이나 표준 입력에서 JSON 을 읽어 filter 를 적용하고, JSON(또는 raw 텍스트) 를 표준 출력으로 씁니다. 기본적으로 보기 좋게 출력하며, 데이터를 어디로도 보내지 않습니다 —— 로컬 바이너리라 민감한 payload 에도 안성맞춤입니다.

jq 설치

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget or choco)
winget install jqlang.jq

# 확인
jq --version

Identity Filter: 무엇이든 예쁘게 출력

가장 단순한 filter . 는 입력을 그대로 돌려줍니다 —— 덕분에 jq 는 즉석 포매터가 됩니다:

# 파일을 예쁘게 출력
jq . data.json

# curl 응답을 예쁘게 출력
curl -s https://api.example.com/users | jq .

# 반대로 minify (compact 출력)
jq -c . data.json

필드 선택

객체로는 .key, 배열로는 [] 로 파고들어 갑니다:

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# 배열의 모든 원소
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# 배열의 각 원소에서 한 필드씩
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# -r 로 JSON 따옴표 제거 (raw output)
jq -r '.[].name' users.json

select 로 필터링

# 조건에 맞는 객체만 남기기
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# 숫자 비교
jq '.[] | select(.age > 30)' users.json

map 와 객체 구성으로 변형하기

# 각 원소를 새 객체로 재구성
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# 평면적인 값 리스트 뽑기
jq '[.[].email]' users.json     # ["a@x.com", ...]

# filter 를 | 로 연결
jq '.items | map(.price) | add' order.json   # 전체 price 합

자주 쓰는 Recipe

작업명령
예쁘게 출력jq . file.json
Minifyjq -c . file.json
필드 한 개 뽑기jq '.data.token' resp.json
Raw 문자열(따옴표 없이)jq -r '.token' resp.json
배열 길이 세기jq '. | length' list.json
객체의 key 들jq 'keys' obj.json
행 필터링jq '.[] | select(.active)'
필드로 정렬jq 'sort_by(.age)'
필드 합계jq '[.[].amount] | add'
객체 key 정렬jq --sort-keys . file.json
유효성 검증(exit code)jq empty file.json

객체 재구성: to_entries / from_entries

jq 에서 가장 유용한 객체 형태 변환기 두 가지:

# 모든 key 의 이름 바꾸기 (여기서는 소문자화)
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# 값이 null 인 key 버리기
jq 'with_entries(select(.value != null))' file.json

# 객체 ⇄ 쌍의 배열
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

보간과 출력 형식: \(.x), @csv, @json, @base64

jq 에는 문자열 보간과 JSON 을 다른 형식으로 바꾸는 format 문자열 이 내장되어 있습니다:

# 따옴표 문자열 안에서의 문자열 보간
jq -r '"\(.user) bought \(.items|length) items"' order.json

# 객체당 한 줄짜리 CSV
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# 셸에서 쓸 인라인 JSON (이스케이프된 문자열 리터럴)
jq -r '.user | @json' record.json

# 값을 Base64 인코딩 (token / data URI 에 유용)
jq -r '.payload | @base64' message.json
# 디코드 쪽: 최신 jq 는 @base64d 를 지원

jq 로 JSON 검증하기

jq 는 잘못된 입력에 대해 0 이 아닌 exit code 를 반환하므로 jq empty file.json 는 스크립트와 CI 에서 깔끔한 유효성 검사가 됩니다 —— 다른 검증 방법은 JSON 검증 방법 참고.

브라우저 도구가 더 빠를 때

jq 는 스크립트와 파이프라인에서 진가를 발휘하지만, 일회성 작업 —— 붙여넣은 응답 예쁘게 출력, 처음 보는 구조 살펴보기, 깨진 JSON 수리 —— 에는 설치도 셸 이스케이프도 필요 없는 브라우저 도구가 더 빠릅니다:

자주 묻는 질문

jq 로 JSON 을 예쁘게 출력하려면?

jq . file.json 를 실행하세요 —— identity filter . 가 입력을 돌려주고 jq 가 기본으로 예쁘게 출력합니다. compact 출력은 -c 를 쓰세요.

jq 로 단일 필드를 추출하려면?

jq '.data.token' 같은 경로 filter 를 쓰고, 따옴표 없는 raw 값을 원하면 -r 를 추가하세요.

jq 로 JSON 배열을 필터링하려면?

.[] 로 순회하고 select() 를 적용하세요. 예: jq '.[] | select(.active == true)'.

jq 로 JSON 을 검증할 수 있나요?

네 —— jq empty file.json 는 입력을 파싱해서 잘못되었으면 0 이 아닌 exit code 로 끝나므로 CI 에서 유용합니다. 자세한 내용은 JSON 검증 방법.

계속 읽기