摘要
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})
参数 | 说明 | 数据类型 |
in_table | 要素类、图层、表或表视图。 | String |
field_names [field_names,...] | 字段名称列表(或组)。 对于单个字段,可以使用一个字符串,而不使用字符串列表。 要访问输入表中的所有字段(BLOB 字段除外),可以使用星号 (*) 代替字段列表。 但是,为了获得较快的性能和可靠的字段顺序,建议您将字段列表限制在实际需要的字段。 不支持栅格字段。 以令牌(如 OID@)取代字段名称可访问更多的信息:
| 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.
Use TOP in a prefix clause and ORDER BY in a postfix clause.
Use GROUP BY in a postfix clause.
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 into the feature class. ListTransformations 函数可用于提供两个空间参考之间的有效基准面变换列表。 | String |
explicit [explicit,...] | 如果字段具有默认值并且该字段可为空,则使用 True 值将显式覆盖默认值并将空值插入到记录中。 使用 False 值时,将插入默认值而不是空值。 Apply the explicit rule to all fields: 显式规则也可以应用于使用布尔值列表的各个字段。 值列表的长度必须与字段列表的长度相同。 Apply the explicit rule to only the first two fields: (默认值为 False) | Boolean |
属性
属性 | 说明 | 数据类型 |
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 |
代码示例
通过评估其他字段值使用 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 更新缓冲距离字段,以便与缓冲函数配合使用。
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')