Skip to main content

UpdateCursor

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

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

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

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

Обсуждение

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

Для одновременного начала операций вставки и/или обновления в одной рабочей области с использованием разных курсоров необходимо открыть сеанс редактирования.

Далее представлены некоторые типы наборов данных, которые можно изменять только в ходе сеанса редактирования:

  • Классы объектов, участвующие в топологии

  • Классы объектов, участвующие в геометрической сети

  • Классы объектов, участвующие в наборе сетевых данных

  • Версионные наборы данных в многопользовательских базах геоданных

  • Определенные объекты и классы пространственных объектов с расширениями

В Python 2 UpdateCursor поддерживает итератор метода next для получения следующей строки за пределами цикла. В Python 3 аналогичная операция выполняется с помощью встроенной в Python функции next.

Примечание:

Инструмент Вычислить поле и Вычислить поля можно использовать для обновления значений полей.

Примечание:

Использование UpdateCursor в слое с присоединенной таблицей не поддерживается.

Синтаксис

UpdateCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation}, {explicit}, {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, но должны быть обновлены как объект bytearray или bytes.

  • 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 или эквивалент строки.

(Значение по умолчанию — 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 for a table located in a file geodatabase. DISTINCT is not honored in a relational database.

with arcpy.da.UpdateCursor(
        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.UpdateCursor(
        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.UpdateCursor(
        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

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

Когда курсор проецирует объекты из одной пространственной привязки в другую, если пространственные привязки не имеют общих данных, следует указать соответствующее преобразование датума.

An update cursor can perform a projection or transformation at two stages: when reading the features from the feature class on disk and when writing the updated features to the feature class.

Функция ListTransformations может использоваться для предоставления списка допустимых преобразований данных между двумя пространственными привязками.

Более подробно о преобразовании датума

String

explicit

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

Если поле имеет значение по умолчанию, и это поле может содержать значение null, использование значения True обязательно отменит значение по умолчанию и вставит в эту запись значения null. При использовании значения False вместо значения null будет вставлено значение по умолчанию.

Apply the explicit rule to all fields:

with arcpy.da.UpdateCursor(table, [field1, field2, field3], explicit=True) as cursor:
    print('Additional code')

Данное правило также может быть применено к отдельным полям из списка булевых значений. Список значений должен быть той же длины, что и список полей.

Apply the explicit rule to only the first two fields:

with arcpy.da.UpdateCursor(table, [field1, field2, field3], explicit=[True, True, False]) as cursor:
    print('Additional code')

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

Boolean

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

Методы

deleteRow()

Удаляет текущую строку.

reset()

Метод reset возвращает курсор обратно к первой строке.

updateRow(row)

Обновляет текущую строку в таблице.

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

row

A list or tuple of values. The order of values should be in the same order as the fields.

When updating fields, if the incoming values match the type of field, the values will be cast as necessary. For example, a value of 1.0 to a string field will be added as "1.0", and a value of "25" added to a float field will be added as 25.0.

tuple

Пример кода

UpdateCursor, пример 1

Используйте UpdateCursor для обновления значения поля за счет вычисления значений других полей.

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_YIELD', 'WELL_CLASS']

# Create update cursor for feature class
with arcpy.da.UpdateCursor(fc, fields) as cursor:
    # For each row, evaluate the WELL_YIELD value (index position
    # of 0), and update WELL_CLASS (index position of 1)
    for row in cursor:
        if (row[0] >= 0 and row[0] <= 10):
            row[1] = 1
        elif (row[0] > 10 and row[0] <= 20):
            row[1] = 2
        elif (row[0] > 20 and row[0] <= 30):
            row[1] = 3
        elif (row[0] > 30):
            row[1] = 4

        # Update the cursor with the updated list
        cursor.updateRow(row)
UpdateCursor, пример 2

Используйте UpdateCursor для обновления поля буферных расстояний, используемых с функцией Буфер.

import arcpy

arcpy.env.workspace = 'c:/data/output.gdb'
fc = 'c:/data/base.gdb/roads'
fields = ['ROAD_TYPE', 'BUFFER_DISTANCE']

# Create update cursor for feature class
with arcpy.da.UpdateCursor(fc, fields) as cursor:
    # Update the field used in Buffer so the distance is based on road
    # type. Road type is either 1, 2, 3, or 4. Distance is in meters.
    for row in cursor:
        # Update the BUFFER_DISTANCE field to be 100 times the
        # ROAD_TYPE field.
        row[1] = row[0] * 100
        cursor.updateRow(row)

# Buffer feature class using updated field values
arcpy.analysis.Buffer(fc, 'roads_buffer', 'BUFFER_DISTANCE')
UpdateCursor, пример 3

Используйте UpdateCursor с пространственным фильтром, чтобы обновить значения поля.

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 = ["OCCUPIED"]

with arcpy.da.UpdateCursor(
    fc, fields, where_clause="OCCUPIED != 'Vacant'", spatial_filter=new_road
) as cursor:
    for row in cursor:
        row[0] = 'Vacant'
        cursor.updateRow(row)