追加 (数据管理工具)

汇总

将多个输入数据集追加到现有目标数据集，或更新现有目标数据集。输入数据集可以是要素类、表格、shapefile、栅格、注记或尺寸注记要素类。输入也可能是托管要素服务。

要将输入数据集合并到新的输出数据集中，请使用合并工具。

插图

追加工具图示

用法

使用该工具，可将多个数据集中的新要素或其他数据添加至现有数据集。该工具可将点、线、面要素类、表、栅格、注记要素类或尺寸要素类追加到现有的相同类型数据集中。例如，您可以将多个表追加到现有表，或者可以将多个栅格追加到现有栅格数据集，但无法将线要素类追加到点要素类。
可使用字段映射参数控制如何将输入数据集字段中的属性信息传输到目标数据集。仅当为字段匹配类型参数指定使用字段映射协调字段差异时，才可使用字段映射参数。
使用字段映射参数将输入数据集中的字段映射或匹配到目标数据集中的字段。
- 使用操作确定将如何将输入数据集中的一个或多个字段的值映射到目标数据集中的单个字段。
- 可用的操作包括第一个、最后一个、串连、求和、平均值、中位数、众数、最小值、最大值、标准差和计数。
- 当使用串连操作时，可以指定分隔符，例如逗号或其他字符。单击分隔符文本框的开始部分以添加分隔符。
- 单个输入值不支持标准差选项。
- 使用导出选项将字段映射另存为 .fieldmap 文件。
- 使用加载选项加载 .fieldmap 文件。文件中指定的要素图层或数据集必须与工具中使用的数据集相匹配。否则，将重置字段映射参数。
- 对于文本源字段，使用分割文本按钮，可以选择从输入值中提取到目标字段的字符。要访问分割文本按钮，需将鼠标悬停在输入字段列表中的文本字段上，然后指定起始和结束字符位置。
- 还可以在 Python 脚本中映射字段。
在 Python 中，当使用 field_mapping 参数的 FieldMappings 对象时，首先从目标数据集添加字段，如下面的代码所示。输入字段映射到目标字段的模式。当首先添加输入字段时，字段映射可能会重置或出现意外行为。
```
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(target)
fieldmappings.addTable(input)
```
向目标数据集添加要素时，此工具不会打断要素。输入要素类和目标要素类中的所有要素都将在追加后保持原样，即使出现要素相互叠置情况也是如此。要合并或打断要素几何，请使用联合工具。
如果字段匹配类型参数设置为输入字段必须与目标字段匹配，则输入数据集方案必须与目标数据集方案相匹配，才能追加要素。

如果字段匹配类型参数设置为使用字段映射协调字段差异，则方案无需匹配。不会将与目标数据集字段不匹配的输入数据集字段映射到目标数据集，除非在字段映射参数中设置了映射。目标数据集中未映射到输入数据集字段的字段将包含空值。

如果字段匹配类型参数设置为如果方案不匹配，则跳过并发出警告，则输入数据集方案必须与目标数据集方案相匹配，才能追加要素。如果输入数据集包含的一些字段与目标数据集中的字段不匹配，则输入数据集将被忽略。
追加行的数量显示在工具消息中，并由追加的行计数输出返回。
由于输入数据集的数据已写入具有预定义方案的现有目标数据集中，因此无法使用字段映射参数在目标数据集中添加或移除字段。
可以使用此工具通过同一操作在目标数据集中插入新记录并更新现有记录（相当于 UPSERT 数据库操作）。使用要更新的匹配字段参数，来指定要匹配到目标数据集中的字段的输入数据集字段。对于具有匹配字段值的记录，目标记录中的任何字段都将使用输入记录中同名字段的值进行更新。具有匹配字段的已更新行的数量将显示在工具消息中，并由更新的行计数输出返回。如果已选中更新几何参数，则将更新几何。
输入和目标数据集可能具有不同的空间参考。在这种情况下，该工具会将输入要素投影到目标的坐标系。为了获得最佳结果，需使用地理变换环境指定适当的地理变换。如果目标数据集是地图图层，则该工具可能应用默认变换。 Python 中无默认变换。
此工具不执行边匹配，即不会对要素的几何进行调整。
可将地图图层用作输入数据集参数值。如果图层具有选定内容，则将使用所选记录（要素或表行）。
在工具中，无法使用具有相同名称的多个输入图层。而是使用地理处理窗格上的浏览按钮，浏览到每个输入数据集值的完整路径。
如果输入数据集和目标数据集具有相同的名称，则工具的性能将会降低。
要使用子类型参数，目标数据集必须已定义子类型字段且已分配子类型代码。在子类型参数中，提供子类型描述以将该子类型分配给已追加到目标数据集中的所有新数据。
使用强制域参数强制执行目标数据集中字段的属性域。选中此参数后，工具将遵循目标数据集中定义的域值。不符合这些属性域值的输入字段中的数据将作为空值插入。
以下为更新目标数据集字段的相关内容：
- 使用此工具通过同一操作在目标数据集中插入新记录并更新现有记录（相当于 UPSERT 数据库操作）。使用要更新的匹配字段参数，来指定要匹配到目标数据集中的字段的输入数据集字段。
- 默认情况下，对于包含匹配字段值的记录，使用输入中的值更新目标记录的字段（如果它们的字段名称相同）。具有匹配字段的已更新行的数量将显示在工具消息中，并由派生的更新的行计数参数返回。
- 候选字段参数可用于选择性地在目标数据集中更新或插入字段。例如，对于包含名为 f1、f2、f3 和 f4 的字段的目标数据集，可以指定仅更新目标行的 f3 和 f4 字段。插入时仅插入 f3 和 f4 字段。
- 如果已选中更新几何参数，则将更新几何。
- 要在目标数据集中仅更新几何且不更新属性字段，请确保选中了更新几何参数，且在候选字段参数中仅指定了 Shape 字段。如果目标数据集是要素服务，请参阅下方用法说明部分了解详细信息。
- 跳过选项参数具有以下用于控制更新行和插入行行为的选项：
  - 不跳过更新或插入—在目标数据集中更新所有具有匹配字段的行，并插入输入数据集中所有不匹配行。
  - 跳过不匹配行的插入（仅更新）—在目标数据集中更新所有具有匹配字段的行。不插入输入数据集中的不匹配行。
  - 跳过匹配行的更新（仅插入）—在目标数据集中不更新任何具有匹配字段的行。仅插入输入数据集中的不匹配行。
以下为要素服务的相关内容：
- 此工具可直接用于后端数据存储、服务器或 Web 要素图层的数据库，以获得最佳性能。对于引用地理数据库的要素服务，可以使用数据库连接直接将大规模数据加载至基础数据库。对于 ArcGIS Enterprise 上的托管服务，请通过要素图层项目页面或 ArcGIS REST API 使用 append 操作。
- 对于 ArcGIS Online 和 ArcGIS Enterprise 上的托管服务，当 supportAppend 属性为 true 时，管理员和服务所有者可以将此工具与 ArcGIS REST API 配合使用，以获得最佳性能。必须为非管理员用户启用要素服务追加功能，才能将此工具与 ArcGIS REST API 一起使用。对于 ArcGIS Enterprise 托管要素图层，必须启用 Uploads 功能。
- 仅当目标数据集支持要素服务追加功能时才支持优化要素服务的性能参数。当选中此参数时，该工具将执行以下操作：
  - 该工具将使用 ArcGIS REST API 以获得最佳性能。
  - 将输入数据集参数限制为一个数据集。
  - 不支持表达式和强制域参数。
  - 将要更新的匹配字段参数限制为一对匹配字段。
  - 将所有更新和插入操作都计入输出的追加的行计数值中。
- 当此工具在现有编辑会话中运行或打开启用撤消切换按钮时，将忽略优化要素服务的性能参数。
- 如果选中优化要素服务的性能参数，并且要更新的匹配字段参数值具有匹配 Global ID 字段，则将保留全局 ID 值。如果未包含 Global ID 字段，则将插入所有输入行并分配新的全局 ID 值。
- 要仅更新目标数据集的几何，请选中更新几何参数，并确保候选字段参数仅包含匹配字段的名称。例如，如果要更新的匹配字段参数值为 globalid 字段，则候选字段参数应仅包含 globalid 字段。

标注	说明	数据类型
输入数据集	包含将追加到目标数据集的数据的输入数据集。输入数据集可以是点、线、面要素类、表、栅格、注记要素类或尺寸要素类。可将表和要素类组合起来。如果将要素类追加到表，则将传递属性，但不会移除要素。如果将表追加到要素类中，则输入表中的行将具有空几何。	Table View; Raster Layer
目标数据集	将追加输入数据集数据的现有数据集。	Table View; Raster Layer
字段匹配类型（可选）	指定输入数据集的字段是否必须与目标数据集的字段匹配才能追加数据。输入字段必须与目标字段匹配—输入数据集的字段必须与目标数据集的字段相匹配。如果字段不匹配，将返回错误。这是默认设置。使用字段映射协调字段差异—输入数据集的字段不需要与目标数据集的字段相匹配。不会将与目标数据集字段不匹配的输入数据集字段映射到目标数据集，除非在字段映射参数中显式设置了映射。如果方案不匹配，则跳过并发出警告—输入数据集的字段必须与目标数据集的字段相匹配。如果某个输入数据集包含的字段与目标数据集不匹配，则输入数据集将被忽略，并且将发出一条警告消息。	String
字段映射（可选）	字段映射参数用于控制将字段从输入数据集传输或映射到目标数据集。仅当将字段匹配类型参数设置为使用字段映射协调字段差异时，才可使用此参数。由于输入数据集追加到的现有目标数据集具有预定义字段，因此无法在字段映射中添加、移除、重新排序或更改字段属性。字段映射可以用于将一个或多个输入字段的值合并为单个输出字段。	Field Mappings
子类型（可选）	将分配给追加到目标数据集的所有新数据的子类型描述。	String
表达式（可选）	用于选择输入数据集记录子集的 SQL 表达式。如果指定了多个输入数据集，将使用表达式对它们进行评估。如果没有与输入数据集表达式匹配的记录，将不会向目标数据集追加该数据集的记录。有关 SQL 语法的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。	SQL Expression
要更新的匹配字段（可选）	用于匹配到目标数据集的输入数据集字段。如果这些字段的值匹配，则将使用输入数据集的记录更新目标数据集的相应记录。值表列： Target Fields—The fields from the target dataset that will be matched. Input Fields—The fields from the input dataset that will be matched.	Value Table
更新几何（可选）	指定当 `match_fields` 参数字段值相匹配时，目标数据集中的几何是否将使用输入数据集中的几何进行更新。选中—当 `match_fields` 参数字段值相匹配时，将更新目标数据集中的几何。未选中—不更新几何。这是默认设置。	Boolean
强制域（可选）	指定是否将强制使用目标的字段属性域。选中—将强制使用目标的字段属性域。如果输入字段值超出目标字段属性域定义范围，则将插入记录，但输入字段将为空。如果指定了匹配的更新字段，则将不会更新目标字段。工具消息将包含一条警告消息，用于标识无法写入输出字段值的行。未选中—将不会强制使用目标的字段属性域。这是默认设置。	Boolean
优化要素服务的性能（可选）	指定当目标数据集为 ArcGIS Online 或 ArcGIS Enterprise 要素服务时是否将优化性能。仅当目标数据集支持优化时，此参数才有效。选中—当目标数据集是启用了追加功能的要素服务时，工具的性能将得到优化。当受目标要素服务支持时，该项为默认值。优化使用服务器端处理，其中输入数据被发送到要素服务追加 API 并异步加载到数据集中。选中此参数时，不再支持表达式和强制域参数，且要更新的匹配字段参数仅限使用一个输入数据集和一对字段。未选中—当目标是要素服务时，工具的性能将不会优化。	Boolean
候选字段（可选）	将在目标数据集中更新或插入的字段。如果要在目标数据集中更新或插入字段子集，请使用此参数。当插入新记录时，该列表中不包含的字段将为空值。	Field
跳过选项（可选）	当指定要更新的匹配字段参数时，指定是否跳过更新和插入。不跳过更新或插入—将更新包含匹配字段的目标行，并在目标数据集中插入不包含匹配的输入行。这是默认设置。跳过不匹配行的插入（仅更新）—将不在目标数据集中插入不包含匹配字段的输入行。该选项仅更新包含匹配字段的目标数据集中的行。跳过匹配行的更新（仅插入）—将不更新输入数据集中包含匹配字段的目标行。该选项仅插入输入数据集中不包含匹配字段的新行。	String

派生输出

标注	说明	数据类型
更新的目标数据集	已更新的目标数据集。	Table View; Raster Layer
追加的行计数	追加到目标数据集的行数。当选中优化要素服务的性能参数，并且指定了要更新的匹配字段参数值，将计入所有更新和插入操作。	Long
更新的行计数	目标数据集中更新的行数。选中优化要素服务的性能参数时，将不会为目标要素服务数据集提供更新的行计数。	Long

标注

说明

数据类型

更新的目标数据集

已更新的目标数据集。

Table View; Raster Layer

追加的行计数

追加到目标数据集的行数。

当选中优化要素服务的性能参数，并且指定了要更新的匹配字段参数值，将计入所有更新和插入操作。

Long

更新的行计数

目标数据集中更新的行数。

选中优化要素服务的性能参数时，将不会为目标要素服务数据集提供更新的行计数。

Long

arcpy.management.Append(inputs, target, {schema_type}, {field_mapping}, {subtype}, {expression}, {match_fields}, {update_geometry}, {enforce_domains}, {feature_service_mode}, {candidate_fields}, {skip_options})

名称	说明	数据类型
inputs [inputs,...]	包含将追加到目标数据集的数据的输入数据集。输入数据集可以是点、线、面要素类、表、栅格、注记要素类或尺寸要素类。可将表和要素类组合起来。如果将要素类追加到表，则将传递属性，但不会移除要素。如果将表追加到要素类中，则输入表中的行将具有空几何。	Table View; Raster Layer
target	将追加输入数据集数据的现有数据集。	Table View; Raster Layer
schema_type （可选）	指定输入数据集的字段是否必须与目标数据集的字段匹配才能追加数据。 `TEST`—输入数据集的字段必须与目标数据集的字段相匹配。如果字段不匹配，将返回错误。这是默认设置。 `NO_TEST`—输入数据集的字段不需要与目标数据集的字段相匹配。不会将与目标数据集字段不匹配的输入数据集字段映射到目标数据集，除非在字段映射参数中显式设置了映射。 `TEST_AND_SKIP`—输入数据集的字段必须与目标数据集的字段相匹配。如果某个输入数据集包含的字段与目标数据集不匹配，则输入数据集将被忽略，并且将发出一条警告消息。	String
field_mapping （可选）	字段映射参数用于控制将字段从输入数据集传输或映射到目标数据集。仅当 `schema_type` 参数设置为 `NO_TEST` 时，才能使用该参数。由于输入数据集追加到的现有目标数据集具有预定义字段，因此无法在字段映射中添加、移除、重新排序或更改字段属性。字段映射可以用于将一个或多个输入字段的值合并为单个输出字段。在 Python 中，使用 `FieldMappings` 类来定义该参数。	Field Mappings
subtype （可选）	将分配给追加到目标数据集的所有新数据的子类型描述。	String
expression （可选）	用于选择输入数据集记录子集的 SQL 表达式。如果指定了多个输入数据集，将使用表达式对它们进行评估。如果没有与输入数据集表达式匹配的记录，将不会向目标数据集追加该数据集的记录。有关 SQL 语法的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。	SQL Expression
match_fields [[target_field, input_field],...] （可选）	用于匹配到目标数据集的输入数据集字段。如果这些字段的值匹配，则将使用输入数据集的记录更新目标数据集的相应记录。值表列： `Target Fields`—The fields from the target dataset that will be matched. `Source Fields`—The fields from the input dataset that will be matched.	Value Table
update_geometry （可选）	指定当 `match_fields` 参数字段值相匹配时，目标数据集中的几何是否将使用输入数据集中的几何进行更新。 `UPDATE_GEOMETRY`—当 `match_fields` 参数字段值相匹配时，将更新目标数据集中的几何。 `NOT_UPDATE_GEOMETRY`—不更新几何。这是默认设置。	Boolean
enforce_domains （可选）	指定是否将强制使用目标的字段属性域。 `ENFORCE_DOMAINS`—将强制使用目标的字段属性域。如果输入字段值超出目标字段属性域定义范围，则将插入记录，但输入字段将为空。如果指定了匹配的更新字段，则将不会更新目标字段。工具消息将包含一条警告消息，用于标识无法写入输出字段值的行。 `NO_ENFORCE_DOMAINS`—将不会强制使用目标的字段属性域。这是默认设置。	Boolean
feature_service_mode （可选）	指定当目标数据集为 ArcGIS Online 或 ArcGIS Enterprise 要素服务时是否将优化性能。仅当目标数据集支持优化时，此参数才有效。 `USE_FEATURE_SERVICE_MODE`—当目标数据集是启用了追加功能的要素服务时，工具的性能将得到优化。这是默认设置。优化使用服务器端处理，其中输入数据被发送到要素服务追加 API 并异步加载到数据集中。当参数值为 `USE_FEATURE_SERVICE_MODE` 时，不再支持 `expression` 和 `enforce_domains` 参数，且 `match_fields` 参数仅限使用一个输入数据集和一对字段。 `NO_FEATURE_SERVICE_MODE`—当目标是要素服务时，工具的性能将不会优化。	Boolean
candidate_fields [candidate_fields,...] （可选）	将在目标数据集中更新或插入的字段。如果要在目标数据集中更新或插入字段子集，请使用此参数。当插入新记录时，该列表中不包含的字段将为空值。	Field
skip_options [skip_options,...] （可选）	当指定 `match_fields` 参数时，指定是否跳过更新和插入。 `NO_SKIP`—将更新包含匹配字段的目标行，并在目标数据集中插入不包含匹配的输入行。这是默认设置。 `SKIP_INSERT_IF_UNMATCHED`—将不在目标数据集中插入不包含匹配字段的输入行。该选项仅更新包含匹配字段的目标数据集中的行。 `SKIP_UPDATE_IF_MATCHED`—将不更新输入数据集中包含匹配字段的目标行。该选项仅插入输入数据集中不包含匹配字段的新行。	String

派生输出

名称说明数据类型

名称	说明	数据类型
output	已更新的目标数据集。	Table View; Raster Layer
appended_row_count	追加到目标数据集的行数。当 `feature_service_mode` 参数值为 `USE_FEATURE_SERVICE_MODE` 且指定了 `match_fields` 参数值时，将计入所有更新和插入操作。	Long
updated_row_count	目标数据集中更新的行数。当 `feature_service_mode` 参数值为 `USE_FEATURE_SERVICE_MODE` 时，将不会为目标要素服务数据集提供更新的行计数。	Long

output

已更新的目标数据集。

Table View; Raster Layer

appended_row_count

追加到目标数据集的行数。

当 feature_service_mode 参数值为 USE_FEATURE_SERVICE_MODE 且指定了 match_fields 参数值时，将计入所有更新和插入操作。

Long

updated_row_count

目标数据集中更新的行数。

当 feature_service_mode 参数值为 USE_FEATURE_SERVICE_MODE 时，将不会为目标要素服务数据集提供更新的行计数。

Long

代码示例

Append 示例 1（Python 窗口）

以下 Python 窗口脚本演示了如何在即时模式下使用 Append 函数。

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.management.Append(["north.shp", "south.shp", "east.shp", "west.shp"],
                        "wholecity.shp", "TEST")

Append 示例 2（Python 窗口）

以下 Python 窗口脚本演示了如何在即时模式下使用具有 match_fields 和 update_geometry 参数的 Append 函数。

import arcpy
arcpy.env.workspace = "C:/data/zoning.gdb"
arcpy.management.Append("Zoning_update_2040", "Zoning_2020", "TEST",
                        match_fields=[["ZONEID", "ZONEID"]], update_geometry="UPDATE_GEOMETRY")

Append 示例 3（独立脚本）

以下脚本演示了如何使用 Append 函数。

# Name: Append.py
# Description: Use the Append tool to combine several polygon feature classes

# Import system modules
import arcpy
import os

# Set environment settings
arcpy.env.workspace = "C:/data/towns.gdb"

# Set local variables
outLocation = "C:/data/output.gdb"
outName = "MA_towns.shp"
schemaType = "NO_TEST"
fieldMappings = ""
subtype = ""

# Process: Append to an existing "amherst" polygon feature class
target = os.path.join(outLocation, "amherst")

# All polygon FCs in the workspace are MA town FCs, you want to append these
# to the target FC. The list will resemble ["amherst", "hadley", "pelham",
# "coldspring"]

fcList = arcpy.ListFeatureClasses("", "POLYGON")

# Create FieldMappings object to manage merge output fields
fieldMappings = arcpy.FieldMappings()

# Add the target table to the field mappings class to set the schema
fieldMappings.addTable(target)

# Add input fields for the town name to TOWNNAME field that matches the
# target dataset since each input dataset has a different field name for
# this info
fldMap = arcpy.FieldMap()
fldMap.addInputField("amherst", "TOWNNAME")
fldMap.addInputField("hadley", "NAME")
fldMap.addInputField("pelham", "TOWN_NAME")
fldMap.addInputField("coldspring", "TOWN")

# Set name of new output field "TOWNNAME"
townName = fldMap.outputField
townName.name, townName.aliasName, townName.type = "TOWNNAME", "TOWNNAME", "TEXT"
fldMap.outputField = townName

# Add output field to field mappings object
fieldMappings.addFieldMap(fldMap)

# Do the same for the POPULATION field
fldMap = arcpy.FieldMap()
fldMap.addInputField("amherst","POPULATION")
fldMap.addInputField("hadley","POP")
fldMap.addInputField("pelham","POP_2010")
fldMap.addInputField("coldspring","POP")

# Set name of new output field "POPULATION"
pop = fldMap.outputField
pop.name, pop.aliasName, pop.type = "POPULATION", "POPULATION", "LONG"
fldMap.outputField = pop

# Add output field to field mappings object
fieldMappings.addFieldMap(fldMap)

# Process: Append the feature classes to the target feature class
arcpy.management.Append(fcList, os.path.join(outLocation, "amherst"), schemaType,
                        fieldMappings, subtype)

环境

范围, 当前工作空间, 保留全局 ID, 维护附件, 地理变换

特殊情况

保留全局 ID

For the Append tool, this environment will only preserve Global ID values from the input dataset if the target Global ID field has a unique index. If the target Global ID field does not have a unique index, the tool may fail. To add a unique index to a Global ID field, use the Add Attribute Index tool.

If the target dataset contains a Global ID field and the input data does not, running the Append tool with this environment set to True will automatically generate new Global ID values for inserted rows.

This environment is ignored for target feature services. To preserve Global IDs for feature services that support optimization, check the Optimize performance for feature services parameter and specify GlobalID as the match fields in the Matching Fields for Update parameter.

许可信息

基本: 是
标准: 是
高级: 是

追加 (数据管理工具)

汇总

插图

用法

参数

派生输出

环境

特殊情况

许可信息

相关主题