What is the difference between merge and append in Stata?

merge adds variables by matching on keys; append adds observations from another dataset with the same variables.

What does _merge == 3 mean in Stata?

The observation was matched in both the master and using datasets. 1 means master only, 2 means using only.

Why does Stata say the variables do not uniquely identify observations?

You declared a 1 side (1:1, m:1 or 1:m) but that dataset has duplicate keys. Remove duplicates or choose the right merge type.

How do I check a key is unique before merging in Stata?

Run isid followed by the key variables on the dataset. It stops with an error if they don't uniquely identify observations; duplicates report shows how many repeats there are.

Can Stata merge on more than one variable?

Yes. List all key variables after the merge type, for example merge 1:1 person_id year using income.

What happens to variables that exist in both files in a Stata merge?

The master's values are kept by default. Use the update option to fill missing master values from using, or update replace to overwrite them.

How do I merge many-to-many in Stata?

Not with merge m:m, which pairs rows in order. Use joinby to form every combination of observations within each key group.

How to merge datasets in Stata

By the Analistable team · Updated 2026-10-07 · 5 min read

Load the master dataset, then run merge m:1 customer_id using customers (many orders, one customer each), merge 1:1 id using other (one row per key on both sides) or merge 1:m (the reverse of m:1). Stata adds a _merge variable: 1 = master only, 2 = using only, 3 = matched. Add keep(match) for an inner join, and use append to stack datasets.

Part of our guide: How to merge data in pandas, R and SQL

Choosing 1:1, m:1 or 1:m

merge types
Master (in memory)	Using (on disk)	Command
One row per person	One row per person	merge 1:1 person_id using survey2
Many orders per customer	One row per customer	merge m:1 customer_id using customers
One row per customer	Many orders per customer	merge 1:m customer_id using orders

Stata checks the claim: if the “1” side has duplicate keys, the merge stops with an error saying the variable doesn't uniquely identify observations. Avoid merge m:m — it pairs rows in order rather than forming every combination; use joinby for that.

A worked example

use orders, clear
merge m:1 customer_id using customers

tab _merge
*   _merge |  Freq.
*   master only (1) |  1    <- order with an unknown customer
*    using only (2) |  1    <- customer with no orders
*       matched (3) |  3

Three orders matched a customer, one order had no customer record, and one customer had no orders.

Keep the rows you need

merge m:1 customer_id using customers, keep(match) — inner join.
keep(master match) — left join: every order.
nogenerate — don't create _merge (only once you've checked it).
keepusing(name country) — bring only some variables from the using dataset.

Stacking with append

use orders_2025, clear
append using orders_2026, generate(source)

generate(source) adds 0 for rows from the master and 1 for rows from the appended file. Variables are matched by name; missing ones are filled with missing values.

Key variables must have the same type in both files: a string customer_id won't merge with a numeric one. Convert with destring or tostring first. Equivalent joins in pandas, R and SQL: merging data in pandas, R and SQL.

Checking the result

assert _merge == 3 stops a do-file if any observation failed to match, which is useful when every order must have a customer. Use count if _merge == 1 to report unmatched observations without stopping.

A second example: panel data with 1:1 on two keys

Survey waves are stored per person and year. Merge income data onto the survey using both identifiers:

use survey, clear                     // person_id year satisfaction
merge 1:1 person_id year using income  // person_id year income

tab _merge
drop if _merge == 2                   // income rows with no survey response
drop _merge

Both datasets must be unique on the combination of person_id and year, which you can confirm beforehand with isid person_id year in each file. If isid fails, duplicates report person_id year shows how many repeats there are and duplicates list person_id year lists them.

Checking keys before you merge

use customers, clear
isid customer_id                // error if customer_id is not unique
duplicates report customer_id
describe customer_id            // check str or numeric type and length

use orders, clear
describe customer_id
count if missing(customer_id)   // orders that can never match

Two minutes of checks avoids the most common failures. String keys with different capitalisation or leading spaces won't match; clean them with replace customer_id = upper(strtrim(customer_id)) in both files and save before merging.

Troubleshooting

Symptom, cause and fix
Message or symptom	Cause	Fix
variable customer_id does not uniquely identify observations in the using data	The 1 side has duplicates	Remove duplicates, or use the correct m:1 / 1:m direction
key variable customer_id is str in master but float in using	Different types	destring or tostring one of them, then save
variable _merge already defined	A previous merge left _merge in the data	drop _merge, or use generate(newname)
A variable from using seems to be ignored	Master already has a variable with the same name, and master's values are kept	Rename it in using before merging, or use update / update replace if that is intended

By default, variables that exist in both files keep the master's values. The update option fills master's missing values from using, and update replace also overwrites the master's non-missing values with non-missing values from using, so use those only when that is what you intend.

Merge, append or joinby?

merge: add variables from another file by key, one side unique.
append: add observations from files with the same variables, such as yearly waves.
joinby: form every pairwise combination within groups, the true many-to-many join.
frlink and frget (Stata 16 and later): link a second dataset held in a frame and copy variables across without leaving the master in memory.

Put the steps in a do-file with assert checks so that next month's data is merged and validated in the same way. The equivalent logic in SAS uses IN= flags; see SAS MERGE with BY and IN=.

Frequently asked questions

What is the difference between merge and append in Stata?: merge adds variables by matching on keys; append adds observations from another dataset with the same variables.
What does _merge == 3 mean in Stata?: The observation was matched in both the master and using datasets. 1 means master only, 2 means using only.
Why does Stata say the variables do not uniquely identify observations?: You declared a 1 side (1:1, m:1 or 1:m) but that dataset has duplicate keys. Remove duplicates or choose the right merge type.
How do I check a key is unique before merging in Stata?: Run isid followed by the key variables on the dataset. It stops with an error if they don't uniquely identify observations; duplicates report shows how many repeats there are.
Can Stata merge on more than one variable?: Yes. List all key variables after the merge type, for example merge 1:1 person_id year using income.
What happens to variables that exist in both files in a Stata merge?: The master's values are kept by default. Use the update option to fill missing master values from using, or update replace to overwrite them.
How do I merge many-to-many in Stata?: Not with merge m:m, which pairs rows in order. Use joinby to form every combination of observations within each key group.