Ontopia 5.1 2010-06-09
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 Maps 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 Maps model. It is recommended to study the Topic Maps Data Model.
These are predicates that are built directly into the language without being part of any specific module.
/=
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"?
coalesce
This predicate is often used to assign fallback or default values to variables. If the first argument is unbound then it is bound to the first non-null argument following it. If the first argument is bound then it will be compared to the first non-null argument following it.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
result | object | no | yes | The result value. |
v1..vN | object+ | yes | yes | The value to check to see if it is not null. If not null then it will be bound or compared to the result argument. In that case any following arguments will be ignored. |
The coalesce predicate is often used to assign default values, and is quite often used with optional clauses as can be seen in the example below:
Find all operas and their illustrations. Assign a default illustration to the operas that do not have one already.
select $OPERA, $ILLUSTRATION from
instance-of($OPERA, opera), { illustration($OPERA, $I) },
coalesce($ILLUSTRATION, $I, "http://example.org/nicephoto.jpg")?
association
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.
association-role
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.
base-locator
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.
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.
datatype
Finds the datatype of an occurrence or variant name.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | variant, occurrence | no | yes | The object having the datatype. |
datatype | string | no | yes | The URI of the object’s datatype, as a string. |
The predicate is true when the object
has the datatype
as its datatype URI. The predicate can be used to find the datatype of an object, all objects with a specific datatype, or all object/datatype combinations.
Find all occurrences with integer values
select $OCC from
occurrence($TOPIC, $OCC),
datatype($OCC, "http://www.w3.org/2001/XMLSchema#integer")?
This query will find all occurrences in the topic map, then remove the ones whose datatype is not the XML Schema integer datatype.
direct-instance-of
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.ltm
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.
PERSON | TYPE |
---|---|
Ulrica | Character |
La Rocca | Character |
Maddalena | Character |
… | … |
Cammarano, Salvatore | Librettist |
Civinini, Guelfo | Librettist |
Daudet, Alphonse | Writer |
… | … |
instance-of
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”.
item-identifier
Used to query the item identifiers of a topic map construct.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | topic map, topic, topic name, variant, occurrence, association, association role | no | yes | The object having the item identifier. |
locator | string | no | yes | The item identifier of the object. |
The predicate is true when the locator
is a item identifier for the object
. This is useful for finding the item identifiers of a particular object, for looking up the object that has a particular item identifier, or for listing all item identifiers in the topic map.
Find all non-topics which have item identifiers
select $OBJECT from
item-identifier($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 item identifiers (and the item identifiers), then remove the rows where the object is a topic.
object-id
Used to query object IDs of topic map objects.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | topic map, topic, topic 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 item-identifier 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.
occurrence
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")?
reifies
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, topic 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).
resource
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.
role-player
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.
scope
Used to query the scopes of topic characteristics.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
scoped | topic 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.
subject-identifier
Used to query the subject identifiers of a topic. (A subject identifier is the URI of a subject identifier.)
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 identifier
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.
subject-locator
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.
topic
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.
topic-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.
topicmap
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.
type
Queries the type of topic map objects (but not topics).
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | association, topic 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.
value
Finds the string value of an object.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | topic 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.
value-like
Performs a full-text search.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
object | topic 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 topic names, variants, and occurrences matching a particular string. Note that the object found is not a topic, but a topic 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 topic 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.
variant
Queries the topic name-variant relationship.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
topicname | topic name | no | yes | The topic name of which the variant is a variant. |
variant | variant | no | yes | The variant of the topic name. |
The predicate is true when the variant
is a variant of the topicname
. Can be used to find all variants of a topic name, the topic 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, $NAME),
variant($NAME, $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.
It is possible to extend tolog with external fulltext predicates by implementing the SearcherIF
and SearchResultIF
interfaces from the net.ontopia.topicmaps.query.spi
package (see the API documentation for more information). If the class com.foo.MySearcher
implements the SearcherIF
interface, that class can be used in tolog as follows:
import "urn:x-java:com.foo.MySearcher" as fulltext
select $A, $RELEVANCE from
fulltext:search($A, "CMS", $RELEVANCE)
order by $RELEVANCE?
The class name in the import URI is enough for Ontopia to instantiate the class and use it. The actual predicate name (fulltext:search
in the example above) does not need to be significant. The name is passed into the SearcherIF
class, but it is up to the SearcherIF
class to attach significance to the predicate name. (One alternative is to always use a specific name, such as “search”. Another is to use the name to select which full-text index to search.)
The parameters to external fulltext predicates are:
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
result | unspecified | no | yes | This is the value found by the search. The type depends on the searcher implementation. More information about this below. |
query | string | yes | yes | This is the query passed to the external full-text implementation. |
relevance | float | no | no | This is a floating-point number between 0 and 1 indicating the relevance of this item in the search result to the search criteria. 1 indicates the highest relevance, 0 the lowest. |
The SearcherIF
implementation can produce values of different types, as indicated by the getValueType
method. The table below explains the different possible values.
Value type | Result type | Meaning |
---|---|---|
SUBJECT_LOCATOR | topic | The searcher must return a string, and the predicate will return the topic with that subject locator. |
SUBJECT_IDENTIFIER | topic | The searcher must return a string, and the predicate will return the topic with that subject identifier. |
ITEM_IDENTIFIER | topic map object | The searcher must return a string, and the predicate will return the topic map object with that item identifier (a.k.a. source locator). |
OBJECT_ID | topic map object | The searcher must return a string, and the predicate will return the topic map object with that object ID. |
STRING_VALUE | string | The predicate will return the result of calling the toString on the object returned by the searcher. There is no defined Topic Maps interpretation of the string. |
OBJECT_VALUE | any | The predicate will return the the object returned by the searcher. There is no defined Topic Maps interpretation of the object. |
The URI of this module is http://psi.ontopia.net/tolog/string/
. For usage, see the examples.
concat
Concatenates two strings.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | string | no | yes | The concatenated string. |
IN1 | string | yes | yes | The first of the two strings to concatenate. |
IN2 | string | yes | yes | The second of the two strings to concatenate. |
The predicate is true when OUT
is equal to IN1
immediately followed by IN2
.
Concatenate two strings
import "http://psi.ontopia.net/tolog/string/" as str
str:concat($NAME, "Ontopia", " AS")?
This results in a single row with a single column containing the string "Ontopia AS"
.
contains
Tests whether a substring appears in another string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
STR | string | yes | yes | The string to test. |
SUBSTRING | string | yes | yes | The substring that must appear inside STR . |
The predicate is true when SUBSTRING
appears at some position inside STR
.
Find all PSIs defined by Ontopia
import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
subject-identifier($TOPIC, $SI),
str:contains($SI, ".ontopia.net/")?
In the following topic map:
[subtype-of : hierarchical-relation-type = "Subtype of"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
@"http://psi.ontopia.net/occurrence/description"]
The result of this query would be one row, containing "http://psi.ontopia.net/occurrence/description"
.
ends-with
Tests whether a substring appears at the end of another string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
STR | string | yes | yes | The string to test. |
SUFFIX | string | yes | yes | The substring that must appear at the end of STR . |
The predicate is true when SUFFIX
appears as the last part of STR
. In other words, if STR
is the concatenation of some other string and SUFFIX
the predicate is true.
Find all class PSIs
import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
subject-identifier($TOPIC, $SI),
str:ends-with($SI, "class")?
In the following topic map:
[subtype-of : hierarchical-relation-type = "Subtype of"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
@"http://psi.ontopia.net/occurrence/description"]
The result of this query would be three rows, containing "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"
, "http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"
, and "http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"
.
index-of
Finds the first occurrence of a substring within another string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | number | no | yes | The position of the substring. |
IN | string | yes | yes | The string to search in. |
SEARCHFOR | string | yes | yes | The substring to search for. |
The predicate is true when SEARCHFOR
can be found inside IN
starting at position OUT
, and there are no occurrences of SEARCHFOR
at a lower position inside IN
. Position counts start at zero. This means that if the substring cannot be found at all the predicate does not match. Multiple occurrences of the substring later in the string are ignored.
Find the first occurrence of a word in a string.
import "http://psi.ontopia.net/tolog/string/" as str
str:index-of($POS, "The first occurrence of 'the' in the sentence.", "the")?
This results is a single row with a single column containing the position of the left-most occurrence of ‘the’ (all lowercase) in the sentence, i.e. 25
.
last-index-of
Finds the last occurrence of a substring within another string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | number | no | yes | The position of the substring. |
IN | string | yes | yes | The string to search in. |
SEARCHFOR | string | yes | yes | The substring to search for. |
The predicate is true when SEARCHFOR
can be found inside IN
starting at position OUT
, and there are no occurrences of SEARCHFOR
at a higher position inside IN
. Position counts start at zero. This means that if the substring cannot be found at all the predicate does not match. Multiple occurrences of the substring earlier in the string are ignored.
Find all PSI namespaces in a topic map
import "http://psi.ontopia.net/tolog/string/" as str
select $PREFIX from
subject-identifier($TOPIC, $SI),
str:last-index-of($IX, $SI, "/"),
str:substring($PREFIX, $SI, 0, $IX)
order by $PREFIX?
In the following topic map:
[subtype-of : hierarchical-relation-type = "Subtype of"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
@"http://psi.ontopia.net/occurrence/description"]
The result of this query would be two rows, containing "http://www.topicmaps.org/xtm/1.0/"
and "http://psi.ontopia.net/occurrence/"
.
length
Finds the length of a string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
STR | string | yes | yes | The string to test. |
LENGTH | number | no | yes | The number of characters in STR . |
The predicate is true when STRING
contains exactly LEN
characters.
Find the topics with the longest names
import "http://psi.ontopia.net/tolog/string/" as str
select $TOPIC from
topic-name($TOPIC, $TN),
value($TN, $NAME),
str:length($NAME, $LEN),
not(topic-name($TOPIC2, $TN2),
value($TN2, $NAME2),
str:length($NAME2, $LEN2),
$LEN < $LEN2)?
This query will find the topic with the longest name, or almost. What it in fact will do is to find all topics for which there is no topic with a longer name. This means that if, say, three topics all have names 26 characters long, and no topics have longer names, then all those three topics will be found.
starts-with
Tests whether a substring appears at the beginning of another string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
STR | string | yes | yes | The string to test. |
PREFIX | string | yes | yes | The substring that must appear at the beginning of STR . |
The predicate is true when PREFIX
appears inside STR
starting at position 0.
Find all PSIs defined by Ontopia
import "http://psi.ontopia.net/tolog/string/" as str
select $SI from
subject-identifier($TOPIC, $SI),
str:starts-with($SI, "http://psi.ontopia.net/")?
In the following topic map:
[subtype-of : hierarchical-relation-type = "Subtype of"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass-subclass"]
[supertype = "Supertype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#superclass"]
[subtype = "Subtype"
@"http://www.topicmaps.org/xtm/1.0/core.xtm#subclass"]
[descr = "Description"
@"http://psi.ontopia.net/occurrence/description"]
The result of this query would be one row, containing "http://psi.ontopia.net/occurrence/description"
.
substring
Extract part of a string.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | string | no | yes | The resulting string. |
STR | string | yes | yes | The string to operate on. |
FROM | number | yes | yes | The position of the start of the substring. |
TO | number | yes | no | The position of the end of the substring. |
The predicate is true when OUT
is equal to the substring of STR
starting at position FROM
and ending at position TO
(non-inclusive). If TO
is not given, the substring extends to the end of the string. All position counts are zero-based.
Find all PSI namespaces in a topic map
import "http://psi.ontopia.net/tolog/string/" as str
select $PREFIX from
subject-identifier($TOPIC, $SI),
str:last-index-of($IX, $SI, "/"),
str:substring($PREFIX, $SI, 0, $IX)
order by $PREFIX?
This query would produce all PSI namespaces used in a given topic map.
substring-after
Extract part of a string after the first occurrence of a substring.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | string | no | yes | The resulting string. |
STR | string | yes | yes | The string to operate on. |
SUB | string | yes | yes | The substring to search for. |
The predicate is true when OUT
is equal to the substring of STR
after the first occurrence of SUB
within STR
. If there are no occurrences of SUB
the predicate is false.
Get month and day
import "http://psi.ontopia.net/tolog/string/" as str
select $DATE from
str:substring-after($DATE, "2007-03-12", "-")?
This query would produce 03-12
.
substring-before
Extract part of a string before the first occurrence of a substring.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | string | no | yes | The resulting string. |
STR | string | yes | yes | The string to operate on. |
SUB | string | yes | yes | The substring to search for. |
The predicate is true when OUT
is equal to the substring of STR
before the first occurrence of SUB
within STR
. If there are no occurrences of SUB
the predicate is false.
Get month and day
import "http://psi.ontopia.net/tolog/string/" as str
select $DATE from
str:substring-before($DATE, "2007-03-12", "-")?
This query would produce 2007
.
translate
Replace and/or delete characters in one string. Often used to remove whitespace or do case normalization.
Name | Type | Must be bound | Required | Description |
---|---|---|---|---|
OUT | string | no | yes | The resulting string. |
STR | string | yes | yes | The string to operate on. |
FROM | string | yes | yes | The list of characters to translate from. |
TO | string | yes | yes | The list of characters to translate to. |
DELETE | string | no | yes | The list of characters to remove. |
The predicate builds a translation table where the first character in FROM
maps to the first character in TO
(and so on). This is the basic function performed by the predicate.
The predicate is really a mix of the XPath translate
function and the Python translate
function, turned into a predicate. If the DELETE
parameter is provided it behaves like the Python function, and if not it behaves like the XPath function.
That is, if the DELETE
is not present, then the predicate translates characters as specified by the translation table, but any characters for which no mapping has been defined will be deleted. Characters in the FROM
string for which there are no corresponding characters in the TO
string will map to themselves (that is, if FROM
is longer than TO
). Conversely, if TO
is longer than FROM
any excess characters in TO
will be ignored.
Lowercasing
import "http://psi.ontopia.net/tolog/string/" as str
select $OUT from
str:translate($OUT,
"Addis Abeba (12)",
"ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvxyz ",
"abcdefghijklmnopqrstuvxyzabcdefghijklmnopqrstuvxyz ")?
The example above produces "addis abeba " as the output. If we remove the space at the end of the FROM
string the result is “addisabeba”.
If the DELETE
is present, then the predicate translates characters as specified by the translation table and any characters for which no mapping has been defined will be mapped to themselves. Any characters in the DELETE
string will be deleted, of course. If FROM
and TO
are of different lengths the effect is the same as specified above when DELETE
is not present.
Lowercasing
import "http://psi.ontopia.net/tolog/string/" as str
select $OUT from
str:translate($OUT,
"Addis Abeba (12)",
"ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvxyz",
"abcdefghijklmnopqrstuvxyzabcdefghijklmnopqrstuvxyz",
"()")?
The example above produces “addis abeba 12” as the output.