Half the value in GIS lives in tables that have no geometry at all: census figures by district code, inspection results by parcel ID, species counts by site name. A join by field value is how those tables marry a map. You name the shared key, the column both sides hold, and the table's attributes attach to the layer's features wherever the keys match, turning a plain boundary layer into an analyzable, styleable dataset. QGIS offers two implementations with genuinely different behaviors, a live join in the layer's properties and a processing algorithm that bakes a new layer, and choosing between them, plus surviving the classic failure where every joined value arrives NULL, is the content of this guide. The neighboring operation, joining by location instead of by key, is our spatial join guide; this one is about keys.
Home / GIS and Open Map Data for Beginners
QGIS Join Attributes by Field Value: Attach a Table to Your Layer by a Shared Key

Photo: Tima Miroshnichenko / Pexels
Bookkeeping That Holds: The Join Checklist
Check off each step as you finish it. Your progress stays on this page.
0 of 8 complete
0% done
The Idea: A Lookup for Maps
Strip away the GIS and a field-value join is the spreadsheet VLOOKUP wearing boots. The layer is one table, the external data, a CSV, a spreadsheet, another layer's attributes, is the second, and the key field is the column whose values identify the same real-world thing in both: the district code, the station ID, the ISO country code. Where keys match, the second table's columns become readable as if they were the layer's own. Where they do not match, the feature gets NULLs, which is information, not an error: it tells you the lookup failed for that row, and a census of those NULLs after any join is the cheapest data-quality report in GIS. Keys must be true identifiers, unique on at least one side, stable, and formatted identically on both sides; names make fragile keys because spelling varies, while codes make strong ones. If your data lacks a real key, building one is data work worth doing before any joining, often with the field calculator normalizing a messy column into a matchable one.
Set Up the Join: Two Routes
Route one is the live join: open the layer's Properties, go to the Joins tab, add a join, choose the table layer, the join field in that table, and the target field in your layer, optionally picking a field prefix and which columns to bring across. The joined columns appear in the attribute table immediately, styled with the prefix, and the join is dynamic: edit the source table and the layer reflects it. The cost is that the join is a relationship, not data: it lives in the project, does not travel with the file, and exports must explicitly materialize it. Route two is the processing algorithm Join Attributes by Field Value in the Processing Toolbox, which takes the layer, the table, the two key fields, and writes a new layer with the joined columns physically attached. That permanence is what deliverables, exports, and hand-offs need. Choose the live join for exploration, the processing tool for products. Both share the same matching logic, so the failure modes below apply to each.

The All-NULL Disaster: Key Types Must Match
Every QGIS user meets this once: the join completes without complaint and every joined value is NULL. The cause, almost always, is a key type mismatch. Your layer's code field is an integer, 101, 102, 103; the CSV's code column was read as text, "101", "102", "103", and the join engine, correctly, refuses to equate a number with a string that merely looks like one. CSVs are the repeat offender because they carry no type information and QGIS guesses, often differently than the layer's format guessed. The diagnosis takes ten seconds: open both attribute tables and compare the key columns' alignment and behavior, text left-aligns and sorts alphabetically, numbers right-align and sort numerically, or check the field types in each layer's properties. The fixes are equally mechanical: convert one side to the other's type with the field calculator, to_int or to_string, or control the CSV's interpretation with a companion type file. Trailing spaces and case differences in text keys produce the partial version of the same disaster, some rows matched, some NULL, and a trim and case normalization on both sides is the cure. Rule of the craft: after any join, before any analysis, count the NULLs in a joined column. Zero unexpected NULLs is the join's certificate; anything else is a diagnosis waiting to happen.
One-to-One, One-to-Many, and the Fine Print
Joins have a shape, and the shape decides what you get. One-to-one, each key appears once on both sides, is the clean case: every feature gains exactly its row. Many-to-one, many features share a key that is unique in the table, a hundred parcels joining to one zoning row, is equally safe. One-to-many is the dangerous direction: one feature whose key matches several table rows, a district joining to a table of yearly figures. A live layer join resolves this by taking the first matching record and silently ignoring the rest, which is a data-loss behavior hiding inside a successful operation. The processing tool offers more control, including discarding non-matching features and, in its options, how multiple matches are handled, but no setting makes one-to-many honest inside a single flat layer; the correct structures are either a relation in the project, or one output feature per match where the analysis truly needs the long form. Know your shape before you join: count duplicates in the table's key column, and if the count is not what your mental model assumed, stop and remodel. Joins are cheap; un-joining a conclusion built on silently dropped rows is not.
Make It Permanent, and Keep It Clean
Finish the job like a professional. If the joined result will be shared, filtered, exported, or built upon, materialize it: run the processing join, or export the live-joined layer to a new file, which bakes the joined columns in as real fields, and verify the export's row count and NULL census match the in-project view. Remove live joins you no longer need from the layer's properties; stale joins slow projects and confuse successors, and a join whose source table has moved becomes a quiet source of empty columns. Name joined fields clearly at creation, since the default prefix is often the table's name repeated into uselessness. And document the key: a line in the layer's metadata or your project notes, joined on district_code to the 2024 census table, is the difference between a dataset and a mystery for whoever inherits the project, including future you. The join by field value is a small operation with an outsized blast radius, because everything downstream, every map, statistic, and decision, will trust its matches. The NULL census, the type check, and the duplicate count are how that trust is earned.
A Worked Example: Census Figures Onto District Boundaries
Watch the whole discipline operate on the canonical job. You have a district boundary layer whose key field, dist_code, is an integer, and a census CSV whose district column was typed by a human and arrives as text, with two districts spelled by name instead of code. The naive join produces the all-NULL disaster's subtler cousin: most rows match after you convert the CSV's column to integer with to_int, but the two name-spelled rows convert to NULL keys and their districts join to nothing, which your post-join NULL census catches immediately because exactly two districts lack population. The fix is a small translation table for the two exceptions, or a corrected source file, applied before the join rather than patched after. With keys clean, the processing join bakes population, households, and median income onto the boundaries as real fields; the row count matches the boundary layer exactly, the NULL census is zero, and a spot check of the largest district against the census publication confirms the match is the right district and not merely a district. Only now does styling by population density, itself a field calculator division away, rest on something trustworthy. The example is ordinary to the point of dullness, which is the lesson: joins are not advanced GIS, they are bookkeeping, and bookkeeping done with a type check, a duplicate count, and a NULL census is what separates a map that merely looks informed from one that is.
Joining to Spreadsheets Without Tears
Most attribute tables that arrive for joining were born in a spreadsheet, and spreadsheets have habits worth preempting. Save or export the sheet as CSV rather than joining a live spreadsheet file, because the plain text format freezes the values, strips the formatting traps, and travels between machines without driver drama. Check the first data row for dignity: spreadsheet exports love to include a totals row, a blank separator row, or a repeated header halfway down where two tables were pasted together, and each becomes a junk key or a phantom record downstream. Numbers stored with thousands separators or currency symbols arrive as text and fail the type discipline until cleaned, and dates exported in a local format become strings that sort alphabetically rather than chronologically. None of this is the spreadsheet user's fault; the two programs simply keep different promises. The CSV conversion ritual, export, eyeball the head and tail of the file, confirm the key column's contents, then join, takes two minutes and converts the most failure-prone input in everyday GIS into the most predictable one.
Related Guides
The closest companions to this guide are the GIS and open map data guides below. Each one picks up a thread this page starts:
- How to Merge Layers in QGIS: One Layer, Same Geometry, Shared CRS: Twelve district files that should be one province, four quarterly exports that should be one year: merging layers is the janitorial task every GIS...
- The QGIS Attribute Table: Rows Are Places, Columns Are Facts: Every layer in QGIS is two things at once: the shapes on the map and the table behind them.
- Geocoding in QGIS: Turn a Table of Addresses Into Points With MMQGIS: Every spreadsheet of addresses is a map waiting to happen, and geocoding is the machine that makes it: street, city, and country in, points on the...
- QGIS Join by Attribute: The Live Joins Tab, From Shared Field to Saved Project: the live Joins tab version of the join
Frequently Asked Questions
What is the difference between the layer join and the processing join in QGIS?
The Joins tab in layer properties creates a live relationship: joined columns appear immediately and update with the source table, but they are not stored in the file. The Join Attributes by Field Value processing tool writes a new layer with the columns physically attached, which is what exports and deliverables need.
Why are all my joined values NULL?
Most often a key type mismatch: the key is an integer on one side and text on the other, a classic with CSV files, which carry no types. Compare the field types in both layers and convert one side with to_int or to_string in the field calculator. Trailing spaces and case differences in text keys cause partial versions of the same failure.
What happens when one feature matches several table rows?
A live layer join takes the first matching record and ignores the rest, silently. Check for duplicate keys in your table before joining; if the data is genuinely one-to-many, use a project relation or restructure the data rather than letting a flat join drop rows.
Can I join a CSV or spreadsheet to a layer?
Yes. Add the CSV or spreadsheet as a layer in QGIS, then join it by the shared field. Watch its inferred column types, especially on the key, and consider converting the table to a GeoPackage or using a type-definition file if the guesses are wrong.
How do I make a join permanent?
Either run the Join Attributes by Field Value processing tool to produce a new layer, or export the live-joined layer to a new file, which bakes the joined fields in. Verify row counts and check for unexpected NULLs in the result before relying on it.
Photo credits: Tima Miroshnichenko (Pexels); Mikhail Nilov (Pexels). Photos are served from this site; follow the credit to the library page for the original.