Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.data

Class QueryParameters

java.lang.Object
com.esri.arcgisruntime.data.QueryParameters
public final class QueryParameters extends Object
Parameters to perform a query on a dataset.

These parameters provide attribute, spatial, and temporal criteria that you can use to filter features. You can define attribute criteria using a standard SQL expression based on the available attribute fields, spatial criteria using a geometry and a spatial relationship (such as within, contains, intersect), or temporal filters using a single date/time, or a range. You can also control how the results are sorted and whether to return geometry.

In addition to querying features in a table, you can also use these parameters to count specific features, calculate the extent of features, select features in layers, and populate service-based tables. If the query method produces a set of features, they are returned in a FeatureQueryResult.

Different query parameter objects are available to query data sources such as related features (RelatedQueryParameters), statistical information (StatisticsQueryParameters), and portals (PortalQueryParameters). Specialized query parameters also exist for working with utility networks and routing.

Since:
100.0.0
See Also:

  • Constructor Details

    • QueryParameters

      public QueryParameters()
      Creates a new instance.
      Since:
      100.0.0

  • Method Details

    • getWhereClause

      public String getWhereClause()
      Gets the attribute expression that defines features to be included in the query.

      The where clause should follow standard SQL syntax similar to that discussed in the document SQL reference for query expressions used in ArcGIS

      If the where clause includes dates, they must be correctly formatted based on the geodatabase datasource used in the service. Refer to Dates and time for date formats expected by different data sources.

      ArcGISFeatureTable objects expect that any Field.Type.GLOBALID or Field.Type.GUID parameters in the where clause are formatted as: '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'. All characters are uppercase, wrapped in curly braces and surrounded by single quotes.

      If the where clause is used to populate an OgcFeatureCollectionTable, you can use a CQL2-TEXT or CQL2-JSON string as defined in the document OGC API - Features - Part3.

      Returns:
      the attribute expression that defines features to be included in the query
      Since:
      100.0.0
      See Also:

    • setWhereClause

      public void setWhereClause(String whereClause)
      Sets the attribute expression that defines features to be included in the query.

      The where clause should follow standard SQL syntax similar to that discussed in the document SQL reference for query expressions used in ArcGIS

      If the where clause includes dates, they must be correctly formatted based on the geodatabase datasource used in the service. Refer to Dates and time for date formats expected by different data sources.

      ArcGISFeatureTable objects expect that any Field.Type.GLOBALID or Field.Type.GUID parameters in the where clause are formatted as: '{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'. All characters are uppercase, wrapped in curly braces and surrounded by single quotes.

      If the where clause is used to populate an OgcFeatureCollectionTable, you can use a CQL2-TEXT or CQL2-JSON string as defined in the document OGC API - Features - Part3.

      Parameters:
      whereClause - the attribute expression that defines features to be included in the query
      Since:
      100.0.0
      See Also:

    • getGeometry

      public Geometry getGeometry()
      Gets the geometry used to filter the results.

      The geometry that (along with the getSpatialRelationship()) defines features to be included in the query.

      Returns:
      the geometry used to filter the results, or null if none
      Since:
      100.0.0

    • setGeometry

      public void setGeometry(Geometry geometry)
      Sets the geometry used to filter the results.

      The geometry that (along with the getSpatialRelationship()) defines features to be included in the query.

      Parameters:
      geometry - the geometry used to filter the results
      Since:
      100.0.0

    • getSpatialRelationship

      public QueryParameters.SpatialRelationship getSpatialRelationship()
      Gets the spatial relationship that (along with the getGeometry()) defines features to be included in the query.

      The default spatial relationship is QueryParameters.SpatialRelationship.INTERSECTS.

      Returns:
      the spatial relationship that (along with the QueryParameters.getGeometry()) defines features to be included in the query.
      Since:
      100.0.0

    • setSpatialRelationship

      public void setSpatialRelationship(QueryParameters.SpatialRelationship spatialRelationship)
      Sets the spatial relationship that (along with the setGeometry(Geometry)) defines features to be included in the query.

      The default spatial relationship is QueryParameters.SpatialRelationship.INTERSECTS.

      Parameters:
      spatialRelationship - the spatial relationship that (along with the QueryParameters.setGeometry()) defines features to be included in the query.
      Throws:
      IllegalArgumentException - if input is null
      Since:
      100.0.0

    • getOutSpatialReference

      public SpatialReference getOutSpatialReference()
      Gets the spatial reference of the feature results' geometry.

      If not specified, geometries are returned in the spatial reference of the service.

      Returns:
      the spatial reference of the feature results' geometry, or null if none
      Since:
      100.0.0

    • setOutSpatialReference

      public void setOutSpatialReference(SpatialReference outSR)
      Sets the spatial reference of the feature results' geometry.

      If not specified, geometries are returned in the spatial reference of the service.

      Parameters:
      outSR - the spatial reference of the feature results' geometry reference is same as the spatial reference of the input geometry.
      Since:
      100.0.0

    • getInSpatialReference

      public SpatialReference getInSpatialReference()
      Gets the spatial reference of the set geometry.
      Returns:
      the spatial reference of the set geometry. If no geometry is set, then null.
      Since:
      100.0.0

    • setReturnGeometry

      public void setReturnGeometry(boolean returnGeometry)
      True if geometry values are returned in the results, otherwise false.

      This is needed when you want to display the features on a map or a scene. When querying non-spatial data, results do not include geometry.

      Parameters:
      returnGeometry - true if geometry values are returned in the results, otherwise false
      Since:
      100.0.0

    • isReturnGeometry

      public boolean isReturnGeometry()
      True if geometry values are returned in the results, otherwise false.

      This is needed when you want to display the features on a map or a scene. When querying non-spatial data, results do not include geometry.

      Returns:
      true if geometry values are returned in the results, otherwise false
      Since:
      100.0.0

    • getObjectIds

      public List<Long> getObjectIds()
      Gets a mutable list of object IDs of the features to be queried. By default this list is empty. Add to this list to query for an object ID.
      Returns:
      the object IDs of the features to be queried
      Since:
      100.0.0

    • getOrderByFields

      public List<QueryParameters.OrderBy> getOrderByFields()
      Gets the fields by which query results will be ordered.

      Results can be sorted by one or more fields. Each QueryParameters.OrderBy instance includes a field name and whether to sort by that field in ascending or descending order. If a service-based table is being queried it must support advanced queries.

      Returns:
      the fields by which query results will be ordered
      Since:
      100.0.0

    • setMaxFeatures

      public void setMaxFeatures(int maxFeatures)
      Sets the maximum number of features the query should return. If 0, then there is no limit set on the number of features.

      For consistent ordering of results when using pagination, provide a value for getOrderByFields(). Note that if you provide a maximum features value to support paging of results, you must also set a getResultOffset() value. Otherwise, the result may contain local features in place of server features if they satisfy the query. To ensure strict paging of server features, specify both maximum features and QueryParameters.getResultOffset().

      Parameters:
      maxFeatures - the maximum number of features to be included in the result
      Throws:
      IllegalArgumentException - if input is less than 0
      Since:
      100.0.0

    • getMaxFeatures

      public int getMaxFeatures()
      Gets the maximum number of features the query should return.

      For consistent ordering of results when using pagination, provide a value for getOrderByFields(). Note that if you provide a maximum features value to support paging of results, you must also set a getResultOffset() value. Otherwise, the result may contain local features in place of server features if they satisfy the query. To ensure strict paging of server features, specify both maximum features and QueryParameters.getResultOffset().

      Returns:
      the maximum number of features the query should return
      Since:
      100.0.0

    • setResultOffset

      public void setResultOffset(int resultOffset)
      Sets the starting offset of results to fetch. This is useful for paging through results.

      For consistent ordering of results when using pagination, you should also provide a value for the getOrderByFields(). Note that if you provide a result offset to support paging of results, you must also set a getMaxFeatures() value. Otherwise, the result offset is ignored.

      Parameters:
      resultOffset - the starting offset of results to fetch. This is useful for paging through results.
      Since:
      100.2.1

    • getResultOffset

      public int getResultOffset()
      Gets the offset of results to fetch. This is useful for paging through results.

      For consistent ordering of results when using pagination, you should also provide a value for the getOrderByFields(). Note that if you provide a result offset to support paging of results, you must also set a getMaxFeatures() value. Otherwise, the result offset is ignored.

      Returns:
      the offset of results to fetch. This is useful for paging through results.
      Since:
      100.2.1

    • setTimeExtent

      public void setTimeExtent(TimeExtent timeExtent)
      Sets a span of time used to query features in a time-aware feature layer.

      You can apply a temporal filter on any FeatureLayer that supports time filtering (FeatureLayer.isTimeFilteringSupported()). Set the TimeExtent.getStartTime() and TimeExtent.getEndTime() to query features across a span of time. A single point in time can be queried by setting them to the same time value. By default, this value is null and no time criteria is applied by the query.

      Parameters:
      timeExtent - a span of time used to query features in a time-aware feature layer
      Since:
      100.3.0

    • getTimeExtent

      public TimeExtent getTimeExtent()
      Gets a span of time used to query features in a time-aware feature layer.

      You can apply a temporal filter on any FeatureLayer that supports time filtering (FeatureLayer.isTimeFilteringSupported()). Set the TimeExtent.getStartTime() and TimeExtent.getEndTime() to query features across a span of time. A single point in time can be queried by setting them to the same time value.

      By default, this value is null and no time criteria is applied by the query.

      Returns:
      a span of time used to query features in a time-aware feature layer, or null if none
      Since:
      100.3.0

    • getMaxAllowableOffset

      public double getMaxAllowableOffset()
      Gets the maximum allowable offset used for generalizing geometries returned by the query operation. The default is 0. If 0 is specified the value is not passed to the server in the query operation. The offset is in the units of the outSpatialReference. If an outSpatialReference is not defined, the spatial reference of the service is used.
      Returns:
      the maximum allowable offset
      Since:
      100.4.0

    • setMaxAllowableOffset

      public void setMaxAllowableOffset(double maxAllowableOffset)
      Sets the maximum allowable offset used for generalizing geometries returned by the query operation. The default is 0. If 0 is specified the value is not passed to the server in the query operation. The offset is in the units of the outSpatialReference. If an outSpatialReference is not defined, the spatial reference of the service is used.
      Parameters:
      maxAllowableOffset - the maximum allowable offset
      Since:
      100.4.0