SearchRelatedRecords

Zusammenfassung

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.

Diskussion

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

Parameter	Erläuterung	Datentyp
relationship_class	The path to the relationship class.	String
oids_to_search [oids_to_search,...]	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. (Der Standardwert ist "*")	Integer
origin_fields [origin_fields,...]	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. SHAPE@XY—Ein Tupel von XY-Koordinaten für den Feature-Schwerpunkt. SHAPE@XYZ—Ein Tupel von XYZ-Koordinaten für den Feature-Schwerpunkt. SHAPE@TRUECENTROID—Ein Tupel von XY-Koordinaten für den Feature-Schwerpunkt. Dies gibt denselben Wert zurück wie SHAPE@XY. SHAPE@X—X-Koordinate des Features als Zahlenwert (Double). SHAPE@Y—Y-Koordinate des Features als Zahlenwert (Double). SHAPE@Z—Z-Koordinate des Features als Zahlenwert (Double). SHAPE@M—M-Wertes des Features als Zahlenwert (Double). SHAPE@JSON—Die Esri JSON-Zeichenfolge für die Geometrie. SHAPE@WKB—Das Well-known Binary (WKB)-Format für OGC-Geometrie. Es bietet eine übertragbare Darstellung eines Geometriewertes in Form eines zusammenhängenden Datenstroms.Werte werden als bytearray-Objekt zurückgegeben. SHAPE@WKT—Das Well-Known Text (WKT)-Format für OGC-Geometrie. Es bietet eine übertragbare Darstellung eines Geometriewertes in Form einer Textzeichenfolge. SHAPE@—Ein Geometrie-Objekt für das Feature. SHAPE@AREA—Fläche des Features als Zahlenwert (Double). SHAPE@LENGTH—Länge des Features als Zahlenwert (Double). CREATED@—Ein datetime-Objekt für den Zeitpunkt der Erstellung des Features. Dieses Feld ist schreibgeschützt. CREATOR@—Eine Zeichenfolge für den Benutzernamen des Benutzers, der das Feature erstellt hat. Dieses Feld ist schreibgeschützt. EDITED@—Ein datetime-Objekt für den Zeitpunkt der letzten Bearbeitung des Features. Dieses Feld ist schreibgeschützt. EDITOR@—Eine Zeichenfolge für den Benutzernamen des Benutzers, der das Feature zuletzt bearbeitet hat. Dieses Feld ist schreibgeschützt. GLOBALID@—Eine Zeichenfolge für die UUID (Universally Unique Identifier) des Features. Dieses Feld ist schreibgeschützt. OID@—Der Wert des Objekt-ID-Feldes. SUBTYPE@—Der Subtype-Code als ganze Zahl. (Der Standardwert ist None)	String
destination_fields [destination_fields,...]	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. SHAPE@XY—Ein Tupel von XY-Koordinaten für den Feature-Schwerpunkt. SHAPE@XYZ—Ein Tupel von XYZ-Koordinaten für den Feature-Schwerpunkt. SHAPE@TRUECENTROID—Ein Tupel von XY-Koordinaten für den Feature-Schwerpunkt. Dies gibt denselben Wert zurück wie SHAPE@XY. SHAPE@X—X-Koordinate des Features als Zahlenwert (Double). SHAPE@Y—Y-Koordinate des Features als Zahlenwert (Double). SHAPE@Z—Z-Koordinate des Features als Zahlenwert (Double). SHAPE@M—M-Wertes des Features als Zahlenwert (Double). SHAPE@JSON—Die Esri JSON-Zeichenfolge für die Geometrie. SHAPE@WKB—Das Well-known Binary (WKB)-Format für OGC-Geometrie. Es bietet eine übertragbare Darstellung eines Geometriewertes in Form eines zusammenhängenden Datenstroms.Werte werden als bytearray-Objekt zurückgegeben. SHAPE@WKT—Das Well-Known Text (WKT)-Format für OGC-Geometrie. Es bietet eine übertragbare Darstellung eines Geometriewertes in Form einer Textzeichenfolge. SHAPE@—Ein Geometrie-Objekt für das Feature. SHAPE@AREA—Fläche des Features als Zahlenwert (Double). SHAPE@LENGTH—Länge des Features als Zahlenwert (Double). CREATED@—Ein datetime-Objekt für den Zeitpunkt der Erstellung des Features. Dieses Feld ist schreibgeschützt. CREATOR@—Eine Zeichenfolge für den Benutzernamen des Benutzers, der das Feature erstellt hat. Dieses Feld ist schreibgeschützt. EDITED@—Ein datetime-Objekt für den Zeitpunkt der letzten Bearbeitung des Features. Dieses Feld ist schreibgeschützt. EDITOR@—Eine Zeichenfolge für den Benutzernamen des Benutzers, der das Feature zuletzt bearbeitet hat. Dieses Feld ist schreibgeschützt. GLOBALID@—Eine Zeichenfolge für die UUID (Universally Unique Identifier) des Features. Dieses Feld ist schreibgeschützt. OID@—Der Wert des Objekt-ID-Feldes. SUBTYPE@—Der Subtype-Code als ganze Zahl. (Der Standardwert ist None)	String
backward	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. (Der Standardwert ist False)	Boolean

Methodenübersicht

Methode	Erläuterung
reset ()	Resets the iteration back to the first row.

Methoden

reset ()

Codebeispiel

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)