Join tables

This tool can be used to join (i.e. merge) a shapefile's attribute table with a second table. The user must specify the name of the shapefile (and associated attribute file) as well as the primary key within the table. The primary key is the field within the table that is being appended to that serves as the unique identifier. Additionally, the user must specify the name of a second shapefile/attribute table from which the data appended into the first table will be derived. The foreign key, the unique identifying field within the second table that corresponds with the data contained within the primary key in the table, must be specified. Both the primary and foreign key should either be strings (text) or integer values. Fields containing decimal values are not good candidates for keys. Lastly, the names of the fields within the second file to include in the merge operation must also be input.

Merging works for one-to-one and many-to-one database relations. A one-to-one relations exists when each record in the attribute table corresponds to one record in the second table and each primary key is unique. Since each record in the attribute table is associated with a geospatial feature in the shapefile, an example of a one-to-one relation may be where the second file contains AREA and PERIMETER fields for each polygon feature in the shapefile. This is the most basic type of relation. A many-to-one relation would exist when each record in the first attribute table corresponds to one record in the second file and the primary key is NOT unique. Consider as an example a shapefile and attribute table associated with a world map of countries. Each country has one or more more polygon features in the shapefile, e.g. Canada has its mainland and many hundred large islands. You may want to append a table containing data about the population and area of each country. In this case, the COUNTRY columns in the attribute table and the second file serve as the primary and foreign keys respectively. While there may be many duplicate primary keys (all of those Canadian polygons) each will correspond to only one foreign key containing the population and area data. This is a many-to-one relation. The Join Tables tool does not support one-to-many nor many-to-many relations.

See Also:

Scripting:

The following is an example of a Python script that uses this tool:

wd = pluginHost.getWorkingDirectory()
# Input data has the shapefile name followed
# by the attribute (primary key), separated by
# a semicolon.
inputData = wd + "coutries.shp" + ";" + "NAME"
secondFile = wd + "populationData.shp"
foreignKey = "COUNTRY"
includeFields = "POPULATION;AREA"
args = [inputData, secondFile, foreignKey, includeFields]
pluginHost.runPlugin("MergeTables", args, False)

This is a Groovy script also using this tool:

def wd = pluginHost.getWorkingDirectory()
// Input data has the shapefile name followed
// by the attribute (primary key), separated by
// a semicolon.
def inputData = wd + "coutries.shp" + ";" + "NAME"
def secondFile = wd + "populationData.csv"
def foreignKey = "COUNTRY"
def includeFields = "POPULATION;AREA"
String[] args = [inputData, secondFile, foreignKey, includeFields]
pluginHost.runPlugin("MergeTables", args, False)

Credits: