Summary
The FieldMappings object is a collection of FieldMap objects. Use the object as a parameter value for tools that perform field mapping, such as the Merge tool.
Discussion
The properties of the FieldMap object include the start and end position of an input text value, so an output value can be created using a slice of an input value. If a FieldMap object contains multiple input fields from the same table or feature class, each record's values are merged using the mergeRule property. This is a convenient way to join values, such as a street name that is held in one field and a street type that is held in another, for example, Eureka and Street. The joinDelimiter property of the FieldMap object is used when Join is specified as the mergeRule value. Any set of characters, such as a space, can be used as a delimiter. In the example above, this would create a value of Eureka Street.
The FieldMappings object is a collection of FieldMap objects, and it is used as the parameter value for tools that perform field mapping, such as Merge. The easiest way to work with these objects is to first create a FieldMappings object, then initialize its FieldMap objects by adding the input feature classes or tables that are to be combined. Once all inputs are provided, the FieldMappings object will contain one FieldMap object, or output field, for each unique field name from all the inputs. You can modify this list by adding new fields, altering the properties or contents of an output field, or removing unwanted output fields.
Syntax
FieldMappings ()
Properties
Property | Explanation | Data Type |
fieldCount (Read Only) | The number of output fields. | Integer |
fieldMappings (Read and Write) | A list of FieldMap objects that make up the FieldMappings object. | FieldMap |
fieldValidationWorkspace (Read and Write) | The workspace type that defines the rules for attribute field naming. These rules are used when determining the output field names, which are based on the names of the input fields. For example, setting the fieldValidationWorkspace property to the path of a folder on disk containing the input shapefiles will result in the output field names being truncated to 10 characters. Setting the fieldValidationWorkspace property to the path of a file geodatabase will allow for much longer field names. The fieldValidationWorkspace property should be set with a consideration for the output format. | String |
fields (Read Only) | A list of Field objects. Each field object represents the properties of each output field. | Field |
Method Overview
Method | Explanation |
addFieldMap (field_map) | Add a field map to the field mappings. |
addTable (table_dataset) | Adds a table to the field mappings object. |
exportToString () | Exports the object to its string representation. |
findFieldMapIndex (field_map_name) | Find a field map within the field mappings by name. |
getFieldMap (index) | Returns a FieldMap object from the FieldMappings object by index position. |
loadFromString (string) | Defines a FieldMappings object from a formatted string. |
removeAll () | Removes all values and creates an empty object. |
removeFieldMap (index) | Removes a FieldMap object from the FieldMappings object. |
replaceFieldMap (index, value) | Replace a FieldMap object within the FieldMappings object. |
Methods
addFieldMap (field_map)
Parameter | Explanation | Data Type |
field_map | The field map to add to the field mappings | FieldMap |
addTable (table_dataset)
Parameter | Explanation | Data Type |
table_dataset | The table to add to the field mappings object. | String |
exportToString ()
Data Type | Explanation |
String | The string representation of the object. |
findFieldMapIndex (field_map_name)
Parameter | Explanation | Data Type |
field_map_name | Find the field map by name. | String |
Data Type | Explanation |
Integer | The index position of the field map. |
getFieldMap (index)
Parameter | Explanation | Data Type |
index | The index position of the FieldMap object. | Integer |
Data Type | Explanation |
FieldMap | The FieldMap object from the FieldMappings object. |
loadFromString (string)
Parameter | Explanation | Data Type |
string | The string representation of the object. In addition to FieldMappings and FieldMap methods and properties, you can also construct a FieldMappings object from a formatted string. The following example shows the creation of a FieldMappings object that could be used with the Merge tool.
The first nine values in the string define an output field and are space delimited.
The remaining values define the field map characteristics and are comma delimited.
Any number of input fields can be mapped to the output field, not only two, as implied in the example. Include the merge rule and concatenator once, and include the dataset path, field name, and start position and end position for each input field. Enclose any values with spaces, such as the field alias or concatenator, in quotation marks. To skip a value, use a # for string values, and -1 for numeric values. As shown in the following example, use a semicolon delimiter to separate multiple output fields.
| String |
removeAll ()
removeFieldMap (index)
Parameter | Explanation | Data Type |
index | The index position of the FieldMap. | Integer |
replaceFieldMap (index, value)
Parameter | Explanation | Data Type |
index | The index position of the FieldMap object to be replaced. | Integer |
value | The replacement FieldMap object. | FieldMap |
Code sample
FieldMap objects are often used to merge similar datasets into one, all-encompassing dataset. In this example, the Trees feature class and the Plants.shp shapefile are merged into one feature class: Vegetation. Both original feature classes have two attributes: Type and Diameter. These two attributes must be maintained through the merge.
import arcpy
# Set the workspace
arcpy.env.workspace = 'c:/base'
in_features_1 = 'data.gdb/Trees'
in_features_2 = 'Plants.shp'
out_features = 'data.gdb/Vegetation'
# Create the required FieldMap and FieldMappings objects.
fm_type = arcpy.FieldMap()
fm_diam = arcpy.FieldMap()
fms = arcpy.FieldMappings()
# Get the field names of vegetation type and diameter for both
# original files.
tree_type = "Tree_Type"
plant_type = "Plant_Type"
tree_diam = "Tree_Diameter"
plant_diam = "Diameter"
# Add fields to their corresponding FieldMap objects.
fm_type.addInputField(in_features_1, tree_type)
fm_type.addInputField(in_features_2, plant_type)
fm_diam.addInputField(in_features_1, tree_diam)
fm_diam.addInputField(in_features_2, plant_diam)
# Set the output field properties for both FieldMap objects.
type_field = fm_type.outputField
type_field.name = 'Veg_Type'
fm_type.outputField = type_field
diam_field = fm_diam.outputField
diam_field.name = 'Veg_Diam'
fm_diam.outputField = diam_field
# Add the FieldMap objects to the FieldMappings object.
fms.addFieldMap(fm_type)
fms.addFieldMap(fm_diam)
# Merge the two feature classes.
arcpy.management.Merge([in_features_1, in_features_2], out_features, fms)
This sample illustrates using FieldMap objects to merge fields using the ExportFeatures tool. In this example, a feature class contains information about the number of accidents per intersection in a city. Each year of data is maintained in one field. The user wants to find the average number of accidents in each intersection without altering the existing table.
import arcpy
in_features = r'c:/base/data.gdb/AccidentData'
out_features = r'c:/base/data.gdb/AverageAccidents'
# Create the necessary FieldMap and FieldMappings objects.
fm = arcpy.FieldMap()
fm1 = arcpy.FieldMap()
fms = arcpy.FieldMappings()
# Each field with accident data begins with 'Yr'.
# The next step loops through each of the fields beginning with 'Yr',
# and adds them to the FieldMap object.
for field in arcpy.ListFields(in_features, 'Yr*'):
fm.addInputField(in_features, field.name)
# Set the merge rule to find the mean value of all fields in the
# FieldMap object.
fm.mergeRule = 'Mean'
# Set the properties of the output field.
out_field = fm.outputField
out_field.name = 'AvgAccidents'
out_field.aliasName = 'AvgAccidents'
fm.outputField = out_field
# Add the intersection field to the second FieldMap object.
fm1.addInputField(in_features, "Intersection")
# Add both FieldMap objects to the FieldMappings object.
fms.addFieldMap(fm)
fms.addFieldMap(fm1)
# Create the output feature class using the FieldMappings object.
arcpy.conversion.ExportFeatures(in_features, out_features, field_mapping=fms)