ArcGIS REST API - ArcGIS Services - Query Related Records (Map Service/Layer)

URL:https://<layer-url>/queryRelatedRecords
Required Capability:Data
Version Introduced:10.0

Description

The query related records operation is performed on a layer / table resource. The result of this operation is one or more featuresets grouped by source layer / table object IDs. Each featureset 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 featureset. For related tables, the featureset does not include geometries.

Also, each featureset contains an array of field information objects for fields requested in outFields parameter. See Layer/Table for details on fields.

Note:

All parameters related to geometry will be ignored when querying related tables.

You can provide arguments to the query related records operation as query parameters defined in the parameters table below.

Note:

The domain's member is not included in field information objects returned with the response.

New at 10.9

A new parameter, timeReferenceUnknownClient, has been added at 10.9. Setting timeReferenceUnknownClient as true indicates that the client is capable of working with date field data values that are not in UTC. For more information on this parameter, see the Request parameters table below.

New in 10.5

The feature service layer Query operation supports the returnTrueCurves and historicMoment parameters.

New in 10.1

Support for returnZ and returnM was added for layers. Default value for returnZ and returnMis false.
Support for gdbVersion parameter was added. Use this parameter to specify the geodatabase version to query.
geometryPrecision parameter was introduced. This option can be used to specify the number of decimal places in the response geometries returned by the query operation.
JSON response contains an optional property exceededTransferLimit. This property will be true only if the number of records exceeds the maximum number configured by the server administrator.

Request parameters


Parameter	Details
objectIds	The object IDs of this layer/table to be queried. Records related to these object IDs will be queried. Syntax `objectIds=<objectId1>, <objectId2>` Example `objectIds=37, 462`
relationshipId	The ID of the relationship to be queried. The relationships that this layer/table participates in are included in the Layer / Table Resource response. Records in tables/layers corresponding to the related table/layer of the relationship are queried. Example `relationshipId=4`
outFields	The list of fields from the related table/layer to be included in the returned featureset. 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 `outFields=AREANAME,ST,POP2000 //wildcard usage outFields=`
definitionExpression	The definition expression to be applied to the related table/layer. From the list of records that are related to the specified objectIds, only those records that conform to this expression will be returned. Example `definitionExpression=POP2000 > 100000`
returnGeometry	If true, the featureset includes the geometry associated with each feature. The default is true. Note: This parameter only applies to related layers. It will be ignored for related tables. Values: true \| false
maxAllowableOffset	This option was added at 10.0. This option can be used to specify the maxAllowableOffset to be used for generalizing geometries returned by the query related records operation. The maxAllowableOffset is in the units of the outSR. If outSR is not specified, the maxAllowableOffset is assumed to be in the unit of the spatial reference of the map. Example `maxAllowableOffset=2`
geometryPrecision	This option was added at 10.1. This option can be used to specify the number of decimal places in the response geometries returned by the queryRelatedRecords operation. This applies to X and Y values only (not m- or z-values). Example `geometryPrecision=3`
historicMoment	This option was added at 10.5 and works with ArcGIS Enterprise 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 `historicMoment=<Epoch time in milliseconds>` Example `historicMoment=1199145600000`
outSR	The spatial reference of the returned geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference json object. If outSR is not specified, the geometry is returned in the spatial reference of the map. Note: This parameter only applies to related layers. It will be ignored for related tables.
returnZ	This option was added at 10.1. If true, Z values will be included in the results if the features have Z values. Otherwise, Z values are not returned. The default is false. Note: This parameter only applies if returnGeometry is true. Values: true \| false
returnM	This option was added at 10.1. If true, M values will be included in the results if the features have M values. Otherwise, M values are not returned. The default is false. Note: This parameter only applies if returnGeometry is true. Values: true \| false
returnTrueCurves	This option was added at 10.5. Optional parameter that is false by default. When set to true, returns true curves in output geometries; otherwise, curves are converted to densified polylines or polygons. Values: true \| false
gdbVersion	This option was added at 10.1. GeoDatabase version to query. This parameter applies only if hasVersionedData of the property of the service and isDataVersioned property of the layer(s) queried are true. If this is not specified, query will apply to published map's version. Syntax `gdbVersion=<geodatabase version>` Example `gdbVersion=sde.USER1`
timeReferenceUnknownClient	Setting timeReferenceUnknownClient as true indicates that the client is capable of working with data values that are not in UTC. If its not set to true, and the service layer's datesInUnknownTimeZone property is true, then an error is returned. The default is false Its possible to define a service's time zone of date fields as unknown. Setting the time zone as unknown means that date values will be returned as-is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the datesInUnknownTimeZone layer property as true. Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields which are stored and returned in UTC even when the time zone is set to unknown. Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service in order to avoid problems.. Setting this parameter to true indicates that the client is capable of working with unknown date values that are not in UTC. Note: ArcGIS Pro 2.7 or newer can work with these feature services. Value: true \| false
f	The response format. The default response format is html. Values: html \| json \| pjson

Example usage

https://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Petroleum/KSPetro/MapServer/0/queryRelatedRecords?objectIds=3,4,5&relationshipId=2&returnGeometry=true&outFields=*&f=html

JSON Response syntax

            
          
{
  "geometryType": "<geometryType>", //if records include geometry
  "spatialReference": <spatialReference>, //if records include geometry
  "hasZ": <true|false>, //added in 10.1
  "hasM": <true|false>, //added in 10.1
  "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 examples

            
          
{
  "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
                ]
              ]
            ]
          }
        }
      ]
    }
  ]
}

{
  "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
                ]
              ]
            ]
          }
        }
      ]
    }
  ]
}