SearchRelatedRecords

Summary

The SearchRelatedRecords object retrieves related records based on the relationship between the origin and destination feature class or table defined in a relationship class.

The object returns an iterator of tuples. Each tuple contains two items: the first item is a row (tuple) from the origin table and the second item is a row (tuple) from the destination table.

Discussion

The SearchRelatedRecords class can be iterated using a for loop. The order that records are yielded may not match the order of the ObjectID values passed to the oids_to_search parameter. The SearchRelatedRecords object also supports with statements to aid in the removal of data locks.

The exact fields returned from each table can be controlled with the origin_fields and destination_fields parameters. Either origin_fields or destination_fields can be omitted individually, but at least one of them must be provided an argument. If one of these parameters is not provided an argument, the other must be provided an argument.

Origin and destination feature class Geometry object properties can be accessed by providing the SHAPE@ token in the respective list of fields. However, accessing full geometry with the SHAPE@ token is a computationally intensive operation. If only simple geometry information is required, such as the x, y coordinates of a point, use tokens such as SHAPE@XY, SHAPE@Z, and SHAPE@M for faster, more efficient access.

By default, the relationship is read in the forward direction. This means that the provided ObjectID values apply to the origin table and are used to find related records in the destination table. To reverse the direction, set the backward parameter to True. Now the provided ObjectID values apply to the destination table and are used to find related records in the origin table.

If no related records are found for a provided ObjectID value, no results will be yielded for that record.

Syntax

SearchRelatedRecords(relationship_class, {oids_to_search}, {origin_fields}, {destination_fields}, {backward})

Name	Explanation	Data type
relationship_class	The path to the relationship class.	String
oids_to_search (Optional)	A list of ObjectID values that will be used to search for related records. Use an asterisk (*) instead of a list of ObjectID values to search for all related records. The default value is "*".	Integer
origin_fields (Optional)	A list (or tuple) of field names. For a single field, you can use a string instead of a list of strings. Use an asterisk (*) instead of a list of fields to access all fields from the input table (BLOB fields are excluded). However, for faster performance and reliable field order, it is recommended that the list of fields be narrowed to only those that are actually needed. Additional information can be accessed using tokens (such as OID@) in place of field names: If no argument is passed to origin_fields, you must pass an argument to destination_fields. ANNO@—An Annotation object for the feature. This option is only valid for ArcGIS Pro annotation feature classes. SHAPE@XY—A tuple of the feature's centroid x,y coordinates. SHAPE@XYZ—A tuple of the feature's centroid x,y,z coordinates. SHAPE@TRUECENTROID—A tuple of the feature's centroid x,y coordinates. This returns the same value as SHAPE@XY. SHAPE@X—A double of the feature's x-coordinate. SHAPE@Y—A double of the feature's y-coordinate. SHAPE@Z—A double of the feature's z-coordinate. SHAPE@M—A double of the feature's m-value. SHAPE@GEOJSON—The GeoJSON representation of the feature's geometry. SHAPE@JSON—The Esri JSON string representing the geometry. SHAPE@WKB—The well-known binary (WKB) representation for OGC geometry. It provides a portable representation of a geometry value as a contiguous stream of bytes. Values are returned as a bytearray object. SHAPE@WKT—The well-known text (WKT) representation for OGC geometry. It provides a portable representation of a geometry value as a text string. SHAPE@—A geometry object for the feature. SUBTYPE@—An integer of the subtype code. SHAPE@AREA—A double of the feature's area. SHAPE@LENGTH—A double of the feature's length. CREATED@—A datetime object of when the feature was created. This field is read-only. CREATOR@—A string of the username that created the feature. This field is read-only. EDITED@—A datetime object of when the feature was last edited. This field is read-only. EDITOR@—A string of the username that last edited the feature. This field is read-only. GLOBALID@—A string of the universal unique identifier of the feature. This field is read-only. OID@—The value of the Object ID field. The default value is None.	String
destination_fields (Optional)	A list (or tuple) of field names. For a single field, you can use a string instead of a list of strings. Use an asterisk (*) instead of a list of fields to access all fields from the input table (BLOB fields are excluded). However, for faster performance and reliable field order, it is recommended that the list of fields be narrowed to only those that are actually needed. Additional information can be accessed using tokens (such as OID@) in place of field names: If no argument is passed to destination_fields, you must pass an argument to origin_fields. ANNO@—An Annotation object for the feature. This option is only valid for ArcGIS Pro annotation feature classes. SHAPE@XY—A tuple of the feature's centroid x,y coordinates. SHAPE@XYZ—A tuple of the feature's centroid x,y,z coordinates. SHAPE@TRUECENTROID—A tuple of the feature's centroid x,y coordinates. This returns the same value as SHAPE@XY. SHAPE@X—A double of the feature's x-coordinate. SHAPE@Y—A double of the feature's y-coordinate. SHAPE@Z—A double of the feature's z-coordinate. SHAPE@M—A double of the feature's m-value. SHAPE@GEOJSON—The GeoJSON representation of the feature's geometry. SHAPE@JSON—The Esri JSON string representing the geometry. SHAPE@WKB—The well-known binary (WKB) representation for OGC geometry. It provides a portable representation of a geometry value as a contiguous stream of bytes. Values are returned as a bytearray object. SHAPE@WKT—The well-known text (WKT) representation for OGC geometry. It provides a portable representation of a geometry value as a text string. SHAPE@—A geometry object for the feature. SUBTYPE@—An integer of the subtype code. SHAPE@AREA—A double of the feature's area. SHAPE@LENGTH—A double of the feature's length. CREATED@—A datetime object of when the feature was created. This field is read-only. CREATOR@—A string of the username that created the feature. This field is read-only. EDITED@—A datetime object of when the feature was last edited. This field is read-only. EDITOR@—A string of the username that last edited the feature. This field is read-only. GLOBALID@—A string of the universal unique identifier of the feature. This field is read-only. OID@—The value of the Object ID field. The default value is None.	String
backward (Optional)	The directionality of the related record search. Set to False to search the relationship from the origin table to the destination table. Set to True to search the relationship from the destination table to the origin table. The default value is False.	Boolean

Methods

reset()

Resets the iteration back to the first row.

Code sample

SearchRelatedRecords example 1

Use the SearchRelatedRecords class to find all the Buildings related to a set of Parcels.

import arcpy

relc = os.path.join(arcpy.env.workspace, "Parcel_Building_Rel")
oids = [2710, 1010]

with arcpy.da.SearchRelatedRecords(relc, oids, origin_fields="APN", destination_fields="BUILDING_NUMBER") as related_records:
    for record in related_records:
        print(record)

SearchRelatedRecords example 2

Use the SearchRelatedRecords class in the backward direction to find Parcels related to a set of Buildings

import arcpy

relc = os.path.join(arcpy.env.workspace, "Parcel_Building_Rel")
oids = [850, 921, 1018, 2301]

with arcpy.da.SearchRelatedRecords(relc, oids, origin_fields="APN", destination_fields="BUILDING_NUMBER", backward=True) as related_records:
    for record in related_records:
        print(record)

SearchRelatedRecords example 3

Use the SearchRelatedRecords class to retrieve attributes using tokens. This example also demonstrates omitting one of the field parameters, which can be useful when you're only interested in the related records.

import arcpy

relc = os.path.join(arcpy.env.workspace, "Parcel_Building_Rel")
oids = [2710]

with arcpy.da.SearchRelatedRecords(relc, oids, destination_fields=["OID@", "SHAPE@AREA"]) as related_records:
    for record in related_records:
        print(record)

SearchRelatedRecords example 4

Use the Python sorted function to sort records returned by SearchRelatedRecords. This example also demonstrates omitting the oids_to_search parameter, which will cause the SearchRelatedRecords class to return all related records.

import arcpy

relc = os.path.join(arcpy.env.workspace, "Parcel_Building_Rel")

for record in sorted(arcpy.da.SearchRelatedRecords(relc, origin_fields="APN", destination_fields=["BUILDING_NUMBER", "POPULATION"])):
    print(record)