Курсор – это объект доступа к данным, который может использоваться как для итерации набора строк в таблице, так и для вставки новых строк в таблицу. Курсоры могут быть трех форм: поиска, вставки и обновления. Как правило, курсоры используются для считывания существующей геометрии и записи новых геометрий.
Каждый тип курсора создается соответствующей функцией ArcPy (SearchCursor, InsertCursor или UpdateCursor) в таблице, представлении таблицы, классе объектов или векторном слое. Курсор поиска может использоваться для быстрой выборки строк. Курсор обновления может использоваться для позиционного обновления и удаления строк, тогда как курсор вставки – для вставки строк в таблицу или в класс объекта.
| Курсор | Объяснение |
|---|---|
arcpy.da.InsertCursor(in_table, field_names) | Вставляет строки |
arcpy.da.SearchCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}) | Доступ только для чтения |
arcpy.da.UpdateCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}) | Обновляет или удаляет строки |
Прежние версии:
В ArcGIS 10.1 добавлен новый модуль доступа к данным (arcpy.da). Существовавшие ранее курсоры (в разделе arcpy) также можно использовать и они работают корректно. Однако, новые курсоры arcpy.da имеют значительно более высокое быстродействие. В большинстве случаев использование курсоров arcpy.da в показано справочной системе. Более подробную информацию о классической модели курсора смотрите в таблице ниже.
| Курсор | Объяснение |
|---|---|
arcpy.InsertCursor(dataset, {spatial_reference}) | Вставляет строки |
arcpy.SearchCursor(dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields}) | Доступ только для чтения |
arcpy.UpdateCursor(dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields}) | Обновляет или удаляет строки |
Примечание:
Курсоры учитывают определяющие запросы к представлениям слоев и таблиц и выборки. Объект курсора содержит в этом случае только те строки, которые бы использовались любыми инструментами геообработки в это время.
Курсоры можно перемещать только в направлении вперед. Их нельзя передвинуть назад и выбрать строки, которые уже были выбраны. Если скрипту необходимо выполнить многократные проходы по данным, можно выбрать метод сброса курсора reset.
Курсоры поиска или обновления могут быть итерированы с помощью цикла for. Доступ к следующей строке можно получить с помощью исключительного использования метода next для возврата следующей строки. При использовании метода next для курсора с целью выбора всех строк таблицы с количеством строк n, скрипт должен выполнить количество вызовов n к методу next. Вызов next после получения последней выбранной строки в наборе результатов возвращает исключение StopIteration.
import arcpy
cursor = arcpy.da.SearchCursor(fc, ['fieldA', 'fieldB'])
for row in cursor:
print(row)Курсоры поиска и обновления также поддерживают выражение with.
import arcpy
with arcpy.da.SearchCursor(fc, ['fieldA', 'fieldB']) as cursor:
for row in cursor:
print(row)Все строки, извлеченные из таблицы, выдаются в виде списка значений поля. Значения извлекаются в порядке, предусмотренном аргументом курсора field_names. Свойство fields курсора может также использоваться для подтверждения порядка значений поля.
Объект курсора
SearchCursor, UpdateCursor и InsertCursor создают объект курсора, который может использоваться для итерации записей. Методы объекта курсора, созданного различными функциями курсора, различаются в зависимости от типа созданного курсора.
В таблице ниже представлены методы, поддерживаемые каждым типом курсора:
| Тип курсора | Метод | Влияние на положение |
|---|---|---|
arcpy.da.SearchCursor | reset() | Сбрасывает курсор в исходное положение |
arcpy.da.InsertCursor | insertRow() | Вставляет строку в таблицу |
arcpy.da.UpdateCursor | updateRow() | Обновляет текущую строку |
deleteRow() | Удаляет строку из таблицы | |
reset() | Сбрасывает курсор в исходное положение |
insertRow
Курсор вставки используется для создания и вставки строк. После создания курсора метод insertRow используется для вставки списка или кортежа (tuple) значений, которые создают новую строку. Любому полю в таблице, не включенному в курсор, назначается значение поля по умолчанию.
import arcpy
# Create insert cursor for table
cursor = arcpy.da.InsertCursor("c:/base/data.gdb/roads_lut",
["roadID", "distance"])
# Create 25 new rows. Set the initial row ID and distance values
for i in range(0,25):
cursor.insertRow([i, 100])updateRow
Метод updateRow используется для обновления строки в текущем положении курсора обновления. После возврата строки из объекта курсора можно при необходимости изменить строку и вызвать updateRow, передав измененную строку.
import arcpy
# Create update cursor for feature class
with arcpy.da.UpdateCursor("c:/base/data.gdb/roads",
["roadtype", "distance"]) as cursor:
for row in cursor:
# Update the values in the distance field by multiplying
# the roadtype by 100. Road type is either 1, 2, 3 or 4.
row[1] = row[0] * 100
cursor.updateRow(row)deleteRow
Метод deleteRow используется для удаления строки в текущем положении курсора обновления. После выбора строки, вызовите deleteRow в курсоре для удаления строки.
import arcpy
# Create update cursor for feature class
with arcpy.da.UpdateCursor("c:/base/data.gdb/roads",
["roadtype"]) as cursor:
# Delete all rows that have a roads type of 4
for row in cursor:
if row[0] == 4:
cursor.deleteRow()Доступ к значениям поля и их установка
Для каждого курсора используемые поля предоставляются списком или кортежем имен полей. При возврате строки из курсора, строка возвращается как список значений полей, соответствующих положению указателя.
В примере ниже доступ к названию штата и количеству населения осуществляется по положению.
import arcpy
fc = "c:/base/data.gdb/USA/States"
# Use SearchCursor to access state name and the population count
with arcpy.da.SearchCursor(fc, ['STATE_NAME', 'POP2000']) as cursor:
for row in cursor:
# Access and print the row values by index position.
# state name: row[0]
# population: row[1]
print('{} has a population of {}'.format(row[0], row[1]))Подсказка:
Несмотря на то, что доступ ко всем полям можно получить с помощью звездочки (*), делать это не рекомендуется. Чем больше заданных полей, тем медленнее работает курсор. Включение в список только тех полей, которые будут использоваться, улучшает производительность курсора.
Можно также использовать токены в качестве сокращений вместо имен полей. Все таблицы включают поле ObjectID, которое может иметь множество различных имен в зависимости от типа данных. Простым классам объектов требуется поле геометрии; обычно (но не всегда) это Shape. Токен OID@ может использоваться для доступа к полю ObjectID, а токен SHAPE@, возвращающий объект геометрии, – для доступа к полю геометрии класса объекта без предварительных сведений об имени поля.import arcpy
infc = arcpy.GetParameterAsText(0)
# Enter for loop for each feature
for row in arcpy.da.SearchCursor(infc, ["OID@", "SHAPE@"]):
# Print the current multipoint's ID
print("Feature {}:".format(row[0]))
# For each point in the multipoint feature,
# print the x,y coordinates
for pnt in row[1]:
print("{}, {}".format(pnt.X, pnt.Y))
Дополнительные токены геометрии можно использовать для доступа к конкретным сведениям о геометрии. Доступ к полной геометрии требует больше времени. Если требуются только конкретные свойства геометрии, используйте токены, чтобы предоставить быстрый доступ к свойствам геометрии. Например, SHAPE@XY возвращает кортеж координат x и y, представляющий центроид объекта.
Курсоры и блокировка
Курсоры вставки и обновления соблюдают блокировки таблицы, установленные приложениями ArcGIS. Блокировки предохраняют сложные процессы от изменения одной и той же таблицы одновременно. Существует два типа блокировок, общие и эксклюзивные:
- Общая блокировка применяется в любое время к таблице или набору данных, к которым производится доступ. Несколько общих блокировок может быть создано для таблицы, но если имеется общая блокировка, то создание эксклюзивной блокировки запрещается. Отображение класса объектов и предварительный просмотр таблицы являются примерами общей блокировки.
- Эксклюзивные блокировки применяются при внесении изменений в таблицу или класс объекта. Редактирование и сохранение класса объектов на карте, изменение схемы таблицы или использование курсора вставки для класса объекта в Python IDE являются примерами применения эксклюзивной блокировки в ArcGIS.
Курсоры обновления и вставки не могут быть созданы для таблицы или класса объектов при наличии эксклюзивной блокировки для набора данных. Функции UpdateCursor или InsertCursor выдают ошибку из-за эксклюзивной блокировки набора данных. Если эти функции успешно создают курсор, то они используют эксклюзивную блокировку для набора данных так, чтобы два скрипта не могли создать курсор обновления или вставки для того же набора данных.
В Python блокировка сохраняется до тех пор, пока курсор не будет снят. Иначе все другие приложения или скрипты могли бы неоправданно перекрывать доступ к набору данных. Курсор может быть освобожден одним из следующего:
- При добавлении курсора в выражение with, которое гарантирует снятие блокировок, вне зависимости от того, удачно или неудачно завершилась работа курсора.
- Вызов reset в курсоре.
- Курсор успешно завершен.
- Непосредственное удаление курсора с помощью выражения Python del.
В сеансе редактирования создается общая блокировка данных на время сеанса. Эксклюзивная блокировка применяется при сохранении изменений. Если уже существует эксклюзивная блокировка, то набор данных нельзя редактировать.
Курсоры и поля BLOB
Большой двоичный объект (BLOB) представляет собой некоторую часть данных, хранимую в виде длинной последовательности двоичных чисел. ArcGIS хранит как BLOB аннотации и объекты-размеры, а также такие элементы, как изображения, мультимедиа или фрагменты кода. Курсор можно использовать для загрузки или просмотра содержимого поля BLOB.
В Python поля типа BLOB могут содержать строки, bytearray и memoryviews. При чтении полей BLOB возвращается объект memoryview.
import arcpy
data = open("c:/images/image1.png", "rb").read()
ic = arcpy.da.InsertCursor("c:/data/fgdb.gdb/fc", ['imageblob'])
ic.insertRow([data])import arcpy sc = arcpy.da.SearchCursor("c:/data/fgdb.gdb/fc", ["imageblob"]) memview = sc.next()[0] open("c:/images/image1_copy.png", "wb").write(memview.tobytes())