Help:Inline queries

From NYC Resistor Wiki
Jump to: navigation, search

SMW user manual

Introduction

Browsing and searching

Browsing interfaces

Semantic search

Editing

Properties and types

Custom units

Semantic templates

Inline queries

Service links

Semantic Web

OWL/RDF export

External tools

Importing vocabulary

Ontology import

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.

A query interface that allows intuitive assembling of inline queries, without knowing the necessary syntax is provided along with the ow:Halo Extension.

Introduction[edit]

You put a query inline in the wiki-text of a page using the ask parser function implemented by Semantic MediaWiki. Like other meta:Help:Parser_function parser functions in extensions, the syntax for this is by writing text of the form

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

where the arguments … describe the query.

(Note that prior to Semantic MediaWiki version 1.0 there was a different syntax for inline queries using an <ask> tag, it still works and is documented at the end of this page.)

The most important argument to the #ask function is the conditions for display, as described in the help page to semantic search. For example, one can write

{{#ask: [[Category:City]] [[located in::Germany]] }}

to obtain a list of all cities in Germany. Where you insert this query in the wiki-text, a simple list of the matching page titles will be displayed within the page.

Let's do it: Result: Inline queries

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 the current page. In a similar way, all kinds of queries can be embedded inline.

To display additional properties of the pages matching the condition, you add additional arguments of the form ?property name, for example

{{#ask: [[Category:City]] [[located in::Germany]]
  | ?Population
}}
Result:
 Population
Inline queries*

A few things to note:

  1. We use the '|' symbol to separate the conditions from the property to display.
  2. As you can see, you can add whitespace within the #ask function, the parsing is fairly flexible.
  3. The format of the results display is different. SMW picks an appropriate default format, but you have extensive control of the appearance of query results.

Inline query arguments[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?
  2. What information should be displayed about those pages?
  3. How should the results be formated 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":

{{#ask:
  [[Category:City]] 
  [[located in::Germany]] 
  | ?Population
  | format=ol
}}
Result:
  1. Inline queries (Population *)

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 parameters[edit]

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

Parameter Possible values Description
limit non-negative number maximal number of pages selected (in the case of a table: rows)
offset number where to start
sort property name name of property to use for sorting queries; this property must occur in the query in a statement without "*"
order "ascending"/"asc", "descending"/"desc"/"reverse" defines how results should be ordered, only used if sort is used, "ascending" is the default
headers "show", "hide" shows or hides the labels/headers used in the output, "hide" is default
mainlabel plain text title of the first column (the one with the page titles in it)
link "none", "subject", "all" defines which article names in the result are hyperlinked, "subject" normally is the default
default plain text if, for any reason, the query returns no results, this will be printed instead
intro plain text initial text that is prepended the output, if at least some results exist
headers "hide" In table format, should the headers (usually the names of properties you ask query results to display) be shown?
searchlabel plain text text for continuing the search (default is "… further results")
debug "true" [only SMW≤0.6] gives an SQL statement for debugging instead of the query results
format a format name (see below) selected output format; some formats allow further parameters (see #Output formats)

Result limits and further results[edit]

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

<ask limit="3">
  [[Category:Country]] 
  [[located in::Africa]] 
</ask>

returns 3 countries in Africa. Even if no value for limit is given, there is a default limit that will be used. 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. Its value is specified by the site administrators based on performance considerations.

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 searchlabel. If the value of searchlabel is "", then the link to further results will no be shown. 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. This is done by selecting a limit of "0". For instance, the query

<ask limit="0" searchlabel="Browse list of countries">[[Category:Country]]</ask>

displays a sole link entitled "<ask limit="0" searchlabel="Browse list of countries" default="Browse list of countries"></ask>" if any country is found. Otherwise, nothing is shown.

Sorting results[edit]

By default, semantic search results are in page title order, ascending. The Special:Ask input form has additional input fields to specify a different sort column and ordering. In inline queries, you specify those sort column with the parameter sort, and the order with the parameter order; the value of order should be "ascending" or "descending" (or the short forms "asc" and "desc"). For example, the inline query

<ask sort="population" order="descending">
  [[Category:Country]]
  [[located in::Africa]]
  [[population::+]]
  [[population::*]]
</ask>

re

Output formats[edit]

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). The following formats are available:

Format Description Additional parameters
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.
timeline Use dates in the output to print a timeline. timelinestart, timelineend, timelinesize (default "300px"), timelinebands, timelineposition (default "middle")
eventline Unstable. Use dates in the output to print a timeline that shows more than two dates per article. timelinestart, timelineend, timelinesize (default "300px"), timelinebands, timelineposition (default "middle")
embedded Unstable. Embed selected articles. embedonly (if set, don't show article link), embedformat (can be ol, ul, h1, h2 ..., h6)
template Unstable. Print results by passing result fields as parameters to a given template. template (mandatory)
count Just the number of results, instead of the results themselves
debug Debugging information for analysing problems in query answering.
rss Print links to RSS feeds for query results. rsstitle, rssdescription


Using templates[edit]

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

<ask format=template template=templatename> ... </ask> or
<ask format=list template=templatename> ... </ask>.

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

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

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

Notes:

  • When output is limited, the template format will not be carried forward to the continuation link.
  • Parser functions applied to parameters (e.g. for computations and branching) do not work.
  • If the selected page itself would normally be produced, this selected page is referred to as {{{1}}}, and the other results are subsequently referred to as {{{2}}}, {{{3}}}, .... If the selected page itself is normally not produced, {{{1}}} refers to the first result about the page. Thus typically different format templates are needed for both cases. To avoid that, when enumerating pages in the query (or specifying a particular one), use par

Using a query to produce annotations[edit]

When querying for a property, SMW does not (currently) automatically query for transitive or inverse properties. Pages must be ensured to have the properties in the query being made. For example, if there are pages for architects with the property architect of, you still must annotate pages for buildings with the annotation has architect to make the 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

 Its architect is [[Has architect::{{#ask: [[Architect of::{{PAGENAME}}]]|link=none}} ]]

If there is more than one inverse property, this will not work. For example, there are many pages with the property located in:=California. However, put an inline query on a scratch page that will generate a list of these properties that looks like wiki text, and then paste it into the edit box of the page. In this example,

[ [location of:=<ask sep="| ]][[location of:=">[[located in::California]]</ask>| ]]

generates

[ [location of:=<ask sep="| ]]
"">[[located in" contains the "[" character as part of a property label and has been classified as invalid.
</ask>| ]]

and copy this generated wikitext to the edit box of the Germany page. (Remove the space between the first two brackets after pasting it in.)

Old <ask> tag format[edit]

Prior to SMW version 1.0, you would write inline queries inside an ask tag.

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

where the … describes the query.

This form still works but is no longer recommended.

The part between the two ask-tags can be any query, as described in the help page to semantic search. For example, one can write

<ask>[[Category:City]] [[located in::Germany]]</ask>

Unlike the {{#ask:}} function,

  • you specify additional properties to display by mentioning them in annotation format with a '*' in place of any condition
  • you specify additional parameters in the opening ask tag.

For example, to display the population of these cities, sort by population descending, and limit to the biggest 5 cities, you would write

<ask sort=Population order=desc limit=5>
   [[Category:City]] [[located in::Germany]]
   [[Population:*]]
</ask>

Result: <ask sort=Population order=desc limit=5> Germany

  *

</ask>