Relate features

You can relate a feature in one table to a feature in another table for a variety of reasons, such as to allow your users to view information in one table for features in another table. For example, a user may be interested in a list of species that live in a national park where park and species information are each in different, but related, layers.

Alaska park table related to species table

When you relate features, you're editing them because the relate operation adds an attribute to the destination feature. The relate operation associates the two tables by adding a keyField attribute in the destination feature based on the corresponding origin feature. The keyField value is the origin table feature's primary key or global ID. In this parks example, relating a park to species (one to many) adds the keyField value of the parks feature in the Alaska National Parks layer (origin table) to the corresponding (Park_Name) field in the species feature in the Alaska National Parks Species layer (destination table).

The tables of the two features you want to relate must be in a table relationship with each other (must be related tables). Table relationships are created using ArcGIS Pro or using ArcMap.

The pattern for editing a feature to relate it to another is the same as for editing any feature, as described in the Edit features topic, whether the feature is the origin feature in a table relationship or the destination feature. The part of the edit that sets up the relate is described below in the Relate two features section. When tables participate in a relationship like this, you can also perform other editing-oriented operations: unrelating features and validating relationship constraints.

Other considerations, such as supported data sources, are in the Additional information section below.

Relate two features

You use ArcGISFeature.relate to relate a feature in one table to a feature in a different table as long as the two participating tables have a valid relationship between them (they must be related tables). The relate method updates the foreign key (KeyField) value on the destination feature and can be called on either the origin or destination feature.

Relating features is akin to changing the attributes of feature; it's synchronous and done in memory. A feature, once related, must be added or updated to the table using FeatureTable.add(_:) or FeatureTable.update(_:) for changes to be committed.

It's important to know the cardinality of the table relationship when you relate features. You can determine this by examining the JSON of the service, as illustrated in the following image.

Cardinality and role shown in JSON

The sample feature service at https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/AlaskaNationalParksPreservesSpecies_List/FeatureServer contains a table relationship where the Alaska National Parks layer is the origin table to the destination table of Alaska National Parks Species. Each park has zero or more species related to it because it was set up that way in the table relationship, which gave parks a one-to-many relationship with species.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
        // Identifies a feature in the 'parks' layer (from a tap on the map, for example).
        guard let parkFeature = identifyLayerResult.geoElements.first as? ArcGISFeature else { return }

        // Gets the feature table from the feature.
        guard let parksTable = parkFeature.table as? ArcGISFeatureTable else { return }

        // Gets a list of tables related to the 'parks' feature table.
        // Assumes the species table is the first related table.
        // If there are many related tables, you can loop through the array and check the table name.
        guard let speciesTable = parksTable.relatedTables.first else { return }

        // Creates a new feature in the species table.
        guard let speciesFeature = speciesTable.makeFeature() as? ArcGISFeature else { return }
        // Adds a value to the 'Scientific_Name' attribute.
        speciesFeature.setAttributeValue("Vulpes vulpes", forKey: "Scientific_Name")

        // Relates the selected park to the new species.
        do {
            try parkFeature.relate(to: speciesFeature)
        } catch {
            print(error)
        }

Unrelate features

You may want to unrelate two already related features. For example, when a feature has a constraint violation, such as an invalid cardinality, you may want to undo the last relate operation that caused the violation. Unrelating features resets the KeyField of the destination feature. Like the relate method, unrelate is also synchronous and is done in memory. Therefore FeatureTable.add(_:) or FeatureTable.update(_:) must be called for changes to be committed to the table.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
        // Gets the layer info from the parks table.
        let layerInfo = parksTable.layerInfo

        // Gets all the relationship infos and find a specific one.
        guard let relationships = layerInfo?.relationshipInfos,
              let relatedSpeciesInfo = relationships.first(where: { $0.name == "AK_National_Parks_Species" }) else { return }

        // Creates related query parameters and query for related species.
        let relatedQueryParams = RelatedQueryParameters(relationshipInfo: relatedSpeciesInfo)
        do {
            let relatedFeatureQueryResults = try await parksTable.queryRelatedFeatures(to: parkFeature, using: relatedQueryParams, queryFeatureFields: .loadAll)
            // Gets all species related to this park.
            guard let relatedFeatures = relatedFeatureQueryResults.first?.features() as? [ArcGISFeature] else { return }
            // Checks each species related to this park.
            try relatedFeatures.forEach { relatedFeature in
                // If the status is not 'Approved', unrelate the species.
                if let status = relatedFeature.attributes["Record_Status"] as? String,
                   status != "Approved" {
                    try parkFeature.unrelate(from: relatedFeature)
                }
            }
            // Updates the feature to commit changes to the table.
            try await parksTable.update(parkFeature)
        } catch {
            print(error)
        }

Validate the relationship constraints of a feature

You can check if a given feature violates any relationship constraints (for example, when a new species for a park is being added by a user), such as cardinality violations. In one-to-one relationships, if an origin feature is already related to a destination feature, no other destination feature can be related to it. In one-to-many relationships, a destination feature can be related to only one origin feature while an origin feature can be related to one or more destination features. For more info on cardinality and types of relationships, see ArcGIS Pro's help topic Relationship class properties or ArcMap's help topic Relationship class properties.

Considering the parks and species example above with a relationship cardinality of one to many, if a species were to be related to a second park, it would be a cardinality violation.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
        // See if this park feature violates relationship constraints with species.
        do {
            let violationType = try await parksTable.validateRelationshipConstraints(for: parkFeature)
            switch violationType {
            case .cardinality:
                // Cardinality means the wrong number of related features (more than 1 related record in a 1:1 relationship, for example).
                print("Cardinality")
            case .orphaned:
                // Orphaned means a record with no related feature when one is required.
                print("Orphaned")
            case .noViolations:
                print("No violations")
            @unknown default:
                print("Unknown RelationshipConstraintViolationType")
            }
        } catch {
            print(error)
        }

Note that an update operation on a feature succeeds even if a relationship constraint has been violated by the edit. This is consistent handling with ArcGIS Server and ArcGIS Desktop, which also allow cardinality violations. ArcGIS Desktop provides a Validate Feature tool, which allows you to recover from violations in a back-office operation after applying edits or syncing, if you choose to do so. For more information, see ArcGIS Pro help's Relationship or ArcMap's Validating features and relationships topics. However, if you wish to check for violations in your app and recover from them, you can use the validate method.

Another type of constraint violation captured by the validate method occurs in a composite relationship when an orphan feature is added to the destination table without relating it to an origin feature. You can recover from this violation by relating the orphaned destination feature to a valid origin feature.

Additional information

Getting related tables for a layer or table on the map returns only those tables on the map. Similarly, related queries require both origin and destination table/layer to be present on the map. For tables not on the map, you can query them using regular query operations but cannot use related queries. You can also view what relationships the tables participate in.

All the tables participating in a relationship must be present in the data source. ArcGIS Maps SDK for Native Apps supports related tables with the following data sources:

  • ArcGIS feature service
  • ArcGIS map service
  • Geodatabase downloaded from a feature service
  • Standalone mobile geodatabases authored in ArcGIS Pro
  • Geodatabase in a mobile map package

Two participating tables can have one of the following cardinalities: one-to-one, one-to-many, or many-to-many.

When defining relationships, one table must be the origin and the other, the destination. A table can participate in more than one relationship. A table can play a destination role in one relationship and origin in another, resulting in nested relationships.

Simple and composite workflow-based relationships are supported:

  • In a simple relationship, features in the destination table are independent to features in the origin table. For example, a transformer and an electric pole may be related but they can also exist on their own. Deleting an origin feature resets the keyField of the relationship to NULL in the destination feature.
  • In a composite relationship, each feature in the destination table is expected to be related to an origin feature. In other words, any orphan destination features are considered a violation of the relationship. For example, a park and a species must be related. While the park (origin) can exist on its own, a species (destination) must be related to a park. When an origin feature is deleted, the destination feature should also be deleted. This is known as a cascade delete.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.