3,103
edits
Changes
no edit summary
</blockquote>
</blockquote>
[[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.
[[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 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.
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.
== Introduction to #ask ==
== Introduction to #ask ==
The basic way of writing an inline query is to use the parser function <tt>#ask</tt>. The query string (See [[Help:Selecting pages|selecting pages]] for syntax) and any [[Help:Displaying information|printout statements]] are directly given as parameter, like in the following example:
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:
<pre><nowiki>
<pre><nowiki>
* 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.
* 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 [[Help:Selecting pages|query string]] and [[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:
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> | … <nowiki>}}</nowiki>
<nowiki>{{</nowiki>#ask: <i>argument 1</i> | <i>argument 2</i> | … <nowiki>}}</nowiki>
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? ([[Help:Selecting pages|query description]])
# Which pages are requested? ([http://semantic-mediawiki.org/wiki/Help:Selecting_pages query description])
# What information should be displayed about those pages? ([[Help:Displaying information|printout statements]])
# What information should be displayed about those pages? ([[Help:Displaying information|printout statements]])
# How should the results be formatted within the page?
# How should the results be formatted within the page?
| <tt>order</tt>
| <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
| <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 [[Help:Selecting pages]])
| 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]])
|-
|-
| <tt>headers</tt>
| <tt>headers</tt>
}}</pre>
}}</pre>
As explained in [[Help: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:
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:
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
<pre>{{#ask: [[Category:City]] [[Located in::Germany]]
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.
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 [[Help:Displaying information]], using the equality symbol after printouts. Example:
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:
<pre>{{#ask: [[Category:City]]
<pre>{{#ask: [[Category:City]]
== Result 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-separated list (format <tt>list</tt>). In addition to the formats provided by SMW, [[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:
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"
! Additional parameters (usually optional)
! 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>template</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>
| <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>
| <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:Category format|<tt>category</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Category_format <tt>category</tt>]
| List in columns, with first letters as section headers, in the style of MediaWiki category pages
| List in columns, with first letters as section headers, in the style of MediaWiki category pages
| <tt>sep</tt>, <tt>template</tt>, <tt>delim</tt>, <tt>userparam</tt>, <tt>columns</tt>
| <tt>sep</tt>, <tt>template</tt>, <tt>delim</tt>, <tt>userparam</tt>, <tt>columns</tt>
|-
|-
| [[Help:Embedded format|<tt>embedded</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Embedded_format <tt>embedded</tt>]
| Embed selected articles.
| Embed selected articles.
| <tt>embedonly</tt> (if set, don't show article link), <tt>embedformat</tt> (can be ol, ul, h1, h2 ..., h6)
| <tt>embedonly</tt> (if set, don't show article link), <tt>embedformat</tt> (can be ol, ul, h1, h2 ..., h6)
|-
|-
| [[Help:Template format|<tt>template</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Template_format <tt>template</tt>]
| Print results by passing result fields as parameters to a given template.
| Print results by passing result fields as parameters to a given template.
| <tt>template</tt> (mandatory)
| <tt>template</tt> (mandatory)
|-
|-
| [[Help:Count format|<tt>count</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Count_format <tt>count</tt>]
| Just the number of results (a count of the number of matching pages), instead of the results themselves
| Just the number of results (a count of the number of matching pages), instead of the results themselves
|
|
|-
|-
| [[Help:Debug format|<tt>debug</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:Debug_format <tt>debug</tt>]
| Debugging information for analysing problems in query answering.
| Debugging information for analysing problems in query answering.
|
|
|-
|-
| [[Help:RSS format|<tt>rss</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:RSS_format <tt>rss</tt>]
| Print links to RSS feeds for query results.
| Print links to RSS feeds for query results.
| <tt>title</tt>, <tt>description</tt>
| <tt>title</tt>, <tt>description</tt>
|-
|-
| [[Help:CSV format|<tt>csv</tt>]]
| [http://semantic-mediawiki.org/wiki/Help:CSV_format <tt>csv</tt>]
| Export result table as CSV (comma-separated values), ''available since [[SMW 1.2.1]]''
| 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>
| <tt>sep</tt>
|}
|}
}}
}}
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 [[Help:Displaying information]]).
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.
Below is a similar query sorted by population that uses <tt>format=ol</tt> to produce a numbered list.
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):
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):
* [[semanticweb: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.
* [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).
* [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).