v.db.join(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 v.db.join — the GRASS manual, but make it bestie-coded 💖

okay so. hi. you're looking at v.db.join from the GRASS User's Manual, and honestly? this one is a bop. it's the little glue stick that merges a whole other database table into your vector map's attribute table. no cap. let's get into it 🫶

✨ NAME ✨

v.db.join — Joins a database table to a vector map table. 💅

🏷️ KEYWORDS 🏷️

vector, attribute table, database

🌈 SYNOPSIS 🌈

v.db.join
v.db.join --help
v.db.join map=name  [layer=string]  column=name other_table=name
other_column=name  [subset_columns=name[,name,...]]
[exclude_columns=name[,name,...]]   [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags

  • --help — Print usage summary. the "wait what does this even do" button 🙈
  • --verbose — Verbose module output. she talks a LOT and we love that for her ✨
  • --quiet — Quiet module output. she says nothing. mysterious. iconic 💀
  • --ui — Force launching GUI dialog. for the girlies who want buttons instead of typing 🖱️

🌸 Parameters

  • map=name [required] — Name of vector map. Vector map to which to join other table. this is your main character map 👑
  • layer=string — Layer number or name. Layer where to join. Default: 1. yes bestie, layers have numbers, and the default is 1 🧚
  • column=name [required] — Identifier column (e.g.: cat) in the vector table to be used for join. this is the column y'all are matching on 💖
  • other_table=name [required] — Other table name. the table you're dragging INTO the map 🎀
  • other_column=name [required] — Identifier column (e.g.: id) in the other table used for join. and this is her matching partner 🦋
  • subset_columns=name[,name,...] — Subset of columns from the other table. only bring the some of the other table, not all of it. lowkey selective, highkey smart 💅
  • exclude_columns=name[,name,...] — Columns to exclude from the other table. bring everything EXCEPT these ones. not me blocking specific columns 🙈

💜 DESCRIPTION 💜

v.db.join joins the content of another table into the connected attribute table of a vector map.

periodt. that's the whole gig. it's giving matchmaker. 👑

📝 NOTES 📝

v.db.join is a front-end to db.execute to allow easier usage. so she's basically a friendly wrapper around the real one. a translator, if you will ✨

The vector attribute table must be stored in a SQL database (SQLite, PostgreSQL, MySQL, ODBC, ...). The DBF backend is not supported. so like — SQL databases only bestie. DBF is NOT invited to the party 💀

Tables can be imported with db.in.ogr. handy!! 🫶

The vector map-database connection(s) can be verified with v.db.connect. do this. pls. trust me. vibe check your connections first 🔍

🧪 EXAMPLES 🧪

Exercise to join North Carolina geological classes from a CSV table to the "geology" map of the North Carolina sample dataset (requires download of legend CSV file nc_geology.csv from External data for NC sample dataset):

# check original map attributes
v.db.select geology column=GEO_NAME,SHAPE_area
# import of CSV table
db.in.ogr input=nc_geology.csv output=nc_geology
# work on copy of geology map in current mapset
g.copy vector=geology,mygeology
# check column names of vector map attributes
v.info -c mygeology
# check column names of legend table
db.describe -c nc_geology
# join table using key columns (map: "GEO_NAME"; table: "geol_id")
v.db.join map=mygeology column=GEO_NAME other_table=nc_geology other_column=geol_id
# verify result (here abbreviated)
v.db.select mygeology | head -3
cat|onemap_pro|PERIMETER|GEOL250_|GEOL250_ID|GEO_NAME|SHAPE_area|SHAPE_len|geol_id|longname|comment
1|963738.75|4083.97998|2|1|Zml|963738.608571|4083.979839|Zml|Metagraywacke|Interlayered with metaconglomerate, ...
2|22189124|26628.261719|3|2|Zmf|22189123.2296|26628.261112|Zmf|Metafelsite|Light-colored porphyritic extrusive rock
...

🍓 Soil map table join 🍓

Joining the soil type explanations from table soils_legend into the Spearfish soils map (download legend):

g.copy vect=soils,mysoils
# import legend table
db.in.ogr soils_legend.csv out=soils_legend
# get join column names
v.info -c mysoils
db.describe -c soils_legend
# look at original table
v.db.select mysoils
cat|label
1|Aab
2|Ba
3|Bb
4|BcB
5|BcC
...
# look at legend
db.select table=soils_legend
db.select table=soils_legend | head -7
id|shortname|longname
0|no data|no data
0|AaB|Alice fine sandy loam, 0 to 6
0|Ba|Barnum silt loam
0|Bb|Barnum silt loam, channeled
0|BcB|Boneek silt loam, 2 to 6
0|BcC|Boneek silt loam, 6 to 9
...
# join soils_legend into mysoils attribute table
v.db.join mysoils col=label other_table=soils_legend ocol=shortname
# verification of join
v.db.select mysoils
cat|label|id|shortname|longname
1|Aab|||
2|Ba|2|Ba|Barnum silt loam
3|Bb|3|Bb|Barnum silt loam, channeled
4|BcB|4|BcB|Boneek silt loam, 2 to 6
5|BcC|5|BcC|Boneek silt loam, 6 to 9
...

notice how we used col= and ocol= as the short versions of column= and other_column= in that last join? yeah. she's flexible like that. ate. 💅

👀 SEE ALSO 👀

db.execute, db.in.ogr, db.select, v.db.update

GRASS SQL interface

👑 AUTHOR 👑

Markus Neteler

🦋 SOURCE CODE 🦋

Available at: v.db.join source code (history)

Latest change: Friday Feb 07 19:16:09 2025 in commit: a82a39f673b97fafcfce1604dc3e6015cb96487a

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

okay that's the whole thing bestie, you're SO ready to join some tables now 🌸 slay 💖 and for the cute little sign-off: this whole manual moment is © 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual, and yes the big banner down at the bottom says GRASS 8.5.0 with v.db.join(1grass) — go forth and merge, my love 🎀✨

📦 where this page comes from