ArcMap

SearchCursor

概要

SearchCursor は、フィーチャクラスまたはテーブルから返されるレコードに対して読み取り専用アクセスを設定します。

タプルの反復子を返します。 タプルの値の順番は、field_names 引数で指定されたフィールドの順番と一致します。

ディスカッション

Geometry プロパティには、フィールドのリストでトークン SHAPE@ を指定することでアクセスできます。

検索カーソルは、for ループを使用して反復処理できます。 検索カーソルは、反復処理をリセットしてロックの削除に役立つ with ステートメントもサポートしています。 ただし、ロックが起こるあらゆる事態を防ぐために、del ステートメントを使用してオブジェクトを削除するか、関数内でカーソルを折り返してカーソル オブジェクトを範囲外に移動することを検討してください。

SearchCursor から返されるレコードは、属性条件または空間条件に一致するように制限できます。

SHAPE@ で完全なジオメトリにアクセスする操作は、コストがかかります。 ポイントの X、Y 座標など、単純なジオメトリ情報のみが必要な場合は、SHAPE@XY、SHAPE@Z、SHAPE@M などのトークンを使用すると、より高速で効率的なアクセスが実現します。

Python 2 では、SearchCursor はループ外の次の行を取得する反復子の next メソッドをサポートしています。 Python 3 では、Python の組み込み next 関数を使用して同等の処理を実行できます。

構文

SearchCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause})
パラメーター説明データ タイプ
in_table

フィーチャクラス、レイヤー、テーブル、またはテーブル ビュー。

String
field_names
[field_names,...]

フィールド名のリスト (またはタプル)。 単一フィールドの場合、文字列のリストの代わりに文字列を使用できます。

入力テーブルのすべてのフィールド (ラスターおよび BLOB フィールドは除きます) にアクセスする場合、フィールドのリストの代わりにアスタリスク (*) を使用します。 ただし、パフォーマンスとフィールドの順序の信頼性を高めるために、フィールドのリストは実際に必要なフィールドのみに絞り込むことをお勧めします。

ラスター フィールドはサポートされていません。

その他の情報には、フィールド名の代わりにトークン (OID@ など) を使用してアクセスできます。

  • SHAPE@XY —フィーチャの重心を表す X 座標と Y 座標の組み合わせ
  • SHAPE@XYZ —フィーチャの重心を表す XYZ 座標の組み合わせ このトークンは、ジオメトリが Z 対応である場合にのみサポートされます。
  • SHAPE@TRUECENTROID —フィーチャの重心を表す X 座標と Y 座標の組み合わせ SHAPE@XY と同じ値が返されます。
  • SHAPE@X —フィーチャの X 座標 (Double)
  • SHAPE@Y —フィーチャの Y 座標 (Double)
  • SHAPE@Z —フィーチャの Z 座標 (Double)
  • SHAPE@M —フィーチャの M 値 (Double)
  • SHAPE@JSON — ジオメトリを表す Esri JSON 文字列
  • SHAPE@WKB —OGC ジオメトリの WKB (Well-Known Binary) 表現。ジオメトリ値の汎用的な表現が、連続的なバイト ストリームとして提供されます。
  • SHAPE@WKT —OGC ジオメトリの WKT (Well-Known Text) 表現。ジオメトリ値の汎用的な表現が、テキスト文字列として提供されます。
  • SHAPE@ —フィーチャのジオメトリ オブジェクト
  • SHAPE@AREA —フィーチャの面積 (Double)
  • SHAPE@LENGTH —フィーチャの長さ (Double)
  • OID@ —ObjectID フィールドの値
String
where_clause

返されるレコードを制限するオプションの条件式。 WHERE 句と SQL ステートメントの詳細については、「クエリ式の作成」をご参照ください。

(デフォルト値は次のとおりです None)

String
spatial_reference

フィーチャクラスの空間参照。 これは、SpatialReference オブジェクトまたは同等の文字列を使用して指定できます。

(デフォルト値は次のとおりです None)

SpatialReference
explode_to_points

フィーチャを個々のポイントまたは頂点に分解します。 explode_to_points が True に設定されている場合、たとえば 5 つのポイントがあるマルチポイント フィーチャは 5 つの行で表現されます。

(デフォルト値は次のとおりです False)

Boolean
sql_clause

リストまたはタプルに編成された SQL の接頭辞句と接尾辞句のオプションのペア。

An SQL prefix clause supports None, DISTINCT, and TOP. An SQL postfix clause supports None, ORDER BY, and GROUP BY.

SQL の接頭辞句は、最初の位置に配置され、SELECT キーワードと SELECT COLUMN LIST の間に挿入されます。 SQL の接頭辞句は、DISTINCT または ALL などの句に最もよく使用されます。

SQL の接尾辞句は、2 番目の位置に配置され、WHERE 句に続く SELECT ステートメントに追加されます。 SQL の接尾辞句は、ORDER BY などの句に最もよく使用されます。

(デフォルト値は次のとおりです (None, None))

tuple

プロパティ

プロパティ説明データ タイプ
fields
(読み取り専用)

A tuple of field names used by the cursor.

The tuple will include all fields and tokens specified by the field_names argument.

The order of the field names on the fields property will be the same as passed in with the field_names argument.

If the field_names argument is set to *, the fields property will include all fields used by the cursor. A value of * will return geometry in a tuple of x,y coordinates (equivalent to the SHAPE@XY token).

tuple

手法の概要

手法説明
next ()

Returns the next row as a tuple. The order of fields will be returned in the order they were specified when creating the cursor.

reset ()

Resets the cursor back to the first row.

手法

next ()

戻り値

データ タイプ説明
tuple

The next row as a tuple.

reset ()

コードのサンプル

SearchCursor の例 1

SearchCursor を使用して、フィーチャクラスを移動して、特定のフィールド値とポイントの X、Y 座標を印刷します。

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE', 'SHAPE@XY']

# For each row, print the WELL_ID and WELL_TYPE fields, and
# the feature's x,y coordinates
with arcpy.da.SearchCursor(fc, fields) as cursor:
    for row in cursor:
        print(u'{0}, {1}, {2}'.format(row[0], row[1], row[2]))
SearchCursor の例 2

SearchCursor を使用して、一意のフィールド値のセットを返します。

import arcpy

fc = 'c:/data/base.gdb/well'
field = 'Diameter'

# Use SearchCursor with list comprehension to return a
# unique set of values in the specified field
values = [row[0] for row in arcpy.da.SearchCursor(fc, field)]
uniqueValues = set(values)

print(uniqueValues)
SearchCursor の例 3

SearchCursor を使用して、トークンを使って属性を返します。

import arcpy

fc = 'c:/data/base.gdb/well'

# For each row, print the Object ID field, and use the SHAPE@AREA
#  token to access geometry properties
with arcpy.da.SearchCursor(fc, ['OID@', 'SHAPE@AREA']) as cursor:
    for row in cursor:
        print('Feature {} has an area of {}'.format(row[0], row[1]))
SearchCursor の例 4

SearchCursor と WHERE 句を使用して、特定の条件を満たすフィーチャを特定します。

import arcpy

fc = 'c:/base/data.gdb/roads'
class_field = 'Road Class'
name_field = 'Name'

# Create an expression with proper delimiters
expression = u'{} = 2'.format(arcpy.AddFieldDelimiters(fc, name_field))

# Create a search cursor using an SQL expression
with arcpy.da.SearchCursor(fc, [class_field, name_field],
                           where_clause=expression) as cursor:
    for row in cursor:
        # Print the name of the residential road
        print(row[1])
SearchCursor の例 5A

SearchCursor と Python の sorted メソッドを使用して、行を並べ替えます。その他の並べ替えオプションについては、Python の「Sorting Mini-HOW TO」をご参照ください。

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']

# Use Python's sorted method to sort rows
for row in sorted(arcpy.da.SearchCursor(fc, fields)):
    print(u'{0}, {1}'.format(row[0], row[1]))
SearchCursor の例 5B

または、データが SQL の ORDER BY をサポートしている場合に、sql_clause を使用して並べ替えます。

import arcpy

fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']

# Use ORDER BY sql clause to sort field values
for row in arcpy.da.SearchCursor(
        fc, fields, sql_clause=(None, 'ORDER BY WELL_ID, WELL_TYPE')):
    print(u'{0}, {1}'.format(row[0], row[1]))
SearchCursor の例 6

SQL の TOP を使用して、返されるレコードの数を制限します。

import arcpy

fc = 'c:/data/base.mdb/well'
fields = ['WELL_ID', 'WELL_TYPE']

# Use SQL TOP to sort field values
for row in arcpy.da.SearchCursor(fc, fields, sql_clause=('TOP 3', None)):
    print(u'{0}, {1}'.format(row[0], row[1]))

関連トピック