ArcPy游标遍历要素与属性更新

ArcPy
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

要用 ArcPy 遍历要素并更新属性,优先使用 arcpy.da.UpdateCursor。它按你指定的字段顺序返回每行值列表,改完后必须调用 updateRow 才会写回数据;推荐用 with 语句包住游标,自动释放锁。旧版 arcpy.UpdateCursor 仍可用,但性能明显更慢,日常脚本请统一用 da 模块。

用 ArcPy 游标遍历要素并写回属性的工作示意

arcpy 游标有哪几种,为什么优先 da

游标是表/要素类上的数据访问对象,用来逐行读取、插入或更新。ArcPy 提供三种:SearchCursor(只读遍历)、InsertCursor(插入新行)、UpdateCursor(读写更新或删除)。自 ArcGIS 10.1 起引入了 arcpy.da 模块,性能远高于早期游标;当前 ArcGIS Pro(截至 2026 年 11 月最新为 3.7)文档也明确推荐 da 游标。

  • 只查属性或几何 → 用 arcpy.da.SearchCursor
  • 批量追加要素 → 用 arcpy.da.InsertCursor
  • 按条件改字段值、删行 → 用 arcpy.da.UpdateCursor

更系统的对比和字段计算替代方案,可参考本站ArcPy更新游标、cursor与字段计算说明。官方总览见ArcGIS Pro 使用游标进行数据访问。

UpdateCursor 怎么写:可执行步骤

目标很明确:打开要素类 → 只取需要的字段 → 循环改值 → 写回并释放锁。按下面做即可验收。

  1. 准备要素类路径(或图层名)和字段列表。字段顺序决定 row 列表下标,不要用 *(会拖慢性能)。
  2. 用 with arcpy.da.UpdateCursor(fc, fields) as cursor: 打开游标。with 能在退出时自动清理锁。
  3. 写 for row in cursor:。此时 row 是列表,例如 fields=[“NAME”,”STATUS”] 则 row[0] 是 NAME,row[1] 是 STATUS。
  4. 按业务改 row 中的值(字符串、数值、日期均可)。需要几何时用令牌,如 SHAPE@XY、SHAPE@AREA、OID@。
  5. 立刻调用 cursor.updateRow(row)。只改内存不调用此方法,磁盘数据不会变。
  6. 若要删当前行,用 cursor.deleteRow()(一般放在 updateRow 之前或单独判断)。
  7. 循环结束后 with 自动结束;若没用 with,请显式 del cursor、row,避免模式锁。

最小逻辑示意(写成脚本时注意缩进):with arcpy.da.UpdateCursor(fc, [“STATUS”,”SCORE”]) as cursor: → for row in cursor: → 若满足条件则 row[0]=”已复核”;row[1]=row[1]+10 → cursor.updateRow(row)。完整写法示例还可对照本站ArcPy游标怎么用与UpdateCursor写法。

ArcGIS Pro 官方「使用游标进行数据访问」文档页面截图
ArcGIS Pro 官方「使用游标进行数据访问」文档页面截图(截图来源:pro.arcgis.com)

字段令牌、性能与适用边界

几何和系统字段不要整表拉出来,用令牌更稳、更快。常用令牌如下:

令牌 含义 典型用途
OID@ 对象 ID 日志、关联、去重判断
SHAPE@ 完整几何对象 需要改形状时(较重)
SHAPE@XY 质心或点坐标元组 只读坐标、简单偏移
SHAPE@AREA 面积 面积阈值、统计写回
  • 只列真正要读/写的字段,循环里少调其他 ArcPy 工具。
  • UpdateCursor 不支持带连接(Join)的图层——请直接对着源要素类/表,或先移除连接。
  • 参与拓扑、几何网络、网络数据集的要素类,以及企业库版本化数据、部分带类扩展对象,通常必须在编辑会话里改:用 arcpy.da.Editor 的 startEditing / startOperation,再开游标。
  • 简单字段批量赋值,也可改用 Calculate Field / Calculate Fields 工具,脚本更短;复杂条件判断仍用 UpdateCursor 更清晰。

类说明与方法(updateRow、deleteRow、reset)见UpdateCursor 官方类参考。

锁、报错与验收标准

最常见失败不是语法,而是锁和会话。按下面排查:

  • Cannot acquire a lock / schema lock:属性表在 Pro 里开着、别的脚本占着、或服务在用同一数据。关掉相关窗口,确认脚本用 with,必要时 del 游标;避免两个游标同时写同一数据集。
  • 改了 row 但数据没变:漏了 updateRow。
  • 版本化/拓扑报错:先 Editor 启动编辑会话再更新,结束时 stopOperation / stopEditing。
  • RuntimeError: NotInitialized:外部跑脚本时 Pro 未登录或未授权,先在本机登录 Named User 或完成离线授权。

验收标准建议:更新前后用 SearchCursor 或属性表抽查同一 OID 的字段值;确认无残留 .lock 文件;企业库场景检查版本是否正确提交。ArcPy 随 ArcGIS Pro 自带,安装 Pro 后用「Python 命令提示符」或 propy 即可,无需单独装包。

常见问题

旧版 arcpy.UpdateCursor 还能用吗?

能,但自 10.1 / Pro 早期起已被 arcpy.da.UpdateCursor 取代,速度慢很多。新脚本请统一写 da,除非维护极老代码。

为什么必须用 with,不用行不行?

可以,但容易忘释放锁。with 在异常退出时也会清理,是官方推荐写法;不用 with 时请手动 del cursor 和 row。

能不能一边 SearchCursor 一边 UpdateCursor 同一要素类?

不建议同时打开两个写相关游标。先读到列表再更新,或分两次会话,可大幅减少锁冲突。

只改一个字段,还要不要列全字段?

不要。field_names 只写要读和要写的字段即可,越少越快;几何用令牌,避免 SHAPE@ 除非真要改形状。

总结:遍历并更新属性,选 arcpy.da.UpdateCursor,字段列表写清楚,改完立刻 updateRow,全程用 with 管锁;遇连接、版本化或拓扑就换源表或加 Editor。建议先在小样本要素类上跑通再上生产库,复杂条件更新可结合本站两篇游标教程对照验收。