SearchCursor (arcpy.da)
摘要
SearchCursor 用于建立从要素类或表中返回的记录的只读访问权限。
返回一组迭代的元组。元组中值的顺序与 field_names 参数指定的字段顺序相符。
讨论
几何属性可通过在字段列表中指定令牌 SHAPE@ 进行访问。
使用 For 循环可迭代搜索游标。搜索游标也支持 With 语句；使用 With 语句可保证数据库锁的关闭和释放，并重置迭代。
利用属性条件和/或空间条件，可以限制 SearchCursor 返回的记录。
使用 SHAPE@ 访问整个几何是一种代价较高的操作。如果仅需要几何信息（如点的 x、y 坐标），请使用 SHAPE@XY、SHAPE@Z 和 SHAPE@M 之类的令牌进行更快速、高效的访问。
注:不要将 arcpy.da.SearchCursor 与 arcpy.SearchCursor 相混淆。
语法
| 参数 | 说明 | 数据类型 |
in_table |
要素类、图层、表或表视图。 | String |
field_names [field_names,...] | 字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。 如果要访问输入表中的所有字段（栅格和 BLOB 字段除外），可以使用星号 (*) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。 不支持栅格字段。 以令牌（如 OID@）取代字段名称可访问更多的信息：
注:SHAPE@JSON、SHAPE@WKB 和 SHAPE@WKT 令牌在 ArcGIS 10.1 Service Pack 1 中可用。 | String |
where_clause | 用于限制所返回的记录的可选表达式。有关 WHERE 子句和 SQL 语句的详细信息，请参阅构建查询表达式和使用 Python 指定查询。 (默认值为 None) | String |
spatial_reference | 要素类的空间参考。可以使用 SpatialReference 对象或等效字符串来指定。 (默认值为 None) | SpatialReference |
explode_to_points | 将要素解构为单个点或折点。如果将 explode_to_points 设置为 True，则一个包含五个点的多点要素将表示为五行。 (默认值为 False) | Boolean |
sql_clause | 以列表或组的形式列出的可选 SQL 前缀和后缀子句对。 SQL prefix supports None, DISTINCT, and TOP. SQL postfix supports None, ORDER_BY, and GROUP_BY. SQL 前缀子句位于第一个位置，将被插入到 SELECT 关键字和 SELECT COLUMN LIST 之间。最常用于 DISTINCT 或 ALL 等子句。 SQL 后缀子句位于第二个位置，将追加到 SELECT 语句的 where 子句之后。最常用于 ORDER BY 等子句。 注:此功能仅在使用地理数据库时才可用。其他数据源不支持此功能。 (默认值为 (None, None)) | tuple |
属性
| 属性 | 说明 | 数据类型 |
| fields (只读) |
A tuple of field names used by the cursor. The tuple will include all fields (and tokens) specified by the field_names argument. If the field_names argument is set to "*", the fields property will include all fields used by the cursor. When using "*", geometry values will be returned in a tuple of the x,y-coordinates (equivalent to the SHAPE@XY token). | tuple |
方法概述
| 方法 | 说明 |
| next () |
将下一行作为元组返回。字段将按照创建光标时所指定的顺序返回。 |
| reset () |
将光标重置回第一行。 |
方法
| 数据类型 | 说明 |
| tuple |
代码实例
使用 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
# the feature's x,y coordinates
#
with arcpy.da.SearchCursor(fc, fields) as cursor:
for row in cursor:
print("{0}, {1}, {2}".format(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))]
uniqueValues = set(values)
print(uniqueValues)
使用 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("Feature {0} has an area of {1}".format(row[0], 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
#
expression = arcpy.AddFieldDelimiters(fc, name_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 的排序方法对行排序。
有关其他排序选项，请参阅 Python 的如何实现最短排序。
import arcpy
fc = "c:/data/base.gdb/well"
f1, f2 = "WELL_ID", "WELL_TYPE"
# Use Python's sorted method to sort rows
#
for row in sorted(arcpy.da.SearchCursor(fc, [f1, f2])):
print("{0}, {1}".format(row[0], row[1]))