Two tables can look perfectly compatible and still refuse to match. A bookings export calls a customer 0042, while a directory calls the same customer 42. Another identifier appears twice in the directory because it contains both a current and an old address. A join cannot decide whether those differences are mistakes or meaningful distinctions. It follows the matching rule you give it.
Before combining CSVs, investigate the key as a piece of information. The goal is to explain which rows should match, which should remain unmatched and whether one match is allowed to produce several results. That investigation is often more valuable than the button that performs the join.
Write one sentence describing a match
Suppose the left table contains orders and the right table contains customer details. A useful rule is: “Each order keeps its own row and receives the current directory entry with the same CustomerID.” This sentence implies a left join and one directory entry per identifier. It does not imply that customer names are unique, or that orders with missing directory details should disappear.
Make the key’s unit explicit. Is it a customer, an account, a location or an individual transaction? Joining on an account code when the right table has one row per location introduces a different relationship. A column label can be identical across two files while referring to different entities. Ask the producer of the data when the meaning is unclear.
Protect identifiers from numeric interpretation
The Microsoft guidance on leading zeros explains why identifiers may need to be imported as text. A code is not necessarily a number merely because it contains digits. Leading zeros can distinguish the original representation, and long digit strings can be damaged by numeric conversion.
Check the raw CSV before trying to repair it. If the export contains 0042 but a spreadsheet displays 42, the interpretation may have changed during import. If the file itself already contains 42, changing the display format cannot establish what the missing characters were. Return to a trustworthy source rather than padding every value according to an unsupported guess.
Inspect a few boundary cases in both tables: the shortest key, the longest key, a key containing letters, one with punctuation and one you expect to be absent. Also look for surrounding spaces and differences in capitalization. Handyfold compares exact strings. “AC-7” and “ac-7” are different, as are a plain code and a code followed by a space.
Duplicates tell you about the relationship
Consider a left table with one order for customer A and a right table with two rows for A. A general relational join can produce two output rows for that order. If both sides repeat A, the expansion grows further. The pandas merging guide illustrates this duplicate-key behavior and the risk of unexpectedly enlarged results.
Handyfold’s CSV key join takes a deliberately narrower approach: duplicate keys on the right are rejected. Treat that message as a prompt to resolve the data model. Do the rows represent legitimate alternatives? Should you choose a current record using a date? Should the result be a one-to-many report in a different system? Deleting whichever duplicate happens to come second is not a reliable policy.
Repeated keys on the left can be legitimate. Several orders may belong to one customer, so several left rows can receive the same directory details. The important distinction is between repeated entities that are part of the task and accidental repetition that changes its meaning.
Use a tiny reconciliation example
Try the tool’s sample. The left table has ID and Name, with Ada at ID 1 and Sam at ID 2. The right table has ID and Role, with Designer at ID 1 and Writer at ID 3. After the left join, Ada receives Designer. Sam stays in the result with an empty Role. ID 3 does not become a new left row.
Those two output rows demonstrate the intended accounting. For a larger version of the same relationship, the output should retain the left table’s row count because right keys must be unique. Investigate any surprising result before calculating totals from the joined data. Count how many rows matched and examine a sample of the rows with empty added fields.
Do not confuse an empty value with a failed match
An empty Role can mean either that no directory row matched or that the matching row contained an empty Role. If that distinction matters, add a clearly named presence column to the right-side source, filled with a constant such as directory-record. Its appearance in the result makes presence easier to inspect without inventing a meaning for a blank business field.
Finally, check a known match by hand and retain the original files. Exported column names can change when names overlap; Handyfold prefixes conflicting right-side names. Read the actual header before handing the result to another process. A dependable join is one whose relationship, unmatched rows and column origins you can explain, even without opening the tool that created it.
