Spatial Match Tool

The Spatial Match tool establishes the spatial relationship (contains, intersects, touches, etc) between two sets of spatial objects. The tool accepts a set of spatial objects from the Target Input and a set of spatial objects from the Universe Input. At least one input stream should contain Polygon type spatial objects.

For more information on the Spatial Match tool, see Spatial Match Behavior.

Connect Inputs

A Universe input connection into this tool is optional (this file can be specified via an input path ), as indicated by the white input connection arrow .

For each record from the Target’s data stream, the Spatial Match tool analyzes the spatial object’s extents and attempts to find a record in the Universe’s data stream whose spatial object’s extents intersect with that of the Target's. If a matching record is found in the Universe Input, it is sent through the Matched output, and joined to the Target record. If no matching Universe Input record is found, the Target record is sent through the Unmatched output.

Configure the Tool

The Spatial Match tool accepts two spatial inputs.

  1. Select the Targets Spatial object.

    2. When working with polygons on both sides, the physically larger polygons should be on the Targets side. When working with polygons and points, the polygon should be on the Targets side.

  2. Specify the Universe object:
    • Use Records from U Input: Select the Spatial Object field from the data going into the tool.
    • Use Records from File or Database: When reading in spatial objects from a data source, make sure the data source that is being brought in has already been sorted on the spatial object. Ensure no connection is going to the U input.
      • To specify the input data source, either type in the file path location of the input or click Browse to navigate to the data source's location.

      • Select the Spatial Object field from the input data source to match against. The physically smaller objects should be on the Universe side.

        Specifying a .yxdb file for direct import is a more efficient vehicle for running a Spatial Match. In fact, it is good practice to convert any static polygon file (such as basic geographies: States, Counties, etc.) to a pre-sorted .yxdb file. See Troubleshooting/FAQ.

        Calgary spatial matches

        If specifying a Calgary (cydb) file, be aware that the Calgary spatial index uses 5 decimal places of accuracy for compression and speed.  The .yxdb spatial index uses 6 decimal places. This adds an addition round off error of up to a maximum of 1.8 feet to Calgary indexes. In other words, it is possible that a point can be 1.8 feet inside of a polygon and be found as outside in Calgary.

  3. Specify the type of Spatial Match to calculate:

    • Where Target Intersects Universe: Matches records where both sets of objects have any area in common.

    • Where Target Contains Universe: Matches records where Target objects contain Universe objects in their entirety.

    • Where Target Is Within Universe: Matches records where Target objects are entirely within Universe objects.

    • Where Target Touches Universe: Matches records where Target objects touches the outside boundary of Universe objects. To qualify as touching, neither object can occupy any of the same interior space.

    • Where Target Touches or Intersects Universe: Matches records where Target objects either share interior space with Universe objects, or touch the boundary of Universe objects.

      • or

    • Bounding Rectangle Overlaps: Matches records where the bounding rectangles of Target objects and Universe objects share interior space.

    • Custom DE-9IM Relation: User must be familiar with DE-91M relations to enter the custom value.

      • When bringing Line type objects into the Spatial Match, matching is based on the bounding rectangle only.

  4. Output Intersection Object (Intersects Only): When checked, the intersection polygon will be included in downstream tools. This option is only relevant when matching polygon to polygon.

Use the table to modify the incoming data stream. Each row in the table represents a column in the data.

To include a column in data, select the check box to the left of the column name. Deselect the check box to exclude the column.

To reorder the columns of data:

  1. Click to highlight a row, or click and drag down to highlight multiple rows.
  2. Click the or arrows, or right-click and drag, to move the rows to a new location.

New columns

The Unknown column is selected by default. It allows new columns in the data. Move the column to the location where you want a new column to be.

To change the supported length (characters for string and numeric fixed decimal types) or measurement (bytes for other numeric types) of data in a column, click Size and type a number. Size varies by data type and can be edited for fixed decimal numeric types and all string types. See Data Types.

Use the [data type]: Forced option to ensure a column always contains the expected data type; this is helpful when creating macros. See Macros.

To change the name of a column, click Rename and type the new name.

To add a description, click Description and type a description.

After selecting or highlighting rows (columns of data) in the table, click Options to view more configuration options:

  • Save/Load: Save the column configuration as a .yxft file. The Alteryx Field Type File is a text file can be used in other workflows using the Load Field Names or Load File Names and Types options.
  • Select: Select or deselect all or highlight columns. Options include Select All and Deselect All.
  • Change Field Type of Highlighted Fields: Change the data type of all highlighted columns at once.
  • Sort: Sort the column order in ascending or descending order. Options include Sort on Original Field Name, Sort on New Field Name, and Sort on Field Type, or Revert to Incoming Field Order.
  • Move: Move highlighted columns to the top or bottom of the list.
  • Add Prefix to Field Names: Add a prefix to the selected or highlighted column name.
  • Add Suffix to Field Names: Add a suffix to the selected or highlighted column name.
  • Remove Prefix or Suffix: Remove the prefix or suffix from the selected or highlighted column name.
  • Clear All Renames: Remove the new name for all column.
  • Clear Highlighted Renames: Remove the new name for all highlighted columns.
  • Revert All to Original Type and Size: Undo all changes to type and size in all columns and use the original values.
  • Revert Highlighted to Original Type and Size: Undo changes to type and size in the selected or highlighted columns and use the original values.
  • Forget All Missing Fields: Remove all columns that are no longer included in the data.
  • Forget Highlighted Missing Fields: Remove all highlighted columns that are no longer included in the data.
  • Deselect Duplicate Fields: Deselect the second column when duplicate column names exist; this optional is only available with multiple inputs.

View the output

The Spatial Match tool produces a single or double data stream with one record for each instance of a Target Input record matching a Universe Input record. The schema of the output table is formed by appending the fields from both records into one wide record.

Spatial outputs

While using spatial tools, you may have more than one spatial object field in the data stream. When you are configuring the final output tool, you must remember that output to files such as .dbf, .xls or .csv do not accept the spatial object fields, and that spatial files only accept one spatial object field.

Connect a Browse tool to each output anchor to view results.

  • M anchors: Matched records that come from this stream are Target records whose object has a match from the Universe stream. The Universe object and selected fields are joined to the Target Record.

    • A Target record may come out of the matched side any number of times, depending on how many Universe objects are matched.

  • U anchors: Unmatched records that come from this stream are Target records whose object that had no match from the Universe stream.