Наверх

UpdateCursor

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

  1. Краткая информация
  2. Обсуждение
  3. Синтаксис
  4. Свойства
  5. Обзор метода
  6. Методы
  7. Пример кода
Связанные разделы
  1. SearchCursor
  2. InsertCursor

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

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
[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:

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:

Use GROUP BY in a postfix clause.

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

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

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

Apply the explicit rule to only the first two fields:

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

(Значение по умолчанию — 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 ()

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

updateRow (row)

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

Методы

deleteRow ()
reset ()
updateRow (row)
ПараметрОписаниеТип данных
row

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

Если при обновлении полей входящие значения совпадают с типом поля, значения будут объявлены необходимыми. Например, значение 1.0 будет добавлено в поле string как "1.0", а значение "25" в поле float будет записано как 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)

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

  • SearchCursor
  • InsertCursor

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

В этом разделе
  1. Краткая информация
  2. Обсуждение
  3. Синтаксис
  4. Свойства
  5. Обзор метода
  6. Методы
  7. Пример кода
Связанные разделы
  1. SearchCursor
  2. InsertCursor