Query and filter

Introduction

This topic provides an overview of the many workflows you can use for querying and filtering data. Query and filter operations can be done against all features available in the service on the server-side or against all features available in the browser (or view) on the client-side.

First, we will review which layers allow you to query and filter subsets of features. In doing so, we must understand the concept of server-side vs client-side layers, and Layer vs LayerView.

Server-side and client-side layers

The ArcGIS API for JavaScript makes it possible for you to add data from many sources. Layers that allow you to query and filter subsets of their features can be grouped into server-side layers and client-side layers.

Server-side layers fetch only required features when they load. Afterwards, layers fetch their features from the server as needed or requested. These layers include: FeatureLayer, SceneLayer and StreamLayer. The server-side layer is created by setting the layer's url property to point to a service.

Client-side layers fetch all of their features at once and store them on the client-side when they load. Once these layers are loaded, there will be no more server-side requests. These layers include: CSVLayer and GeoJSONLayer. They are created by setting the layer's url property to a csv or geojson file. It also includes a FeatureLayer created from an array of client-side graphics by setting its source property.

Layer and LayerView

A LayerView is created when a layer is added to either a MapView or a SceneView. The LayerView is responsible for rendering features in the view. The layer view also provides methods and properties that give developers the ability to query, filter, and highlight graphics in the view on the client-side.

The following table shows a simplified steps that take place when the user adds a layer to a view.

  const layer = new FeatureLayer({
    url: “service url”
  });
  view.map.add(layer);
      

  const layer = new CSVLayer({
    url: "csv file url"
  });
  view.map.add(layer);
    

view.whenLayerView(layer).then(function(layerView){
  // now we have access to the layerView, an
  // object representing the layer in the view
});
      

view.whenLayerView(layer).then(function(layerView){
  // now we have access to the layerView, an
  // object representing the layer in the view
});
      

The following image illustrates the features available for querying from a layer and a layer view. As you can see the layer has features covering much more area than the initial extent of the application. The layer properties and methods provide access to all of these features. When the layer is loaded, the layer view has access to features that are visible within the app's initial extent. Any operation called on the layer view after the app loads provides access to features visible in the view. The image also shows the count of features available on the layer versus on the layer view. The layerView feature count is much less because it returns features within the initial extent of the view while layer count represents all features in the layer.

Querying

There are three types of queries: attribute, spatial, and statistic. This document provides detailed information on each type of query. Queries can be done on the layer or on its layer view.

Server-side and client-side queries

A server-side query is issued when a query... method is called on a server-side layer. The query is executed against all features available in the service.

(Feature|Scene)Layer // queries all features in the service
  .queryFeatures() // queries all features and returns a FeatureSet
  .queryExtent() // queries all features returns extent of features that satisfy query
  .queryFeatureCount() // queries all features and returns count of features
  .queryObjectIds() // queries all features and returns objectIds array of features

A client-side query is issued when a query... method is called on a client-side layer or any layer view. The query is executed against all features available in the layer or layer view.

(Feature|CSV|GeoJSON)Layer  // queries all features in the layer
(Feature|CSV|GeoJSON|Scene|Stream)LayerView // queries available features in view
  .queryFeatures() // queries features and returns a FeatureSet
  .queryExtent() // queries features returns extent of features that satisfy query
  .queryFeatureCount() // queries features and returns count of features
  .queryObjectIds() // queries features and returns objectIds array of features

Should I use client-side query or server-side query?

Tips when using query methods on LayerViews

• Add fields to a layer's outFields at the time of the layer initialization to ensure that you have access to these fields on the client-side. By default the layer view only fetches the fields that are required for layer rendering, labeling, elevation info.
• If you query a layerView when the app loads, then you must wait until layerView's updating property becomes false to make sure that the features are loaded with the layerView. You can use watchUtils.whenFalseOnce if the query needs to run only once at the time of initialization.
• If you query a layerView each time the view extent changes, then you must wait until the layerView's updating property becomes false to make sure the layerView finished fetching the features for that extent.
• The client-side attribute values are case sensitive.

Use the query tag to explore all samples that demonstrate these concepts. This tutorial walks through querying FeatureLayer and FeatureLayerView.

Filtering

Filters affect the availability of features in a layer or the visibility of features in a layer view. Features that satisfy the filter requirements will be displayed in the view. Filtering can take place on the server-side or on the client-side.

Server-side and client-side filtering

All layers covered in this guide have a definitionExpression property. Setting a definitionExpression on a server-side layer triggers a network request to fetch features that satisfy the definition expression. Setting a definition expression is useful when the dataset is large and you don't want to bring all features to the client for analysis. If the definition expression is set after the layer has been added to the map, the view will automatically refresh itself to display the features that satisfy the new definition expression.

// fetch all features that satisfy requirements from the service
(Feature|Scene|Stream)Layer
  .definitionExpression = "type = 'metal'";

A definitionExpression on a client-side layer will only display features that satisfy the definitionExpression. Setting a definitionExpression happens on the client-side against all features available in the layer.

// only display features that satisfy the requirements in the layer
(Feature|CSV|GeoJSON)Layer
  .definitionExpression = "mag > 5";

If a layer has a definitionExpression, all layerView queries and filters will honor the definitionExpression. This means only features that meet the layer's definitionExpression will be evaluated by the layer view's query and filter operations.

You can apply filters on features available for drawing by setting a filter on a LayerView. The FeatureFilter allows you to display the features that satisfy the filter requirements in the layer view. Since the filter is applied to a layer view, this happens on the client-side against features that are available for drawing.

(Feature|CSV|GeoJSON|Scene|Stream)LayerView
   // only display features that satisfy the requirements in the layer
  .filter = {
    where: "age > 25";
  }

Filters can be applied based on attributes, time, and/or geometry. Search the sample code using the FeatureFilter tag to explore all current samples that demonstrate how you can use the featureFilter to display subset of features that meet requirements. This tutorial walks through querying FeatureLayer and FeatureLayerView.