Envision Query Language

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. run queries on the map to locate IDU’s matching specific attribute criteria, and
  3. 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.

The Field | Operator| Value triplets are the fundamental query elements and are defined as follows:

  1. Field indicates a column name in the IDU database, e.g. LULC_A. Any database column can be referenced using 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.

  2. Operator is one of the relational operators; these include:

    OperatorDefinitionApplicable TypesExample
    =, !=Equal to, not equal toAny (numeric, string)LULC_A = 3
    <, <=Greater than, greater than or equal toAny numericSLOPE < 10
    >, >=Less than, less than or equal toAny numericPOPDENS >= 100
    |, &Logical OR, logical AND: performs bitwise logical operations on the argumentsIntegerDEVELOP_AS | 2
    $, CONTAINSSearches for substrings within strings. The ‘$’ notation is shorthand for the full keywordStringADDRESS contains “Main” ADDRESS $ “Main”

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

  3. 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:

LULC_A=10 AND DIST_STR<100

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

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

OperatorDefinitionApplicable TypesExample
NextTo( query )Returns True if the IDU is adjacent to an IDU that satisfies the query argumentquery: Any valid queryNextTo( 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 queryNextToArea( LULC_A=40 ) > 500
Within(query, distance)Returns True is the IDU is within the specified distance of any IDU that satisfies the query argumentquery: Any valid query; distance: a numeric distance 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 )
    

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.

> 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.