jq

AI
gemma-4-31b
작성자
익명
작성일
2026.08.03
조회수
1
버전
v1
기술 → 데이터과학 → 데이터 처리 도구
jq JSON CLI 데이터 파싱 쉘 스크립트 데이터 처리 도구 초급

jq

개요

jq는 명령줄 인터페이스(CLI) 환경에서 JSON(JavaScript Object Notation) 데이터를 처리, 필터링, 변형하기 위한 경량적이고 유연한 명령줄 JSON 프로세서입니다.

현대적인 소프트웨어 개발 환경에서 REST API의 응답 값이나 설정 파일, 로그 데이터 등이 대부분 JSON 형식을 취함에 따라, 텍스트 기반의 쉘 환경에서 복잡한 JSON 구조를 효율적으로 파싱하고 원하는 데이터만 추출하기 위한 필수적인 도구로 자리 잡았습니다. jq는 단순한 텍스트 검색 도구인 grep이나 sed와 달리 JSON의 계층 구조를 이해하고 처리하는 전용 문법을 제공합니다.

설치 및 기본 사용법

운영체제별 설치 방법

jq는 대부분의 주요 운영체제 패키지 관리자를 통해 설치할 수 있습니다.

운영체제 설치 명령어
macOS brew install jq
Ubuntu/Debian sudo apt-get install jq
CentOS/RHEL sudo yum install jq
Windows choco install jq 또는 scoop install jq

기본 실행 구문

jq의 기본 실행 구조는 다음과 같습니다. 

jq '[필터]' [파일명 또는 입력값]

단순 출력 예제: data.json 파일의 내용이 {"name": "Alice", "age": 25}일 때, 전체 내용을 예쁘게 출력(Pretty-print)하려면 마침표(.) 필터를 사용합니다. 

jq '.' data.json

핵심 필터 및 문법

데이터 추출 및 처리 원리

jq는 필터(Filter)라는 개념을 사용하여 데이터를 처리합니다. 필터는 입력 데이터를 받아 변형한 뒤 출력하는 함수와 같습니다.

  • 점 표기법 (.): 루트 객체를 의미하며, .key 형태로 특정 키의 값에 접근합니다.
  • 배열 처리 ([]): 배열의 모든 요소를 개별적으로 출력하거나, .[0]과 같이 인덱스로 접근합니다.
  • 파이프라인 (|): 앞선 필터의 출력 결과를 다음 필터의 입력으로 전달합니다. 이는 유닉스 쉘의 파이프와 유사한 동작 방식입니다.

주요 연산자 및 필터 요약

연산자/함수 설명 예시 결과
. 루트 객체 전체 출력 jq '.' 전체 JSON 출력
.key 특정 키의 값 추출 jq '.name' "Alice"
.[] 배열의 모든 요소 전개 jq '.items[]' 배열 내 각 객체 출력
.[index] 배열의 특정 인덱스 접근 jq '.items[0]' 첫 번째 요소 출력
| 필터 체이닝 (결과 전달) jq '.items[] | .name' 모든 아이템의 이름만 추출
slice 배열의 일부 구간 추출 jq '.items[0:2]' 0번부터 1번 인덱스까지 추출

고급 기능 및 함수

제어문 및 내장 함수

단순 추출을 넘어 데이터를 가공하기 위해 다음과 같은 고급 기능을 제공합니다.

  • select(condition): 조건에 맞는 요소만 필터링합니다.
  • 예: jq '.[] | select(.age > 20)' (나이가 20 초과인 요소만 추출)
  • map(filter): 배열의 모든 요소에 특정 필터를 적용하여 새로운 배열을 생성합니다.
  • 예: jq 'map(.name)' (객체 배열에서 이름만 추출하여 새로운 배열 생성)
  • keys: 객체의 모든 키를 배열 형태로 반환합니다.
  • length: 배열의 길이, 문자열의 길이, 또는 객체의 키 개수를 반환합니다.
  • if-then-else: 조건부 로직을 구현합니다.
  • 문자열 보간법 (\(expression)): 문자열 내에 \( )를 사용하여 변수나 필터의 결과값을 삽입할 수 있습니다. (예: "Hello, \(.name)!")

실전 복잡 쿼리 예제

다음과 같은 JSON 데이터(users.json)가 있다고 가정합니다. 

[
  {"id": 1, "name": "Kim", "role": "admin", "tags": ["dev", "ops"]},
  {"id": 2, "name": "Lee", "role": "user", "tags": ["design"]},
  {"id": 3, "name": "Park", "role": "admin", "tags": ["dev", "security"]}
]

요구사항: 역할이 'admin'인 사용자들의 이름만 추출하여 새로운 배열로 만들기 

jq '[ .[] | select(.role == "admin") | .name ]' users.json
# 결과: ["Kim", "Park"]

실무 활용 사례

API 응답 값 파싱

curl 명령어로 받은 JSON 응답에서 특정 값만 추출하여 쉘 변수에 할당하는 방식이 가장 흔하게 사용됩니다. 이때 -r (raw-output) 옵션을 사용하지 않으면 결과값에 쌍따옴표(")가 포함되어 쉘 변수 활용 시 오류가 발생할 수 있으므로 주의해야 합니다.

# GitHub API를 통해 특정 저장소의 Star 개수 추출 (-r 옵션으로 따옴표 제거)
STAR_COUNT=$(curl -s https://api.github.com/repos/jqlang/jq | jq -r '.stargazers_count')
echo "This repo has $STAR_COUNT stars."

로그 파일 분석 및 변형

JSON 형식의 로그 파일에서 에러 레벨이 "ERROR"인 로그의 메시지와 타임스탬프만 추출하여 텍스트 파일로 저장하는 사례입니다.

cat app.log | jq -r '.[] | select(.level == "ERROR") | "\(.timestamp) - \(.message)"' > error_report.txt

JSON 입력 방식별 차이점

jq는 다양한 방식으로 데이터를 입력받을 수 있으며, 입력 방식에 따라 처리 흐름이 달라집니다.

입력 방식 명령어 예시 특징
파일 입력 jq '.' file.json 파일 시스템에서 직접 읽어 처리하며 대용량 파일에 적합함
표준 입력 (stdin) cat file.json | jq '.' 다른 명령어의 출력을 파이프로 받아 처리하는 전형적인 유닉스 방식
문자열 입력 echo '{"a":1}' | jq '.' 짧은 JSON 문자열을 즉석에서 테스트할 때 유용함
여러 파일 입력 jq '.' a.json b.json 여러 파일을 순차적으로 읽어 각각 필터를 적용함

성능 최적화 및 팁

자주 쓰이는 옵션 요약

옵션 긴 이름 설명
-r --raw-output 출력값의 따옴표를 제거하고 원시 문자열(raw string)로 출력. 쉘 스크립트 연동 시 필수적임
-c --compact-output 줄바꿈 없이 한 줄로 압축하여 출력 (로그 저장 시 유리)
-S --sort-keys 객체의 키를 알파벳 순으로 정렬하여 출력
-s --slurp 입력된 여러 JSON 객체를 하나의 큰 배열로 묶어서 처리

대용량 파일 처리 주의점

jq는 기본적으로 입력 데이터를 메모리에 로드하여 처리합니다. 수 GB 단위의 매우 큰 JSON 파일을 처리할 때 메모리 부족 현상이 발생할 수 있습니다. 이 경우 다음과 같은 전략을 권장합니다.

  1. --stream 옵션: 데이터를 스트리밍 방식으로 처리하여 메모리 사용량을 최소화합니다. 다만, 일반 필터와 문법이 완전히 다르며 매우 복잡하므로, 사용 전 공식 문서의 Streaming 섹션을 반드시 참조하십시오.
  2. 예시: jq --stream 'select(.[0][0] == "key")' large.json
  3. split 활용: 파일을 적절한 크기로 나누어 처리합니다.

참고 문헌 및 링크

AI 생성 콘텐츠 안내

이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.

주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.

이 AI 생성 콘텐츠가 도움이 되었나요?