CSV Join Guard

Check two CSV files before merging them. If a key appears twice on the left and three times on the right, an equality join creates six rows for that key. This Actor counts those combinations without building a potentially huge joined table.

Useful for data engineers, scraper users and automation builders preparing inventory, catalog or other tabular exports. It diagnoses join cardinality; it does not join, clean, modify or certify your data.

Try the free sample

Run {"demo":true} or use the prefilled form. The optional unchecked trimKeys:false switch submitted by the form is also accepted; other custom fields are rejected. The fixed synthetic sample produces 5 inner-join rows, 7 left-join rows, 6 right-join rows and 8 full-join rows. Product A has a many-to-many match; an empty SKU and unmatched products are reported separately. The fixed sample cannot process custom data and triggers no priced event.

Your own files

Disable Run fixed demonstration and paste two comma-separated UTF-8 CSV files with headers. Set leftKeys and optionally rightKeys; they default to ["id"] and the left names respectively. Up to four key columns are matched by position, using exact case-sensitive text equality. Leading zeros are preserved.

{
  "demo": false,
  "leftCsv": "order_id,sku\nO-1,A\nO-2,A\n",
  "rightCsv": "code,name\nA,Red\nA,Blue\n",
  "leftKeys": ["sku"],
  "rightKeys": ["code"],
  "expectedRelationship": "many_to_one"
}

This example predicts four inner-join rows and flags a violation of the requested many-to-one relationship. An optional expectation can be one_to_one, one_to_many, many_to_one or many_to_many. Expectations concern matched keys only; check unmatched and empty-key counts separately.

An empty component is treated as SQL NULL and never matches, including another empty component. Literal NULL, null and N/A are ordinary text. trimKeys:true removes outer whitespace before matching; false is the default. Numeric coercion, fuzzy matching, case folding, locale comparison and Unicode normalization are not performed. These semantics can differ from pandas, spreadsheet, database or other join settings; compare the rules before relying on the estimates.

Outputs

The Output tab opens a readable HTML report. Storage → Key-value store contains OUTPUT (full JSON), REPORT-CSV (one row per non-empty key group), and REPORT-HTML. Download JSON/CSV there if your browser blocks an embedded view. The default dataset has a summary row so downstream automation can read counts easily. Full key-level evidence is in OUTPUT, not the summary dataset.

The report provides inner, left, right and full equality-join row estimates, unmatched row counts, empty-key counts, duplicate-key group counts, many-to-many groups and expectation violations. Each key group includes side counts, predicted inner output rows and up to five source record examples per side. Up to twenty empty-key record references are included per side. Counts are complete within accepted inputs; reference examples are truncated. Record numbers count non-blank data records after the header, not physical lines.

CSV key values are JSON-encoded arrays, preserving component boundaries and making formula-like key values start with a literal bracket. Other exported cells are protected against spreadsheet formulas. HTML escapes source text and contains no scripts or external resources. No other input columns are returned.

Limits

• 1–5,000 non-blank data records and 2 MB UTF-8 per input.
• Comma-separated CSV only, including quoted fields and multiline records. No Excel, PDF, URLs or file download.
• 1–200 distinct, non-empty headers, at most 256 characters each. Selected key names must exist.
• Each field at most 16,384 characters; each key component at most 256 characters.
• Missing or extra CSV cells, malformed CSV, excessive limits or invalid configuration fail the run.
• Each export at most 8 MB; dense reports exceeding the limit fail before charging. Split your inputs when needed.
• No join table is materialized, even if predicted output is millions of rows.

Pricing and privacy

$0.25 per completed check, platform usage included, with no separate startup or dataset-item fee. The Pricing tab is authoritative. One check-completed event covers both files within the limits, including no-match results or a report containing relationship violations. Structural failures and the fixed demo do not trigger that event. Set the run maximum cost to at least $0.25 for your own data.

Reports and summary are saved before charging. A retry within the same run uses a stable billing key; resurrecting can add another summary row but does not charge another completed-check event for the same run. A new run is a new purchase, even with unchanged input. There is no subscription or managed baseline.

Data stays in the caller's Apify run storage under its access and retention settings. The Actor does not automatically delete it. No data is sent to AI providers, websites or other external services. Only supply files you have permission to process. Avoid sensitive personal data when a small set of non-sensitive identifiers will do. No source rows or keys are logged by the Actor.

Run when a new export arrives, using a saved task or Apify API. The surrounding workflow supplies both files each time. Review the report before making downstream changes; inferred equality does not prove real-world identity or completeness.

For support, open an Actor issue with the run ID and a small synthetic or anonymized example. Never post private source data publicly.