InsertCursor

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

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

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

Обсуждение

При использовании InsertCursor в классе точечных объектов создание PointGeometry и установка токена SHAPE@ является относительно затратной операцией. Для более быстрого и эффективного доступа можно определить точечный объект с помощью таких токенов, как SHAPE@XY, SHAPE@Z и SHAPE@M.

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

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

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

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

Примечание:

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

Когда поле имеет значение по умолчанию, курсор применяет значение по умолчанию, если поле не указано или установлено на None.

Синтаксис

 InsertCursor (in_table, field_names, {datum_transformation}, {explicit})

Параметр	Описание	Тип данных
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 или bytes. SHAPE@WKT—Стандартное текстовое (well-known text, WKT) представление для геометрии OGC. Он обеспечивает портативное представление значения геометрии в виде текстовой строки. SHAPE@—Объект geometry (геометрия) для пространственного объекта. SUBTYPE@—Целое число кода подтипа. Polygon, polyline, or multipoint features can only be created using the SHAPE@ token.	String
datum_transformation	When features to be inserted have a different spatial reference than the target feature class, a projection will be performed automatically. If the two spatial references have a different datum, an appropriate transformation should be specified. Функция ListTransformations может использоваться для предоставления списка допустимых преобразований данных между двумя пространственными привязками. Более подробно о преобразовании датума	String
explicit [explicit,...]	Если поле имеет значение по умолчанию, и это поле может содержать значение null, использование значения True обязательно отменит значение по умолчанию и вставит в эту запись значения null. При использовании значения False вместо значения null будет вставлено значение по умолчанию. Apply the explicit rule to all fields: with arcpy.da.InsertCursor(table, [field1, field2, field3], explicit=True) as cursor: ... Данное правило также может быть применено к отдельным полям из списка булевых значений. Список значений должен быть той же длины, что и список полей. Apply the explicit rule to only the first two fields specified: with arcpy.da.InsertCursor(table, [field1, field2, field3], explicit=[True, True, False]) as cursor: # ... (Значение по умолчанию — False)	Boolean

Свойства

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

Обзор метода

Метод	Описание
insertRow (row)	Вставляет строку в таблицу.

Методы

insertRow (row)

Параметр	Описание	Тип данных
row [row,...]	Список или кортеж значений. Порядок значений должен соответствовать тому, что был задан при создании курсора. Если при обновлении полей входящие значения совпадают с типом поля, значения будут объявлены необходимыми. Например, значение 1.0 будет добавлено в поле string как "1.0", а значение "25" в поле float будет записано как 25.0.	tuple

Возвращаемое значение

Тип данных	Описание
Integer	Метод insertRow возвращает значение objectid для нового поля.

Пример кода

InsertCursor, пример 1

InsertCursor используется для вставки новых строк в таблицу.

import arcpy
import datetime

# Create an insert cursor for a table specifying the fields that will
# have values provided
fields = ['rowid', 'distance', 'CFCC', 'DateInsp']

with arcpy.da.InsertCursor('D:/data/base.gdb/roads_maint', fields) as cursor:

    # Create 25 new rows. Set default values on distance and CFCC code
    for x in range(0, 25):
        cursor.insertRow((x, 100, 'A10', datetime.datetime.now()))

InsertCursor, пример 2

Использование InsertCursor с токеном SHAPE@XY для добавления точечных объектов в класс точечных объектов.

import arcpy

# A list of values that will be used to construct new rows
row_values = [('Anderson', (1409934.4442000017, 1076766.8192000017)),
              ('Andrews', (752000.2489000037, 1128929.8114))]

# Open an InsertCursor using a context manager
with arcpy.da.InsertCursor('C:/data/texas.gdb/counties', ['NAME', 'SHAPE@XY']) as cursor:

    # Insert new rows that include the county name and a x,y coordinate
    #  pair that represents the county center
    for row in row_values:
        cursor.insertRow(row)

Пример InsertCursor 3

Использование InsertCursor с токеном SHAPE@ для добавления нового объекта с помощью объекта геометрии.

import arcpy

# Create a polyline geometry
array = arcpy.Array([arcpy.Point(459111.6681, 5010433.1285),
                     arcpy.Point(472516.3818, 5001431.0808),
                     arcpy.Point(477710.8185, 4986587.1063)])
polyline = arcpy.Polyline(array)

# Open an InsertCursor using a context manager and insert the new geometry
with arcpy.da.InsertCursor('C:/data/texas.gdb/counties', ['SHAPE@']) as cursor:
    cursor.insertRow([polyline])