- URL:https://<featurelayer-url>/queryRelatedRecords
- Required Capability:Query
- Version Introduced:10.0
Description
The queryRelatedRecords operation is performed on a feature service layer resource. The result of this operation are feature sets grouped by source layer and table object IDs. Each feature set contains Feature objects including the values for the fields requested by the user. For related layers, if you request geometry information, the geometry of each feature is also returned in the feature set. For related tables, the feature set does not include geometries.
All parameters related to geometry are ignored when querying related tables.
Nota:
The exceededTransferLimit property is now included in the JSON response when paging through a query result with the resultOffset and resultRecordCount parameters. When exceededTransferLimit is true, it indicates there are more query results, and you can continue to page through the results. When exceededTransferLimit is false, it indicates that you have reached the end of the query results.
When the resultOffset and resultRecordCount parameters are not used, the exceededTransferLimit property may also be included in the query results. In this case, the property will be true only if the number of records exceeds the maximum number configured by the server administrator.
New at 11.2
- This operation now supports pagination for non-hosted feature services that reference enterprise geodatabase data. Support for pagination is indicated when the layer-level supportsQueryRelatedPagination property, under advancedQueryCapabilities, is true.
- Hosted and non-hosted feature services now support the orderBy and returnCountOnly parameters. Support for these parameters is indicated when the layer-level supportsAdvancedQueryRelated property, under advancedQueryCapabilities, is true.
New at 11.1
Starting at ArcGIS Enterprise 11.1, qualifying hosted feature services now support pagination with the queryRelatedRecords operation. Support for pagination is indicated when the layer-level supportsQueryRelatedPagination property, under advancedQueryCapabilities, is true.
Request parameters
| Parameter | Details |
|---|---|
| objectIds | The object IDs of the layer or table to be queried. Records related to these object IDs will be queried. Syntax Example |
| relationshipId | The ID of the relationship to be queried. The relationships in which this layer or table participates are included in the Feature Service Layer resource response. Records in tables or layers corresponding to the related table or layer of the relationship are queried. Example |
| outFields | The list of fields from the related table or layer to be included in the returned feature set. This list is a comma delimited list of field names. If you specify the shape field in the list of return fields, it is ignored. To request geometry, set returnGeometry to true. You can also specify the wildcard (*) as the value of this parameter. In this case, the results will include all the field values. Example |
| definitionExpression | Related records returned by the queryRelatedRecords operation can be further limited by setting a definition expression. The definition expression refers to the related table and is applied on top of the result set. Example |
| returnGeometry | If true, the feature set includes the geometry associated with each feature. The default is true. This parameter only applies to related layers. It is ignored for related tables. If the outFields parameter is set to the wildcard (*), it implicitly implies that returnGeometry=true, and setting returnGeometry to false has no effect. Values: true | false |
| maxAllowableOffset | This option can be used to specify the maxAllowableOffset to be used for generalizing geometries returned by the query operation. maxAllowableOffset is in the units of outSR. If outSR is not specified, maxAllowableOffset is assumed to be in the unit of the spatial reference of the map. Example |
| geometryPrecision | This option can be used to specify the number of decimal places in the response geometries returned by the query operation. This applies to X and Y values only (not m- or z-values). Example |
| resultOffset | This option can be used for fetching query results by skipping the specified number of records and starting from the next record (that is, resultOffset + 1th), and to fetch records that are beyond the maxRecordCount. The default is 0. Nota:This parameter only applies if supportsQueryRelatedPagination is true.Example |
| resultRecordCount | This option can be used for fetching query results up to the resultRecordCount specified. When resultOffset is specified but this parameter is not, the map service defaults it to maxRecordCount. The maximum value for this parameter is the value of the layer's maxRecordcountresultOffset property. Nota:This parameter only applies if supportsQueryRelatedPagination is true.Example |
| outSR | The spatial reference of the returned geometry. The spatial reference can be specified as either a well-known ID or a spatial reference json object. If outSR is not specified, the geometry is returned in the spatial reference of the map. This parameter only applies to related layers. It is ignored for related tables. |
| gdbVersion | The geodatabase version to query. This parameter applies only if the isDataVersioned property of the layer queried is true. If this is not specified, query will apply to the published map’s version. Syntax Example |
| historicMoment | This option works with ArcGIS Server services only. The historic moment to query. This parameter applies only if the supportsQueryWithHistoricMoment property of the layers being queried is set to true. This setting is provided in the layer resource. If historicMoment is not specified, the query will apply to the current features. Syntax Example |
| returnZ | If true, z-values are included in the results if the features have z-values. Otherwise, z-values are not returned. The default is false. This parameter only applies if returnGeometry is true. Values: true | false |
| returnM | If true, m-values are included in the results if the features have m-values. Otherwise, m-values are not returned. The default is false. This parameter only applies if returnGeometry is true. Values: true | false |
| returnTrueCurves (Optional) | When set to true, it returns true curves in output geometries; otherwise, curves are converted to densified polylines or polygons. The default value is false. Values: true | false Example |
| orderByFields | This parameter is used to request a list of the related records based on the field order. This list is a comma delimited list of field names. Nota:This parameter only applies if supportsAdvancedQueryRelated is true. Syntax Example |
| returnCountOnly | If true, returns the count of the related records for each object ID. The default is false. This parameter is only applicable if supportsAdvancedQueryRelated is true. Nota:If included in the request, this parameter will overwrite all other parameters and responses. Values: true | false Example |
| datumTransformation | Introduced at 10.8. This parameter applies a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference. When specifying transformations, you need to think about which datum transformation best projects the layer (not the feature service) to the outSR and sourceSpatialReference property in the layer resource report. For a list of valid datum transformation ID values ad well-known text strings, see Using spatial references. For more information on datum transformations, please see the transformation parameter in the Project operation. Syntax Example |
| f | The response format. The default response format is html. Values: html | json |
Example usage
- Example one
- Example two
- Example three
- Example four
Example one
The following is a sample request URL for the queryRelatedRecords operation, which will query the related records as defined by relationship ID 2 that are related to the specified objectIds in layer 0:
https://machine.domain.com/webadaptor/rest/services/Petroleum/KSPetro/FeatureServer/0/queryRelatedRecords?objectIds=3,4,5&relationshipId=2&returnGeometry=true&outFields=*&f=htmlExample two
The following is a sample request URL for the queryRelatedRecords operation, which requests to skip the first two records and return the next four records where the objectId is greater than 3:
https://machine.domain.com/webadaptor/rest/services/RelationshipOID_test/FeatureServer/3/queryRelatedRecords?objectIds=&relationshipId=1&outFields=*&definitionExpression=ObjectID>3&returnGeometry=true&maxAllowableOffset=&geometryPrecision=&outSR=&resultOffset=2&resultRecordCount=4&f=htmlExample three
The following is a sample request URL for the queryRelatedRecords operation, which will return the related records count for each specified objectId where TOWNSHIP is the value for orderByField:
https://machine.domain.com/webadaptor/rest/services/KSPetro/FeatureServer/1/queryRelatedRecords?objectIds=7028,7029,71,6263,166,72,69,7126,6080,7522,335&relationshipId=1&outFields=OBJECTID&definitionExpression=&orderByFields=TOWNSHIP&returnCountOnly=true&returnGeometry=false&maxAllowableOffset=&geometryPrecision=&outSR=&resultOffset=&resultRecordCount=&f=html&token=Example four
The following is a sample request URL for the queryRelatedRecords operation, which will return the related records for each specified objectId where TOWNSHIP is the value for both the outField and orderByField:
https://machine.domain.com/webadaptor/rest/services/Kansas_Petro_Data/FeatureServer/1/queryRelatedRecords?objectIds=7028,7029&relationshipId=1&outFields=TOWNSHIP&definitionExpression=1=1&orderByFields=TOWNSHIP&returnCountOnly=false&returnGeometry=false&maxAllowableOffset=&geometryPrecision=&outSR=&resultOffset=&resultRecordCount=&f=html&token=JSON Response syntax
{
"geometryType": "<geometryType>", //if records include geometry
"spatialReference": <spatialReference>, //if records include geometry
"hasZ": <true|false>,
"hasM": <true|false>,
"fields": [
{
"name": "<fieldName1>",
"type": "<fieldType1>",
"alias": "<fieldAlias1>",
"length": "<length1>"
},
{
"name": "<fieldName2>",
"type": "<fieldType2>",
"alias": "<fieldAlias2>",
"length": "<length2>"
}
],
"relatedRecordGroups": [
{
"objectId": <objectId1>,
"relatedRecords": [ //features may include geometry for related layers only
<relatedFeature11>, <relatedFeature12>
]
},
{
"objectId": <objectId2>,
"relatedRecords": [
<relatedFeature21>, <relatedFeature22>
]
}
]
}JSON Response example
- Example one
- Example two
- Example three
JSON Response example
Example one
The following is a sample response returned by the queryRelatedRecords operation:
{
"geometryType": "esriGeometryPolygon",
"spatialReference": {
"wkid": 4267
},
"fields": [
{
"name": "OBJECTID",
"type": "esriFieldTypeOID",
"alias": "OBJECTID"
},
{
"name": "FIELD_KID",
"type": "esriFieldTypeString",
"alias": "FIELD_KID",
"length": 25
},
{
"name": "APPROXACRE",
"type": "esriFieldTypeDouble",
"alias": "APPROXACRE"
},
{
"name": "FIELD_NAME",
"type": "esriFieldTypeString",
"alias": "FIELD_NAME",
"length": 150
}
],
"relatedRecordGroups": [
{
"objectId": 3,
"relatedRecords": [
{
"attributes": {
"OBJECTID": 5540,
"FIELD_KID": "1000147595",
"APPROXACRE": 95929,
"FIELD_NAME": "LOST SPRINGS",
},
"geometry": {
"rings": [
[
[
-96.929599633999942,
38.52426809800005
],
[
-96.929602437999961,
38.522448437000037
],
[
-96.92959118999994,
38.529723252000053
],
[
-96.929594022999936,
38.527905578000059
],
[
-96.929596839999988,
38.526087119000067
],
[
-96.929599633999942,
38.52426809800005
]
]
]
}
}
]
}
]
}Example two
The example below demonstrates a response that is returned when the request has the objectIds parameter set as 7028,7029, the relationshipId parameter is set as 1, the outFields parameter is set as TOWNSHIPS,RANGE, the orderByFields parameter is set as TOWNSHIP,RANGE, the returnCountryOnly parameter is set as false, and returnGeometry is set as false:
{
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 33
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 34
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
},
{
"attributes": {
"TOWNSHIP": 24,
"RANGE": 35
}
}
}Example three
The response example below demonstrates a response that is returned when the request has the objectIds parameter set as 7028,7029, the relationshipId parameter set as 1, the returnCountyOnly parameter is set as true, and the returnGeometry parameter is set as false:
{
"relatedRecordGroups": [
{
"objectId": 7028,
"count": 10218
},
{
"objectId": 7029,
"count": 3304
}
]
}