UpdateCursor—ArcGIS Pro

摘要

UpdateCursor 用于建立对从要素类或表返回的记录的读写访问权限。

返回一组迭代列表。列表中值的顺序与 field_names 参数指定的字段顺序相符。

了解有关使用游标访问数据的详细信息

说明

使用 for 循环可迭代更新游标。更新游标也支持 with 语句以重置迭代并帮助移除锁。但是，为了防止锁定所有内容，应考虑使用 del 语句来删除对象或将游标包含在函数中以使游标对象位于作用范围之外。

使用不同游标在同一个工作空间上开启同步插入或更新操作时，需要启动编辑会话。

以下列出了只能在编辑会话中编辑的一些数据集类型：

参与拓扑的要素类
参与几何网络的要素类
参与网络数据集的要素类
企业级地理数据库中的版本化数据集
一些带有类扩展的对象和要素类

在 Python 2 中，UpdateCursor 支持迭代器 next 方法，在循环外检索下一行。在 Python 3 中，可使用 Python 内置 next 函数执行等效操作。

注：

计算字段和计算字段工具也可以用于更新字段值。

注：

不支持在包含连接表的图层上使用 UpdateCursor。

语法

 UpdateCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation}, {explicit}, {spatial_filter}, {spatial_relationship}, {search_order})

参数	说明	数据类型
in_table	要素类、图层、表或表视图。	String
field_names [field_names,...]	字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。要访问输入表中的所有字段（BLOB 字段除外），可以使用星号 (*) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。不支持栅格字段。以令牌（如 OID@）取代字段名称可访问更多的信息： ANNO@—要素的 Annotation 对象。此选项仅对 ArcGIS Pro 注记要素类有效。 SHAPE@XY—一组要素的质心 x,y 坐标。 SHAPE@XYZ—一组要素的质心 x,y,z 坐标。 SHAPE@TRUECENTROID—一组要素的质心 x,y 坐标。这会返回与 SHAPE@XY 相同的值。 SHAPE@X—要素的双精度 x 坐标。 SHAPE@Y—要素的双精度 y 坐标。 SHAPE@Z—要素的双精度 z 坐标。 SHAPE@M—要素的双精度 m 值。 SHAPE@JSON—表示几何的 Esri JSON 字符串。 SHAPE@WKB—OGC 几何的熟知二进制 (WKB) 表示。用于以可移植的方式将几何值表示为连续的字节流。值返回为 bytearray 对象，但是可以更新为 bytearray 或 bytes 对象。 SHAPE@WKT—OGC 几何的熟知文本 (WKT) 表示。用于以可移植的方式将几何值表示为文本字符串。 SHAPE@—要素的几何对象。 SHAPE@AREA—要素的双精度面积。 SHAPE@LENGTH—要素的双精度长度。 CREATED@—要素创建时间的日期时间对象。此字段为只读字段。 CREATOR@—创建要素的用户名字符串。此字段为只读字段。 EDITED@—要素上次编辑时间的日期时间对象。此字段为只读字段。 EDITOR@—上次编辑要素的用户名字符串。此字段为只读字段。 GLOBALID@—要素的通用唯一标识符字符串。此字段为只读字段。 OID@—“对象 ID”字段的值。 SUBTYPE@—整型子类型编码。	String
where_clause	用于限制所返回的记录的可选表达式。有关 WHERE 子句和 SQL 语句的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。 (默认值为 None)	String
spatial_reference	要素类的空间参考。指定此参数后，将根据输入的空间参考对要素进行投影（或变换）。如果未指定，则将使用输入要素类的空间参考。此参数的有效值为 SpatialReference 对象或等效字符串。 (默认值为 None)	SpatialReference
explode_to_points	将要素解构为其单个点或折点。如果将 explode_to_points 设置为 True，则一个包含五个点的多点要素将表示为五行。 (默认值为 False)	Boolean
sql_clause	以列表或组的形式列出的 SQL 前缀和后缀子句对。 SQL 前缀子句支持 None、DISTINCT 和 TOP。 SQL 后缀子句支持 None、ORDER BY 和 GROUP BY。 Use DISTINCT in a prefix clause for a table located in a file geodatabase. DISTINCT is not honored in a relational database. `with arcpy.da.UpdateCursor( in_features, ["OID@", "STREET_NAME"], sql_clause=("DISTINCT STREET_NAME", None) ) as cur:` Use TOP in a prefix clause and ORDER BY in a postfix clause. `with arcpy.da.UpdateCursor( in_features, ['OID@', "ELEVATION"], sql_clause=("TOP 5", "ORDER BY ELEVATION DESC") ) as cur:` Use GROUP BY in a postfix clause. `with arcpy.da.UpdateCursor( in_features, ['STREET_NAME'], sql_clause=(None, "GROUP BY STREET_NAME") ) as cur:` SQL 前缀子句位于第一个位置，并将被插入到 SELECT 关键字与 SELECT COLUMN LIST 之间。 SQL 前缀子句最常用于 DISTINCT 或 ALL 等子句。 SQL 后缀子句位于第二个位置，并将被追加到 where 子句之后的 SELECT 语句中。 SQL 后缀子句最常用于 ORDER BY 等子句。注：仅在使用数据库时支持 DISTINCT、ORDER BY 和 ALL。它们不适用于其他数据源（如 dBASE 或 INFO 表）。仅 SQL Server 数据库支持 TOP。 (默认值为 (None, None))	tuple
datum_transformation	当光标将要素从一个空间参考投影到另一个空间参考时，如果空间参考未共享同一基准面，则应指定相应的基准面变换。 An update cursor can perform a projection or transformation at two stages: when reading the features from the feature class on disk and when writing the updated features to the feature class. ListTransformations 函数可用于提供两个空间参考之间的有效基准面变换列表。了解有关基准面变换的详细信息	String
explicit [explicit,...]	如果字段具有默认值并且该字段可为空，则使用 True 值将显式覆盖默认值并将空值插入到记录中。使用 False 值时，将插入默认值而不是空值。 Apply the explicit rule to all fields: `with arcpy.da.UpdateCursor(table, [field1, field2, field3], explicit=True) as cursor: ...` 显式规则也可以应用于使用布尔值列表的各个字段。值列表的长度必须与字段列表的长度相同。 Apply the explicit rule to only the first two fields: `with arcpy.da.UpdateCursor(table, [field1, field2, field3], explicit=[True, True, False]) as cursor: ...` (默认值为 False)	Boolean
spatial_filter	用于对要素进行空间过滤的几何对象。如果指定此参数，则游标将基于指定的几何和 spatial_relationship 值来限制返回的要素。 (默认值为 None)	Geometry
spatial_relationship	spatial_filter 参数中的输入和查询几何之间的空间关系。仅当指定 spatial_filter 参数时，此参数才适用。 INTERSECTS— Rows are only returned when the spatial_filter geometry intersects the input row's geometry. ENVELOPE_INTERSECTS— Rows are only returned when the spatial_filter geometry's envelope intersects the input row's geometry. INDEX_INTERSECTS— Rows are only returned when the spatial_filter geometry's envelope intersects the index entry for the input row's geometry. Because it uses the underlying index grid, rather than the envelope of the feature, it is faster and is commonly used for return features for display purposes. TOUCHES— Rows are only returned when the spatial_filter geometry touches the input row's geometry. OVERLAPS— Rows are only returned when the spatial_filter geometry overlaps the input row's geometry. CROSSES— Rows are only returned when the spatial_filter geometry crosses the input row's geometry. WITHIN— Rows are only returned when the spatial_filter geometry is within the input row's geometry. CONTAINS— Rows are only returned when the spatial_filter geometry contains the input row's geometry. (默认值为 INTERSECTS)	String
search_order	RDBMS 应用空间搜索的顺序。此属性仅影响企业级地理数据库数据，并且仅当指定 spatial_filter 参数时才适用。 ATTRIBUTEFIRST—The attribute query will be applied first. SPATIALFIRST— The spatial query will be applied first. (默认值为 ATTRIBUTEFIRST)	String

属性

属性	说明	数据类型
fields (只读)	游标使用的一组字段名称。该组将包括由 field_names 参数指定的所有字段和令牌。 fields 属性中字段名称的排序顺序将与 field_names 参数的传递顺序一致。如果 field_names 参数设置为，则字段属性将包括游标使用的全部字段。值将返回 x,y 坐标元组中的几何（相当于 SHAPE@XY 令牌）。	tuple

说明

数据类型

fields

(只读)

游标使用的一组字段名称。

该组将包括由 field_names 参数指定的所有字段和令牌。

fields 属性中字段名称的排序顺序将与 field_names 参数的传递顺序一致。

如果 field_names 参数设置为 *，则字段属性将包括游标使用的全部字段。 * 值将返回 x,y 坐标元组中的几何（相当于 SHAPE@XY 令牌）。

tuple

方法概述

方法	说明
deleteRow ()	删除当前行。
reset ()	将光标重置回第一行。
updateRow (row)	更新表中的当前行。

方法

deleteRow ()

reset ()

updateRow (row)

参数	说明	数据类型
row	值列表或组。值的顺序应与字段的顺序相同。更新字段时，如果传入的值与字段类型匹配，则将根据需要对这些值进行转换。例如，将值 1.0 添加到字符串字段将添加为 "1.0"；将值 "25" 添加到浮点型字段将添加为 25.0。	tuple

参数

说明

数据类型

row

值列表或组。值的顺序应与字段的顺序相同。

更新字段时，如果传入的值与字段类型匹配，则将根据需要对这些值进行转换。例如，将值 1.0 添加到字符串字段将添加为 "1.0"；将值 "25" 添加到浮点型字段将添加为 25.0。

tuple

代码示例

UpdateCursor 示例 1

通过评估其他字段值使用 UpdateCursor 更新字段值。

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_YIELD', 'WELL_CLASS']

# Create update cursor for feature class 
with arcpy.da.UpdateCursor(fc, fields) as cursor:
    # For each row, evaluate the WELL_YIELD value (index position 
    # of 0), and update WELL_CLASS (index position of 1)
    for row in cursor:
        if (row[0] >= 0 and row[0] <= 10):
            row[1] = 1
        elif (row[0] > 10 and row[0] <= 20):
            row[1] = 2
        elif (row[0] > 20 and row[0] <= 30):
            row[1] = 3
        elif (row[0] > 30):
            row[1] = 4

        # Update the cursor with the updated list
        cursor.updateRow(row)

UpdateCursor 示例 2

使用 UpdateCursor 更新缓冲距离字段，以便与缓冲函数配合使用。

import arcpy

arcpy.env.workspace = 'c:/data/output.gdb'
fc = 'c:/data/base.gdb/roads'
fields = ['ROAD_TYPE', 'BUFFER_DISTANCE']

# Create update cursor for feature class 
with arcpy.da.UpdateCursor(fc, fields) as cursor:
    # Update the field used in Buffer so the distance is based on road 
    # type. Road type is either 1, 2, 3, or 4. Distance is in meters. 
    for row in cursor:
        # Update the BUFFER_DISTANCE field to be 100 times the 
        # ROAD_TYPE field.
        row[1] = row[0] * 100
        cursor.updateRow(row) 

# Buffer feature class using updated field values
arcpy.analysis.Buffer(fc, 'roads_buffer', 'BUFFER_DISTANCE')

UpdateCursor 示例 3

将 UpdateCursor 与空间过滤器配合使用以更新字段值。

import arcpy

arr = arcpy.Array(
    [arcpy.Point(342917.4, 553980.8), arcpy.Point(366915.9, 594749.1)]
)
new_road = arcpy.Polyline(arr, spatial_reference=arcpy.SpatialReference(26971))

fc = r"C:\data\chicago.gdb\houses"
fields = ["OCCUPIED"]

with arcpy.da.UpdateCursor(
    fc, fields, where_clause="OCCUPIED != 'Vacant'", spatial_filter=new_road
) as cursor:
    for row in cursor:
        row[0] = 'Vacant'
        cursor.updateRow(row)

摘要

说明

注：

注：

语法

注：

属性

方法概述

方法

代码示例

相关主题

在本主题中

相关主题