Skip To Content ArcGIS for Developers Sign In Dashboard

Relate features

You may 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. For example, you might want a user to be able to view fire hydrant inspection reports from a reports table, and view general fire hydrant information from a hydrants table - for the same set of fire hydrants.

When you relate features, you're editing them because the relate operation changes the attribute of the destination feature. The relate operation associates the two tables by setting up 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 hydrant example, relating a hydrant and an inspection report adds the keyField value of the hydrant feature in the hydrants table (origin table) to the corresponding (hydrant) field in the report feature in the reports table (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 Desktop.

The pattern for editing a feature to relate it to another is the same as for editing a "regular" feature, as described in Edit features, whether the feature is the origin feature in a table relationship or the destination feature. When tables participate in a table relationship like this, you can perform additional editing-oriented operations not described in Edit features but described on this page:

Relate two features

You use the relate method 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. The relate method sets up 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 addFeatureAsync(feature) or updateFeatureAsync(feature) for changes to be committed.

It's important to know the cardinality of the table relationship when you relate features.

The sample feature service at contains a layer of point features that represent customer requests for service. A related table contains zero or more comments for each feature in the service request layer. The following code uses this service to show how to add a new related comment to a service request feature clicked in the map.

// identify a feature from the service request
ListenableFuture<IdentifyLayerResult> result = mapView.identifyLayerAsync(layer, point, 5, false);
result.addDoneListener(() -> {
  try {
    // get first feature that was identified 
    if (result.get().getElements().size() > 0 && result.get().getElements().get(0) instanceof ArcGISFeature) {
      ArcGISFeature serviceFeature = (ArcGISFeature) result.get().getElements().get(0);
      // get related tables from feature
      ArcGISFeatureTable serviceRequestTable = serviceFeature.getFeatureTable();
      List<ArcGISFeatureTable> relatedTables = serviceRequestTable.getRelatedTables();

      // Assuming the comments table is the first related table
      // (if there are many related tables, you can loop through the collection and check the table name)
      ArcGISFeatureTable commentsTable = relatedTables.get(0);

      // create a new feature in that table
      ArcGISFeature createdFeature = (ArcGISFeature) commentsTable.createFeature();
      createdFeature.getAttributes().put("comments", "Please show up on time!");

      // relate identified feature to new feature comment 
  } catch (ExecutionException | InterruptedException ex) {
    // .. handle any exception that may occur

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 field of the destination feature. Like the relate method, unrelate is also synchronous and is done in memory. Therefore addFeatureAsync(feature) or updateFeatureAsync(feature) must be called for changes to be committed to the table.

The following code loops through related comments for a service request feature and removes those more than seven days old.

ArcGISFeatureLayerInfo layerInfo = serviceTable.getLayerInfo();
List<RelationshipInfo> relationships = layerInfo.getRelationshipInfos();

// assuming the first relationship is the service request comments
// (if multiple relationships check for name)
RelatedQueryParameters queryParameters = new RelatedQueryParameters(relationships.get(0));

// Query the service requests table to get related comments
ListenableFuture<List<RelatedFeatureQueryResult>> results =
  serviceTable.queryRelatedFeaturesAsync(serviceFeature, queryParameters);
results.addDoneListener(() -> {
  try {
    List<RelatedFeatureQueryResult> relatedResults = results.get();
    if (relatedResults.size() > 0) {
      RelatedFeatureQueryResult relatedResult = relatedResults.get(0);
      relatedResult.forEach(feature -> {
        if (feature instanceof ArcGISFeature) {
          // check if the comment was submitted before January 1ST 2018
          Long january1st2018 = 1514764800000L;
          Date expiredDate = new Date(january1st2018);
          Date featureDate = (Date) feature.getAttributes().get("submitdt");
          if (featureDate.before(expiredDate)) {
            // Unrelate the comment from the service request (doesn't delete the related feature)
            serviceFeature.unrelateFeature((ArcGISFeature) feature);
  } catch (ExecutionException | InterruptedException ex) {
    // .. handle any exception that may occur

Validate the relationship constraints of a feature

You can check if a given feature violates any relationship constraints (for example, when a hydrant inspection report is being added by a user), such as cardinality violations. In 1:1 relationships, if an origin feature is already related to a destination feature, no other destination feature can be related to it. In 1:n 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 Relationship class properties in the ArcGIS Desktop help.

The following branching statement checks for a relationship constraint violation for the service request feature and its related comment records.

ListenableFuture<RelationshipConstraintViolation> result =
result.addDoneListener(() -> {
  try {
    RelationshipConstraintViolation constraintViolation = result.get();
    switch (constraintViolation) {
      case CARDINALITY:
        // Cardinality means the wrong number of related features (more than 1 related record in a 1:1 relationship, for example)
      case ORPHANED:
        // Orphaned means a record with no related feature when one is required
        // No violations
  } catch (ExecutionException | InterruptedException ex) {
    // .. handle any exception that may occur

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 do not enforce 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. See Validating features and relationships in ArcMap for more information. 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.


Performance tip: If the related features are not local to the device, the validate method makes network calls to query for them. As a result, it can negatively impact performance when used on a number of features. This hit to performance is why edit operations such as add, update, and delete do not check proactively for relationship constraint violations.

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 Runtime supports related tables in the following data sources:

  • ArcGIS feature service
  • ArcGIS map service
  • Geodatabase downloaded from a feature service
  • 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 origin and the other 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 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 building and its mailbox must be related. While the building (origin) can exist on its own, a mailbox (destination) must be related to a building. When an origin feature is deleted, the destination feature should also be deleted. This is known as a cascade delete.