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.
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 the two tables are related, you can query the hydrants table for related features of a given hydrant, and the query will return results from the hydrant-inspections table.
The following steps describe how to set up the above scenario of searching for inspection reports (related features) of a given hydrant (feature). Note that you could also search for all fire hydrants inspected during a particular inspection.
Search for related features
- Add the participating tables to the same map. If a table is a spatial table, you can create a feature layer from it and add it to the list of the map's operational layers. If a table is non-spatial, you must add it to the list of the map's tables. Similarly in a disconnected scenario, you'd add the tables to the map but you'd first download them into a mobile geodatabase.
Note that while the participating tables must be in the same map, they do not have to be loaded.
- If you want to return only features from the table that participates in the provided relationship, set input parameters as described in this step. Otherwise, skip to step 4.
- Create an AGSRelatedQueryParameters object.
- 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.
- 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. You may also specify a list of fields to sort the results in.
- Call the query method on the table containing the feature for which you want to search for related features as described in this step, then skip to step 5. In the hydrant example described above, if you want users to be able to view all inspection reports for a particular hydrant, you would query the hydrants table.
In a connected scenario, whether a query is online or local depends on the feature request mode of the related table:
- 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
- If you want to return related features from all participating relationships of a given feature, perform the search without any query parameters.
- Handle the returned query results.
Query operations are asynchronous and get called back with the query results and an optional error, if anyand emit signals with the query results or an error, if any. The results are an array of AGSRelatedFeatureQueryResult objects, one for each of the related table 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 enumerated over. The query result also contains relatedTable in addition to relationshipInfo because 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