TQL: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
m (Replaced content with "#REDIRECT Tygron Query Language")
 
(21 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{learned|file=TQL-Logo-v2-Q3-2015.jpg|what the Tygron Query Language (TQL) is|how to create TQL queries|what type of queries you can create|what TQL is currently applied for}}
#REDIRECT [[Tygron Query Language]]
 
==TQL==
The Tygron Query Language is a special-purpose programming language designed for obtaining spatial area information during a specific project session in the Tygron Engine. The primary reason for its introduction was to bridge the gap between the Tygron Engine and the implementation of Microsoft Excel spreadsheets.
 
==Queries==
The main operation used in TQL is the query, which is performed with the declarative <code>SELECT</code> statement or <code>UPDATE</code> statement. A '''declarative''' statement tells the system which data is specifically required, after which the system will retrieve the data on it's 'own'. This is contrary to an '''imperative''' statement, where the system is told 'how' to obtain said data. A <code>SELECT</code> statement retrieves data from a running Tygron project session. A <code>UPDATE</code> statement changes data from a running Tygron project session. Queries using <code>SELECT</code> statements have no persistent effect on the project session itself. Queries using the <code>UPDATE</code> statement do have an effect om the project session itself. The <code>UPDATE</code> statement is used in the Excel indicator calculations and the outcome of the calculation is redirected as output to update the key figures in the project.
 
Queries in TQL using the <code>SELECT</code> statement allow the user to describe the desired data, leaving the Tygron Engine responsible for planning, optimizing, and performing the physical operations necessary to produce the desired result as output.
Queries in TQL using the <code>UPDATE</code> statement allow the user to describe the desired data, leaving the Tygron Engine responsible for calculating the before the update situation and give it back as output to the Tygron Engine after executing the desired adjustment in the project.
 
When starting a query with the <code>SELECT</code> statement, a result parameter must follow after the <code>SELECT</code> keyword. Currently, one of the following result parameters can be selected:
{| class="wikitable"
|-
! Result Parameter
! Description
! Example
|-
| <code>FLOORSIZE</code>
| Floor size of buildings.
| <code>SELECT_FLOORSIZE_WHERE_CATEGORY_IS_OFFICES</code>
|-
| <code>LOTSIZE</code>
| Lot size of buildings.
| <code>SELECT_LOTSIZE_WHERE_CATEGORY_IS_OFFICES</code>
|-
| <code>UNITS</code>
| Amount of housing units.
| <code>SELECT_UNITS_WHERE_CATEGORY_IS_SOCIAL</code>
|-
| <code>LANDSIZE</code>
| Amount of surface area.
| <code>SELECT_LANDSIZE_WHERE_BEHAVIOR_IS_GRASSLAND</code>
|-
| <code>DIKES</code>
| Surface space of constructed dikes or levees.
| <code>SELECT_DIKES_WHERE_ZONE_IS_1</code>
|-
| <code>ACTIVE</code>
| Useful for Excel Indicators
| <code>SELECT_ACTIVE_WHERE_ZONE_IS_1</code>
|-
| <code>NAME</code>*
| Name of selection as query result
| <code>SELECT_NAME_WHERE_CATEGORYMULT_IS_SELL_PRICE_M2</code>
|-
| <code>COLOR</code>*
| Color of selection as query result
| <code>SELECT_COLOR_WHERE_FUNCTION_IS_816</code>
|-
| <code>GRID_AVG</code>
| Average grid value per grid point
| <code>SELECT_GRIDAVG_WHERE_GRIDTYPE_IS_TRAFFIC_NOISE</code>
|}
''* can be followed by one clause maximum''
 
When starting a query with the <code>UPDATE</code> statement, the result parameter is predefined in the statement. One of the following result parameters can be selected:
{| class="wikitable"
|-
! Result Parameter
! Description
! Example
|-
| <code>UPDATE_AREA</code>
| Update the area attribute.
| <code>UPDATE_AREA_COLOR_WHERE_AREA_IS_0</code>
|-
| <code>UPDATE_BUILDING</code>
| Update the building attribute.
| <code>UPDATE_BUILDING_TRAFFIC_FLOW_WHERE_BUILDING_IS_64</code>
|-
| <code>UPDATE_GLOBAL</code>
| Update the value of the global.
| <code>UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_COSTS_WATER_SYSTEM</code>
|-
| <code>UPDATE_NEIGHBORHOOD</code>
| Update the neighborhood attribute.
| <code>UPDATE_NEIGHBORHOOD_COLOR_WHERE_NEIGHBORHOOD_IS_3</code>
|-
| <code>UPDATE_PANEL</code>
| Update the visual panel.
| <code>UPDATE_PANEL_VISIBLE_WHERE_PANEL_IS_1</code>
|-
| <code>UPDATE_ZONE</code>
| Update the zone attribute.
| <code>UPDATE_ZONE_AMOUNT_FLOORS_WHERE_ZONE_IS_589</code>
|}
 
===Comparison Predicate===
The <code>SELECT</code> and result parameter are followed by a <code>WHERE</code> statement. The <code>WHERE</code> statements contains a comparison predicate, which are logical propositions that restrict the information retrieved by the query. In other words, the <code>WHERE</code> clause eliminates all information from the result set where the comparison predicate does not evaluate as being valid (Boolean = True).
 
Take for instance the following statement as example of a logical proposition:
 
: ''The Student is a Senior.''
 
This statement excludes all students that are Junior, Sophomore or Freshman, as the outcome of the logical proposition would be 'False' in these cases.
 
The comparison predicate consists of 0 or more clauses, which consist of three parts;
* Clause Type
* Operator
* Value
 
====Clauses====
Some clauses are particular for constructions, others are applied to surface areas of constructions or dikes. The clause types and expected values currently supported are:
{| class="wikitable"
|-
! Clause Type
! Description
! Value Type
! Example
|-
| <code>CATEGORY</code>
| A construction belongs to the specific [[List_of_actions#Construction_Options | Function category]]
| Function category
| <code>CATEGORY_IS_INDUSTRY</code>
|-
| <code>CATEGORYMULT</code>
| A category multiplier, a fixed value for a given Function category
| Function value
| <code>CATEGORYMULT_IS_BUYOUT_COST_M2</code>
|-
| <code>BEHAVIOR</code>
| A specific type (= behavior) of land or open water
| Land
| <code>BEHAVIOR_IS_GRASSLAND</code>
|-
| <code>BEHAVIORMULT</code>
| A category multiplier, a fixed behavior value for a given Function
| Function value
| <code>BEHAVIORMULT_IS_GREEN_FACTOR</code>
|-
| <code>FUNCTION</code>
| A construction belongs to a specific [[Function]]
| Function ID
| <code>FUNCTION_IS_621</code>
|-
| <code>FUNCTIONMULT</code>
| A function multiplier, a fixed function value for a given Function
| Function value
| <code>FUNCTIONMULT_IS_WATER_STORAGE_M2</code>
|-
| <code>DIKE</code>
| Surface area lies (partly) within a particular type of [[Dike Types| Dike (or Levee)]]
| Dike ID
| <code>DIKE_IS_0</code>
|-
| <code>MAP</code>
| A construction or dike is present in the specified map or view. Also see [[#Simulation_Type | Simulation Type]]
| CURRENT or MAQUETTE
| <code>MAP_IS_MAQUETTE</code>
|-
| <code>STAKEHOLDER</code>
| A construction or surface area is owned by a specific [[Stakeholders| Stakeholder]]
| Stakeholder ID
| <code>STAKEHOLDER_IS_7</code>
|-
| <code>STAKEHOLDERTYPE</code>
| A construction or surface area is owned by stakeholders of a specific [[Stakeholders#Which_types_of_stakeholder_are_available_in_the_Tygron_Engine.3F | Stakeholder Type]]
| Stakeholder Type
| <code>STAKEHOLDERTYPE_IS_COMPANY</code>
|-
| <code>STATE</code>
| A construction is in specifide [[#State| State]]
| State Type
| <code>STATE_IS_PENDING_CONSTRUCTION</code>
|-
| <code>TERRAIN</code>
| Surface area lies (partly) within a specific [[Terrains|Terrain]]
| Terrain ID
| <code>TERRAIN_IS_1</code>
|-
| <code>TERRAINTYPE</code>
| Surface area lies (partly) within terrains with a specific [[Terrains#Terrain_Type | Type of Terrain]]
| Terrain Type
| <code>TERRAINTYPE_IS_SAFE_ZONE</code>
|-
| <code>ZONE</code>
| A specific part pertaining to an zone, or which lies within a[[Zoning|Zone]]
| Zone ID
| <code>ZONE_IS_25</code>
|-
| <code>GRIDTYPE</code>
| Type of grid used for a [[Grid indicators|Grid Indicator]]
| Grid Type
| <code>GRIDTYPE_IS_LIVABILITY</code>
|-
| <code>MINGRIDVALUE</code>
| Minimum treshold value for a [[Grid indicators|Grid Indicator]]
| Minimum grid value
| <code>MINGRIDVALUE_IS_50.0</code>
|-
| <code>MAXGRIDVALUE</code>
| Maximum treshold value for a [[Grid indicators|Grid Indicator]]
| Maximum grid value
| <code>MAXGRIDVALUE_IS_50.0</code>
|-
| <code>AREA</code>
| A specific part pertaining to an area, or which lies within an [[Area|Area]]
| Area ID
| <code>WHERE_AREA_IS_0</code>
|-
| <code>AREA_WITH_ATTRIBUTES</code>
| A specific part of an area, or which lies within an area that can be assigned with [[Attributes|Attributes]]
| An aera attribute
| <code>AREA_WITH_ATTRIBUTE_IS_COLOR</code>
|-
| <code>NEIGHBORHOOD</code>
| A specific part of the projectmap divided in the existing [[Neighborhoods|Neighborhood]]
| Neighborhood ID
| <code>NEIGHBORHOOD_IS_3</code>
|-
| <code>NEIGHBORHOOD_WITH_ATTRIBUTE</code>
| A specific part of a neighborhood, or which lies within a neighborhood that can be assigned with [[Attributes|Attributes]]
| Color or Urbanization
| <code>NEIGHBORHOOD_WITH_ATTRIBUTE_IS_URBANIZATION</code>
|-
| <code>ZONE_WITH_ATTRIBUTE</code>
| A specific part of a zone, or which lies within a zone that can be assigned with [[Attributes|Attributes]]
| Zone Attribute
| <code>ZONE_WITH_ATTRIBUTE_IS_MAX_BUILDING_HEIGHT</code>
|-
| <code>BUILDING</code>
| A specific [[Constructions|Construction]]
| Adress
| <code>BUILDING_IS_64</code>
|-
| <code>NAME</code>
| XX [[Constructions|Construction]]
| XX
| <code>BUILDING_IS_64</code>
|-
| <code>PANEL</code>
| XX [[Constructions|Construction]]
| XX
| <code>BUILDING_IS_64</code>
|-
| <code>LAYERTYPE</code>
| XX [[Constructions|Construction]]
| XX
| <code>BUILDING_IS_64</code>
|}
 
====Operators====
TQL clauses currently support one Operator:
{| class="wikitable"
|-
! Operator
! Description
! Example
|-
| <code>IS</code>
| Equal to
| <code>CATEGORY_IS_OFFICES</code>
|}
 
====Simulation Type====
Depending on the [[Simulation Type]], the map parameter is named as follows in the [[Query Tool]]:
{| class="wikitable"
|-
! Simulation Type
! <code>CURRENT</code>
! <code>MAQUETTE</code>
|-
| Planning
| <code>ORIGINAL</code>
| <code>PLANNED</code>
|-
| Timeline
| <code>TODAY</code>
| <code>MODEL</code>
|}
 
====State====
During a project session in the Tygron Engine, construction states transform from one phase into another. For example; from being planned, to being permitted, to being constructed, to being ready.
<br>
The currently available states are:
{| class="wikitable"
|-
! State
! Explanation
|-
| <code>CONSTRUCTING</code>
| Construction is being constructed.
|-
| <code>CONSTRUCTION_APPROVED</code>
| Construction is approved.
|-
| <code>CONSTRUCTION_DENIED</code>
| Construction is denied.
|-
| <code>DEMOLISH_APPROVED</code>
| Demolition is approved.
|-
| <code>DEMOLISH_DENIED</code>
| Demolition is denied.
|-
| <code>DEMOLITION_FINISHED</code>
| Demolition is finished.
|-
| <code>DEMOLISHING</code>
| Construction is being demolished.
|-
| <code>NOTHING</code>
| Construction does not exist.
|-
| <code>PENDING_CONSTRUCTION</code>
| Construction is waiting for the date to be constructed.
|-
| <code>PENDING_DEMOLISHING</code>
| Construction is waiting for the date to be demolished.
|-
| <code>PENDING_UPGRADE</code>
| Construction is waiting for the date to be upgraded.
|-
| <code>READY</code>
| Construction is done constructing.
|-
| <code>REQUEST_CONSTRUCTION_APPROVAL</code>
| Request is send to ask construction approval.
|-
| <code>REQUEST_DEMOLISH_APPROVAL</code>
| Request is send to ask demolition approval.
|-
| <code>REQUEST_ZONING_APPROVAL</code>
| Request is send to ask zoning approval.
|-
| <code>WAITING_FOR_DATE</code>
| Waiting to receive a date on which to start construction.
|-
| <code>WAITING_FOR_DEMOLISH_DATE</code>
| Waiting to receive a date on which to start demolition.
|}
 
==Query Tool==
In order to make it easier to construct queries, a tool has been developed to create queries in the editor, which can then be copied and used elsewhere. This tool is known as the [[Query Tool]] and more information can be found on its own page.
 
==TQL Uses==
TQL is currently used to communicate with a Microsoft Excel spreadsheet, when using such a spreadsheet for a (custom) [[Excel (Indicator)|Excel Indicator]].

Latest revision as of 09:23, 20 August 2018