Query a feature layer (SQL)

Learn how to execute a SQL query to return features from a feature layer based on spatial and attribute criteria.

A feature layer can contain a large number of features stored in ArcGIS. You can query a layer to access a subset of its features using any combination of spatial and attribute criteria. You can control whether or not each feature's geometry is returned, as well as which attributes are included in the results. Queries allow you to return a well-defined subset of your hosted data for analysis or display in your app.

In this tutorial, you'll write code to perform SQL queries that return a subset of features in the LA County Parcel feature layer (containing over 2.4 million features). Features that meet the query criteria are selected in the map.

Prerequisites

Before starting this tutorial:

You need an ArcGIS Location Platform or ArcGIS Online account.
Your system meets the system requirements.

Develop or Download

To complete this tutorial you have 2 options:

Option 1: Develop the code or
Option 2: Download the completed solution

Option 1: Develop the code

To start the tutorial, complete the Display a map tutorial. This creates a map to display the Santa Monica Mountains in California using the topographic basemap from the ArcGIS basemap styles service. You can choose to implement either API key authentication or user authentication.

Continue with the following instructions to execute a SQL query to return features from a feature layer based on spatial and attribute criteria.

Update the map

In Xcode, in the Project Navigator, click ContentView.swift.

In the editor, modify the map variable's initial viewpoint.

ContentView.swift
Use dark colors for code blocks
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
78
79
80
81
82
83
83
83
83
83
83
84
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
85
Change line        let map: Map = {
            let map = Map(basemapStyle: .arcGISTopographic)

            map.initialViewpoint = Viewpoint(latitude: 34.03000, longitude: -118.80500, scale: 6e4)

            return map
        }()

Create a private extension named Model with a class of type ObservableObject. Move the map variable there.

ContentView.swift
Use dark colors for code blocks
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
59
60
60
60
60
60
60
60
60
60
60
60
60
60
60
60
60
60
61
62
63
64
65
66
67
67
67
67
67
67
68
69
70
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
71
72
73
74
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.private extension ContentView {

    class Model: ObservableObject {

        let map: Map = {
            let map = Map(basemapStyle: .arcGISTopographic)

            map.initialViewpoint = Viewpoint(latitude: 34.03000, longitude: -118.80500, scale: 6e4)

            return map
        }()


    }

}

Create a ServiceFeatureTable from the parcels service URL, then use it to make a FeatureLayer. Then, add the parcels feature layer to the map as an operational layer.

ContentView.swift
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
77
77
77
Add line.Add line.Add line.Add line.    class Model: ObservableObject {

        let map: Map = {
            let map = Map(basemapStyle: .arcGISTopographic)

            map.initialViewpoint = Viewpoint(latitude: 34.03000, longitude: -118.80500, scale: 6e4)

            let parcelsURL = URL(string: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0")!
            let featureTable = ServiceFeatureTable(url: parcelsURL)
            let featureLayer = FeatureLayer(featureTable: featureTable)
            map.addOperationalLayer(featureLayer)

            return map
        }()


    }

To access the model's map in the ContentView struct, create a private variable of type Model with a @StateObject property wrapper and modify the MapView to display the model's map.

ContentView.swift
Use dark colors for code blocks
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
19
20
21
22
23
24
24
24
25
26
27
28
29
30
31
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
33
34
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
Add line.Change linestruct ContentView: View {

    @StateObject private var model = Model()

    @State private var geoViewExtent: Envelope?

    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

    }

}

Make an enumeration for predefined where clauses

To allow the user to query the parcels feature layer, create an enum that contains a set of predefined where clauses.

In the ContentView extension, make an enum type called WhereClause that is CaseIterable and Equatable. Add a switch statement and a case option for each where clause.

ContentView.swift
Use dark colors for code blocks
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
58
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
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
93
94
95
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.private extension ContentView {

    enum WhereClause: CaseIterable, Equatable {
        case government, residential, farm, taxRate10853, taxRate10860, landValueGreaterThan, landValueLessThan

        var expression: String {
            switch self {
            case .government: return "UseType = 'Government'"
            case .residential: return "UseType = 'Residential'"
            case .farm: return "UseType = 'Irrigated Farm'"
            case .taxRate10853: return "TaxRateArea = 10853"
            case .taxRate10860: return "TaxRateArea = 10860"
            case .landValueGreaterThan: return "Roll_LandValue > 1000000"
            case .landValueLessThan: return "Roll_LandValue < 1000000"
            }
        }
    }

    class Model: ObservableObject {

        let map: Map = {
            let map = Map(basemapStyle: .arcGISTopographic)

            map.initialViewpoint = Viewpoint(latitude: 34.03000, longitude: -118.80500, scale: 6e4)

            let parcelsURL = URL(string: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0")!
            let featureTable = ServiceFeatureTable(url: parcelsURL)
            let featureLayer = FeatureLayer(featureTable: featureTable)
            map.addOperationalLayer(featureLayer)

            return map
        }()


    }

}

Create a function to query the parcels layer and select the result

Create a new function that queries the parcels FeatureTable with the chosen where clause and current extent. Clear any currently selected features and create a new QueryParameters object. Set the selectedWhereClause property to the option selected by the user and geoViewExtent to the current visible area. Asynchronously, query the feature table using the QueryParameters and select the features returned in the FeatureQueryResult.

Create a private variable of type Envelope with the @State property wrapper named geoViewExtent. This variable keeps track of the current, visible extent.

ContentView.swift
Expand
Use dark colors for code blocks
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
19
20
21
22
23
24
24
24
25
26
27
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
28
29
30
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
31
Add line.struct ContentView: View {

    @StateObject private var model = Model()

    @State private var geoViewExtent: Envelope?

    var body: some View {

        MapView(map: model.map)

    }

}
Expand

To update the geoViewExtent variable when the visible area is changed, add the onVisibleAreaChanged(perform:) task modifer to the map view. When the visible area has changed, update geoViewExtent to the new area's extent.

ContentView.swift
Expand
Use dark colors for code blocks
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
19
20
21
22
23
24
24
24
25
26
27
28
29
30
31
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
32
33
34
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
35
Add line.Add line.Add line.struct ContentView: View {

    @StateObject private var model = Model()

    @State private var geoViewExtent: Envelope?

    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

    }

}
Expand

Create a new method called queryFeatureLayer(selectedWhereClause:extent:) in the Model. Specify that it accepts parameters of type WhereClause and Envelope.

ContentView.swift
Expand
Use dark colors for code blocks
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
76
75
74
74
74
74
74
74
74
74
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
54
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
91
91
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.    class Model: ObservableObject {

        let map: Map = {
            let map = Map(basemapStyle: .arcGISTopographic)

            map.initialViewpoint = Viewpoint(latitude: 34.03000, longitude: -118.80500, scale: 6e4)

            let parcelsURL = URL(string: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0")!
            let featureTable = ServiceFeatureTable(url: parcelsURL)
            let featureLayer = FeatureLayer(featureTable: featureTable)
            map.addOperationalLayer(featureLayer)

            return map
        }()


        func queryFeatureLayer(with selectedWhereClause: WhereClause, in extent: Envelope) async {
            guard
                let parcelsFeatureLayer = map.operationalLayers.first as? FeatureLayer,
                let featureTable = parcelsFeatureLayer.featureTable
            else { return }
            parcelsFeatureLayer.clearSelection()

            let parameters = QueryParameters()
            parameters.whereClause = selectedWhereClause.expression
            parameters.geometry = extent

            do {
                let result = try await featureTable.queryFeatures(using: parameters)
                let features = result.features()
                parcelsFeatureLayer.selectFeatures(features)
            } catch {
                print(error)
            }
        }

    }
Expand

Add UI for selecting a predefined where clause

To allow the user to choose a where clause that queries the parcels dataset, add a Picker that presents the list of predefined where clauses.

In the ContentView, create a @State variable named selectedWhereClause of type WhereClause. Assign .government as the default enum. The @State variable selectedWhereClause allows the model's queryFeatureLayer(selectedWhereClause:extent:) method to track which where clause the user has selected.

ContentView.swift
Expand
Use dark colors for code blocks
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
34
34
34
33
32
31
30
29
28
27
26
25
24
23
22
21
20
20
20
20
21
22
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
23
Add line.struct ContentView: View {

    @StateObject private var model = Model()

    @State private var geoViewExtent: Envelope?

    @State private var selectedWhereClause: WhereClause = .government

    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

    }

}
Expand

In the body, add a Toolbar and a ToolbarItemGroup with .bottomBar placement to the MapView.

ContentView.swift
Expand
Use dark colors for code blocks
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
27
28
29
30
31
32
33
34
35
36
37
37
37
37
37
37
37
37
37
37
37
37
37
37
37
38
39
40
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
41
Add line.Add line.Add line.Add line.Add line.    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

            .toolbar {
                ToolbarItemGroup(placement: .bottomBar) {

                }
            }

    }
Expand

Add a Picker to the toolbar item group and label it, "Choose an SQL where clause". Set the selection to $selectedWhereClause. Iterating through .allCases of the WhereClause to populate the Picker with all the WhereClause enums.

ContentView.swift
Expand
Use dark colors for code blocks
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
43
43
43
43
43
44
45
46
47
48
49
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

            .toolbar {
                ToolbarItemGroup(placement: .bottomBar) {

                    Spacer()
                    Picker("Choose an SQL `where` clause", selection: $selectedWhereClause) {
                        ForEach(WhereClause.allCases, id: \.self) { clause in
                            Text(clause.expression)
                        }

                    }
                    Spacer()

                }
            }

    }
Expand

Lastly, add a .task modifier that calls the model's queryFeatureLayer(selectedWhereClause:extent:) function using the selectedWhereClause property.

ContentView.swift
Expand
Use dark colors for code blocks
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
26
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
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
55
Add line.Add line.Add line.Add line.    var body: some View {

        MapView(map: model.map)

            .onVisibleAreaChanged { newVisibleArea in
                geoViewExtent = newVisibleArea.extent
            }

            .toolbar {
                ToolbarItemGroup(placement: .bottomBar) {

                    Spacer()
                    Picker("Choose an SQL `where` clause", selection: $selectedWhereClause) {
                        ForEach(WhereClause.allCases, id: \.self) { clause in
                            Text(clause.expression)
                        }

                        .task(id: selectedWhereClause) {
                            guard let geoViewExtent = geoViewExtent else { return }
                            await model.queryFeatureLayer(with: selectedWhereClause, in: geoViewExtent)
                        }

                    }
                    Spacer()

                }
            }

    }
Expand

Run the solution

Press Command + R to run the app.

If you are using the Xcode simulator your system must meet these minimum requirements: macOS 14 (Sonoma), Xcode 16, iOS 18. If you are using a physical device, then refer to the system requirements.

The app loads with the map centered on the Santa Monica Mountains in California with the parcels feature layer displayed. Choose an attribute expression and to display parcels that meet the selected criteria.

Alternatively, you can download the tutorial solution, as follows.

Option 2: Download the solution

Click the Download solution link under Solution and unzip the file to a location on your machine.
Open the .xcodeproj file in Xcode.

Since the downloaded solution does not contain authentication credentials, you must first set up authentication to create credentials, and then add the developer credentials to the solution.

Set up authentication

To access the secure ArcGIS location services used in this tutorial, you must implement API key authentication or user authentication using an ArcGIS Location Platform or an ArcGIS Online account.

You can implement API key authentication or user authentication in this tutorial. Compare the differences below:

API key authentication

Users are not required to sign in.
Requires creating an API key credential with the correct privileges.
API keys are long-lived access tokens.
Service usage is billed to the API key owner/developer.
Simplest authentication method to implement.
Recommended approach for new ArcGIS developers.

Learn more in API key authentication.

User authentication

Users are required to sign in with an ArcGIS account.
User accounts must have privilege to access the ArcGIS services used in application.
Requires creating OAuth credentials.
Application uses a redirect URL and client ID.
Service usage is billed to the organization of the user signed into the application.

Learn more in User authentication.

Create a new API key access token with privileges to access the secure resources used in this tutorial.

Complete the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps
Copy and paste the API Key access token into a safe location. It will be used in a later step.

Set developer credentials in the solution

To allow your app users to access ArcGIS location services, pass the developer credentials that you created in the Set up authentication step to the application's ArcGISEnvironment.

Pass your API Key access token to the ArcGISEnvironment.

In the Project Navigator, click MainApp.swift.

Set the AuthenticationMode to .apiKey.

MainApp.swift
Use dark colors for code blocks
    // Change the `AuthenticationMode` to `.apiKey` if your application uses API key authentication.

    private var authenticationMode: AuthenticationMode { .apiKey }

Set the apiKey property with your API key access token.

MainApp.swift
Expand
Use dark colors for code blocks
    // Please enter an API key access token if your application uses API key authentication.

    private let apiKey = APIKey("YOUR-ACCESS-TOKEN")

Expand

Best Practice: The access token is stored directly in the code as a convenience for this tutorial. In a production environment we do not recommend that you store it directly in source code.

Use the Authenticator toolkit component to manage your OAuth credentials and pass it to the ArcGISEnvironment.

In the Project Navigator, click MainApp.swift.

Set the AuthenticationMode to .user.

MainApp.swift
Use dark colors for code blocks
// Change the `AuthenticationMode` to `.user` if your application uses OAuth credentials.

    private var authenticationMode: AuthenticationMode { .user }

Set your portalURL, clientID and redirectURL values.

MainApp.swift
Expand
Use dark colors for code blocks
    // Setup an `Authenticator` with OAuth configuration if your application uses OAuth credentials.
    @ObservedObject var authenticator = Authenticator(
        oAuthUserConfigurations: [
            OAuthUserConfiguration(

                // Please enter OAuth credentials for user authentication.

                portalURL: URL(string: "YOUR-PORTAL-URL")!,
                clientID: "YOUR-CLIENT-ID",
                redirectURL: URL(string: "YOUR-REDIRECT-URL")!

            )
        ]
    )
Expand

Best Practice: The OAuth credentials are stored directly in the code as a convenience for this tutorial. In a production environment we do not recommend that you store it directly in source code.

Run the solution

Press Command + R to run the app.

What's next?

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