Наверх

SearchCursor

В этом разделе

  1. Сводка
  2. Описание
  3. Синтаксис
  4. Свойства
  5. Обзор метода
  6. Методы
  7. Пример кода
Связанные разделы
  1. UpdateCursor
  2. InsertCursor
  3. Доступ к данным с помощью курсоров

Сводка

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})
ParameterОбъяснениеТип данных
in_table

Входной класс объектов, слой, таблица или табличное представление.

String
field_names
[field_names,...]

Список (или кортеж) имен полей. Для одного поля можно использовать строку вместо списка строк.

Используйте символ звездочки (*) вместо списка полей, если вы хотите получить доступ ко всем полям из входной таблицы (растровые поля и поля BLOB исключены). Однако для повышения производительности и улучшения надежности порядка полей рекомендуется сузить список полей до реально необходимых полей.

Растровые поля не поддерживаются.

Доступ к дополнительной информации можно получить, используя токены (такие как OID@) вместо имен полей:

  • SHAPE@XY —Кортеж x, y координат центроида объекта.
  • SHAPE@XYZ —Кортеж x, y, z координат центроида объекта. Этот токен поддерживается, только если для геометрии включена координата z.
  • SHAPE@TRUECENTROID —Кортеж x, y координат центроида объекта. Выдает такой же результат, что и SHAPE@XY.
  • 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 см. раздел Справочник по 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.

(Значение по умолчанию — (None, None))

tuple

Свойства

ВладениеОбъяснениеТип данных
fields
(только чтение)

Кортеж имен полей, используемых курсором.

В кортеж будут включены все поля (и токены), указанные с помощью аргумента field_names. Если аргумент field_names будет иметь значение *, то в свойства полей будут включаться все поля, используемые курсором. Когда используется *, значения геометрии будут выводиться в кортеже координат x и y (аналог токена SHAPE@XY).

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

tuple

Обзор метода

МетодОбъяснение
reset ()

Сбрасывает курсор на первую строку.

Методы

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])
Пример 5A SearchCursor

Использование 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]))
Пример 5В SearchCursor

Вы также можете выполнить сортировку, используя 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]))
Пример SearchCursor 6

Используйте команду 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]))

Связанные разделы

  • UpdateCursor
  • InsertCursor
  • Доступ к данным с помощью курсоров

Отзыв по этому разделу?

В этом разделе
  1. Сводка
  2. Описание
  3. Синтаксис
  4. Свойства
  5. Обзор метода
  6. Методы
  7. Пример кода
Связанные разделы
  1. UpdateCursor
  2. InsertCursor
  3. Доступ к данным с помощью курсоров