SearchCursor

汇总

SearchCursor 对象可建立要素类或表中记录的只读访问权限。

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

了解有关使用游标访问数据的详细信息

讨论

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	字段名称列表（或组）。对于单个字段，可以使用一个字符串，而不使用字符串列表。要访问输入表中的所有字段（BLOB 字段除外），可以使用星号 (`*`) 代替字段列表。但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。以令牌（如 `OID@` ）取代字段名称可访问更多的信息： ANNO@—要素的 `Annotation` 对象。此选项仅对 ArcGIS Pro 注记要素类有效。 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) 表示。用于以可移植的方式将几何值表示为连续的字节流。值返回为 `bytearray` 对象。 SHAPE@WKT—OGC 几何的熟知文本 (WKT) 表示。用于以可移植的方式将几何值表示为文本字符串。 SHAPE@—要素的几何对象。 SHAPE@AREA—要素的双精度面积。 SHAPE@LENGTH—要素的双精度长度。 CREATED@—要素创建时间的日期时间对象。此字段为只读字段。 CREATOR@—创建要素的用户名字符串。此字段为只读字段。 EDITED@—要素上次编辑时间的日期时间对象。此字段为只读字段。 EDITOR@—上次编辑要素的用户名字符串。此字段为只读字段。 GLOBALID@—要素的通用唯一标识符字符串。此字段为只读字段。 OID@—“对象 ID”字段的值。 SUBTYPE@—整型子类型编码。	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. `with arcpy.da.SearchCursor( in_features, ["OID@", "STREET_NAME"], sql_clause=("DISTINCT STREET_NAME", None) ) as cur: print('Additional code')` Use `TOP` in a prefix clause, and `ORDER BY` in a postfix clause. `with arcpy.da.SearchCursor( in_features, ['OID@', "ELEVATION"], sql_clause=("TOP 5", "ORDER BY ELEVATION DESC") ) as cur: print('Additional code')` Use `GROUP BY` in a postfix clause. `with arcpy.da.SearchCursor( in_features, ['STREET_NAME'], sql_clause=(None, "GROUP BY STREET_NAME") ) as cur: print('Additional code')` 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— Rows are only returned when the `spatial_filter` geometry intersects the input row's geometry. ENVELOPE_INTERSECTS— Rows are only returned when the `spatial_filter` geometry's envelope intersects the input row's geometry. INDEX_INTERSECTS— Rows are only returned when the `spatial_filter` geometry's envelope intersects the index entry for the input row's geometry. Because it uses the underlying index grid, rather than the envelope of the feature, it is faster and is commonly used for return features for display purposes. TOUCHES— Rows are only returned when the `spatial_filter` geometry touches the input row's geometry. OVERLAPS— Rows are only returned when the `spatial_filter` geometry overlaps the input row's geometry. CROSSES— Rows are only returned when the `spatial_filter` geometry crosses the input row's geometry. WITHIN— Rows are only returned when the `spatial_filter` geometry is within the input row's geometry. CONTAINS— Rows are only returned when the `spatial_filter` geometry contains the input row's geometry. (默认值为 INTERSECTS)	String
search_order （可选）	RDBMS 应用空间搜索的顺序。此属性仅影响企业级地理数据库数据，并且仅当指定 `spatial_filter` 参数时才适用。 ATTRIBUTEFIRST—The attribute query will be applied first. SPATIALFIRST— The spatial query will be applied first. (默认值为 ATTRIBUTEFIRST)	String

属性

名称说明数据类型

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

fields

（只读）

游标使用的一组字段名称。

该组将包括由 field_names 参数指定的所有字段和令牌。

fields 属性中字段名称的排序顺序将与 field_names 参数的传递顺序一致。

如果 field_names 参数设置为 * ，则字段属性将包括游标使用的全部字段。 * 值将返回 x,y 坐标元组中的几何（相当于 SHAPE@XY 令牌）。

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(f'{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)]
unique_values = set(values)

print(unique_values)

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(f'Feature {row[0]} has an area of {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
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 示例 5

使用 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]}')

SearchCursor 示例 6

或者，如果数据支持 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]}')

SearchCursor 示例 7

使用 SQL TOP 子句以限制要返回的记录数量。

注:

TOP 子句仅受 SQL Server 数据库的支持。

import arcpy

fc = 'c:/data/base.gdb/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 示例 8

使用 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 示例 9

使用 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]}')

SearchCursor

汇总

讨论

语法

注:

属性

方法

reset()

代码示例

注:

注:

相关主题

`reset()`