InsertCursor

摘要

InsertCursor 对象可在要素类或表上建立写入游标。 可以使用 InsertCursor 来添加新行。

了解有关使用游标访问数据的详细信息

说明

对点要素类使用 InsertCursor 时，创建 PointGeometry 对象并将其设置为 SHAPE@ 令牌操作的运算量很大。 此时，使用诸如 SHAPE@XY、SHAPE@Z 和 SHAPE@M 等令牌定义的点要素访问反而更为快速有效。

插入游标支持 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—要素的双精度 x 坐标。 SHAPE@Y—要素的双精度 y 坐标。 SHAPE@Z—要素的双精度 z 坐标。 SHAPE@M—要素的双精度 m 值。 SHAPE@JSON—表示几何的 Esri JSON 字符串。 SHAPE@WKB—OGC 几何的熟知二进制 (WKB) 表示。 用于以可移植的方式将几何值表示为连续的字节流。可将值添加为 bytearray 或 bytes 对象。 SHAPE@WKT—OGC 几何的熟知文本 (WKT) 表示。 用于以可移植的方式将几何值表示为文本字符串。 SHAPE@—要素的几何对象。 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,...]	如果字段具有默认值并且该字段可为空，则使用 True 值将显式覆盖默认值并将空值插入到记录中。 使用 False 值时，将插入默认值而不是空值。 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 将返回新行的对象 ID。

代码示例

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