SearchCursor (arcpy.da)
Краткая информация
SearchCursor устанавливает доступ только для чтения к записям, возвращенным из класса пространственных объектов или таблицы.
Возвращает итератор кортежей. Порядок значений в кортеже совпадает с порядком полей, указанных аргументом field_names.
Обсуждение
Доступ к свойствам Геометрия (Geometry) может быть получен путем указания токена 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 префикс поддерживает 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 () |
Сбрасывает курсор на первую строку. |
Методы
| Тип данных | Объяснение |
| 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 и метода 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]))
Вы также можете выполнить сортировку, используя sql_clause, если данные поддерживают команду SQL ORDER BY.
Примечание: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('{0}, {1}'.format(row[0], row[1]))
Используйте команду 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('{0}, {1}'.format(row[0], row[1]))