CSV Lookup Join
Join CSV by key.
Keep every picking-list row.
Add details from one CSV table to another. Keep every row in your list, even when an ID repeats. New to this? Try the example below.
Free · no signup · files processed in your browser · limited aggregate usage counts
1. Choose your CSV files
- Main CSV: your list to keep.
- Lookup CSV: the list with details to add, such as product names.
UTF-8, comma-separated files with unique, nonblank headers. Up to 2 MiB, 10,000 rows, 100 columns and 200,000 cells per file.
2. Choose what to match and add
A key is the value used to find a match.
- Choose a key column in each file. For example, match Item to SKU.
- Under Lookup fields to append, tick the details to add.
- Choose Join CSV files.
“Append” means add columns to your list.
Usually one pair is enough. If an item has a different shelf at each location, add a second pair for location. You can use up to three pairs; every value in the chosen combination must match. Select each column only once per file.
Keys match exact, case-sensitive text: 001 ≠ 1 and ABC ≠ abc. Spaces are preserved, never trimmed. An empty or whitespace-only key value counts as missing. A main row with any missing key value stays in the result as missing_key. A missing lookup key value or duplicate full lookup combination blocks the join; fix the lookup file first.
3. Review and download
matched means details were found. unmatched means no exact match was found. missing_key means a main row lacked a key value. The unmatched download includes both kinds of rows needing review.
CSV exports prefix formula-like cells with an apostrophe for safer spreadsheet review. This changes those values; CSV is not lossless and spreadsheet software may still infer types such as numbers. Exact-text JSON preserves strings, including leading zeros and formula text, and includes an unusedLookup table for unused lookup rows. Review before importing or sharing.
Review unused lookup rows
Example: add product names and bins
This synthetic picking list has four lines. Item 001 appears twice; both lines need the same product details. Map Item → SKU and select Name and Bin.
The Main CSV is the picking list you want to keep. The Lookup CSV is a product reference with one row per SKU. These are two related tables, not Before and After versions of one table.
Practice files only; no real orders or products. Upload them directly without opening and saving them in a spreadsheet, which could change 001 into 1.
- Download both files. Choose synthetic-main.csv under Main CSV and synthetic-lookup.csv under Lookup CSV.
- Set Main key column to Item and Lookup key column to SKU. The headings can differ; the values are what match.
- Select Name and Bin as the lookup fields; leave SKU unchecked. Choose Join CSV files.
- Check the four-row result below. Download Joined CSV for the enriched list or Unmatched CSV to review L4. Use Exact-text JSON when you need the original strings preserved.
Main CSV
Line,Item,Qty L1,001,2 L2,001,1 L3,002,3 L4,003,1
Lookup CSV
SKU,Name,Bin 001,Mug,A1 002,Towel,B2 004,Plate,C1
Result: 4 rows, 3 matched, 1 unmatched, 1 unused lookup key. L1 and L2 get Mug / A1; L3 gets Towel / B2. L4 stays in place with blank lookup fields and unmatched status. SKU 004 is unused.
Example: join by SKU and location
A synthetic picking list has three lines: L1 for Item 001 at Site North, L2 for 001 at South, and L3 for 001 at North again. The product has a different bin at each location:
| SKU | Location | Bin |
|---|---|---|
| 001 | North | A1 |
| 001 | South | B2 |
Map Item → SKU, choose Add key pair, then map Site → Location. Select Bin to append. The three lines receive A1, B2 and A1 in that order: 3 matched, 0 unmatched and 0 unused combinations.
SKU alone is duplicated in the lookup, so a one-column join is blocked. SKU plus Location identifies each row without deleting legitimate records or combining cells manually. A second 001, North lookup row still blocks the join. A blank Site stays missing_key, even if SKU matches. The same pattern works for Order ID plus Line number; up to three column pairs are supported.
Which lookup rows were not used?
In the same synthetic example, Unmatched CSV contains main row L4 (Item 003), which found no reference. Unused lookup CSV contains lookup SKU 004 (Plate, C1), which no main row requested. These are opposite sides of the join, not interchangeable reports.
| lookup_record | SKU | Name | Bin |
|---|---|---|---|
| 4 | 004 | Plate | C1 |
After joining, open Review unused lookup rows or download Unused lookup CSV. It keeps lookup source order, paired key columns and selected fields only. The record column counts the header as record 1; quoted multiline records count once. Exact-text JSON includes the same rows under unusedLookup, without CSV formula-prefix changes. With composite keys, a lookup combination is unused only if no complete main combination matched it.
Unused means not requested by this main file. It does not prove a product is obsolete, inventory is wrong, or the reference row should be deleted. Repeated matching main keys use a lookup row once for this count. Zero unused rows gives a header-only unused CSV and an empty JSON rows array.
What happens to missing or duplicate keys?
A missing main key component stays in the output as missing_key and is included in the unmatched download. With only Item → SKU selected, a second 001 in the lookup blocks the join. With multiple pairs, only a repeated full combination is a duplicate. Download lookup issues to find its CSV record and the first occurrence; record numbers include the header, and quoted multiline records count once. For multiple pairs, issue exports show each lookup key component in its own labeled column. Exact-text JSON also records the paired key column names. Fix the source and retry. The tool never picks a first or last duplicate or multiplies rows.
How are output columns named?
Original columns stay unchanged. Selected fields get a lookup_ prefix and the final column reports join status. Name collisions get suffixes such as lookup_Name_2 or join_status_2. If formula protection would make two exported headers identical, rename a source column and reload. Joined output is limited to 100 columns and 200,000 cells; combined exports use a conservative 8 MiB budget.
Which CSV tool do I need?
Use this tool to enrich main rows from a unique lookup table. To find added, removed or changed records between two versions, use CSV Change Report or read how to compare CSV files by ID. That workflow requires unique keys in both files. If changing export timestamps obscure the real differences, compare selected columns and ignore the timestamp; use a join when you need to add reference columns instead.
Find a HubSpot company ID from its website
Have a list of company websites? Add each company’s HubSpot ID beside it. A domain is a website name, such as acme.example. A Record ID is the number HubSpot uses to identify a company.
Try it with two practice files
A CSV is a table saved as a text file. These files use made-up companies and IDs.
- Download the website list and download the company list.
- At the top of this page, choose hubspot-main.csv under Main CSV. This is the list you want to add details to. Choose hubspot-lookup.csv under Lookup CSV. This list supplies the IDs.
- Set Main key column to Domain and Lookup key column to Company domain name. These are the two columns to compare.
- Under Lookup fields to append, select only Record ID and Company name. “Append” means add to your list. Click Join CSV files.
What should you see?
The two acme.example rows both get ID 1001. Three rows have no exact match, so their added cells stay blank.
| Row | Domain | lookup_Record ID | lookup_Company name | join_status |
|---|---|---|---|---|
| 1 | acme.example | 1001 | Acme Demo | matched |
| 2 | acme.example | 1001 | Acme Demo | matched |
| 3 | unknown.example | unmatched | ||
| 4 | www.acme.example | unmatched | ||
| 5 | ACME.example | unmatched |
Choose Unmatched CSV to download rows 3–5 for checking. other.example is an unused company: it was in the company list but was not needed.
Before using your own files
- Export your companies: follow HubSpot’s export steps. Include Company domain name, Record ID and Company name. Use one domain per cell.
- Check the spelling: capitals, spaces and
www.matter.ACME.exampleandwww.acme.exampledo not matchacme.example. - Check the company list: each domain must appear once and cannot be blank. Fix these issues before joining. Your main list can repeat domains.
- A missing match does not mean a new company. Your export may be old or leave out companies because of filters. Check HubSpot before taking action.
- Review the download before using it. Added column names start with
lookup_. This is not a file ready to import into HubSpot, and this tool does not connect to your account.
File limits and spreadsheet tips
Each file can contain up to 2 MiB, 10,000 rows, 100 columns and 200,000 cells. The tool does not split multiple domains in one cell or tidy website addresses.
For spreadsheet safety, downloaded CSVs add an apostrophe before values that look like formulas. Spreadsheets may also change IDs. Choose Exact-text JSON if you need a data file that keeps the original text.
HubSpot’s own import tools, Excel lookups and paid data tools are other options. This example only compares two CSV files on your device.
Your files stay on your device
Processing runs locally with a 30-second timeout. Cancel stops active work; clear or refresh removes working data and download links. Previously downloaded files remain on your device. No files, headers or values are sent to a server. The hosting provider receives ordinary connection information when serving this page. See the privacy note.
Limited usage measurement
Plausible counts pageviews, tool visits, processing attempts, ready results and download requests. Failed or cancelled attempts may count as starts, but not ready results. Download requests do not prove a file was saved. We send no file contents, filenames, column names, selected keys, values, raw errors, query strings or arbitrary properties. Page URLs are fixed; external referrals include only HTTP(S) protocol and hostname, without ports. No app browser storage is used. Plausible receives ordinary connection information, including your IP address and browser information, for aggregate statistics. The built-in picking-list example and its unchanged downloadable practice tables do not count as workflows. The HubSpot-style practice files, modified practice data and other synthetic uploads may count.
Files are processed locally. The hosting provider receives ordinary connection information when serving this website. See the Litewares privacy note.