TopicMap Query Language

TopicMap Query Language (TMQL) can be used to make queries on topicmaps. It provides a way of accessing parts of a topicmap based on various conditions. For example, you can query a topicmap to find all of the topics that are in an association.

Syntax

Between SELECT and WHERE

A TMQL query can be split into two parts. The first part identifies the things that will be returned as the results of the query. The second part describes the data that will be returned. This is most simply explained by looking at an example:

SELECT topic x WHERE x in
assoc

TMQL queries always start with the keyword SELECT. Between the keyword SELECT and the keyword WHERE, the return identities are defined. In the above example we are saying that a topic will be returned. We call it x so we can identify that specific topic in the second part of the query. More than one return identity can be defined between the SELECT and the WHERE keywords but each identity must have a unique name and only one type, e.g.

SELECT
topic x assoc y WHERE x in y

The types that TMQL supports are topics, associations, association templates, roles, association ends, scopes, names, strings, occurrences, resources, locators and identities. The typing keywords used to represent these are (respectively) topic, assoc, assoctemp, role, end, scope, name, string, occurrence, resource, locator and id.

It is not necessary to have a WHERE keyword in a TMQL query. For example: SELECT topic x is a valid query.

When the WHERE keyword is omitted the query returns all items of the specified type or types in the topicmap. In the above example all topics are returned.

Note that the keywords in TMQL are not case sensitive. However, identifiers that you define, are.

To the right of WHERE

The data that will be returned from the query is described from the keyword WHERE to the end of the query. In the first example above, we define that we want x to be all of the topics that are in associations. We know that x is of type topic from the information between SELECT and WHERE. The typing keyword 'assoc' refers to all associations, we do not bother to give it an identifier as we are not interested in returning the values that it contains. The keyword 'in' when used between something of type 'topic' something of type 'assoc' means that the topic or topics play roles in the association or associations.

The right hand side of the query can consist of many conditions chained together. For example, if we wanted all of the topics that played a role in an association and that association's template is called "myTemplate" we could make a query something like this:

SELECT topic x WHERE x in assoc template_is assoctemp named
"myTemplate"

Notice that we have used the value "myTemplate" in the last query. This is called a literal. Its actual type is 'string' but as we know that the keyword named can only take a literal of type 'string' on its right hand side, the type is inferred. There are three literal types: 'string', 'locator' and 'id'. Whereever possible TMQL will infer their type but in ambiguous situations you may need to type the literal yourself. For example:

SELECT topic x WHERE topic has occurrence has locator 'http://www.mysite.co.uk'

In this case 'occurrence has' can take an id or a locator so we have to specify which it is.

Brackets - part 1

Non-typing keywords (such as 'in' and 'named' in the above example) always act on the things immediately to their left and right in the query. They cannot act on anything that is outside their grammar semantics. We can use brackets to group together parts to make more complex queries possible. If, for example, we wanted to get all of the topics called "Spielberg" that are in a role called "Director" we CANNOT do the following query:

SELECT
topic x WHERE x named "Spielberg" in role named
"Director"

The above query is invalid because the keyword 'in' cannot take a string on its left hand side. By using brackets we can produce a valid query that will return what we want:

SELECT topic x WHERE (x named
"Spielberg") in role named "Director"

The keyword to the right of the brackets considers everything within the brackets to be the first type contained. In the example the first type in the brackets is a topic so the keyword 'in' after the brackets uses this for evaluation purposes.

AND and OR keywords

The AND and OR keywords make it possible to do more complex queries. For example, say we wanted to get all of the topics that are called "Bill" and all the topics that are called "Ben". Using only the TMQL described thus far, it is impossible to do in a single query. However, using OR we can make the following query:

SELECT topic plantPot WHERE plantPot named "Ben" OR plantPot
named "Bill"

This means that the results of the query will contain all of the topics called "Ben" as well as all of the topics called "Bill".

If we wanted to get all of the associations that "Bill" and "Ben" play roles in, we could use the AND keyword. For example:

SELECT assoc a WHERE a has topic named "Ben" AND a has topic named
"Bill"

When evaluating queries, any AND keywords are evaluated before any OR keywords. So a query like

SELECT topic x WHERE x named "Bill" OR x named "Ben" AND x in
assoc

will find all the topics that are named "Ben" that are in associations plus all the topics that are just named "Bill".

Brackets - part 2

Brackets can also be used to group AND and OR statements. Things in brackets get evaluated before anything else. If, in the previous example, we wanted to find all of the topics that were named either "Bill" or "Ben" and that were in associations, the query would look like this:

SELECT
topic x WHERE (x named "Ben" OR x named "Bill") AND x in
assoc

NOT keyword

The NOT keyword can be used to return things that are not true. For example, if we want all of the topics in a map that are not in an association, we could say:

SELECT topic x WHERE NOT x in
assoc

It is possible to use NOT in complex statements as well. For example:

SELECT topic x WHERE NOT (x named "Bill" OR x named "Ben")
AND x in assoc

will find all of the topics that aren't called either "Bill" or "Ben" and that are in an association.

Defining more identifiers

It is perfectly valid to define more identifiers to the right hand side of the WHERE keyword. This allows more complex queries and checking within queries. For example, if we want all of the topics that are in associations that the topic named "Ben" is in, we can do the query:

SELECT topic x
WHERE x in assoc has topic y named "Ben" AND NOT x = y

If we do not specify that x should not equal y then the topic called "Ben" will be returned as "Ben" in an association that has a topic named "Ben".

Regular Expressions

TMQL provides support for matching strings with regular expressions. This means that you can search for string names, locators or ids that match a particular pattern rather than having to match them exactly. The use of regular expressions in TMQL is indicated by the 'like' keyword directly preceding the literal itself. For example, to match all topics whose unconstrained names begin with A:

SELECT topic x WHERE x named like "^A"

The "^A" is the regular expression. If the type of the literal has to be specified, then the query would look like this:

SELECT topic x WHERE x named string like "^A"

The expressions available in regular expressions in TMQL are outlined in the documentation for theJakarta-RegExp package.

TMQL Grammar

This section describes the entire grammar of TMQL. For convenience, the descriptions in the table assume that there is one value in the left hand type and therefore describe what will be put into the right hand type. During actual TMQL evaluations there may be one or many values in both, either or neither type. The descriptions of these scenarios have been omitted to try and keep this table manageable.

Type on left	Keyword	Type on right	Description
topic	named	name	All of the names of the topic.
topic	named	string	The string form of the topic's name in the unconstrained scope.
topic	in	assoctemp	All of the associations where the topic plays a role in one or more of the association template's child associations.
topic	in	assoc	All of the associations that the topic plays a role in.
topic	in	end	All of the association ends that the topic plays a role in.
topic	in	role	All of the roles that the topic plays.
topic	in	scope	All of the scope sets that the topic is in.
topic	has	occurrence	All occurrences of the topic.
topic	has	id	All identities of the topic.
topic	=	topic
topic	=	role
topic	occurs	resource	All of the resource topics that are in occurrences of the topic.
topic	occurs	locator	All of the URIs that define the occurrence locations for the topic.
topic	instance_of	topic	All of the topics that are instances of the topic.
topic	instance_of	assoctemp	All of the association templates that are instances of the topic.
topic	instance_of	assoc	All of the associations that are instances of the topic.
topic	instance_of	role	All of the roles that are instances of the topic.
topic	instance_of	occurrence	All of the occurrences that are instances of the topic.
topic	instance_is	topic	All of the topics of which the topic is an instance.
topic	instance_is	assoctemp	All of the association templates of which the topic is an instance.
topic	instance_is	assoc	All of the associations of which the topic is an instance.
topic	instance_is	role	All of the roles of which the topic is an instance.
topic	instance_is	occurrence	All of the occurrences of which the topic is an instance.
topic	subclass_of	topic	All of the topics that are direct subclasses of the topic.
topic	subclass_of	assoctemp	All of the association templates that are direct subclasses of the topic.
topic	subclass_of	assoc	All of the associations that are direct subclasses of the topic.
topic	subclass_of	role	All of the roles that are direct subclasses of the topic.
topic	subclass_of	occurrence	All of the occurrences that are direct subclasses of the topic.
topic	superclass_of	topic	All of the topics that are direct superclasses of the topic.
topic	superclass_of	assoctemp	All of the association templates that are direct superclasses of the topic.
topic	superclass_of	assoc	All of the associations that are direct superclasses of the topic.
topic	superclass_of	role	All of the roles that are direct superclasses of the topic.
topic	superclass_of	occurrence	All of the occurrences that are direct superclasses of the topic.
assoctemp	named	name	All of the names of the association template.
assoctemp	named	string	The string form of the association template's name in the unconstrained scope.
assoctemp	in	assoc	All of the associations that the association template plays a role in.
assoctemp	in	end	All of the association ends that the association template plays a role in.
assoctemp	in	role	All of the roles that the association template plays.
assoctemp	in	scope	All of the scope sets that the association template is in.
assoctemp	has	topic	All of the topics that plays roles in the associations that are templated by the association template.
assoctemp	has	role	The roles that are defined in the association template.
assoctemp	has	end	The ends of the association template.
assoctemp	has	occurrence	All occurrences of the association template.
assoctemp	has	id	All identities of the association template.
assoctemp	=	assoctemp
assoctemp	occurs	resource	All of the resource topics that are in occurrences of the association template.
assoctemp	occurs	locator	All of the URI's that define the occurrence locations for the association template.
assoctemp	template_of	assoc	The associations that the association template is the template for.
assoctemp	instance_of	topic	All of the topics that are instances of the association template.
assoctemp	instance_of	assoctemp	All of the association templates that are instances of the association template.
assoctemp	instance_of	assoc	All of the associations that are instances of the association template.
assoctemp	instance_of	role	All of the roles that are instances of the association template.
assoctemp	instance_of	occurrence	All of the occurrences that are instances of the association template.
assoctemp	instance_is	topic	All of the topics of which the association template is an instance.
assoctemp	instance_is	assoctemp	All of the association templates of which the association template is an instance.
assoctemp	instance_is	assoc	All of the associations of which the association template is an instance.
assoctemp	instance_is	role	All of the roles of which the association template is an instance.
assoctemp	instance_is	occurrence	All of the occurrences of which the association template is an instance.
assoctemp	subclass_of	topic	All of the topics that are direct subclasses of the association template.
assoctemp	subclass_of	assoctemp	All of the association templates that are direct subclasses of the association template.
assoctemp	subclass_of	assoc	All of the associations that are direct subclasses of the association template.
assoctemp	subclass_of	role	All of the roles that are direct subclasses of the association template.
assoctemp	subclass_of	occurrence	All of the occurrences that are direct subclasses of the association template.
assoctemp	superclass_of	topic	All of the topics that are direct superclasses of the association template.
assoctemp	superclass_of	assoctemp	All of the association templates that are direct superclasses of the association template.
assoctemp	superclass_of	assoc	All of the associations that are direct superclasses of the association template.
assoctemp	superclass_of	role	All of the roles that are direct superclasses of the association template.
assoctemp	superclass_of	occurrence	All of the occurrences that are direct superclasses of the association template.
assoctemp	scoped_by	scope	The scope set that scopes the association template.
assoc	named	name	All of the names of the association.
assoc	named	string	The string form of the association's name in the unconstrained scope.
assoc	in	assoc	All of the associations that the association plays a role in.
assoc	in	end	All of the association ends that the association plays a role in.
assoc	in	role	All of the roles that the association plays.
assoc	in	scope	All of the scope sets that the association template is in.
assoc	has	topic	All of the topics playing roles in the association.
assoc	has	assoctemp	All of the association templates playing roles in the associations.
assoc	has	assoc	All of the associations playing roles in the association.
assoc	has	role	All of the roles in the association.
assoc	has	end	All of the ends in the association.
assoc	has	occurrence	All occurrences of the association.
assoc	has	id	All identities of the association.
assoc	=	assoc
assoc	occurs	resource	All of the resource topics that are in occurrences of the association.
assoc	occurs	locator	All of the URI's that define the occurrence locations for the association.
assoc	template_is	assoctemp	The template for the association.
assoc	instance_of	topic	All of the topics that are instances of the association.
assoc	instance_of	assoctemp	All of the association templates that are instances of the association.
assoc	instance_of	assoc	All of the associations that are instances of the association.
assoc	instance_of	role	All of the roles that are instances of the association.
assoc	instance_of	occurrence	All of the occurrences that are instances of the association.
assoc	instance_is	topic	All of the topics of which the association is an instance.
assoc	instance_is	assoctemp	All of the association templates of which the association is an instance.
assoc	instance_is	assoc	All of the associations of which the association is an instance.
assoc	instance_is	role	All of the roles of which the association is an instance.
assoc	instance_is	occurrence	All of the occurrences of which the association is an instance.
assoc	subclass_of	topic	All of the topics that are direct subclasses of the association.
assoc	subclass_of	assoctemp	All of the association templates that are direct subclasses of the association.
assoc	subclass_of	assoc	All of the associations that are direct subclasses of the association.
assoc	subclass_of	role	All of the roles that are direct subclasses of the association.
assoc	subclass_of	occurrence	All of the occurrences that are direct subclasses of the association.
assoc	superclass_of	topic	All of the topics that are direct superclasses of the association.
assoc	superclass_of	assoctemp	All of the association templates that are direct superclasses of the association.
assoc	superclass_of	assoc	All of the associations that are direct superclasses of the association.
assoc	superclass_of	role	All of the roles that are direct superclasses of the association.
assoc	superclass_of	occurrence	All of the occurrences that are direct superclasses of the association.
assoc	scoped_by	scope	The scope set that scopes the association.
role	named	name	All of the names of the role.
role	named	string	The string form of the role's name in the unconstrained scope.
role	in	assoctemp	The association templates for which the role defines a role.
role	in	assoc	The associations for which the role defines a role.
role	in	end	The ends in which the role defines a role.
role	in	role	The roles the role plays.
role	in	scope	The scope sets that the role is in.
role	has	topic	The topics that play the role.
role	has	assoctemp	The association templates that play the role.
role	has	assoc	The associations that play the role.
role	has	role	The roles that play the role.
role	has	occurrence	The occurrences of the role.
role	has	id	The identities of the role.
role	=	role
role	=	topic
role	occurs	resource	All of the resource topics that are in occurrences of the role.
role	occurs	locator	All of the URI's that define the occurrence locations for the role.
role	instance_of	topic	All of the topics that are instances of the role.
role	instance_of	assoctemp	All of the association templates that are instances of the role.
role	instance_of	assoc	All of the associations that are instances of the role.
role	instance_of	role	All of the roles that are instances of the role.
role	instance_of	occurrence	All of the occurrences that are instances of the role.
role	instance_is	topic	All of the topics of which the role is an instance.
role	instance_is	assoctemp	All of the association templates of which the role is an instance.
role	instance_is	assoc	All of the associations of which the role is an instance.
role	instance_is	role	All of the roles of which the role is an instance.
role	instance_is	occurrence	All of the occurrences of which the role is an instance.
role	subclass_of	topic	All of the topics that are direct subclasses of the role.
role	subclass_of	assoctemp	All of the association templates that are direct subclasses of the role.
role	subclass_of	assoc	All of the associations that are direct subclasses of the role.
role	subclass_of	role	All of the roles that are direct subclasses of the role.
role	subclass_of	occurrence	All of the occurrences that are direct subclasses of the role.
role	superclass_of	topic	All of the topics that are direct superclasses of the role.
role	superclass_of	assoctemp	All of the association templates that are direct superclasses of the role.
role	superclass_of	assoc	All of the associations that are direct superclasses of the role.
role	superclass_of	role	All of the roles that are direct superclasses of the role.
role	superclass_of	occurrence	All of the occurrences that are direct superclasses of the role.
end	in	assoctemp	The association template that the end is in.
end	in	assoc	The associations that the end is in.
end	has	topic	The topic that play the role in the end.
end	has	assoctemp	The association template that plays the role in the end.
end	has	assoc	The association that plays the role in the end.
end	has	role	The role that plays the role in the end.
end	has	occurrence	The occurrence that plays the role in the end.
end	=	end
scope	has	topic	The topics that make up the scope.
scope	has	assoctemp	The association templates that make up the scope.
scope	has	assoc	The associations that make up the scope.
scope	has	role	The roles that make up the scope.
scope	has	occurrence	The occurrences that make up the scope.
scope	=	scope
scope	scopes	assoctemp	The association templates that the scope scopes.
scope	scopes	assoc	The associations that the scope scopes.
scope	scopes	name	The names that the scope scopes.
scope	scopes	occurrence	The occurrences that the scope scopes.
name	=	name
name	is	string	The string value of the name.
name	scoped_by	scope	The scope set that scopes the name.
name	names	topic	The topics which the name is a name of.
name	names	assoctemp	The association templates which the name is a name of.
name	names	assoc	The associations which the name is a name of.
name	names	role	The roles which the name is a name of.
name	names	occurrence	The occurrences which the name is a name of.
string	=	string
string	is	name	The names that the string is the value of.
string	names	topic	The topics which the string is the value of a name of (in the unconstrained scope).
string	names	assoctemp	The association templates which the string is the value of a name of (in the unconstrained scope).
string	names	assoc	The associations which the string is the value of a name of (in the unconstrained scope).
string	names	role	The roles which the string is the value of a name of (in the unconstrained scope).
string	names	occurrence	The occurrences which the string is the value of a name of (in the unconstrained scope).
occurrence	named	name	All of the names of the occurrence.
occurrence	named	string	The string form of the occurrence's name in the unconstrained scope.
occurrence	in	assoc	All of the associations that the occurrence plays a role in.
occurrence	in	end	All of the association ends that the occurrence plays a role in.
occurrence	in	role	All of the roles that the occurrence plays.
occurrence	in	scope	All of the scopes that the occurrence is in.
occurrence	has	resource	The resource topics that are in the occurrence.
occurrence	has	locator	The URI locators of the resource topics that are in the occurrence.
occurrence	has	id	The identities of the occurrence.
occurrence	=	occurrence
occurrence	occurs	resource	All of the resource topics that are in occurrences of the occurrence.
occurrence	occurs	locator	All of the URI's that define the occurrence locations for the occurrence.
occurrence	instance_of	topic	All of the topics that are instances of the occurrence.
occurrence	instance_of	assoctemp	All of the association templates that are instances of the occurrence.
occurrence	instance_of	assoc	All of the associations that are instances of the occurrence.
occurrence	instance_of	role	All of the roles that are instances of the occurrence.
occurrence	instance_of	occurrence	All of the occurrences that are instances of the occurrence.
occurrence	instance_is	topic	All of the topics of which the occurrence is an instance.
occurrence	instance_is	assoctemp	All of the association templates of which the occurrence is an instance.
occurrence	instance_is	assoc	All of the associations of which the occurrence is an instance.
occurrence	instance_is	role	All of the roles of which the occurrence is an instance.
occurrence	instance_is	occurrence	All of the occurrences of which the occurrence is an instance.
occurrence	subclass_of	topic	All of the topics that are direct subclasses of the occurrence.
occurrence	subclass_of	assoctemp	All of the association templates that are direct subclasses of the occurrence.
occurrence	subclass_of	assoc	All of the associations that are direct subclasses of the occurrence.
occurrence	subclass_of	role	All of the roles that are direct subclasses of the occurrence.
occurrence	subclass_of	occurrence	All of the occurrences that are direct subclasses of the occurrence.
occurrence	superclass_of	topic	All of the topics that are direct superclasses of the occurrence.
occurrence	superclass_of	assoctemp	All of the association templates that are direct superclasses of the occurrence.
occurrence	superclass_of	assoc	All of the associations that are direct superclasses of the occurrence.
occurrence	superclass_of	role	All of the roles that are direct superclasses of the occurrence.
occurrence	superclass_of	occurrence	All of the occurrences that are direct superclasses of the occurrence.
occurrence	of	topic	The topic that the occurrence is of.
occurrence	of	assoctemp	The association template that the occurrence is of.
occurrence	of	assoc	The association that the occurrence is of.
occurrence	of	role	The role that the occurrence is of.
occurrence	of	occurrence	The occurrence that the occurrence is of.
occurrence	scoped_by	scope	The scope set that scopes the occurrence.
resource	has	locator	The URI locator of the resource.
resource	=	resource
resource	of	topic	The topic in the same occurrence as the resource.
resource	of	assoctemp	The association template in the same occurrence as the resource.
resource	of	assoc	The association in the same occurrence as the resource.
resource	of	role	The role in the same occurrence as the resource.
resource	of	occurrence	The occurrence in the same occurrence as the resource.
locator	=	locator
locator	of	topic	The topics that the locator is the URI for.
locator	of	assoctemp	The association templates that the locator is the URI for.
locator	of	assoc	The associations that the locator is the URI for.
locator	of	role	The roles that the locator is the URI for.
locator	of	occurrence	The occurrences that the locator is the URI for.
locator	of	resource	The resources that contain the locator.
id	=	id
id	of	topic	The topics that the id identifies.
id	of	assoctemp	The association templates that the id identifies.
id	of	assoc	The associations that the id identifies.
id	of	role	The roles that the id identifies.
id	of	occurrence	The occurrences that the id identifies.