n8n item JSON 구조 완벽 가이드: 데이터 흐름과 배열 처리 심층 분석

효율적인 n8n 워크플로우 설계와 디버깅의 핵심은 ‘n8n item JSON 구조’를 이해하는 것에서 출발합니다. 모든 데이터는 ‘아이템(Item)’ 단위로 묶여 ‘아이템 배열(Array of Items)’ 형태로 노드 간에 전달되며, 이 구조에 대한 명확한 이해는 표현식 작성, 데이터 매핑, 디버깅 등 고급 기능을 마스터하는 데 필수적입니다. 이 글은 n8n의 기본 데이터 단위인 Item의 상세 구조부터 배열 처리 방식, 전체 데이터 흐름까지 완벽히 마스터하여 더 정교한 자동화를 구축할 수 있도록 돕습니다.

n8n 데이터의 기본 단위: n8n item JSON 구조 심층 분석

n8n 워크플로우에서 처리되는 모든 정보의 최소 단위를 ‘Item’이라고 부릅니다. Item은 데이터를 담는 기본 컨테이너 역할을 합니다. 여기서 가장 중요한 점은, 노드 간에 전달되는 것은 단일 값이 아니라 항상 하나 이상의 Item을 담고 있는 배열이라는 사실입니다. 이 Item의 내부를 들여다보면 n8n의 데이터 처리 방식의 핵심을 파악할 수 있습니다.

핵심: `n8n item JSON 구조` 해부

모든 Item은 표준화된 구조를 따릅니다. 가장 기본적인 형태는 `json`과 `binary`라는 두 개의 핵심 속성을 가진 객체입니다. 아래 예시를 통해 각 속성의 역할과 중요성을 자세히 살펴보겠습니다.

[
  {
    "json": {
      "id": 123,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "tags": ["customer", "active"],
      "details": {
        "last_login": "2026-07-21T10:00:00Z"
      }
    },
    "binary": {},
    "pairedItem": {}
  }
]

1. `json` 속성: 모든 비즈니스 데이터의 중심

`json` 속성은 워크플로우 자동화에서 다루는 대부분의 데이터를 담는 핵심 영역입니다. 고객 이름, 이메일 주소, 주문 ID, 상태 값 등 텍스트, 숫자, 참/거짓(불리언), 배열, 그리고 다른 객체를 포함하는 중첩된 구조까지 모든 종류의 데이터를 이곳에 저장합니다. 이것이 바로 n8n의 가장 기본적인 `n8n 데이터 타입` 입니다.

n8n 표현식에서 `$json`이라는 변수를 사용하면, 현재 처리 중인 아이템의 `json` 객체 내부 데이터에 직접 접근할 수 있습니다. 예를 들어, 위 데이터 구조에서 `$json.name`이라는 표현식은 “John Doe”라는 문자열을 반환합니다. 이처럼 `json` 속성은 n8n 워크플로우의 심장과도 같이, 모든 데이터 처리와 가공의 기준점이 됩니다. n8n 공식 데이터 구조 문서에서 더 자세한 내용을 확인할 수 있습니다.

2. `binary` 속성: 파일 및 미디어 데이터 처리

이미지, PDF, 동영상, 압축 파일 등 JSON 형식으로 표현할 수 없는 데이터를 ‘바이너리 데이터’라고 합니다. n8n은 이러한 바이너리 데이터를 처리하기 위해 `binary`라는 별도의 속성을 제공합니다. `json` 속성이 텍스트 기반의 정형 데이터를 다룬다면, `binary` 속성은 파일 그 자체를 다루는 공간입니다.

`binary` 객체 내부에는 보통 Base64로 인코딩된 실제 파일 데이터인 `data`와 함께 `fileName`, `mimeType` (파일 종류를 나타내는 타입, 예: ‘image/png’) 같은 유용한 정보가 포함됩니다. “데이터는 `json`에, 파일은 `binary`에” 라는 원칙을 기억하면 두 속성의 역할을 명확히 구분할 수 있습니다. 이 분리된 구조 덕분에 n8n은 대용량 파일도 효율적으로 처리할 수 있습니다.

3. `pairedItem` 속성: 고급 데이터 병합을 위한 내부 정보

`pairedItem`은 여러 데이터 흐름을 `Merge` 노드 등으로 병합할 때, 어떤 아이템들이 서로 짝이었는지 그 관계를 추적하기 위해 n8n이 내부적으로 사용하는 메타데이터입니다. 예를 들어, `If` 노드에서 분기되었던 데이터가 나중에 다시 합쳐질 때, `pairedItem` 정보를 이용해 원래 어떤 아이템에서 파생되었는지 알 수 있습니다.

일반적인 워크플로우를 설계할 때는 이 속성을 직접 다룰 일이 거의 없습니다. 하지만 여러 데이터 소스를 결합하는 복잡한 시나리오에서 `Merge` 노드가 어떻게 동작하는지 그 원리를 깊이 이해하고 싶을 때 이 속성의 존재를 아는 것이 큰 도움이 됩니다.

JSON 데이터와 바이너리 데이터를 포함한 n8n 아이템 내부 구조 상세 이미지

데이터 묶음의 처리: n8n item 배열 동작 원리

n8n의 데이터 처리에서 가장 독특하고 강력한 특징 중 하나는 모든 것을 ‘배열’ 단위로 처리한다는 점입니다. 한 노드에서 다음 노드로 데이터가 넘어갈 때, 단 하나의 정보 조각이 아닌 `n8n item 배열` 이라는 데이터 묶음 전체가 전달됩니다. 예를 들어, 구글 시트에서 100개의 행을 읽어오는 노드는 100개의 Item을 가진 단 하나의 배열을 출력으로 생성합니다.

이러한 ‘배열 중심 처리’ 방식은 n8n의 `n8n 데이터 흐름` 을 매우 효율적으로 만듭니다. 사용자가 별도로 반복문(Loop)을 만들지 않아도, 대부분의 노드는 입력으로 받은 배열의 각 아이템을 하나씩 순서대로 독립적으로 실행합니다. 이를 ‘암시적 루프(Implicit Loop)’라고 부르며, n8n의 핵심 동작 원리입니다.

`n8n item 배열` 을 제어하는 핵심 노드

때로는 이 아이템 배열을 직접 제어하고 조작해야 하는 경우가 생깁니다. n8n은 이러한 상황을 위해 강력한 제어 노드들을 제공합니다.

노드 이름	주요 기능 및 사용 사례
`Split In Batches`	수천 개의 아이템이 담긴 거대한 배열을 작은 묶음(배치)으로 나누어 처리할 때 사용합니다. 예를 들어, 외부 API가 1분에 100개의 요청만 허용하는 속도 제한(Rate Limit)이 있을 경우, 1000개의 아이템을 100개씩 10개의 배치로 나누어 각 배치 처리 사이에 지연 시간을 둠으로써 오류를 방지할 수 있습니다.
`Merge`	`If` 나 `Switch` 노드에 의해 여러 경로로 분기되었던 데이터 흐름을 다시 하나의 배열로 합칠 때 사용합니다. 또한, 완전히 다른 두 데이터 소스(예: 데이터베이스와 API)에서 온 아이템 배열을 서로 결합하는 데에도 필수적입니다.
`Item Lists`	배열 자체를 직접 조작하고 싶을 때 사용하는 다재다능한 노드입니다. 여러 아이템의 특정 숫자 필드를 모두 더해 하나의 아이템으로 만들거나(Aggregate), 특정 조건(예: ‘status’가 ‘completed’인 아이템)에 맞는 아이템만 남기고 나머지는 제거하는(Filter) 등의 고급 작업을 수행할 수 있습니다. 더 자세한 활용법은 n8n 공식 문서에서 찾아볼 수 있습니다.

이 노드들을 활용하면 아무리 복잡한 데이터 배열이라도 원하는 형태로 자유롭게 가공하고 제어하며 워크플로우의 데이터 흐름을 완벽하게 관리할 수 있습니다.

대량의 아이템 배열이 노드에 의해 배치(Batch)로 나누어지는 과정을 표현한 이미지

노드 간 n8n 데이터 흐름 완벽 마스터하기

워크플로우의 진정한 힘은 데이터가 여러 노드를 거치며 변형되고, 분기하며, 다시 합쳐지는 과정, 즉 `n8n 데이터 흐름` 에서 나옵니다. 이 흐름을 이해하는 것은 자동화 로직을 설계하고 문제를 해결하는 데 매우 중요합니다.

기본적인 데이터 전달 과정

n8n의 가장 기본적인 원칙은 “이전 노드의 출력(Output)은 다음 노드의 입력(Input)이 된다”는 것입니다. 이 과정에서 `n8n item 배열` 전체가 그대로 다음 노드로 전달됩니다. 각 노드는 입력받은 아이템 배열을 처리하고, 새로운 형태의 아이템 배열을 생성하여 다음 노드로 전달합니다. 이 연쇄적인 과정이 모여 하나의 완성된 워크플로우를 구성합니다.

노드를 거치며 진화하는 데이터

데이터는 워크플로우를 따라 흐르면서 가만히 있지 않습니다. 각 노드는 `n8n item JSON 구조` 를 필요에 맞게 추가, 수정, 또는 완전히 대체하며 데이터를 동적으로 변형시킵니다.

`Set` 노드: 이 노드는 데이터 구조를 조작하는 데 가장 기본적이면서도 강력한 도구입니다. 예를 들어, 기존 `json` 데이터에 있는 `firstName`과 `lastName` 필드를 조합하여 `fullName`이라는 새로운 필드를 추가할 수 있습니다. 또는, 불필요한 데이터를 제거하여 구조를 깔끔하게 정리하는 용도로도 사용됩니다.
`HTTP Request` 노드: 이 노드는 외부 API와 통신하여 데이터를 가져옵니다. API 호출이 성공하면, 그 응답 데이터(주로 JSON 형태)가 새로운 `json` 구조를 형성하여 기존 아이템의 데이터를 덮어쓰거나 추가하게 됩니다.

데이터 흐름의 분기와 병합

복잡한 자동화 로직을 구현하기 위해서는 데이터 흐름을 조건에 따라 나누고 다시 합치는 과정이 필수적입니다.

`If` 노드: 이 노드는 특정 조건을 기준으로 아이템 배열을 두 개의 경로(‘true’ 출력과 ‘false’ 출력)로 나눕니다. 예를 들어, `$json.tags` 배열에 “customer”라는 값이 포함되어 있는지 확인하여, 포함된 아이템들은 ‘true’ 경로로, 그렇지 않은 아이템들은 ‘false’ 경로로 보냅니다.
`Merge` 노드: 분기되었던 데이터는 각자의 경로를 따라 필요한 처리를 거친 후, `Merge` 노드를 통해 다시 하나의 `n8n 데이터 흐름` 으로 합쳐질 수 있습니다. 이를 통해 워크플로우의 로직을 일관성 있게 마무리할 수 있습니다.

필수 디버깅 팁

워크플로우가 예상대로 동작하지 않을 때, 데이터 흐름을 추적하는 것은 문제 해결의 첫걸음입니다. 다음 팁들은 디버깅 시간을 획기적으로 줄여줄 것입니다.

`Set` 노드로 데이터 확인: 워크플로우 중간에 `Set` 노드를 추가하고, ‘Value’ 필드를 비워두세요. 그리고 이 노드를 실행하면, 해당 시점의 전체 아이템 배열과 각 아이템의 상세한 `json`, `binary` 구조를 명확하게 확인할 수 있습니다.
표현식 테스터 활용: 노드 설정 창에서 표현식(Expression)을 입력할 때, 편집기 화면에서 `$json`과 같은 변수를 입력하면 현재 노드가 보고 있는 아이템의 데이터 구조를 실시간으로 미리 볼 수 있습니다.
자주 발생하는 오류 이해: “ERROR: Cannot read properties of undefined” 와 같은 오류 메시지를 만났다면, 이는 대부분 데이터 경로를 잘못 지정했기 때문입니다. 예를 들어, 실제 경로는 `$json.data.name`인데 `$json.name`으로 잘못 참조했을 가능성이 높습니다. 데이터 구조를 다시 한번 확인하여 정확한 경로를 사용해야 합니다. n8n 표현식 관련 공식 문서는 문제 해결에 큰 도움이 될 수 있습니다.

조건에 따라 데이터가 분기되고 다시 하나로 병합되는 n8n 데이터 흐름 시각화

결론: 데이터 구조 이해를 통한 n8n 전문가로의 도약

지금까지 우리는 n8n 워크플로우의 가장 근본적인 요소인 데이터 모델에 대해 깊이 있게 탐색했습니다. 이 글에서 다룬 `n8n item JSON 구조` 의 핵심(`json`과 `binary` 속성), 모든 처리가 `n8n item 배열` 을 중심으로 이루어지는 방식, 그리고 노드 간의 동적인 `n8n 데이터 흐름` 원리는 n8n을 마스터하기 위한 필수 지식입니다.

n8n의 데이터 모델을 이해하는 것은 단순히 몇 가지 노드의 기능을 아는 것을 넘어섭니다. 이는 여러분이 원하는 자동화를 더 빠르고, 더 안정적이며, 더 유연하게 구축할 수 있는 근본적인 역량이 됩니다. 데이터가 어떻게 흐르고 변형되는지를 알면, 복잡한 문제에 직면했을 때 더 체계적으로 디버깅하고 창의적인 해결책을 찾을 수 있습니다.

이제 여러분은 n8n의 데이터가 어떻게 흐르는지 명확히 이해했습니다. 이 지식을 바탕으로 더욱 강력하고 정교한 자동화 워크플로우를 구축하며 여러분의 생산성을 한 단계 끌어올려 보시기 바랍니다.

자주 묻는 질문 (FAQ)

Q: n8n에서 모든 데이터는 왜 배열 형태로 전달되나요?

A: n8n은 ‘암시적 루프(Implicit Loop)’라는 강력한 기능을 제공하기 위해 모든 데이터를 아이템 배열로 처리합니다. 이를 통해 사용자가 별도의 반복문을 설정하지 않아도, 노드가 배열의 각 아이템에 대해 순차적으로 작업을 수행할 수 있어 대량의 데이터를 효율적으로 처리할 수 있습니다.

Q: `json` 속성과 `binary` 속성의 가장 큰 차이점은 무엇인가요?

A: `json` 속성은 텍스트, 숫자, 객체 등 구조화된 데이터를 담는 공간이고, `binary` 속성은 이미지, PDF, 파일 등 JSON으로 표현할 수 없는 바이너리 데이터(파일) 자체를 담는 공간입니다. “데이터는 json에, 파일은 binary에” 라는 원칙으로 명확히 구분할 수 있습니다.

Q: 워크플로우 디버깅 시 “Cannot read properties of undefined” 오류가 발생하면 어떻게 해야 하나요?

A: 이 오류는 대부분 표현식에서 데이터 경로를 잘못 지정했을 때 발생합니다. 예를 들어 `$json.user.name`으로 접근해야 할 데이터를 `$json.name`으로 잘못 참조하는 경우입니다. 워크플로우 중간에 `Set` 노드를 추가하여 해당 시점의 정확한 데이터 구조를 확인하고, 올바른 경로로 표현식을 수정해야 합니다.

n8n item JSON 구조 완벽 가이드: 데이터 흐름과 배열 처리