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}, {load_only})

Параметр	Описание	Тип данных
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, specify an appropriate transformation. Функция 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: print('Additional code') Данное правило также может быть применено к отдельным полям из списка булевых значений. Список значений должен быть той же длины, что и список полей. 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: print('Additional code') (Значение по умолчанию — False)	Boolean
load_only	Specifies whether the spatial index will be maintained. When set to True, the spatial index will be dropped and only the records will be loaded. When the cursor is completed, the spatial index will be recalculated and re-created. When set to False, the spatial index will be maintained during the loading of the records. (Значение по умолчанию — True)	Boolean

Свойства

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

Обзор метода

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

Методы

insertRow (row)

Параметр	Описание	Тип данных
row [row,...]	A list or tuple of values. The order of values must be in the same order as specified when creating the cursor. 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

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

Тип данных	Описание
Integer	insertRow возвращает идентификатор объекта новой строки.

Пример кода

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)])
spatial_ref = arcpy.SpatialReference(26911)  # NAD 1983 UTM Zone 11N
polyline = arcpy.Polyline(array, spatial_ref)

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