サマリー
フィーチャクラスまたはテーブルのレコードに対して読み取り専用アクセスを設定します。
タプルの反復子を返します。 タプルの値の順番は、field_names 引数で指定されたフィールドの順番と一致します。
説明
Geometry オブジェクト プロパティには、フィールドのリストでトークン SHAPE@ を指定することでアクセスできます。
検索カーソルは、for ループを使用して反復処理できます。 検索カーソルは、反復処理をリセットしてロックの削除に役立つ with ステートメントもサポートしています。 ただし、ロックが起こるあらゆる事態を防ぐために、del ステートメントを使用してオブジェクトを削除するか、関数内でカーソルを折り返してカーソル オブジェクトを範囲外に移動することを検討してください。
SearchCursor から返されるレコードは、属性条件または空間条件に一致するように制限できます。
SHAPE@ で完全なジオメトリにアクセスする操作は、コストがかかります。 ポイントの X、Y 座標など、単純なジオメトリ情報のみが必要な場合は、SHAPE@XY、SHAPE@Z、SHAPE@M などのトークンを使用すると、より高速で効率的なアクセスが実現します。
構文
SearchCursor (in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}, {datum_transformation}, {spatial_filter}, {spatial_relationship}, {search_order})| パラメーター | 説明 | データ タイプ |
in_table | フィーチャクラス、レイヤー、テーブル、またはテーブル ビュー。 | String |
field_names [field_names,...] | フィールド名のリスト (またはタプル)。 単一フィールドの場合、文字列のリストの代わりに文字列を使用できます。 フィールドのリストの代わりにアスタリスク (*) を使用すると、入力テーブルのすべてのフィールドにアクセスできます (BLOB フィールドは除きます)。 ただし、パフォーマンスとフィールドの順序の信頼性を高めるために、フィールドのリストは実際に必要なフィールドのみに絞り込むことをお勧めします。 その他の情報には、フィールド名の代わりにトークン (OID@ など) を使用してアクセスできます。
| String |
where_clause | 返されるレコードを制限するオプションの式。 WHERE 句と SQL ステートメントの詳細については、「ArcGIS で使用されるクエリ式への SQL リファレンス」をご参照ください。 (デフォルト値は次のとおりです None) | String |
spatial_reference | フィーチャクラスの空間参照。 この引数を指定すると、フィーチャが入力の空間参照から投影 (または変換) されます。 指定しないと、入力フィーチャクラスの空間参照が使用されます。 この引数に有効な値は、SpatialReference オブジェクトまたはそれに相当する文字列です。 If a spatial reference is specified, but the input feature class has an unknown spatial reference, neither a projection nor transformation can be completed. The geometry returned by the cursor will have coordinates matching the input, with a spatial reference updated to the one specified. (デフォルト値は次のとおりです None) | SpatialReference |
explode_to_points | フィーチャを個々のポイントまたは頂点に分解します。 explode_to_points が True に設定されている場合、たとえば 5 つのポイントがあるマルチポイント フィーチャは 5 つの行で表現されます。 (デフォルト値は次のとおりです False) | Boolean |
sql_clause | リストまたはタプルに編成された、SQL の接頭辞句と接尾辞句のペア。 SQL 接頭辞句は None、DISTINCT、TOP をサポートしています。 SQL 接尾辞句は None、ORDER BY、GROUP BY をサポートしています。 Use DISTINCT in a prefix clause. Use TOP in a prefix clause, and ORDER BY in a postfix clause. Use GROUP BY in a postfix clause. SQL 接頭辞句は最初の位置に配置され、SELECT キーワードと SELECT COLUMN LIST との間に挿入されます。 SQL 接頭辞句は、DISTINCT や ALL などの句で最も多く使用されます。 SQL 接尾辞句は 2 番目の位置に配置され、Where 句に続く SELECT ステートメントに追加されます。 SQL 接尾辞句は、ORDER BY などの句で最も多く使用されます。 注意:DISTINCT、ORDER BY、ALL は、データベースを操作する場合のみサポートされています。 他のデータ ソース (dBASE や INFO テーブルなど) ではサポートされていません。 TOP は、SQL Server データベースでのみサポートされています。 (デフォルト値は次のとおりです (None, None)) | tuple |
datum_transformation | カーソルでフィーチャを 1 つの空間参照から別の空間参照に投影する際に、これらの空間参照が同じ測地基準系を共有していない場合は、適切な測地基準系変換を指定する必要があります。 ListTransformations 関数を使用すると、2 つの空間参照の間で有効な測地基準系変換のリストを表示できます。 (デフォルト値は次のとおりです None) | String |
spatial_filter | フィーチャを空間的にフィルター処理するために使用されるジオメトリ オブジェクト。 この引数を指定すると、カーソルは指定したジオメトリと [spatial_relationship] の値に基づいて、返されるフィーチャを制限します。 (デフォルト値は次のとおりです None) | Geometry |
spatial_relationship | spatial_filter 引数の入力ジオメトリとクエリ ジオメトリ間の空間リレーションシップ。 この引数は、spatial_filter 引数を指定した場合にのみ適用されます。
(デフォルト値は次のとおりです INTERSECTS) | String |
search_order | RDBMS によって空間検索が適用される順序。 このプロパティはエンタープライズ ジオデータベース データにのみ影響し、spatial_filter 引数を指定した場合にのみ適用されます。
(デフォルト値は次のとおりです ATTRIBUTEFIRST) | String |
プロパティ
| プロパティ | 説明 | データ タイプ |
| 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 |
方法の概要
| 方法 | 説明 |
| reset () | Resets the cursor back to the first row. |
方法
reset ()
コードのサンプル
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(f'{row[0]}, {row[1]}, {row[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)]
unique_values = set(values)
print(unique_values)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(f'Feature {row[0]} has an area of {row[1]}')SearchCursor と WHERE 句を使用して、特定の条件を満たすフィーチャを特定します。
import arcpy
fc = 'c:/base/data.gdb/roads'
class_field = 'Road Class'
name_field = 'Name'
# Create an expression with proper delimiters
delimited_field = arcpy.AddFieldDelimiters(fc, name_field)
expression = f'{delimited_field} = 2'
# 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 と 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(f'{row[0]}, {row[1]}')または、データが SQL の ORDER BY 句をサポートしている場合に、sql_clause を使用して並べ替えます。
注意:
ORDER BY 句は、データベースを操作する場合のみサポートされています。 他のデータ ソース (dBASE など) ではサポートされていません。
import arcpy
fc = 'c:/data/base.gdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use ORDER BY sql clause to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=(None, "ORDER BY WELL_ID, WELL_TYPE")) as cursor:
for row in cursor:
print(f'{row[0]}, {row[1]}')SQL の TOP 句を使用して、返されるレコードの数を制限します。
注意:
TOP 句は、SQL Server データベースでのみサポートされています。
import arcpy
fc = 'c:/data/base.mdb/well'
fields = ['WELL_ID', 'WELL_TYPE']
# Use SQL TOP to sort field values
with arcpy.da.SearchCursor(fc, fields, sql_clause=('TOP 3', None)):
for row in cursor:
print(f'{row[0]}, {row[1]}')ジオメトリ オブジェクトで空間フィルターを使って SearchCursor を使用します。
import arcpy
arr = arcpy.Array(
[arcpy.Point(342917.4, 553980.8), arcpy.Point(366915.9, 594749.1)]
)
new_road = arcpy.Polyline(arr, spatial_reference=arcpy.SpatialReference(26971))
fc = r"C:\data\chicago.gdb\houses"
fields = ["ADDRESS", "OCCUPIED"]
with arcpy.da.SearchCursor(
fc, fields, where_clause="OCCUPIED != 'Vacant'", spatial_filter=new_road
) as cursor:
for row in cursor:
print(f'{row[0]}: {row[1]}')別のフィーチャクラスのジオメトリ オブジェクトで空間フィルターを使って、SearchCursor を使用します。
import arcpy
fc = r"c:\connections\sqlserver.sde\DBO.ShipPositions"
fields = ["OBJECTID", "SHIP_NAME"]
searchPoly = [row[0] for row in arcpy.da.SearchCursor("searchArea", ["SHAPE@"])][0]
with arcpy.da.SearchCursor(
fc, fields, spatial_filter=searchPoly, search_order="SPATIALFIRST"
) as cursor:
for row in cursor:
print(f'{row[0]}: {row[1]}')