- URL:
- https://<root>/<serviceName>/FeatureServer/<layerId>/query3D
- Methods:
GET
- 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 |
---|---|
| A SQL-92
For information on how to format time and date information, see the Date-time queries section below. Examples
|
|
The object IDs of this layer or table to be queried. Syntax
Example
|
|
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: Syntax
Example
|
|
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:
|
|
The type of geometry specified by the Values: |
| 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 |
|
The spatial relationship to be applied to the input At 10.9.1, a Values: |
| The buffer distance for the input geometries. The distance unit is specified by Syntax
Example
|
| Specifies the unit for the buffer distance. If no value is specified, the default will be Values: |
| The spatial relate function that can be applied while performing the |
| 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 Example
|
| This parameter was added at 10.6.1. This parameter specifies the condition used with Values: |
|
The geodatabase version to query. This parameter applies only if the Syntax: Example: |
| 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 Syntax
Example
|
| Specifies whether distinct values based on the fields specified in Values: |
| One or more field names on which the features or records will be ordered. Use Syntax
Example
|
| One or more field names on which the values will be grouped for calculating the statistics. This parameter is valid only when the Syntax
Example
|
| The definitions for one or more field-based statistics to be calculated. This parameter is supported only on layers and tables that indicate Syntax
Example
|
| 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 ( 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: |
| The number of records that will be skipped when fetching query results. The first query result will be the next record (that is, Example
|
| The number of query results that will be fetched. When Example
|
| Specifies whether the client is capable of working with data values that are not in UTC. If this is set to 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 Most clients released prior to ArcGIS Enterprise 10.9 cannot work with feature services that have an unknown time setting. The Value: |
| The SQL format that will be used. The value can be standard SQL-92 ( Values: |
| The response format. The default response format is Example
Values: |
Date-time queries
Time zone properties
The date
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.
When you are working with data, consider the time zone of the associated fields. If you are querying a date type field and date
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 date
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_
, 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 date
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 date
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.
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_
and CURRENT_
values. Both can be used with +
or -
of INTERVAL
values.
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 SECOND
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 statistic
value is supported if the supports
layer property (in advanced
) 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 statistic
values, PERCENTILE_
(discrete) and PERCENTILE_
(continuous). Discrete returns a data value from that dataset; continuous is an interpolated value.
The order
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 order
set to ASC
is 9. The percentile value for 0.9 with order
set to DESC
is 2. The default is ASC
.
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 sql
parameter and what you can expect from the query API:
sqlFormat value | useStandardizedQuery is true | useStandardizedQuery is false |
---|---|---|
| Yes | Yes |
| Not supported | Yes |
| Only SQL-92 ( | 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
}
]
}