TQL tutorial: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
No edit summary
Line 9: Line 9:
|Start your project. This can be a pre-existing project, or a newly created project.
|Start your project. This can be a pre-existing project, or a newly created project.


{{page break}}
{{clear}}{{page break}}
===Creating various Grid Overlays===
===Creating various Grid Overlays===
To experiment with queries for grid calculation results, a [[Grid Overlay]] should be present in the [[Project]]. To experiment appropriately with the various statements, both a [[Heat Stress Overlay]] a [[Water Overlay]] are good [[Grid Overlay]]s to add and experiment with.
To experiment with queries for grid calculation results, a [[Grid Overlay]] should be present in the [[Project]]. To experiment appropriately with the various statements, both a [[Heat Stress Overlay]] a [[Water Overlay]] are good [[Grid Overlay]]s to add and experiment with.
Line 16: Line 16:


{{editor location|Overlays|dropdown=Water|3=Rainfall Overlay}}
{{editor location|Overlays|dropdown=Water|3=Rainfall Overlay}}
[[File:tql-preparation-rainfall.jpg|frame|center|TODO]]


Next Ensure a [[Heat Stress Overlay]] is present in the [[Project]].
Next Ensure a [[Heat Stress Overlay]] is present in the [[Project]].


{{editor location|Overlays|dropdown=Environmental|3=Heat Overlay}}
{{editor location|Overlays|dropdown=Environmental|3=Heat Overlay}}
[[File:tql-preparation-heat.jpg|frame|center|TODO]]


In addition to a [[Heat Stress Overlay]]'s default [[Pet result type (Heat Overlay)|PE Temperature]] result, a shade result can be output as well, which will be useful in demonstrating specific query structures.
In addition to a [[Heat Stress Overlay]]'s default [[Pet result type (Heat Overlay)|PE Temperature]] result, a shade result can be output as well, which will be useful in demonstrating specific query structures.
Line 26: Line 28:


Click on "Configuration Wizard" to open the [[Heat Overlay Wizard (Heat Overlay)|Heat Overlay Configuration Wizard]].
Click on "Configuration Wizard" to open the [[Heat Overlay Wizard (Heat Overlay)|Heat Overlay Configuration Wizard]].
[[File:tql-preparation-heat-configuration.jpg|frame|center|TODO]]


Continue to the step regarding "Output Overlays".
Continue to the step regarding "Output Overlays".


Ensure that, in addition to the default [[Pet result type (Heat Overlay)|PE Temperature]] result, the [[Shade result type (Heat Overlay)|Shade]] result type is selected as well.
Ensure that, in addition to the default [[Pet result type (Heat Overlay)|PE Temperature]] result, the [[Shade result type (Heat Overlay)|Shade]] result type is selected as well.
[[File:tql-preparation-heat-outputs.jpg|frame|center|TODO]]


Close the [[Heat Overlay Wizard (Heat Overlay)|Heat Overlay Configuration Wizard]]
Close the [[Heat Overlay Wizard (Heat Overlay)|Heat Overlay Configuration Wizard]]
Line 36: Line 40:


{{editor location|update}}
{{editor location|update}}
 
[[File:tql-preparation-update.jpg|frame|center|TODO]]
}}
}}
 
{{clear}}
==Introduction to TQL==
==Introduction to TQL==
TQL is an abbreviation for [[Tygron Query Language]]. It is a custom query language created to allow for obtaining statistical data from a [[Project]]. The language consists of "queries", which can be interpreted as questions asked of the [[Project]]. Such a query is composed of a statement, which embodies the requested information, and a number of clauses, which define/filter the data taken into consideration.
TQL is an abbreviation for [[Tygron Query Language]]. It is a custom query language created to allow for obtaining statistical data from a [[Project]]. The language consists of "queries", which can be interpreted as questions asked of the [[Project]]. Such a query is composed of a statement, which embodies the requested information, and a number of clauses, which define/filter the data taken into consideration.
Line 51: Line 55:
To get started with the creation of queries, open the [[query tool]]:
To get started with the creation of queries, open the [[query tool]]:
{{editor location|query tool}}
{{editor location|query tool}}
[[File:tql-tool-open.jpg|frame|center|TODO]]


The query tool is an assistive tool for the creation of queries. It helps by offering up options for which clauses can be added to statements and queries. It also allows for executing queries and seeing the results. This means that any created queries can be validated that they function as expected, but also that small bits of information can be requested on-the-fly.
The query tool is an assistive tool for the creation of queries. It helps by offering up options for which clauses can be added to statements and queries. It also allows for executing queries and seeing the results. This means that any created queries can be validated that they function as expected, but also that small bits of information can be requested on-the-fly.


When the query tool opens, a simple query is already composed.
When the query tool opens, a simple query is already composed.
[[File:tql-tool-firstquery.jpg|frame|center|TODO]]


If any clauses are listed, click on "Remove clause" for each of them until no clauses remain. Only the statement should remain.
If any clauses are listed, click on "Remove clause" for each of them until no clauses remain. Only the statement should remain.
[[File:tql-tool-statement1.jpg|frame|center|TODO]]


Ensure the query type is set to "SELECT", which means to request data from the Project.
Ensure the query type is set to "SELECT", which means to request data from the Project.


Ensure the statement is set to "LANDSIZE", which is a request for surface area.
Ensure the statement is set to "LANDSIZE", which is a request for surface area.
[[File:tql-tool-statement1-detail.jpg|frame|center|TODO]]


Click on "Execute Query".
Click on "Execute Query".
[[File:tql-tool-statement1-executequery.jpg|frame|center|TODO]]


The result shown is the surface area found in the Project, unqualified. It will be the size of the [[Project]] in its entirety.
The result shown is the surface area found in the Project, unqualified. It will be the size of the [[Project]] in its entirety.
[[File:tql-tool-statement1-result.jpg|frame|center|TODO]]


Next, click on "Add clause". This adds a qualifier to the query; a filter or rule the data must conform to before being taken into consideration.
Next, click on "Add clause". This adds a qualifier to the query; a filter or rule the data must conform to before being taken into consideration.
[[File:tql-tool-statement2-addclause.jpg|frame|center|TODO]]


Set the clause to "NEIGHBORHOOD", and select a Neighborhood which is well present in the [[Project]].
Set the clause to "NEIGHBORHOOD", and select a Neighborhood which is well present in the [[Project]].
[[File:tql-tool-statement2-clausedetail.jpg|frame|center|TODO]]


Then, click on "Execute Query" again.
Then, click on "Execute Query" again.


The result shown is the surface area which lies in the selected [[Neighborhood]].
The result shown is the surface area which lies in the selected [[Neighborhood]].
[[File:tql-tool-statement2-result.jpg|frame|center|TODO]]


Note that the composed query is shown in the query tool as well. The dropdowns allow for (and guide) the selection of the individual parts of the query, but the full query is all components strung together.
Note that the composed query is shown in the query tool as well. The dropdowns allow for (and guide) the selection of the individual parts of the query, but the full query is all components strung together.
[[File:tql-tool-statement2-query.jpg|frame|center|TODO]]


Also note that using the dropdown, a [[Neighborhood]] could be selected by name, but in the actual query the [[ID]] of the [[Neighborhood]] is used. If the name of the [[Neighborhood]] (or any other [[Item]] being queried) is ever changed, the [[ID]] remains unchanged and thus the query will remain functional.
Also note that using the dropdown, a [[Neighborhood]] could be selected by name, but in the actual query the [[ID]] of the [[Neighborhood]] is used. If the name of the [[Neighborhood]] (or any other [[Item]] being queried) is ever changed, the [[ID]] remains unchanged and thus the query will remain functional.


==Basic queries==
==Basic queries==
To begin working with TQL, it is necessary to have a basic sense of the most commonly used components. With a few basics it is possible to reformulate questions and use-cases to fit into a query form.


===Statements===
===Statements===
To create queries effectively, some knowledge of which statements are available is important. Construct the following queries and see the results:
To create queries effectively, some knowledge of which statements are available is important. These will be essential as they determine the kinds of data you can obtain from any [[Project area]]. Construct the following queries and see the results:


; SELECT_NAME
; SELECT_NAME
Line 89: Line 104:


The result is the name of the [[Neighborhood]] queried.
The result is the name of the [[Neighborhood]] queried.
[[File:tql-tool-statements3-name.jpg|frame|center|TODO]]


; SELECT_LANDSIZE
; SELECT_LANDSIZE
Line 96: Line 112:


The result is the size of the entire [[Project area]].
The result is the size of the entire [[Project area]].
[[File:tql-tool-statements3-landsize.jpg|frame|center|TODO]]


; SELECT_LOTSIZE
; SELECT_LOTSIZE
Line 103: Line 120:


The result is the surface area within the [[Project area]] which is taken up by [[Building]]s.
The result is the surface area within the [[Project area]] which is taken up by [[Building]]s.
[[File:tql-tool-statements3-lotsize.jpg|frame|center|TODO]]


; SELECT_FLOORSIZE
; SELECT_FLOORSIZE
Line 110: Line 128:


The result is the total floorsize of ''all'' [[Building]]s in the [[Project area]].
The result is the total floorsize of ''all'' [[Building]]s in the [[Project area]].
[[File:tql-tool-statements3-floorsize.jpg|frame|center|TODO]]


; SELECT_UNITS
; SELECT_UNITS
Line 117: Line 136:


The result is the total amount of housing units in the [[Project area]]. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.
The result is the total amount of housing units in the [[Project area]]. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.
[[File:tql-tool-statements3-units.jpg|frame|center|TODO]]


===Clauses===
===Clauses===
Line 126: Line 146:


The result is the total amount of housing units in the specified [[Neighborhood]]. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.
The result is the total amount of housing units in the specified [[Neighborhood]]. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.
[[File:tql-tool-statements4-units-neighborhood.jpg|frame|center|TODO]]


; WHERE_CATEGORY_IS_...
; WHERE_CATEGORY_IS_...
Line 133: Line 154:


The result is the amount of office space in the [[Project area]].
The result is the amount of office space in the [[Project area]].
[[File:tql-tool-statements4-floorsize-offices.jpg|frame|center|TODO]]


; WHERE_STAKEHOLDER_IS...
; WHERE_STAKEHOLDER_IS...
Line 140: Line 162:


The result is the amount of built surface area which is owned by the Municipality.
The result is the amount of built surface area which is owned by the Municipality.
[[File:tql-tool-statements4-lotsize-stakeholder.jpg|frame|center|TODO]]


; WHERE_FUNCTIONMULT_IS_...
; WHERE_FUNCTIONMULT_IS_...
Line 149: Line 172:


The result is the amount of parking spots which are required to meet the parking demand of all [[Building]]s in the [[Project area]]. This is calculated by obtaining all the floorsize of all [[Building]]s, and then multiplying it by the respective [[Parking lots demand (Function Value)|parking demand]] for all [[Building]]s.
The result is the amount of parking spots which are required to meet the parking demand of all [[Building]]s in the [[Project area]]. This is calculated by obtaining all the floorsize of all [[Building]]s, and then multiplying it by the respective [[Parking lots demand (Function Value)|parking demand]] for all [[Building]]s.
[[File:tql-tool-statements4-floorsize-parkingdemand.jpg|frame|center|TODO]]


Create and execute the following query: {{code|1=SELECT_FLOORSIZE_WHERE_CATEGORYMULT_IS_PARKING_LOTS_PER_M2}}
Create and execute the following query: {{code|1=SELECT_FLOORSIZE_WHERE_CATEGORYMULT_IS_PARKING_LOTS_PER_M2}}


The result is the amount of parking spots which are available in the [[Project area]]. This is calculated by obtaining all the floorsize of all [[Building]]s, and then multiplying it by the respective [[Parking lots (Function Value)|parking supply]] for all [[Building]]s.
The result is the amount of parking spots which are available in the [[Project area]]. This is calculated by obtaining all the floorsize of all [[Building]]s, and then multiplying it by the respective [[Parking lots (Function Value)|parking supply]] for all [[Building]]s.
[[File:tql-tool-statements4-floorsize-parking.jpg|frame|center|TODO]]


{{header|level=3|color=#c45911|Assignments}}
{{header|level=3|color=#c45911|Assignments}}
Line 163: Line 188:
===Grid clauses===
===Grid clauses===
The following clauses, related to accessing grids, are important to be aware of to properly work with grids.
The following clauses, related to accessing grids, are important to be aware of to properly work with grids.
Because an important part of querying grids can be filtering based on grid values, it is important to note that TQL does not have an inherent concept of units. Instead, whenever a [[Grid Overlay]]s values are consulted, those values considered as numerical only. The intended unit should be implicitly considered to be the same as that of the consulted grid.


; WHERE_GRID_IS_...
; WHERE_GRID_IS_...
Line 176: Line 203:


The result is the surface area in the [[Project area]] which has calculated temperatures in the range of 35°C to 45°C.
The result is the surface area in the [[Project area]] which has calculated temperatures in the range of 35°C to 45°C.
[[File:tql-tool-statements5-grid-range.jpg|frame|center|TODO]]


; WHERE_TIMEFRAME_IS_...
; WHERE_TIMEFRAME_IS_...
: The [[Timeframe]] of the grid to use. When absent, the last [[Timeframe]] of the [[Grid Overlay]] is used.  
: The [[Timeframe]] of the grid to use. When absent, the last [[Timeframe]] of the [[Grid Overlay]] is used.


Create and execute the following query, with the [[Water Overlay]] selected for the GRID clause: {{code|1=SELECT_LANDSIZE_WHERE_MINGRIDVALUE_IS_0.2_AND_TIMEFRAME_IS_0_AND_GRID_IS_...}}
Create and execute the following query, with the [[Water Overlay]] selected for the GRID clause: {{code|1=SELECT_LANDSIZE_WHERE_MINGRIDVALUE_IS_0.2_AND_TIMEFRAME_IS_0_AND_GRID_IS_...}}


The result is the surface area in the [[Project area]] which has at least 20 cm of water on it at the first recorded timeframe (timeframe 0) of the [[Water Overlay]]'s calculation.
The result is the surface area in the [[Project area]] which has at least 20 cm of water on it at the first recorded timeframe (timeframe 0) of the [[Water Overlay]]'s calculation.
[[File:tql-tool-statements5-grid-timeframe.jpg|frame|center|TODO]]


; WHERE_GRIDVALUE_IS_...
; WHERE_GRIDVALUE_IS_...
Line 190: Line 219:


The result is the surface area in the [[Project area]] which, at the end of the [[Water Overlay]]'s calculation, has no water on it.
The result is the surface area in the [[Project area]] which, at the end of the [[Water Overlay]]'s calculation, has no water on it.
[[File:tql-tool-statements5-grid-value.jpg|frame|center|TODO]]


===Grid statements===
===Grid statements===
Line 200: Line 230:


The result is the average temperature in the [[Project area]].
The result is the average temperature in the [[Project area]].
[[File:tql-tool-statements6-grid-avg.jpg|frame|center|TODO]]


; SELECT_GRIDVOLUME
; SELECT_GRIDVOLUME
Line 207: Line 238:


The result is the volume of water in the [[Project area]].
The result is the volume of water in the [[Project area]].
[[File:tql-tool-statements6-grid-volume.jpg|frame|center|TODO]]


====Boolean results====
====Boolean results====
Line 216: Line 248:


The result is the average value of shade coverage in the [[Project area]].
The result is the average value of shade coverage in the [[Project area]].
[[File:tql-tool-statements7-grid-avg.jpg|frame|center|TODO]]


However, because all the values in the [[Grid Overlay]] are only a 1 or a 0, the result can also be read as the amount of [[Project area]] which has shade coverage.
However, because all the values in the [[Grid Overlay]] are only a 1 or a 0, the result can also be read as the fraction of [[Project area]] which has shade coverage.


Create and execute the following query, with the [[Heat Stress Overlay]]'s [[Shade result type (Heat Overlay)|Shade Coverage]] selected for the GRID clause: {{code|1=SELECT_GRIDVOLUME_WHERE_GRID_IS_...}}
Create and execute the following query, with the [[Heat Stress Overlay]]'s [[Shade result type (Heat Overlay)|Shade Coverage]] selected for the GRID clause: {{code|1=SELECT_GRIDVOLUME_WHERE_GRID_IS_...}}


The result is the average value of shade coverage in the [[Project area]].
The result is the "volume" of shade coverage in the [[Project area]].
[[File:tql-tool-statements7-grid-volume.jpg|frame|center|TODO]]


However, because all the values in the [[Grid Overlay]] are only a 1 or a 0, the value as read as a volume can equally be read as a surface area. (Because all surface area which should be taken into account is multiplied by "1", leaving the value unchanged) Therefore, the result can also be read as the surface area which has shade coverage.
However, because all the values in the [[Grid Overlay]] are only a 1 or a 0, the value as read as a volume can equally be read as a surface area. (Because all surface area which should be taken into account is multiplied by "1", leaving the value unchanged) Therefore, the result can also be read as the surface area which has shade coverage.

Revision as of 11:06, 18 December 2023

This article is a stub.

Prerequisites

The following prerequisites should be met before starting this tutorial:

  • This tutorial relies on base knowledge about the editor interface. If you have not yet followed the tutorials related to those subjects please do so first.
  • This tutorial can be followed with any project of any arbitrary location, preferable in an urban environment. 

Preparations

Take the following steps as preparation for following this tutorial:

  • Start your project. This can be a pre-existing project, or a newly created project.

Creating various Grid Overlays

To experiment with queries for grid calculation results, a Grid Overlay should be present in the Project. To experiment appropriately with the various statements, both a Heat Stress Overlay a Water Overlay are good Grid Overlays to add and experiment with.

First, ensure a Rainfall Overlay is present in the Project.

Editor → Current Situation (Ribbon tab) → Overlays (Ribbon bar) → Water (Dropdown) → Rainfall Overlay
TODO

Next Ensure a Heat Stress Overlay is present in the Project.

Editor → Current Situation (Ribbon tab) → Overlays (Ribbon bar) → Environmental (Dropdown) → Heat Overlay
TODO

In addition to a Heat Stress Overlay's default PE Temperature result, a shade result can be output as well, which will be useful in demonstrating specific query structures.

After adding the Heat Stress Overlay, it will have been selected in the Editor, and its details are opened in the right panel.

Click on "Configuration Wizard" to open the Heat Overlay Configuration Wizard.

TODO

Continue to the step regarding "Output Overlays".

Ensure that, in addition to the default PE Temperature result, the Shade result type is selected as well.

TODO

Close the Heat Overlay Configuration Wizard

Ensure the Heat Stress Overlay is recalculated as well.

Editor → Recalculation icon (Ribbon bar) → Update (Dropdown)
TODO

Introduction to TQL

TQL is an abbreviation for Tygron Query Language. It is a custom query language created to allow for obtaining statistical data from a Project. The language consists of "queries", which can be interpreted as questions asked of the Project. Such a query is composed of a statement, which embodies the requested information, and a number of clauses, which define/filter the data taken into consideration.

TQL queries are an important tool for automated analyses of Projects, both of the Current Situation as well as any Future Designs.

TQL queries by themselves can be used to obtain bits of information. In broader contexts, such as Excel Indicators or Panels, or scripts interacting via the API, the combination of multiple queries allows for obtaining large amounts of information which together can be used for more complex analyses.

Most statements return numerical values which can be used in calculations. Some statements return some form of text.

Query tool

To get started with the creation of queries, open the query tool:

Editor → Current Situation (Ribbon tab) → Queries (Ribbon bar)
TODO

The query tool is an assistive tool for the creation of queries. It helps by offering up options for which clauses can be added to statements and queries. It also allows for executing queries and seeing the results. This means that any created queries can be validated that they function as expected, but also that small bits of information can be requested on-the-fly.

When the query tool opens, a simple query is already composed.

TODO

If any clauses are listed, click on "Remove clause" for each of them until no clauses remain. Only the statement should remain.

TODO

Ensure the query type is set to "SELECT", which means to request data from the Project.

Ensure the statement is set to "LANDSIZE", which is a request for surface area.

TODO

Click on "Execute Query".

TODO

The result shown is the surface area found in the Project, unqualified. It will be the size of the Project in its entirety.

TODO

Next, click on "Add clause". This adds a qualifier to the query; a filter or rule the data must conform to before being taken into consideration.

TODO

Set the clause to "NEIGHBORHOOD", and select a Neighborhood which is well present in the Project.

TODO

Then, click on "Execute Query" again.

The result shown is the surface area which lies in the selected Neighborhood.

TODO

Note that the composed query is shown in the query tool as well. The dropdowns allow for (and guide) the selection of the individual parts of the query, but the full query is all components strung together.

TODO

Also note that using the dropdown, a Neighborhood could be selected by name, but in the actual query the ID of the Neighborhood is used. If the name of the Neighborhood (or any other Item being queried) is ever changed, the ID remains unchanged and thus the query will remain functional.

Basic queries

To begin working with TQL, it is necessary to have a basic sense of the most commonly used components. With a few basics it is possible to reformulate questions and use-cases to fit into a query form.

Statements

To create queries effectively, some knowledge of which statements are available is important. These will be essential as they determine the kinds of data you can obtain from any Project area. Construct the following queries and see the results:

SELECT_NAME
The name of a specific Item.

Create and execute the following query:

SELECT_NAME_WHERE_NEIGHBORHOOD_IS_...

The result is the name of the Neighborhood queried.

TODO
SELECT_LANDSIZE
The amount of surface area matching whichever qualifiers are provided in the clauses.

Create and execute the following query:

SELECT_LANDSIZE_WHERE_

The result is the size of the entire Project area.

TODO
SELECT_LOTSIZE
The amount of surface area which is taken up by Buildings such as apartments, roads, parks and trees. It's effectively the footprint of all constructions.

Create and execute the following query:

SELECT_LOTSIZE_WHERE_

The result is the surface area within the Project area which is taken up by Buildings.

TODO
SELECT_FLOORSIZE
The footprint of constructions, multiplied by their respective floors. The amount of space which the found constructions contain for use. This includes "single floor" constructions like roads and trees, unless further qualified.

Create and execute the following query:

SELECT_FLOORSIZE_WHERE_

The result is the total floorsize of all Buildings in the Project area.

TODO
SELECT_UNITS
The amount of housing units present. This is calculated by dividing the floorspace of Buildings by their respective UNIT_SIZE Attributes. Buildings which are not representative of housing are ignored.

Create and execute the following query:

SELECT_UNITS_WHERE_

The result is the total amount of housing units in the Project area. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.

TODO

Clauses

WHERE_NEIGHBORHOOD_IS_...
The data must be related to, or inside of, this Neighborhood.

Create and execute the following query:

SELECT_UNITS_WHERE_NEIGHBORHOOD_IS_...

The result is the total amount of housing units in the specified Neighborhood. Note that this may include a fractional housing unit, as it is calculated based on the known/computable floor sizes.

TODO
WHERE_CATEGORY_IS_...
The data requested is related to Buildings, and those Buildings must be of a specific Category.

Create and execute the following query:

SELECT_FLOORSIZE_WHERE_CATEGORY_IS_OFFICES

The result is the amount of office space in the Project area.

TODO
WHERE_STAKEHOLDER_IS...
The data must be related to, or owned by, this Stakeholder.

Create and execute the following query, with the Municipal Stakeholder selected for the STAKEHOLDER clause:

SELECT_LOTSIZE_WHERE_STAKEHOLDER_IS...

The result is the amount of built surface area which is owned by the Municipality.

TODO
WHERE_FUNCTIONMULT_IS_...
WHERE_CATEGORYMULT_IS_...
WHERE_ATTRIBUTE_MULT_IS_...
The data requested is related to Buildings, and the found amount is multiplied by the respective Function Values or Attributes.

Create and execute the following query:

SELECT_FLOORSIZE_WHERE_CATEGORYMULT_IS_PARKING_LOTS_DEMAND_PER_M2

The result is the amount of parking spots which are required to meet the parking demand of all Buildings in the Project area. This is calculated by obtaining all the floorsize of all Buildings, and then multiplying it by the respective parking demand for all Buildings.

TODO

Create and execute the following query:

SELECT_FLOORSIZE_WHERE_CATEGORYMULT_IS_PARKING_LOTS_PER_M2

The result is the amount of parking spots which are available in the Project area. This is calculated by obtaining all the floorsize of all Buildings, and then multiplying it by the respective parking supply for all Buildings.

TODO

Assignments

  1. Create a query to find the amount of social housing in the Project area which is owned by a collective corporation.
  2. Create a query to find the surface area in a Neighborhood which is taken up by shops and restaurants.

Grid queries

Queries can be used to consult grid data as well. Spatial calculations can produce produce results which allow for a general estimation of outcomes, but of which the exact values may be more difficult to read. For example, a Heat Stress Overlay may compute the location of hot or cool locations, but it may be difficult to compare optically how two different locations compare to one another.

Grid clauses

The following clauses, related to accessing grids, are important to be aware of to properly work with grids.

Because an important part of querying grids can be filtering based on grid values, it is important to note that TQL does not have an inherent concept of units. Instead, whenever a Grid Overlays values are consulted, those values considered as numerical only. The intended unit should be implicitly considered to be the same as that of the consulted grid.

WHERE_GRID_IS_...
The grid to use. Whenever a query is constructed to consult data related to a query, the consulted grid must be specified as well.
WHERE_MINGRIDVALUE_IS_...
Consulting only grid cells the value of which is at least the specified value. (Inclusive, so a cell with the exact value is included.)
WHERE_MAXGRIDVALUE_IS_...
Consulting only grid cells the value of which is at most the specified value. (Exclusive, so a cell with the exact value is excluded.)

Create and execute the following query, with the Heat Stress Overlay's PE Temperature selected for the GRID clause:

SELECT_LANDSIZE_WHERE_MINGRIDVALUE_IS_35.0_AND_MAXGRIDVALUE_IS_45.0_AND_GRID_IS_...

The result is the surface area in the Project area which has calculated temperatures in the range of 35°C to 45°C.

TODO
WHERE_TIMEFRAME_IS_...
The Timeframe of the grid to use. When absent, the last Timeframe of the Grid Overlay is used.

Create and execute the following query, with the Water Overlay selected for the GRID clause:

SELECT_LANDSIZE_WHERE_MINGRIDVALUE_IS_0.2_AND_TIMEFRAME_IS_0_AND_GRID_IS_...

The result is the surface area in the Project area which has at least 20 cm of water on it at the first recorded timeframe (timeframe 0) of the Water Overlay's calculation.

TODO
WHERE_GRIDVALUE_IS_...
Consulting only grid cells the value of which is exactly the specified value.

Create and execute the following query, with the Water Overlay selected for the GRID clause:

SELECT_LANDSIZE_WHERE_GRIDVALUE_IS_0.0_AND_GRID_IS_...

The result is the surface area in the Project area which, at the end of the Water Overlay's calculation, has no water on it.

TODO

Grid statements

Construct the following queries and see the results.

SELECT_GRIDAVG
The average value of grid values.

Create and execute the following query, with the Heat Stress Overlay's PE Temperature selected for the GRID clause:

SELECT_GRIDAVG_WHERE_GRID_IS_...

The result is the average temperature in the Project area.

TODO
SELECT_GRIDVOLUME
The volume of grid values. The surface area of each individual grid cell, multiplied by its respective value.

Create and execute the following query, with the Water Overlay selected for the GRID clause:

SELECT_GRIDVOLUME_WHERE_GRID_IS_...

The result is the volume of water in the Project area.

TODO

Boolean results

A boolean value is a value which is either "true" or "false". Computationally, a "0" is generally representative of "false", and a "1" is generally representative of "true".

When working with grids which only output a 0 or 1, some statements can be used in slightly more efficient ways as well.

Create and execute the following query, with the Heat Stress Overlay's Shade Coverage selected for the GRID clause:

SELECT_GRIDAVG_WHERE_GRID_IS_...

The result is the average value of shade coverage in the Project area.

TODO

However, because all the values in the Grid Overlay are only a 1 or a 0, the result can also be read as the fraction of Project area which has shade coverage.

Create and execute the following query, with the Heat Stress Overlay's Shade Coverage selected for the GRID clause:

SELECT_GRIDVOLUME_WHERE_GRID_IS_...

The result is the "volume" of shade coverage in the Project area.

TODO

However, because all the values in the Grid Overlay are only a 1 or a 0, the value as read as a volume can equally be read as a surface area. (Because all surface area which should be taken into account is multiplied by "1", leaving the value unchanged) Therefore, the result can also be read as the surface area which has shade coverage.

Assignments

  1. Create a query to obtain the average temperature in a specific neighborhood.
  2. Create a query to obtain the surface area of roads in a specific neighborhood with a temperature of at most 40 degrees.
  3. Create a query to obtain the surface area of roads in a specific neighborhood with is covered by shade

Combined queries

Queries are composed of a single statement, and a number of clauses. The clauses are always connected with an "AND" operation. This means that the data obtained by the query must match all the clauses.

Although TQL does not have an "OR" operation, its functionality can be easily replicated simply by performing complementary statements.

A practical example is obtaining the amount of floorspace of all types of housing combined. There are multiple categories of housing: SOCIAL, NORMAL, LUXE, SENIOR, STUDENT. By using 5 queries, one for each category, the total amount of floorspace of housing can be obtained:

SELECT_FLOORSIZE_WHERE_CATEGORY_IS_SOCIAL
SELECT_FLOORSIZE_WHERE_CATEGORY_IS_NORMAL
SELECT_FLOORSIZE_WHERE_CATEGORY_IS_LUXE
SELECT_FLOORSIZE_WHERE_CATEGORY_IS_SENIOR
SELECT_FLOORSIZE_WHERE_CATEGORY_IS_STUDENT

This principle extends beyond cumulative or complementary data. Other mathematical operations are possible as well.

A practical example is that the amount of actual land can be obtained using the following queries, and subtracting the results from one another:

SELECT_LANDSIZE_WHERE_
SELECT_LANDSIZE_WHERE_TERRAIN_WITH_ATTRIBUTE_IS_WATER

By subtracting all surface area which is a Water Terrain from the total surface area, what remains is all the surface area which is not water.

Another example is calculating fractions, percentages, and ratios. For example, with the same queries listed above for landsize and the surface area for water, it is possible to calculate as a percentage how much of the Project area is covered by water.

Final assignments

These assignments require multiple queries. Perform the required queries in sequence, note the results, and manually perform any calculations using the results to obtain the answer.

  1. Using a LANDSIZE query and a LOTSIZE query, compute the amount of surface area which does not contain a Building in a specific Neighborhood.
  2. Compute the percentage of a specific Neighborhood in use for housing.
  3. Using a UNITS query and a FLOORSIZE query, compute the average size of houses in a specific Neighborhood.
  4. Continuing from that, compare the average size of social housing in a specific Neighborhood with the average size of luxury housing in that same Neighborhood.
  5. Pick 2 or 3 Neighborhoods, and determine which neighborhood remains driest, relative to their size. Test for the existence of more that 10cm of water on land (not on terrain which itself is Water).

Tutorial completed

Congratulations. You have now completed this tutorial. In it, you have learned how to create Combo Overlays, and how to create TQL queries, and the most commonly used query components.