Help:Semantic inline queries

Semantic MediaWiki includes a simple query language for semantic search, so that users can directly request certain information from the wiki. But visitors to the site must still learn the query language in order to use the Special:Ask page effectively. As an alternative, editors can insert dynamic inline queries directly into the pages they create. Such queries, once formulated by a few editors, can then benefit many readers. This is probably the most important and most powerful benefit that Semantic MediaWiki can provide.

Inline queries are very similar to other semantic search features, and are also subject to restriction should the administration deem it necessary to ensure sufficient performance. Inline queries exploit the existing caching mechanisms of MediaWiki, so most requests for a page with such dynamic contents can be served without any performance compromise.

A query interface that allows intuitive assembling of inline queries, without knowing the necessary syntax is provided along with the Halo Extension. The administration is always open to a suggestion for the installation of that extension when semantic annotation becomes extensive.

Inline query formats
Originally an editor could specify an inline query in one of two ways: tag syntax or parser function syntax. But as of SMW version 1.2, tag syntax is now discontinued.

Tag syntax
SMW originally supported the following tag pair:

...

where the &hellip; described the query. For example:

king of::United Kingdom of Israel Accession::*

to obtain a list of all the kings of the United Kingdom of Israel and show their dates of accession.

However, the tag syntax was never a preferred method of specifying an inline query. The developers might or might not have noticed that the processing of the tags interfered with other tags prescribed by other extensions, such as Cite's tags. Thus no one could write inline queries ahead of the tag that captures all the references. Here on CreationWiki, we found that unacceptable, and the developers ultimately decided that parser functions were far more versatile.

Parser function syntax
SMW (beginning with Version 1.0) supports parser function syntax. An editor may use this function either in a template or directly in an article&mdash;although use within a template is much more versatile. The function is:

In this case the first ellipsis is the list of query conditions, and the ellipses between the pipes describe additional properties to print, and parameters to pass. Specify each additional-printout property with a question mark, and specify parameters by name.

This syntax has at least two advantages:


 * 1) The parser function syntax is suitable for use within templates. The old tag syntax was far more difficult to work with. At CreationWiki, repeated tests of this syntax within a template never succeeded.
 * 2) Parser function code, whether used directly or in a template, is not a tag and therefore does not interfere with the processing of tags, such as.

Beginning with SMW 1.2, another parser function became available: the function. Its syntax is

This allows an editor to pull an annotated number, string, date, page name, or other value from another article. It saves the editor the trouble of looking up the value in the article, copying it, and pasting it in the article an editor is working on. It also provides a dynamic value, one that always updates itself if for any reason someone changes the annotated value in the looked-up article. To see two examples, see Nebula theory.

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


 * 1) Which pages are requested?
 * 2) What information should be displayed about those pages?
 * 3) How should the results be formatted within the page?

The first two points are mostly part of the query, and are explained fully at Help:Semantic search. The third point is unique to the inclusion of query results in many pages. In our above example, we might wish to get a numbered king list with each king's date of accession printed in parentheses after his name. This can be achieved by choosing the format "ol":

This third step is rather independent from the other two, and an increasing number of output formats is provided for inline queries. In addition to "format," inline queries accept a number of further parameters, e.g. for sorting the results or for limiting the number of returned items.

Standard settings
A number of standard parameters are always available for customising the result of inline queries. They are:

Result limits and further results
The parameter limit can be used to restrict the maximum number of results that are returned. For example, the query

returns 3 countries in Africa. Even if no value for limit is given, a default limit will apply. One can override this by specifying a higher value for limit. However, SMW imposes an absolute maximum limit on query size. Here on CreationWiki, the current default limit is 50 entries, and the absolute maximum is 500. These limits exist in the SMW settings page and require database access to alter. The administration will keep these and other limits under review.

If the number of retrieved results exceeds a declared, default, or absolute limit, often a link to "further results" will display below the query. The text of this link can be modified in the query using the parameter searchlabel. If the value of searchlabel is "", then the link to further results will not display. Some output formats (see below) never display the search link, or display it only if a searchlabel was specified.

An interesting application of limit and searchlabel is to display only a link to the results of a search, without showing any result inline. To do this, set a limit of "0". For instance, the query

displays a sole link titled "Browse list of planets" if any article in the category of "Planet" is found. Otherwise, nothing will display.

Sorting results
In the case of Special:Ask, additional input fields were used to specify whether and how the result should be ordered (see Help:Semantic search). In the case of inline queries, those settings are specified as parameters. The attribute selected for ordering is assigned to the parameter sort</tt> whereas the order is specified with the parameter order</tt>. The value of order</tt> should be "ascending" or "descending" (or the short forms "asc" and "desc"), where the default setting is "ascending". For example, the inline query

returns all United Kingdom rulers in the order of their accession, and prints this accession date as well. Note that the statement with "+" is needed to restrict the search to pages that have an annotated accession-date value at all, as explained in Help:Semantic search. The statement with "*" in turn makes the result show the accession date in the output. (In the parser-function system, you specify this type of "additional printout field" and precede it with the question mark. Note also that in assigning values to parameters, do not use leading spaces ahead of the equals sign. The parser-function extension will not trim them.)

Configuring labels/table headers
Queries that return more than just the selected articles (e.g. the accession date in the above example), will use labels to describe the various output fields. In the standard tabular view, the labels are used as headers for columns. In other cases, labels might appear right before the output fields.

By default, the labels just display the name of the selected property, or the text "Categories" if categories are displayed (using the statement [[Category:*]] ). This can be changed by using the "|"-notation for alternative labels, as is done links in MediaWiki, or by typing the question mark, then the property name, then an equals sign, then a custom label. For example, the query

returns a table with five columns: the selected articles (unlabeled), the population (labeled "Inhabitants"), the area in km² (labeled "Area (km²)"), bordering countries (labeled "Next to"), and page categories (labeled "Category memberships"). Labels that refer to properties will additionally link to the respective pages in the Property: namespace.

To change the label of the first column, one currently needs to use the parameter mainlabel</tt> which takes an arbitrary text. This might change in future versions to provide an additional simpler method with the parser function syntax.

The display of labels can be controlled with the parameter headers</tt> which currently can take one of two values:


 * "show": display labels (default)
 * "hide": hide all labels or table headers

Introduction and default text
Certain texts should be shown or not shown depending on whether the query has results or not. For example, one may want the query to show an output of the following form:

Upcoming conferences: IJCAI2007, ICCS2007, &hellip;

where the list of conferences is generated by a suitable query. If the query (for whatever reason) would not return any results, the page would look as follows

Upcoming conferences:

which is not desirable. Two parameters exist to prevent this.


 * default</tt>: this parameter can be set to a default text that should be returned when no results are obtained. In the above example, one would probably write something like

Upcoming conferences:


 * so that, if no result is obtained, the article will display

Upcoming conferences: none


 * intro</tt>: this parameter specifies a text that should be prepended to the output of a query, but only if one or more results exist. In the above example, one could write


 * so that, if no result is obtained, nothing will be printed at all. Note that we use "_" to encode the final space. This is needed for initial and final spaces in any parameter, since those are otherwise removed internally (not by SMW).

Both of the above solutions will show the intended output if results are found. It is also possible to combine both parameters if desired. Note that the above parameters only accept simple texts: neither wiki-markup nor HTML-elements are supported at the moment.

Also note that if the set of pages selected in a query is empty, no header row or blank line, not even any blank space, is produced. This can also be useful to "hide" queries that are not applicable. However, it is not recommended to insert great amounts of queries into every page, based on the assumption that this can do no harm since no output is generated. Indeed, answering queries requires much computational resources and should not be done without a purpose.

Output formats
The parameter format</tt> determines how the results of a query are displayed in the article. If it is omitted, all queries are displayed as tables (format table</tt>), unless there would be only one column, in which case the results are displayed as a comma-sepearated list (format list</tt>). The following formats are available:

Using templates
In an inline query, when  format=template </tt> or  format=list </tt>, wiki templates may be used to format the output of the query, using the following syntax:


 *  </tt> or
 *  </tt>.

The template should use numbered parameters; they refer to the results that would be produced by the inline query for each selected page (including that page itself if that would normally be produced) in the same order. Thus, if the selected page itself would normally be produced, this selected page is referred to as </tt>, and the other results are subsequently referred to as ,, ...</tt>. See also below.

The template feature allows greater flexibility in the output of the query, including:


 * Changing the order in which output is displayed, or omitting or duplicating output;
 * Displaying images depending on query results;
 * Creating links for attributes;
 * Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables.

Notes:
 * When output is limited, the template format will not be carried forward to the continuation link.
 * Parser functions applied to parameters (e.g. for computations and branching) do not work.
 * If the selected page itself would normally be produced, this selected page is referred to as </tt>, and the other results are subsequently referred to as <tt>,, ....</tt> If the selected page itself is normally not produced, <tt></tt> refers to the first result about the page. Thus typically different format templates are needed for both cases. To avoid that, when enumerating pages in the query (or specifying a particular one), use parameter "mainlabel" in the query to assign <tt></tt> to the selected page, so that <tt></tt> etc. refer to the same results as when pages are not enumerated in the query.

Using a query to produce wikitext for annotations
When querying for a property, SMW does not (currently) automatically query for transitive or inverse properties. Pages must be ensured to have the properties in the query being made. For example, if there are many pages with the property <tt>king of::United Kingdom of Israel</tt>, if a query is made for its inverse <tt> United Kingdom of IsraelRuled by::* </tt>, SMW will not find these pages.

However, an editor can put an inline query on a scratch page (say, a subpage of his own User page) that will generate a list of these properties that looks like wiki text, and then paste it into the edit box of the page. In this example, [ [ruled by::<ask sep="| ]]ruled by::">[[king of::United Kingdom of Israel | ]]

generates
 * <tt>[ [ruled by::<ask sep="| ]]ruled by::">[[king of::United Kingdom of Israel | ]]</tt>

One can then copy this generated wikitext to the edit box of the United Kingdom of Israel page, remove the space between the first two brackets, and also remove the pipes that follow the names. (User pages are either removed, or the namespace prefix "user:" appears.)

This method is also a good way to provide a backbone for creating a fixed table. A fixed table is preferable to the interactive table that an inline query produces when:


 * 1) The order of presentation is an integral part of the article, and thus the editor would not want this order subject to change by the visitor, or
 * 2) The editor needs to include certain columns in the table that a semantic inline query cannot produce.

Fixed tables also load faster and do not tax the server nearly as much.

CreationWiki also has imported a template that automatically finds pages annotated with any given property and automatically annotates the page that includes it with multiple instances of that property's inverse. Thus

when placed in the article United Kingdom of Israel would annotate that article with multiple instances of the "ruled by" property, each one pointing to a page that itself is annotated with "king of" with the value of "United Kingdom".