Краткая информация
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@) вместо имен полей:
| String |
where_clause | Возвращается дополнительное выражение, которое ограничивает записи. Более подробно о выражении WHERE и о условиях SQL см. в разделе Справочник по SQL для выражений запросов, применяемых в ArcGIS. (Значение по умолчанию — 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.
Use TOP in a prefix clause, and ORDER BY in a postfix clause.
Use GROUP BY in a postfix clause.
Префикс 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. Порядок имен полей в свойстве fields будет таким же, что и передаваемый порядок в аргументе field_names. Если аргумент field_names будет иметь значение *, то в свойства полей будут включаться все поля, используемые курсором. Значение * вернет геометрию в кортеже координат x, y (эквивалентно токену SHAPE@XY). | tuple |
Обзор метода
Метод | Описание |
reset () | Сбрасывает курсор на первую строку. |
Методы
reset ()
Пример кода
Использование 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 для возврата набора уникальных значений полей.
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 {} has an area of {}'.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 = 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 и метода 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(u'{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(u'{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(u'{0}, {1}'.format(row[0], row[1]))