ArcPy入门学习指南(含：arcpy search cursor详细解析)

作者： GIS研习社更新时间：2025-09-01 10:56:34 分类：ArcPy

很多团队在做 ArcGIS 数据处理时，最头疼的是“如何既快又稳地按条件读取大批量要素或表记录”。当记录过万、字段多且涉及几何时，手工导出往往慢且易错。我是 Dr.gis，从工程一线出发，带你用 ArcPy 的数据访问游标把这件事做对、做快、做稳。

ArcPy 与数据访问游标：是什么

ArcPy 是 ArcGIS Pro/ArcMap 提供的 Python 接口，用于把日常地理处理工具脚本化与自动化。其中 arcpy.da 模块（data access）提供了新一代高性能游标，包含只读的 SearchCursor、可写的 InsertCursor、可改的 UpdateCursor 等。

SearchCursor 的职责是高效、只读地遍历要素类或表的记录，按你指定的字段顺序返回行数据，并支持 SQL 条件筛选、排序、几何投影与几何令牌等能力。与早期游标相比，arcpy.da 族在性能和易用性上更优，工程实践中应优先选择。

为什么要用游标遍历

内存友好：逐行迭代，不需一次性加载整表。
只读安全：避免误改数据结构；搭配 with 语句自动释放锁。
精确取数：只取所需字段与几何令牌，I/O 最小化。
可筛选排序：支持 where_clause 与 sql_clause，服务端/数据源侧过滤更快。
几何感知：直接获取 Geometry、面积、长度、坐标等衍生信息。

快速上手：从表到记录

下面示例在点要素类中，读取对象 ID、点坐标与名称，按类型筛选。

import arcpy

fc = r"C:gisdatacity.gdbFacilities"  # 点要素类
fields = ["OID@", "SHAPE@XY", "NAME"]    # 令牌 + 普通字段
where = "TYPE = 'Park'"

with arcpy.da.SearchCursor(fc, fields, where_clause=where) as cursor:
    for oid, (x, y), name in cursor:
        print(f"{oid}t{name}t({x:.3f}, {y:.3f})")

要点：

字段顺序决定了每行元组的顺序。
OID@ 和 SHAPE@XY 为令牌，能快速访问常用信息。
使用 with 语句可确保游标关闭、锁释放。

常用几何令牌与含义

令牌是对几何或系统字段的快捷访问。下表列出常用子集（不同几何类型的返回值与行为请以官方定义为准）。

令牌	返回	典型用途
OID@	对象ID（整数）	唯一标识、日志
SHAPE@	arcpy.Geometry 对象	全面几何运算与投影
SHAPE@XY	(X, Y) 坐标对	点坐标或几何代表点坐标
SHAPE@AREA	面积（数据坐标系单位）	快速面积统计
SHAPE@LENGTH	长度（数据坐标系单位）	快速长度统计
SHAPE@WKT / SHAPE@WKB / SHAPE@JSON	文本/二进制/JSON	跨系统传输、存档
SHAPE@TRUECENTROID	几何质心坐标	标注、空间聚合
SHAPE@X / @Y / @Z / @M	点几何的坐标/量测值	点要素快速取值

过滤与排序：where_clause 与 sql_clause

把筛选交给数据源端总是更快。注意不同数据存储（FGDB、SDE、Shapefile）的字段定界符差异，建议使用 arcpy.AddFieldDelimiters 构造字段名。

import arcpy

tbl = r"C:gisdatacity.gdbParcels"
fld = arcpy.AddFieldDelimiters(tbl, "ZONE")
where = f"{fld} IN ('R1','R2','R3')"
fields = ["OID@", "ZONE", "AREA"]

# sql_clause 是 (prefix, postfix)，常用在 postfix 放 ORDER BY
sql = (None, "ORDER BY AREA DESC")

with arcpy.da.SearchCursor(tbl, fields, where_clause=where, sql_clause=sql) as cur:
    for oid, zone, area in cur:
        print(zone, area)

提示：字符串值须加引号；日期字段在不同数据源上语法不同（例如 #yyyy-mm-dd# 或 date 'yyyy-mm-dd'），参考官方 SQL 表达式文档。

空间参考与几何计算

当需要几何令牌（如 SHAPE@、SHAPE@XY）时，可通过 spatial_reference 参数指定输出几何的空间参考，避免手动投影。

import arcpy

fc = r"C:gisdatacountry.gdbProvinces"
wgs84 = arcpy.SpatialReference(4326)  # WGS 84
fields = ["NAME", "SHAPE@"]           # 返回 Geometry（已投影）

with arcpy.da.SearchCursor(fc, fields, spatial_reference=wgs84) as cur:
    for name, geom in cur:
        # 以大地测地方法计算面积（平方千米）
        area_km2 = geom.getArea("GEODESIC", "SQUAREKILOMETERS")
        print(name, round(area_km2, 2))

说明：

spatial_reference 仅影响返回几何的坐标系，不修改源数据。
涉及面积/长度的分析，优先使用合适的投影（等积/等距）或使用几何对象的地理计算方法（如 GEODESIC）。

性能优化：工程经验清单

字段最小化：只取需要的字段与令牌，行宽越小越快。
尽量下推过滤：把条件写进 where_clause/sql_clause，避免 Python 端再筛选。
为查询字段建索引：对高频过滤字段使用 Add Index（尤其是大表）。
合理使用令牌：几何 JSON/WKB 转换成本高，仅在确需跨系统传输时使用。
控制循环里的开销：避免在迭代中频繁打印、打开文件或做重计算。
explode_to_points：当 True 时将沿几何顶点逐点迭代，适合提取折线/多边形所有节点，但行数会暴增，谨慎使用。
上下文管理：总是使用 with，减少锁与句柄泄漏。

常见错误与排查

字段名与大小写/定界符：跨不同数据源时用 AddFieldDelimiters；注意保留字冲突。
字符串与编码：包含中文条件常见因转义/编码导致不匹配，优先使用原始字符串 r"..."，或参数化拼接并核对数据实际值。
空值处理：None 参与数值计算会报错，进入计算前做空值替换（例如 x or 0）。
锁问题：SearchCursor 为只读，但并发写入会引发锁冲突；确保其他进程未占用，或拆分任务时间窗。
坐标单位误判：SHAPE@AREA/SHAPE@LENGTH 使用数据坐标系单位，地理坐标系下并非平方米/米；需要投影或使用地理测地方法。

综合案例：条件提取并聚合统计

目标：统计各城市的公园总面积（平方千米），只遍历一次数据。

import arcpy
from collections import defaultdict

fc = r"C:gisdatacity.gdbParks"           # 面要素
fields = ["CITY", "SHAPE@"]                  # 取城市与几何
result = defaultdict(float)

# 使用等积投影或使用 GEODESIC 方法；此处直接用 GEODESIC
with arcpy.da.SearchCursor(fc, fields) as cur:
    for city, geom in cur:
        if not city:  # 跳过空城市
            continue
        area_km2 = geom.getArea("GEODESIC", "SQUAREKILOMETERS")
        result[city] += area_km2

# 输出 Top 5
for city, area in sorted(result.items(), key=lambda kv: kv[1], reverse=True)[:5]:
    print(f"{city}t{area:.2f} km^2")

若需导出结果为表，可将字典转换为结构化数组再用 arcpy.da.NumPyArrayToTable 写回地理数据库。

与更高层工具的协同

FeatureClassToNumPyArray/da.FeatureClassToNumPyArray：一次性拉取小中型数据到 NumPy，适合向量化计算；大表仍建议游标逐行流式处理。
地理处理工具配合：筛选、排序、连接等若有数据库/GP 工具能高效完成，先在数据源侧做，游标只负责“读取与轻度逻辑”。