jq로 JSON 객체 변환 및 생성

API나 로그 파일에서 받은 원시 JSON은 필요한 형태와 정확히 일치하는 경우가 드뭅니다. 큰 객체를 받았지만 특정 필드만 필요할 수도 있고, 키 이름을 바꾸거나 중첩된 구조를 평탄화하거나 다른 서비스로 보낼 완전히 새로운 페이로드를 만들어야 할 수도 있습니다.

jq는 이러한 변환을 하나의 파이프라인에서 수행할 수 있게 해 주는 가볍고 강력한 명령줄 JSON 처리 도구입니다. 이 강의에서는 데이터를 재구성하는 세 가지 핵심 기법을 배웁니다.

• 객체 구성 — 처음부터 새로운 JSON 객체 만들기
• map — 배열의 모든 요소에 변환 적용하기
• to_entries / from_entries — 객체의 키-값 쌍을 배열처럼 다루어 필터링하고 다시 구성하기

모든 예제에서는 jq가 설치되어 있다고 가정합니다(apt install jq / brew install jq).

jq의 가장 기본적인 기능은 객체 구성입니다. 표현식을 {}로 감싸 새로운 JSON 객체를 만듭니다. 어떤 필드를 포함할지와 필드 이름을 어떻게 지정할지를 직접 선택할 수 있습니다.

구문:

• { newKey: .existingField } — 필드 이름 바꾸기
• { name, age } — 새 키가 필드 이름과 같을 때 사용하는 축약형
• { total: (.price * .qty) } — 인라인으로 값 계산하기

아래 코드는 상품 JSON을 읽고 계산된 subtotal 필드를 포함한 더 간결한 형태를 만듭니다.

실제 JSON은 중첩되어 있는 경우가 많습니다. jq를 사용하면 객체 생성자 안에서 중첩된 경로에 접근하면서 동시에 구조를 평탄화할 수 있습니다.

생성자 값 표현식 안에서 점으로 구분된 경로 표기법을 사용하세요.

• { city: .address.city }
• { lat: .location.coords.lat }

아래 예제는 깊게 중첩된 사용자 레코드를 가져와 CSV 헤더 행이나 API 요청 본문에 적합한 평탄한 요약으로 만듭니다.

map(expr)는 jq에서 각 요소에 적용하는 반복에 해당합니다. 입력 배열의 모든 요소에 expr을 적용하고, 같은 길이의 새로운 배열을 반환합니다.

핵심 사항:

• map(expr)은 [.[] | expr]의 축약형입니다.
• 내부의 표현식에는 객체 구성 등 어떤 jq 필터든 사용할 수 있습니다.
• select()와 연결하면 변환하기 전에 필터링할 수 있습니다.

이 코드는 주문 목록을 처리하여 배송 명세서에 필요한 필드만 남깁니다.

map 안에서는 단순히 값을 복사하는 것뿐 아니라 새로운 값을 계산하고, 형식을 변환하고, 필드를 결합할 수 있습니다. 일반적인 패턴은 다음과 같습니다.

• 문자열 보간: "\(.first) \(.last)"
• 산술 연산: 20% 인상을 적용하는 (.price * 1.2 | round)
• 조건문: if .score >= 90 then "A" else "B" end

아래 예제는 경력 연수에 따라 계산된 fullName과 seniority 레이블을 추가하여 직원 목록을 보강합니다.

to_entries는 JSON 객체를 {key, value} 쌍의 배열로 변환합니다. 이를 통해 객체의 필드에 배열 연산(map, select, sort)을 적용할 수 있습니다. 객체에는 이러한 연산을 직접 적용할 수 없습니다.

변환 예:

• 입력: {"a": 1, "b": 2}
• 출력: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

반대 연산은 from_entries이며, 이 연산은 배열을 다시 객체로 바꿉니다. 두 연산을 함께 사용하면 객체 수준 변환을 위한 to_entries | map(...) | from_entries 관용구를 구성할 수 있습니다.

to_entries의 가장 실용적인 용도 중 하나는 키 이름 자체를 기준으로 유지하거나 제외할 키를 동적으로 필터링하는 것입니다. 키 이름을 미리 알 수 없을 때는 객체 구성만으로 이 작업을 수행할 수 없습니다.

패턴:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

아래 코드는 구성 객체를 외부 서비스로 전달하기 전에 밑줄로 시작하는 모든 키(내부/비공개 필드)를 제거합니다.

객체 구성은 작성 시점에 이름을 알고 있는 키의 이름을 바꿉니다. to_entries를 사용하면 키 이름을 프로그래밍 방식으로 바꿀 수 있습니다. 예를 들어 camelCase를 snake_case로 변환하거나 접두사를 추가할 수 있습니다.

map 안에서 각 항목의 .key 필드를 업데이트한 다음 from_entries로 전달합니다.

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — camelCase를 snake_case로 변환
• map(.key |= "app_" + .) — 모든 키에 접두사 추가

이 예제는 컨테이너에 주입하기 전에 모든 환경 변수 이름에 APP_ 접두사를 붙여 이름 공간을 만듭니다.

to_entries | map(...) | from_entries 패턴은 매우 자주 사용되므로 jq는 with_entries(expr)라는 축약형을 제공합니다.

동일한 기능을 더 간결하게 표현한 것입니다.

• with_entries(.value |= . * 2) — 모든 숫자 값을 두 배로 만들기
• with_entries(select(.value != null)) — 값이 null인 키 제거하기
• with_entries(.key |= ascii_upcase) — 모든 키를 대문자로 바꾸기

아래 코드는 REST API에 PATCH 요청을 보내기 전에 값이 null이거나 빈 문자열인 모든 키를 제거합니다. 이는 흔히 수행하는 정리 단계입니다.

실제 변환에서는 여러 jq 연산을 함께 연결합니다. API 페이로드를 준비하는 일반적인 파이프라인은 다음 작업을 수행할 수 있습니다.

1. map(select(...))로 입력 배열 필터링하기
2. 객체 구성으로 각 요소의 형태 재구성하기
3. 계산된 필드 추가하기
4. 결과 정렬하기

아래 예제는 서버 지표 목록을 읽고 CPU 사용량이 높은 서버만 남긴 다음, 웹훅에 POST할 수 있는 간결한 경고 페이로드를 만듭니다.

jq에서는 덧셈 연산자 +와 as $var를 사용한 변수 바인딩으로 입력을 병합하고 여러 JSON 소스에서 값을 가져오는 객체를 구성할 수 있습니다.

유용한 패턴:

• obj1 + obj2 — 두 객체 병합하기(키가 충돌하면 오른쪽 값이 우선합니다)
• --argjson — 두 번째 JSON 문서를 변수로 전달하기
• $ENV — jq 내부에서 환경 변수를 직접 읽기

이 코드는 기본 구성과 환경별 재정의를 병합합니다. 셸 스크립트에서 12요소 애플리케이션 구성 관리를 할 때 흔히 사용하는 패턴입니다.

다음 JSON 객체에서 값이 0보다 작은 모든 키를 제거하여 음이 아닌 값만 포함하는 새 객체를 만들어야 합니다. 이를 올바르게 수행하는 jq 표현식은 무엇일까요?

입력: {"a": 10, "b": -3, "c": 0, "d": 5}

jq로 JSON을 재구성하는 데 필요한 핵심 기법을 살펴보았습니다.

• 객체 구성 {} — 입력에서 필드를 선택하고, 이름을 바꾸고, 값을 계산하여 새 객체 만들기
• map(expr) — 중첩된 객체 구성과 필터링을 위한 select()를 포함해 배열의 모든 요소에 변환 적용하기
• to_entries / from_entries — 객체를 {key, value} 쌍의 배열로 변환하여 키와 값에 배열 연산을 적용한 다음 다시 객체로 변환하기
• with_entries(expr) — 전체 to_entries → map → from_entries 파이프라인을 간결하게 표현하는 축약형
• +와 --argjson를 사용하여 여러 소스의 페이로드를 위해 객체 병합하기

이러한 구성 요소는 서로 결합할 수 있습니다. select로 필터링하고, 객체 구성으로 형태를 재구성하고, 계산된 필드로 보강한 다음, 읽기 쉬운 하나의 jq 표현식으로 모두 연결할 수 있습니다. 이러한 패턴을 익히면 Python이나 Node로 전용 스크립트를 작성하지 않고도 셸에서 거의 모든 JSON 페이로드를 직접 다룰 수 있습니다.