GP service example: Selecting data

Complexity: Beginner Data Requirement: ArcGIS Tutorial Data Setup

Folder	SelectingData
Purpose	Demonstrates various ways to select data by attribute query or location query.
Services	SelectingData (geoprocessing service with a source map document) SelectingDataRMS (geoprocessing service with result map service)
Geoprocessing tasks	Several (See the models below.)
Inputs	Varies by model; usually a query string or a feature set.
Output	Selected data
Data	Uses a dataset of a small area in the city of Portland, Oregon.
Extensions	None

About this example

About these services

A common task for geoprocessing services is to select a subset of data based on an attribute query or a spatial query. The models in this example demonstrate several useful ways of selecting data. The primary geoprocessing tools used in these models are Select Layer By Attribute and Select Layer By Location. Both tools take layers as input. Their output is the updated input layer containing the selected features.

Because Select Layer By Attribute and Select Layer By Location output layers (as opposed to datasets), you need to be aware of how ArcGIS Server handles tasks that output layers. Recall that there are three geoprocessing service configurations, shown below:

In the first two configurations, when ArcGIS Server executes a task that outputs a layer, it reads the selected features from the layer and transports the selected features back to the client.

In the third configuration, there are two services—the geoprocessing service and the result map service. The two services execute independently of each other. When the task executes, ArcGIS Server executes the geoprocessing task first, then executes the result map service, which draws the output of the geoprocessing service, sending the map image of the output data back to the client. Because of this execution order, the result map service needs datasets on disk produced by the geoprocessing service. This means that the output of the tasks in the geoprocessing service must be datasets, not layers. Layers, allowed in the first two configurations, do not work with the result map service configuration.

In this example, you will find two toolbox/map document pairs; SelectingData (for publishing as a geoprocessing service with a source map document) and SelectingDataRMS (for publishing as a geoprocessing with a result map service). The tools in the SelectingDataRMS toolbox result in datasets on disk, while the tools in the SelectingData toolbox result in layers. In general, the tools in the SelectingDataRMS toolbox take a bit longer to execute since they must copy their data to disk.

Which service you choose to publish—SelectingData or SelectingDataRMS—is up to you. Typically, you publish a result map service when any of the following are true:

• The selected set of features can be large and you do not want to transport a large number of features back to the client.
• You want to protect your data and only let the client see a map image of the data.
• You have advanced cartography that can only be drawn by ArcMap, not other client applications.

Data

The data is of a small area in the city of Portland, Oregon, and is found in C:\arcgis\ArcTutor\GP Service Examples\SelectingData\ToolData\Portland.gdb. This file geodatabase has been compressed to save space using the Compress File Geodatabase Data tool. You cannot make edits to a compressed file geodatabase. If you need to make edits, use the Uncompress File Geodatabase tool.

Several of the models use feature set and record set variables, which need schemas to define their feature types and fields. These schemas can be found in C:\arcgis\ArcTutor\GP Service Examples\SelectingData\ToolData\Templates.gdb.

Overview of the models

SelectingData toolbox and map document

Toolset	Tool	Description
Select By Attribute
	Select Tax Lots With Value Greater Than	Selects all tax lots whose total value is greater than the value the user enters.
	Select Tax Lots With Value Greater Than (with summary)	Same as above, but additionally summarizes the total value of all selected lots.
	Select Tax Lot By Address (attribute method)	Given an address, selects the tax lot.
	Select Neighborhood	Selects a neighborhood from a drop-down list.
	Select Layer By Area	Allows the user to first select a layer, then selects features based on their area.
	Mailing List	Selects a tax lot by address, selects all tax lots within a given distance, then produces a mailing list for all selected tax lots.
Select By Location
	Select Tax Lot By Address (location method)	Given addresses, creates a point feature for each address and uses these point features to select tax lots.
	Select Tax Lots By Neighborhood	Selects tax lots based on a selected neighborhood polygon.
	Select Tax Lots By Neighborhood (optimized)	Same as above, but uses a preprocessed dataset to perform the selection.

SelectingData toolbox

SelectingDataRMS toolbox and map document

The tools in the SelectingDataRMS toolbox perform the same work as the tools in the SelectingData toolbox. The main difference is that the SelectingDataRMS tools output feature classes that can be drawn by the result map service. The Copy Features tool is used to copy the features from the layer to the feature class. Illustrated below is the Select Tax Lots With Value Greater Than model using the Copy Features tool. All the tools in the toolbox follow a similar pattern.

Select Tax Lots With Value Greater Than (for result map service)

Attribute and spatial indexes

Whenever you query a particular field often, as these services do, the speed of the queries can be increased by creating indexes on the query fields. For example, the Select Tax Lots With Value Greater Than task queries the TOTALVAL field, so to optimize the queries, TOTALVAL has an attribute index. You can use the Add Attribute Index tool to create attribute indexes.

Similarly, if you are performing spatial queries, spatial indexes will increase how quickly features can be located. Spatial indexes are automatically created and maintained for feature classes in a geodatabase, but not so for shapefiles.

Learn more about geodatabase spatial indexesLearn more about shapefile spatial indexesLearn more about the Add Spatial Index tool

Working with layer selections and tool layers

The SelectingData map document contains tool layers for each of the tools listed above. The sublayer found in the tool layer (the output of the tool) is the same as the input layer—it is not an independent layer. Because it is not independent, if you change the properties of either the original input layer or the output sublayer, the other layer's properties change as well. As illustrated below with the Select Tax Lots With Value Greater Than tool, both the input and output layer are Tax Lots. If you right-click the Tax Lot layer (the input layer) in the ArcMap table of contents and change the symbology, the symbology on both layers will change.

When you work with layer selections (as these tools do), there are a few guidelines to remember:

• When you create the tool layer in ArcMap (before publishing), the sublayer (the output of the model) will always be a layer named the same as the input layer, regardless of the output variable name in the model. The symbology will be the same as the input layer.
• When you execute the server task (after publishing), the output layer will be the name of the model variable.

Building expressions using variable substitution

Selection expressions usually require an input from the user. As shown in the Select Tax Lots With Value Greater Than model below, the user's input is the Total value greater than variable. This is a double variable created as follows:

Steps:

1. In ModelBuilder, right-click the canvas and click Create Variable
2. On the Create Variable dialog box, choose Double as the variable type.
3. Click OK.
4. Rename the variable.
5. Open the variable and provide a default value, if desired.

When creating the expression on the Select Layer By Attribute tool dialog box, you use percent signs (%) around the variable name.

Although it is not required, it is good practice to make the variable a precondition to the process that substitutes the variable. To make a precondition, follow these steps:

Steps:

1. In ModelBuilder, right-click a tool and click Properties.
2. Click the Preconditions tab.
3. Choose the variable or variables that are a precondition to tool execution.

Selection method

Both the Select Layer By Attribute tool and the Select Layer By Location tool have several options for selection. For example, instead of creating a new selection, you can add or remove features from the current selection. The Select Layer By Location tool lets you establish a spatial relationship, such as CONTAINS, WITHIN, and INTERSECT. The example models make use of just a few of the options. Consult the Select Layer By Location tool documentation for more information.

Selecting data without map layers

You do not need to use layers from a map document to make use of the Select Layer By Attribute and Select Layer By Location tools. You can create a feature layer from a dataset by using the Make Feature Layer tool, as shown below.

Using Make Feature Layer in a model

You can also use the Select tool to create a dataset of selected features from a dataset—no layer is required.

Using the Select tool

The Select Tool performs attribute selection. If you need to perform spatial selection, consider using one or more of the following tools:

• The Make Feature Layer tool
• Tools from the Analysis toolbox, such as Clip or Spatial Join

SelectionUtilities

This toolbox contains several utility tools to support the tasks.

Tool	Description
Check Match Results	Checks the output of the Geocode Addresses tool and outputs an error if addresses do not match.
Get 1 Field Value	Reads a field value from the first record of a table and outputs it to a geoprocessing model variable.
Get 2 Field Values	Same as above, but reads two fields and outputs two variables.
Get 3 Field Values	Same as above, but reads three fields and outputs three variables.
Overlay Tax Lots And Neighborhoods	Creates the dataset used by the Select Tax Lots By Neighborhood (optimized) model above.
Print Tax Lot Mailing Labels	Given a selected set of tax lots, prints a file of mailing labels.

Utility tools

Notes on the models

Select Tax Lots With Value Greater Than

This is the simplest of the models. It selects all tax lots whose total value is greater than the input value. As noted above, it uses variable substitution to build the select expression.

Select Tax Lots With Value Greater Than

Select Tax Lots With Value Greater Than (with summary)

This performs the same work as the model above, then adds the Summary Statistics tool to sum the total value of all selected lots. Summary Statistics outputs a table that is read by the Get 2 Field Values tool, a utility tool found in the SelectionUtilities toolbox included with this example. This is a script tool that outputs the values of two fields, Total value of all lots and Number of lots. These values, along with the selected tax lots, are returned to the client.

Select Tax Lots With Value Greater Than (with summary)

The output of Summary Statistics is written to an in-memory table rather than a table on disk. Writing tables and feature classes to memory is fast compared to writing to disk.

Select Tax Lot By Address (attribute method)

Selecting features by address is a common task. This model shows one method of selecting features by address (another method is shown below).

Select Tax Lots By Address (attribute method)

Model element	Description
TaxLot Locator	An address locator for the TaxLots feature class. This locator uses the U.S. Single Address style. Learn more about address locators
Address	This is a record set variable. The template is ToolData/templates.gdb/Address. For some sample addresses in the study area, see ToolData/sample addresses.txt.
Geocode Addresses	Takes a table containing addresses and outputs a point feature class of the address location. A status field is also output. This field will contain an M if the address was found.
Check Match Results	A custom script tool found in the SelectionUtilities toolbox included with this example. It checks that the address was successfully match.
Success	Output of Check Match Results. True if there was one address input and the address matched.
Get 1 Field Value	A custom script tool found in the SelectionUtilities toolbox included with this example. It retrieves the unique object ID of the tax lot matching the address.
Select Layer By Attribute	Selects the tax lot with the object ID output by Get 1 Field Value.

Model elements

Select Neighborhood

This model selects a polygon from the Neighborhood layer.

Select Neighborhood

This model lets you pick a neighborhood from a list of neighborhoods. The Neighborhood Name variable is a string variable that has a Value List filter containing all neighborhood names. To create or change a filter, open the model properties dialog box and click the Parameters tab, shown below.

Select Layer By Area

This model allows the user to first select a layer, then specify a minimum area for selection.

The main feature of this model is how it allows you to first choose a layer. The Layer to Select variable is a string variable that has a Value List filter containing Tax Lots and Neighborhoods. To view the filter, open the Model Properties dialog box and click the Parameters tab, as illustrated below.

The Calculate Value tool takes the string and turns it into a feature layer variable, as illustrated below. This technique of turning a string into another data type is discussed in Input and output data types. The output of Calculate Value is input to Select Layer By Attribute.

Finally, the selected features are copied to a feature class using the Copy Features tool. This final step is not required. (Copying the features helps to avoid confusion when creating and testing the tool layer.) The features are written to memory rather than to disk (writing features to memory is faster than writing to disk). In the SelectingDataRMS toolbox, the selected features have to be written to disk for the result map service to draw them.

Mailing List

This model shows how to select nearby features based on a selected feature, as well as generating a simple text containing the addresses of the nearby features.

Mailing List

Model element	Description
Address	This is a record set variable. The template is ToolData/templates.gdb/Address. For some sample addresses in the study area, see ToolData/sample addresses.txt.
Select Tax Lot By Address (attribute method)	This is the model described above.
Selected Lot	The selected tax lot. This is the Tax Lot layer.
Search Distance	Search distance to use.
Input Layer	The Tax Lot layer.
Select Layer By Location	Selects all tax lots within the distance specified, using Selected Lot as the center of the search.
Tax Lots	Tax lots within the search distance.
Print Tax Lot Mailing Labels	A custom script tool found in the SelectionUtilities toolbox.
MailingList.txt	A text file containing mailing addresses.
Success	True if every record has a mailing address. False if one or more of the records has an empty or corrupted mailing address.

Model elements

Select Tax Lot By Address (location method)

This is the first of the tools found in the Select By Location toolset. It does the same work as the Select Tax Lot By Address (attribute method) tool, but instead of selecting the tax lot using the feature ID, it uses the output point feature of Geocode Addresses as input to Select Layer By Location .

This is the method to use when the geocoded point comes from a different locator. For example, the locator may be based on a street dataset, and you need to use the geocoded point to select a nonstreet feature, such as a building, tax lot, or point of interest.

Select Tax Lot By Address (location method)

Select Tax Lots By Neighborhood

Another common selection task is to use a feature from one dataset to select a feature from another dataset. This model uses the Select Neighborhood model described above to select a single neighborhood, then uses the Select Layer By Location tool to select all tax lots that fall within the neighborhood.

Select Tax Lots By Neighborhood

Select Tax Lots By Neighborhood (optimized)

The methodology used by the Select Tax Lots By Neighborhood model above is acceptable for infrequent queries. That is, an analyst might use this method to find the tax lots for a quick onetime analysis. But geoprocessing services are usually tasks that are run repeatedly and often. Since selecting tax lots by a neighborhood is a task that will be used frequently, you want to optimize it.

For this optimization, the Intersect tool is used to assign the neighborhood name to each tax lot. The Overlay Tax Lots And Neighborhoods tool found in the SelectionUtilities toolbox shows how to use the Intersect tool to create a new dataset that contains all tax lots with all the neighborhood attributes. This model only needs to be executed once to produce the TaxLotsOverNeighborhoods dataset.

Overlay Tax Lots And Neighborhoods

Once TaxLotsOverNeighborhoods is created, all that is necessary is a simple attribute query to select all tax lots within a neighborhood.

Select Tax Lots By Neighborhood (optimized)

Publishing

Publish Portland.mxd found in the publishing section of GP service example: Clip and ship as a map service. You will use this map service as a basemap for the services in this example. (The corresponding folder for this service is C:\arcgis\ArcTutor\GP Service Examples\ClipAndShip.)

Publish SelectingData.mxd as a geoprocessing service based on a source map document. Because features are sent back to the client, be sure to increase the maximum number of records that can be returned by the service to 11,000 (slightly more than the number of features in the Tax Lot layer).

Learn more about publishing geoprocessing services with a source map document

Publish SelectingDataRMS as a geoprocessing service with a result map service.

Learn more about publishing geoprocessing services with result map services

Using

To use the services, open a new ArcMap session and add the Portland map service as a basemap.

Open the Catalog window and go to the ArcGIS Server user connection where you can see and execute all the tasks you published. Expand SelectingDataRMS service and execute the Mailing List task.

Open the Results window and perform the following steps:

Steps:

1. Expand the MailingList result.
2. Right-click the Mailing List task result and choose Get Data. The task result changes from <Data on Server> to MailingList.txt.
3. Right-click MailingList.txt and click Copy Location. (Since the result is a text file, Add to Display has no effect.)
4. Open your Internet browser and paste the location into the address bar. The contents of MailingList.txt appear.
5. Optionally, you can click the Copy tool and drag MailingList.txt from the Results window onto the input parameter of the Copy tool dialog box. The file is copied to a location of your choice.