Querying layers

The Query Layer tool allows end users to retrieve features from a map service layer by populating values in a pre-defined query. This query is defined by configuring the tool within the Application Builder, where complex queries that interrogate numerous fields can be constructed. Each condition of the query is encapsulated in a query expression, and these expressions can be grouped and joined using the logical operators "and" and "or." For each expression, the tool can be configured to allow end users to input any value they wish, to restrict their input to a pre-defined list, or not to change the input value at all. For fields that use domains, the values are automatically restricted to those wihin the domain. While the configuration of the tool provides a great deal of flexibility, users of the tool are presented with a simple dialog that consists of labels, textboxes, and drop-down menus for defining query values.

For developers, the tool's full source code has been made available on ArcGIS Online and provides an example of an advanced tool that leverages the Viewer's extensibility endpoints. The implementation provides an example of surfacing complex configuration options that integrate seamlessly with the Application Builder, shows how to execute queries and add layers programmatically, demonstrates how to make an add-in localizable, and more. To view the source code, download the Query tool sample from ArcGIS Online and open the QueryTool.sln file. To debug the add-in, follow the instructions provided in the Deployment and Use Instructions text file included with the sample.

Configuring the Query Layer tool

The steps required to configure the Query Layer tool are provided below. Parts of the configuration that have many options are described in greater detail in subsequent sections.

1. On the Tools tab of the Application Builder, click Add Tool. The Add Tool dialog will appear.
2. Scroll to the Query category, and select the Query Layer tool:

   

3. Click Next
4. Specify the toolbar, label, tooltip, and icon for the tool, then click Next. While, in many cases, the Query Layer tool's default toolbar and icon may be suitable, it is recommended that the label and tooltip be updated to reflect the query that the tool will execute. For example, if the the tool is configured to find US cities with a population greater than a certain amount, an appropriate label would be "Query US Cities," and a suitable tooltip would be "Find US cities based on population."
5. Specify the URL to the layer to be queried and click Connect. Note that this URL must specify a layer within a map service - not the map service itself:

   

6. Once the connection to the layer has been established, click Next
7. Specify an expression for querying features in the layer, including the field, operator, and input method. For more information, see the section Defining a query expression below.
8. Once the query expression has been defined, click Next
9. A page will appear that lists all the query expressions that have been defined. Since only one has been defined at this point, only one will be listed. To define additional query expressions, click Add New. Expressions that have already been defined can be modified and deleted using the buttons that appear next to them. If there are multiple expressions, how they are combined can be manipulated through the selection of logical operators and grouping. For further information, refer to the Combining query expressions section below. Click Next when done defining query expressions.
10. On the page that appears, specify the fields to include with the query results, and review the other options pertaining to how the results are displayed. Then click Next.
11. The last page of the wizard defines the appearance of the dialog that will be presented to end users of the Query Layer tool. The title appearing at the top of the dialog can be specified at the top of the page. In the Parameter Appearance section, the label for each query expression can be defined. Alternatively, if a query expression has a default value, it can be hidden from end users altogether by unchecking the Visible checkbox that appears next to the expression. This will have the effect of always using the default value for the expression when the query is executed.
12. Click OK once specifying the dialog appearance is complete. The Query Layer tool will be added to the specified toolbar.

Defining a query expression

In the Query Layer tool, a query expression defines a condition against which features in the layer to be queried are checked. If features satisfy this condition, then they will be retrieved and shown on the map. Each query expression consists of the following three parts:

• Field - defines which attribute within the layer will be checked for values that satisfy the condtion defined by the query expression
• Operator - specifies the relationship being searched for between the input value and the values in the layer. For example, the greater than (>) operator indicates that features with a value greater than the input value should be retrieved.
• Input method - determines how end users will be able to define input values. If the input method Type in value is selected, then end users will be presented with a textbox to input the value for the query expression. If instead the input method Pick value from list is specified, end users will be shown a drop-down menu with predefined values from which they can select one.

The image below shows a query expression that will retrieve features with a population greater than the input value. A default input value of 100,000 has been specfied.

Combining query expressions

The Query Layer tool provides the ability to include multiple query expressions within a single tool. While specifying multiple expressions is often necessary for retrieval of the desired set of features, having multiple expressions also necessitates consideration of how those expressions are combined. During configuration of the Query Layer tool, the logical operator used to combine multiple expressions can be selected from a drop-down menu as shown below:

When and is selected, it means that features must satisfy both query expressions in order to be included in the query results. When or is specified, features that satisfy either condition will be retrieved.

Expressions can also be grouped to force them to be evaluated together. When combining multiple query expressions, this is sometimes necessary to ensure the desired evaluation of the query. Consider the following set of expressions:

With the expressions combined as shown above, the query will retrieve features that (1) have a population greater than the first input value, (2) have a population less than the second input value, and (3) have a certain class (e.g. city, town, etc), or it will retrieve features that match none of those conditions, but do match the input value for CAPITAL. Suppose that this is not the desired behavior, but instead the intent is to retrieve features that satisfy both of the population conditions and one or the other of the remaining two conditions. This requires grouping the final two conditions to indicate that they should be evaluated together. To do so, simply select the expressions to be grouped by clicking on them, then click the Group Selected button that appears:

Once this is done, a symbol will appear next to the grouped query expressions to indicate the grouping:

Once expressions are grouped, the grouping can be removed by selecting the expressions included in the group and clicking the Ungroup Selected button shown in the image above.

Using the Query Layer tool

Once the Query Layer tool has been configured, it is very simple to use. The steps for doing so are as follows:

1. Click the Query Layer button on the toolbar. Which toolbar includes the tool is defined as part of the tool's configuration.
2. If the tool has been configured with no visible input parameters, the query will execute with the default values that were specified during configuration. Otherwise, a dialog will be displayed to allow the end user to define input values for the query. With the query expressions defined in the previous section, the dialog could appear as shown in the image below. Note the exact appearance will vary depending on the dialog title, labels, and parameter visibility specified during configuration.

   

3. Input the desired values and click Execute. Once the query is complete, the results will be shown on the map:

   

4. To remove results from the map, simply close the dialog. Alternatively, to keep the results on the map after the dialog is closed, check the Keep results on map checkbox before closing the dialog.

: