TQL tutorial

Redirect to:

• Tygron Query Language

This article is a stub.

Prerequisites

The following prerequisites should be met before starting this tutorial:

• This tutorial relies on base knowledge about the editor interface. If you have not yet followed the tutorials related to those subjects please do so first.
• This tutorial can be followed with any project of any arbitrary location, preferable in an urban environment. 

Preparations

Take the following steps as preparation for following this tutorial:

• Start your project. This can be a pre-existing project, or a newly created project.

Introduction to TQL

TQL is an abbreviation for Tygron Query Language. It is a custom query language created to allow for obtaining statistical data from a Project. The language consists of "queries", which can be interpreted as questions asked of the Project. Such a query is composed of a statement, which embodies the requested information, and a number of clauses, which define/filter the data taken into consideration.

TQL queries are an important tool for automated analyses of Projects, both of the Current Situation as well as any Future Designs.

TQL queries by themselves can be used to obtain bits of information. In broader contexts, such as Excel Indicators or Panels, or scripts interacting via the API, the combination of multiple queries allows for obtaining large amounts of information which together can be used for more complex analyses.

Most statements return numerical values which can be used in calculations. Some statements return some form of text.

Query tool

To get started with the creation of queries, open the query tool:

Editor → Current Situation (Ribbon tab) → Queries (Ribbon bar)

The query tool is an assistive tool for the creation of queries. It helps by offering up options for which clauses can be added to statements and queries. It also allows for executing queries and seeing the results. This means that any created queries can be validated that they function as expected, but also that small bits of information can be requested on-the-fly.

When the query tool opens, a simple query is already composed.

If any clauses are listed, click on "Remove clause" for each of them until no clauses remain. Only the statement should remain.

Ensure the query type is set to "SELECT", which means to request data from the Project.

Ensure the statement is set to "LANDSIDE", which is a request for surface area.

Click on "Execute Query".

The result shown is the surface area found in the Project, unqualified. It will be the size of the Project in its entirety.

Next, click on "Add clause". This adds a qualifier to the query; a filter or rule the data must conform to before being taken into consideration.

Set the clause to "NEIGHBORHOOD", and select a Neighborhood which is well present in the Project.

Then, click on "Execute Query" again.

The result shown is the surface area which lies in the selected Neighborhood.

Note that the composed query is shown in the query tool as well. The dropdowns allow for (and guide) the selection of the individual parts of the query, but the full query is all components strung together.

Also note that using the dropdown, a Neighborhood could be selected by name, but in the actual query the ID of the Neighborhood is used. If the name of the Neighborhood (or any other Item being queried) is ever changed, the ID remains unchanged and thus the query will remain functional.

Basic queries

To create queries effectively, some knowledge of which statements are available is important. Construction the following queries and see the results:

SELECT_NAME

The name of a specific Item.

SELECT_LANDSIZE

The amount of surface area matching whichever qualifiers are provided in the clauses.

SELECT_LOTSIZE

The amount of surface area which is taken up by Buildings such as apartments, roads, parks and trees. It's effectively the footprint of all constructions.

SELECT_FLOORSIZE

The footprint of constructions, multiplied by their respective floors. The amount of space which the found constructions contain for use. This includes "single floor" constructions like roads and trees, unless further qualified.

SELECT_UNITS

The amount of housing units present. This is calculated by dividing the floorspace of Buildings by their respective UNIT_SIZE Attributes. Buildings which are not representative of housing are ignored.

Statements

WHERE_NEIGHBORHOOD_IS_...

The data must be related to, or inside of, this Neighborhood.

WHERE_CATEGORY_IS_...

The data requested is related to Buildings, and those Buildings must be of a specific Category.

WHERE_STAKEHOLDER_IS...

The data must be related to, or owned by, this Stakeholder.

WHERE_FUNCTIONMULT_IS_...

WHERE_CATEGORYMULT_IS_...

WHERE_ATTRIBUTE_MULT_IS_...

The data requested is related to Buildings, and the found amount is multiplied by the respective Function Values or Attributes.

Final notes

Although not part of the general explanation provided in this tutorial, the following notes are important to keep in mind:

• The editor interface will generally present the first 3 inputs (A, B, and C) of the Combo Overlay. However, a total of 10 inputs can be added and used, by switching to the "inputs" tab.

Tutorial completed

Congratulations. You have now completed this tutorial. In it, you have learned how to create Combo Overlays, and how to use Average Overlays to rasterize data for use in the Combo Overlay.