ArcGIS Runtime SDK for macOS

Search for related features

You can search for features in one table that are related to features in another table, provided a relationship was defined between the two tables. Table relationships are defined using ArcGIS Desktop, as described in Essentials of relating tables in the ArcGIS Desktop help.

Note:

For example, say your app lets users view all the fire hydrants (fire hydrant features) in a city through a hydrants table. You now want users to be able to look up the inspection reports for a given hydrant that are stored in a different table, say hydrant-inspections. If a relationship has been defined between these tables, you can query the hydrants table to find related features from the hydrant-inspections table for a given hydrant.

The following steps describe how to set up the above scenario — searching for inspection reports (related features) of a given hydrant (feature). Note that you could also query the relationship in the other direction to search for all fire hydrants with a specified inspection criteria.

Search for related features

  1. Add the related tables to the same map. If the tables participating in the relationship are in a single map service, you can add the service to the map as an AGSArcGISMapImageLayer. This will add all spatial and non-spatial tables from the service. If a table is a spatial table from a map service or feature service, you can add it to the map's operational layers as a feature layer. Likewise, a non-spatial table can be added to the map's table collection. In a disconnected scenario, you add the tables to the map after downloading them into a mobile geodatabase.

    The following code adds a feature layer and a non-spatial table to a map.

    let featureLayer = AGSFeatureLayer(featureTable: hydrantsTable)
    self.map.operationalLayers.add(featureLayer)
    self.map.tables.add(inspectionsTable)

    All participating tables must be in the same map but they do not have to be loaded..

  2. If you want to return only those features from the table that participate in the provided relationship, set input parameters as described in this step. Otherwise, skip to step 4.
    1. Create an AGSRelatedQueryParameters object.
    2. Provide a relationshipInfo from the ArcGISFeatureLayerInfo class in the arcgisservices package. Any time you create an AGSRelatedQueryParameters object, you must also provide a relationshipInfo that defines the relationship.

      let queryParams = AGSRelatedQueryParameters(relationshipInfo: (hydrantsTable.layerInfo?.relationshipInfos[0])!)
      queryParams.whereClause = "InspectionStatus = 'Failed'"

    3. You can provide additional input parameters, such as a whereClause, to further filter the related features, whether or not you wish to receive the geometry of the related features, and result sorting preferences.
  3. Query the table containing the feature for which you want related features. In the hydrant example, you would query the hydrants table to find inspection reports for a particular hydrant.

    hydrantsTable.queryRelatedFeatures(for: hydrantFeature, parameters: queryParams, completion: { (results:      [AGSRelatedFeatureQueryResult]?, error: Error?) -> Void in
    
           //Check for errors                
           if let error = error {
                   //Handle errors                     
                   return
           }
    
           if let results = results {
                for result in results  {
                    //Enumerate over related features
                    if result.featureEnumerator().allObjects.count > 0 {
    
                       //Inspection reports features
                    }
                }
          }
    })

    In a connected scenario, whether a query is online or local depends on the feature request mode of the related table. For more information about feature request modes, see the Table performance section in the Layers and tables topic.

    • For On_Interaction_Cache, the query can be online or local as features are cached
    • For On_Interaction_NoCache, the query is always online
    • For Manual_Cache, the query is always local
    In a disconnected scenario, all queries are local.

  4. If you want to find related features from all participating relationships of a given feature, perform the search without any query parameters.

    hydrantsTable.queryRelatedFeatures(for: hydrantFeature,
                  completion: { (results: [AGSRelatedFeatureQueryResult]?, error: Error?) -> Void in
    
                  //Check for error   
                  if let error = error {
                        //Handle error                                                
                        return
                  }
    
            //Related features of 'hydrantFeature' from all relationships 'hydrantsTable' participates in    
           if let results = results {
              for result in results  {
                   if result.featureEnumerator().allObjects.count > 0 {
    
                            //Related features
                   }
              }
           }
     })

  5. Handle query results.

    Query operations are asynchronous and get called back with the query results and an optional error, if any. The results are an array of AGSRelatedFeatureQueryResult objects, one for each related table that was queried. If more than one table was queried, multiple query operations may be performed internally and the query method is called back when all such operations have completed.

    Each AGSRelatedFeatureQueryResult contains a list of related features that can be iterated over. The query result also contains the relatedTable and relationshipInfo since multiple instances of the same table can be added to the map (for instance with different scale level visibility, definition expression, and so on). In such cases, a query is performed on each table instance and an AGSRelatedFeatureQueryResult object is returned for each.

    The query result also contains:

    • The feature for which the related features were queried.
    • Information on whether the resulting related feature count exceeded the maximum limit supported by the server.