Tygron Query Language: Difference between revisions

From Tygron Preview Support Wiki
Jump to navigation Jump to search
No edit summary
Line 15: Line 15:


It's also possible to execute TQL queries directly via the [[API]]. The advantage of using TQL, rather than inspecting a project's data via the API directly, is that it can be used to perform calculations that require some intermediate processing. For example, calculating the intersection of buildings with an area or neighborhood. Other examples of this include the queries related to values of [[grid overlay|grid]]s, or the multiplication of floor size with a related [[function values | function value]].
It's also possible to execute TQL queries directly via the [[API]]. The advantage of using TQL, rather than inspecting a project's data via the API directly, is that it can be used to perform calculations that require some intermediate processing. For example, calculating the intersection of buildings with an area or neighborhood. Other examples of this include the queries related to values of [[grid overlay|grid]]s, or the multiplication of floor size with a related [[function values | function value]].
==Statements==
Statements are the primary part of a query. They indicate what must be done with data in a [[session]]. Statements start with either <code>SELECT</code> or <code>UPDATE</code>. <code>SELECT</code> statements retrieve data from a [[session]]. <code>UPDATE</code> statements write data into the session. All statements can interact with data, treating it as either item data or polygon data, depending on the exact statement.
===Polygon statements===
These <code>SELECT</code> statements interact with data as polygon data. This means that, depending on the clauses added to the query, they generally compute how much surface area in the [[project area]] meets a certain set of conditions.
====Land polygons====
Land polygon statements relate to the surface area of the land itself, regardless of what is built on it. These are mostly used for getting the sizes of areas, to then divide specific uses by.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| LANDSIZE
| Amount of surface area. (m2)
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Attribute polygons}}
* {{inlink|Grids}}
* {{inlink|Stakeholders}}
* {{inlink|Map types}}
* {{inlink|Layer types}}
* {{inlink|Transformations}}
|-
| LANDPOLYGONS
| Whether land meets the criteria (1) or not (0). When used in a [[panel]] and the panel is opened, the matched land is highlighted.
|
|}
====Levee polygons====
Levee statements relate to the adjustments to the terrain in the form of levees, as effected through applicable actions.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| LEVEES
| The amount of surface area taken up by levees. (m2)
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Attribute polygons}}
* {{inlink|Levees}}
* {{inlink|Timestates}}
* {{inlink|Stakeholders}}
* {{inlink|Map types}}
* {{inlink|Layer types}}
* {{inlink|Transformations}}
|}
====Building polygons====
Building polygon statements relate to surface area in use by [[building]]s. These are mostly used for determining the amount of certain types of buildings, and their cumulative values.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| LOTSIZE
| Amount of surface area used by a [[building]]. (m2)
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Attribute polygons}}
* {{inlink|Grids}}
* {{inlink|Building}}
* {{inlink|Network types}}
* {{inlink|Building categories}}
* {{inlink|Timestates}}
* {{inlink|Attributes}}
* {{inlink|Stakeholders}}
* {{inlink|Relations}}
* {{inlink|Layer types}}
* {{inlink|Map types}}
* {{inlink|Multipliers}}
* {{inlink|Transformations}}
|-
| FLOORSIZE
| The amount of floorspace, based on building's lotsize and their amount of floors. (m2)
|
|-
| UNITS
| The amount of housing units, based on building's lotsize and amount of floors (floorsize), and their unit size.
|
|-
| LOTPOLYGONS
| Whether something meets the criteria (1) or not (0). When used in a [[panel]] and the panel is opened, the polygon is highlighted.
|
|}
====Grid values====
Grid statements relate to calculated values of [[grid overlay]]s. These are used to retrieve calculated effects of built-in spatial calculation models.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| GRIDAVG
| The average value of a [[grid overlay|grid]] within the defined area.
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Attribute polygons}}
* {{inlink|Grids}} (Excluding the value clauses)
* {{inlink|Map types}}
|-
| GRIDSTDEV
| The standard deviation of a [[grid overlay| grid]] within the defined area.
|
|-
| GRIDVOLUME
| The surface area multiplied by the average [[grid overlay| grid]] value on that surface.
|
|-
| GRIDMIN
| The minimum value of a [[grid overlay| grid]] within the defined area.
|
|-
| GRIDMAX
| The maximum value of a [[grid overlay| grid]] within the defined area.
|
|-
| HEIGHT
| The average height of the [[terrain]]. ({{mdatum}})
|
* {{inlink|Grids}} (Including the value clauses)
* {{inlink|Transformations}}
|}
====Distance====
Distance statements are used to determine the distance between the central points of 2 specific polygons.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| DISTANCE
| The exact distance between the center of 2 distinct polygons.
|
|rowspan="9"|
* {{inlink|Specific polygons}} (ONLY ATTRIBUTE and NEIGHBORHOOD)
* {{inlink|Contructions}} (Only BUILDING)
|}
Note that although the clauses are described as "intersecting", in the context of this statement the centers of the selected polygons are used.
===Item statements===
These <code>SELECT</code> statements interact with data as item data. This means that, depending on the clauses added to the query, they retrieve a specific property or value related to a single component of a [[project]], such as an [[area]]'s [[attribute]], or the name of a [[stakeholder]].
====Numeric values====
Numeric value statements relate to [[attribute]]s and [[global]]s, which are both numeric values which can be created, read, and written to during a session. These are mostly used as parameters in calculations of [[grid overlay]]s, and as parameters in user-ceated [[excel]] files for [[indicator]]s and [[panel]]s.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| ATTRIBUTE
| The numeric [[attribute]] value of an item.
|
* {{inlink|Specific polygons}}
* {{inlink|Buildings}}
* {{inlink|Network lines}}
* {{inlink|Interface}}
* {{inlink|Arrays}}
* {{inlink|Map types}}
* {{inlink|Relations}}
|rowspan="9"|
* {{inlink|Variables}}
|-
| GLOBAL
| The value of a [[global]] variable
|
|}
====IDs====
ID statements are used when the [[ID|unique identifier]] of a specific item is required. This is used when, for example, creating an [[event]] which affects a specific item. Another use can be to uniquely identify an item in user-defined calculations.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| IDs
| The numeric identifier value of an item.
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Grids}} (Only GRID)
* {{inlink|Buildings}}
* {{inlink|Network lines}}
* {{inlink|Measures}}
* {{inlink|Levees}}
* {{inlink|Networks}}
* {{inlink|Stakeholders}}
* {{inlink|Interface}}
* {{inlink|Relations}}
|}
====Names====
Name statements are used to retrieve the human-readable name of an item. This allows [[panel]]s and [[indicator]]s based on [[excel]]s to display the same and appropriate texts throughout the entire project.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| NAME
| The name or human-readable version of a technical name.
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Grids}}
* {{inlink|Buildings}}
* {{inlink|Network lines}}
* {{inlink|Network types}}
* {{inlink|Measures}}
* {{inlink|Levees}}
* {{inlink|Building categories}}
* {{inlink|Timestates}}
* {{inlink|Stakeholders}}
* {{inlink|Interface}}
* {{inlink|Arrays}}
* {{inlink|Indicators}}
* {{inlink|Terms}}
* {{inlink|Map types}}
* {{inlink|Layer types}}
* {{inlink|Multipliers}}
* {{inlink|Transformations}}
* {{inlink|Relations}}
|}
====Active====
Active statements are used to determine whether certain polygons are active or not. The {{software}} will not consider inactive [[area]]s or [[neighborhood]]s in its calculations. Testing whether an item is active or not is often used to exclude those polygons from [[excel]] calculations as well.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| ACTIVE
| Whether the item is active/under consideration (1) or not (0).
|
|rowspan="9"|
* {{inlink|Specific polygons}} (Only AREA and NEIGHBORHOOD)
|}
====Color====
Color statements are used to retrieve the color of specific items. Color's support the [[user]]'s ability to differentiate between pieces of data. These statements allow for [[indicator]]s and [[panel]]s to display the same information with the same colors across the entire project, such as the colors of [[neighborhoods]].
Colors can be retrieved in 2 ways. The color statement will return a hexadecimal value representing the color. It's also possible in most cases to retrieve the color by [[attribute]], using <code>SELECT_ATTRIBUTE_WHERE_NAME_IS_COLOR</code>. In these cases the color is returned as a numeric value. For more information on this value, see the [[attribute#COLOR|attribute]] article.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| COLOR
| The color of an item (hexadecimal value).
|
|rowspan="9"|
* {{inlink|Specific polygons}}
* {{inlink|Buildings}} (BUILDING and FUNCTION)
* {{inlink|Network lines}}
* {{inlink|Building categories}}
* {{inlink|Stakeholders}}
* {{inlink|Interface}} (If a COLOR attribute is present)
|}
====State====
State statements are used to determine what [[timestate]] an item is in, effectively testing at what point in its lifecycle of permission, building, and demolition it currently is. This is mostly used to determine the progression of permissions and buildings; how far buildings plans have progressed in the decision process of [[stakeholder]]s.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| STATE
| What the current timestate is of an item.
|
|rowspan="9"|
* {{inlink|Buildings}} (Excluding FUNCTIONS)
* {{inlink|Network types}}
* {{inlink|Measures}}
* {{inlink|Timestates}}
|}
====Building====
Building statements are used to interact with data inherent to buildings, such as the top floor of buildings. This provides more detailed information on an individual building, and is mostly used for [[zoning]] permission [[excel]]s.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| TOPFLOOR
| The largest amount of floors among sections of a specific building
|
|rowspan="9"|
* {{inlink|Buildings}} (Only BUILDING)
|}
====Network====
Network statements are used to interact with data inherent to networks, such as the length of pipes. This is mostly used for cost- and efficiency calculations related to the extent of a network.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| LENGTH
| The length of [[net line|pipes/lines/cables]] of [[network]]s.
|
|rowspan="9"|
* {{inlink|Network lines}}
* {{inlink|Network types}}
|}
====Stakeholder finances====
Stakeholder finance statements are used to retrieve the financial situation of [[stakeholder]]s.
To affect the stakeholder finances using TQL, it's possible to update the value of a [[global]], which is in turn connected directly to a stakeholder's finance.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| EXPENSES
| The costs incurred by a [[stakeholder]] during a [[session]].
|
|rowspan="9"|
* {{inlink|Stakeholders}}
|-
| REVENUE
| The income of a stakeholder during a session
|
|}
====Indicator====
Indicator statements can be used to interact with properties of [[indicator]]s, allowing [[excel]]s driving indicators to make use of properties of indicators defined in the [[editor]].
These statements mostly facilitate the retrieval of the indicator targets.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| TARGET
| The target set for an [[indicator]].
|
|rowspan="9"|
* {{inlink|Building categories}}
* {{inlink|Interface}} (Only INDICATOR)
* {{inlink|Indicators}}
|}
====Session====
Session statements can be used to retrieve data regarding the [[session]] itself. These don't require any clauses.
{| class="wikitable"
|-
! Query
! Value returned
! Clauses for specific query
! Clauses for entire group
|-
| SESSIONSTATE
| Whether the [[project]] is currently in [[editor]] mode (0), starting a [[session]] (1), or in a session/[[Test Run|test run]] (2).
|
|rowspan="9"|
|-
| TOKEN
| The [[API token]] for this session.
|
|}
===Update statements===
Update statements are a seperate kind of statement, which interact with data in the [[session]] not by reading it from the session but by altering it in the session. Update statements indicate the type of item to update, and the attribute which needs to be updated. Most update statements interact directly with item data, and a specific item must be specified to perform the update on. There are also update statements which do not affect items directly, but which affect that type of item based on whether it meets specific conditions, i.e. clauses.
{| class="wikitable"
|-
! Query
! Item updated
! Clauses
|-
| AREA
| The specific [[area]] indicated by the clause with its ID.
| AREA
|-
| BUILDING
| All buildings which meet the specified clauses.
|
* {{inlink|Specific polygons}}
* {{inlink|Attribute polygons}}
* {{inlink|Buildings}} (Only FUNCTION)
* {{inlink|Timestates}}
* {{inlink|Stakeholders}}
* {{inlink|Map types}}
|-
| ADDRESS
| The specific [[address]] indicated by the clause with its ID.
| ADDRESS
|-
| GLOBAL
| The specific [[global]] with the name indicated by the clause.
|
* {{inlink|Variables}}
|-
| INDICATOR
| The specific [[indicator]] indicated by the clause with its ID.
| INDICATOR
|-
| NEIGHBORHOOD
| The specific [[neighborhood]] indicated by the clause with its ID.
| NEIGHBORHOOD
|-
| NET_LINE
| The specific [[net line]] indicated by the clause with its ID.
| NET_LINE
|-
| NET_FUNCTION
| The specific [[net line definition]] indicated by the clause with its ID.
| NET_FUNCTION
|-
| NET_LOAD
| The specific [[net load]] indicated by the clause with its ID.
| NET_LOAD
|-
| PANEL
| The specific [[panel]] indicated by the clause with its ID.
| PANEL
|-
| ZONE
| The specific [[zone]] indicated by the clause with its ID.
| ZONE
|}


==Clauses==
==Clauses==

Revision as of 13:22, 28 February 2023

TQL is short for Tygron Query Language. It provides a means of obtaining and adjusting data of a session. It is comprised of a number of key phrases, divided into 2 categories: statements and clauses. The statements indicate what data interaction should take place; retrieving using a SELECT statement, or adjusting using an UPDATE statement. The clauses provide a means to filter the data the interaction is applied to. A query always consists of exactly 1 statement and 0 or more clauses.

Interactions can take place with the data in 2 ways: as item data or polygon data. Item data pertains to a specific component of a project, such as individual buildings, indicators, or globals. Polygon data pertains to geographic data; surface areas in the project area, such as the footprint of buildings, the surface area of neighborhoods, or calculated grids. Depending on what kind of statement is used, the query will interact with its clauses treating them as items or as polygons.

An example of a TQL query is SELECT_LOTSIZE_WHERE_CATEGORY_IS_SOCIAL_AND_STAKEHOLDERTYPE_IS_MUNICIPALITY. In this example, SELECT_LOTSIZE is the statement. CATEGORY_IS_SOCIAL is the first clause, and STAKEHOLDERTYPE_IS_MUNICIPALITY is the second clause. It would return all the land area taken up with social housing, which is also owned by a municipal stakeholder.

Note that all clauses in a TQL query are cumulative. All clauses are connected by the term AND. This means all clauses must be met before the data is "counted". Depending on how you use TQL in your project or applications, it is possible to simulate an "OR" functionality as well (i.e. CATEGORY_IS_SOCIAL or CATEGORY_IS_NORMAL). This can be done simply by executing multiple queries, one for each "OR" section.

More examples can be found in the example section.

Usage

TQL can be used in a number of places. The most common place is in the excels of custom indicators or panels. To indicate which cells should contain certain data from the session, cells in an excel file can be given a name. In this case, the name would be a TQL query. When an indicator calculation takes place, the Tygron Platform will obtain all queries that exist in the excel file of the indicator. For the queries with SELECT statements, the results of those queries are obtained and placed in the corresponding cells. when the calculation of the excel is complete, the cells with an UPDATE statement are read out, and the items in the project indicated by those queries are updated with those values.

TQL can also be used to quickly check data in a project. When in editor mode, it's possible to open the query tool. With this tool, queries can be made and directly executed. The result is then presented to the user. This can be especially handy when it's necessary to quickly check whether a certain type of data is present or correctly readable. The query tool also functions both in and out of test runs, allowing a user to also check data in a project during a session.

It's also possible to execute TQL queries directly via the API. The advantage of using TQL, rather than inspecting a project's data via the API directly, is that it can be used to perform calculations that require some intermediate processing. For example, calculating the intersection of buildings with an area or neighborhood. Other examples of this include the queries related to values of grids, or the multiplication of floor size with a related function value.

Clauses

Clauses indicate the conditions which must be met for any data to be taken into account for a statement. In a query, they are connected to the statement using the phrase WHERE. Multiple additonal clauses can be added to a query using the phrase AND. Clauses added to a query are cumulative conditions which must all be met. When, for any data, at least one condition is not met, that data is not taken into account or affected by the query.

Clauses can be broadly grouped into 3 different groups: Common clauses, singular clauses, and modifying clauses. For any given statement, different clauses can be applied from across all these groups. The availability and function of clauses is also influenced by whether the statement dictates an interaction with polygon data or with item data. Some clauses may or may not be available at all, depending on this.

The order in which the clauses appear in the query is not relevant.

Common clauses

Common clauses are clauses which can be used by multiple statements and are commonly required.

Specific polygons

Clause As a polygon As an item Type
AREA It must intersect with this area. It must be data of this area specifically. ID indicating a specific area.
NEIGHBORHOOD It must intersect with this neighborhood. It must be data of this neighborhood specifically. ID indicating a specific neighborhood.
ZONE It must intersect with this zone. It must be data of this zone specifically. ID indicating a specific zone.
TERRAIN It must intersect with this terrain type. It must be data of this type of terrain. There are no specific "instances" of terrain. ID indicating a type of terrain.

Attribute polygons

Clause As a polygon As an item Type
AREA_WITH_ATTRIBUTE It must intersect with at least one area with this attribute. N/A Attribute name of one or more areas.
NEIGHBORHOOD_WITH_ATTRIBUTE It must intersect with at least one neighborhood with this attribute. N/A Attribute name of one or more neighborhoods.
ZONE_WITH_ATTRIBUTE It must intersect with at least one zone with this attribute. N/A Attribute name of one or more zones.
TERRAIN_WITH_ATTRIBUTE It must intersect with terrain with this attribute. N/A Attribute name of one or more terrains.

Only Items with the specified Attribute with a non-zero value will be used to select data.

If multiple distinct Items qualify but overlap over selected data, the selected data is counted multiple times. For example, when using SELECT_LOTSIZE_WHERE_AREA_WITH_ATTRIBUTE, and two relevant Areas overlap with a Buildings, the Building's lotsize is counted twive.

Grids

Clause As a polygon As an item Type
MAXGRIDVALUE It must intersect with at most this value on a grid overlay (exclusive). N/A Decimal number.
MINGRIDVALUE It must intersect with at least this value on a grid overlay (inclusive). N/A Decimal number.
GRID It must fall within this grid. It must be data of this Grid Overlay specifically. ID indicating a specific Grid Overlay.
GRIDVALUE It must must have this exact value on a Grid Overlay N/A Decimal number.
TIMEFRAME The grid data being considered must be data from this timeframe of the grid specifically. N/A Integer specifying the timeframe to use.
GRID_WITH_ATTRIBUTE It must fall specifically within the Grid Overlay which has this attribute. N/A Attribute name of an attribute of a Grid Overlay

The counting/naming of timeframes begins at 0. The first timeframe is "0", the second timeframe is "1", etc. If a grid has 20 timeframes, the last timeframe is "19". If the specified timeframe does not exist, or no timeframe is specified, the last timeframe of the grid is used. If a grid overlay does not have results in the form of multiple timeframes, the overlay is considered to have exactly 1 timeframe.

When using GRID_WITH_ATTRIBUTE, there may not be any ambiguity. I.e. only one Grid Overlay may have the indicated Attribute.

Note that each grid automatically covers the entire map, unless a minimum gridvalue or maximum gridvalue is defined. For queries such as GRIDAVG, this can be acceptable. However, for example, a query of SELECT_LANDSIZE_WHERE_GRID_IS_2 is functionally the same as SELECT_LANDSIZE.

Also note that the GRIDVALUE clause requires an exact numerical match, making it appropriate only for situations where the grid can be expected to contain exact values, ideally integer values. Examples include the Distance Zone Overlay with the "Count hit" setting enabled, the Water Overlay with the IMPACTED_BUILDINGS result type, or the Average Overlay.

Buildings

Clause As a polygon As an item Type
BUILDING It must intersect with this building. It must be data of this building specifically. ID indicating a specific building.
NET_LOAD It must intersect with the building of this net load. It must be data of this net load specifically. ID indicating a specific net load.
NET_CLUSTER It must intersect with buildings of net loads of this net cluster. It must be data of this net cluster specifically. ID indicating a specific net cluster.
FUNCTION It must intersect with buildings of this function. It must be data related to this function type. ID indicating a specific function.
RESIDENCE It must intersect with buildings that contain residences. It must be data related to buildings that contain residences. Boolean indicating it contains any residence.
ROAD_SYSTEM It must intersect with buildings that belong to the road system. It must be data related to buildings that belong to the road system. Boolean indicating it belongs to the road system.

Network lines

Clause As a polygon As an item Type
NET_LINE N/A It must be data of this net line specifically. ID indicating a specific net line.
NET_FUNCTION N/A It must be data of net lines of this definition. ID indicating a line definition.

Network types

Clause As a polygon As an item Type
NET_TYPE N/A It must be data of this type of network. ID indicating the type of network.

For statements such as NAME, the network type itself is queried. For statements such as STATE or LOTSIZE, only items which are part of that network are taken into consideration. For example the net loads in a net cluster of only a specific network type, while more loads of other network types may exist in that same cluster.

Measures

Clause As a polygon As an item Type
MEASURE N/A It must be data of this Measure specifically. ID indicating a specific Measure.

Levees

Clause As a polygon As an item Type
LEVEE It must intersect with this levee. It must be data of this levee specifically. ID indicating a specific levee.

Building categories

Clause As a polygon As an item Type
CATEGORY It must intersect with buildings of this category. It must be related to this specific category. Technical name indicating a category.

Timestates

Clause As a polygon As an item Type
STATE It must intersect with buildings or other spatial actions, which are currently in this timestate. It must be related to this specific timestate. Technical name indicating a timestate.

Attributes

Clause As a polygon As an item Type
ATTRIBUTE_MAX Included polygonal items in the results must have an attribute value less than this value. N/A Decimal number.
ATTRIBUTE_MIN Included polygonal items in the results must have an attribute value greater than this value. N/A Decimal number.
ATTRIBUTE The attribute of which to test the value. N/A Attribute name of any polygonal item.

When neither a maximum or minimum value is specified, or when no attribute is specified, everything is taken into consideration.

Stakeholders

Clause As a polygon As an item Type
STAKEHOLDER The land must be owned by this specific stakeholder. It must be data of this stakeholder specifically. ID indicating a specific stakeholder.
STAKEHOLDERTYPE The land must be owned by this type of stakeholder. N/A Technical name indicating a type of stakeholder.

Interface

Clause As a polygon As an item Type
INDICATOR N/A It must be data of this indicator specifically. ID indicating a specific indicator.
OVERLAY N/A It must be data of this overlay specifically. ID indicating a specific overlay.
PANEL N/A It must be data of this panel specifically. ID indicating a specific panel.

Singular clauses

Singular clauses are clauses which are not used as often, which are only used by specific statements, or only in specific use-cases.

Variables

Clause As a polygon As an item Type
NAME N/A The data requested must have this name. The name which identifies the requested data.

Arrays

Clause As a polygon As an item Type
INDEX N/A Of the array of data specified, get specifically the data in the indicated index in the array. The index of the requested data in the specified array.

Arrays are 0-indexed. I.e., the first value is stored at index 0. If an index is requested which does not exist, "0" is returned. Queries on arrays without an INDEX query return the value at index 0.

Indicators

Clause As a polygon As an item Type
INDICATORTYPE N/A It must be related to this type of indicator. Technical name indicating a type of indicator.

Terms

Clause As a polygon As an item Type
STATE N/A It must be related to this specific text (or "term") used by the Tygron Platform. Technical name indicating a term.


Modifying clauses

Modyfing clauses are clauses which, in some fashion, modify the way the query functions, either in some way changing what data is being requests (as opposed to how other clauses merely filter data), or by performing some further operation on the resulting data.

Map types

Clause As a polygon As an item Type
MAP It must be data from this moment of time in a session. It must be data from this moment of time in a session. Technical name of the original/current state or the planned/maquette state.

The precise terms vary based on the simulation type, but the terms which appear in the query are CURRENT and MAQUETTE.

Layer types

Clause As a polygon As an item Type
LAYERTYPE It must be data from this layer. N/A Technical name of the surface or underground layers.

The precise terms are SURFACE and UNDERGROUND.

Multipliers

Clause As a polygon As an item Type
ATTRIBUTE_MULT Multiply the result by the (spatial) value of an attribute. N/A Attribute name of any polygonal item.
FUNCTIONMULT Multiply the result by the (spatial) value of an attribute. N/A The name of a function value.
CATEGORYMULT Multiply the result by the (spatial) value of an attribute. N/A The name of a category value.

Transformations

Clause As a polygon As an item Type
BUFFER N/A Expand the valid polygon(s) used to select data Size of the buffer

When a polygon clause (consisting of specific polygons, attribute polygons, or grid clauses, which behaves comparably for this purpose) is used, the "selection polygon" defined by those clauses is buffered before determining what valid data falls in the selection polygon.

There is a more in-depth example on how to use the BUFFER clause in the how to's section.

Relations

Relation is a TQL Clause Parameter that can basically switch the subject of a TQL request to an other one related to the original subject.

Clause As a polygon As an item Type
RELATION N/A Rather than requesting data from the specified item, use the item which has this relation to it. Technical name indicating a type of relation.

Examples for common use-cases

A number of use-cases come up frequently across various projects. Queries of the following forms often provide a firm basis for using TQL to obtain required data.

Function values (selecting)

Parking requirements of social housing

The parking demand is based on a function value of each function, and is defined as "parking places per m2". Parking demand is not based on the footprint of a building, but the size of a building. i.e. a building 4 floors high needs more parking than a building with the same footprint 2 floors high.

SELECT_FLOORSIZE_WHERE_CATEGORY_IS_SOCIAL_AND_CATEGORYMULT_IS_PARKING_LOTS_DEMAND_PER_M2

  • SELECT_FLOORSIZE: What we are basically looking for is the floorsize of the building.
  • CATEGORY_IS_SOCIAL: We only want to look at buildings which are of the category social housing. For that, a category clause is added.
  • CATEGORYMULT_IS_PARKING_LOTS_DEMAND_PER_M2: Lastly, we are not looking directly for the floorsize, but for the parking demand as a result of that floorsize.

Function values (updating)

Traffic intensity on roads

The traffic intensity is a function value which affects calculations related to traffic. Some use-cases require these values to be updated dynamically. This can be done per neighborhood. (In this example, the neighborhood in question has the ID 1.)

UPDATE_BUILDING_TRAFFIC_FLOW_WHERE_CATEGORY_IS_ROAD_AND_NEIGHBORHOOD_IS_1

  • UPDATE_BUILDING: We're changing an attribute of a building.
  • TRAFFIC_FLOW: The attribute we are changing is the TRAFFIC_FLOW, which is the technical name of a function value.
  • CATEGORY_IS_ROAD: We only want to update this value on roads.
  • NEIGHBORHOOD_IS_1: We are updating only in this specific neighborhood. Nothing outside the neighborhood is updated by this statement.

Grid average

Quality of livability in a neighborhood

The livability overlay calculates, for each grid cell, the average livability. The best indication of how well a certain region performs in terms of livability would be to average these values out. That way, its possible to compare places which are not the same size. (In this example, the neighborhood in question has the ID 1, and the grid of livability has the ID 4.)

SELECT_GRIDAVG_WHERE_NEIGHBORHOOD_IS_1_AND_GRID_IS_4

For any given neighborhood, different points of a grid may score differently.

  • SELECT_GRIDAVG: We're looking for the average score across the entire neighborhood.
  • NEIGHBORHOOD_IS_1: We don't need the average of the entire map, but only of a specific neighborhood.
  • GRID_IS_4: We need to specify the grid we wish to use the values of.

Grid values

The area of open water which is flooded by more than 20 cm of water

The rainfall overlay calculates what amounts of water ends up where. The overlay's results are in meters. If we wish to provide some minimum value, it must be in meters as well. 20 cm is 0,2 meters. The project can also contain multiple types of water. All types of have one thing in common, namely that they all have the WATER attribute, which can be tested against. (In this example, the grid of inundation has the ID 4, and has its result type set to water stress.)

SELECT_LANDSIZE_WHERE_MINGRIDVALUE_IS_0.2_AND_GRID_IS_4_AND_TERRAIN_WITH_ATTRIBUTE_IS_WATER

  • SELECT_LANDSIZE: The end result must be some area; some amount of square meters.
  • MINGRIDVALUE_IS_0.2: We only want to count the area where the value calculated is at least 0.2 (meters).
  • GRID_IS_4: We need to specify the grid we wish to use the values of.
  • TERRAIN_WITH_ATTRIBUTE_IS_WATER: We are only looking for the water which ends up on water, identified by the "WATER" attribute.

Buffers

The amount of green in or near a neighborhood

Green buildings can be found by their green function value. The value is the amount of green in square meters, per square meter of building. Green can be in a neighborhood, but can also be within a certain range near a neighborhood (say, 20 meters) and still have an effective presence.

SELECT_LOTSIZE_WHERE_NEIGHBORHOOD_IS_1_AND_BUFFER_IS_20.0_AND_FUNCTIONMULT_IS_GREEN_M2

  • SELECT_LOTSIZE: The end result must be area taken up by buildings; some amount in square meters.
  • NEIGHBORHOOD_IS_1: We want the greenery in a particular neighborhood.
  • BUFFER_IS_20.0: We don't just want to look at buildings in the neighborhood itself, but also buildings within 20 meters of the neighborhood
  • FUNCTIONMULT_IS_GREEN_M2:The end result must be multiplied by the green value of the respective buildings found.

How-to's

See also

Video's

Information about Residents and Energylabels in the Tygron Platform. (In dutch)
Retrieved from "https://previewsupport.tygron.com/w/index.php?title=Tygron_Query_Language&oldid=53654"