SearchRelatedRecords

Synthèse

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.

Syntaxe

SearchRelatedRecords (relationship_class, {oids_to_search}, {origin_fields}, {destination_fields}, {backward})
ParamètreExplicationType de données
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.

(La valeur par défaut est "*")

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@XYTuple des coordonnées x,y du centroïde de l’entité.
  • SHAPE@XYZTuple des coordonnées x,y,z du centroïde de l’entité.
  • SHAPE@TRUECENTROIDTuple des coordonnées x,y du centroïde de l’entité. La valeur renvoyée est la même que celle renvoyée par SHAPE@XY.
  • SHAPE@XDouble de la coordonnée x de l’entité.
  • SHAPE@YDouble de la coordonnée y de l’entité.
  • SHAPE@ZDouble de la coordonnée z de l’entité.
  • SHAPE@MDouble de la valeur m de l’entité.
  • SHAPE@JSONChaîne JSON Esri représentant la géométrie.
  • SHAPE@WKBReprésentation binaire connue (WKB) de la géométrie de l’OGC. Cette représentation constitue une représentation portable d’une valeur de géométrie sous la forme d’un flux contigu d’octets.Les valeurs sont renvoyées en tant qu’objet bytearray.
  • SHAPE@WKTReprésentation textuelle connue (WKT) de la géométrie de l’OGC. Cette représentation constitue une représentation portable d’une valeur de géométrie sous la forme d’une chaîne de texte.
  • SHAPE@Objet géométrie de l’entité.
  • SHAPE@AREADouble de la surface de l’entité.
  • SHAPE@LENGTHDouble de la longueur de l’entité.
  • CREATED@Objet datetime correspondant à la date et à l’heure de création de l’entité. Ce champ est en lecture seule.
  • CREATOR@Chaîne du nom de l’utilisateur ayant créé l’entité. Ce champ est en lecture seule.
  • EDITED@Objet datetime correspondant à la date et à l’heure de la dernière modification de l’entité. Ce champ est en lecture seule.
  • EDITOR@Chaîne du nom du dernier utilisateur ayant modifié l’entité. Ce champ est en lecture seule.
  • GLOBALID@Chaîne de l’identifiant unique universel de l’entité. Ce champ est en lecture seule.
  • OID@Valeur du champ ID d’objet.
  • SUBTYPE@Entier du code de sous-type.

(La valeur par défaut est 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@XYTuple des coordonnées x,y du centroïde de l’entité.
  • SHAPE@XYZTuple des coordonnées x,y,z du centroïde de l’entité.
  • SHAPE@TRUECENTROIDTuple des coordonnées x,y du centroïde de l’entité. La valeur renvoyée est la même que celle renvoyée par SHAPE@XY.
  • SHAPE@XDouble de la coordonnée x de l’entité.
  • SHAPE@YDouble de la coordonnée y de l’entité.
  • SHAPE@ZDouble de la coordonnée z de l’entité.
  • SHAPE@MDouble de la valeur m de l’entité.
  • SHAPE@JSONChaîne JSON Esri représentant la géométrie.
  • SHAPE@WKBReprésentation binaire connue (WKB) de la géométrie de l’OGC. Cette représentation constitue une représentation portable d’une valeur de géométrie sous la forme d’un flux contigu d’octets.Les valeurs sont renvoyées en tant qu’objet bytearray.
  • SHAPE@WKTReprésentation textuelle connue (WKT) de la géométrie de l’OGC. Cette représentation constitue une représentation portable d’une valeur de géométrie sous la forme d’une chaîne de texte.
  • SHAPE@Objet géométrie de l’entité.
  • SHAPE@AREADouble de la surface de l’entité.
  • SHAPE@LENGTHDouble de la longueur de l’entité.
  • CREATED@Objet datetime correspondant à la date et à l’heure de création de l’entité. Ce champ est en lecture seule.
  • CREATOR@Chaîne du nom de l’utilisateur ayant créé l’entité. Ce champ est en lecture seule.
  • EDITED@Objet datetime correspondant à la date et à l’heure de la dernière modification de l’entité. Ce champ est en lecture seule.
  • EDITOR@Chaîne du nom du dernier utilisateur ayant modifié l’entité. Ce champ est en lecture seule.
  • GLOBALID@Chaîne de l’identifiant unique universel de l’entité. Ce champ est en lecture seule.
  • OID@Valeur du champ ID d’objet.
  • SUBTYPE@Entier du code de sous-type.

(La valeur par défaut est 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.

(La valeur par défaut est False)

Boolean

Vue d’ensemble des méthodes

MéthodeExplication
reset ()

Resets the iteration back to the first row.

Méthodes

reset ()

Exemple de code

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)