|
|
| (215 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| {{stub}}
| | 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, that can be divided into 2 categories: statements and clauses. The statements indicate what data interaction should take place; retrieving using a [[Select (TQL)|<code>SELECT</code>]] statement, or adjusting using an [[Update (TQL)|<code>UPDATE</code>]] 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. Each clause always consists of a [[Clause (TQL)|Clause parameter]] and a value. |
|
| |
|
| ==TQL==
| | TQL can access both property data from individual items, as well as spatial information. Property data pertains to a specific component of a [[project]], such as individual [[building]]s, [[indicator]]s, or [[global]]s. Polygon data pertains to geographic data; surface areas in the [[project area]], such as the lot size of [[building]]s, the surface area of [[neighborhood]]s, or calculated [[grid overlay|grid]]s. Depending on what kind of statement is used, the query will interact with its clauses treating them as items or as polygons. |
| 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 [[construction]]s, [[indicator]]s, or [[global]]s. Polygon data pertains to geographic data; surface areas in the [[3D world]]. Such as the footprint of [[construction]]s, the surface area of [[neighborhood]]s, or calculated [[grid overlays| 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: |
| | : <code>SELECT_LOTSIZE_WHERE_CATEGORY_IS_SOCIAL_AND_STAKEHOLDERTYPE_IS_MUNICIPALITY</code>. |
|
| |
|
| ==Usage==
| |
| TQL can be used in a number of situations. The most common situation where using TQL is required is when creating custom [[indicator]]s or [[panel]]s, 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.
| |
|
| |
|
| 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 its neccesary to quickly check whether a certain type of data is present or correctly readable. The query tool also functions both in and out of [[testrun]]s, allowing a user to also check data in a [[project]] during a session.
| | In this example, <code>SELECT_LOTSIZE</code> is the statement. <code>CATEGORY_IS_SOCIAL</code> is the first clause, and <code>STAKEHOLDERTYPE_IS_MUNICIPALITY</code> is the second clause. It would return all the land area taken up with social housing, which is also owned by a municipal stakeholder. |
|
| |
|
| It's also possible to execute TQL queries directly via the [[API]]. Although in most situations it's more effective to inspect data via the API directly, or to use events via the API directly, there are some TQL queries possible which perform some intermediate processing. Examples of this include the queries related to values of [[grid overlay|grid]]s, or the multiplication of floor size with a related [[function value]].
| | Note that all clauses in a TQL query are cumulative. All clauses are connected by the term <code>AND</code>. 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 (e.g. <code>CATEGORY_IS_SOCIAL</code> ''or'' <code>CATEGORY_IS_NORMAL</code>). This can be done simply by executing multiple queries, one for each "OR" section. |
|
| |
|
| ==Statements==
| | More examples can be found at [[TQL Examples]]. |
| 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=== | | ==TQL components== |
| 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.
| | TQL queries are composed of 2 major elements: the [[#Statements|statement]], and the [[Clause (TQL)|clauses]]. Together they may make up a single query. |
|
| |
|
| ====Land polygons==== | | ===Statements=== |
| 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.
| | Statements are the instruction which is to be performed with the [[Project]]. A query always has exactly one statement. |
|
| |
|
| {| class="wikitable"
| | There are 2 kinds of [[TQL]] Statements: |
| |- | | * [[Select (TQL)|Select statement]]s, for data retrieval from [[Item]]s in a [[Project]] |
| ! Query
| | * [[Update (TQL)|Update statement]]s, for writing data (back) into the [[Project]] and its [[Item]]s |
| ! Value returned
| |
| ! Clauses for specific query
| |
| ! Clauses for entire group
| |
| |-
| |
| | LANDSIZE
| |
| | Amount of surface area. (m2)
| |
| | | |
| * {{inlink|Grids}}
| |
| |rowspan="9"|
| |
| * {{inlink|Specific polygons}}
| |
| * {{inlink|Attribute polygons}}
| |
| * {{inlink|Stakeholders}}
| |
| * {{inlink|Map types}}
| |
| |-
| |
| | DIKES
| |
| | The amount of surface area taken up by dikes. (m2)
| |
| |
| |
| * {{inlink|Dikes}}
| |
| * {{inlink|Timestates}}
| |
| |}
| |
|
| |
|
| ====Construction polygons==== | | ===Clauses=== |
| Construction polygon statements relate to surface area in use by [[construction]]s. These are mostly used for determining the amount of certain types of constructions, and their cumulative values.
| | {{main|Clause (TQL)}} |
| {| class="wikitable" | | 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 <code>WHERE</code>. Multiple additional clauses can be added to a query using the phrase <code>AND</code>. 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. |
| |-
| |
| ! Query
| |
| ! Value returned
| |
| ! Clauses for specific query
| |
| ! Clauses for entire group
| |
| |-
| |
| | LOTSIZE
| |
| | Amount of surface area used by a [[construction]]. (m2)
| |
| |
| |
| |rowspan="9"|
| |
| * {{inlink|Specific polygons}}
| |
| * {{inlink|Attribute polygons}}
| |
| * {{inlink|Grids}}
| |
| * {{inlink|Constructions}}
| |
| * {{inlink|Dikes}}
| |
| * {{inlink|Building categories}}
| |
| * {{inlink|Timestates}}
| |
| * {{inlink|Attributes}}
| |
| * {{inlink|Stakeholders}}
| |
| * {{inlink|Relations}}
| |
| * {{inlink|Layer types}}
| |
| * {{inlink|Map types}}
| |
| * {{inlink|Multipliers}}
| |
| |-
| |
| | 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====
| | For any given [[Select (TQL)]] or [[Update (TQL)]] 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. |
| 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]].
| |
| |
| |
| |rowspan="9"|
| |
| * {{inlink|Specific polygons}}
| |
| * {{inlink|Attribute polygons}}
| |
| * {{inlink|Grids}} (Excluding the value clauses)
| |
| * {{inlink|Map types}}
| |
| |-
| |
| | 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)
| |
| |
| |
| * {{inlink|Grids}} (Including the value clauses)
| |
| |}
| |
|
| |
|
| ===Item statements===
| | The order in which the clauses appear in the query is not relevant. |
| 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====
| | For a full list of available clauses, see [[Clause (TQL)]]. |
| 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|Constructions}}
| |
| * {{inlink|Network}}
| |
| * {{inlink|Interface}}
| |
| * {{inlink|Relations}}
| |
| * {{inlink|Map types}}
| |
| |rowspan="9"|
| |
| * {{inlink|Variables}}
| |
| |-
| |
| | GLOBAL
| |
| | The value of a [[global]] variable
| |
| |
| |
| |}
| |
|
| |
|
| ====IDs==== | | ====Limiting Search Polygon==== |
| 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.
| | Some clause parameters described on this wiki note that they ''Limit the Search Polygon''. The Search Polygon is the geometry created from the specified clauses that will limit the buildings that will be considered when executing the statement. For example <code>SELECT_LOTSIZE_WHERE_AREA_WITH_ATTRIBUTE_SPECIAL_CASE_AND_CATEGORY_IS_SOCIAL</code> will create a search polygon for buildings based on the areas that have the attribute <code>SPECIAL_CASE</code>. The [[Area with attribute (TQL Param)]] is a search polygon limiter. |
| {| 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|Constructions}}
| |
| * {{inlink|Dikes}}
| |
| * {{inlink|Networks}}
| |
| * {{inlink|Stakeholders}}
| |
| * {{inlink|Interface}}
| |
| * {{inlink|Relations}}
| |
| |}
| |
|
| |
|
| ====Names====
| | It will also have effect when executing the statement: <code>SELECT_LANDSIZE_WHERE_NEIGHBORHOOD_IS_2_AND_AREA_WITH_ATTRIBUTE_SPECIAL_CASE</code>, where together with the [[Neighborhood (TQL Param)]] they limit the search polygon to the intersection of the Neighborhood with Item ID 2 and areas with an attribute <code>SPECIAL_CASE</code>. Ultimately, the statement returns the landsize of the limiting search polygon. |
| 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|Constructions}}
| |
| * {{inlink|Dikes}}
| |
| * {{inlink|Building categories}}
| |
| * {{inlink|Timestates}}
| |
| * {{inlink|Networks}}
| |
| * {{inlink|Stakeholders}}
| |
| * {{inlink|Interface}}
| |
| * {{inlink|Indicators}}
| |
| * {{inlink|Terms}}
| |
| * {{inlink|Layer types}}
| |
| * {{inlink|Map types}}
| |
| * {{inlink|Multipliers}}
| |
| |}
| |
| | |
| ====Active====
| |
| Active statements are used to determine whether certain polygons are active or not. The engine 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]].
| |
| {| 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|Constructions}}
| |
| * {{inlink|Stakeholders}}
| |
| |}
| |
| 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.
| |
| | |
| ====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 [[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|Constructions}} (Excluding FUNCTIONS)
| |
| * {{inlink|Timestates}}
| |
| |}
| |
| | |
| ====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|Networks}}
| |
| |}
| |
| | |
| ====Stakeholder finances====
| |
| Stakeholder finance statements are used to retrieve the financial situation of [[stakeholder]]s.
| |
| {| 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
| |
| |
| |
| |}
| |
| 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 [[indicator]]s, allowing [[excel]]s driving indicators to make use of properties of indicators defined in the [[editor]].
| |
| {| 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}}
| |
| |}
| |
| 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.
| |
| {| 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/[[testrun]] (2).
| |
| |
| |
| |rowspan="9"|
| |
| |-
| |
| | TOKEN
| |
| | The [[API token]] for this session.
| |
| |
| |
| |}
| |
| | |
| ==Clauses==
| |
| The following groups of clauses exist:
| |
| | |
| ===Main clause groups===
| |
| | |
| ====Specific polygons====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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.
| |
| <!--|-
| |
| | GRIDTYPE
| |
| | It must fall within this type of grid.
| |
| | It must be data of this type of grid, not a specific "instance" of this grid.
| |
| | Technical name indicating a type of grid overlay.-->
| |
| |}
| |
| | |
| 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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 load]]s 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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 line]]s of this [[net line definition|definition]].
| |
| | ID indicating a line definition.
| |
| |-
| |
| | NET_TYPE
| |
| | N/A
| |
| | It must be data of [[net line]]s of this type of [[net type|network]].
| |
| | ID indicating the type of network.
| |
| |}
| |
| | |
| ====Stakeholders====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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.
| |
| |}
| |
|
| |
|
| | ==Usage== |
| | TQL can be used in a number of places. The most common place is in the [[excel]]s of custom [[indicator]]s, [[panel]] or [[global]]s. 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 {{software}} will obtain all queries that exist in the excel file of the indicator. For the queries with <code>SELECT</code> 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 <code>UPDATE</code> statement are read out, and the items in the project indicated by those queries are updated with those values. |
|
| |
|
| ===Modifying clause groups===
| | 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 Run|test runs]], allowing a user to also check data in a [[project]] during a session. |
|
| |
|
| ====Map types====
| | 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]]. |
| {| class="wikitable"
| |
| |-
| |
| ! Clause
| |
| ! As a polygon
| |
| ! As an item
| |
| ! Type
| |
| |-
| |
| | MAP
| |
| | It must be data from this [[maptype|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====
| | {{article end |
| {| class="wikitable"
| | |seealso= |
| |-
| | * [[Excel indicator]]s, [[Panel]]s and [[Global]]s |
| ! Clause
| | * [[Select (TQL)]], [[Update (TQL)]] and [[Clause (TQL)]] |
| ! As a polygon
| | * [[Query tool]] |
| ! As an item
| | |howtos= |
| ! Type
| | * [[How to use buffers (TQL)]] |
| |- | | * [[TQL Examples]] |
| | LAYERTYPE
| | |videos= |
| | It must be data from this layer of the [[3D world]].
| | {{video|link=https://youtu.be/6D29CclkWQ4|description=Information about Residents and Energylabels in the {{software}}.|language=dutch}} |
| | N/A | | }} |
| | Technical name of the surface or underground layers of the 3D world. | |
| |} | |
| The precise terms are SURFACE and UNDERGROUND.
| |
|
| |
|
| ====Multipliers====
| |
| {| class="wikitable"
| |
| |-
| |
| ! 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====
| | {{TQL nav}} |
| {| class="wikitable" | |
| |-
| |
| ! 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.
| |
| |}
| |
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, that can be 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. Each clause always consists of a Clause parameter and a value.
TQL can access both property data from individual items, as well as spatial information. Property 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 lot size 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 (e.g. 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 at TQL Examples.
TQL components
TQL queries are composed of 2 major elements: the statement, and the clauses. Together they may make up a single query.
Statements
Statements are the instruction which is to be performed with the Project. A query always has exactly one statement.
There are 2 kinds of TQL Statements:
Clauses
- Main article: Clause (TQL)
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 additional 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.
For any given Select (TQL) or Update (TQL) 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.
For a full list of available clauses, see Clause (TQL).
Limiting Search Polygon
Some clause parameters described on this wiki note that they Limit the Search Polygon. The Search Polygon is the geometry created from the specified clauses that will limit the buildings that will be considered when executing the statement. For example SELECT_LOTSIZE_WHERE_AREA_WITH_ATTRIBUTE_SPECIAL_CASE_AND_CATEGORY_IS_SOCIAL will create a search polygon for buildings based on the areas that have the attribute SPECIAL_CASE. The Area with attribute (TQL Param) is a search polygon limiter.
It will also have effect when executing the statement: SELECT_LANDSIZE_WHERE_NEIGHBORHOOD_IS_2_AND_AREA_WITH_ATTRIBUTE_SPECIAL_CASE, where together with the Neighborhood (TQL Param) they limit the search polygon to the intersection of the Neighborhood with Item ID 2 and areas with an attribute SPECIAL_CASE. Ultimately, the statement returns the landsize of the limiting search polygon.
Usage
TQL can be used in a number of places. The most common place is in the excels of custom indicators, panel or globals. 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.
How-to's
Videos
Information about Residents and Energylabels in the Tygron Platform. (In dutch)
See also
