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

You need an ArcGIS Location Platform or ArcGIS Online account.

Steps

Create a new pen

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

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an API key with the following privilege(s):

    • Privileges
      • Location services > Basemaps
    • Item access
      • Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.
  2. Copy the API key access token to your clipboard when prompted.

  3. In CodePen, update the accessToken variable to use your access token.

    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    const accessToken = "YOUR_ACCESS_TOKEN";
    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=${accessToken}`,
      zoom: 12, // starting zoom
      center: [-118.805, 34.027] // starting location [longitude, latitude]
    });
    

To learn about the other types of authentication available, go to Types of authentication.

Add API references

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

  1. In the <head> element, add references to the ArcGIS REST JS library.
Expand
Use dark colors for code blocks
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@4/dist/maplibre-gl.js></script>
    <link href=https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css rel="stylesheet" />

    <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-feature-service@4/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>
Expand

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
    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=${accessToken}`,
            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
    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.

    Expand
    Use dark colors for code blocks
    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
    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.

    Expand
    Use dark colors for code blocks
    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
    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
    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
    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:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.