Query widget

The Query widget allows you to retrieve information from source data by executing a predefined query. Data sources can be one of the following:

• Feature layer in the current map
• Feature layer as an item in the portal
• Feature layer from an ArcGIS Server REST service

  Tip:

  A feature layer can be from a map service or a feature service.

• Imagery layer from an image service
• Table

  Tip:

  When running a query against a table with related records, all the related features are highlighted on the map and listed in the Query panel.

The Query widget serves as a query builder during configuration, allowing you to define the query by specifying source data, filters, and displaying fields in query results. Each query works with a single layer. However, you can define multiple queries for a single app, and data layers can be from multiple sources.

Configure the Query widget

The Query widget can be set to open automatically when an app starts. To do so, click the dot on the widget to turn it dark green.

The following steps describe how to configure a query. Repeat these steps if you need to define multiple queries.

1. Hover over the Query widget and click the small edit icon .

   The configuration window for this widget appears.

2. Optionally click change widget icon if you want to replace the default icon for this widget.

   A file explorer window appears, allowing you to browse to a local image file to use as the widget icon.

3. Click + New Query.

   The Set Data Source window appears. By default, Select from Map is chosen and all feature layers in the current map are listed below it.

   Alternatively, you can choose Select from Portal or Add Service URL. In addition to layers, you can query against related tables.

4. Click the radio button next to a data source.
5. Select a layer from the list.
6. Click OK to close the Set Data Source window and return to the query configuration window.

   By default, the Info tab is active.

7. Specify the title and icon for the query task.
8. Click the Filters tab.
9. Click Set under Attribute criteria to define a where clause for the query.
   1. Click Add a filter expression to display the expression builder.

      The filter expression can be a value-based operation or an operation between two fields.

   2. Select a query field—an expression—and provide a value in the text box. There are three options.
      • Value—This filter is based on a specific value. You can either set a predefined value or interactively ask the end user for a new value by checking Ask for values. When Ask for values is enabled, provide information about the value in the Prompt field and a hint in the Hint field. This will help the end user enter their query values.
      • Field—Compare the value in one field with the value in another field.
      • Unique—This filter is based on a list of the unique values for the selected field in the layer. It is often used in conjunction with Ask for values so the end user can interactively select a value from a list, which can be a set of all unique values or a set of dynamic unique values based on the previous expressions or on all other expressions regardless of their order. When Ask for values is enabled, provide information about the value in the Prompt field and a hint in the Hint field, and select how the values are listed.

        Caution:

        To display description for coded values when Values filtered by previous expressions or Values filtered by all other expressions is selected, the service must support the capability of query by statistics.

   3. You can also use Add an expression set, which allows you to define and apply two filters to a single query. If All or Any of the expressions in this set are true, records meeting all the expressions or records meeting any of the expressions in the set are returned as results.
   4. Click OK to close the dialog box.
10. Check Display SQL expression for end users if you want to show the SQL expression on the widget.
11. The Spatial filters section allows you to choose which spatial filters will be available to end users. Check one or more of the following filters and set one of them as the default by clicking Make default.
    • Only return features within current map extent—Return features within the current map extent.
    • Only return features that intersect with the shape drawn on the map—Click the icons to choose drawing tools shown on the widget. Check Enable buffer option if you want to add a buffer setting for end users.
    • Only return features that have a spatial relationship with features in another layer—Click Set to choose spatial relationship rules from Set Spatial Relationships. You can specify a user-friendly label for each relationship by double-clicking the label field. Check Enable buffer option if you want to add a buffer setting for end users. The following spatial relationships are supported:
      • Intersect—Part of a feature from layer 1 is contained in a feature from layer 2.
      • Contain—Part or all of a feature from layer 1 completely contains the feature from layer 2.
      • Cross—The feature from layer 1 crosses a feature from layer 2.
      • Envelope intersect—The envelope of layer 1 intersects with the envelope of layer 2.
      • Index intersect—The envelope of the query layer intersects the index entry for the target layer.
      • Overlap—Features from layer 1 overlap features in layer 2.
      • Touch—The feature from layer 1 touches the border of a feature from layer 2.
      • Within—The feature from layer 1 is completely enclosed by the feature from layer 2.
    • Return features within full extent of the map—Return features within the full extent of the map.

    Note:

    Uncheck all the options if you don't want to apply a spatial filter to the query.
12. Click the Results tab to configure the displayed content and symbol for the query results.
13. Check Use layer's pop-up configuration in the web map if you want to show the same content defined by the layer’s pop-up configuration in the web map.
14. Check Configure custom content if you want to show the custom content.
    1. Click the add icon next to the Title of each result item text box.

       The list of fields in the layer displays. You can select fields one at a time. Values from the selected field display in the text box and are used as the query results title. Repeat this step to add additional fields. When multiple fields are added, the concatenation of field values are used as the result title.

    2. Click the pencil icon next to the These field attributes will display text box to open the Set Display Fields dialog box. Check the fields you want to display in the results. For individual fields, the Special Type column allows them to display as a link or an image depending on your selection. You can also click the up and down arrows in the Actions column to adjust the field order.
15. Click the pencil icon next to Sort result items to configure the fields by which the query result is sorted.

    The services must support pagination or sort on the query result.

16. Select the Use symbols defined by the layer option if you want to use the layer’s default symbol.
17. Optionally select the Use custom symbol option, and click the symbol icon to set a custom symbol.

    The Preview window appears, allowing you to choose the color and style for the resulting highlighting symbol.

18. Click anywhere outside of the symbol preview window to close it.
19. Optionally check Allow to change symbols at runtime if you want to interactively change the symbols for the resultant features at run time.
20. Click the Options tab to specify whether or not the query results can be exported and how the query task will create layers.
21. Repeat steps 3 through 20 to add more query tasks.
22. To reorder the existing query tasks, hover over the task and click the up and down arrows.
23. Click OK to save and close the Query window.

Use the Query widget

The following steps explain how to use the Query widget:

1. Click the Query widget to open it. A list of queries is shown on the Tasks tab if you have configured more than one query.

   

   If the widget only has one query, and it does not ask for input from end users, clicking the widget will run the query and immediately display the results.

   if the widget only has one query, and it asks for input from end users, clicking the widget will display the query with user inputs.

   Note:

   The input from end users can include attribute criteria, one or many spatial filters, or a combination of both.

2. Click one of the queries. The query may execute differently depending on your configuration.
   1. If the query does not ask for input, the result is shown on the Results tab, and the resulting features display on the map with the symbol you specified during the configuration.
   2. If Ask for values is checked in the configuration, a text box displays prompting you for a new value for the parameter. The default value initially shows in the box. If unique values are set, the text box will list them all.
   3. You can use one or more spatial filters.
      • Only return features within current map extent—Return features within the current map extent.
      • Only return features that intersect with the shape drawn on the map—A set of drawing tools can be used to draw shapes on the map to define the area. Optionally, a search distance can be applied to the shapes.

        

      • Only return features that have a spatial relationship with features in another layer—The results are based on the spatial relationship between features in the query layer and features in the related layer. Optionally, a search distance can be applied to the geometries of the features in the related layer.

        

      • Return features within full extent of the map—Return features within the full extent of the map.
   4. Click Execute to run the query.

      Features resulting from the query are highlighted on the map with the symbol you specified during the configuration. If the layer has related data, the related records are also included in the results.

3. Click the ellipsis (…) to take actions on the results set, such as running statistics, exporting the results locally or to My Content in ArcGIS Online or Portal for ArcGIS, or changing the feature symbol.

   Tip:

   The maximum number of features a query can return depends on the maxRecordCount property set in the service. The default is 1,000. For example, if you take the default value and expect 1,300 features to return from a query, you will first see 1,000 features in the query result panel. When you scroll down the panel, you will see the remaining 300 features.

   Alternatively, if the query is performed on a related table, all the related features are highlighted on the map and listed in the Query panel.