Show Navigation | Hide Navigation
You are here:
Geoprocessing > Using geoprocessing tools > Using the tool dialog

Using the field mapping control

Release 9.3
Last modified January 26, 2009
E-mail This Topic Printable Version Give Us Feedback

Print all topics in : "Using the tool dialog"


Related Topics

When merging several input datasets into a single output dataset, the field structure and contents are a consideration. Each input dataset will contain fields that also exist in other input datasets, as well as fields that are unique to only that dataset. How these fields are managed determines the field structure and content in the output dataset. The Field Mapping control allows you to define this output dataset field structure.

All input dataset fields will be mapped to the output dataset. When there is field duplication (based solely on name) between all the inputs, the output dataset field will be a combination of each occurrence. All unique input dataset fields (those not found in other input datasets) are also mapped to the output dataset.

It is possible for a field map's subfields to be of varying data types. In this case, the output field's data type is set to the data type of the first input dataset and all other subfields are cast to this type. For example, the first input field is text, and the second input field (of the same name) is double. The output data type will be text, and the values in the second input field will be cast (converted) to this type. There may be instances when casting is not possible and errors will be raised during execution that state where the problem is. For instance, a BLOB field can't be cast to any data type other than BLOB. Also, an alphanumeric field would have to be truncated (start point and end point stated) to remove the alphabetic portion of its values if the field is to be cast as numeric type.

Field mapping is displayed graphically in a catalog tree. All root (top-level) entries are the output dataset fields. You will see their names and their default output data types. The default output field data type is the same as the first input's data type.

Each root-level entry is expandable. When expanded, it will display all subfields from which data will be gathered to populate the output field. For each occurrence of a field (by name) in the input dataset, a subfield entry will appear, showing its source and its data type. The first input dataset's occurrence of a field will be the first to appear in the subfield list.

This is the default structure of the output dataset fields. You may, at any time, add or delete input datasets; add, delete, or rename output dataset fields; and add, delete, rename, or custom format subfields.


Modifying the default field mappings

The default field mapping structure can be modified at any time. Output fields can be added, deleted, or renamed. Subfields can also be added, deleted, or renamed; and in the case of text output fields, they may be formatted. In the field mapping tree view, context menus (accessed by right-clicking a selected field, subfield, or just in the white space) can be used to make these modifications.

The context menu for output fields has the following options: Add Input Field, Delete, Rename, and Properties. Add Input Field opens a dialog box that lists all input dataset fields. Choosing an available field adds it to the selected output field's subfield list.

Field map context menu and subsequent Add Output Field dialog
Delete removes the selected field from the output dataset, and Rename allows you to alter the output field's name.

The Properties option allows you to alter the selected field's properties. You can change the field's name, type, type properties, merge rule, and delimiter (if the Join merge rule is selected).

Field map properties dialog
The context menu for subfields has the following options: Delete and Format (text fields only). Delete removes the selected subfield. If the first subfield is the one deleted, the output field's data type will not change to reflect the new first position subfield. If you want to change the output field's data type, you must do so manually (Properties dialog box), or use the Reset option on the field mapping windows context menu.

The Format option allows you to alter the field width, start position, and end position, then have the changes applied to all the other subfields of the same name.
SUb field context menu and subsequent Format dialog
If the field width is decreased, the output row values will be truncated to fit. Truncation also occurs if the start point and endpoint values are altered. The Start Position value is the start point from which row values will be truncated. Row value widths start at zero.
Index (position) of row values
Values that are longer than the End Position value will be truncated at the specified point. For example, a text field with a row value of "environment," a width of 12, a start position of 3, and an end position of 7 would appear in the output field as "ironm".

The context menu of the field mapping pane (white space) has the following options: Add Output Field and Reset. Add Output Field allows you to add a new field. A secondary dialog box opens that allows you to alter the name, data type, data type properties, merge rule, and a delimiter (if the Join merge rule is selected).

Field Map windows context menu and subsequent Add Output Field dalog
The Reset option will set all output field properties back to the default. All modifications will be removed.


Merge rules

Each output field allows you to set certain properties such as name, type, and merge rule. The merge rules allow you to specify how values from two or more input fields (subfields) are merged into a single output value. Null values are excluded from all statistical calculations. There are several merge rules that you can use:




Setting the Field Map parameter at the Command Line

At the command line, field mapping can be done by entering a string value for the field map parameter of the tool or setting a variable that can be referenced by the field map parameter of the tool. With the first option, since the string can become complex with a large number of fields, formatting merge rules, and so on, it is recommended only for use in cases in which the field number is small, the number of subfields is limited, or there is little if any alteration to the fields required. For most uses of the field map parameter, it is suggested you declare a variable that can be referenced easily.

You can declare a variable at any time by right-clicking the command line window and choosing Variables on the context menu. This allows you to create a field mappings variable whose value can be defined by using a dialog box.

Alternatively, you can create a variable as you type the tool's syntax. Instead of entering a parameter value, right-click, choose Variables on the context menu , then use the dialog boxes. Once a variable has been created (using either method), you can reference it in the tool syntax by typing the variable's name, or by right-clicking and choosing Insert Variable on the context menu. Insert Variable will open a dialog box specific to that parameter.


Setting the Field Map parameter in ModelBuilder

In ModelBuilder, there are three ways to utilize field mapping: use a tool's dialog box to set the parameters, create a generic variable, or create a variable from a field map parameter.

First, any tool that has a field map parameter has that parameter exposed on its dialog box. You can open the dialog box and utilize it the same way as if you accessed the tool from the ArcToolbox window.

Second, the ModelBuilder window allows you to create generic, stand-alone variables by right-clicking in the window and choosing Create Variable. This opens a dialog box on which you choose the type of variable (in this case, field mappings). A model element is created and its dialog can be used to create the field mapping values.

Third, you can right-click on any tool that has a field map parameter and choose Make Variable > From Parameter > Field Map. A model element is created and its dialog box will display the output dataset's fields if at least one input dataset has been set.

Learn more about working with model variables

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.