Help:Inline queries

From Wiki@OntoWorld

Jump to: navigation, search

Semantic MediaWiki Docu

Annotations

Semantic templates

Browsing and searching

Inline queries

External tools

Semantic Web

RDF export

Importing vocabulary

Ontology import

SPARQL endpoint

Installation

Semantic MediaWiki includes an easy-to-use query language which enables users to access the wiki's knowledge. The syntax of this query language is very similar to the syntax of annotations in Semantic MediaWiki that many editors of the wiki are already familiar with. Readers who do not wish to learn the query syntax can still profit from this feature: inline queries dynamically include query resutls into articles. So queries once formulated by a few editors can then be consumed by many readers.

Naturally, answering queries requires additional resources, and the administrators of some site can decide to switch off or restrict most of the features given below in order to ensure that even high-traffic sites can handle the additional load. Moreover, since inline queries exploit the existing caching mechanisms of MediaWiki, most requests for an article with such dynamic contents can be served without any performance impact whatsoever.

The documenation below applies to Semantic MediaWiki of version 0.4.3 and above.

Contents

Introduction

Inline queries are written in the wiki-text of some page by writing text of the form

<ask ...>...</ask>

where the … describe the query. The part between the two ask-tags contains (among other things) conditions that describe what is asked for. For example, the query:

<ask>[[Category:Actor]]</ask>

is a query for all articles within the category "Actor", i.e. for all actors. At the place where this query is inserted into the wiki-text, a simple list of all requested articles will be displayed within the page. Otherwise, everything between <ask> and </ask> is ignored, so that the above example will not add the current article to the category Actor. Much more complex queries are possible, but let us first explain some important things about queries.

In general, an inline query is a request to find a number of articles that satisfy certain requirements. The query must answer three questions:

  1. Which articles are requested?
  2. What information should be displayed about those articles?
  3. How should the results be formated within the article?

The first point is obvious. The second point is important to retrieve more knowledge. In the example above, one might be interested in all actors and their date of birth. This requires two steps: first find all actors; second print out their names and dates of birth. The third point is important to be able to smoothly include query results in many articles. In our running example, we might wish to get a bulleted list of actors with date of birth printed in parentheses after each actor. Again, this third step is rather independent from the other two. Each of the three points are now explained independently in the sections below.

What articles are searched?

In the example above, we gave the single condition [[Category:Actor]] to describe which articles we were interested in. The condition here is exactly what one would otherwise write to assert that some article is in the category Actor. The enclosing ask-tags invert its meaning to return all such articles (actually some more; but read on). This is a general scheme: The syntax for asking for articles that satisfy some condition is exactly the syntax for explicitly asserting that this condition holds.

The following queries show what this means:

  1. <ask>[[Category:Actor]]</ask> asks for everybody (or everything) annotated as being an actor.
  2. <ask>[[born in::Boston]]</ask> asks for everybody (or everything) annotated as being born in Boston.
  3. <ask>[[height:=180cm]]</ask> asks for everybody (or everything) annotated as having a height of 180cm.

By using other categories, relations, or attributes than above, we can already ask for articles which have certain annotations. Next let us combine those requrirements:

<ask>[[Category:Actor]] [[born in::Boston]] [[height:=180cm]]</ask> 

asks for everybody who is an actor and was born in Boston and is 180cm in tall. In other words: when many conditions are written into one query, the result is narrowed down to those articles that meet all the requirements. By the way: queries can also include line-breaks in order to make them more readable for other editors. So we could as well write:

<ask>
  [[Category:Actor]] 
  [[born in::Boston]] 
  [[height:=180cm]]
</ask>

to get the same result as above. This said, we are ready to explore some more powerful querying functions.

Wildcards and disjunctions

In the examples above, we pgave very concrete conditions, using "Actor", "Boston", and "180cm" as fillers. It is possible to weaken these conditions in several ways.

Wildcards are written as "+" and allow any filler for a given condition. For example, <ask>[[born in::+]]</ask> returns all articles that have some annotations for relations "born in", and <ask>[[height:=+]]</ask> returns everything that has been asigned some height. For categories, this feature makes little sense: <ask>[[Category:+]]</ask> just returns everything that has some category.

Disjunctions are written as "||" and allow queries to require (at least) one out of several possible fillers. For example, <ask>[[Category:Musical actor||Theatre actor]]</ask> retrieves everything that is a musical actor or a theatre actor. This also includes everything that is both, i.e. we really have a logical OR here. The same works for relations, e.g. <ask>[[born in::Boston||New York]]</ask>. For attributes, disjunctions currently are not supported (but read on for other helpful means of relaxing attribute conditions).

Asking for categories

Conditions with categories are generally simple, but they are more powerful than they might at first appear:

When searching for articles within a category, the result also involves all articles that are contained in subcategories of this category.

For example, assume that we have a category "Theatre actor" which is a subcategory of "Actor". Then the query <ask>[[Category:Actor]]</ask> will also return those "special" actors that are in the category "Theatre actor" only. This makes sense in many situations, but you can still view the articles that where directly put into the category actor by just going to the article of that category (by following the link [[:Category:Actor]]).

Conditions with attributes

With attribute values, we are usually not looking for exact results, but rather for entities that are included within a certain range. For example

<ask>[[Category:Actor]] [[height:=>6 ft]] [[height:=<7 ft]]</ask>

asks for all actors that are at least 6 feet and at most 7 feet tall. Here we take advantage of the automatic unit conversion: even if the height of the actor was set with [[height:=195cm]] it would be recognized as a correct answer.

Such range conditions on attributes are mostly releavent for attributes with values that can be ordered in a natural way. For example, it makes sense to ask <ask>[[start date:=>May 6 2006]]</ask> but is is not really helpful to say <ask>[[homepage URL:=>http://www.somewhere.org]]</ask>.

If a datatype has no natural linear ordering, Semantic MediaWiki will just apply the alphabetical order to the normalized datavalues as they are used in the RDF export.

Direct conditions on articles

So far, all conditions depended on some or the other annotation given within an article. But there are also conditions that directly select some articles, or articles from a given namespace.

By directly giving a link to some article, it is possible to "preselect" exactly this article for a query. For example, <ask>[[Bill Murray]]</ask> will return exactly this single article. This might not seem very helpful, but can be of great use when combined with the features described in the next section. Even now, this direct selection of articles can be combined with disjunctions as explained above, so that one could ask, e.g., "Who of Bill Murray, Dan Aykroyd, Harold Ramis and Ernie Hudson is taller than 7ft?"

In the case of categories, it is necessary (as known from normal articles) to put a ":" before the article name to prevent confusion of the conditions [[Category:Actor]] (return all actors) and [[:Category:Actor]] (return the category "Actor").

A less strict way of selecting given articles is via namespaces. This is done by using wildcards in the selected articles, e.g. by writing

<ask>[[Help:+]]</ask>

to return every article in the "Help" namespace. Since the main namespace usually has no prefix, one must write <ask>[[:+]]</ask> in this case. In the case of categories, an additional ":" is again needed in front of the namespace label to prevent confusion.

What should be displayed?

Simple queries using conditions as above will merely return a list of articles. To display further properties of these articles, one adds statements such as [[height:=*]] to show the height (if any) of the selected articles. Using "*" as a filler always indicates that a "condition" is really just a request for print-out. Thus, we can also write

  • [[born in::*]] to show all articles that have a "born in" relation to the result article,
  • [[Category:*]] to show all categories that the result article has directly been stated to be in.

Such print-out statements do not affect the selected set of articles. So it does not matter whether an article has no, one, or many "born in" relations – all will be printed for all of the retrieved articles.

How should the results be displayed?

The resulting list is a comma separated list. The separator may be set explicitly in the query with the "sep"-attribute (see below for all attributes) in the opening <ask>-tag, in order to customize the output as needed. To capture the two most common styles for lists, the user may use instead the format-attribute. The following query returns everything located in Boston as a bullet list:

<ask format="ul">[[located in::Boston]]</ask>

Instead of a "ul" (named after HTML's ul-tag), also an ordered and numbered list may be asked for by using "ol" as the format, or a real table (format="table"). Tables created by Semantic MediaWiki are connected by the delivered stylesheet to a Javascript program that allows the user to sort the displayed table by columns inside the browser. Tables are also the only possibility to render more complex queries that need more than one column, like the following table that returns all actors, together with their place of birth and height.

<ask>[[Category:Actor]] [[born in::*]] [[height:=*]]</ask>}

The name of the relation or attribute is used as the header. If an alternative header should be used, the well-known Wikipedia syntax for alternative texts can be used.

<ask>[[Category:Actor]] [[born in::*|P
Personal tools