TQL: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
Line 5: Line 5:


==Queries==
==Queries==
The main operation used in TQL is the query, which is performed with the declarative <code>SELECT</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. TQL queries using <code>SELECT</code> statements have no persistent effect on the project session itself.  
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 or a <code>UPDATE</code> statement retrieves data from a running Tygron project session. TQL queries using <code>SELECT</code> statements have no persistent effect on the project session itself. TQL queries using the <code>UPDATE</code> statement does 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. That is how the project will be influenced when using the <code>UPDATE</code> query.


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>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 descirbe 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:
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:
Line 53: Line 54:
|}
|}
''* can be followed by one clause maximum''
''* can be followed by one clause maximum''
When starting a query with the <code>UPDATE</code> statement, the result parameter is predifined to the statement. One of the following result parameters can be selected:
{| class="wikitable"
|-
! Result Parameter
! Description
! Example
|-
| <code>UPDATE_AREA</code>
| Floor size of buildings.
| <code>SELECT_FLOORSIZE_WHERE_CATEGORY_IS_OFFICES</code>
|-
| <code>UPDATE_BUILDING</code>
| Lot size of buildings.
| <code>SELECT_LOTSIZE_WHERE_CATEGORY_IS_OFFICES</code>
|-
| <code>UPDATE_GLOBAL</code>
| Amount of housing units.
| <code>SELECT_UNITS_WHERE_CATEGORY_IS_SOCIAL</code>
|-
| <code>UPDATE_NEIHBORHOOD</code>
| Amount of surface area.
| <code>SELECT_LANDSIZE_WHERE_BEHAVIOR_IS_GRASSLAND</code>
|-
| <code>UPDATE_PANEL</code>
| Surface space of constructed dikes or levees.
| <code>SELECT_DIKES_WHERE_ZONE_IS_1</code>
|-
| <code>UPDATE_ZONE</code>
| Useful for Excel Indicators
| <code>SELECT_ACTIVE_WHERE_ZONE_IS_1</code>
|}


===Comparison Predicate===
===Comparison Predicate===

Revision as of 13:12, 26 July 2016

Template:Learned

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 SELECT statement or UPDATE 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 SELECT statement or a UPDATE statement retrieves data from a running Tygron project session. TQL queries using SELECT statements have no persistent effect on the project session itself. TQL queries using the UPDATE statement does have an effect om the project session itself. The UPDATE 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. That is how the project will be influenced when using the UPDATE query.

Queries in TQL using the SELECT 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 UPDATE statement allow the user to descirbe 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 SELECT statement, a result parameter must follow after the SELECT keyword. Currently, one of the following result parameters can be selected:

Result Parameter Description Example
FLOORSIZE Floor size of buildings. SELECT_FLOORSIZE_WHERE_CATEGORY_IS_OFFICES
LOTSIZE Lot size of buildings. SELECT_LOTSIZE_WHERE_CATEGORY_IS_OFFICES
UNITS Amount of housing units. SELECT_UNITS_WHERE_CATEGORY_IS_SOCIAL
LANDSIZE Amount of surface area. SELECT_LANDSIZE_WHERE_BEHAVIOR_IS_GRASSLAND
DIKES Surface space of constructed dikes or levees. SELECT_DIKES_WHERE_ZONE_IS_1
ACTIVE Useful for Excel Indicators SELECT_ACTIVE_WHERE_ZONE_IS_1
NAME* Name of selection as query result SELECT_NAME_WHERE_CATEGORYMULT_IS_SELL_PRICE_M2
COLOR* Color of selection as query result SELECT_COLOR_WHERE_FUNCTION_IS_816
GRID_AVG* Average grid value per grid point SELECT_GRIDAVG_WHERE_GRIDTYPE_IS_TRAFFIC_NOISE

* can be followed by one clause maximum

When starting a query with the UPDATE statement, the result parameter is predifined to the statement. One of the following result parameters can be selected:

Result Parameter Description Example
UPDATE_AREA Floor size of buildings. SELECT_FLOORSIZE_WHERE_CATEGORY_IS_OFFICES
UPDATE_BUILDING Lot size of buildings. SELECT_LOTSIZE_WHERE_CATEGORY_IS_OFFICES
UPDATE_GLOBAL Amount of housing units. SELECT_UNITS_WHERE_CATEGORY_IS_SOCIAL
UPDATE_NEIHBORHOOD Amount of surface area. SELECT_LANDSIZE_WHERE_BEHAVIOR_IS_GRASSLAND
UPDATE_PANEL Surface space of constructed dikes or levees. SELECT_DIKES_WHERE_ZONE_IS_1
UPDATE_ZONE Useful for Excel Indicators SELECT_ACTIVE_WHERE_ZONE_IS_1

Comparison Predicate

The SELECT and result parameter are followed by a WHERE statement. The WHERE statements contains a comparison predicate, which are logical propositions that restrict the information retrieved by the query. In other words, the WHERE 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:

Clause Type Description Value Type Example
CATEGORY A construction belongs to the specific Function category Function category CATEGORY_IS_INDUSTRY
CATEGORYMULT A category multiplier, a fixed value for a given Function category Function value CATEGORYMULT_IS_BUYOUT_COST_M2
BEHAVIOR A specific type (= behavior) of land or open water Land BEHAVIOR_IS_GRASSLAND
BEHAVIORMULT A category multiplier, a fixed behavior value for a given Function Function value BEHAVIORMULT_IS_GREEN_FACTOR
FUNCTION A construction belongs to a specific Function Function ID FUNCTION_IS_621
FUNCTIONMULT A function multiplier, a fixed function value for a given Function Function value FUNCTIONMULT_IS_WATER_STORAGE_M2
DIKE Surface area lies (partly) within a particular type of Dike (or Levee) Dike ID DIKE_IS_0
MAP A construction or dike is present in the specified map or view. Also see Simulation Type CURRENT or MAQUETTE MAP_IS_MAQUETTE
STAKEHOLDER A construction or surface area is owned by a specific Stakeholder Stakeholder ID STAKEHOLDER_IS_7
STAKEHOLDERTYPE A construction or surface area is owned by stakeholders of a specific Stakeholder Type Stakeholder Type STAKEHOLDERTYPE_IS_COMPANY
STATE A construction resides in the specified State State Type STATE_IS_PENDING_CONSTRUCTION
TERRAIN Surface area lies (partly) within a specific Terrain Terrain ID TERRAIN_IS_1
TERRAINTYPE Surface area lies (partly) within terrains with a specific Type of Terrain Terrain Type TERRAINTYPE_IS_SAFE_ZONE
ZONE Surface area lies (partly) within a specific Zone Zone ID ZONE_IS_25
GRIDTYPE Type of grid used for a Grid Indicator Grid Type GRIDTYPE_IS_LIVABILITY
MINGRIDVALUE Minimum treshold value for a Grid Indicator Minimum grid value MINGRIDVALUE_IS_50.0
MAXGRIDVALUE Maximum treshold value for a Grid Indicator Maximum grid value MAXGRIDVALUE_IS_50.0

Operators

TQL clauses currently support one Operator:

Operator Description Example
IS Equal to CATEGORY_IS_OFFICES

Simulation Type

Depending on the Simulation Type, the map parameter is named as follows in the Query Tool:

Simulation Type CURRENT MAQUETTE
Planning ORIGINAL PLANNED
Timeline TODAY MODEL

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.
The currently available states are:

State Explanation
CONSTRUCTING Construction is being constructed.
CONSTRUCTION_APPROVED Construction is approved.
CONSTRUCTION_DENIED Construction is denied.
DEMOLISH_APPROVED Demolition is approved.
DEMOLISH_DENIED Demolition is denied.
DEMOLITION_FINISHED Demolition is finished.
DEMOLISHING Construction is being demolished.
NOTHING Construction does not exist.
PENDING_CONSTRUCTION Construction is waiting for the date to be constructed.
PENDING_DEMOLISHING Construction is waiting for the date to be demolished.
PENDING_UPGRADE Construction is waiting for the date to be upgraded.
READY Construction is done constructing.
REQUEST_CONSTRUCTION_APPROVAL Request is send to ask construction approval.
REQUEST_DEMOLISH_APPROVAL Request is send to ask demolition approval.
REQUEST_ZONING_APPROVAL Request is send to ask zoning approval.
WAITING_FOR_DATE Waiting to receive a date on which to start construction.
WAITING_FOR_DEMOLISH_DATE 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.