SearchCursor

Краткая информация

SearchCursor устанавливает доступ только для чтения к записям, возвращенным из класса пространственных объектов или таблицы.

Возвращает итератор кортежей. Порядок значений в кортеже совпадает с порядком полей, указанных аргументом field_names.

Описание

Доступ к свойствам Геометрия (Geometry) может быть получен путем указания токена SHAPE@ в списке полей.

Курсоры поиска могут быть итерированы с помощью цикла For.

Записи, возвращаемые курсором SearchCursor, могут быть отфильтрованы по атрибутивному и/или пространственному критерию.

Доступ к полной геометрии SHAPE@ – это затратная операция. Если требуется только простая информация о геометрии, например, координаты x и y точки, используйте для более быстрого и эффективного доступа такие токены, как SHAPE@XY, SHAPE@Z и SHAPE@M.

Примечание:

arcpy.da.SearchCursor не следует путать с arcpy.SearchCursor.

Синтаксис

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

Параметр	Объяснение	Тип данных
in_table	Входной класс объектов, слой, таблица или табличное представление.	String
field_names [field_names,...]	Список (или кортеж) имен полей. Для одного поля можно использовать строку вместо списка строк. Используйте символ звездочки (*) вместо списка полей, если вы хотите получить доступ ко всем полям из входной таблицы (растровые поля и поля BLOB исключены). Однако для повышения производительности и улучшения надежности порядка полей рекомендуется сузить список полей до реально необходимых полей. Растровые поля не поддерживаются. Доступ к дополнительной информации можно получить, используя токены (такие как OID@) вместо имен полей: SHAPE@XY —Кортеж x, y координат центроида объекта. SHAPE@TRUECENTROID —Кортеж x, y координат истинного центроида объекта. SHAPE@X —Значение двойной точности координаты х объекта. SHAPE@Y —Значение двойной точности координаты y объекта. SHAPE@Z —Значение двойной точности координаты z объекта. SHAPE@M —Значение двойной точности m для объекта. SHAPE@JSON — Строка esri JSON, представляющая геометрию. SHAPE@WKB —Стандартное двоичное (well-known binary, WKB) представление для геометрии OGC. Он обеспечивает портативное представление значения геометрии в виде непрерывного потока байтов. SHAPE@WKT —Стандартное текстовое (well-known text, WKT) представление для геометрии OGC. Он обеспечивает портативное представление значения геометрии в виде текстовой строки. SHAPE@ —Объект geometry (геометрия) для пространственного объекта. SHAPE@AREA —Значение двойной точности для площади объекта. SHAPE@LENGTH —Значение двойной точности для длины объекта. OID@ —Значение поля ObjectID.	String
where_clause	Возвращается дополнительное выражение, которое ограничивает записи. Более подробно об условиях WHERE и выражениях 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, и GROUPBY. Префикс SQL располагается в первой позиции и будет вставлен между ключевым словом SELECT и SELECT COLUMN LIST. Префикс выражения SQL чаще всего используется для таких выражений, как DISTINCT и ALL. Постфикс SQL располагается во второй позиции и добавляется к инструкции SELECT после выражения where. Постфикс выражения SQL чаще всего используется для таких выражений, как ORDER BY. Примечание: DISTINCT, ORDER BY и ALL поддерживаются только при работе с базами данных. Другие источники данных, такие как таблицы dBASE или INFO, эти команды не поддерживают. Команда TOP поддерживается только базами данных SQL Server и MS Access. (Значение по умолчанию — (None, None))	tuple

Свойства

Свойство	Объяснение	Тип данных
fields (только чтение)	Список (или кортеж) имен полей, используемых курсором. В кортеж будут включены все поля (и токены), указанные аргументом field_names. Если аргумент field_names будет иметь значение "*", то в свойства полей будут включаться все поля, используемые курсором. Когда используется "*", значения геометрии будут выводиться в кортеже координат x и y (эквивалент токену SHAPE@XY).	tuple

Обзор метода

Метод	Объяснение
next ()	Возвращает следующую строку в виде кортежа (набора взаимосвязанных величин). Порядок возвращаемых полей зависит от порядка, указанного при создании курсора.
reset ()	Сбрасывает курсор на первую строку.

Методы

next ()

Возвращаемое значение

Тип данных	Объяснение
tuple

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
# 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 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)

Пример 3 SearchCursor

Использование 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]))

Пример 4 SearchCursor

Использование 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 5A

Использование SearchCursor и метода sorted Python для сортировки строк.Сведения о дополнительных опциях сортировки см. в Sorting Mini-HOW TO для языка 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('{0}, {1}'.format(row[0], row[1]))

Пример SearchCursor 5В

Вы также можете выполнить сортировку, используя sql_clause, если данные поддерживают команду SQL ORDER BY.

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

Пример SearchCursor 6

Используйте команду SQL TOP, чтобы ограничить число возвращаемых записей.

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