You can relate a feature from one table to a feature in another table for many reasons, such as to allow your users to view related feature information. For example, a user may be interested in a list of the species that live in Alaskan national parks where parks and species are in different, but related, layers.
Relate features is an editing function that adds an attribute to the destination feature. The relate operation associates the origin feature and destination feature by adding a keyField attribute in the destination feature that corresponds to the origin table feature's primary key or global ID. In the national parks example, relating a park to species (one to many) adds the keyField value from 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 when editing any feature, as described in the Edit features topic. For related features, it doesn't matter whether the feature is the origin feature in a table relationship or the destination feature. The Relate two features section describes how to set up the relationship between two features. When tables are related, other operations available include 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.relateFeature to relate a feature from one table to a feature in another, provided the two participating tables already have a valid relationship (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 to the table or updated using FeatureTable::addFeatureCompleted or FeatureTable::updateFeature() for changes to be committed to the local geodatabase.
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.
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 Alaska National Parks Species destination table. Each park has zero or more species related to it (which is how it was set up in the table relationship); this gives the parks a one-to-many relationship with species.
// Signal to handle the mouse click on the screen, used to start the identify for the layer.
connect(m_mapView, &MapQuickView::mouseClicked, this, [this, parksLayer](QMouseEvent& e)
{
// Perform the identify on the layer using the screen coordinates (X,Y) where
// the user clicked on the screen, using a tolerance of 15 pixels, a false to return
// both popups and graphics.
m_mapView->identifyLayerAsync(parksLayer, e.position(), 15, false).then(this,
[this](IdentifyLayerResult* rawResult)
{
// Wrap the identify result in a unique_ptr to manage the lifetime of the result.
auto identifyResult = std::unique_ptr<IdentifyLayerResult>(rawResult);
// Something went wrong with the identify, return the function.
if (!identifyResult)
return;
// Get the geo element from the identify result.
GeoElement* firstGeoElement = identifyResult->geoElements().first();
if (firstGeoElement)
{
// Get the ArcGIS feature from the geo element.
ArcGISFeature* parkFeature = static_cast<ArcGISFeature*>(firstGeoElement);
// Make sure we have something valid for the 'service requests' feature.
if (!parkFeature)
{
return;
}
// Get the feature table from the ArcGIS feature.
ArcGISFeatureTable* parksTable = static_cast<ArcGISFeatureTable*>(
parkFeature->featureTable());
// Get a list of tables related to the 'parks' feature table.
QList<ArcGISFeatureTable*> relatedTables = parksTable->relatedTables();
// Assume the species table is the first related table
// (if there are many related tables, you can loop through the
// collection and check the table name).
ArcGISFeatureTable* speciesTable = relatedTables.first();
// Create a new feature in the species table.
Feature* newSpeciesFeature = speciesTable->createFeature(this);
// Get the ArcGIS feature from the feature.
ArcGISFeature* newSpecies = static_cast<ArcGISFeature*>(newSpeciesFeature);
// Add species text to the 'Scientific_Name' attribute.
newSpecies->attributes()->replaceAttribute("Scientific_Name", "Vulpes vulpes");
// Relate the selected park request to the species feature.
parkFeature->relateFeature(newSpecies);
}
});
});
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 Key of the destination feature. Like the relate method, unrelate is also synchronous and is done in memory. Therefore, FeatureTable::addFeatureCompleted or FeatureTable::updateFeature() must be called for changes to be committed to the table.
// Get the layer info from the parks table.
const ArcGISFeatureLayerInfo parksLayerInfo = parksTable->layerInfo();
// Find the info for the 'AK_National_Parks_Species' relationship.
const QString relatedSpeciesWhereClause =
"select r from relationships where r.name = `AK_National_Parks_Species`";
// Create a relationship query parameters using this relationship info.
RelatedQueryParameters relatedParksQueryParams;
// Set the where clause which will filter the parks returned when the query is executed.
relatedParksQueryParams.setWhereClause(relatedSpeciesWhereClause);
// Call the query related features async method on the ArcGIS feature table using
// the input parameters of an ArcGIS feature.
parksTable->queryRelatedFeaturesAsync(parksFeature, this).then(this,
[this, parksFeature, parksTable](QList<RelatedFeatureQueryResult*> rawRelatedResults)
{
// Proceed if the list of relayed feature query results is greater that 0.
if (rawRelatedResults.count() > 0)
{
// Get the species from the relationship results.
RelatedFeatureQueryResult* theRelatedFeatureQueryResult = rawRelatedResults.first();
FeatureIterator featureIterator = theRelatedFeatureQueryResult->iterator();
// Loop through all species related to this park.
while (featureIterator.hasNext())
{
// Get the related feature.
ArcGISFeature* relatedFeature = static_cast<ArcGISFeature*>(
featureIterator.next(this));
// Load the related feature before accessing attribute values
connect(relatedFeature, &ArcGISFeature::doneLoading, this, [relatedFeature,
parksFeature](const Error& error)
{
// Check to ensure the load was successful.
if (!error.isEmpty())
{
qDebug() << "encountered an error:" << error.message();
return;
}
// Get the status of this record.
const QVariant status = relatedFeature->attributes()->attributeValue("Record_Status");
// See if the record status is anything other than 'Approved'.
if (status != "Approved")
{
// Unrelate this species from the park (doesn't delete the related feature).
parksFeature->unrelateFeature(relatedFeature);
}
});
}
// Update the feature to commit changes to the table.
parksTable->updateFeatureAsync(parksFeature).then(this,[]()
{
// continue processing ...
});
}
});
Validate the relationship constraints of a feature
You can validate if a given feature violates any relationship constraints, such as cardinality violations (for example, when user adds a new species for a park). 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 information about cardinality and relationship types, see the ArcGIS Pro help topic Relationship class properties or the ArcMap 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.
// See if this park feature violates relationship constraints with species.
speciesTable->validateRelationshipConstraintsAsync(parksFeature).then(this,
[](Esri::ArcGISRuntime::RelationshipConstraintViolationType relationshipConstraintViolationType)
{
// Check for a constraint violations.
if (relationshipConstraintViolationType == RelationshipConstraintViolationType::Cardinality)
{
// Cardinality means the wrong number of related features (more than
// 1 related record in a 1:1 relationship, for example).
}
else if (relationshipConstraintViolationType == RelationshipConstraintViolationType::Orphaned)
{
// Orphaned means a record with no related feature when one is required.
}
else
{
// No violations.
}
});
Note that an update operation on a feature succeeds even if a relationship constraint is violated by the edit. This is consistent handling with ArcGIS Server and ArcGIS Desktop, which 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 the ArcGIS Pro help topic Relationship or the ArcMap topic Validating features and relationships. 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 tables that are included in the map. Similarly, related queries require both the 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 which relationships the map's tables participate in.
All the tables participating in a relationship must be present in the data source. ArcGIS Maps SDK for Qt 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 an origin role in another, resulting in nested, non-hierarchical relationships.
Simple and composite workflow-based relationships are supported:
- In a simple relationship, features in the destination table are independent from 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.