n8n 워크플로우의 데이터 구조: 배열과 객체로 노드를 잇는 법

n8n 워크플로우에서 노드 하나를 통과한 데이터를 콘솔에 찍어보면 항상 같은 모양이 나온다. 배열 안에 객체가 들어있고, 그 객체는 다시 json이라는 키로 한 번 더 감싸여 있다. HTTP Request 노드로 받아온 API 응답이든 데이터베이스 노드로 읽어온 테이블 행이든 예외가 없다. 이 규칙 하나를 이해하고 나면 n8n의 데이터 흐름 대부분이 설명된다.

배열, 객체, json 래핑

n8n의 데이터는 JSON 객체의 배열이다. 배열은 인덱스 0부터 시작하는 순차 구조이고, 비어 있을 수도 있고 수천 개의 원소를 담을 수도 있다. 각 원소는 키-값 쌍으로 이루어진 객체이며, 객체 안에 다시 객체가 중첩될 수 있어 복잡한 데이터 구조도 표현할 수 있다.

여기에 n8n 고유의 규칙이 하나 더 붙는다. 배열의 각 원소는 실제 데이터를 json이라는 키로 한 번 더 감싼 형태로 저장된다. 이 래핑은 노드 간 호환성을 보장하기 위한 장치로, 버전 0.166.0 이상에서는 json 키가 빠져 있어도 n8n이 자동으로 보정해서 추가한다.

아이템: 노드가 실제로 처리하는 단위

배열의 각 원소, 즉 { json: {...} } 형태의 객체 하나하나를 n8n은 아이템이라고 부른다. 워크플로우의 모든 노드는 이 아이템을 기본 처리 단위로 삼는다. 노드는 입력으로 들어온 아이템 배열을 받아 각 아이템에 대해 독립적으로 작업을 수행하고, 그 결과를 다시 표준 형식의 배열로 출력한다. 이 순환 구조 덕분에 노드 하나가 처리하는 아이템 수와 상관없이 다음 노드로 이어지는 인터페이스는 항상 동일하게 유지된다.

⤢✕

Code 노드로 아이템 직접 만들기

Code 노드에서 return 문으로 배열을 반환하면 그 자체가 새 데이터셋이 된다. 가장 단순한 형태는 이렇다.

return [
  { json: { name: "Leonardo", color: "blue" } },
  { json: { name: "Michelangelo", color: "orange" } },
];

객체 안에 객체를 중첩하는 것도 그대로 동작한다.

return [
  {
    json: {
      name: "Contact1",
      email: {
        personal: "john@personal.com",
        work: "john@company.com",
      },
    },
  },
];

이전 노드가 만든 데이터를 참조하려면 $input.all()로 전체 아이템 배열을, $input.first()로 첫 번째 아이템만 가져올 수 있다. 여기에 표현식(Expressions)을 조합하면 특정 노드의 출력을 직접 지목해서 읽어오는 것도 가능하다.

노드로 바꿀지, 코드로 바꿀지

배열 구조를 바꾸는 작업 자체는 시각적 노드로도 충분히 처리된다. Split Out 노드는 하나의 아이템 안에 있는 배열 필드를 여러 개의 독립된 아이템으로 풀어내고, Aggregate 노드는 반대로 여러 아이템을 하나로 모아 그룹화한다. 코드를 한 줄도 쓰지 않고 드래그 앤 드롭만으로 끝나는 작업이다.

노드로 표현하기 어려운 로직, 예를 들어 조건에 따라 다르게 변환하거나 특정 필드만 골라 처리하거나 외부 API 응답 구조를 표준 형태로 맞추는 작업은 Code 노드로 넘어간다.

// 단일 아이템을 다중 아이템으로 분리
return $input.first().json.data.map((item) => {
  return { json: item };
});

// 다중 아이템을 단일 아이템으로 통합
return [
  {
    json: {
      data_object: $input.all().map((item) => item.json),
    },
  },
];

실무에서 마주치는 패턴

이 구조가 실제로 힘을 발휘하는 지점은 서로 다른 스키마를 가진 시스템을 연결할 때다. PokéAPI 같은 외부 REST API에서 받아온 응답은 HTTP Request 노드와 Code 노드를 조합해 n8n 표준 구조로 바꾼 뒤에야 다음 노드에서 다룰 수 있다. 관계형 데이터베이스의 쿼리 결과나 NoSQL의 문서 기반 데이터도 마찬가지로 배열 객체 형태로 정규화해야 워크플로우 안에서 일관되게 처리된다. 대용량 데이터셋을 배치나 스트리밍으로 다룰 때도 이 표준 구조가 전제가 된다.

BI 도구로 데이터를 보내는 보고서·대시보드 자동화도 결국 같은 원리다. 여러 소스에서 온 데이터를 하나의 표준 구조로 맞춘 다음, 필요한 집계 로직을 Code 노드나 조합 노드로 얹는 식이다. 이 표준화 규칙을 몸에 익혀두면 노드 하나하나의 동작을 외우지 않아도 새로운 노드를 마주쳤을 때 데이터가 어떻게 들어오고 나갈지 예측할 수 있게 된다.