说明
Geometry 对象属性可通过在字段列表中指定令牌 SHAPE@ 进行访问。
使用 for 循环可迭代搜索游标。 搜索游标也支持 with 语句以重置迭代并帮助移除锁。 但是，为了防止锁定所有内容，应考虑使用 del 语句来删除对象或将游标包含在函数中以使游标对象位于作用范围之外。
利用属性条件或空间条件，可以限制 SearchCursor 返回的记录。
使用 SHAPE@ 访问整个几何是一种代价较高的操作。 如果只需几何信息（如点的 x,y 坐标），请使用 SHAPE@XY、SHAPE@Z 和 SHAPE@M 等令牌进行更快速、更高效的访问。
语法
SearchCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation}, {spatial_filter}, {spatial_relationship}, {search_order})| 参数 | 说明 | 数据类型 |
in_table | 要素类、图层、表或表视图。 | String |
field_names [field_names,...] | 字段名称列表（或组）。 对于单个字段，可以使用一个字符串，而不使用字符串列表。 要访问输入表中的所有字段（BLOB 字段除外），可以使用星号 (*) 代替字段列表。 但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。 以令牌（如 OID@）取代字段名称可访问更多的信息：
| String |
where_clause | 用于限制所返回的记录的可选表达式。 有关 WHERE 子句和 SQL 语句的详细信息，请参阅在 ArcGIS 中使用的查询表达式的 SQL 参考。 (默认值为 None) | String |
spatial_reference | 要素类的空间参考。 指定此参数后，将根据输入的空间参考对要素进行投影（或变换）。 如果未指定，则将使用输入要素类的空间参考。 此参数的有效值为 SpatialReference 对象或等效字符串。 If a spatial reference is specified, but the input feature class has an unknown spatial reference, neither a projection nor transformation can be completed. The geometry returned by the cursor will have coordinates matching the input, with a spatial reference updated to the one specified. (默认值为 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 | 当光标将要素从一个空间参考投影到另一个空间参考时，如果空间参考未共享同一基准面，则应指定相应的基准面变换。 ListTransformations 函数可用于提供两个空间参考之间的有效基准面变换列表。 (默认值为 None) | String |
spatial_filter | 用于对要素进行空间过滤的几何对象。 如果指定此参数，则游标将基于指定的几何和 spatial_relationship 值来限制返回的要素。 (默认值为 None) | Geometry |
spatial_relationship | spatial_filter 参数中的输入和查询几何之间的空间关系。 仅当指定 spatial_filter 参数时，此参数才适用。
(默认值为 INTERSECTS) | String |
search_order | RDBMS 应用空间搜索的顺序。 此属性仅影响企业级地理数据库数据，并且仅当指定 spatial_filter 参数时才适用。
(默认值为 ATTRIBUTEFIRST) | String |
属性
| 属性 | 说明 | 数据类型 |
| fields (只读) | 游标使用的一组字段名称。 该组将包括由 field_names 参数指定的所有字段和令牌。 fields 属性中字段名称的排序顺序将与 field_names 参数的传递顺序一致。 如果 field_names 参数设置为 *，则字段属性将包括游标使用的全部字段。 * 值将返回 x,y 坐标元组中的几何（相当于 SHAPE@XY 令牌）。 | tuple |
方法概述
| 方法 | 说明 |
| reset () | 将光标重置回第一行。 |
方法
reset ()
代码示例
使用 SearchCursor 浏览要素类并打印指定字段值和点的 x,y 坐标。
import arcpy
fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE', 'SHAPE@XY']
# For each row, print the WELL_ID and WELL_TYPE fields, and
# the feature's x,y coordinates
with arcpy.da.SearchCursor(fc, fields) as cursor:
for row in cursor:
print(f'{row[0]}, {row[1]}, {row[2]}')使用 SearchCursor 返回一组唯一字段值。
import arcpy
fc = 'c:/data/base.gdb/well'
field = 'Diameter'
# Use SearchCursor with list comprehension to return a
# unique set of values in the specified field
values = [row[0] for row in arcpy.da.SearchCursor(fc, field)]
unique_values = set(values)
print(unique_values)使用 SearchCursor 返回使用令牌的属性。
import arcpy
fc = 'c:/data/base.gdb/well'
# For each row, print the Object ID field, and use the SHAPE@AREA
# token to access geometry properties
with arcpy.da.SearchCursor(fc, ['OID@', 'SHAPE@AREA']) as cursor:
for row in cursor:
print(f'Feature {row[0]} has an area of {row[1]}')使用 SearchCursor 与 where 子句识别满足特定条件的要素。
import arcpy
fc = 'c:/base/data.gdb/roads'
class_field = 'Road Class'
name_field = 'Name'
# Create an expression with proper delimiters
delimited_field = arcpy.AddFieldDelimiters(fc, name_field)
expression = f'{delimited_field} = 2'
# Create a search cursor using an SQL expression
with arcpy.da.SearchCursor(
fc, [class_field, name_field], where_clause=expression
) as cursor:
for row in cursor:
# Print the name of the residential road
print(row[1])使用 SearchCursor 和 Python sorted 方法对行排序。
有关其他排序选项，请参阅 Python 如何实现最短排序。
import arcpy
fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use Python's sorted method to sort rows
for row in sorted(arcpy.da.SearchCursor(fc, fields)):
print(f'{row[0]}, {row[1]}')或者，如果数据支持 ORDER BY 子句，则使用 sql_clause 进行排序。
注：
仅当使用数据库时，才支持 ORDER BY 子句。 它不适用于其他数据源（如 dBASE）。
import arcpy
fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use ORDER BY sql clause to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=(None, "ORDER BY WELL_ID, WELL_TYPE")) as cursor:
for row in cursor:
print(f'{row[0]}, {row[1]}')使用 SQL TOP 子句以限制要返回的记录数量。
注：
TOP 子句仅受 SQL Server 数据库的支持。
import arcpy
fc = 'c:/data/base.mdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use SQL TOP to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=('TOP 3', None)):
for row in cursor:
print(f'{row[0]}, {row[1]}')使用 SearchCursor（将空间过滤器与几何对象配合使用）。
import arcpy
arr = arcpy.Array(
[arcpy.Point(342917.4, 553980.8), arcpy.Point(366915.9, 594749.1)]
)
new_road = arcpy.Polyline(arr, spatial_reference=arcpy.SpatialReference(26971))
fc = r"C:\data\chicago.gdb\houses"
fields = ["ADDRESS", "OCCUPIED"]
with arcpy.da.SearchCursor(
fc, fields, where_clause="OCCUPIED != 'Vacant'", spatial_filter=new_road
) as cursor:
for row in cursor:
print(f'{row[0]}: {row[1]}')使用 SearchCursor（将空间过滤器与来自其他要素类的几何对象配合使用）。
import arcpy
fc = r"c:\connections\sqlserver.sde\DBO.ShipPositions"
fields = ["OBJECTID", "SHIP_NAME"]
searchPoly = [row[0] for row in arcpy.da.SearchCursor("searchArea", ["SHAPE@"])][0]
with arcpy.da.SearchCursor(
fc, fields, spatial_filter=searchPoly, search_order="SPATIALFIRST"
) as cursor:
for row in cursor:
print(f'{row[0]}: {row[1]}')