<!-- BusyBot node reference — https://busybot.net/tools/compare-datasets/ -->

> Node: Compare Datasets (`compare_datasets`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Compare Datasets

> Compare two datasets and categorize matches

## Overview

The Compare Datasets tool takes two inputs (Input A and Input B) and compares them using user-specified match fields. Items are categorized into 4 output ports: (0) In A Only — items in Input A with no match in B, (1) Same — matching items that are identical, (2) Different — matching items with different values, (3) In B Only — items in Input B with no match in A. Supports fuzzy comparison (type coercion), multiple resolve strategies for different items, and skip fields.

**Category:** Core Nodes  
**Tool Name:** `compare_datasets`  
**Version:** 1

**Appearance:** Icon: `lucide-GitCompareArrows` | Color: `#ff6d5a`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input A`, `Input B` |
| Output | `In A Only`, `Same`, `Different`, `In B Only`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Merge By Fields | `fixedCollection` | No | `{}` | The field pairs used to decide whether an Input A item and an Input B item describe the same record. At least one pair is required. |
| — Input A Field | `string` | No | — | Field name from Input A to match on. |
| — Input B Field | `string` | No | — | Field name from Input B to match on. |
| When There Are Differences | `options` | No | `preferInput2` | How to handle items that match but have different field values. |
| | | | | Options: `preferInput1` (use the Input A version), `preferInput2` (use the Input B version), `mix` (blend both versions), `includeBoth` (keep both under `input1` and `input2`) |
| Prefer | `options` | No | `input2` | When mixing, which input to prefer for conflicting fields. _(shown when When There Are Differences is `mix`)_ |
| | | | | Options: `input1`, `input2` |
| For Everything Except | `string` | No | — | Comma-separated fields to exclude from the mix preference. _(shown when When There Are Differences is `mix`)_ |
| Options | `collection` | No | `{}` | Additional comparison options. |
| — Fuzzy Compare | `boolean` | No | `false` | Tolerate type differences when comparing (e.g., 3 == "3", true == "TRUE"). |
| — Disable Dot Notation | `boolean` | No | `false` | Disable dot notation, so a field name containing a dot is read as a literal key instead of a path into nested data. |
| — Fields to Skip Comparing | `string` | No | — | Comma-separated fields to ignore when checking if items are the same or different. |
| — Multiple Matches | `options` | No | `first` | How to handle an Input A item that matches more than one Input B item. |
| | | | | Options: `first` (pair each item once, with its first match), `all` (emit a result for every match) |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

Every input item leaves through exactly one of the four category outputs — nothing is dropped and no extra properties are added to the JSON. Binary data travels with the item.

| Output | What lands on it |
|--------|------------------|
| `In A Only` | The Input A item, JSON and binary unchanged — no Input B item matched on the merge-by fields. |
| `Same` | The Input A item, JSON and binary unchanged — a match was found and every other field is equal. |
| `Different` | One combined item per matched pair, built according to **When There Are Differences**. Binary from both items is merged onto it. |
| `In B Only` | The Input B item, JSON and binary unchanged — no Input A item matched it. |

The shape of a `Different` item depends on the resolve strategy:

- `preferInput1` — a copy of the Input A item.
- `preferInput2` — a copy of the Input B item.
- `mix` — the Input A item with the Input B fields merged in. **Prefer** decides which side wins a conflicting field, and any field named in **For Everything Except** is left out of the merge.
- `includeBoth` — both versions side by side:

```json
{
  "input1": { "id": 42, "status": "active" },
  "input2": { "id": 42, "status": "churned" }
}
```

Two items count as the **same** only when every field they carry is equal. Fields named in **Fields to Skip Comparing** and the merge-by fields themselves are excluded from that check, so volatile columns like `updatedAt` do not push a pair into `Different`.

## Usage Examples

- Compare two CSV imports to find new, changed, and deleted records
- Diff database snapshots
- Find contacts that exist in one CRM but not the other

## Example Configuration

Basic comparison — match user records by email and keep the Input B version when they differ:

```json
{
  "type": "compare_datasets",
  "parameters": {
    "mergeByFields": {
      "values": [
        {
          "field1": "email",
          "field2": "email"
        }
      ]
    },
    "resolve": "preferInput2",
    "maxConcurrency": 5
  }
}
```

Advanced comparison — match on two field pairs, mix the versions, and ignore volatile fields:

```json
{
  "type": "compare_datasets",
  "parameters": {
    "mergeByFields": {
      "values": [
        {
          "field1": "id",
          "field2": "user_id"
        },
        {
          "field1": "department",
          "field2": "dept"
        }
      ]
    },
    "resolve": "mix",
    "preferWhenMix": "input1",
    "exceptWhenMix": "lastLogin,status",
    "options": {
      "fuzzyCompare": true,
      "skipFields": "timestamp,version",
      "multipleMatches": "all"
    },
    "maxConcurrency": 10
  }
}
```

Include both versions so a downstream node can decide for itself:

```json
{
  "type": "compare_datasets",
  "parameters": {
    "mergeByFields": {
      "values": [
        {
          "field1": "productId",
          "field2": "id"
        }
      ]
    },
    "resolve": "includeBoth",
    "options": {
      "fuzzyCompare": false,
      "disableDotNotation": true,
      "skipFields": "lastModified"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Compares two input datasets, categorizing items into 4 outputs: only-in-A, same, different, only-in-B.

### Common Patterns

**User Data Reconciliation** — when comparing user datasets from different systems:

- Use email or user ID for matching
- Enable fuzzy comparison for type tolerance
- Skip timestamp fields that don't affect data integrity

**Product Catalog Sync** — when synchronizing product catalogs:

- Match on product ID or SKU
- Use "mix" resolution with preference for authoritative source
- Exclude volatile fields like stock count from difference detection

**Data Quality Auditing** — when auditing data consistency:

- Use "includeBoth" to see all versions
- Enable strict comparison (no fuzzy matching)
- Process all multiple matches to catch duplicates