GIS Tools - Join Tool (CSV ↔ Layer)

What Is an Attribute Join in GIS?

An attribute join is the operation of merging two tables based on a common key field, where one table contains spatial features and the other contains tabular data you want to attach to those features. It is the GIS analyst's daily bread: you have a shapefile of census tracts and a CSV of demographic data downloaded from the Census Bureau, both keyed by GEOID, and you want to put the demographics on the map. The attribute join glues them together so you can style, filter, and analyze using the combined attributes.

The join is conceptually identical to a SQL join. You specify a left table (the spatial layer), a right table (the CSV or other tabular file), the join key field on each side, and the join type (inner, left, right, full outer). The join engine walks through the rows, matches keys, and produces a combined feature collection where each feature has the original geometry plus the attributes from the matched row.

This is the standard pattern for csv join shapefile workflows: you have a boundary layer once and you bring in fresh tabular data every reporting period (every quarter, every month, every election cycle) without re-creating the boundaries. It is also the foundation for any analysis that combines authoritative geometry with mutable observations.

The gis.tools join tool runs entirely in the browser. You drop a CSV (or another GeoJSON) on top of an already-loaded spatial layer, pick the join keys from a dropdown, and the tool produces a new layer with the merged attributes. No server, no database, no SQL knowledge required.

How an Attribute Join Works

Hash join

The most common implementation is a hash join. The engine walks the right table once, building a hash map from key value to row. Then it walks the left table, looks up each feature's key in the hash map, and copies the matched row's columns into the feature's properties. This is O(N + M) — linear in the total size of both tables.

Join types

Inner join: keep only features that have a match in the right table. Drops orphans on both sides.
Left join: keep all features from the left table; right-side fields are null for unmatched features. This is the default for GIS attribute joins because you usually want to retain all geometries.
Right join: keep all rows from the right table; rare in spatial workflows.
Full outer join: keep all rows from both tables. Rarely used in GIS.

Key matching

Keys are compared with strict equality. Whitespace, case differences, and type mismatches cause join failures. The tool offers normalization options (trim, lowercase, cast to number) to handle common issues.

Field collision handling

If both tables have a field named name, the join tool prefixes the right-side field with the right-table name (e.g., csv_name) to avoid clobbering.

Key Parameters and Options

Join key fields

Pick the field on each side that contains the matching values. The tool offers a preview of the first few matches so you can verify the keys line up.

Join type

Left join is the safe default. Switch to inner join when you want to drop orphan geometries.

Key normalization

Options to trim whitespace, lowercase, or cast to integer/string before matching.

Field selection

Choose which columns from the right table to bring across. Dropping unused columns keeps the output light.

Practical Applications

Census mapping

A demographer downloads American Community Survey tables as CSV and joins them to TIGER/Line census tract shapefiles using the GEOID field. The result is a spatial layer with median income, age distribution, and population density attached to each tract — ready to style as a choropleth using Graduated Color Styling.

Election results

An elections analyst joins precinct-level voting results (CSV from the county elections office) to a precinct boundary shapefile. The combined layer becomes a precinct-level result map for election night reporting and post-election analysis.

Real estate market analysis

A realty firm joins MLS listings data (CSV) to a parcel shapefile using parcel ID. The result is a map of active listings with price, days on market, and listing agent attached to each parcel boundary.

Public health surveillance

A public health analyst joins case counts (CSV from the state health department) to county boundaries to produce a daily incidence map.

School district reporting

An education researcher joins standardized test results (CSV from the state education agency) to school district boundaries for an annual report on educational equity.

Environmental compliance tracking

A regulatory office joins facility inspection results (CSV from the inspection database) to a facility location shapefile to produce a compliance status map.

Business operations

A retail chain joins quarterly store revenue (CSV from the data warehouse) to store locations (GeoJSON) for the executive map dashboard.

Step-by-Step Workflow

Load your spatial layer (shapefile, GeoJSON, KML) into the GeoJSON, KML, Shapefile & GIS File Viewer.
Drop your CSV file onto the viewer or use the join tool's file picker.
Open the join dialog and pick the spatial layer as the left table and the CSV as the right table.
Select join keys: pick the field on each side that contains the matching values.
Preview the matches — the dialog shows how many features matched, how many are orphaned, and a sample of the merged attributes.
Choose join type (left join is the default).
Pick which fields to bring across.
Run the join — a new layer is created with the merged attributes.
Style or analyze the joined layer using Graduated Color Styling, Categorical Styling, or further filters.
Export the joined dataset using Multi-Select & Export.

Worked Example

A city budget office wants to map per-capita library spending across council districts. They have a council district GeoJSON with 17 features and a CSV of district-level budget allocations exported from the financial system. The CSV has columns district_num, library_budget, population, and fiscal_year.

They load the GeoJSON, drop the CSV on top, and open the join tool. The dialog suggests district_num as the join key on both sides. The preview shows all 17 districts matching. They run a left join. The new layer has the original geometry plus the four CSV columns. They use the Graduated Color Styling tool to style the layer by library_budget / population, producing a choropleth map of per-capita library spending.

The analysis reveals that District 4 spends $42 per resident on libraries while District 11 spends $7 — a six-fold difference. The map goes into the budget office's annual equity report.

Common Pitfalls and Gotchas

Key type mismatches. A district_num field stored as integer in the shapefile but as string in the CSV will not match. Use the cast option to normalize.
Leading zeros stripped. CSV imports often strip leading zeros from text-like IDs, breaking joins on FIPS codes or zip codes.
Whitespace in keys. Trailing spaces in one source but not the other cause silent join failures. Use the trim option.
Case sensitivity. "CA" and "ca" are different keys without the lowercase normalization option.
Encoding mismatches. Non-ASCII characters in keys may not match across UTF-8 and Latin-1 sources.
Many-to-one joins inflating geometry. Joining a one-to-many table to a spatial layer creates duplicate features per match, often unintended.
Field name collisions. Both tables having a name field can cause one to overwrite the other unless the tool prefixes.
Nulls in the join key. Features with null keys cannot match anything; they appear as orphans in the output.

Tips for Best Results

Always verify the key types match before joining.
Use a left join to retain all geometries; use an inner join to drop orphans.
Trim and lowercase keys aggressively if data quality is unknown.
Inspect the join preview before committing — match counts tell the truth.
Drop unused columns from the right table to keep the output light.
Save the joined output as a new file for reproducibility.
Document the join key, join type, and join date in metadata.
Use the Data Profiling Report on both inputs first to spot key quality issues.

Comparison with SQL and Desktop GIS

The join is conceptually identical to a SQL LEFT JOIN. PostGIS implements it via the same SQL syntax against a spatial table. QGIS calls this a Joins property on a layer (Layer Properties > Joins) and supports CSV joins natively. ArcGIS has Add Join, which works similarly.

The gis.tools approach is faster for one-off joins because it requires no project setup, no database connection, and no SQL knowledge. For recurring joins on large datasets, a database is more appropriate.

Performance Considerations

Hash joins are linear in the total row count. For two tables of 100,000 rows each, expect under 500ms. The bottleneck is usually the JSON parse and serialization, not the join itself. For million-row joins, consider doing the join in a database and loading only the result.

Data Privacy and Browser-Based Processing

Both input files and the joined output stay in your browser. The join engine has no network calls. This makes the tool safe for combining sensitive data sources — for example, joining patient encounter counts to clinic boundaries without uploading either to a third party.

Related GIS Concepts

Spatial join. A different operation that joins by geometric relationship rather than by attribute key. See Spatial Join.

Foreign key. The standard relational concept of a column whose values reference the primary key of another table.

Lookup table. A reference table joined to a main table to attach descriptive attributes.

Denormalization. Pre-joining tables to avoid runtime join cost in queries.

Frequently Asked Questions

How do I join a CSV to a shapefile?

Load the shapefile, drop the CSV onto the viewer, open the join tool, pick matching keys on both sides, and run the join.

What if my keys are different types?

Use the cast option to convert one side. Common conversions are integer to string (for FIPS codes) and trimming whitespace.

Why does my join produce no matches?

Usually a type mismatch, leading zeros stripped, or case difference. Inspect the key values from each side.

Can I join two shapefiles by attribute?

Yes. Drop both as separate layers and use the join tool.

What is the difference between attribute join and spatial join?

Attribute join matches by a common key field. Spatial Join matches by geometric relationship like intersection or proximity.

GeoJSON Layer

CSV Data

About Table Joins