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}, {datum_transformation})

パラメーター	説明	データ タイプ
in_table	フィーチャクラス、レイヤー、テーブル、またはテーブル ビュー。	String
field_names [field_names,...]	フィールド名のリスト (またはタプル)。 単一フィールドの場合、文字列のリストの代わりに文字列を使用できます。 フィールドのリストの代わりにアスタリスク (*) を使用すると、入力テーブルのすべてのフィールドにアクセスできます (BLOB フィールドは除きます)。 ただし、パフォーマンスとフィールドの順序の信頼性を高めるために、フィールドのリストは実際に必要なフィールドのみに絞り込むことをお勧めします。 その他の情報には、フィールド名の代わりにトークン (OID@ など) を使用してアクセスできます。 SHAPE@XY—フィーチャの重心を表す X 座標と Y 座標の組み合わせ SHAPE@XYZ—フィーチャの重心を表す XYZ 座標の組み合わせ 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) 表現。 ジオメトリ値の汎用的な表現が、連続的なバイト ストリームとして提供されます。値は bytearray オブジェクトとして返されます。 SHAPE@WKT—OGC ジオメトリの WKT (Well-Known Text) 表現。 ジオメトリ値の汎用的な表現が、テキスト文字列として提供されます。 SHAPE@—フィーチャのジオメトリ オブジェクト SHAPE@AREA—フィーチャの面積 (Double) SHAPE@LENGTH—フィーチャの長さ (Double) OID@—Object ID フィールドの値	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. with arcpy.da.SearchCursor( in_features, ["OID@", "STREET_NAME"], sql_clause=("DISTINCT STREET_NAME", None) ) as cur: Use TOP in a prefix clause, and ORDER BY in a postfix clause. with arcpy.da.SearchCursor( in_features, ['OID@', "ELEVATION"], sql_clause=("TOP 5", "ORDER BY ELEVATION DESC") ) as cur: Use GROUP BY in a postfix clause. with arcpy.da.SearchCursor( in_features, ['STREET_NAME'], sql_clause=(None, "GROUP BY STREET_NAME") ) as cur: 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

プロパティ

プロパティ	説明	データ タイプ
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 の例 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 を使用して並べ替えます。

注意:

ORDER BY は、データベースを操作する場合のみサポートされています。 他のデータ ソース (dBASE や INFO テーブルなど) ではサポートされていません。

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 を使用して、返されるレコードの数を制限します。

注意:

TOP は、SQL Server および MS Access データベースでのみサポートされています。

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