Skip to main content

SearchCursor

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

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

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

Дополнительные сведения о доступе к данным посредством курсоров

Обсуждение

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

Курсоры поиска могут быть итерированы с помощью цикла for. Курсоры поиска также поддерживают выражения with для сброса итераций и снятия блокировок. Однако использование выражения del удаляет объект или заводит курсор в функцию для того, чтобы объект-курсор вышел из области применения, нужно принять во внимание настройки безопасности в случае блокировок.

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

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

Синтаксис

SearchCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation}, {spatial_filter}, {spatial_relationship}, {search_order})

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

in_table

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

String

field_names

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

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

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

  • ANNO@—Объект Annotation для этого объекта. Эта опция действительна только для классов объектов аннотаций ArcGIS Pro.

  • SHAPE@XY—Кортеж x, y координат центроида объекта.

  • SHAPE@XYZ—Кортеж x, y, 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. Он обеспечивает портативное представление значения геометрии в виде непрерывного потока байтов.Значения будут возвращены как объект bytearray.

  • SHAPE@WKT—Стандартное текстовое (well-known text, WKT) представление для геометрии OGC. Он обеспечивает портативное представление значения геометрии в виде текстовой строки.

  • SHAPE@—Объект geometry (геометрия) для пространственного объекта.

  • SHAPE@AREA—Значение двойной точности для площади объекта.

  • SHAPE@LENGTH—Значение двойной точности для длины объекта.

  • CREATED@—Объект даты и времени, когда объект был создан. Это поле доступно только для чтения.

  • CREATOR@—Строка имени пользователя, создавшего объект. Это поле доступно только для чтения.

  • EDITED@—Объект даты и времени, указывающий на последнее редактирование объекта. Это поле доступно только для чтения.

  • EDITOR@—Строка имени пользователя, который последний раз редактировал объект. Это поле доступно только для чтения.

  • GLOBALID@—Строка универсального уникального идентификатора объекта. Это поле доступно только для чтения.

  • OID@—Значение поля Object ID.

  • SUBTYPE@—Целое число кода подтипа.

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.

with arcpy.da.SearchCursor(
        in_features,
        ["OID@", "STREET_NAME"],
        sql_clause=("DISTINCT STREET_NAME", None)
) as cur:
    print('Additional code')

Use TOP in a prefix clause, and ORDER BY in a postfix clause.

with arcpy.da.SearchCursor(
        in_features,
        ['OID@', "ELEVATION"],
        sql_clause=("TOP 5", "ORDER BY ELEVATION DESC")
) as cur:
    print('Additional code')

Use GROUP BY in a postfix clause.

with arcpy.da.SearchCursor(
        in_features,
        ['STREET_NAME'],
        sql_clause=(None, "GROUP BY STREET_NAME")
) as cur:
    print('Additional code')

Префикс 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

spatial_filter

(Дополнительный)

Объект геометрии для пространственной фильтрации объекта. Если указан этот аргумент, курсор будет ограничивать возвращаемые объекты, основываясь на указанной геометрии и значении spatial_relationship.

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

Geometry

spatial_relationship

(Дополнительный)

Пространственное отношение между входной и запрашиваемой геометрией в аргументе spatial_filter. Этот аргумент используется только при задании аргумента spatial_filter.

  • INTERSECTS— Rows are only returned when the spatial_filter geometry intersects the input row's geometry.

  • ENVELOPE_INTERSECTS— Rows are only returned when the spatial_filter geometry's envelope intersects the input row's geometry.

  • INDEX_INTERSECTS— Rows are only returned when the spatial_filter geometry's envelope intersects the index entry for the input row's geometry. Because it uses the underlying index grid, rather than the envelope of the feature, it is faster and is commonly used for return features for display purposes.

  • TOUCHES— Rows are only returned when the spatial_filter geometry touches the input row's geometry.

  • OVERLAPS— Rows are only returned when the spatial_filter geometry overlaps the input row's geometry.

  • CROSSES— Rows are only returned when the spatial_filter geometry crosses the input row's geometry.

  • WITHIN— Rows are only returned when the spatial_filter geometry is within the input row's geometry.

  • CONTAINS— Rows are only returned when the spatial_filter geometry contains the input row's geometry.

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

String

search_order

(Дополнительный)

Порядок, в котором СУБД будет применять пространственный поиск. Это свойство влияет только на данные многопользовательской базы геоданных и применимо только при указании аргумента spatial_filter.

  • ATTRIBUTEFIRST—The attribute query will be applied first.

  • SPATIALFIRST— The spatial query will be applied first.

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

String

Свойства

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

fields

(Только для чтения)

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

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

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

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

tuple

Методы

reset()

Метод 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 feature's x,y coordinates
with arcpy.da.SearchCursor(fc, fields) as cursor:
    for row in cursor:
        print(f'{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)]
unique_values = set(values)

print(unique_values)
SearchCursor, пример 3

Использует 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(f'Feature {row[0]} has an area of {row[1]}')
SearchCursor, пример 4

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

import arcpy

fc = 'c:/base/data.gdb/roads'
class_field = 'Road Class'
name_field = 'Name'

# Create an expression with proper delimiters
delimited_field = arcpy.AddFieldDelimiters(fc, name_field)
expression = f'{delimited_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, пример 5

Использует SearchCursor и метода Python sorted для сортировки строк.

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

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

Примечание:

Запрос ORDER BY поддерживается только при работе с базами данных. Другие источники данных, такие как таблицы dBASE, эти команды не поддерживаются.

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']

# Use ORDER BY sql clause to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=(None, "ORDER BY WELL_ID, WELL_TYPE")) as cursor:
    for row in cursor:
        print(f'{row[0]}, {row[1]}')
SearchCursor, пример 7

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

Примечание:

Команда TOP поддерживается только базами данных SQL Server.

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']

# Use SQL TOP to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=('TOP 3', None)):
    for row in cursor:
        print(f'{row[0]}, {row[1]}')
SearchCursor, пример 8

Использует SearchCursor с пространственным фильтром с объектом геометрии.

import arcpy

arr = arcpy.Array(
    [arcpy.Point(342917.4, 553980.8), arcpy.Point(366915.9, 594749.1)]
)
new_road = arcpy.Polyline(arr, spatial_reference=arcpy.SpatialReference(26971))

fc = r"C:\data\chicago.gdb\houses"
fields = ["ADDRESS", "OCCUPIED"]

with arcpy.da.SearchCursor(
    fc, fields, where_clause="OCCUPIED != 'Vacant'", spatial_filter=new_road
) as cursor:
    for row in cursor:
        print(f'{row[0]}: {row[1]}')
SearchCursor, пример 9

Использует SearchCursor с пространственным фильтром с объектом геометрии другого класса пространственных объектов.

import arcpy

fc = r"c:\connections\sqlserver.sde\DBO.ShipPositions"
fields = ["OBJECTID", "SHIP_NAME"]
searchPoly = [row[0] for row in arcpy.da.SearchCursor("searchArea", ["SHAPE@"])][0]

with arcpy.da.SearchCursor(
    fc, fields, spatial_filter=searchPoly, search_order="SPATIALFIRST"
) as cursor:
    for row in cursor:
        print(f'{row[0]}: {row[1]}')