ArcMap

UpdateCursor

描述

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

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

说明

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

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

语法

UpdateCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause})
参数说明数据类型
in_table

要素类、图层、表或表视图。

String
field_names
[field_names,...]

字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。

如果要访问输入表中的所有字段（栅格和 BLOB 字段除外），可以使用星号 (*) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。

不支持栅格字段。

以令牌（如 OID@）取代字段名称可访问更多的信息：

  • SHAPE@XY —一组要素的质心 x,y 坐标。
  • SHAPE@XYZ —一组要素的质心 x,y,z 坐标。仅当几何启用了 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@ —ObjectID 字段的值。
String
where_clause

用于限制所返回的记录的可选表达式。有关 WHERE 子句和 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 等子句。

(默认值为 (None, None))

tuple

属性

属性说明数据类型
fields
（只读）

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

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

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

tuple

方法概述

方法说明
deleteRow ()

删除当前行。

next ()

将下一行作为元组返回。字段将按照创建光标时所指定的顺序返回。

reset ()

将光标重置回第一行。

updateRow (row)

更新表中的当前行。

方法

deleteRow ()
next ()

返回值

数据类型说明
tuple

将下一行作为元组。

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

相关主题