Difference between revisions of "Help:Inline queries"

MyWikiBiz, Author Your Legacy — Thursday March 28, 2024
Jump to navigationJump to search
m (Help:Inline Queries moved to Help:Inline queries: Conform to SMW)
 
(14 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
</blockquote>
 
</blockquote>
  
[http://meta.wikimedia.org/wiki/Semantic_MediaWiki Semantic MediaWiki] includes a simple query language for [[Help:Semantic search|semantic search]], so that users can directly request certain information from the wiki. Readers who do not wish to learn the query syntax can still profit from this feature: '''inline queries''' dynamically include query results into pages. So queries once formulated by a few editors can then be consumed by many readers.  
+
[http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki] includes a simple query language for [http://semantic-mediawiki.org/wiki/Help:Semantic_search semantic search], so that users can directly request certain information from the wiki. Readers who do not wish to learn the query syntax can still profit from this feature: '''inline queries''' dynamically include query results into pages. So queries created by a few editors can be consumed by many readers.  
  
Inline queries are very similar to other semantic search features, and can also be restricted on a site in order to ensure sufficient performance. Since inline queries exploit the existing caching mechanisms of [[MediaWiki]], most requests for a page with such dynamic contents can be served without any performance impact whatsoever.
+
Inline queries are similar to other semantic search features, and can also be restricted on a site in order to ensure sufficient performance. Since inline queries exploit the existing caching mechanisms of [http://mediawiki.org/wiki/MediaWiki | MediaWiki], most requests for a page with such dynamic contents can be served without any performance impact whatsoever.
  
''The documentation below applies to Semantic MediaWiki of version 0.6 and above.''
+
== Introduction to #ask ==
  
== Introduction ==
+
The basic way of writing an inline query is to use the parser function <tt>#ask</tt>. The query string (See [http://semantic-mediawiki.org/wiki/Help:Selecting_pages selecting pages] for syntax) and any [http://semantic-mediawiki.org/wiki/Help:Displaying_information|printout statements] are directly given as parameter, like in the following example:
  
Inline queries are written in the wiki-text of a page by writing text of the form
+
<pre><nowiki>
 +
{{#ask: [[Category:City]] [[located in::Germany]]
 +
| ?population
 +
| ?area#km² = Size in km²
 +
}}</nowiki></pre>
  
<nowiki><ask ...>...</ask></nowiki>
+
Here we query for all cities located in Germany, and two additional printout statements are used (a simple one and one with some extra settings). This displays the following result on a page:
  
where the &hellip; describes the query. The part between the two ask-tags can be any query, as described in the help page to [[Help:Semantic search|semantic search]]. For example, one can write
+
{{#ask: [[Category:City]] [[located in::Germany]]  
 +
| ?population
 +
| ?area#km² = Size in km²
 +
}}
  
<nowiki><ask>[[Category:Country]] [[located in::Africa]] [[Population:=*]]</ask></nowiki>
+
It is common to put the query as the first parameter behind <tt>#ask:</tt>. All other parameters are separated by <tt>|</tt>, just like for other [http://semantic-mediawiki.org/wiki/meta:Help:Parser_function parser functions]. The exact formatting of the inline query is not essential, but it is good to use line breaks to make it more readable to other editors. As with all templates, one line per parameter, starting with the <tt>|</tt> is most accepted in practice.
  
to obtain a list of all African countries and show their population number. At the place where this query is inserted into the wiki-text, a simple list of all requested pages will be displayed within the page. Besides this, everything between <nowiki><ask></nowiki> and <nowiki></ask></nowiki> is ignored, so that the above example will not add the current page to the category Country. In a simliar way, all kinds of queries can be embedded inline.
+
Note that all the arguments to the #ask: function are ignored by the page parsing, hence the above example does not add a category or a «located in» property annotation to this page. A few more things to note are:
 +
* The pipe '<tt>|</tt>' symbol is used to separate the conditions from the property to display.
 +
* The conditions for display are a single argument to the <tt>#ask</tt> function, so there are no '<tt>|</tt>' symbols between them.
 +
* White space and line breaks can be used within the <tt>#ask</tt> function, SMW is fairly flexible there.
 +
* The format of the results display changes when you request display of additional properties. SMW picks an appropriate default format for query results, but you also have detailed control of the appearance of query results.
 +
 
 +
Knowing the basics of [http://semantic-mediawiki.org/wiki/Help:Selecting_pages query string] and [http://semantic-mediawiki.org/wiki/Help:Displaying_information printout statements] therefore is enough to write many kinds of queries. But there are many cases where the standard table output of a query may not be the best choice, or where further settings are desired (like the maximum number of results that should be displayed). For this purpose, inline queries have a number of other possible parameters that one can use to control their appearance in detail. The general syntax for <tt>#ask</tt> therefore is the following:
 +
 
 +
<nowiki>{{</nowiki>#ask: <i>argument 1</i> | <i>argument 2</i> | &hellip; <nowiki>}}</nowiki>
 +
 
 +
Most of this page explains the various arguments one may use in inline queries.
 +
 
 +
Prior to Semantic MediaWiki 1.0 there was a different syntax for inline queries using an <tt><nowiki><ask></nowiki></tt> tag, which is still enabled on some wikis. Please see the [http://semantic-mediawiki.org/wiki/Help:Inline_queries_0.7 old documentation page] for details on this feature. It is strongly recommended to use only the new syntax now.
 +
 
 +
== The #show parser function ==
 +
 
 +
A common usage of queries is to display only a single property value for a single page. For example, one could insert the population of Berlin into some article, and use a query instead of manual copying to achieve this.  SMW has a special shortcut to make such queries simpler. For example, one can write
 +
 
 +
<nowiki>{{#show: Berlin | ?population}}</nowiki>
 +
 
 +
to display the population of Berlin (Result: «{{#show: Berlin | ?population}}»). The function otherwise works like an inline query, and all parameters available for inline queries can also be used on #show if desired. The above function can also be written as an #ask query as follows:
 +
 
 +
<nowiki>{{#ask: [[Berlin]] | ?population = }}</nowiki>
 +
 
 +
Here the equality symbol assigns another label for displaying the property, and this label is empty. Without this, the result would display «Population:» before the actual number.
 +
 
 +
== Standard parameters for inline queries ==
  
 
In general, an inline query is a request to find a number of '''pages''' that satisfy certain requirements. The query must answer three questions:
 
In general, an inline query is a request to find a number of '''pages''' that satisfy certain requirements. The query must answer three questions:
  
# Which pages are requested?
+
# Which pages are requested? ([http://semantic-mediawiki.org/wiki/Help:Selecting_pages query description])
# What information should be displayed about those pages?
+
# What information should be displayed about those pages? ([http://semantic-mediawiki.org/wiki/Help:Displaying_information printout statements])
# How should the results be formated within the page?
+
# How should the results be formatted within the page?
  
The first two points are mostly part of the query, and have been explained at [[Help:Semantic search]]. The third point is important to be able to smoothly include query results in many pages. In our above example, we might wish to get a bulleted list of countries with population printed in parentheses after each country. This can be achieved by choosing the format "ol":
+
The first two points are explained in their respective manual pages. The third point is important to smoothly include query results in pages, yet is largely independent of the first two. Without further settings, queries often produce tables like above or simple lists (if no additional printouts are used). An example of another possible format are bulleted lists, which one can create with the parameter <tt>format=ol</tt>:
  
<pre><ask format="ol">
+
<pre>{{#ask: [[Category:City]] [[located in::Germany]]  
  [[Category:Country]]  
+
| ?Population
  [[located in::Africa]]  
+
| format=ul
  [[Population:=*]]
+
}}</pre>
</ask></pre>
 
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 ==
+
This will produce the following output:
  
A couple of standard parameters are always available for customising the result of inline queries. Here is a short overview:
+
{{#ask: [[Category:City]] [[located in::Germany]]
 +
| ?Population
 +
| format=ul
 +
}}
 +
 
 +
SMW implements a wide variety of output formats for inline queries, and allows you to futher control results display using a MediaWiki template. The parameter <tt>format</tt> is one of the most important parameters for selecting the appearance of query results and will be explained in more detail below. The following table gives an overview of common parameters that can be used in basically all queries:
  
 
{| class="smwtable"
 
{| class="smwtable"
! Paramter
+
! Parameter
 
! Possible values
 
! Possible values
 
! Description
 
! Description
 
|-
 
|-
| limit  
+
| <tt>format</tt>
 +
| a format name (see below)
 +
| selected output format; some formats allow further parameters (see [[#Result formats]])
 +
|-
 +
| <tt>limit</tt>
 
| non-negative number
 
| non-negative number
 
| maximal number of pages selected (in the case of a table: rows)
 
| maximal number of pages selected (in the case of a table: rows)
 
|-
 
|-
| sort  
+
| <tt>offset</tt>
| attribute name
+
| number
| name of attribute to use for sorting queries; this attribute must occur in the query in a statement without "*"
+
| where to start
 +
|-
 +
| <tt>sort</tt>
 +
| property name or a list of property names separated by ,
 +
| name of properties to use for sorting queries (see [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages])
 +
|-
 +
| <tt>order</tt>
 +
| <tt>ascending</tt>/<tt>asc</tt>, <tt>descending</tt>/<tt>desc</tt>/<tt>reverse</tt>,<br />or a list of those if more than one property is used for sorting
 +
| defines how results should be ordered, only applicable if <tt>sort</tt> is used, <tt>ascending</tt> is the default (see [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages]])
 
|-
 
|-
| order
+
| <tt>headers</tt>
| "ascending"/"asc", "descending"/"desc"/"reverse"
+
| <tt>show</tt>, <tt>hide</tt>
| defines how results should be ordered, only used if <tt>sort</tt> is used, "ascending" is the default
+
| shows or hides the labels/headers used in some output formats such as «table», <tt>hide</tt> is default
 
|-  
 
|-  
| headers
+
| <tt>mainlabel</tt>
| "show", "hide"
 
| shows or hides the labels/headers used in the output, "hide" is deault
 
|-
 
| mainlabel
 
 
| plain text
 
| plain text
| title of the first column (the one with the page titles in it)
+
| title of the first column (the one with the page titles in it), default is no title; set to <tt>-</tt> to suppress printing the page titles
 
|-
 
|-
| link  
+
| <tt>link</tt>
| "none", "subject", "all"
+
| <tt>none</tt>, <tt>subject</tt>, <tt>all</tt>
| defines which article names in the result are hyperlinked, "subject" normally is the default
+
| defines which article names in the result are hyperlinked, <tt>all</tt> normally is the default
 +
 
 +
Note: linking can also be controlled for individual printouts using the ''plain output format'' as described in [[Help:Displaying_information#Display_format|Displaying information]].
 
|-
 
|-
| default  
+
| <tt>default</tt>
 
| plain text
 
| plain text
| if, for any reason, no result is being created, this will be returned
+
| if, for any reason, the query returns no results, this will be printed instead
 
|-
 
|-
| intro  
+
| <tt>intro</tt>
 
| plain text
 
| plain text
| initial text that is prepended the output, if at least some results exist
+
| initial text that prepends the output, if at least some results exist
 
|-
 
|-
| debug
+
| <tt>outro</tt>
| "true"
+
| plain text
| gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results
+
| text that is appended to the output, if at least some results exist
 
|-
 
|-
| format
+
| <tt>searchlabel</tt>
| a format name (see below)
+
| plain text
| selected output format, some formats allow further parameters (see below)
+
| text for continuing the search (default is «&hellip; further results»)
 
|}
 
|}
  
=== Result limits and further results ===
+
In addition to the above, some formats have their own parameters that control special aspects of the format. These special settings are described in the documentation of each format.
 +
 
 +
=== Result limits and links to further results ===
 +
 
 +
You can set the parameter <tt>limit</tt> to restrict the maximum number of results that are returned. For example, the query
 +
 
 +
<pre>{{#ask: [[Category:City]] [[located in::Germany]]
 +
  | limit=3
 +
}}</pre>
 +
 
 +
displays at most 3 cities in Germany. Even if you do not specify a value for <tt>limit</tt>, SMW always applies some limit to the results a query returns. Depending on a site's settings, it might be possible to increase the number of displayed results by specifying a higher value for <tt>limit</tt>. However, there is usually a maximum limit that cannot be exceeded, set by the wiki administrator based on performance considerations.
 +
 
 +
Running the above query produces: {{#ask:
 +
  [[Category:City]]
 +
  [[located in::Germany]]
 +
  | limit=3
 +
}}
 +
 
 +
This shows that whenever a query does not display all results due to a limit, it will normally show a link to «further results».  The text of this link can be modified by setting the parameter <tt>searchlabel</tt>. If the value of <tt>searchlabel</tt> is empty, then no link to further results appears. Some output formats (see below) never display the search link, or display it only if a searchlabel was specified.
 +
 
 +
An interesting application of <tt>limit</tt> and <tt>searchlabel</tt> is to display ''only'' a link to the results of a search, without showing any result inline.
 +
You achive this by specifying a limit of «0» or «-1». For instance, the query
 +
 
 +
<nowiki>{{#ask: [[Category:City]] | limit=0 | searchlabel=Click to browse a list of cities }}</nowiki>
 +
 
 +
displays: {{#ask: [[Category:City]] | limit=0 | searchlabel=Click to browse a list of cities }}. this link will only appear if there are any results at all. In other words, SMW will still compute the query to check if there are any results. If this is not needed, or if a link should be shown in any case, one can use the limit «-1». SMW will then only print a link to further results, even if no results exist at all. This also saves some computation time on the server.
 +
 
 +
=== Introduction and default text ===
  
The parameter <tt>limit</tt> can be used to restrict the maximum number of results that are returned. For example, the query  
+
If no articles satisfy the conditions of a query, ''nothing is shown''. This is sometimes a useful behaviour, but often 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:
  
<pre><ask limit="3">
+
Upcoming conferences: [[semanticweb:ISWC2008|ISWC2008]], [[semanticweb:IJCAI2007|IJCAI2007]], &hellip;
  [[Category:Country]]  
 
  [[located in::Africa]]  
 
</ask></pre>
 
  
returns 3 countries in Africa. Even if no value for <tt>limit</tt> is given, there is a default limit that will be used. Depending on a sites settings, it might be possible to increase the number of displayed results by specifying a higher value for <tt>limit</tt>. However, there is usually a maximum limit that cannot be exceeded. Its value is specified by the site administrators based on performance considerations.
+
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
  
If not all results of a query have been displayed due to a restricted limit, there will often be a link to "further results" that is displayed below the query. The text of this link can be modified by setting the parameter <tt>searchlabel</tt>. If the value of <tt>searchlabel</tt> is "", then the link to further results will no be shown. Some output formats (see below) do never display the search link, or display it only if a searchlabel was specified.
+
Upcoming conferences:
  
An intersting application of <tt>limit</tt> and <tt>searchlabel</tt> is to display ''only'' a link to the results of a search, without showing any result inline. This is done by selecting a limit of "0". For instance, the query
+
which is not desirable. Two parameters exist to prevent this.
  
<nowiki><ask limit="0" searchlabel="Browse list of countries">[[Category:Country]]</ask></nowiki>
+
* <tt>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
  
displays a sole link entitled "<ask limit="0" searchlabel="Browse list of countries" default="Browse list of countries">[[Category:Country]]</ask>" if any country is found. Otherwise, nothing is shown.
+
Upcoming conferences: <nowiki>{{#ask: ... | default=none}}</nowiki>
  
=== Sorting results ===
+
: so that, if no result is obtained, the article will display
  
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 paramters. The attribute selected for ordering is assigned to the parameter <tt>sort</tt> whereas the order is specified with the parameter <tt>order</tt>. The value of <tt>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
+
Upcoming conferences: none
  
<pre><ask order="population" sort="descending">
+
* <tt>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
  [[Category:Country]]
 
  [[located in::Africa]]
 
  [[population:=+]]
 
  [[population:=*]]
 
</ask></pre>
 
  
returns all African countries ordered by population, and prints this population as well. Note that the statement with "+" is needed to restrict the search to pages that have a population value at all, as explained in [[Help:Semantic search]]. The statement with "*" in turn makes the result ''show'' the population number in the output.
+
<nowiki>{{#ask: ... | intro=Upcoming conferences:_}}</nowiki>
  
=== Configuring labels/table headers ===
+
: 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 (this is always the case in MediaWiki and is not specific to SMW).
  
Queries that return more than just the selected articles (e.g. the population 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.
+
Both of the above solutions will show the intended output if results are found. It is also possible to combine both parameters if desired. The parameters can also include MediaWiki markup, such as links or templates, as long as this does not confuse MediaWiki in recognising the <tt>#ask</tt> function.
  
By default, the labels just display the name of the selected attribute or relation, or the text "Categories" if categories are displayed (using the statement <nowiki>[[Category:*]]</nowiki>). This can be changed by using the "|"-notation for alterantive labels, as it is known for links in MediaWiki. For example, the query
+
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.
  
<pre><ask>
+
Using default texts for queries is also a good habit in general, since it may happen that a query will no longer have any results in some future, e.g. due to changes in the way the wiki organises its data. Such queries that once worked properly may be forgotten so that nobody notices the query on a page labouring to display nothing.
[[Category:Country]]
 
[[Population:=*|Inhabitants]]
 
[[Area:=*km²|Size in km²]]
 
[[borders::*|Next to]]
 
[[Category:*|Category memberships]]
 
</ask></pre>
 
  
returns a table with five columns: the selected articles (unlabeled), the population (labeled "Inhabitants"), the area in km² (labeled "Size in km²"), bordering countries (labeled "Next to"), and page categories (labeled "Category memberships"). Labels that refer to attributes or relations will additionally link to the respective pages in the Attribute: and Relation: namespaces.
+
=== Sorting results ===
  
<ask limit="1" searchlabel="..."> [[Category:Country]] [[Population:=*|Inhabitants]] [[Area:=*km²|Size in km²]] [[borders::*|next to]]  [[Area:=+]] [[Population:=+]]  [[Category:*|Category memberships]]</ask>
+
It has been explained in [http://semantic-mediawiki.org/wiki/Help:Selecting_pages selecting pages] that query results can be ordered by one or more properties. As explained there, [[Special:Ask]] has additional input fields to specify sort properties and ordering. In inline queries, sort properties are defined with the parameter <tt>sort</tt>, and the order can be set with the parameter <tt>order</tt>. The value of <tt>order</tt> should be «<tt>ascending</tt>» or «<tt>descending</tt>», or one of the short forms «asc» and «desc», or «reverse». You can also set the value to «<tt>random</tt>» (or «<tt>rand</tt>») for ordering results in an essentially random way (this feature can be disabled by the site administrator, see [http://semantic-mediawiki.org/wiki/Help:Configuration Configuration]). An example is the following query for the three largest cities in Germany:
  
To change the label of the first column, one currently needs to use the parameter <tt>mainlabel</tt> which takes an arbitrary text. ''This might change in future versions to provide an additional simpler method with the |-syntax.''
+
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
 +
| ?Population
 +
| sort=Population
 +
| order=descending
 +
| limit=3
 +
}}</pre>
  
The '''display of labels''' can be controlled with the parameter <tt>headers</tt> which currently can take one of two values:
+
As explained in [http://semantic-mediawiki.org/wiki/Help:Selecting_pages Selecting pages], sorting conditions may impose restrictions on the set of query results. In the above case, only German cities that have a value for population are considered. If more than one property is used for sorting, the parameters <tt>sort</tt> and <tt>order</tt> can be set to lists of property names and orders, repsectively, separated by commas. The following is an example:
  
* "show": display labels (default)
+
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
* "hide": hide all labels or table headers
+
| ?State
 +
| ?Population
 +
| sort=State,Population
 +
| order=ascending,descending
 +
}}</pre>
  
=== Introduction and default text ===
+
This query would return all German cities for which a state and population was specified. These results will be ordered by the name of the state they are located in (ordered alphabetically). Cities that are located in the same state will be ordered by their population, largest first («descending»).
  
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:
+
=== Configuring labels/table headers ===
  
Upcoming conferences: [[IJCAI2007]], [[ICCS2007]], &hellip;
+
Queries that return more than just the selected articles (e.g. the population in the above example) will display labels that describe the various output fields. By default, the label just displays the name of the requested property, or the text «Category» if categories are displayed. Labels for properties normally display as a link to the respective pages in the Property: namespace.
  
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 a follows
+
In the table format, the labels appear as column headers. In other formats, the labels might appear right before the output fields. The texts used for these labels can be controlled as explained in [http://semantic-mediawiki.org/wiki/Help:Displaying_information Displaying information], using the equality symbol after printouts. Example:
  
  Upcoming conferences:
+
<pre>{{#ask: [[Category:City]]
 +
|?Population=
 +
| ?Area#km²=Size in km²
 +
| ?Category=Category memberships
 +
| format=table
 +
| default=nothing found in Category:City
 +
}}</pre>
 +
This query will produce:
 +
{{#ask: [[Category:City]]
 +
| ?Population=
 +
| ?Area#km²=Size in km²
 +
| ?Category=Category memberships
 +
| format=table
 +
  | default=nothing found in Category:City
 +
}}
  
which is not desriable. Two parameters exist to prevent this.
+
It is possible to use empty printout labels to have no label for a result column at all. In tables, however, the table header will still be shown even if all printouts use empty labels. To remove the header of a table completely, the parameter <tt>headers</tt> can be used. Three values are possible:
  
* <tt>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
+
* <tt>show</tt>: display labels (default)
 +
* <tt>plain</tt>: show labels and headers, but a plain text without links (available since SMW 1.4.3)
 +
* <tt>hide</tt>: hide all labels and table headers
  
Upcoming conferences: <nowiki><ask default="none">...</ask></nowiki>
+
This setting works for tables as well as for other outputs. In the latter case, the value <tt>hide</tt> will hide all printout labels, even if they have a non-empty label set in the query.
  
: so that, if no result is obtained, the article will display
+
=== Changing the first result column ===
  
Upcoming conferences: none
+
Most queries by default display the actual result pages in the first result position, e.g. as the first column in a table. The header of this column is usually blank. To change the label, or to hide the whole first column, the parameter <tt>mainlabel</tt> can be used. Normally, the text given to that parameter will simply be used as a header for the first column, for example in the query
  
* <tt>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
+
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
 +
| mainlabel=City
 +
| ?Population=Number of inhabitants
 +
| limit=3
 +
}}</pre>
  
  <nowiki><ask intro="Upcoming conferences:_">...</ask></nowiki>
+
This will produce the table:
 +
{{#ask: [[Category:City]] [[Located in::Germany]]
 +
  | mainlabel=City
 +
| ?Population=Number of inhabitants
 +
| limit=3
 +
}}
  
: 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).
+
The parameter <tt>mainlabel</tt> can also be used to completely hide the first column. This happens if the value of this parameter is set to «-» (minus symbol). To insert the list of main results at another position, the printout statement «?», i.e. the question mark without any additions, can be used. For example, modifying the example above to display the city name after Population,
  
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 aboe parameters only accept simple texts: neither wiki-markup nor HTML-elements are supported at the moment.
+
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
 +
| ?Population=Number of inhabitants
 +
| ?=City
 +
| mainlabel=-
 +
| limit=3
 +
}}</pre>
  
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.
+
This results in the table:
 +
{{#ask: [[Category:City]] [[Located in::Germany]]
 +
| ?Population=Number of inhabitants
 +
| ?=City
 +
| mainlabel=-
 +
| limit=3
 +
}}
  
== Output formats ==
+
== Result formats ==
  
The parameter <tt>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 <tt>table</tt>), unless there would be only one column, in which case the results are displayed as a comma-sepearated list (format <tt>list</tt>). The following formats are available:
+
The parameter <tt>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 <tt>table</tt>), unless there would be only one column, in which case the results are displayed as a comma-separated list (format <tt>list</tt>). In addition to the formats provided by SMW, [http://semantic-mediawiki.org/wiki/Help:SMW_extensions extensions] can provide additional formats; see [http://www.mediawiki.org/wiki/Extension:Semantic_Result_Formats Semantic Result Formats] and [http://www.mediawiki.org/wiki/Extension:Semantic_Maps Semantic Maps] for two such extensions. The following formats are available in SMW by default:
  
 
{| class="smwtable"
 
{| class="smwtable"
 
! Format
 
! Format
 
! Description
 
! Description
! Additional parameters
+
! Additional parameters (usually optional)
 
|-
 
|-
| [[Help:List format|<tt>list</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>list</tt>]
 
| Comma-separated list, with additional outputs shown in parentheses
 
| Comma-separated list, with additional outputs shown in parentheses
| <tt>sep</tt>
+
| <tt>sep</tt>, <tt>template</tt>
 
|-
 
|-
| [[Help:List format|<tt>ol</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>ol</tt>]
 
| Ordered list, with additional outputs shown in parentheses
 
| Ordered list, with additional outputs shown in parentheses
|  
+
| <tt>sep</tt>, <tt>template</tt>
 
|-
 
|-
| [[Help:List format|<tt>ul</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:List_format <tt>ul</tt>]
 
| Bulleted list, with additional outputs shown in parentheses
 
| Bulleted list, with additional outputs shown in parentheses
|  
+
| <tt>sep</tt>, <tt>template</tt>
 
|-
 
|-
| [[Help:Table format|<tt>table</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:Table_format <tt>table</tt>]
 
| Tabular output
 
| Tabular output
 
|
 
|
 
|-
 
|-
| [[Help:Table format|<tt>broadtable</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:Table_format <tt>broadtable</tt>]
 
| Tabular output, where the table is as wide as the article.
 
| Tabular output, where the table is as wide as the article.
 
|
 
|
 
|-
 
|-
| [[Help:Timeline format|<tt>timeline</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:Category_format <tt>category</tt>]
| Use dates in the output to print a timeline.
+
| List in columns, with first letters as section headers, in the style of MediaWiki category pages
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
+
| <tt>sep</tt>, <tt>template</tt>, <tt>delim</tt>, <tt>userparam</tt>, <tt>columns</tt>
 +
|-
 +
| [http://semantic-mediawiki.org/wiki/Help:Embedded_format <tt>embedded</tt>]
 +
| Embed selected articles.
 +
| <tt>embedonly</tt> (if set, don't show article link), <tt>embedformat</tt> (can be ol, ul, h1, h2 ..., h6)
 
|-
 
|-
| [[Help:Timeline format|<tt>eventline</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:Template_format <tt>template</tt>]
| '''Unstable.''' Use dates in the output to print a timeline that shows more than two dates per article.
+
| Print results by passing result fields as parameters to a given template.
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
+
| <tt>template</tt> (mandatory)
 
|-
 
|-
| [[Help:Embedded format|<tt>embedded</tt>]]
+
| [http://semantic-mediawiki.org/wiki/Help:Count_format <tt>count</tt>]
| '''Unstable.''' Embed selected articles.
+
| Just the number of results (a count of the number of matching pages), instead of the results themselves
| <tt>titleformat</tt>
+
|
 +
|-
 +
| [http://semantic-mediawiki.org/wiki/Help:Debug_format <tt>debug</tt>]
 +
| Debugging information for analysing problems in query answering.
 +
|
 +
|-
 +
| [http://semantic-mediawiki.org/wiki/Help:RSS_format <tt>rss</tt>]
 +
| Print links to RSS feeds for query results.
 +
| <tt>title</tt>, <tt>description</tt>
 +
|-
 +
| [http://semantic-mediawiki.org/wiki/Help:CSV_format <tt>csv</tt>]
 +
| Export result table as CSV (comma-separated values), ''available since [http://semantic-mediawiki.org/wiki/SMW_1.2.1 SMW_1.2.1]''
 +
| <tt>sep</tt>
 
|}
 
|}
  
[[Category:Semantic MediaWiki]]
+
== Exporting query results: RSS, etc. ==
 +
 
 +
Two of SMW's result formats, 'rss' and 'csv', enable data export from the wiki. In addition, two of the formats defined by the [http://www.mediawiki.org/wiki/Extension:Semantic_Result_Formats Semantic Result Formats] extension, 'icalendar' and 'vcard', also enable data export (these two formats were contained in Semantic MediaWiki until version 1.4.2). These formats differ from other formats in two ways:
 +
 
 +
# Instead of displaying data on the page, they produce only a link to [[Special:Ask]], which in turn outputs the data in a downloadable form. (This link is similar to the normal «further results» link, though it uses different default text, like «RSS»; it is possible to change the link text with the parameter <tt>searchlabel</tt>.)
 +
# They use fixed standard formats for exporting (non-fixed, free-form) wiki content. Hence, for formats other than CSV, it must be explained which wiki properties belong to which part of the data export format.
 +
 
 +
The second point makes it necessary to relate printout statements (properties) to the data fields available in the export format. For example, ''vCard'' is a data format that can encode many kinds of contact data about a person, but it cannot represent arbitrary properties. To specify which wiki properties belong to which of the available data fields, the label of the property printout is used. For example, vCard supports (among many others) the data fields «firstname», «lastname» and «homepage». A query could thus be
 +
 
 +
<nowiki>
 +
{{#ask: [[Category:Person]]
 +
  | ?firstname
 +
  | ?lastname
 +
  | ?url = homepage
 +
  | format=vcard
 +
}}</nowiki>
 +
 
 +
Here the wiki would have properties called «firstname» and «lastname», but the homepage of a person is stored in a property called «url». The label «homepage» is given to the latter so that vCard recognises the special meaning of this property. With this method, wikis can use arbitrary property names (in any language) and still export to standard formats. See the pages of the above formats for details on the data fields they support.
 +
 
 +
== Using templates for custom formatting ==
 +
 
 +
Some of the above result formats support the use of wiki [http://semantic-mediawiki.org/wiki/meta:Help:Template template] to fully control the display of an inline query. This works for the formats <tt>template</tt>, <tt>list</tt>, <tt>ol</tt> and <tt>ul</tt>. If a template is specified, all result «rows» are formatted using this template. The name of the template (without the initial «Template:») is given in the parameter <tt>template</tt>, so the query has the following general form:
 +
 
 +
  <nowiki>{{#ask:</nowiki> ... | format=template/list/ol/ul | template=''templatename'' }}
 +
 
 +
For each result in an inline query, SMW then calls the specified template, where the result and printout values are used as numbered template parameters. So a query that would display three columns when formatted as a table, will set three template parameters. These values can then be used in the template in the normal way writing <tt>{{{1}}}</tt>, <tt>{{{2}}}</tt>, etc. Each parameter refers to one "field" or column in the results that would be displayed by the inline query for each selected page. Normally the first field a query displays is the page title (see [[#Changing the first result column]]),
 +
so parameter <tt>{{{1}}}</tt> is the page title, and <tt>{{{2}}}, {{{3}}}, ...</tt> are the other properties displayed by the query. A number of examples are given below.
 +
 
 +
The template feature allows greater flexibility in the display 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 property values;
 +
* Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables.
 +
 
 +
If you do use a template to adjust the appearance of links, you will probably need to set the parameter <tt> | link=none | </tt> to disable SMW's automatic linking of article names. A similar effect can also be achieved by selecting the plain output format for some or all of the printouts, as described in [[Help:Displaying_information#Display_format|Displaying information]]. Your template will then have to add <tt>[[ ]]</tt> around anything you want to be a link.
 +
 
 +
To understand how to create a template for formatting some query, it is useful to look at the query with <tt>format=table</tt> first. For example, queries that refer to a single page only (like the ones one would use with <tt>#show</tt>) hide the page title of the result page, so that the parameter <tt>{{{1}}}</tt> refers to the first printout statement. Using the printout statement <tt>?</tt> or specifying any value for <tt>mainlabel</tt> willchange this.
 +
 
 +
The following examples all use [[Template:Query output demo]] that basically contains the following wiki text:
 +
 
 +
<nowiki>{{{2}}} people squeeze into the {{{3}}} of {{{1}}}.</nowiki>
 +
 
 +
The following queries illustrate the effect of this template:
 +
 
 +
<pre>{{#ask: [[Category:City]] [[Area::+]] [[Population::+]]
 +
  | ?Population=Inhabitants
 +
  | ?Area#km²=Size in km²
 +
  | format=template
 +
  | template=Query output demo
 +
  | limit=3
 +
}}</pre>
 +
 
 +
'''Result:''' {{#ask: [[Category:City]] [[Area::+]] [[Population::+]]
 +
  | ?Population=Inhabitants
 +
  | ?Area#km²=Size in km²
 +
  | format=template
 +
  | template=Query output demo
 +
  | limit=3
 +
}}
 +
 
 +
In the above example you can see how the template ignores any header labels specified in the query such as «Size in km²». Yet the values the template displays do use the units specified in <tt>?Area'''#km²'''=Size in km²</tt>, and will similarly respect all given display formats (see [http://semantic-mediawiki.org/wiki/Help:Displaying_information Displaying information]).
 +
 
 +
Below is a similar query sorted by population that uses <tt>format=ol</tt> to produce a numbered list.
 +
 
 +
<pre>{{#ask: [[Category:City]] [[Area::+]] [[Population::+]]
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=ol
 +
  | template=Query output demo
 +
  | limit=3
 +
  | sort=population
 +
  | order=desc
 +
}}</pre>
 +
 
 +
'''Result:''' {{#ask:
 +
  [[Category:City]] [[Area::+]] [[Population::+]]
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=ol
 +
  | template=Query output demo
 +
  | limit=3
 +
  | sort=population
 +
  | order=desc
 +
}}
 +
 
 +
If we directly specify a single page, then normally the query results do not include the page, so to reuse the same template in the query below we must tell the query to display the page title as the first column by adding <tt>|?</tt>
 +
 
 +
<pre>{{#ask: [[Berlin]]
 +
  | ?
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=template
 +
  | template=Query output demo
 +
}}</pre>
 +
 
 +
'''Result:''' {{#ask: [[Berlin]]
 +
  | ?
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=template
 +
  | template=Query output demo
 +
}}
 +
 
 +
The same can be accomplished using <tt>#show</tt> even though this may not be the most typical use of this function:
 +
 
 +
<pre>{{#show: Berlin
 +
  | ?
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=template
 +
  | template=Query output demo
 +
}}</pre>
 +
 
 +
'''Result:''' {{#show: Berlin
 +
  | ?
 +
  | ?Population
 +
  | ?Area#km²
 +
  | format=template
 +
  | template=Query output demo
 +
}}
 +
 
 +
Templates may also include other parser functions such as conditionals and even queries. Examples of complex query formats can be found on the following pages (external links, may change):
 +
 
 +
* [Displaying informationsemanticweb:Main_Page|Upcoming events on semanticweb.org's Main Page]: the events section on this page displays only certain major events. Each such event is formatted with a template that uses another inline query to find sub-events (co-located workshops, tutorials, etc.) for a given event.
 +
* [http://korrekt.org/page/Publications Publications on korrekt.org]: all lists on this page are created with templated queries. Conditionals (<tt>#if</tt> and <tt>#ifeq</tt>) are used to change the format of a result depending on its publication type and provided data (majorpublications have bold-faced titles).
 +
 
 +
<!--
 +
==Using a query to produce annotations ==
 +
 
 +
When querying for a property, SMW does not (currently) automatically query for transitive or inverse properties. Pages must have the properties in the query being made.  For example, even if there are pages for architects with the property ''Architect of'', you must still annotate pages for buildings with ''<nowiki>[[Has architect::Le Corbusier]]</nowiki>'' to make this inverse property appear on pages and in queries.
 +
 
 +
If you know there is exactly one annotation, you can put the function form of the query for the inverse inside the annotation.  For example, on the building's page you could add
 +
  <nowiki>Its architect is [[Has architect::{{#ask: [[Architect of::{{PAGENAMEE}}]]|link=none}} ]]</nowiki>
 +
 
 +
If there is more than one inverse property, this will not work.  For example, there are many pages with the property <tt>Located in::Germany</tt>.  However, you can put an inline query on a scratch page that uses its <tt>sep</tt> parameter to generate a list of pages that looks like annotated wiki text. You can then paste the query results into the edit box of the page. In this example,
 +
<nowiki>[ [location of::<ask sep="</nowiki>'''<nowiki>| ]][[location of::</nowiki>'''<nowiki>">[[Located in::Germany]]</ask>| ]]</nowiki>
 +
 
 +
generates
 +
: <tt>[ [location of::<ask sep="| ]][[location of::">[[located in::Germany]]</ask>| ]]</tt>
 +
You can then copy this generated wikitext to the edit box of the [[Germany]] page. (Remove the space between the first two brackets after pasting it in.)
 +
 
 +
It's possible to do this more directly using templates, see [[Germany (inverse example)]].
 +
-->

Latest revision as of 23:13, 23 May 2010

Help:Contents

This page has been copied from the Semantic MediaWiki web site at Ontoworld. Please refer to that site for more detailed explanations and examples of Centiare's powerful inline query facilities.

Semantic MediaWiki includes a simple query language for semantic search, so that users can directly request certain information from the wiki. Readers who do not wish to learn the query syntax can still profit from this feature: inline queries dynamically include query results into pages. So queries created by a few editors can be consumed by many readers.

Inline queries are similar to other semantic search features, and can also be restricted on a site in order to ensure sufficient performance. Since inline queries exploit the existing caching mechanisms of | MediaWiki, most requests for a page with such dynamic contents can be served without any performance impact whatsoever.

Introduction to #ask

The basic way of writing an inline query is to use the parser function #ask. The query string (See selecting pages for syntax) and any statements are directly given as parameter, like in the following example:

{{#ask: [[Category:City]] [[located in::Germany]] 
| ?population 
| ?area#km² = Size in km²
}}

Here we query for all cities located in Germany, and two additional printout statements are used (a simple one and one with some extra settings). This displays the following result on a page:


It is common to put the query as the first parameter behind #ask:. All other parameters are separated by |, just like for other parser functions. The exact formatting of the inline query is not essential, but it is good to use line breaks to make it more readable to other editors. As with all templates, one line per parameter, starting with the | is most accepted in practice.

Note that all the arguments to the #ask: function are ignored by the page parsing, hence the above example does not add a category or a «located in» property annotation to this page. A few more things to note are:

  • The pipe '|' symbol is used to separate the conditions from the property to display.
  • The conditions for display are a single argument to the #ask function, so there are no '|' symbols between them.
  • White space and line breaks can be used within the #ask function, SMW is fairly flexible there.
  • The format of the results display changes when you request display of additional properties. SMW picks an appropriate default format for query results, but you also have detailed control of the appearance of query results.

Knowing the basics of query string and printout statements therefore is enough to write many kinds of queries. But there are many cases where the standard table output of a query may not be the best choice, or where further settings are desired (like the maximum number of results that should be displayed). For this purpose, inline queries have a number of other possible parameters that one can use to control their appearance in detail. The general syntax for #ask therefore is the following:

{{#ask: argument 1 | argument 2 | … }}

Most of this page explains the various arguments one may use in inline queries.

Prior to Semantic MediaWiki 1.0 there was a different syntax for inline queries using an <ask> tag, which is still enabled on some wikis. Please see the old documentation page for details on this feature. It is strongly recommended to use only the new syntax now.

The #show parser function

A common usage of queries is to display only a single property value for a single page. For example, one could insert the population of Berlin into some article, and use a query instead of manual copying to achieve this. SMW has a special shortcut to make such queries simpler. For example, one can write

{{#show: Berlin | ?population}}

to display the population of Berlin (Result: «3,402,312»). The function otherwise works like an inline query, and all parameters available for inline queries can also be used on #show if desired. The above function can also be written as an #ask query as follows:

{{#ask: [[Berlin]] | ?population = }}

Here the equality symbol assigns another label for displaying the property, and this label is empty. Without this, the result would display «Population:» before the actual number.

Standard parameters for inline queries

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? (query description)
  2. What information should be displayed about those pages? (printout statements)
  3. How should the results be formatted within the page?

The first two points are explained in their respective manual pages. The third point is important to smoothly include query results in pages, yet is largely independent of the first two. Without further settings, queries often produce tables like above or simple lists (if no additional printouts are used). An example of another possible format are bulleted lists, which one can create with the parameter format=ol:

{{#ask: [[Category:City]] [[located in::Germany]] 
 | ?Population
 | format=ul
}}

This will produce the following output:


SMW implements a wide variety of output formats for inline queries, and allows you to futher control results display using a MediaWiki template. The parameter format is one of the most important parameters for selecting the appearance of query results and will be explained in more detail below. The following table gives an overview of common parameters that can be used in basically all queries:

Parameter Possible values Description
format a format name (see below) selected output format; some formats allow further parameters (see #Result formats)
limit non-negative number maximal number of pages selected (in the case of a table: rows)
offset number where to start
sort property name or a list of property names separated by , name of properties to use for sorting queries (see Selecting pages)
order ascending/asc, descending/desc/reverse,
or a list of those if more than one property is used for sorting
defines how results should be ordered, only applicable if sort is used, ascending is the default (see Selecting pages])
headers show, hide shows or hides the labels/headers used in some output formats such as «table», hide is default
mainlabel plain text title of the first column (the one with the page titles in it), default is no title; set to - to suppress printing the page titles
link none, subject, all defines which article names in the result are hyperlinked, all normally is the default

Note: linking can also be controlled for individual printouts using the plain output format as described in Displaying information.

default plain text if, for any reason, the query returns no results, this will be printed instead
intro plain text initial text that prepends the output, if at least some results exist
outro plain text text that is appended to the output, if at least some results exist
searchlabel plain text text for continuing the search (default is «… further results»)

In addition to the above, some formats have their own parameters that control special aspects of the format. These special settings are described in the documentation of each format.

Result limits and links to further results

You can set the parameter limit to restrict the maximum number of results that are returned. For example, the query

{{#ask: [[Category:City]] [[located in::Germany]]
  | limit=3
}}

displays at most 3 cities in Germany. Even if you do not specify a value for limit, SMW always applies some limit to the results a query returns. Depending on a site's settings, it might be possible to increase the number of displayed results by specifying a higher value for limit. However, there is usually a maximum limit that cannot be exceeded, set by the wiki administrator based on performance considerations.

Running the above query produces:

This shows that whenever a query does not display all results due to a limit, it will normally show a link to «further results». The text of this link can be modified by setting the parameter searchlabel. If the value of searchlabel is empty, then no link to further results appears. 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. You achive this by specifying a limit of «0» or «-1». For instance, the query

{{#ask: [[Category:City]] | limit=0 | searchlabel=Click to browse a list of cities }}

displays: Click to browse a list of cities. this link will only appear if there are any results at all. In other words, SMW will still compute the query to check if there are any results. If this is not needed, or if a link should be shown in any case, one can use the limit «-1». SMW will then only print a link to further results, even if no results exist at all. This also saves some computation time on the server.

Introduction and default text

If no articles satisfy the conditions of a query, nothing is shown. This is sometimes a useful behaviour, but often 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: ISWC2008, IJCAI2007, …

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: 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: {{#ask: ... | default=none}}
so that, if no result is obtained, the article will display
Upcoming conferences: none
  • intro: 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
{{#ask: ... | intro=Upcoming conferences:_}}
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 (this is always the case in MediaWiki and is not specific to 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. The parameters can also include MediaWiki markup, such as links or templates, as long as this does not confuse MediaWiki in recognising the #ask function.

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.

Using default texts for queries is also a good habit in general, since it may happen that a query will no longer have any results in some future, e.g. due to changes in the way the wiki organises its data. Such queries that once worked properly may be forgotten so that nobody notices the query on a page labouring to display nothing.

Sorting results

It has been explained in selecting pages that query results can be ordered by one or more properties. As explained there, Special:Ask has additional input fields to specify sort properties and ordering. In inline queries, sort properties are defined with the parameter sort, and the order can be set with the parameter order. The value of order should be «ascending» or «descending», or one of the short forms «asc» and «desc», or «reverse». You can also set the value to «random» (or «rand») for ordering results in an essentially random way (this feature can be disabled by the site administrator, see Configuration). An example is the following query for the three largest cities in Germany:

{{#ask: [[Category:City]] [[Located in::Germany]]
 | ?Population
 | sort=Population
 | order=descending
 | limit=3
}}

As explained in Selecting pages, sorting conditions may impose restrictions on the set of query results. In the above case, only German cities that have a value for population are considered. If more than one property is used for sorting, the parameters sort and order can be set to lists of property names and orders, repsectively, separated by commas. The following is an example:

{{#ask: [[Category:City]] [[Located in::Germany]]
 | ?State
 | ?Population
 | sort=State,Population
 | order=ascending,descending
}}

This query would return all German cities for which a state and population was specified. These results will be ordered by the name of the state they are located in (ordered alphabetically). Cities that are located in the same state will be ordered by their population, largest first («descending»).

Configuring labels/table headers

Queries that return more than just the selected articles (e.g. the population in the above example) will display labels that describe the various output fields. By default, the label just displays the name of the requested property, or the text «Category» if categories are displayed. Labels for properties normally display as a link to the respective pages in the Property: namespace.

In the table format, the labels appear as column headers. In other formats, the labels might appear right before the output fields. The texts used for these labels can be controlled as explained in Displaying information, using the equality symbol after printouts. Example:

{{#ask: [[Category:City]]
 |?Population=
 | ?Area#km²=Size in km²
 | ?Category=Category memberships
 | format=table
 | default=nothing found in Category:City
}}

This query will produce:

  Size in km²Category memberships
Austin, Texas0City
Berlin, Germany3,402,312City
Bordeaux, France229,900City
California*
36100000
City
States of the United States
County
Statewide Department
Society/Ethnicity/The Americas
*
Costa Mesa, California109830City
England*
50,690,000
City
Country
Regions of England
Fountain Valley, California55942City
France*
61,538,322
City
Country
Regions of France
Harris County0
*
City
County
Regional District
*
Houston, Texas2016582City
Houston Area Business
Huntington Beach, California189594City
*
Italy*
58,863,156
City
Country
Regions of Italy
Japan*City
Country
Prefectures of Japan
Kabul1780000City
London, England7,500,000City
London Area Business
Long Beach, California461522City
Los Angeles, CaliforniaCity
Los Angeles Area Business
Maiori, Italy6,000City
Marseille, France808,700City
New York City8,143,197City
New York City Area Business
... further results

It is possible to use empty printout labels to have no label for a result column at all. In tables, however, the table header will still be shown even if all printouts use empty labels. To remove the header of a table completely, the parameter headers can be used. Three values are possible:

  • show: display labels (default)
  • plain: show labels and headers, but a plain text without links (available since SMW 1.4.3)
  • hide: hide all labels and table headers

This setting works for tables as well as for other outputs. In the latter case, the value hide will hide all printout labels, even if they have a non-empty label set in the query.

Changing the first result column

Most queries by default display the actual result pages in the first result position, e.g. as the first column in a table. The header of this column is usually blank. To change the label, or to hide the whole first column, the parameter mainlabel can be used. Normally, the text given to that parameter will simply be used as a header for the first column, for example in the query

{{#ask: [[Category:City]] [[Located in::Germany]]
 | mainlabel=City
 | ?Population=Number of inhabitants
 | limit=3
}}

This will produce the table:


The parameter mainlabel can also be used to completely hide the first column. This happens if the value of this parameter is set to «-» (minus symbol). To insert the list of main results at another position, the printout statement «?», i.e. the question mark without any additions, can be used. For example, modifying the example above to display the city name after Population,

{{#ask: [[Category:City]] [[Located in::Germany]]
 | ?Population=Number of inhabitants
 | ?=City
 | mainlabel=-
 | limit=3
}}

This results in the table:


Result formats

The parameter format determines how the results of a query are displayed in the article. If it is omitted, all queries are displayed as tables (format table), unless there would be only one column, in which case the results are displayed as a comma-separated list (format list). In addition to the formats provided by SMW, extensions can provide additional formats; see Semantic Result Formats and Semantic Maps for two such extensions. The following formats are available in SMW by default:

Format Description Additional parameters (usually optional)
list Comma-separated list, with additional outputs shown in parentheses sep, template
ol Ordered list, with additional outputs shown in parentheses sep, template
ul Bulleted list, with additional outputs shown in parentheses sep, template
table Tabular output
broadtable Tabular output, where the table is as wide as the article.
category List in columns, with first letters as section headers, in the style of MediaWiki category pages sep, template, delim, userparam, columns
embedded Embed selected articles. embedonly (if set, don't show article link), embedformat (can be ol, ul, h1, h2 ..., h6)
template Print results by passing result fields as parameters to a given template. template (mandatory)
count Just the number of results (a count of the number of matching pages), instead of the results themselves
debug Debugging information for analysing problems in query answering.
rss Print links to RSS feeds for query results. title, description
csv Export result table as CSV (comma-separated values), available since SMW_1.2.1 sep

Exporting query results: RSS, etc.

Two of SMW's result formats, 'rss' and 'csv', enable data export from the wiki. In addition, two of the formats defined by the Semantic Result Formats extension, 'icalendar' and 'vcard', also enable data export (these two formats were contained in Semantic MediaWiki until version 1.4.2). These formats differ from other formats in two ways:

  1. Instead of displaying data on the page, they produce only a link to Special:Ask, which in turn outputs the data in a downloadable form. (This link is similar to the normal «further results» link, though it uses different default text, like «RSS»; it is possible to change the link text with the parameter searchlabel.)
  2. They use fixed standard formats for exporting (non-fixed, free-form) wiki content. Hence, for formats other than CSV, it must be explained which wiki properties belong to which part of the data export format.

The second point makes it necessary to relate printout statements (properties) to the data fields available in the export format. For example, vCard is a data format that can encode many kinds of contact data about a person, but it cannot represent arbitrary properties. To specify which wiki properties belong to which of the available data fields, the label of the property printout is used. For example, vCard supports (among many others) the data fields «firstname», «lastname» and «homepage». A query could thus be

 {{#ask: [[Category:Person]]
   | ?firstname
   | ?lastname
   | ?url = homepage
   | format=vcard 
 }}

Here the wiki would have properties called «firstname» and «lastname», but the homepage of a person is stored in a property called «url». The label «homepage» is given to the latter so that vCard recognises the special meaning of this property. With this method, wikis can use arbitrary property names (in any language) and still export to standard formats. See the pages of the above formats for details on the data fields they support.

Using templates for custom formatting

Some of the above result formats support the use of wiki template to fully control the display of an inline query. This works for the formats template, list, ol and ul. If a template is specified, all result «rows» are formatted using this template. The name of the template (without the initial «Template:») is given in the parameter template, so the query has the following general form:

 {{#ask: ... | format=template/list/ol/ul | template=templatename }}

For each result in an inline query, SMW then calls the specified template, where the result and printout values are used as numbered template parameters. So a query that would display three columns when formatted as a table, will set three template parameters. These values can then be used in the template in the normal way writing {{{1}}}, {{{2}}}, etc. Each parameter refers to one "field" or column in the results that would be displayed by the inline query for each selected page. Normally the first field a query displays is the page title (see #Changing the first result column), so parameter {{{1}}} is the page title, and {{{2}}}, {{{3}}}, ... are the other properties displayed by the query. A number of examples are given below.

The template feature allows greater flexibility in the display 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 property values;
  • Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables.

If you do use a template to adjust the appearance of links, you will probably need to set the parameter | link=none | to disable SMW's automatic linking of article names. A similar effect can also be achieved by selecting the plain output format for some or all of the printouts, as described in Displaying information. Your template will then have to add [[ ]] around anything you want to be a link.

To understand how to create a template for formatting some query, it is useful to look at the query with format=table first. For example, queries that refer to a single page only (like the ones one would use with #show) hide the page title of the result page, so that the parameter {{{1}}} refers to the first printout statement. Using the printout statement ? or specifying any value for mainlabel willchange this.

The following examples all use Template:Query output demo that basically contains the following wiki text:

{{{2}}} people squeeze into the {{{3}}} of {{{1}}}.

The following queries illustrate the effect of this template:

{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] 
  | ?Population=Inhabitants
  | ?Area#km²=Size in km²
  | format=template
  | template=Query output demo
  | limit=3
}}

Result:

In the above example you can see how the template ignores any header labels specified in the query such as «Size in km²». Yet the values the template displays do use the units specified in ?Area#km²=Size in km², and will similarly respect all given display formats (see Displaying information).

Below is a similar query sorted by population that uses format=ol to produce a numbered list.

{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] 
  | ?Population
  | ?Area#km²
  | format=ol
  | template=Query output demo
  | limit=3
  | sort=population
  | order=desc
}}

Result:

If we directly specify a single page, then normally the query results do not include the page, so to reuse the same template in the query below we must tell the query to display the page title as the first column by adding |?

{{#ask: [[Berlin]]
  | ?
  | ?Population
  | ?Area#km²
  | format=template
  | template=Query output demo
}}

Result: Template:Query output demo

The same can be accomplished using #show even though this may not be the most typical use of this function:

{{#show: Berlin
  | ?
  | ?Population
  | ?Area#km²
  | format=template
  | template=Query output demo
}}

Result: Template:Query output demo

Templates may also include other parser functions such as conditionals and even queries. Examples of complex query formats can be found on the following pages (external links, may change):

  • [Displaying informationsemanticweb:Main_Page|Upcoming events on semanticweb.org's Main Page]: the events section on this page displays only certain major events. Each such event is formatted with a template that uses another inline query to find sub-events (co-located workshops, tutorials, etc.) for a given event.
  • Publications on korrekt.org: all lists on this page are created with templated queries. Conditionals (#if and #ifeq) are used to change the format of a result depending on its publication type and provided data (majorpublications have bold-faced titles).