TMQL

Revision as of 13:35, 7 April 2014

This is an upcoming feature. The current public version of Wandora does not yet support TMQL, but will soon.

Introduction

Wandora uses the TMQL4J library for TMQL. TMQL4J in turn uses the TMAPI and standard the TMDM data model, which is slightly different to Wandora's topic map data model. This necessitates some conversion between the two data models when using TMQL, which may cause some unexpected behaviour at times. For the most part, however, TMQL works as one would expect. See the article about Wandora's Reduced Topic Maps for more information on what kind of constructs will not work in Wandora.

For information about TMQL itself, refer to the documentation of TMQL4J, which includes some easy to follow tutorials.

Using the TMQL search dialog

In the graphical user interface, TMQL can be used in the search dialog, accessed through the Edit/Search menu item.

Then select the TMQL query tab and enter your TMQL query. There are also options to save queries for later use or selecting a saved query from a list.

You may perform any kind of TMQL queries, including ones that modify the topic map, not just select queries. The results however will always be returned in a tabular format when invoked through the search dialog, so trying to output XML or CTM fragments like this will be impractical. Additional tools may be created later for these use cases.

Using TMQL in Velocity templates

TMQL queries can also be ran in the Apache Velocity templates used by the services of the Embedded HTTP server. The context automatically contains a variable tmqlrunner which has the method runTMQL. This method needs the topic map and the TMQL query as variables. See the querydemo service for an example on how to use TMQL like this.

In any other web applications TMQL queries can be similarly used in Velocity templates, as long as you pass the TMQL runner object to the Velocity context. The full class name is org.wandora.topicmap.TMQLRunner.

Known problems

The main issue with TMQL is that it uses the standard TMDM data model whereas Wandora has its own slightly reduced data model. Wandora does the conversion between the two data models automatically when using TMQL.

Some features of TMDM are not fully supported in Wandora. However, you are still able to create and manipulate such structures in TMQL. If you do so, those structures will either be modified to fit Wandora's data model or dropped entirely, when converted back to Wandora's data model. In some cases you may get an error executing the query if you try to use a feature that Wandora's data model doesn't support. See Reduced Topic Maps for more details on what structures are not supported in Wandora. It is best to try to not use any of the unsupported structures, as it is not always clear in what way the query execution will behave.

Similarly, when converting from Wandora's data model to TMDM, some default types must be added to some structures. Depending on the query you use, you may have to write out these type identifiers in the query. Each topic will have at most one name, which will have the type http://psi.topicmaps.org/iso13250/model/topic-name, this is the base name of the topic. All variant names are variants of this single name. Names never have a scope, the variants in the single topic name will have a scope of at least one topic.

Occurrences have type corresponding to Wandora's occurrence type, and a scope with a single theme in it which is the occurrence version in Wandora.

Data type of all occurrences and variants is always http://www.w3.org/TR/xmlschema-2/#string.

See also

Wandora also has another option for executing queries using a scripting language. See Query language.