Reference Documentation

Table of contents

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.

Index

Parameters

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.

Description

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.

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 or equal to the
second.

Parameters

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.

Description

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.

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 or equal to
the second.

Parameters

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.

Description

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.

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.

Parameters

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.

Description

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.

Used to query the relationship between associations and the roles they
contain.

Parameters

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.

Description

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.

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.)

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.

Parameters

Description

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.

Parameters

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.

Description

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.

Used to query the types topic are instances of; usually to find the
most specific types of the topics.

Parameters

Name

Type

Must be bound

Required

Description

instance

topic

no

yes

The instance topic.

type

topic

no

yes

The type topic.

Description

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.

Used to query the types topic are instances of; takes the
superclass-subclass association into account.

Parameters

Name

Type

Must be bound

Required

Description

instance

topic

no

yes

The instance topic.

type

topic

no

yes

The type topic.

Description

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.)

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".

Description

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.

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.

Description

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.

Parameters

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.

Description

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.

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.

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:

Parameters

Description

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).

Used to find the URI of an occurrence or variant name, or to find the
occurrences and variant names that have a particular URI.

Parameters

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.

Description

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.

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.

Parameters

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.

Description

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.

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 subject identifiers of a topic. (A subject
identifier is the URI of a subject identifier.)

Parameters

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.

Description

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.

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.)

Parameters

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.

Description

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.

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.

Parameters

Description

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.

Parameters

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.

Description

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.

Parameters

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.

Description

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.

Parameters

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.

Description

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.

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.

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:

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 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".

Parameters

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.

Description

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.

Parameters

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.

Description

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.

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.

Description

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.

Replace and/or delete characters in one string. Often used to remove
whitespace or do case normalization.

Parameters

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.

Description

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.

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 DELETEis 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.