Query a feature layer (SQL)

Learn how to execute a SQL query to access polygon features from a feature layer.

A feature layer can contain a large number of features stored in ArcGIS. To access a subset of the features, you can execute either a SQL or spatial query, or both at the same time. You can return feature attributes, geometry, or both attributes and geometry for each record. SQL and spatial queries are useful when you want to access only a subset of your hosted data.

In this tutorial, you will perform server-side SQL queries to return a subset of features in the LA County Parcel feature layer. The feature layer contains over 2.4 million features. The resulting features are displayed as graphics on the map.

Prerequisites

You need an ArcGIS Developer or ArcGIS Online account to access the dashboard and create an API key.

Steps

Create a new pen

To get started, either complete the Display a map tutorial or .

Set the API key

To access ArcGIS services, you need an API key.

Go to your dashboard to get an API key.
In CodePen, set the apiKey to your key, so it can be used to access basemap layer and location services.

Use dark colors for code blocks
esriConfig.apiKey = "YOUR_API_KEY";
const map = new Map({
  basemap: "arcgis/topographic" // basemap styles service
});

Add modules

In the require statement, add the FeatureLayer module.

The ArcGIS Maps SDK for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. For more information on the different types of modules, visit the Introduction to Tooling guide topic.

Expand
Use dark colors for code blocks
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",
      "esri/layers/FeatureLayer",
    ], function(esriConfig, Map, MapView, FeatureLayer) {
Expand

Create a SQL selector

ArcGIS feature layers support a standard SQL query where clause. Use an HTML select element to provide a list of SQL queries for the LA County Parcel feature layer.

Create a parcelType array of SQL queries. Assign the whereClause element to a SQL query from the array.

Expand
Use dark colors for code blocks
      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-118.80543,34.03000], //Longitude, latitude
        zoom: 13
      });

      // SQL query array
      const parcelLayerSQL = ["Choose a SQL where clause...", "UseType = 'Residential'",  "UseType = 'Government'", "UseType = 'Irrigated Farm'", "TaxRateArea = 10853", "TaxRateArea = 10860", "TaxRateArea = 08637", "Roll_LandValue > 1000000", "Roll_LandValue < 1000000"];
      let whereClause = parcelLayerSQL[0];
Expand

Create a parent select element and add option elements for each SQL query. Add some some basic styles to the elements.

Expand
Use dark colors for code blocks
      // SQL query array
      const parcelLayerSQL = ["Choose a SQL where clause...", "UseType = 'Residential'",  "UseType = 'Government'", "UseType = 'Irrigated Farm'", "TaxRateArea = 10853", "TaxRateArea = 10860", "TaxRateArea = 08637", "Roll_LandValue > 1000000", "Roll_LandValue < 1000000"];
      let whereClause = parcelLayerSQL[0];

      // Add SQL UI
      const select = document.createElement("select");
      select.setAttribute("class", "esri-widget esri-select");
      select.setAttribute("style", "width: 200px; font-family: 'Avenir Next'; font-size: 1em");
      parcelLayerSQL.forEach(function(query){
        let option = document.createElement("option");
        option.innerHTML = query;
        option.value = query;
        select.appendChild(option);
      });

Expand

Add the select element to the top-right corner of the view.

Expand
Use dark colors for code blocks
      // Add SQL UI
      const select = document.createElement("select");
      select.setAttribute("class", "esri-widget esri-select");
      select.setAttribute("style", "width: 200px; font-family: 'Avenir Next'; font-size: 1em");
      parcelLayerSQL.forEach(function(query){
        let option = document.createElement("option");
        option.innerHTML = query;
        option.value = query;
        select.appendChild(option);
      });

      view.ui.add(select, "top-right");
Expand

Add an event listener to listen for select element changes.

Expand
Use dark colors for code blocks
      view.ui.add(select, "top-right");

       // Listen for changes
      select.addEventListener('change', (event) => {
        whereClause = event.target.value;

      });
Expand

Verify that the select element is created.

Create a feature layer to query

Use the FeatureLayer class to access the LA County Parcel feature layer. Since you are performing a server-side query, the feature layer does not need to be added to the map.

Create a parcelLayer and set the url property to access the feature layer in the feature service.

Expand
Use dark colors for code blocks
       // Listen for changes
      select.addEventListener('change', (event) => {
        whereClause = event.target.value;

      });

      // Get query layer and set up query
 const parcelLayer = new FeatureLayer({
        url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
      });
Expand

Execute a query

Use the queryFeatures method to perform a SQL query against the feature layer. The Query will be autocast when the method is called.

Create a queryFeatureLayer function with extent parameter. Define a parcelQuery element and set the where property to the whereClause. Set the spatialProperty to only return features that intersect the geometry, which is restricted to the visible extent of the map. The outFields property will return only a subset of the attributes. Lastly, set returnGeometry to true so that the features can be displayed.

Expand
Use dark colors for code blocks
      // Get query layer and set up query
 const parcelLayer = new FeatureLayer({
        url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
      });

      function queryFeatureLayer(extent) {

        const parcelQuery = {
         where: whereClause,  // Set by select element
         spatialRelationship: "intersects", // Relationship operation to apply
         geometry: extent, // Restricted to visible extent of the map
         outFields: ["APN","UseType","TaxRateCity","Roll_LandValue"], // Attributes to return
         returnGeometry: true
        };

      }
Expand

Call the queryFeatures method on the parcelLayer using parcelQuery. To view the number of features returned, write the result length to the console. This will be updated in the next step.

Expand
Use dark colors for code blocks
      function queryFeatureLayer(extent) {

        const parcelQuery = {
         where: whereClause,  // Set by select element
         spatialRelationship: "intersects", // Relationship operation to apply
         geometry: extent, // Restricted to visible extent of the map
         outFields: ["APN","UseType","TaxRateCity","Roll_LandValue"], // Attributes to return
         returnGeometry: true
        };

        parcelLayer.queryFeatures(parcelQuery)

        .then((results) => {

          console.log("Feature count: " + results.features.length)

        }).catch((error) => {
          console.log(error.error);
        });

      }
Expand

Update the event handler to call the queryFeatureLayer function when the selector changes.

Expand
Use dark colors for code blocks
       // Listen for changes
      select.addEventListener('change', (event) => {
        whereClause = event.target.value;

        queryFeatureLayer(view.extent);

      });
Expand

At the top-right, click Run. Choose a SQL query from the selector. At the bottom left, click Console to view the number of features returned from each query.

Display features

To display the features returned from the SQL query, add them to the view as polygon graphics. Define a pop-up also so the attributes can be displayed when features are clicked.

Create a displayResults function with results as a parameter. Define a symbol and popupTemplate variable to style and display a pop-up for polygon graphics. The attributes referenced match the outFields specified in the query earlier.

Expand
Use dark colors for code blocks
        }).catch((error) => {
          console.log(error.error);
        });

      }

      function displayResults(results) {
        // Create a blue polygon
        const symbol = {
          type: "simple-fill",
          color: [ 20, 130, 200, 0.5 ],
          outline: {
            color: "white",
            width: .5
          },
        };

        const popupTemplate = {
          title: "Parcel {APN}",
          content: "Type: {UseType} <br> Land value: {Roll_LandValue} <br> Tax Rate City: {TaxRateCity}"
        };

      }
Expand

Assign the symbol and popupTemplate elements to each feature returned from the query.

Expand
Use dark colors for code blocks
        const popupTemplate = {
          title: "Parcel {APN}",
          content: "Type: {UseType} <br> Land value: {Roll_LandValue} <br> Tax Rate City: {TaxRateCity}"
        };

        // Assign styles and popup to features
        results.features.map((feature) => {
          feature.symbol = symbol;
          feature.popupTemplate = popupTemplate;
          return feature;
        });

Expand

Clear the existing graphics and pop-up, and then add the new features returned to the view.

Expand
Use dark colors for code blocks
        // Assign styles and popup to features
        results.features.map((feature) => {
          feature.symbol = symbol;
          feature.popupTemplate = popupTemplate;
          return feature;
        });

        // Clear display
        view.closePopup();
        view.graphics.removeAll();
        // Add features to graphics layer
        view.graphics.addMany(results.features);
Expand

Update the queryFeatureLayer function to call the displayResults function. Remove the console.log.

Expand
Use dark colors for code blocks
        parcelLayer.queryFeatures(parcelQuery)

        .then((results) => {

          console.log("Feature count: " + results.features.length)

          displayResults(results);

        }).catch((error) => {
          console.log(error.error);
        });
Expand

Run the app

In CodePen, run your code to display the map.

When the map displays, you should be able to choose a SQL query from the selector. The resulting features will be added to the map as polygon graphics. The SQL query is applied to the visible extent of the map.

What's next?

Learn how to use additional API features and ArcGIS services in these tutorials: