데이터 다루기 — JSON 구조와 표현식

🎯 학습 목표

이 강을 마치면 다음을 할 수 있습니다.

• n8n의 items 배열 데이터 모델을 정확히 이해합니다.
• {{ $json }}, {{ $node }}, {{ $now }} 같은 내장 변수를 활용해 표현식을 작성할 수 있습니다.
• 이전 노드의 데이터를 참조하는 방법을 익힙니다.
• 날짜·문자열 변환 표현식을 직접 작성할 수 있습니다.

💡 n8n 데이터 모델 — items 배열의 진실

이 섹션에서는 n8n 내부에서 데이터가 어떻게 표현되는지 깊이 살펴보겠습니다.

n8n에서 노드 간에 오가는 모든 데이터는 items 배열이라는 구조를 따릅니다. 이 개념은 n8n을 능숙하게 다루기 위해 반드시 이해해야 합니다. items 배열이란 JSON 객체들의 배열로, 각 JSON 객체를 하나의 아이템이라고 부릅니다.

[
  { "id": 1, "name": "홍길동", "email": "hong@example.com" },
  { "id": 2, "name": "김철수", "email": "kim@example.com" },
  { "id": 3, "name": "이영희", "email": "lee@example.com" }
]

위 예시에서 배열 안에 3개의 아이템이 있습니다. n8n은 이 배열을 받는 노드를 각 아이템에 대해 자동으로 3번 실행합니다. 개발자라면 for-each 루프가 자동으로 적용된다고 이해하면 됩니다. 비개발자라면 '아이템 수만큼 처리가 반복된다'고 기억하면 됩니다. 이 자동 반복이 n8n의 강력한 특성 중 하나입니다.

각 아이템은 JSON 필드를 담고 있으며, 이 필드에 접근하는 것이 표현식의 핵심입니다. 아이템의 name 필드에 접근하려면 {{ $json.name }}이라고 작성합니다. $json은 현재 처리 중인 아이템 전체를 가리키는 n8n 내장 변수입니다.

📐 표현식 문법 완전 정리

이 섹션에서는 n8n 표현식의 문법 규칙과 주요 내장 변수를 살펴보겠습니다.

n8n 표현식은 이중 중괄호 {{ }} 안에 작성하는 동적 값입니다. 노드 설정의 입력 필드 어디에서든 사용할 수 있으며, 고정 텍스트 안에 표현식을 섞을 수도 있습니다. 예를 들어 안녕하세요, {{ $json.name }}님!처럼 작성하면 아이템의 name 값이 자동으로 삽입됩니다.

가장 자주 사용하는 내장 변수를 정리했습니다.

변수	의미	예시
$json	현재 아이템의 JSON 데이터	{{ $json.name }}
$json.field.subfield	중첩 필드 접근	{{ $json.address.city }}
$node['노드명'].json	특정 노드의 출력 참조	{{ $node['Set'].json.name }}
$now	현재 시각 (Luxon 객체)	{{ $now.toISO() }}
$today	오늘 날짜 00:00:00	{{ $today.toFormat('yyyy-MM-dd') }}
$items()	현재 노드의 모든 아이템	{{ $items().length }}
$itemIndex	현재 아이템의 인덱스(0부터)	{{ $itemIndex }}
$runIndex	현재 실행 인덱스	{{ $runIndex }}

표현식 입력 필드 오른쪽의 번개 아이콘(⚡)을 클릭하면 표현식 에디터가 열립니다. 이 에디터는 자동완성, 변수 목록, 실시간 결과 미리보기를 제공합니다. 표현식을 처음 작성할 때는 반드시 표현식 에디터를 활용해 결과를 확인하면서 작성하십시오.

🔗 이전 노드 데이터 참조하기

이 섹션에서는 워크플로우 앞 단계의 노드에서 데이터를 가져오는 방법을 살펴보겠습니다.

직전 노드의 데이터는 $json으로 접근하지만, 두 단계 이상 앞의 노드 데이터를 참조하려면 $node['노드명'].json을 사용합니다. 예를 들어 'Fetch User' 노드의 출력에서 userId 필드를 가져오려면 {{ $node['Fetch User'].json.userId }}라고 작성합니다. 노드 이름이 바뀌면 참조도 함께 수정해야 하므로, 노드 이름은 처음부터 의미 있게 짓는 것이 중요합니다.

여러 아이템 중 특정 인덱스의 아이템을 가져올 때는 $node['노드명'].json[0]처럼 인덱스를 지정합니다. 배열의 특정 요소를 가져오거나 집계 연산이 필요할 때 유용합니다. 이보다 복잡한 데이터 조작이 필요하다면 Code 노드에서 JavaScript로 처리하는 것이 더 효율적입니다.

⏰ 날짜·문자열 변환 표현식

이 섹션에서는 실무에서 자주 필요한 날짜와 문자열 변환 표현식을 살펴보겠습니다.

n8n은 날짜 처리에 Luxon 라이브러리를 내장합니다. $now와 $today는 Luxon DateTime 객체이므로 Luxon의 풍부한 메서드를 표현식에서 바로 사용할 수 있습니다.

표현식	출력 예시	설명
{{ $now.toISO() }}	2026-06-18T12:34:56.789Z	ISO 8601 형식
{{ $now.toFormat('yyyy-MM-dd') }}	2026-06-18	날짜만
{{ $now.toFormat('HH:mm') }}	12:34	시:분
{{ $now.plus({days: 7}).toFormat('yyyy-MM-dd') }}	2026-06-25	7일 후
{{ $now.setZone('Asia/Seoul').toFormat('yyyy-MM-dd HH:mm') }}	2026-06-18 21:34	한국 시간

문자열 변환도 JavaScript 내장 메서드를 표현식에서 직접 사용할 수 있습니다. {{ $json.name.toUpperCase() }}는 name을 대문자로, {{ $json.email.split('@')[0] }}은 이메일에서 @ 앞부분(아이디)만 추출합니다. {{ $json.price.toFixed(2) }}는 숫자를 소수점 2자리로 고정합니다. 이처럼 표현식 안에서 JavaScript 문자열·숫자 메서드를 자유롭게 사용할 수 있습니다.

⚠️ 표현식 작성 시 자주 하는 실수

이 섹션에서는 표현식 작성 시 흔히 마주치는 오류와 해결 방법을 살펴보겠습니다.

첫 번째 실수는 없는 필드 접근입니다. $json.name에서 name 필드가 없으면 undefined가 반환되고, 이를 문자열로 사용하면 'undefined'라는 텍스트가 나타납니다. 필드가 있을 때만 처리하려면 {{ $json.name ?? '이름 없음' }}처럼 null 병합 연산자(??)를 사용합니다.

두 번째 실수는 중첩 필드의 null 접근입니다. $json.address.city에서 address 자체가 null이면 에러가 발생합니다. {{ $json.address?.city }}처럼 옵셔널 체이닝(?.)을 사용하면 address가 null이어도 에러 없이 undefined를 반환합니다.

세 번째 실수는 숫자와 문자열 혼동입니다. API 응답에서 숫자가 문자열로 오는 경우가 있습니다. '100'과 100은 다릅니다. 계산에 사용하려면 {{ Number($json.price) * 1.1 }}처럼 명시적으로 숫자로 변환하십시오.

📝 핵심 요약

개념	핵심 내용
items 배열	n8n 데이터의 기본 단위. 각 노드는 배열을 받아 처리 후 내보냄
$json	현재 아이템의 데이터. $json.필드명으로 접근
$node['이름'].json	특정 노드의 출력 참조. 노드 이름 의미있게 짓기 중요
$now / $today	Luxon DateTime. toISO(), toFormat() 등 메서드 사용
옵셔널 체이닝	$json.a?.b — null/undefined 안전 접근

다음 강에서는 Set 노드와 Merge 노드를 집중적으로 살펴봅니다. 데이터를 원하는 형태로 가공하고 여러 경로의 데이터를 하나로 합치는 법을 익히면, 복잡한 데이터 파이프라인도 자유롭게 설계할 수 있습니다.