SearchCursor

描述

SearchCursor 用于建立从要素类或表中返回的记录的只读访问权限。

将返回一组迭代元组。元组中值的顺序与 field_names 参数指定的字段顺序相符。

讨论

Geometry 属性可通过在字段列表中指定令牌 SHAPE@ 进行访问。

使用 for 循环可迭代搜索游标。搜索游标也支持 with 语句以重置迭代并帮助移除锁。但是，为了防止锁定所有内容，应考虑使用 del 语句来删除对象或将游标包含在函数中以使游标对象位于作用范围之外。

利用属性条件或空间条件，可以限制 SearchCursor 返回的记录。

使用 SHAPE@ 访问整个几何是一种代价较高的操作。如果只需几何信息（如点的 x,y 坐标），请使用 SHAPE@XY、SHAPE@Z 和 SHAPE@M 等令牌进行更快速、更高效的访问。

在 Python 2 中，SearchCursor 支持迭代器 next 方法，在循环外检索下一行。在 Python 3 中，可使用 Python 内置 next 函数执行等效操作。

语法

SearchCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation})

参数	说明	数据类型
in_table	要素类、图层、表或表视图。	String
field_names [field_names,...]	字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。 要访问输入表中的所有字段（栅格和 BLOB 字段除外），可以使用星号 (*) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。 不支持栅格字段。 以令牌（如 OID@）取代字段名称可访问更多的信息： SHAPE@XY —一组要素的质心 x,y 坐标。 SHAPE@XYZ —一组要素的质心 x,y,z 坐标。 SHAPE@TRUECENTROID —一组要素的质心 x,y 坐标。这会返回与 SHAPE@XY 相同的值。 SHAPE@X —要素的双精度 x 坐标。 SHAPE@Y —要素的双精度 y 坐标。 SHAPE@Z —要素的双精度 z 坐标。 SHAPE@M —要素的双精度 m 值。 SHAPE@JSON — 表示几何的 Esri JSON 字符串。 SHAPE@WKB —OGC 几何的熟知二进制 (WKB) 制图表达。该存储类型将几何值表示为不间断的字节流形式。 SHAPE@WKT —OGC 几何的熟知文本 (WKT) 制图表达。其将几何值表示为文本字符串。 SHAPE@ —要素的几何对象。 SHAPE@AREA —要素的双精度面积。 SHAPE@LENGTH —要素的双精度长度。 OID@ —“对象 ID”字段的值。	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。 SQL 前缀子句位于第一个位置，将被插入到 SELECT 关键字和 SELECT COLUMN LIST 之间。SQL 前缀子句最常用于 DISTINCT 或 ALL 等子句。 SQL 后缀子句位于第二个位置，将追加到 SELECT 语句的 where 子句之后。SQL 后缀子句最常用于 ORDER BY 等子句。 注： 仅在使用数据库时支持使用 DISTINCT、ORDER BY 和 ALL。它们不受其他数据源（如 dBASE 或 INFO 表）的支持。 TOP 仅受 SQL Server 数据库的支持。 (默认值为 (None, None))	tuple
datum_transformation	当光标将要素从一个空间参考投影到另一个空间参考时，如果空间参考未共享同一基准面，则应指定相应的基准面变换。 ListTransformations 函数可用于提供两个空间参考之间的有效基准面变换列表。 了解有关基准面变换的详细信息 (默认值为 None)	String

属性

属性	说明	数据类型
fields (只读)	游标使用的一组字段名称。 该组将包括由 field_names 参数指定的所有字段（和令牌）。如果 field_names 参数设置为 *，则字段属性将包括游标使用的全部字段。使用 * 时，几何值将以 x,y 坐标组返回（相当于 SHAPE@XY 令牌）。 fields 属性中字段名称的排序顺序将与 field_names 参数的传递顺序一致。	tuple

方法概述

方法	说明
reset ()	将光标重置回第一行。

方法

reset ()

代码示例

SearchCursor 示例 1

使用 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(u'{0}, {1}, {2}'.format(row[0], row[1], row[2]))

SearchCursor 示例 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 示例 3

使用 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 {} has an area of {}'.format(row[0], row[1]))

SearchCursor 示例 4

使用 SearchCursor 与 where 子句识别满足特定条件的要素。

import arcpy
fc = 'c:/base/data.gdb/roads' class_field = 'Road Class' name_field = 'Name'
# Create an expression with proper delimiters expression = u'{} = 2'.format(arcpy.AddFieldDelimiters(fc, name_field))
# 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 示例 5A

使用 SearchCursor 和 Python 的排序方法对行排序。

有关其他排序选项，请参阅 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(u'{0}, {1}'.format(row[0], row[1]))

SearchCursor 示例 5B

或者，如果数据支持 SQL ORDER BY，则使用 sql_clause 进行排序。

注：

仅在使用数据库时才支持使用 ORDER BY。它不适用于其他数据源（如 dBASE 或 INFO 表）。

import arcpy
fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use ORDER BY sql clause to sort field values
for row in arcpy.da.SearchCursor(
        fc, fields, sql_clause=(None, 'ORDER BY WELL_ID, WELL_TYPE')):
    print(u'{0}, {1}'.format(row[0], row[1]))

SearchCursor 示例 6

使用 SQL TOP 限制要返回的记录数。

注：

TOP 仅受 SQL Server 和 MS Access 数据库的支持。

import arcpy
fc = 'c:/data/base.mdb/well' fields = ['WELL_ID', 'WELL_TYPE']
# Use SQL TOP to sort field values for row in arcpy.da.SearchCursor(fc, fields, sql_clause=('TOP 3', None)):
    print(u'{0}, {1}'.format(row[0], row[1]))