View source for Query topic map

'''Note: This feature is not present in the current release version. Expect query topic maps in the version to be published on 31st of May.'''

Query topic map is a special topic map implementation in Wandora. A query topic map is defined by a number of queries in the Wandora [[query language]]. Each query will return one type of associations and the topic map consists of all these associations and the topics needed by the associations. All queries are executed in the context of some other topic map.

For example, you may define a query topic map with a query that will return the transitive closure of superclass-subclass associations. Then you give the query topic map a context topic map where this query will be executed. This will produce a topic map that seemingly contains the superclass-subclass associations making up the closure of such associations in the context topic map.

Currently query topic maps can only be used to create associations. They may be expanded in the future to allow creation of new topics, occurrences, instances, subject identifiers and so on.

== Setting up a query topic map ==

To set up a query topic map you need to make a new query topic map layer. Right click on the layer stack at lower left corner and select '''New Layer'''. Give your layer a name and select the '''Query''' type. For the query topic map to contain anything, you will need to add one or more queries. You can edit or add new queries also later by right clicking the layer and selecting '''Configure Layer'''. See next chapter about creating queries.

You will also need to set the context topic map. You can do this by dragging any layer in the layer stack under the query topic map layer or creating a new topic layer map under it. Note that the contents of the context topic map are not directly visible when it is under query topic map. Only contents produced by the query topic map are visible. For this reason you will usually want to create a special [[linked topic map]]. A linked topic map is a link to some other topic map in the layer and will contain everything in the topic map the link is pointing to contains. All edits made to either the linked topic map or the link target are reflected in the other. This way you can use a query topic map to complement another topic map, for example produce a transitional closure of associations.

== Queries in a query topic map ==

Queries in a query topic map are defined using the Wandora [[query language]]. Each query has a type which is the association type produced by the query. In the query editor, enter the subject identifier of the association type here. The queries themselves return a table of rows. Each column has a role, which will also be the role in the associations produced by the query. Rows of the returned table contain players for the associations.

As described in the [[query language]] page, all queries are executed using some topic as the query context. In query topic maps the currently opened topic acts as the query context. The query should return associations related to this topic. All rows that do not contain the context topic, i.e. context topic is not a player in the association, are ignored.

You should take care that same association is returned regardless of which player is used as the query context. For example, using topic A as context may produce an association saying that A is a superclass of B. Using B as context topic should then return an association saying that B is a subclass of A. Failure to do this will result in strange topic maps where some associations are visible only when looking at a certain topic.

== Examples ==

This section contains some example queries you can use in a query topic map.

=== Transitional closure ===

 importPackage(org.wandora.query);
 importPackage(org.wandora.topicmap);
 new TransitiveDirective(XTMPSI.SUPERCLASS_SUBCLASS, 
                         XTMPSI.SUPERCLASS, XTMPSI.SUBCLASS);

Set http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass as association type.

This query will form a transitional closure of superclass-subclass associations. What this means is that if the context topic map has associations saying that A is a superclass of B and B is a superclass of C then this query will produce an association A is a superclass of C. Similarly for subclasses. The three parameters of TransitiveDirective are association type, and the two roles. By changing these you can create closures of other types of associations.

=== Instances and classes as associations ===

 importPackage(org.wandora.query);
 importPackage(org.wandora.topicmap);
 new UnionDirective(
   new JoinDirective(
     new TypesOfDirective(),
     new ContextTopicDirective("",XTMPSI.INSTANCE)),
   new JoinDirective(
     new InstancesDirective(),
     new ContextTopicDirective("",XTMPSI.CLASS))
 );

Set http://www.topicmaps.org/xtm/1.0/core.xtm#class-instance as association type. Your topic map must also have topics with subject identifiers http://www.topicmaps.org/xtm/1.0/core.xtm#class-instance , http://www.topicmaps.org/xtm/1.0/core.xtm#class and http://www.topicmaps.org/xtm/1.0/core.xtm#instance . These are not in the default Wandora topic map.

This query will make associations out of all instance and class relations. Note how this is done as the union of types of a topic and instances of a topic. This is necessary to have each association visible regardless of what topic is used as the point of view. Suppose that A is the class of B which is of course same as B is an instance of A. If we're looking at topic A then the InstancesDirective will return this information. If we're looking at topic B then the same thing is returned by TypesOfDirective. The results of both these directives only have one column so we must join the context topic itself using JoinDirective and ContextTopicDirective.