Query Tools
Querying GIS Data
Query tools, located on every layer, allow you find features based on a number of different spatial queries. These queries leverage the spatial indexes inherent in nearly every GIS data format. Those indexes allow you to find very specific features quickly even though you may have millions of features.
Each different type of query is useful based on your scenario, and we will cover some common uses for each. It’s important to note that these queries are layer-based and need to be thought of in the context of finding this in a layer based on some input feature. This is in contrast to geometric functions that only compare one geometry to another. While we support those on individual features, these APIs are meant to go against the entire layer’s dataset.
Crossing
Crosses finds features where a line, point or set of points crosses another line or polygon. It is not designed to compare polygons since intersects and overlap covers for those operations.
A common example is finding lines that cross each other. In GIS, line networks, such as roads, are supposed to terminate when they intersect with another line. This, for the case of roads, denotes an intersection. For tunnels or overpasses, however, these lines will cross, which makes this method ideal to use in order to find those.
Another example would be to find where a line crosses a polygon. Let’s say you have a route and want to see if it avoids a certain area that you want to exclude driving in. You could use crosses query to find if the line crosses that exclusion area.
Sample Code
Containing
This query allows you to find all the features that contain a given feature. This is useful in hierarchal datasets where you have smaller features inside of larger boundary features.
A perfect example is where you are trying to find what state and county a particular road is in. Assuming you have the state and county data, you could use the Containing query on the state and county layers, passing in the road. The result would be the county or state that the road is in.
Sample Code
Intersecting
The intersecting query allows you to find all features that share a common space with a given feature. This includes features inside, overlapping, or border sharing. This is commonly used for querying shapes to see if a feature has any relationship with any of the other features in the dataset.
As it is the most liberal of the queries, it’s used often. A good example is finding all the features that are within the current map extent. If you take the current extent and choose a layer, such as roads, you will find all the roads related to the extent, even if a road only shares a part of the boundary of the extent.
Sample Code
Overlapping
The overlapping query find shapes that share some of the same, but not all, of the same area.
A common use of this query might be to identify sales territories that may overlap other territories. Sales territories typically do not overlap. So, if you take a particular territory and run the query against the others, any matches might need to be adjusted so that those areas do not overlap.
Sample Code
Within
This query is helpful in finding all the features of a layer that are totally within a given feature. If any part of the layer’s features extends beyond the feature passed in, then they will not be included in the result set.
An example for the Within query might be finding all the land parcels that are within a county, but don’t overlap with another county. Parcels that overlap another county will not be returned, but could later be found by using the Intersection query based on just the boundary of the county polygon.
Sample Code
Within Distance
This handy query finds all of the features of a layer that are within a certain distance to a given feature. The entire feature doesn’t need to be within the distance, any part will suffice.
A great example might be in marketing, where you have customer point data and you want to find all the customers who are within a few miles from a store you are trying to promote. Another example might be finding all of the gas stations within a few miles of your current GPS point location.
Sample Code
Touches
The Touches query allows you to find all of the features that share some part of a boundary, without overlapping, with another feature. It’s useful to find polygons that border other polygons, such as states that border other states.
Another example might be wanting to find all the streets that intersect with an intersection. You would pass in the intersection’s point, and this query would return all the streets that touch at that intersection.
Sample Code
Querying Feature Data
There are a number of APIs that allow you to find features based either on their ID or column data.
Get All Features - Returns all of the features in the particular layer and is mainly used for smaller datasets.
Get Features By Id - This allows you to pass in an ID of a feature and have that feature retrieved.
Get Features By Column Value - Returns all the features that match the column and data value provided.
Get Count - This simply returns how many features are in that layer.
Sample Code
Disjointed
This query is the inverse of intersection as it finds all of the features in a layer that in no way intersects with the feature passed in. Though not as common as the intersects query, it is useful in specific situations, especially when paired with other operations.
An example would be if you have an existing marketing campaign that covers a two mile radius, and you want to see how many more households you could reach if you extended that radius another mile out. You could query the households layer, passing in the existing marketing campaign polygon, and it would return all of the features outside of it. Next, you could test each point to see if it is within three miles. As the first query already excluded the original two mile radius, we would only find the points between two and three miles out.
Sample Code
Equals
This query finds features which are topologically equal, regardless of their column data. At first glance, this doesn’t seem very useful. However, it’s great for finding duplicated data in your layers or as a test before you add new features.
As an example, you may be importing a new dataset you purchased and as you integrate it, you want to ensure that there are no duplicate entries. Before committing a new feature, you can do this spatial query to ensure no duplication of data occurs.
Sample Code
* Feature available, but no specific sample.