UpdateCursor

描述

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})

参数	说明	数据类型
in_table	要素类、图层、表或表视图。	String
field_names [field_names,...]	字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。 要访问输入表中的所有字段（栅格和 BLOB 字段除外），可以使用星号 (*) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。 不支持栅格字段。 以令牌（如 OID@）取代字段名称可访问更多的信息： 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) 制图表达。该存储类型将几何值表示为不间断的字节流形式。 SHAPE@WKT —OGC 几何的熟知文本 (WKT) 制图表达。其将几何值表示为文本字符串。 SHAPE@ —要素的几何对象。 SHAPE@AREA —要素的双精度面积。 SHAPE@LENGTH —要素的双精度长度。 OID@ —“对象 ID”字段的值。	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。 SQL 前缀子句位于第一个位置，将被插入到 SELECT 关键字和 SELECT COLUMN LIST 之间。SQL 前缀子句最常用于 DISTINCT 或 ALL 等子句。 SQL 后缀子句位于第二个位置，将追加到 SELECT 语句的 where 子句之后。SQL 后缀子句最常用于 ORDER BY 等子句。 注： 仅在使用数据库时支持使用 DISTINCT、ORDER BY 和 ALL。它们不受其他数据源（如 dBASE 或 INFO 表）的支持。 TOP 仅受 SQL Server 数据库的支持。 (默认值为 (None, None))	tuple
datum_transformation	当光标将要素从一个空间参考投影到另一个空间参考时，如果空间参考未共享同一基准面，则应指定相应的基准面变换。 更新游标可以在两个阶段执行投影或变换：在磁盘上从要素类读取要素时，以及将已更新的要素写入要素类时。 ListTransformations 函数可用于提供两个空间参考之间的有效基准面变换列表。 了解有关基准面变换的详细信息	String

属性

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

方法概述

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

方法

deleteRow ()

reset ()

updateRow (row)

参数	说明	数据类型
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.Buffer_analysis(fc, 'roads_buffer', 'BUFFER_DISTANCE')