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. For example, you might want a user to be able to view fire hydrant inspections from an inspections table and view general fire hydrant information (such as install date) from a hydrants table⁠ for the same set of fire hydrants.

Hydrants and related inspections

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 hydrant example, relating a hydrant and an inspection adds the keyField value of the hydrant feature in the hydrants table (origin table) to the corresponding (hydrant) field in the inspection feature in the inspections 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 Pro or using ArcMap.

The pattern for editing a feature to relate it to another is the same as for editing a "regular" feature, as described in Edit, 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 but described on this page:

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

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 ArcGISFeatureTable.addFeatureAsync() or ArcGISFeatureTable.updateFeatureAsync() 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 http://sampleserver6.arcgisonline.com/arcgis/rest/services/ServiceRequest/FeatureServer 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.

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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
// 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 inspections table is the first related table
      // (if there are many related tables, you can loop through the collection and check the table name)
      ArcGISFeatureTable inspectionsTable = relatedTables.get(0);

      // create a new feature in that table
      ArcGISFeature createdFeature = (ArcGISFeature) inspectionsTable.createFeature();
      createdFeature.getAttributes().put("inspection", "Hydrant cap is missing.");

      // relate identified feature to new feature inspection
      serviceFeature.relateFeature(createdFeature);
    }
  } 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 KeyField of the destination feature. Like the relate method, unrelate is also synchronous and is done in memory. Therefore ArcGISFeatureTable.addFeatureAsync() or ArcGISFeatureTable.updateFeatureAsync() must be called for changes to be committed to the table.

In the hydrants and inspections example where there is a cardinality violation because a hydrant is related to two inspections (of the same inspection cycle), the following code unrelates the features, thereby removing the constraint violation.

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

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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481

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

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

// Query the service requests table to get related inspections
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 inspection 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 inspection 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 inspections for a hydrant are 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 ArcGIS Pro's help topic Relationship class properties or ArcMap's help topic Relationship class properties.

Considering the hydrants and inspection example above with a relationship cardinality of 1:1, if an inspection were to be related to a second hydrant, it would be a cardinality violation. The following code checks for constraint violation for a given inspection.

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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
ListenableFuture<RelationshipConstraintViolation> result =
  inspectionsTable.validateRelationshipConstraintsAsync(serviceFeature);
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)
        break;
      case ORPHANED:
        // Orphaned means a record with no related feature when one is required
        break;
      default:
        // 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. For more information see ArcGIS Pro help's Relationship or ArcMap's 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 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
  • 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 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 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 hydrant and its inspection must be related. While the hydrant (origin) can exist on its own, an inspection (destination) must be related to a hydrant. 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.