Inline queries

From semantic-mediawiki.org
Table of Contents

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.

Parser function #ask[edit]

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 printout 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:

 PopulationThe number of inhabitants of some geographical place.Size in km²
Berlin3,520,061891.85 km²344.34 sqmi <br />
Cologne1,080,394405.02 km²156.38 sqmi <br />
Frankfurt679,664248.31 km²95.87 sqmi <br />
Munich1,353,186310.43 km²119.86 sqmi <br />
Stuttgart606,588207.35 km²80.06 sqmi <br />
Würzburg126,63587.63 km²33.83 sqmi <br />

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.

Parser function #show[edit]

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 page, and use a query instead of manual copying to achieve this. SMW provides a special shortcut parser function to make such queries simpler: #show. For example, one can write the following to display the population of Berlin on a page:

Syntax
{{#show: Demo:Berlin |?Population }}
Result

3,520,061

The parser function otherwise works like an inline query, and all parameters available for inline queries can also be used on #show if desired. However note that the #show parser function only takes one argument (a page) as the query condition, i.e. the name of the page that should be queried.

The above query written with the #ask parser function looks as follows:

Syntax
{{#ask: [[Demo:Berlin]] |?Population= |mainlabel=- }}
Result

3,520,061

Here the "=" added to the queried property "?Population" removes the display of the property label and parameter "mainlabel=" followed by the "-" symbol removes the first result column and the label of the column.

Without this, the result would display a table with two columns and rows:

Syntax
{{#ask: [[Berlin]] |?Population }}
Result
 PopulationThe number of inhabitants of some geographical place.
Berlin3,520,061

Standard parameters for inline queries[edit]

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? (See Selecting pages)
  2. What information should be displayed about those pages? (See Printout statements)
  3. How should the results be formatted within the page? (See Results formats)

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=ul: 

{{#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 further control results display using a MediaWiki template. The parameter format is one of the most important parameters for selecting the appearance of query results. See Results formats.


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 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 selecting pages

Note Note:  If the limit specified with this parameter exceeds the limit set with configuration parameter $smwgQUpperboundSets the upper bound of the offset used for the maximal number of rows ever printed in an embedded query, the offset will fallback to the limit of "0".1

sort property name or a list of property names separated by , name of properties to use for sorting queries, a blank as a value stands for the main result column (see Selecting pages)
order ascending/asc, descending/desc/reverse, random/rand
or a list of those if more than one property is used for sorting 		defines how results should be ordered, ascending is the default, without using parameter "sort" the sort order of the main result column is set (see Selecting pages)
headers show, plain, hide Show headers (with links), plain headers (just text) or hide them. show 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
index number defines which value within a record should be displayed, only applicable for properties of type Record
link none, subject, all defines which article names in the result are hyperlinked, all normally is the default. See also the examples page.

Note 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. See also the overview page on ask syntax elements.

Result limits and links to further results[edit]

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. For details, see the overview page on configuration parameters.

Running the above query produces: Berlin, Cologne, Frankfurt... further results

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

The query 

{{#ask: [[Category:City]] | limit=10 | searchlabel= }}

in contrast will show a list of up to ten cities, but no link to further results, even if there are any.

Styling of further results link[edit]

Since SMW 1.9.0 it is possible to assign individual CSS styling to each result format's pending "further results" link. See the help page on styling further results for further information on this.

Introduction and default text[edit]

If no articles satisfy the conditions of a query, nothing is shown. This is sometimes a useful behavior, 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: SMWCon Spring 2013, SMWCon Fall 2013, …

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:&nbsp;}}
so that, if no result is obtained, nothing will be printed at all. Note that we use "&nbsp;" to encode the final space ("&#32;" would have worked as well), because regular whitespace is trimmed off the beginning and end of parser-function parameters.

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 recognizing 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 organizes its data. Such queries that once worked properly may be forgotten so that nobody notices the query on a page laboring to display nothing.

Note that in cases you want to display only a single property value for a single page (see #show), the parameter default does not work since you are actually not querying for pages.

Sorting results[edit]

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», «descending» or «reverse», or one of the short forms «asc» and «desc». 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, respectively, 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»).

It is also possible to explicitly define the main result column to be used for the sorting when more than one sorting condition should be used. This is done by either prepending or appending a comma to an empty statement. Example: 

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

This query would return all German cities for which a state 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 alphabetically (descending) by their name.

Configuring labels/table headers[edit]

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::+]] 
 |?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
Amsterdam783,364219.00 km²84.56 sqmi <br />Europe
Sample pages
City
Berlin3,520,061891.85 km²344.34 sqmi <br />Sample pages
City
Cologne1,080,394405.02 km²156.38 sqmi <br />City
Frankfurt679,664248.31 km²95.87 sqmi <br />Sample pages
City
Karlsruhe294,761173.46 km²66.97 sqmi <br />Sample pages
City
London7,825,2001,706.80 km²659.00 sqmi <br />Sample pages
City
Munich1,353,186310.43 km²119.86 sqmi <br />Sample pages
City
Paris2,234,105105.40 km²40.69 sqmi <br />Sample pages
City
Popular City
Porto237.58441.66 km²16.08 sqmi <br />Sample pages
City
Rome2,761,4771,285.31 km²496.26 sqmi <br />Sample pages
City
San Diego1,307,402963.60 km²372.05 sqmi <br />Sample pages
City
Stuttgart606,588207.35 km²80.06 sqmi <br />Sample pages
City
Sydney4,575,5322,058.00 km²794.59 sqmi <br />Sample pages
City
Vienna1,897
1,888,776		414.87 km²160.18 sqmi <br />
1,073,815,073.82 km²414,600,000.00 sqmi <br />		Sample pages
City
Capital
Warsaw1,720,398516.90 km²199.58 sqmi <br />Sample pages
City
Würzburg126,63587.63 km²33.83 sqmi <br />City

It is possible to use empty printout labels or 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[edit]

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:

CityNumber of inhabitantsThe number of inhabitants of some geographical place.
Berlin3,520,061
Cologne1,080,394
Frankfurt679,664
... further results

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:

Number of inhabitantsThe number of inhabitants of some geographical place.City
3,520,061Berlin
1,080,394Cologne
679,664Frankfurt
... further results

Result formats[edit]

The parameter format determines how the results of a query are displayed in the article. For more info, see the Result formats page.

Exporting query results[edit]

Some SMW's result formats (csv, dsv, json, rdf) enable data export from the wiki. In addition, other formats defined by the Extension "Semantic Result Formats" extension () also enable data export. 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 and DSV, 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 recognizes 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.

Updating of inline queries[edit]

Avoid Self-Referencing[edit]

See Help:Self-Referencing for information about how using an inline query for a property set on the same page can cause unexpected behavior.

Related tips[edit]


Retrieved from "https://www.semantic-mediawiki.org/w/index.php?title=Help:Inline_queries&oldid=74920#Parser_function_.23show"
  • "Attribution 3.0 Germany" (CC BY 3.0 DE)
  • Powered by MediaWiki
  • Powered by Semantic MediaWiki