Introduction

Before you wire up your first real workflow in n8n, you need to understand one thing that trips up almost every beginner: n8n does not pass raw files or streams between nodes. It passes items. Everything — a webhook payload, a database row, an API response — gets wrapped into a structured item before it moves to the next node. Get this mental model right early, and debugging becomes dramatically easier.

What Is an Item?

An item is the fundamental unit of data in n8n. Every node receives an array of items and outputs an array of items. Each item is a JavaScript object with a required key called json, which holds your actual payload data as a JSON object. Optionally, an item can also carry binary data (for files, images, etc.), but that is covered separately.

A single item looks like this at its core:

{
  "json": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

When a node like HTTP Request fetches a list of users from an API, n8n does not hand the next node one big array. It splits that array and gives the next node one item per user. This means if your API returns 10 users, the downstream node runs 10 times — once per item. That behavior is fundamental to how n8n thinks.

How JSON Flows Between Nodes

When you reference data from a previous node, you are always reaching into the json key of an item. In expressions, n8n uses the syntax below to access the output of the previous node:

{{ $json.fieldName }}

特定の名前付きノードからデータを取得したい場合、直前のノードではなく、次のように:

{{ $node["NodeName"].json.fieldName }}

実際には、Setノードが前述の構造でアイテムを生成する場合、次のノードはユーザーのメールアドレスをこのように参照できます:

{{ $json.email }}

内部で理解すべき重要な点は、.raw HTTPレスポンス本文を文字列として扱うことは決してないということです。データが式に到達する時点で、n8nはすでにそれをjsonオブジェクトにパースしています。自分でJSON.parse()を呼ぶ必要はありません。

Execution Model

n8nはアイテムを1つずつ各ノードを通して順次処理します。ノードが複数のアイテムを受け取る場合、それらを自動的に反復します。ループは書く必要がありません。これをアイテムベースの実行モデルと呼びます。

50行をデータベースから読み取り、各行を変換し、各行ごとにメールを送信するワークフローを考えてみてください。"各行ごとにメールを送信する"と書く必要はありません。単にノードを接続します。n8nが反復処理を処理します。

これは重要な影響を持ちます。

まず、チェーン内のすべてのノードはデフォルトでアイテムごとに1回実行されます。タイムスタンプフィールドを追加するノードは50件のアイテムに対して50回実行され、50個の出力アイテムを生成します。

第二に、いくつかのノードは意図的にアイテム数を結合または分割します。Mergeノードはストリームを結合できます。SplitInBatchesノードはアイテムをグループ化できます。Codeノードは必要に応じて全体の配列を再構成できます。ワークフロー全体でアイテム数がどのように変化するかを把握して、予期しない動作を回避することが鍵です。

第三に、いずれかのノードが1つのアイテムで失敗した場合、デフォルトでは実行全体が停止します。これを変更するにはノードごとにエラーハンドリングを設定できますが、デフォルトはフェイルファーストです。

実践的な例

以下はCodeノードに入るとき、アイテム配列が実際にどのように見えるかです。組み込みデバッガを使って、任意のノードの出力パネルをクリックして自分で検査できます。

[
  {
    "json": {
      "orderId": "ORD-001",
      "amount": 120.5,
      "status": "pending"
    }
  },
  {
    "json": {
      "orderId": "ORD-002",
      "amount": 89.0,
      "status": "shipped"
    }
  }
]

これの後にCodeノードを配置し、各アイテムに processed フラグを追加したい場合、次を記述します：

for (const item of items) {
  item.json.processed = true;
}
return items;

Codeノード内で自分でアイテムをループしていることに気づくはずです。これが「n8nはループをしてくれる」という規則の唯一の例外です。Codeノードは完全な配列を渡し、完全な配列を返すことを期待します。

概要

n8n内のデータのすべては json キーを持つ item にラップされています。ノードはアイテムの配列を受け取り、デフォルトでは各ノードはアイテムごとに1回実行されます — Codeノードの外でのループはあなたが管理しません。$json.fieldName のような式は、アイテムデータへアクセスする方法です。この実行モデルを理解することが、変換、分岐、マージ、エラーハンドリングなど、すべての基礎となります。