InsertCursor

摘要

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

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

说明

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

插入游标支持 with 语句以帮助移除锁。 但是，为了防止锁定所有内容，您也可以使用 del 语句来删除游标对象或将游标包含在函数中以使游标对象位于范围之外。

使用不同游标在同一个工作空间上开启同步插入或更新操作时，需要启动编辑会话。

以下列出了只能在编辑会话中编辑的一些数据集类型：

• 参与拓扑的要素类
• 参与几何网络的要素类
• 参与网络数据集的要素类
• 企业级地理数据库中的版本化数据集
• 一些带有类扩展的对象和要素类

注：

不支持在包含连接表的图层上使用 InsertCursor。

当字段具有默认值时，如果该字段未指定或设置为 None，则光标将应用该默认值。

语法

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

参数	说明	数据类型
in_table	要素类、图层、表或表视图。	String
field_names [field_names,...]	字段名称列表（或组）。 对于单个字段，可以使用一个字符串，而不使用字符串列表。 要访问输入表中的所有字段（BLOB 字段除外），可以使用星号 (*) 代替字段列表。 但是，为了获得较快的性能和可靠的字段顺序，建议您将字段列表限制在实际需要的字段。 不支持栅格字段。 以令牌（如 OID@）取代字段名称可访问更多的信息： 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, an appropriate transformation should be specified. 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: ... 显式规则也可以应用于使用布尔值列表的各个字段。 值列表的长度必须与字段列表的长度相同。 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 添加到字符串字段将添加为 "1.0"；将值 "25" 添加到浮点型字段将添加为 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])