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 a SQL or spatial query, or both at the same time. You can also return the attributes, geometry, or both attributes and geometry for each record. SQL and spatial queries are useful when a feature layer is very large and you just want to access a subset of the data.

In this tutorial, you perform server-side SQL queries to return a subset of the features from the LA County Parcel hosted feature layer. The feature layer contains over 2.4 million features. The resulting features are displayed as graphics on the map. A pop-up is also used to display feature attributes.

Prerequisites

Steps

Create a new pen

1. To get started, either complete the Display a map tutorial or use this pen.

Set the API key

To access location services, you need an API key or OAuth 2.0 access token. To learn how to create and scope your key, visit the Create an API key tutorial.

1. Go to your dashboard to get an API key. The API key must be scoped to access the services used in this tutorial.

2. In CodePen, update apiKey to use your key.

   Use dark colors for code blocks

                      

   Change line

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   const apiKey = "YOUR_API_KEY";
   const basemapEnum = "arcgis/streets";
   const map = new maplibregl.Map({
     container: "map", // the id of the div element
     style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${apiKey}`,
     zoom: 12, // starting zoom
     center: [-118.805, 34.027] // starting location [longitude, latitude]
   });
   

Add API references

This tutorial uses ArcGIS REST JS to query the feature layer.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
    <script src=https://unpkg.com/maplibre-gl@3.2.1/dist/maplibre-gl.js></script>
    <link href=https://unpkg.com/maplibre-gl@3.2.1/dist/maplibre-gl.css rel="stylesheet" />

    <script src="https://unpkg.com/@esri/arcgis-rest-request@4.0.0/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-feature-service@4.0.0/dist/bundled/feature-service.umd.js"></script>

    <style>
      html,
      body,
      #map {
        padding: 0;
        margin: 0;
        height: 100%;
        width: 100%;
        font-family: Arial, Helvetica, sans-serif;
        font-size: 14px;
        color: #323232;
      }
    </style>
  </head>

Create a SQL selector

Hosted 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.

To add the <select> HTML element as a Map control, you create an object that implements the MapLibre GL JS IControl interface.

1. Create a QueryControl class with an onAdd function. Inside, create a <div> element with a <select> inside, with options for each of the SQL where clauses. Return this element.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
         const map = new maplibregl.Map({
           container: "map", // the id of the div element
           style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${apiKey}`,
           zoom: 12, // starting zoom
   
           center: [-118.80543, 34.03] // starting location [longitude, latitude]
   
         });
   
         class QueryControl {
           onAdd(map) {
             const template = document.createElement("template");
             template.innerHTML = `<div class="maplibregl-ctrl maplibregl-ctrl-group" style="margin:20px;">
               <select style="font-size:16px; padding:4px 8px;">
                 <option value="">Choose a WHERE clause...</option>
                 <option>UseType = 'Residential'</option>
                 <option>UseType = 'Government'</option>
                 <option>UseType = 'Irrigated Farm'</option>
                 <option>TaxRateArea = 10853</option>
                 <option>TaxRateArea = 10860</option>
                 <option>TaxRateArea = 08637</option>
                 <option>Roll_LandValue > 1000000</option>
                 <option>Roll_LandValue < 1000000</option>
               </select>
             </div>`;
   
             return template.content;
           }
         }
   

   Expand

2. Create a QueryControl and add it to the Map with map.addControl.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
             return template.content;
           }
         }
   
         const queryControl = new QueryControl();
         map.addControl(queryControl);
   

   Expand

Add parcel layer

Parcels returned by the query are simple GeoJSON polygons. You can display them with a GeoJSON source and a fill layer.

1. Create an addParcelLayer function. Inside, add a GeoJSON source and a fill layer. Add the layer before the first symbol layer.

   More info

   By inserting the polygon layer beneath the icon and text layers, it keeps the labels readable. In MapLibre GL JS, there is no distinction between "basemap" layers and "overlay layers", so you can insert the layer anywhere.

   To determine the first symbol layer, you can use map.getStyle to get the style, then iterate to find the first layer whose type is symbol.

   See the MapLibre GL JS documentation for details.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
         const queryControl = new QueryControl();
         map.addControl(queryControl);
   
         function addParcelLayer() {
           map.addSource("parcels", {
             type: "geojson",
             data: {
               type: "FeatureCollection",
               features: []
             }
           });
   
           const firstSymbolLayer = map.getStyle().layers.find((l) => l.type === "symbol");
           map.addLayer(
             {
               id: "parcels-fill",
               source: "parcels",
               type: "fill",
               paint: {
                 "fill-color": "hsla(200, 80%,50%, 0.5)",
   
                 "fill-outline-color": "hsl(360, 100%, 100%)"
               }
             },
             firstSymbolLayer.id
           ); // insert new layer before this one
           map.addLayer({
             id: "parcels-line",
             source: "parcels",
             type: "line",
             paint: {
               "line-width": 0.5,
               "line-color": "hsl(360, 100%,100%)"
             }
           }); // set outline style for parcels
         }
   

   Expand

Add load handler

To add layers to the map, you need to use the load event to ensure the map is fully loaded.

1. Add an event handler for the load event. Inside, call addParcelLayer.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
           const firstSymbolLayer = map.getStyle().layers.find((l) => l.type === "symbol");
           map.addLayer(
             {
               id: "parcels-fill",
               source: "parcels",
               type: "fill",
               paint: {
                 "fill-color": "hsla(200, 80%,50%, 0.5)",
   
                 "fill-outline-color": "hsl(360, 100%, 100%)"
               }
             },
             firstSymbolLayer.id
           ); // insert new layer before this one
           map.addLayer({
             id: "parcels-line",
             source: "parcels",
             type: "line",
             paint: {
               "line-width": 0.5,
               "line-color": "hsl(360, 100%,100%)"
             }
           }); // set outline style for parcels
         }
   
         map.on("load", () => {
   
           addParcelLayer();
   
         });
   

   Expand

Execute the query

Use the ArcGIS REST JS queryFeatures method to find features in the LA County Parcels feature layer that match the selected where clause.

To limit the query results to the visible extent of the Map, you can set the queryFeatures geometry property. To do so, use map.getBounds to get the extent of the Map viewport, and then convert it to the required esriGeometryEnvelope format of [minx, miny, maxx, maxy]. This confines the SQL query to the geographic bounds (extent) of the map.

When the matching parcels are returned, call setData on the parcels source to display them.

1. Create a function called executeQuery with whereClause and geometry parameters. Inside, create a new arcgisRest.ApiKeyManager to access the feature service. Call arcgisRest.queryFeatures. Pass the geometry and geometryType. Specify GeoJSON as the return type, requesting returnGeometry and specific outFields. All of the features within the geometry will be returned with attribute information set by the outFields property.

   More info

   There are many other spatial relationships that you can specify with spatialRel. For example, you can use esriSpatialRelContains to only return parcels completely within the viewport. See the ArcGIS services reference for details.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
         function executeQuery(whereClause, geometry) {
   
           arcgisRest
             .queryFeatures({
               url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
               geometry: geometry,
               geometryType: "esriGeometryEnvelope",
               inSR: 4326, // EPSG:4326 uses latitudes and longitudes
               spatialRel: "esriSpatialRelIntersects",
               where: whereClause,
               f: "geojson",
               returnGeometry: true,
               outFields: ["APN", "UseType", "TaxRateCity", " Roll_LandValue"]
             })
   
         }
   

   Expand

2. Add a response handler. Inside, set the returned parcels as the data for the parcels source.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
           arcgisRest
             .queryFeatures({
               url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
               geometry: geometry,
               geometryType: "esriGeometryEnvelope",
               inSR: 4326, // EPSG:4326 uses latitudes and longitudes
               spatialRel: "esriSpatialRelIntersects",
               where: whereClause,
               f: "geojson",
               returnGeometry: true,
               outFields: ["APN", "UseType", "TaxRateCity", " Roll_LandValue"]
             })
   
             .then((response) => {
               map.getSource("parcels").setData(response);
             });
   

   Expand

3. Update your QueryControl to add a change event handler to the select element. Inside, calculate the viewport extent and call executeQuery with the extent and where clause.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
         class QueryControl {
           onAdd(map) {
             const template = document.createElement("template");
             template.innerHTML = `<div class="maplibregl-ctrl maplibregl-ctrl-group" style="margin:20px;">
               <select style="font-size:16px; padding:4px 8px;">
                 <option value="">Choose a WHERE clause...</option>
                 <option>UseType = 'Residential'</option>
                 <option>UseType = 'Government'</option>
                 <option>UseType = 'Irrigated Farm'</option>
                 <option>TaxRateArea = 10853</option>
                 <option>TaxRateArea = 10860</option>
                 <option>TaxRateArea = 08637</option>
                 <option>Roll_LandValue > 1000000</option>
                 <option>Roll_LandValue < 1000000</option>
               </select>
             </div>`;
   
             const select = template.content.querySelector("select");
             select.addEventListener("change", () => {
               // Do nothing for the "Choose a WHERE clause..." option
               if (select.value !== "") {
                 // Get bounds in [minx, miny, maxx, maxy] format
                 const bounds = map.getBounds().toArray().flat();
                 executeQuery(select.value, bounds);
               }
             });
   
             return template.content;
           }
         }
   

   Expand

4. At the top right, click Run. When you select a where clause using the toolbox, a query will run against the feature layer and display all land parcels within the current viewport matching the where clause.

Add a pop-up

You can add a Popup to view attributes of a parcel when the user clicks on it.

1. Add a click event handler to the parcels-fill layer. Inside, construct the pop-up content from the attributes of the clicked parcel. Create a new Popup, then use popup.setHTML to set the content. Set the position of the pop-up and add it to the map.

   Expand

   Use dark colors for code blocks

                                                                                                                                                              

   Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
   147
   148
   149
   150
   151
   152
   153
   154
   155
             .then((response) => {
               map.getSource("parcels").setData(response);
             });
   
         }
   
         map.on("click", "parcels-fill", (e) => {
           const parcel = e.features[0].properties;
           const landValue = parcel.Roll_LandValue != "null" ? `$${parcel.Roll_LandValue.toLocaleString()}` : `N/A`;
           const message =
             `<b>Parcel ${parcel.APN}</b></br>` +
             `Type: ${parcel.UseType} <br>` +
             `Land value: ${landValue} <br>` +
             `Tax Rate City: ${parcel.TaxRateCity}`;
   
           new maplibregl.Popup().setHTML(message).setLngLat(e.lngLat).addTo(map);
         });
   

   Expand

Run the app

In CodePen, run your code to display the map.

When the map displays, you should be able to use the query selector to display parcels. Click on a parcel to show a pop-up with the feature's attributes.

What's next?

Learn how to use additional ArcGIS location services in these tutorials:

Query a feature layer (spatial)

Execute a spatial query to access polygon features from a feature service.

Get global data

Query demographic information for locations around the world with the GeoEnrichment service.

Get local data

Query regional facts, spending trends, and psychographics with the GeoEnrichment service.

Add a feature layer

Add features from feature layers to a map.

Style a feature layer

Use data-driven styling to apply symbol colors and styles to feature layers.