Query Related Records (Feature Service)

Description

NoteNote:

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.

The query 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.

You can provide arguments to the queryRelatedRecords operation as query parameters defined in the following parameters table:

New in 10.7

AMF as an output format is no longer supported.

New in 10.5

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

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

objectIds=<objectId1>, <objectId2>

Example

objectIds=37, 462
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

relationship=4
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

outFields=AREANAME,ST,POP2000

//wildcare usage
outFields=*
definitionExpression

The definition expression to be applied to the related table or layer. From the list of objectIds, only those records that conform to this expression are queried for related records.

Example

definitionExpression=POP2000 > 100000
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 was added at 10.1. 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

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 query operation. This applies to X and Y values only (not m- or z-values).

Example

geometryPrecision=3
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.

NoteNote:
This parameter only applies if supportsQueryRelatedPagination is true.

Example

//If maxRecordCount is set to 1000, this will return the query results in range of 1001 to 1100.
resultOffset=1000
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.

NoteNote:
This parameter only applies if supportsQueryRelatedPagination is true.

Example

//Will fetch up to 10 records
resultRecordCount=10
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

This option was added at 10.1. 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

gdbVersion=<version>

Example

gdbVersion=SDE.DEFAULT
historicMoment

This option was added at 10.5 and 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

histrociMoment=<Epoch time in milliseconds>

Example

historicMoment=1199145600000
returnZ

This option was added at 10.1. 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

This option was added at 10.1. 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)

This option was added at 10.5. 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

trueCurveClient=true
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.

NoteNote:

This parameter only applies if supportsAdvancedQueryRelated is true.

Syntax

orderByFields=<fieldName1>,<fieldName2>

Example

orderByFields=TOWNSHIP,RANGE
returnCountOnly

If true, returns the count of the related records for each object ID. The default is false.

NoteNote:
  • This parameter only applies if supportsAdvancedQueryRelated is true.
  • This parameter will overwrite all other queryRelated parameters and responses.

Values: true | false

Example

returnCountOnly=true
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 Coordinate systems and transformations (values applicable for ArcGIS Desktop, ArcGIS Enterprise, ArcGIS Pro, and ArcGIS Runtime). For more information on datum transformations, please see the transformation parameter in the Project operation.

Syntax

//Syntax to apply a simple transformation
datumTransformation=<wkid>

//Syntax to apply a simple transformation
datumTransformation={"wkt": "<WKT>"}

//Syntax to apply a composite transformation
datumTransformation={"geoTransforms":[{"wkid":<id>,"forward":<true|false>},{"wkt":"<WKT>","forward":<true|false>}]}

Example

//Applies a simple tranformation
datumTransformation=1623

//Applies a composite transformation
datumTransformation={
  "geoTransforms":[
    {
      "wkid":1088,
      "transformForward": true
    },
    {
      "wkit": "GEOGTRAN[\"S_JTSK_To_WGS_1984_1\",GEOGCS[\"GCS_S_JTSK\",DATUM[\"D_S_JTSK\",SPHEROID[\"Bessel_1841\",6377397.155,299.1528128]],
        PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_
        1984\",6378137.0,298.257223563]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],METHOD[\"Position_Vector\"],
        PARAMETER[\"X_Axis_Translation\",570.8],PARAMETER[\"Y_Axis_Translation\",85.7],PARAMETER[\"Z_Axis_Translation\",462.8],
        PARAMETER[\"X_Axis_Rotation\",4.998],PARAMETER[\"Y_Axis_Rotation\",1.587],PARAMETER[\"Z_Axis_Rotation\",5.261],
        PARAMETER[\"Scale_Difference\",3.56]]",
      "transformForward":false
    }
  ]
}
f

The response format. The default response format is html.

Values: html | json

Example usage

Example 1: Below is a sample GET request URL. This queries related records as defined by relationship ID 2 that are related to objectIds 3, 4, and 5 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=html

Example 2: Below is a sample GET request URL. This request pages through a query result using resultOffset and resultRecordCount to get the next set of results. Requesting to skip the first two records and return the next four records where the ObjectID>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=html

Example 3: Below is a sample GET request URL. This query will return the related records count for each objectIds and orderByField TOWNSHIP:

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 4: Below is a sample GET request URL. The query results will return the related records for each objectIds where TOWNSHIP is 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>, //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 example

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

JSON Response example

The example below demonstrates a response that is returned when the request is sent with the following values: objectIds=7028,7029, relationshipId=1, outFields=TOWNSHIPS,RANGE, orderByFields=TOWNSHIP,RANGE, returnCountryOnly=false, and returnGeometry=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
  }
}

JSON Response example

The example below demonstrates a response that is returned when the request is sent with the following values: objectIds=7028,7029, relationshipId=1, returnCountyOnly=true, and returnGeometry=false.

{
  "relatedRecordGroups": [
    {
      "objectId": 7028, 
      "count": 10218
    }, 
    {
      "objectId": 7029, 
      "count": 3304
    }
  ]
}
Copyright © 1995-2020 Esri. All rights reserved.