Dataset Join Preflight

Measure a proposed equijoin before creating it. The Actor reports duplicate keys, orphan rows, key-quality problems, cardinality, and exact inner- and left-join row counts without materializing joined records.

When should an agent select this tool?

Use it before a proposed exact-key join when duplicate keys could multiply rows or unmatched records need inspection. It returns projected row counts and key-quality findings; it does not execute the join. If your agent already has a trusted local SQL or counting workflow, that remains a capable alternative.

Use from an AI agent through MCP

Add this URL to a client that supports remote HTTP MCP servers, then authorize with your own Apify account:

https://mcp.apify.com/?tools=l3digital/dataset-join-preflight

This selects the Actor directly instead of relying on search ranking. Follow the Apify MCP setup guide for your client. Ask your agent to call l3digital/dataset-join-preflight with the example input below. If the MCP response returns a running job, follow its nextStep to retrieve the completed dataset; an accepted run is not yet a report. Calls use the pricing described below.

Demo: inspect a many-to-many join

Provide two arrays of flat JSON records and the key field on each side:

{
  "leftRecords": [
    {
      "id": 1
    },
    {
      "id": 1
    },
    {
      "id": "1"
    },
    {
      "id": 2
    },
    {
      "id": null
    },
    {}
  ],
  "rightRecords": [
    {
      "key": 1
    },
    {
      "key": 1
    },
    {
      "key": 1
    },
    {
      "key": "1"
    },
    {
      "key": 3
    },
    {
      "key": true
    }
  ],
  "leftKey": "id",
  "rightKey": "key"
}

Observed output excerpt from an internal run on 2026-09-06:

{
  "cardinality": "many-to-many",
  "innerJoinRows": 7,
  "leftJoinRows": 10,
  "duplicates": {
    "leftKeys": 1,
    "leftRows": 1,
    "rightKeys": 1,
    "rightRows": 2
  }
}

Two left integer 1 rows match three right integer 1 rows, producing six pairs. The string "1" matches separately, producing a seventh. Three unmatched left rows bring the left join to ten rows. The next step is to inspect the duplicate-key finding and choose whether that expansion is intended before running a separate join. This report does not decide which records should be removed.

Input limits

The two arrays may contain at most 10,000 combined records. Their canonical serialized UTF-8 JSON input may be at most 2,000,000 bytes. Each record must be flat: values may be JSON strings, numbers, booleans, or null, with no nested arrays or objects. Record and configured key-field names may contain at most 256 characters. String join keys may contain at most 1,024 characters.

Join keys match only when both their type and value match. Strings and integers are valid, so integer 1 and string "1" are different keys. Missing, null, boolean, and other numeric key values are reported separately and never match.

Set includeKeyExamples to true to return up to five typed duplicate or orphan keys, bounded to 8,192 serialized bytes in total. It defaults to false so the report does not expose source values.

Output

The Actor writes exactly one compact report to the default dataset. It includes:

• a 1.0 schema version and deterministic SHA-256 of the validated input;
• row and key-state coverage for each side;
• one-to-one, one-to-many, many-to-one, many-to-many, or no-match cardinality;
• exact inner-join and left-join row counts;
• duplicate-key, duplicate-row, orphan-key, and orphan-row counts;
• deterministic warnings and, only when requested, at most five typed key examples.

The Actor does not return a joined dataset, repair keys, normalize values, or perform fuzzy matching.

Empty arrays are valid and produce a completed no-match report with zero join rows. A valid input with no overlapping keys likewise produces a completed negative result. Both are useful completed reports and incur the same single report-produced charge as a report containing matches.

Limits and runtime

Invalid input fails before join analysis and produces no partial report. Analysis uses frequency tables rather than materialized join rows. Processing and dataset output have a 60-second application timeout. The Actor is configured for 256 MiB by default, allows at most 512 MiB, and does not use Standby mode.

Pricing experiment

The price is $0.05 per completed report, charged once through the report-produced event after the report is stored. Empty and no-match reports qualify; invalid input and failed work do not. The Actor checks the spending limit before analysis. There are no separate start or dataset-item charges. The Store pricing tab is authoritative.

Privacy and permissions

Source records remain within the Apify run and are not copied to the output. Optional key examples can disclose selected join-key values, so leave them disabled for sensitive datasets. The Actor makes no external network requests beyond Apify SDK storage operations and is intended to run with Apify Limited permissions.