- URL:https://<featurelayer-url>/query3D
- Version Introduced:11.1
Description
The query3D operation allows clients to query 3D object features based on the feature service layer-level query operation. Each 3D object feature layer also supports layer- and service-level query operations.
Request parameters
| Parameter | Details |
|---|---|
| where | A WHERE clause for the query filter. SQL-92 WHERE clause syntax is supported on the fields in the layer for most data sources. Some data sources restrict what is supported. Hosted feature services in ArcGIS Enterprise running on a spatiotemporal data source only support a subset of SQL-92. For example, spatiotemporal-based feature services support the like operator but do not support the not like operator or field equivalency expressions such as field1 = field2. The following is a list of supported SQL-92 with spatiotemporal-based feature services: For information on how to format time and date information, see the Date-time queries section below. Examples |
| objectIds | The object IDs of this layer or table to be queried. Note:There might be a drop in performance if the layer/table data source resides in an enterprise geodatabase and more than 1,000 objectIds are specified. Syntax Example |
| time | The time instant or the time extent to query. A null value specified for start time or end time will represent infinity for start or end time, respectively. Example: time=null, 1230768000000 Syntax Example |
| geometry | The geometry to apply as the spatial filter. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, you can specify the geometry of envelopes and points with a simple comma-separated syntax. Syntax:
Examples:
|
| geometryType | The type of geometry specified by the geometry parameter. The geometry type can be an envelope, a point, a line, or a polygon. The default geometry type is an envelope. Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope |
| inSR | The spatial reference of the input geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If the inSR value is not specified, the geometry is assumed to be in the spatial reference of the layer. |
| spatialRel | The spatial relationship to be applied to the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelope intersects, within, and so on. The default spatial relationship is intersects (esriSpatialRelIntersects). At 10.9.1, a supportedSpatialRelationships property can be provided on the layer resource that specifies which spatial relationships are supported. Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin |
| distance | The buffer distance for the input geometries. The distance unit is specified by units. For example, if the distance is 100, the query geometry is a point, units is set to meters, and all points within 100 meters of the point are returned. The geodesic buffer is created based on the datum of the output spatial reference if it exists. If there is no output spatial reference, the input geometry spatial reference is used. Otherwise, the native layer spatial reference is used to generate the geometry buffer used in the query. This parameter only applies if supportsQueryWithDistance is true. Syntax Example |
| units | Specifies the unit for the buffer distance. If no value is specified, the default will be esriSRUnit_Foot when querying feature services in ArcGIS Enterprise, and esriSRUnit_Meter when querying feature services in ArcGIS Online. This parameter only applies if supportsQueryWithDistance is true. Values: esriSRUnit_Meter | esriSRUnit_StatuteMile | esriSRUnit_Foot | esriSRUnit_Kilometer | esriSRUnit_NauticalMile | esriSRUnit_USNauticalMile |
| relationParam | The spatial relate function that can be applied while performing the query operation. An example is "FFFTTT***". For more information about this spatial relate function, see thee spatial relate function documentation. Note:This parameter is not supported for ArcGIS Online hosted services. |
| outFields | The list of fields to be included in the returned result set. This list is a comma-delimited list of field names. You can also use the wildcard * as the value. In this case, the query results include all the field values. Example |
| havingClause | This parameter was added at 10.6.1. This parameter specifies the condition used with outStatistics that limits the query result to groups that satisfy the aggregation function used. It is used with the groupBy and outStatistics parameters and allows you to filter results from outStatistics. This parameter applies only if the supportsHavingClause property of the layer is true. Note:The havingClause parameter takes aggregate functions such as AVG(<fieldname>). It does not support the outStatisticFieldName value from the outStatistics parameter. For example, the having clause can't be set to >1000; it must be set as AVG(housing_price > 1000. You can also use statistics functions in the
having clause that are not in the outStatisticsparameter. For example, the following returns the average housing price for neighborhoods with more than 1,000 homes: Values: AVG | COUNT | SUM | STDDEV | MIN | MAX | VAR Note:havingClause must be used with groupBy and outStatistics. |
| gdbVersion | The geodatabase version to query. This parameter applies only if the isDataVersioned property of the layer is true. If this is not specified, the query will apply to the published map’s version. Syntax: gdbVersion=<version> Example: gdbVersion=SDE.DEFAULT |
| historicMoment | This parameter works with ArcGIS Server services only. This is the historic moment to query. This parameter applies only if the layer is archive enabled and the supportsQueryWithHistoricMoment property is set to true. This property is provided in the layer resource. If historicMoment is not specified, the query will apply to the current features. Syntax Example |
| returnDistinctValues | Specifies whether distinct values based on the fields specified in outFields will be returned. This parameter applies only if the supportsAdvancedQueries property of the layer is true. Values: true | false |
| orderByFields | One or more field names on which the features or records will be ordered. Use ASC or DESC for ascending or descending, respectively, following every field to control the ordering. orderByFields defaults to ASC if <ORDER> is unspecified. orderByFields is only supported for layers and tables that specify supportsAdvancedQueries is true. Note:If supportsOrderByOnlyOnLayerFields is true, only fields from the layer's fields array can be used with the orderByFields parameter. For example, the outStatisticfieldName value from outStatistics can't be used if supportsOrderByOnlyOnLayerFields is true. Syntax Example |
| groupByFieldsForStatistics | One or more field names on which the values will be grouped for calculating the statistics. This parameter is valid only when the outStatistics parameter is used. Syntax Example |
| outStatistics | The definitions for one or more field-based statistics to be calculated. This parameter is supported only on layers and tables that indicate supportsStatistics is true. When using this parameter, the only other parameters that can be used are groupByFieldsForStatistics, orderByFields, time, and where. For information about how to use percentile as the statisticTypevalue, see the Percentile statistic type section below. Note:If outStatisticFieldName is empty or missing, the map server assigns a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore. If the outStatisticFieldName value is a reserved keyword of the underlying DBMS, the operation may fail. Try specifying an alternative outStatisticFieldName value. Syntax Example |
| formatFor3DObjects | Specifies the 3D format that will be used to request a feature. If set to a valid format ID (see layer resource), the geometry of the feature response will be a 3D envelope of the 3D object and will include asset maps for the 3D object. Since formats are created asynchronously, review the flags field in the asset map to determine if the format is available (conversionStatus is COMPLETED). If conversionStatus is INPROGRESS, the format is not ready. Request the feature again later. If a feature does not have the specified format, the feature will still be returned according to the query parameters (such as the where clause), but the asset mapping will be missing. Potential values: 3D_dae | 3D_dwg | 3D_fbx | 3D_glb | 3D_gltf | 3D_ifc | 3D_obj | 3D_shapebuffer | 3D_shapebufferg | 3D_usdc | 3D_usdz |
| resultOffset | The number of records that will be skipped when fetching query results. The first query result will be the next record (that is, resultOffset + 1). The default is 0. This parameter only applies if supportsPagination is true. You can use this parameter to fetch records that are beyond the maxRecordCount value. Example |
| resultRecordCount | The number of query results that will be fetched. When resultOffset is specified but this parameter is not, the maxRecordCount value is used by default. The maximum value for this parameter is the value of the layer's maxRecordCount property. The minimum value provided for this parameter cannot be below 1. This parameter only applies if supportsPagination is true. Example |
| timeReferenceUnknownClient | Specifies whether the client is capable of working with data values that are not in UTC. If this is set to false, and the service layer's datesInUnknownTimeZone property is true, an error is returned. The default is false You can define a service 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. Feature services that are not hosted can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zone 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 cannot work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service 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 later can work with these feature services. Value: true | false |
| sqlFormat | The SQL format that will be used. The value can be standard SQL-92 (standard), the native SQL of the underlying data store (native, or none, which indicates the sqlFormat value depends on the useStandardizedQuery parameter. The default is none. The native format is supported when useStandardizedQuery is false. For more information about formatting, see the SQL format section below. Values: none | standard | native |
| f |
The response format. The default response format is html. The supportsQueryFormats layer property describes which formats are supported. The default response format, html, is always supported. Example Values: html | json | geojson | pbf |
Date-time queries
Time zone properties
The dateFieldsTimeReference property of the feature service layer identifies the time zone in which all dates are stored with the exception of editor tracking fields or time aware layer time zones, as those have separate properties that identify their time zones.
To find the time zone of the editor tracking fields, find the dateFieldsTimeReference property in the editFieldsInfo array in the layer JSON. To find the time zone of the time aware function, find the timeZone property in the timeInfo array in the layer JSON.
When you are working with data, consider the time zone of the associated fields. If you are querying a date type field and dateFieldsTimeReference is set to a specific time zone, ensure that the where clause issues the time in that time zone. For example, to return all the records that match 1:00 p.m. on February 9, 2015, Pacific standard time, the where clause is as follows:
Querying records in PST
where=pacific_time_date_field = DATE '2015-02-09 13:00:00'However, it is possible to have up to three different time zones defined for a service. If the query includes dates from the editor tracking fields or the time aware fields, ensure you submit the query in the respective time zones. The time zones for these fields are indicated in the properties mentioned above. If the dateFieldsTimeReference value is null, the data is assumed to be in UTC. If it is unknown, the time zone is assumed to be undefined. The example below demonstrates how to query three date fields that have three times zones. When querying fields in different time zones, ensure that the time you use corresponds to the time zone of the date field. In this example, there is a date field in PST, EST, and the editor tracking field, created_date, in UTC:
Querying records in three time zones
where=(DateTime_PST=TIMESTAMP '2012-01-01 15:20:00' AND (DateTime_EST=TIMESTAMP '2012-01-01 18:20:00' AND created_date=TIMESTAMP '2012-01-01 22:20:00')Although you issue local time in the where clause, the query operation returns date values in UTC. You can set the date fields time zone, which appears in the dateFieldsTimeReference property of the feature service layer either during publishing or in ArcGIS Server Manager after publishing. In Server Manager, browse to the service you want to edit and click the Parameters tab to update the time zone information. If the dateFieldsTimeReference property is not set, it will appear as null and the data will be assumed to be in UTC. In this case, issue the where clause in UTC.
At ArcGIS Pro 3.1, a new option for defining the time zone during publishing is available. If you don't want to define a time zone at all (including in UTC), you can set it this option to Unknown. Using an unknown time zone makes it so no translation occurs when the query operation submits and returns date values. They are stored and returned as is. This is useful if you have data that spans multiple time zones.
Note:
Not all clients support working with services that have an unknown time zone.Date and time format
The INTERVAL syntax can be used in place of the date-time queries and is standardized across all map and feature services. The INTERVAL syntax can be used to specify either the current date or a time stamp in the query:
//Date
<DateField> >= CURRENT_DATE -+ INTERVAL '<IntervalValue>' <TimeStampFormat>
//Timestamp
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL '<IntervalValue>' <TimeStampFormat>For the syntax above, you can interchange the CURRENT_DATE and CURRENT_TIMESTAMP values. Both can be used with + or - of INTERVAL values.
Note:
For relational and spatiotemporal hosted feature services, CURRENT_TIMESTAMP will always pass and return the date and time in UTC. Values are always stored in UTC. For referenced services, CURRENT_TIMESTAMP is passed directly to the backend database and the database will use the time zone of the machine it is running on, which can be the same time zone as the dateFieldsTimeReference value.
The examples below outline the ways in which the INTERVAL syntax can be modified for the purposes of a query:
//'DD' Day
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD' DAY
//'HH' Hour
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH' HOUR
//'MI' Minute
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI' MINUTE
//'SS(.FFF)' Second
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'SS(.FFF)' SECOND
//'DD HH' DAY TO HOUR
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH' DAY TO HOUR
//'DD HH:MI' DAY TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI' DTY TO MINUTE
//'DD HH:MI:SS(.FFF)' DAY TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI:SS(.FFF)' DAY TO SECOND
//'HH:MI' HOUR TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:MI' HOUR TO MINUTE
//'HH:SS(.FFF)' HOUR TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:SS(.FFF)' HOUR TO SECOND
//'MI:SS(.FFF)' MINUTE TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI:SS(.FFF)' MINUTE TO SECONDNote:
There are additional considerations. Except for the second (.FFF) value, all values must be integers. If a date field is specified in the outFields list, the date-time will be returned in formatted UTC.
To demonstrate the INTERVAL format, the example below uses the INTERVAL syntax to query data gathered over 3 days, 5 hours, 32 minutes, and 28 seconds:
DateField >= CURRENT_TIMESTAMP - INTERVAL '3 05:32:28' DAY TO SECOND
Percentile statistic type
The percentile statisticType value is supported if the supportsPercentileStatistics layer property (in advancedQueryCapabilities) is true. The percentile indicates the value below or above which a given percentage of values in a group of data values falls. For example, the ninetieth percentile (value 0.9) is the value below which 90 percent of the data values may be found. For percentile statistics, there are two statisticTypes values, PERCENTILE_DISC (discrete) and PERCENTILE_CONT (continuous). Discrete returns a data value from that dataset; continuous is an interpolated value.
The orderBy statistic parameter can also be used to calculate percentile. For example, in a set of 10 values from 1 to 10, the percentile value for 0.9 with orderBy set to ASC is 9. The percentile value for 0.9 with orderBy set to DESC is 2. The default is ASC.
Note:
The percentile statisticTypes value cannot be used with the havingClause parameter.
Syntax
[
{
"statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
"statisticParameters": {
"value": percentile_value,
"orderBy": "<ASC | DESC>"
},
"onStatisticField": "Field1",
"outStatisticFieldName": "Out_Field_Name1"
},
{
"statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
"statisticParameters": {
"value": percentile_value,
"orderBy": "<ASC | DESC>"
},
"onStatisticField": "Field2",
"outStatisticFieldName": "Out_Field_Name2"
}
]Example
[
{
"statisticType": "PERCENTILE_CONT",
"statisticParameters": {
"value": 0.9
},
"onStatisticField": "NEAR_DIST",
"outStatisticFieldName": "pop90_cont"
},
{
"statisticType": "PERCENTILE_DISC",
"statisticParameters": {
"value": 0.9,
"orderBy": "DESC"
},
"onStatisticField": "population",
"outStatisticFieldName": "pop90_desc"
}
]SQL format
The following table summarizes the sqlFormat parameter and what you can expect from the query API:
| sqlFormat value | useStandardizedQuery is true | useStandardizedQuery is false |
|---|---|---|
standard (SQL-92) | Yes | Yes |
native (native DBMS SQL) | Not supported | Yes |
none | Only SQL-92 (standard) | Only DBMS native SQL (native) |
Example usage
The following is a sample request URL for the query3D endpoint:
https://machine.domain.com/webadaptor/rest/services/City_Park_Assets/FeatureServer/0/query3D?JSON Response syntax
{
"objectIdFieldName": <objectIdFieldName>,
"globalIdFieldName": <globalIdFieldName>,
"geometryType": <geometryType>,
"spatialReference": "<spatialReferenceOfTheReturedFeatures>",
"fields": [
{
"name": "field1",
"type": "fieldType1",
"alias": "alias1"
},
{
"name": "field2",
"type": "fieldType2",
"alias": "alias2"
}
],
"assetMapFields": [
{
"name": "field1",
"type": "fieldType1",
"alias": "alias1"
},
{
"name": "field2",
"type": "fieldType2",
"alias": "alias2"
}
],
"features": [
<feature1>,
<feature2>
],
"assetMaps": [
<assetMapping1>,
<assetMapping2>,
<assetMapping3>
]
}JSON Response example
{
"objectIdFieldName": "objectid",
"globalIdFieldName": "GlobalID",
"geometryType": "esriGeometryMultipatch",
"spatialReference": {
"wkid": 4326,
"latestWkid": 0,
"vcsWkid": 0,
"latestVcsWkid": 0,
"xyTolerance": 0,
"zTolerance": 0,
"mTolerance": 0,
"falseX": true,
"falseY": true,
"xyUnits": true,
"falseZ": true,
"zUnits": true,
"falseM": true,
"mUnits": true
},
"fields": [
{
"name": "objectid",
"type": "esriFieldTypeOID",
"alias": "Object ID"
},
{
"name": "GlobalID",
"type": "esriFieldTypeUUID",
"alias": "Global ID"
},
{
"name": "datetime",
"type": "esriFieldTypeDate",
"alias": "Earthquake Date",
"length": 36
},
{
"name": "depth",
"type": "esriFieldTypeDouble",
"alias": "Depth"
},
{
"name": "ESRI3DO_TYPE",
"type": "esriFieldTypeString",
"alias": "Asset Type",
"length": 16
},
{
"name": "ESRI3DO_SHASH",
"type": "esriFieldTypeString",
"alias": "Source Hash",
"length": 80
},
{
"name": "ESRI3DO_OX",
"type": "esriFieldTypeDouble",
"alias": "3D asset origin X"
},
{
"name": "ESRI3DO_OY",
"type": "esriFieldTypeDouble",
"alias": "3D asset origin Y"
},
{
"name": "ESRI3DO_OZ",
"type": "esriFieldTypeDouble",
"alias": "3D asset origin Z"
},
{
"name": "ESRI3DO_TX",
"type": "esriFieldTypeDouble",
"alias": "3D translation X"
},
{
"name": "ESRI3DO_TY",
"type": "esriFieldTypeDouble",
"alias": "3D translation Y"
},
{
"name": "ESRI3DO_TZ",
"type": "esriFieldTypeDouble",
"alias": "3D translation Z"
},
{
"name": "ESRI3DO_SX",
"type": "esriFieldTypeDouble",
"alias": "3D scale X"
},
{
"name": "ESRI3DO_SY",
"type": "esriFieldTypeDouble",
"alias": "3D scale Y"
},
{
"name": "ESRI3DO_SZ",
"type": "esriFieldTypeDouble",
"alias": "3D scale Z"
},
{
"name": "ESRI3DO_RX",
"type": "esriFieldTypeDouble",
"alias": "3D rotation direction X"
},
{
"name": "ESRI3DO_RY",
"type": "esriFieldTypeDouble",
"alias": "3D rotation direction Y"
},
{
"name": "ESRI3DO_RZ",
"type": "esriFieldTypeDouble",
"alias": "3D rotation direction Z"
},
{
"name": "ESRI3DO_RDEG",
"type": "esriFieldTypeDouble",
"alias": "3D rotation"
}
],
"assetMapFields": [
{
"name": "ESRI3DO_PID",
"type": "esriFieldTypeGUID",
"alias": "Feature GUID"
},
{
"name": "ESRI3DO_FLAGS",
"type": "esriFieldTypeInteger",
"alias": "Asset Flags"
},
{
"name": "ESRI3DO_NAME",
"type": "esriFieldTypeString",
"alias": "Asset Symbolic Name",
"length": 512
},
{
"name": "ESRI3DO_TYPE",
"type": "esriFieldTypeString",
"alias": "Asset Type",
"length": 16
},
{
"name": "ESRI3DO_SIZE",
"type": "esriFieldTypeInteger",
"alias": "Asset Size [bytes]"
},
{
"name": "ESRI3DO_CPLX",
"type": "esriFieldTypeInteger",
"alias": "Asset Complexity"
},
{
"name": "ESRI3DO_SIZE",
"type": "esriFieldTypeInteger",
"alias": "Asset size [bytes]"
},
{
"name": "ESRI3DO_AHASH",
"type": "esriFieldTypeString",
"alias": "Asset hash",
"length": 80
},
{
"name": "ESRI3DO_SHASH",
"type": "esriFieldTypeString",
"alias": "Source Hash",
"length": 80
},
{
"name": "ESRI3DO_SEQNO",
"type": "esriFieldTypeInteger",
"alias": "Asset sequence number"
}
],
"features": [
{
"attributes": {
"objectid": 3745682,
"datetime": 1272210710000,
"depth": 31.1,
"eqid": "2010vma5",
"latitude": 33.8,
"longitude": -118.15,
"magnitude": 4.8,
"numstations": 112,
"region": "Andrean of Islands, Aleutian Islands, Alaska",
"source": "us",
"version": "Q",
"GlobalID": "{064185b3-d827-fa42-a9bb-aff1ccb9b6a1}",
"ESRI3DO_TYPE": "3D_glb",
"ESRI3DO_SHASH": "6486ee53c8faba18045ef29d382f1c8227bde3a25d37f7a62fe0d2259a3a14dd",
"ESRI3DO_OX": -118.15,
"ESRI3DO_OY": 33.8,
"ESRI3DO_OZ": -12,
"ESRI3DO_TX": 0,
"ESRI3DO_TY": 0,
"ESRI3DO_TZ": 0,
"ESRI3DO_SX": 1,
"ESRI3DO_SY": 1,
"ESRI3DO_SZ": 1,
"ESRI3DO_RX": 0,
"ESRI3DO_RY": 1,
"ESRI3DO_RZ": 0,
"ESRI3DO_RDEG": 0
},
"geometry": {
"xmin": -109.55,
"ymin": 25.76,
"xmax": -86.39,
"ymax": 49.94,
"zmin": -12,
"zmax": 13.3
}
}
]
"assetMaps": [
{
"globalId": "{9db72076-e109-467e-94c7-3d5a3a4ef9ef}",
"parentGlobalId": "{064185b3-d827-fa42-a9bb-aff1ccb9b6a1}",
"assetName": "geometry.glb",
"assetHash": "6486ee53c8faba18045ef29d382f1c8227bde3a25d37f7a62fe0d2259a3a14dd",
"assetType": "3D_glb",
"flags": ["PROJECT_VERTICES"],
"conversionStatus": "COMPLETED",
"size": 8940,
"complexity": 354,
"sourceHash": "6486ee53c8faba18045ef29d382f1c8227bde3a25d37f7a62fe0d2259a3a14dd",
"assetURL": https://machine.domain.com/webadapter/rest/services/ESRI3DO/FeatureServer/0/6486ee53c8faba18045ef29d382f1c8227bde3a25d37f7a62fe0d2259a3a14dd.glb,
"seqNo": 0
}
]
}