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:

{
  "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:

{
  "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:

{
  "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:

{
  "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