Краткая информация
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})| Параметр | Объяснение | Тип данных |
in_table | Входной класс объектов, слой, таблица или табличное представление. | String |
field_names [field_names,...] | Список (или кортеж) имен полей. Для одного поля можно использовать строку вместо списка строк. Используйте символ звездочки (*) вместо списка полей, если вы хотите получить доступ ко всем полям из входной таблицы (растровые поля и поля BLOB исключены). Однако для повышения производительности и улучшения надежности порядка полей рекомендуется сузить список полей до реально необходимых полей. Растровые поля не поддерживаются. Доступ к дополнительной информации можно получить, используя токены (такие как OID@) вместо имен полей:
| 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. (Значение по умолчанию — (None, None)) | tuple |
Свойства
| Свойство | Объяснение | Тип данных |
| fields (только чтение) | Кортеж имен полей, используемых курсором. В кортеж будут включены все поля (и токены), указанные с помощью аргумента field_names. Если аргумент field_names будет иметь значение *, то в свойства полей будут включаться все поля, используемые курсором. Когда используется *, значения геометрии будут выводиться в кортеже координат x и y (аналог токена SHAPE@XY). Порядок имен полей в свойстве fields будет таким же, что и передаваемый порядок в аргументе field_names. | tuple |
Обзор метода
| Метод | Объяснение |
| next () | Возвращает следующую строку в виде кортежа (набора взаимосвязанных величин). Порядок возвращаемых полей зависит от порядка, указанного при создании курсора. |
| reset () | Сбрасывает курсор на первую строку. |
Методы
next ()
Возвращаемое значение
| Тип данных | Объяснение |
| tuple | Следующая строка в виде кортежа. |
reset ()
Пример кода
Пример 1 SearchCursor
Использование 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]))
Пример 2 SearchCursor
Использование 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 {} has an area of {}'.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 = 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 example 5A
Use SearchCursor and the Python sorted method to sort rows.For additional sorting options, see the Python Sorting Mini-HOW TO.
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]))
Пример 5В SearchCursor
Вы также можете выполнить сортировку, используя 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(u'{0}, {1}'.format(row[0], row[1]))
Пример 6 SearchCursor
Используйте команду 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(u'{0}, {1}'.format(row[0], row[1]))