FieldMap

Summary

The FieldMap object provides a field definition and a list of input fields taken from a set of tables or feature classes.

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, including 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 most direct 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. Modify this list by adding new fields or removing unwanted output fields. To alter a FieldMap object's outputField property, assign this property to a variable. Then change the variable's properties such as name and type, and reassign the outputField property to this variable.

Note:

Use this approach to modify the FieldMap object's outputField property; the property cannot be modified in place.

Syntax

 FieldMap ()

Properties

Property	Explanation	Data Type
inputFieldCount (Read Only)	The number of defined input fields.	Integer
joinDelimiter (Read and Write)	A string value that will be used to separate input values from the same table if the output field type is string and the mergeRule is Join.	String
mergeRule (Read and Write)	Specifies how values from two or more fields from the same input table will be merged into a single output value. First—The first input value will be used. Last—The last input value will be used. Join—The values will be merged using the delimiter value to separate the values (only valid if the output field type is text). Min—The smallest input value will be used (only valid if the output field type is numeric). Max—The largest input value will be used (only valid if the output field type is numeric). Mean—The mean will be used and is calculated using the input values (only valid if the output field type is numeric). Median—The median will be used and is calculated using the input values (only valid if the output field type is numeric). Sum—The sum will be used and is calculated using the input values (only valid if the output field type is numeric). StDev—The standard deviation will be used and is calculated using the input values (only valid if the output field type is numeric). Count—The number of values included in statistical calculations will be used. This counts each value except null values.	String
outputField (Read and Write)	The properties of the output field are either set or returned in a Field object.	Field

Method Overview

Method	Explanation
addInputField (table_dataset, field_name, {start_position}, {end_position})	Add an input field to the field map.
findInputFieldIndex (table_dataset, field_name)	Finds an input field from the field map.
getEndTextPosition (index)	Returns the end text position from the field map.
getInputFieldName (index)	Returns the name of an input field from the field map, based on the field's index position.
getInputTableName (index)	Returns the name of an input table from the field map, based on the table's index position.
getStartTextPosition (index)	Returns the start text position from the FieldMap object.
removeAll ()	Removes all values and creates an empty object.
removeInputField (index)	Removes an input field from the FieldMap object.
setEndTextPosition (index, end_position)	Sets the end text position for the field map.
setStartTextPosition (index, start_position)	Sets the start text position for the field map.

Methods

addInputField (table_dataset, field_name, {start_position}, {end_position})

Parameter	Explanation	Data Type
table_dataset	The table that will be added to the field map.	String
field_name	The input field name.	String
start_position	The start position of an input text value. (The default value is -1)	Integer
end_position	The end position of an input text value. (The default value is -1)	Integer

findInputFieldIndex (table_dataset, field_name)

Parameter	Explanation	Data Type
table_dataset	The table that will be added to the field map.	String
field_name	The field name.	String

Return Value

Data Type	Explanation
Integer	The index position of the field name.

getEndTextPosition (index)

Parameter	Explanation	Data Type
index	The index position.	Integer

Return Value

Data Type	Explanation
Integer	The end text position.

getInputFieldName (index)

Parameter	Explanation	Data Type
index	The index position.	Integer

Return Value

Data Type	Explanation
String	The input field name.

getInputTableName (index)

Parameter	Explanation	Data Type
index	The index position.	Integer

Return Value

Data Type	Explanation
String	The input table name.

getStartTextPosition (index)

Parameter	Explanation	Data Type
index	The index position.	Integer

Return Value

Data Type	Explanation
Integer	The start text position.

removeAll ()

removeInputField (index)

Parameter	Explanation	Data Type
index	The index position.	Integer

setEndTextPosition (index, end_position)

Parameter	Explanation	Data Type
index	The index position.	Integer
end_position	The end position of an input text value.	Integer

setStartTextPosition (index, start_position)

Parameter	Explanation	Data Type
index	The index position.	Integer
start_position	The start position of an input text value.	Integer

Code sample

FieldMap example

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 by creating a new variable.
type_field = fm_type.outputField
type_field.name = 'Veg_Type'
# Set the new variable back into the field map's outputField.
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)

FieldMap example 2

This sample illustrates using FieldMap objects to merge fields using the ExportFeatures function. 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 by creating a new variable.
out_field = fm.outputField
out_field.name = 'AvgAccidents'
out_field.aliasName = 'AvgAccidents'
# Set the new variable back into the field map's outputField
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)