| Published by: | Ontopia |
|---|---|
| Date: | $Date: 2005/07/13 12:17:05 $ |
| Version: | 2.2 ($Revision: 1.9 $) |
|
|
The tolog query language has a number of predefined predicates which are part of the language itself. Some of these exist in order to allow access to various parts of the topic map model, while others exist because they provide generally useful query functionality. This document provides a reference to all predicates that are part of the language.
This document is quite difficult to read without a thorough understanding of the topic map model. It is recommended to study either XTM 1.0 or TMDM.
Compares two values to ensure they are different.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | object | yes | yes | The first value to compare. |
| v2 | object | yes | yes | The second value to compare. |
The predicate is true when the two values are different. For strings this means the values must be different when compared character by character case-sensitively, including all whitespace and special characters. For topic map objects this means they must be different objects. Null is different from everything except itself.
Note that this predicate cannot produce new rows in the query or new values in any columns; it can only remove rows.
Find all association types with more than two roles
select $TYPE from association-role($ASSOC, $ROLE1), association-role($ASSOC, $ROLE2), $ROLE1 /= $ROLE2, association-role($ASSOC, $ROLE3), $ROLE3 /= $ROLE1, $ROLE3 /= $ROLE2 type($ASSOC, $TYPE)?
This query will first find all association roles and their associations, then repeat each row once for each role in the same association, and finaly remove the rowws where the two roles are the same. The rest of the query is similar, except that the final predicate finds the type of the association.
Compares two values to ensure the first is less than the second.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | string | yes | yes | The first value to compare. |
| v2 | string | yes | yes | The second value to compare. |
The predicate is true when the first value is less than the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.
Find all operas premiered before 1900
premiere-date($OPERA, $DATE), $DATE < "1900"?
Compares two values to ensure the first is less than or equal to the second.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | string | yes | yes | The first value to compare. |
| v2 | string | yes | yes | The second value to compare. |
The predicate is true when the first value is less than or equal to the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.
Find all operas premiered before 1900
premiere-date($OPERA, $DATE), $DATE <= "1900"?
Compares two values to ensure they are equal.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | object | no | yes | The first value to compare. |
| v2 | object | no | yes | The second value to compare. |
The predicate is true when the two values are equal using the same comparison rule as /=. Note that at least one of the values must be present. (That is, it cannot compare two unbound variables.)
Note that unlike /= this predicate can produce new values in columns.
Find all operas premiered on a given date
premiere-date($OPERA, $DATE), $DATE = "1870 (22 Feb)"?
This query will first set $DATE to the given date, then find all operas premiered on that date. (Thanks to the query optimizer; if that is turned off the query will be rather less efficient, if not really slow.)
Compares two values to ensure the first is greater than the second.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | string | yes | yes | The first value to compare. |
| v2 | string | yes | yes | The second value to compare. |
The predicate is true when the first value is greater than the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.
Find all operas premiered after 1900
premiere-date($OPERA, $DATE), $DATE > "1900"?
Compares two values to ensure the first is greater than or equal to the second.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| v1 | string | yes | yes | The first value to compare. |
| v2 | string | yes | yes | The second value to compare. |
The predicate is true when the first value is greater than or equal to the second. Note that this predicate will never bind any values, nor produce any new result rows. Like /= it can only filter out matches.
Find all operas premiered after 1900
premiere-date($OPERA, $DATE), $DATE >= "1900"?
Used to verify that a value is actually an association.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| assoc | association | no | yes | The value being tested. |
This predicate is true if the parameter is an association, and false if it is not. If used with an unbound variable it will produce all associations in the topic map.
Counting the associations in the topic map
select count($ASSOC) from association($ASSOC)?
The above query counts the associations in the topic map by first producing all of them, then counting them.
Finding all association types
select $TYPE from association($ASSOC), type($ASSOC, $TYPE)?
The above query first finds all associations in the topic map, then finds the type of each, and finally reduces the result to only the types.
Used to query the relationship between associations and the roles they contain.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| assoc | association | no | yes | The association containing the roles. |
| role | association role | no | yes | The association role contained in the association. |
This predicate is true for a given association and association role if the association role is contained in the role. Can be used to find the association a role belongs to, all roles in an association, or all roles in all associations.
Finding all unary association types
select $TYPE from association-role($ASSOC, $ROLE1), not(association-role($ASSOC, $ROLE2), $ROLE2 /= $ROLE1), type($ASSOC, $TYPE)?
The above query first finds all roles in all associations, then removes the associations where there exists another role in the same association, finds the type of the association, and projects us down to the list of types. (So for any given type in the result there could be associations that are instances of it which are not unary. This can be solved, but is more involved.)
Finding all associations between two topics
select $ASSOC from role-player($ROLE1, topic1), association-role($ASSOC, $ROLE1), association-role($ASSOC, $ROLE2), role-player($ROLE2, topic2)?
The above query first finds all roles played by topic1, then finds the association of the role, then finds all other roles in the same association, then removes all rows where the second role isn't played by topic2, and finally projects us down to just the associations.
Used to find the base locator of the topic map.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| locator | locator | no | yes | The base locator of the topic map. |
This predicate is true for a single value: the base locator of the topic map, if it has one. (This predicate will become much more useful when the string module is added to tolog.)
Finding the base locator of the topic map
base-locator($LOC)?
This will return the base locator of the topic map, if it has one. For a topic map loaded from a file this will be the URI of the file, while for an RDBMS topic map this will a JDBC URI pointing to the database.
Used to query the types topic are instances of; usually to find the most specific types of the topics.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| instance | topic | no | yes | The instance topic. |
| type | topic | no | yes | The type topic. |
This predicate is true when the instance topic is explicitly defined by the topic map as being an instance of the type topic. (Contrast with instance-of, where this need not be said explicitly.)
Finding all topic types in the topic map
select $TYPE from direct-instance-of($INSTANCE, $TYPE)?
This will find all instance-type pairs in the topic map, then cut away the instances, leaving only the types.
Finding persons and their types
instance-of($PERSON, person), direct-instance-of($PERSON, $TYPE)?
In the opera.hytm topic map this query would first find all instances of the type person (that is, the instances of all subtypes of person, such as composers, librettists, writers, characters, and so on), and then find the types actually given to the topics in the topic map. The result would be something like the table shown below.
Table 3.1. Example query result
| PERSON | TYPE |
|---|---|
| Ulrica | Character |
| La Rocca | Character |
| Maddalena | Character |
| ... | ... |
| Cammarano, Salvatore | Librettist |
| Civinini, Guelfo | Librettist |
| Daudet, Alphonse | Writer |
| ... | ... |
Used to query the types topic are instances of; takes the superclass-subclass association into account.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| instance | topic | no | yes | The instance topic. |
| type | topic | no | yes | The type topic. |
This predicate is true when the instance topic is an instance of the type topic. This can be either directly, or instance can be an instance of a type that is a subtype of type. Note that for this to work the superclass-subclass association type must use the XTM 1.0 PSIs. (Contrast with direct-instance-of, where this needs to be said explicitly in the topic map, and the superclass-subclass associations are ignored.)
Finding all abstract topic types in the topic map
select $TYPE from instance-of($INST, $TYPE), not(direct-instance-of($INST, $TYPE))?
This will find all type-instance pairs, but then remove pairs where it is explicitly said in the topic map that $INST is an instance of $TYPE. This will leave us with only the types which have no direct instances, that is, where all instances are instances of one of the subtypes. Such types are often called abstract types. One example of this in the Italian Opera topic map is "place". There are lots of places, such as cities, regions, and countries, but they are always defined as instances of one of the more specific types, never as just "place".
Used to query object IDs of topic map objects.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | topic map, topic, base name, variant, occurrence, association, association role | no | yes | The topic map object that has the ID. |
| id | string | no | yes | The object ID of the topic map object. |
This predicate is true when the id is the object ID of the object. It can be used to find the object ID of a specific object, to find the object that has a specific ID, or to find all object IDs in the topic map.
Note that the object ID is not the same as the symbolic ID used in XTM or LTM files; for this, see the source-locator predicate.
Finding the object ID of Puccini
object-id(puccini, $ID)?
This query will produce the object ID after having looked up the Puccini topic. Note that the ID will not be "puccini", but rather something like "2532".
Finding the object with ID 241
object-id($OBJECT, "241")?
What this will return for any given topic map can't be predicted (try it in the Omnigator!), but in any non-trivial topic map it will find something.
Used to query the topic-occurrence relationship.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topic | topic | no | yes | The topic that has the occurrence. |
| occurrence | occurrence | no | yes | The occurrence of the topic. |
This predicate is true when the occurrence is an occurrence of the topic. This is useful for finding the topic an occurrence belongs to, or all occurrences of a topic, or just all occurrences in the topic map.
Finding all occurrences of a topic
select $TYPE, $VALUE from
occurrence(topic, $OCC),
type($OCC, $TYPE),
{ resource($OCC, $VALUE) | value($OCC, $VALUE) }?
This query will first find all occurrences of the topic, then the type of the occurrence, then either the URI of the occurrence or its string value, and finally make a (type, value) table of the results.
Finding all persons born on a specific date
select $PERSON from occurrence($PERSON, $OCC), type($OCC, date-of-birth), value($OCC, "1973-12-25")?
This query will first find all occurrences of all topics, then remove the occurrences that are not date-of-birth occurrences, and then remove all occurrences that don't have "1973-12-25" as their value, and finally we project down to only the topics that have these occurrences.
Note that the easiest way to do this is to use a dynamic occurrence predicate:
Finding all persons born on a specific date
date-of-birth($PERSON, "1973-12-25")?
Used to query the relationship between a reifying topic and the thing it reifies.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| reifier | topic | no | yes | The reifying topic. |
| reified | topic map, association, association role, base name, variant, or occurrence | no | yes | The reified topic map construct. |
This predicate is true when the reifier is an topic that reifies the reified. This is useful when you use reification and want to navigate from the name, occurrence, or association to the reifying topic (or vice versa).
Finding the topic reifying the topic map
select $TOPIC from topicmap($TM), reifies($TOPIC, $TM)?
This query finds the topic map first, then the topic reifying it (if there is one).
Redefining the reifies predicate
reifies($T, $O) :- subject-identifier($T, $LOC), source-locator($O, $LOC).
If tolog did not have the reifies predicate, the rule above could have been used to free it.
Used to find the URI of an occurrence or variant name, or to find the occurrences and variant names that have a particular URI.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | occurrence, variant | no | yes | The occurrence or variant which has the URI. |
| locator | string | no | yes | The URI of the occurrence or variant. |
The predicate is true when the occurrence or variant has the locator as its URI value. This is useful for looking up all occurrences/variants with a specific URI, or finding the URI of a variant/occurrence, or all occurrences/variants which have URI values.
Find Ontopia's home page
select $URI from occurrence(ontopia, $OCC), type($OCC, homepage), resource($OCC, $URI)?
This query will find all occurrences of the topic ontopia, then remove the ones that are not homepage occurrences, and finally find the URIs of the ones remaining.
Used to find the topic playing a specific role, or all the roles played by a topic.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| role | association role | no | yes | The role played by the topic. |
| topic | topic | no | yes | The topic playing the role. |
The predicate is true when the topic plays the given role. This is useful for finding all roles played by a topic, or the topic playing a particular role.
Finding all associations between two topics
select $ASSOC from role-player($ROLE1, topic1), association-role($ASSOC, $ROLE1), association-role($ASSOC, $ROLE2), role-player($ROLE2, topic2)?
The above query first finds all roles played by topic1, then finds the association of the role, then finds all other roles in the same association, then removes all rows where the second role isn't played by topic2, and finally projects us down to just the associations.
Used to query the scopes of topic characteristics.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| scoped | base name, variant, occurrence, association | no | yes | The thing having the scope. |
| theme | topic | no | yes | The scoping topic. |
The predicate is true when the theme is a topic in the scope of the scoped thing. This is useful for finding topic characteristics in a particular scope, finding the scope of a topic characteristic, and so on.
Finding the English names of all operas
select $NAME from instance-of($OPERA, opera), topic-name($OPERA, $TNAME), scope($TNAME, english), value($TNAME, $NAME)?
The above query first finds all operas, then all topic names (or base names) of the operas, then removes the names that are not in the English scope, and finally finds the string value of the remaining names.
Used to query the source locators of a topic map construct.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | topic map, topic, base name, variant, occurrence, association, association role | no | yes | The object having the source locator. |
| locator | string | no | yes | The source locator of the object. |
The predicate is true when the locator is a source locator for the object. This is useful for finding the source locators of a particular object, for looking up the object that has a particular source locator, or for listing all source locators in the topic map.
Find all non-topics which have source locators
select $OBJECT from source-locator($OBJECT, $LOC), not(topic($OBJECT))?
This query will, if run against a topic map that was loaded from an XTM file, find all objects in the topic map other than topics which had id attributes. It works by first finding all objects which have source locators (and the source locators), then remove the rows where the object is a topic.
Used to query the subject identifiers of a topic. (A subject identifier is the URI of a subject indicator.)
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topic | topic | no | yes | The topic having the subject identifier. |
| locator | string | no | yes | The subject identifier of the topic. |
The predicate is true when the locator is a subject identifier for the topic. This is useful for finding the subject identifiers of a particular topic, for looking up the topic that has a particular subject identifier, or for listing all subject identifiers in the topic map.
Find all topics which have more than one subject indicator
select $TOPIC from subject-identifier($TOPIC, $LOC1), subject-identifier($TOPIC, $LOC2), $LOC1 /= $LOC2?
The query will first find all subject identifiers in the topic map and the topics that have them, then for each topic find other subject identifiers belonging to it (again), and finally remove the rows where the two subject identifiers are the same.
Used to query the subject locator of a topic. (A subject locator is the URI of the information resource that the topic represents.)
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topic | topic | no | yes | The topic having the subject locator. |
| locator | string | no | yes | The subject locator of the topic. |
The predicate is true when the locator is a subject locator for the topic. This is useful for finding the subject locator of a particular topic, for looking up the topic that has a particular subject locator, or for listing all subject locators in the topic map.
Find all topics which represent an occurrence
select $TOPIC from occurrence($OTHERTOPIC, $OCC), resource($OCC, $LOC), subject-locator($TOPIC, $LOC)?
This query will find all topics which represent information resources that are occurrences of some topic in the topic map. It starts by finding all occurrences, then removes all occurrences which don't have a URI and at the same time notes the URI, and finally finds all topics which have this URI as their subject locator.
Used to verify that an object is a topic or to find all topics in the topic map.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topic | topic | no | yes | The object that is a topic. |
The predicate is true when the topic is a topic. Can be used to find all topics or to verify that some object is a topic.
Count the topics in the topic map
select count($TOPIC) from topic($TOPIC)?
This query will find all topics in the topic map, then count them.
Find all topics which have no name
select $TOPIC from topic($TOPIC), not(topic-name($TOPIC, $NAME))?
This query will find all topics in the topic map, then remove the ones that have at least one name.
Queries the topic-name relationship.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topic | topic | no | yes | The topic that has the name. |
| name | topic name | no | yes | The name of the topic. |
The predicate is true when the topic has the name as a topic name. Note that name is not a string, but an object. To find the string value use the value predicate on the name object. (Example below.)
The predicate can be used to find all names of a topic, the topic that has a particular name, or to find all names in the topic map.
Find all topics named "Tosca"
select $TOPIC from topic-name($TOPIC, $NAME), value($NAME, "Tosca")?
This query will find all topic names in the topic map, then remove the ones whose string value is not "Tosca". Note that this will only find names that match exactly. For inexact matching, use value-like.
Find all topics which have no name
select $TOPIC from topic($TOPIC), not(topic-name($TOPIC, $NAME))?
This query will find all topics in the topic map, then remove the ones that have at least one name.
Finds the topic map.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| topicmap | topic map | no | yes | The topic map. |
The predicate is true when the topicmap is the topic map itself. This is useful for finding the topic map.
Find the name of the topic map
select $VALUE from topicmap($TM), reifies($TMTOPIC, $TM), topic-name($TMTOPIC, $NAME), value($NAME, $VALUE)?
This query will first find the topic map, then the topic that reifies it (if any), then all names of that topic, then their string values.
Queries the type of topic map objects (but not topics).
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | association, base name, occurrence, association role | no | yes | The object having the type. |
| type | topic | no | yes | The type of the object. |
The predicate is true when the object has the type as its type. This can be used to find the type of an object, all objects of a specific type, or all types. This predicate does not take the superclass-subclass associations into account. Also note that for topics the instance-of and direct-instance-of predicates must be used.
Find all association types
select $TYPE from association($ASSOC), type($ASSOC, $TYPE)?
This query will first find all associations, then the type of each association, and finally produce just a list of the types.
Finds the string value of an object.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | base name, variant, occurrence | no | yes | The object having the string value. |
| value | string | no | yes | The string value of the object. |
The predicate is true when the object has the value as its string value. Variant names and occurrences which have URIs have no string value, and so will not be matched by this predicate. The predicate can be used to find the string value of an object, all objects with a specific value, or all string values.
Find all topics named "Tosca"
select $TOPIC from topic-name($TOPIC, $NAME), value($NAME, "Tosca")?
This query will find all topic names in the topic map, then remove the ones whose string value is not "Tosca". Note that this will only find names that match exactly. For inexact matching, use value-like.
Performs a full-text search.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| object | base name, variant, occurrence | no | yes | The object having the string value matched by the full-text search. |
| query | string | yes | yes | The full-text query string. tolog does not define the syntax to be used here; the interpretation depends on the full-text search engine used by the backend, and different backends may well use different search engines. |
| score | float | no | no | The score/relevancy of the matched object. The value is a float greater than 0.0 and less than 1.0. |
The predicate is true when the object has a string value which matches the query. This can be used to find base names, variants, and occurrences matching a particular string. Note that the object found is not a topic, but a base name, variant, or occurrence. The other predicates must be used to connect this to a topic.
Find all topics matching "tosca"
select $TOPIC from
{ topic-name($TOPIC, $NAME), value-like($NAME, "tosca") |
occurrence($TOPIC, $OCC), value-like($OCC, "tosca") |
topic-name($TOPIC, $TN), variant($TN, $V), value-like($V, "tosca")
}?
This query will find all topics in the topic map matching the full-text query, whether the full-text query matches a base name, variant, or occurrence.
Find default names matching "tosca"
select $NAME, $SCORE from topic-name($TOPIC, $NAME), not(scope($NAME, $SCOPE)), value-like($NAME, "tosca", $SCORE), $SCORE >= 0.50 ?
This query makes use of the optional third argument to the value-like predicate. The query finds all unconstrained topic names containing the pattern "tosca", and where the score value is greater than or equal to 0.50. The score value is also included in the projection.
Queries the base name-variant relationship.
| Name | Type | Must be bound | Required | Description |
|---|---|---|---|---|
| basename | base name | no | yes | The base name of which the variant is a variant. |
| variant | variant | no | yes | The variant of the base name. |
The predicate is true when the variant is a variant of the basename. Can be used to find all variants of a base name, the base name of a variant, or all variants.
Note that although XTM allows variants to nest within each other TMDM collapses this structure, and so that structure is not available to be queried in tolog.
Find all topics which have a sort name
select $TOPIC from topic-name($TOPIC, $BASE), variant($BASE, $VARIANT), scope($VARIANT, i"http://www.topicmaps.org/xtm/1.0/core.xtm#sort")?
This query will find all topic names in the topic map together with their topics, then all variants of the topic names, and finally removes the rows where the variant is not in the scope of the sort PSI defined by XTM 1.0.