Alter Field (Data Management)

Summary

Renames fields and field aliases or alters field properties.

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.

  • This tool allows you to rename fields or field aliases for a geodatabase table or feature class.

  • You can use this tool to modify the field alias of a field in a table or view that has been registered with the geodatabase.

  • If the input field is a required field, only the field alias can be modified.

Parameters

LabelExplanationData Type
Input Table

The input geodatabase table or feature class that contains the field that will be altered.

Table View; Raster Layer; Mosaic Layer
Field Name

The name of the field that will be altered. If the field is a required field, only the field alias will be altered.

Field
New Field Name
(Optional)

The new name for the field.

String
New Field Alias
(Optional)

The new field alias for the field.

String
New Field Type
(Optional)

Specifies the new field type for the field. This parameter is only applicable if the input table is empty (does not contain records).

  • 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 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 value.
  • Timestamp offsetThe field type will be timestamp offset. Timestamp offset fields support a date, time and offset from 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
New Field Length
(Optional)

The new length of the field. This sets the maximum number of allowable characters for each record of the field. This parameter is only applicable to fields of type Text or Blob (binary data). If the table is empty, the field length can be increased or decreased. If the table is not empty, the length can only be increased from the current value.

Long
New Field IsNullable
(Optional)

Specifies whether the field can contain null values. Null values are only supported for fields in a geodatabase. This parameter is only applicable if the table is empty (does not contain records).

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

Specifies whether the alias for the input field will be cleared. The New Field Alias parameter value must be empty to clear the alias of the field.

  • Checked—The field alias will be cleared (set to null). The field alias parameter must be empty.
  • Unchecked—The field alias will not be cleared. This is the default.
Boolean

Derived Output

LabelExplanationData Type
Updated Input Table

The updated input table.

Table View; Raster Layer; Mosaic Layer

arcpy.management.AlterField(in_table, field, {new_field_name}, {new_field_alias}, {field_type}, {field_length}, {field_is_nullable}, {clear_field_alias})
NameExplanationData Type
in_table

The input geodatabase table or feature class that contains the field that will be altered.

Table View; Raster Layer; Mosaic Layer
field

The name of the field that will be altered. If the field is a required field, only the field alias will be altered.

Field
new_field_name
(Optional)

The new name for the field.

String
new_field_alias
(Optional)

The new field alias for the field.

String
field_type
(Optional)

Specifies the new field type for the field. This parameter is only applicable if the input table is empty (does not contain records).

  • 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.
  • 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 value.
  • TIMESTAMPOFFSETThe field type will be timestamp offset. Timestamp offset fields support a date, time and offset from 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.
String
field_length
(Optional)

The new length of the field. This sets the maximum number of allowable characters for each record of the field. This parameter is only applicable to fields of type TEXT or BLOB. If the table is empty, the field length can be increased or decreased. If the table is not empty, the length can only be increased from the current value.

Long
field_is_nullable
(Optional)

Specifies whether the field can contain null values. Null values are only supported for fields in a geodatabase. This parameter is only applicable if the input table is empty (does not contain records).

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

Specifies whether the alias for the input field will be cleared. The new_field_alias parameter must be empty to clear the alias of the field.

  • CLEAR_ALIASThe field alias will be cleared (set to null).
  • DO_NOT_CLEARThe field alias will not be cleared. This is the default.
Boolean

Derived Output

NameExplanationData Type
out_table

The updated input table.

Table View; Raster Layer; Mosaic Layer

Code sample

AlterField example 1 (Python window)

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

import arcpy
arcpy.management.AlterField(
    r'C:\Data\Garbo.gdb\Khyber', 'Elev', 'ELEVATION', 'Elevation in Metres')
AlterField example 2 (stand-alone script)

The following Python window script demonstrates how to use the AlterField function in a stand-alone script.

import arcpy

# Set workspace
arcpy.env.workspace = r'C:\Data\Garbo.gdb'

# Loop through feature classes looking for a field named 'elev'
fcList = arcpy.ListFeatureClasses()  # Get a list of feature classes
for fc in fcList:  # Loop through feature classes
    fieldList = arcpy.ListFields(fc)  # Get a list of fields for each feature class
    for field in fieldList:  # Lloop through each field
        if field.name.lower() == 'elev':  # Look for the name elev
            arcpy.management.AlterField(fc, field.name, 'ELEVATION', 'Elevation in Metres')
AlterField example 3 (stand-alone script)

The following Python window script demonstrates how to use the AlterField function on an empty feature class in a stand-alone script.

import arcpy

# Set local variables
in_table = "C:/Data/Garbo.gdb/trails"  # Note: empty feature class
field = "condition_rating"  # short int, non nullable field
new_field_name = "notes"
new_field_alias = "Comments on Trail Condition"
field_type = "TEXT"
field_length = 60
field_is_nullable = "NULLABLE"
clear_field_alias = "FALSE"

# Alter the properties of a non nullable, short data type field to become a text field
arcpy.management.AlterField(in_table,
                            field,
                            new_field_name,
                            new_field_alias,
                            field_type,
                            field_length,
                            field_is_nullable,
                            clear_field_alias)

Environments