Spatial Query Language Overview

Many of the inputs into Envision can include a spatial query that determines the spatial extent of the phemonemna of interest. ENVISION includes a simple query language and built in query compiler that can be used to:

1. Specify site attribute for policies, to indicate where in the landscape the policy may be applied,
2. To run queries on the map to locate IDU’s matching specific attribute criteria, and
3. To specify inputs into certain evaluative models and autonomous processes.

The syntax for this language is very straightforward and consists most fundamentally of Field | operator | value triplets. These may be logically ‘and’ed or ‘or’ed together and arbitrarily nested to create complex queries. Additionally, the Query language supports several spatial operators to incorporate neighborhood information into the query.

Query Operators

The [Field | operator| value] triplets are the fundamental query elements and are defined as follows:

• Field indicates a column name in the IDU database, e.g. LULC_A. Any database column can be referenced using it's field name. This argument is case-insensitive. Fields in the primary IDU database can by referenced simply by their field name (e.g. AREA). Fields in additional layers included in the application’s Project file can be referenced with an extended syntax that uses a period (.) operate to specify the layer name, field name, and database row to reference. The row reference can be an IDU column name, if the column contains row information for the referenced layer, or can be an explicit row reference. An example of the former is Roads.PaveType[ RoadRef ]. This statement indicates the query references a layer named “Roads”, with a field column named “PaveType”, and the query engine will look up a column in the IDU database named “RoadRef” to find the row in the Roads table that should be returned when the current IDU is being processed. This can be very useful when the IDU layer needs to refer to linked information on an additional map layer.
• operator is one of the relational operators; these include:

  Operator	Definition	Applicable Types	Example
  =, !=	Equal to, not equal to	Any (numeric, string)	LULC_A = 3
  >, >=	Greater than, greater than or equal to	Any numeric	SLOPE < 10
  <, <=	Less than, less than or equal to	Any numeric	POPDENS >= 100
  |, &	Logical OR, logical AND: performs bitwise logical operations on the arguments	Integer	DEVELOP_AS | 2
  $, CONTAINS	Searches for substrings within strings. The ‘$’ notation is shorthand for the full keyword	String	ADDRESS contains “Main”, or ADDRESS $ "Main"

  Note that strings in an expression must be enclosed in double quotes, e.g. “This is a string”.

• value is an expression to be used in the evaluation of the relational operator. This can be a simple expression (e.g. a number or string), a field name (evaluating to the value of the field) or a mathematical expression (e.g. POPDENS*100). Supported mathematical operations include addition (+), subtraction (-), multiplication (*) and division (/).

Complex queries can be constructed using the AND and OR operator to connect the field|operator| value triplets, with optional nesting with parentheses. These operators are not case sensitive. Examples include:

• LULC_A=10 AND DIST_STR<100
• (LULC_A=20 and DIST_STR < 100) OR (LULC_A=30 and DIST_HWY>10)

Spatial Operators

In addition to basic field|operator|value triplets, several spatial operators can be incorporated into a query. These operators are:

Operator	Definition	Arguments	Example
NextTo( query )	Returns True if the IDU is adjacent to an IDU that satisfies the query argument	query: Any valid query	NextTo( LULC_A = 3 )
NextToArea( query )	Returns the area of the region adjacent to an IDU that satisfies the query argument. The area returned is an extended area, meaning it finds all IDUs that define a continuous region around the target IDU, even if some of those IDU’s are not directly adjacent to the target IDU.	query: Any valid query	NextToArea( LULC_A=40 ) > 500
Within(query, distance)	Returns True is the IDU is within the specified distance of any IDU that satisfies the query argument	query: Any valid query distance: a numeric distance, in map units	Within( SLOPE < 10, 100 )
WithinArea (query,radius,percent)	Returns True if the percent area of IDU’s satisfying the query argument within the circle around the center of the IDU is greater than the specified percentage.	query: Any valid query radius: a numeric distance percent: the decimal percent threshold	WithinArea( DENS<100, 1000, 0.20) This is true if within a radius of 1000 of the centroid of the IDU, the DENS value of the IDU areas falling within that radius is less than 100 for at least 20 percent of the area.

These spatial operators can be combined into complex queries in a manner similar to the field|operator|value triplets, e.g.:

• LULC_A=10 and NextTo( LULC_A=30 )

Temporal Operators

The following temporal operators can be incorporated into a query:

Operator	Definition	Arguments	Example
Time()	Returns the current value of teh simulated time.	None	Time() < LASTTIME

Constants

One two constants are defined by the query language, TRUE (which evaluates to 1), and FALSE (which evaluates to 0). These are not case sensitive, so TRUE, true, and TRue all evaluate the same way. These are generally useful for comparing values returned from Boolean database fields.

Embedding Comments in Spatial Queries

Comments can be embedded in spatial queries to greatly improve readability and interpretability of the query string. Anything enclosed in matched braces ( { } ) is considered a comment and ignored by the Query compiler. For example:

• LULC_A=10 {Agricultural Lands} is treated identically as LULC_A=10.