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})
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

Обзор метода

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

Удаляет текущий ряд.

reset ()

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

updateRow (row)

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

Методы

deleteRow ()
reset ()
updateRow (row)
ParameterОбъяснениеТип данных
row

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

Если при обновлении полей входящие значения совпадают с типом поля, значения будут объявлены необходимыми. Например, значение 1.0 будет добавлено в поле string как "1.0", а значение "25" в поле float будет записано как 25.0.

tuple

Пример кода

Пример 1 UpdateCursor

Используйте 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)
Пример 2 UpdateCursor

Используйте 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.Buffer_analysis(fc, 'roads_buffer', 'BUFFER_DISTANCE')

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