TQL
TQL is short for Tygron Query Language. It provides a means of interacting with the data in a session from excel. It is comprised of a numer of key phrases, devided into 2 categories: statements and clauses. The statements indicate what interaction should take place. The clauses provide conditions which must be met for the interaction to take place.
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 constructions, indicators, or globals. Polygon data pertains to geographic data; surface areas in the 3D world. Such as the footprint of constructions, 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.
Usage
TQL can be used in a number of situations. The most common situation where using TQL is required is when creating custom indicators or panels, using excel. To indicate which cells should contain certain data from the session, cells in an excel file can be named. The name would be a TQL query. When a calculation is to take place, the engine will place the data as described by the TQL query in that cell. Likewise, at the end of the calculation, all cells with a name which indicates data in the engine should be updated are read out, and the data indicated by the TQL query is updated with that 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 SELECT or UPDATE. SELECT statements retrieve data from a session. UPDATE 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 statements interact with data as polygon data. This means that, depending on the clauses added to the query, they generally see how much surface area in the world 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.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| LANDSIZE
|
Amount of surface area. (m2)
|
|
|
| DIKES
|
The amount of surface area taken up by dikes. (m2)
|
|
Construction polygons
Construction polygon statements relate to surface area in use by constructions. These are mostly used for determining the amount of certain types of constructions, and their cumulative values.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| LOTSIZE
|
Amount of surface area used by a construction. (m2)
|
|
|
| FLOORSIZE
|
The amount of floorspace, based on constructions' lotsize and their amount of floors. (m2)
|
|
| UNITS
|
The amount of housing units, based on construction's lotsize 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 overlays. These are used to retrieve calculated effects of built-in spatial calculation models.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| GRIDAVG
|
The average value of a grid.
|
|
|
| GRIDSTDEV
|
The standard deviation of a grid.
|
|
| GRIDSVOLUME
|
The surface area multiplied by the average grid value on that surface.
|
|
| HEIGHT
|
The average height of the terrain. (mNAP)
|
- Grids (Including the value clauses)
|
Item statements
These statements interact with data as item data. This means that, depending on the clauses added to the query, they retrieve a specific property of 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 attributes and globals, 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 overlays, and as parameters in user-ceated excel files for indicators and panels.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| ATTRIBUTE
|
The numeric attribute value of an item.
|
|
|
| GLOBAL
|
The value of a global variable
|
|
IDs
ID statements are used when the identification number 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.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| IDs
|
The numeric identifier value of an item.
|
|
|
Names
Name statements are used to retrieve the human-readable name of an item. This allows panels and indicators based on excels to display the same and appropriate texts throughout the entire project.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| NAME
|
The name or human-readable version of a technical name.
|
|
|
Active
Active statements are used to determine whether certain polygons are active or not. The engine will not consider inactive areas or neighborhoods in its calculations. Testing whether an item is active or not is often used to exclude those polygons from excel calculations as well.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| ACTIVE
|
Whether the item is active/under consideration (1) or not (0).
|
|
|
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 indicators andpanels to display the same information with the same colors across the entire project, such as the colors of neighborhoods.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| COLOR
|
The color of an item (hexadecimal value).
|
|
|
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 SELECT_ATTRIBUTE_WHERE_NAME_IS_COLOR. In these cases the color is returned as a numeric value. For more information on this value, see the attribute article.
State
State statements are used to determine what timestate an item is in, effectively testing at what point in its lifecycle of permission, construction, and demolition it currently is. This is mostly used to determine the progression of permissions and constructions; how far construction plans have progressed in the decision process of stakeholders.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| STATE
|
What the current timestate is of an item.
|
|
|
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.
Stakeholder finances
Stakeholder finance statements are used to retrieve the financial situation of stakeholders.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| EXPENSES
|
The costs incurred by a stakeholder during a session.
|
|
|
| REVENUE
|
The income of a stakeholder during a session
|
|
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.
Indicator
Indicator statements can be used to interact with properties of indicators, allowing excels driving indicators to make use of properties of indicators defined in the editor.
| Query
|
Value returned
|
Clauses for specific query
|
Clauses for entire group
|
| TARGET
|
The target set for an indicator.
|
|
|
These statements mostly facilitate the retrieval of the indicator targets.
Session
Session statements can be used to retrieve data regarding the session itself. These don't require any clauses.
| 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/testrun (2).
|
|
|
| TOKEN
|
The API token for this session.
|
|
Clauses
The following groups of clauses exist:
Main clause groups
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.
|
Grids
| Clause
|
As a polygon
|
As an item
|
Type
|
| MAXGRIDVALUE
|
It must intersect with at least this value on a grid overlay.
|
N/A
|
Decimal number.
|
| MINGRIDVALUE
|
It must intersect with at most this value on a grid overlay.
|
N/A
|
Decimal number.
|
| GRID
|
It must fall within this grid.
|
It must be data of this grid overlay specifically.
|
ID indicating a specific zone.
|
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 when a GRIDTYPE is selected but multiple overlays of that type exist in the project, there are no guarantees on which overlay is used specifically.
Constructions
| Clause
|
As a polygon
|
As an item
|
Type
|
| BUILDING
|
It must intersect with this construction.
|
It must be data of this construction specifically.
|
ID indicating a specific construction.
|
| 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 constructions of this function.
|
It must be data related to this function type.
|
ID indicating a specific function.
|
Dikes
| Clause
|
As a polygon
|
As an item
|
Type
|
| DIKE
|
It must intersect with this dike.
|
It must be data of this dike specifically.
|
ID indicating a specific dike.
|
Building categories
| Clause
|
As a polygon
|
As an item
|
Type
|
| CATEGORY
|
It must intersect with constructions 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
|
It must intersect with at least this value of an attribute.
|
N/A
|
Decimal number.
|
| ATTRIBUTE_MIN
|
It must intersect with at most this value of an attribute.
|
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 considered
Networks
| 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_LINE_DEFINITION
|
N/A
|
It must be data of net lines of this definition.
|
ID indicating a line definition.
|
| NET_TYPE
|
N/A
|
It must be data of net lines of this type of network.
|
ID indicating the type of network.
|
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.
|
Minor clause groups
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.
|
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 Engine.
|
Technical name indicating a term.
|
Modifying clause groups
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 of the 3D world.
|
N/A
|
Technical name of the surface or underground layers of the 3D world.
|
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.
|
Relations
| Clause
|
As a polygon
|
As an item
|
Type
|
| RELATION
|
N/A
|
Rather than data of the specified item, use the item which has this relation to it.
|
Technical name indicating a type of relation.
|
