Back to Top

FieldMappings

In this topic

  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample
Related topics
  1. Mapping input fields to output fields
  2. FieldMap

Summary

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.

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 FieldMap is used if the mergeRule value Join is specified. Any set of characters, such as a space, can be used as a delimiter. In the above example, 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. This list can be modified by adding new fields, altering the properties or contents of an output field, or removing any unwanted output fields.

Syntax

 FieldMappings  ()

Properties

PropertyExplanationData 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

MethodExplanation
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)

Restore or update the spatial reference object using a WKT string. The exportToString method can be used to export a WKT string representation of the spatial reference.

  • Using a WKT string with a horizontal coordinate system.
    # The following string is the WKT for the 
# Geographic Coordinate system "WGS 1984" (factory code=4326)
wkt = 'GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],\
              PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]];\
              -400 -400 1000000000;-100000 10000;-100000 10000;8.98315284119522E-09;\
              0.001;0.001;IsHighPrecision'

sr = arcpy.SpatialReference()
sr.loadFromString(wkt)
  • Using a WKT string with a horizontal and vertical coordinate system. Note that the vertical coordinate system is defined in the VERTCS section of the WKT.
    # The following string is the WKT for the 
# Geographic Coordinate system "WGS 1984" (factory code=4326), 
# with a vertical coordinate system "WGS 1984" (factory code=115700)

wkt = 'GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],\
              PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]],\
              VERTCS["WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],\
              PARAMETER["Vertical_Shift",0.0],PARAMETER["Direction",1.0],UNIT["Meter",1.0]];\
              -400 -400 1000000000;-100000 10000;-100000 10000;8.98315284119522E-09;\
              0.001;0.001;IsHighPrecision'

sr = arcpy.SpatialReference()
sr.loadFromString(wkt)

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)
ParameterExplanationData Type
field_map

The field map to add to the field mappings

FieldMap
addTable (table_dataset)
ParameterExplanationData Type
table_dataset

The table to add to the field mappings object.

String
exportToString ()
Return Value
Data TypeExplanation
String

The WKT string representation of the object. 

findFieldMapIndex (field_map_name)
ParameterExplanationData Type
field_map_name

Find the field map by name.

String
Return Value
Data TypeExplanation
Integer

The index position of the field map. 

getFieldMap (index)
ParameterExplanationData Type
index

The index position of the FieldMap object.

Integer
Return Value
Data TypeExplanation
FieldMap

The FieldMap object from the FieldMappings object. 

loadFromString (string)
ParameterExplanationData Type
string

The WKT string representation of the object.

String
removeAll ()
removeFieldMap (index)
ParameterExplanationData Type
index

The index position of the FieldMap.

Integer
replaceFieldMap (index, value)
ParameterExplanationData Type
index

The index position of the FieldMap object to be replaced.

Integer
value

The replacement FieldMap object.

FieldMap

Code sample

FieldMappings example

FieldMap objects are often used to merge similar datasets into one, all-encompassing dataset. In this example, the feature class Trees and the shapefile Plants.shp 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_file1 = 'data.gdb/Trees'
in_file2 = 'Plants.shp'
output_file = '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_file1, tree_type)
fm_type.addInputField(in_file2, plant_type)

fm_diam.addInputField(in_file1, tree_diam)
fm_diam.addInputField(in_file2, plant_diam)

# Set the output field properties for both FieldMap objects
type_name = fm_type.outputField
type_name.name = 'Veg_Type'
fm_type.outputField = type_name

diam_name = fm_diam.outputField
diam_name.name = 'Veg_Diam'
fm_diam.outputField = diam_name

# Add the FieldMap objects to the FieldMappings object
fms.addFieldMap(fm_type)
fms.addFieldMap(fm_diam)

# Merge the two feature classes
arcpy.Merge_management([in_file1, in_file2], output_file, fms)
FieldMappings example 2

This sample displays the option of using FieldMap objects to merge fields, using the FeatureClassToFeatureClass 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

# Set the workspace
arcpy.env.workspace = 'c:/base/data.gdb'

in_file = 'AccidentData'
out_file = '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' (from Yr2007 to Yr2012).
# 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_file, 'Yr*'):
    fm.addInputField(in_file, field.name)

# Set the merge rule to find the mean value of all fields in the
# FieldMap object
fm.mergeRule = 'Mean'

# Set properties of the output name.
f_name = fm.outputField
f_name.name = 'AvgAccidents'
f_name.aliasName = 'AvgAccidents'
fm.outputField = f_name

# Add the intersection field to the second FieldMap object
fm1.addInputField(in_file, "Intersection")

# Add both FieldMaps to the FieldMappings Object
fms.addFieldMap(fm)
fms.addFieldMap(fm1)

# Create the output feature class, using the FieldMappings object
arcpy.FeatureClassToFeatureClass_conversion(
    in_file, arcpy.env.workspace, out_file, field_mapping=fms)

Related topics

  • Mapping input fields to output fields
  • FieldMap

Feedback on this topic?

In this topic
  1. Summary
  2. Discussion
  3. Syntax
  4. Properties
  5. Method Overview
  6. Methods
  7. Code sample
Related topics
  1. Mapping input fields to output fields
  2. FieldMap