Add Field (Data Management)

Summary

Adds a new field to a table or the table of a feature class or feature layer, as well as to rasters with attribute tables.

Usage

    Caution:

    This tool modifies the input data. See Tools that modify or update the input data for more information and strategies to avoid undesired data changes.

  • For shapefiles and dBase tables, if field type defines a character, blanks are inserted for each record. If field type defines a numeric item, zeros are inserted for each record.

  • The Field Length parameter is only applicable to fields of type text. If no field length is provided, a length of 255 will be used.

  • For geodatabases, if field type defines a character or number, <null> is inserted into each record if the Field supports null values parameter is checked.

  • A nonnullable field cannot be added to a nonempty geodatabase feature class or table.

  • A shapefile does not support aliases for fields, so you cannot add a field alias to a shapefile.

  • You can use an existing domain from a feature class in a geodatabase for the Field Domain parameter value. The name of an existing domain must be provided. Providing an invalid domain name or value will not cause the tool to fail, but the invalid name or value will be ignored and no domain will be set for the field.

  • The precision and scale of a field represent the maximum precision and size of data that can be stored in the field. The precision represents the number of digits that can be stored in the field, and the scale represents the number of decimal places for float and double fields. For example, for a value of 54.234, the scale is 3 and the precision is 5.

    Note:

    Field precision and scale are not supported in a file geodatabase feature class or table. If you provide a value for precision or scale, it will be ignored.

    For other database types, use the following guidelines to choose the correct field type for a given precision and scale:

    • When you create a float or double field and specify a precision and scale, if the precision is greater than 6, use a double; otherwise, use a float.
    • For a field with a scale of 0, use a long or short integer field type. When creating a long integer field, specify a precision of 10 or less, or the field may be created as a double.

    Learn more about numeric field types

  • Required fields are permanent and cannot be deleted. To allow for deletion at a later time, set the field so it is not required (the default).

  • A field of type raster allows you to include a raster image as an attribute. It is stored in or alongside the geodatabase. This is helpful when an image is the best way to describe a feature. Precision, scale, and length cannot be set for fields of type raster.

Parameters

LabelExplanationData Type
Input Table

The input table where the specified field will be added. The field will be added to the existing input table and will not create a new output table.

Fields can be added to feature classes in geodatabases, shapefiles, coverages, stand-alone tables, raster catalogs, rasters with attribute tables, and layers.

Mosaic Layer; Raster Layer; Table View
Field Name

The name of the field that will be added to the input table.

String
Field Type

Specifies the field type of the new field.

  • Short (16-bit integer)The field type will be short. Short fields support whole numbers between -32,768 and 32,767.
  • Long (32-bit integer)The field type will be long. Long fields support whole numbers between -2,147,483,648 and 2,147,483,647.
  • Big integer (64-bit integer)The field type will be big integer. Big integer fields support whole numbers between -(253) and 253.
  • Float (32-bit floating point)The field type will be float. Float fields support fractional numbers between -3.4E38 and 1.2E38.
  • Double (64-bit floating point)The field type will be double. Double fields support fractional numbers between -2.2E308 and 1.8E308.
  • TextThe field type will be text. Text fields support a string of characters.
  • DateThe field type will be date. Date fields support date and time values.
  • Date (high precision)The field type will be high precision date. High precision date fields support date and time values with millisecond time.
  • Date onlyThe field type will be date only. Date only fields support date values with no time values.
  • Time onlyThe field type will be time only. Time only fields support time values with no date values.
  • Timestamp offsetThe field type will be timestamp offset. Timestamp offset fields support a date, time, and offset from a UTC value.
  • BLOB (binary data)The field type will be BLOB. BLOB fields support data stored as a long sequence of binary numbers. You need a custom loader or viewer or a third-party application to load items into a BLOB field or view the contents of a BLOB field.
  • GUID (globally unique identifier)The field type will be GUID. GUID fields store registry-style strings consisting of 36 characters enclosed in curly brackets.
  • Raster The field type will be raster. Raster fields can store raster data in or alongside the geodatabase. All ArcGIS software-supported raster dataset formats can be stored, but it is recommended that only small images be used.
String
Field Precision
(Optional)

The number of digits that can be stored in the field. All digits are counted regardless of which side of the decimal they are on.

This parameter is only applicable to numeric field types.

If the input table is in a file geodatabase, the field precision value will be ignored.

Long
Field Scale
(Optional)

The number of decimal places stored in a field.

This parameter is only applicable to fields of type float or double.

If the input table is in a file geodatabase, the field scale value will be ignored.

Long
Field Length
(Optional)

The length of the field. This sets the maximum number of allowable characters for each record of the field. If no field length is provided, a length of 255 will be used.

This parameter is only applicable to fields of type text.

Long
Field Alias
(Optional)

The alternate name for the field. This name is used to describe cryptic field names. This parameter only applies to geodatabases.

String
Field supports null values
(Optional)

Specifies whether the field can contain null values. Null values are different from zero or empty fields and are only supported for fields in a geodatabase.

  • Checked—The field can contain null values. This is the default.
  • Unchecked—The field cannot contain null values.
Boolean
Field is required
(Optional)

Specifies whether the field being created is a required field for the table. Required fields are only supported in a geodatabase.

  • Checked—The field is a required field. Required fields are permanent and cannot be deleted.
  • Unchecked—The field is not a required field. This is the default.
Boolean
Field Domain
(Optional)

Constrains the values allowed in any particular attribute for a table, feature class, or subtype in a geodatabase. You must specify the name of an existing domain for it to be applied to the field.

String

Derived Output

LabelExplanationData Type
Updated Input Table

The updated input table.

Table

arcpy.management.AddField(in_table, field_name, field_type, {field_precision}, {field_scale}, {field_length}, {field_alias}, {field_is_nullable}, {field_is_required}, {field_domain})
NameExplanationData Type
in_table

The input table where the specified field will be added. The field will be added to the existing input table and will not create a new output table.

Fields can be added to feature classes in geodatabases, shapefiles, coverages, stand-alone tables, raster catalogs, rasters with attribute tables, and layers.

Mosaic Layer; Raster Layer; Table View
field_name

The name of the field that will be added to the input table.

String
field_type

Specifies the field type of the new field.

  • SHORTThe field type will be short. Short fields support whole numbers between -32,768 and 32,767.
  • LONGThe field type will be long. Long fields support whole numbers between -2,147,483,648 and 2,147,483,647.
  • BIGINTEGERThe field type will be big integer. Big integer fields support whole numbers between -(253) and 253.
  • FLOATThe field type will be float. Float fields support fractional numbers between -3.4E38 and 1.2E38.
  • DOUBLEThe field type will be double. Double fields support fractional numbers between -2.2E308 and 1.8E308.
  • TEXTThe field type will be text. Text fields support a string of characters.
  • DATEThe field type will be date. Date fields support date and time values.
  • DATEHIGHPRECISIONThe field type will be high precision date. High precision date fields support date and time values with millisecond time.
  • DATEONLYThe field type will be date only. Date only fields support date values with no time values.
  • TIMEONLYThe field type will be time only. Time only fields support time values with no date values.
  • TIMESTAMPOFFSETThe field type will be timestamp offset. Timestamp offset fields support a date, time, and offset from a UTC value.
  • BLOBThe field type will be BLOB. BLOB fields support data stored as a long sequence of binary numbers. You need a custom loader or viewer or a third-party application to load items into a BLOB field or view the contents of a BLOB field.
  • GUIDThe field type will be GUID. GUID fields store registry-style strings consisting of 36 characters enclosed in curly brackets.
  • RASTER The field type will be raster. Raster fields can store raster data in or alongside the geodatabase. All ArcGIS software-supported raster dataset formats can be stored, but it is recommended that only small images be used.

Although the Field object's type property values are not an exact match for the keywords used by the Add Field tool's field_type parameter, all of the Field object's type values can be used as input to this parameter. The different field types are mapped as follows: Integer to LONG, String to TEXT, and SmallInteger to SHORT.

String
field_precision
(Optional)

The number of digits that can be stored in the field. All digits are counted regardless of which side of the decimal they are on.

This parameter is only applicable to numeric field types.

If the input table is in a file geodatabase, the field precision value will be ignored.

Long
field_scale
(Optional)

The number of decimal places stored in a field.

This parameter is only applicable to fields of type float or double.

If the input table is in a file geodatabase, the field scale value will be ignored.

Long
field_length
(Optional)

The length of the field. This sets the maximum number of allowable characters for each record of the field. If no field length is provided, a length of 255 will be used.

This parameter is only applicable to fields of type text.

Long
field_alias
(Optional)

The alternate name for the field. This name is used to describe cryptic field names. This parameter only applies to geodatabases.

String
field_is_nullable
(Optional)

Specifies whether the field can contain null values. Null values are different from zero or empty fields and are only supported for fields in a geodatabase.

  • NULLABLEThe field can contain null values. This is the default.
  • NON_NULLABLEThe field cannot contain null values.
Boolean
field_is_required
(Optional)

Specifies whether the field being created is a required field for the table. Required fields are only supported in a geodatabase.

  • NON_REQUIREDThe field is not a required field. This is the default.
  • REQUIREDThe field is a required field. Required fields are permanent and cannot be deleted.
Boolean
field_domain
(Optional)

Constrains the values allowed in any particular attribute for a table, feature class, or subtype in a geodatabase. You must specify the name of an existing domain for it to be applied to the field.

String

Derived Output

NameExplanationData Type
out_table

The updated input table.

Table

Code sample

AddField example 1 (Python window)

The following Python window script demonstrates how to use the AddField function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/airport.gdb"
arcpy.management.AddField("schools", "ref_ID", "LONG", 9, "", "", "refcode", 
                          "NULLABLE", "REQUIRED")
AddField example 2 (stand-alone script)

The following stand-alone script demonstrates how to use the AddField function.

# Name: AddField_Example2.py
# Description: Add a pair of new fields to a table
 
# Import system modules
import arcpy
 
# Set environment settings
arcpy.env.workspace = "C:/data/airport.gdb"
 
# Set local variables
inFeatures = "schools"
fieldName1 = "ref_ID"
fieldPrecision = 9
fieldAlias = "refcode"
fieldName2 = "status"
fieldLength = 10

# Run AddField twice for two new fields
arcpy.management.AddField(inFeatures, fieldName1, "LONG", fieldPrecision,
                          field_alias=fieldAlias, field_is_nullable="NULLABLE")

arcpy.management.AddField(inFeatures, fieldName2, "TEXT", 
                          field_length=fieldLength)

Environments

Related topics