확인일: 2026년 9월 14일 · Windows x64 · jq 1.8.2
센서 로그에서 필요한 값만 추리거나 HTTP API 응답을 CSV로 바꿀 때 jq를 사용할 수 있습니다. 이 글은 가상의 센서 데이터로 0, null, 누락된 필드, 문자열로 들어온 숫자를 구별하는 실습을 제공합니다.
1. 다운로드와 ZIP 구성
첨부한 jq-1.8.2-windows-amd64-with-notices.zip은 공식 Windows x64 실행파일을 수정 없이 담고 저작권·라이선스 고지문과 출처를 함께 넣어 만든 ZIP입니다. jq 프로젝트가 직접 제공한 ZIP 파일은 아닙니다. 공식 배포 형태는 단일 실행파일이며, 다른 운영체제나 Windows ARM64용 파일은 jq 공식 다운로드에서 선택할 수 있습니다.
jq-json-korean-guide.zip에는 한국어 설명서, sensors.json, 필터 4개, 실행 명령과 예상 결과가 들어 있습니다. 설명서 ZIP 자체에는 실행파일이 없습니다. 두 ZIP을 내려받아 압축을 풀고, 설명서 폴더에 jq-windows-amd64.exe를 복사하면 아래 명령을 그대로 사용할 수 있습니다.
포함 실행파일의 SHA-256은 a6fc67fedaf9128a3309a1e2ebb8b986aeccf70122ee46d2cb4849e423f0c627입니다. 공식 체크섬 목록과 비교했습니다. ZIP 안의 COPYING.txt와 vendor-oniguruma-COPYING.txt를 함께 보관하십시오.
2. PowerShell에서 실행 확인
압축을 푼 실습 폴더에서 PowerShell을 열어 한 줄씩 실행합니다. 관리자 권한이나 별도 설치는 필요하지 않습니다.
.\jq-windows-amd64.exe --version
Get-FileHash .\jq-windows-amd64.exe -Algorithm SHA256
.\jq-windows-amd64.exe . .\sensors.json첫 명령은 jq-1.8.2, 마지막 명령은 센서 5개의 JSON 배열을 표시합니다. 실행파일을 찾지 못하면 현재 폴더와 파일명을 확인하십시오. 이 ZIP은 Windows x64용입니다.
3. 0·null·누락을 구별하는 JSON 실습
예제에는 demo-01의 21.5도, demo-02의 0도, demo-03의 null, demo-04의 필드 누락, demo-05의 문자열 "23.0"이 있습니다. 모두 실제 장비와 무관한 가상 데이터입니다. summary.jq는 값뿐 아니라 키 존재 여부와 자료형도 출력합니다.
map({
device_id,
has_temperature: has("temperature_c"),
value: .temperature_c,
value_type: (.temperature_c | type)
}).\jq-windows-amd64.exe -f .\summary.jq .\sensors.json
.\jq-windows-amd64.exe -f .\valid-temperatures.jq .\sensors.json-f로 파일에 저장한 필터를 읽으면 명령줄 안의 따옴표 처리에 덜 의존합니다. 두 번째 필터는 map(select(.temperature_c | type == "number"))이며 demo-01과 demo-02만 남깁니다. 0은 유효한 숫자로 유지합니다. null과 누락은 첫 번째 출력의 has_temperature로 구별하고, 문자열 숫자는 자동 변환하지 않습니다. 필터 옵션의 정의는 jq 공식 매뉴얼에서 확인할 수 있습니다.
4. CSV 저장과 종료 코드 확인
.\jq-windows-amd64.exe -r -f .\to-csv.jq .\sensors.json
.\jq-windows-amd64.exe -r -f .\to-csv.jq .\sensors.json | Set-Content -Encoding utf8 .\temperatures.csv
.\jq-windows-amd64.exe -e -f .\all-numeric.jq .\sensors.json
$LASTEXITCODECSV는 헤더와 유효한 숫자 행 2개를 출력합니다. 입력 sensors.json과 출력 temperatures.csv를 다른 파일로 유지합니다. CSV 변환은 이 실습의 고정된 가상 장비 ID를 대상으로 합니다. 외부 문자열을 스프레드시트에 넣을 때는 수식으로 해석될 수 있는 값도 별도로 처리해야 합니다.
all-numeric.jq는 배열의 모든 온도가 숫자인지 하나의 불리언으로 판정합니다. 이 데이터에서는 false와 종료 코드 1이 예상 결과입니다. -e는 마지막 출력이 false/null이면 1, 그 외 값이면 0, 유효한 출력이 없으면 4를 사용합니다. 구문 오류 등 다른 실패 코드도 있으므로 자동 처리에서는 0만 성공으로 취급하십시오. 공식 실행 옵션 설명
5. 실무 적용 범위와 문제 해결
위 필터는 객체로 구성된 JSON 배열을 전제로 합니다. 한 줄에 JSON 객체 하나씩 기록하는 JSON Lines 파일은 입력 구조가 다릅니다. 이 예제에 바로 넣지 말고 구조에 맞는 필터를 작성해야 합니다. 빈 배열에 대한 all 판정은 true이므로 데이터가 한 건 이상이어야 하는 업무에서는 길이 조건도 추가해야 합니다.
jq .가 실행됐다는 사실만으로 장비 데이터의 계약이 검증되지는 않습니다. 단위, 범위, 필수 필드, 펌웨어별 버전과 누락 정책은 별도로 정해야 합니다. 큰 정수 식별자는 산술 처리 과정의 정밀도 문제를 피하도록 문자열로 전달하는 방안도 검토하십시오. 원본 로그를 보존한 상태에서 결과를 다른 파일에 저장하는 방식이 점검에 유리합니다.
파일 인코딩 오류가 나면 예제 파일이 UTF-8인지, 따옴표가 일반 큰따옴표인지 확인합니다. Cannot index 오류는 입력 형태와 필터가 맞지 않을 때 생길 수 있습니다. null을 0으로 일괄 치환하면 실제 0도와 측정 실패를 구별할 수 없으므로 이 실습은 치환하지 않습니다.
6. 검증 환경과 공식 출처
Windows에서 첨부 실행파일로 버전, 요약, 숫자 선택, CSV 변환과 false·null·무출력의 종료 코드를 확인했습니다. 실제 센서 연결이나 운영 서버 변경 없이 가상 파일만 사용했습니다.