3,699
edits
Changes
MyWikiBiz, Author Your Legacy — Saturday November 30, 2024
Jump to navigationJump to searchno edit summary
[[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.
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.
''The documentation below applies to Semantic MediaWiki of version 0.6 and above.''
== Introduction ==
Inline queries are written in the wiki-text of a page by writing text of the form
<nowiki><ask ...>...</ask></nowiki>
where the … 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
<nowiki><ask>[[Category:Country]] [[located in::Africa]] [[Population:=*]]</ask></nowiki>
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.
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?
# What information should be displayed about those pages?
# 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":
<pre><ask format="ol">
[[Category:Country]]
[[located in::Africa]]
[[Population:=*]]
</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 ==
A couple of standard parameters are always available for customising the result of inline queries. Here is a short overview:
{| class="smwtable"
! Paramter
! Possible values
! Description
|-
| limit
| non-negative number
| maximal number of pages selected (in the case of a table: rows)
|-
| sort
| attribute name
| name of attribute to use for sorting queries; this attribute must occur in the query in a statement without "*"
|-
| order
| "ascending"/"asc", "descending"/"desc"/"reverse"
| defines how results should be ordered, only used if <tt>sort</tt> is used, "ascending" is the default
|-
| headers
| "show", "hide"
| shows or hides the labels/headers used in the output, "hide" is deault
|-
| 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, no result is being created, this will be returned
|-
| intro
| plain text
| initial text that is prepended the output, if at least some results exist
|-
| debug
| "true"
| gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results
|-
| format
| a format name (see below)
| selected output format, some formats allow further parameters (see below)
|}
=== Result limits and further results ===
The parameter <tt>limit</tt> can be used to restrict the maximum number of results that are returned. For example, the query
<pre><ask limit="3">
[[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.
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.
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
<nowiki><ask limit="0" searchlabel="Browse list of countries">[[Category:Country]]</ask></nowiki>
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.
=== Sorting results ===
In the case of [[Special:Ask]], additional input fields were used to specify whether and how the result should be ordered (see [[Help:Semantic search]]). In the case of inline queries, those settings are specified as 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
<pre><ask order="population" sort="descending">
[[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.
=== Configuring labels/table headers ===
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.
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
<pre><ask>
[[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.
<ask limit="1" searchlabel="..."> [[Category:Country]] [[Population:=*|Inhabitants]] [[Area:=*km²|Size in km²]] [[borders::*|next to]] [[Area:=+]] [[Population:=+]] [[Category:*|Category memberships]]</ask>
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.''
The '''display of labels''' can be controlled with the parameter <tt>headers</tt> which currently can take one of two values:
* "show": display labels (default)
* "hide": hide all labels or table headers
=== Introduction and default text ===
Certain texts should be shown or not shown depending on whether the query has results or not. For example, one may want the query to show an output of the following form:
Upcoming conferences: [[IJCAI2007]], [[ICCS2007]], …
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
Upcoming conferences:
which is not desriable. Two parameters exist to prevent this.
* <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
Upcoming conferences: <nowiki><ask default="none">...</ask></nowiki>
: so that, if no result is obtained, the article will display
Upcoming conferences: none
* <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
<nowiki><ask intro="Upcoming conferences:_">...</ask></nowiki>
: so that, if no result is obtained, nothing will be printed at all. Note that we use "_" to encode the final space. This is needed for initial and final spaces in any parameter, since those are otherwise removed internally (not by SMW).
Both of the above solutions will show the intended output if results are found. It is also possible to combine both parameters if desired. Note that the aboe parameters only accept simple texts: neither wiki-markup nor HTML-elements are supported at the moment.
Also note that if the set of pages selected in a query is empty, no header row or blank line, not even any blank space, is produced. This can also be useful to "hide" queries that are not applicable. '''However, it is not recommended to insert great amounts of queries into every page, based on the assumption that this can do no harm since no output is generated.''' Indeed, answering queries requires much computational resources and should not be done without a purpose.
== Output formats ==
The parameter <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:
{| class="smwtable"
! Format
! Description
! Additional parameters
|-
| [[Help:List format|<tt>list</tt>]]
| Comma-separated list, with additional outputs shown in parentheses
| <tt>sep</tt>
|-
| [[Help:List format|<tt>ol</tt>]]
| Ordered list, with additional outputs shown in parentheses
|
|-
| [[Help:List format|<tt>ul</tt>]]
| Bulleted list, with additional outputs shown in parentheses
|
|-
| [[Help:Table format|<tt>table</tt>]]
| Tabular output
|
|-
| [[Help:Table format|<tt>broadtable</tt>]]
| Tabular output, where the table is as wide as the article.
|
|-
| [[Help:Timeline format|<tt>timeline</tt>]]
| Use dates in the output to print a timeline.
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
|-
| [[Help:Timeline format|<tt>eventline</tt>]]
| '''Unstable.''' Use dates in the output to print a timeline that shows more than two dates per article.
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
|-
| [[Help:Embedded format|<tt>embedded</tt>]]
| '''Unstable.''' Embed selected articles.
| <tt>titleformat</tt>
|}
[[Category:Semantic MediaWiki]]
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.
''The documentation below applies to Semantic MediaWiki of version 0.6 and above.''
== Introduction ==
Inline queries are written in the wiki-text of a page by writing text of the form
<nowiki><ask ...>...</ask></nowiki>
where the … 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
<nowiki><ask>[[Category:Country]] [[located in::Africa]] [[Population:=*]]</ask></nowiki>
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.
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?
# What information should be displayed about those pages?
# 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":
<pre><ask format="ol">
[[Category:Country]]
[[located in::Africa]]
[[Population:=*]]
</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 ==
A couple of standard parameters are always available for customising the result of inline queries. Here is a short overview:
{| class="smwtable"
! Paramter
! Possible values
! Description
|-
| limit
| non-negative number
| maximal number of pages selected (in the case of a table: rows)
|-
| sort
| attribute name
| name of attribute to use for sorting queries; this attribute must occur in the query in a statement without "*"
|-
| order
| "ascending"/"asc", "descending"/"desc"/"reverse"
| defines how results should be ordered, only used if <tt>sort</tt> is used, "ascending" is the default
|-
| headers
| "show", "hide"
| shows or hides the labels/headers used in the output, "hide" is deault
|-
| 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, no result is being created, this will be returned
|-
| intro
| plain text
| initial text that is prepended the output, if at least some results exist
|-
| debug
| "true"
| gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results
|-
| format
| a format name (see below)
| selected output format, some formats allow further parameters (see below)
|}
=== Result limits and further results ===
The parameter <tt>limit</tt> can be used to restrict the maximum number of results that are returned. For example, the query
<pre><ask limit="3">
[[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.
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.
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
<nowiki><ask limit="0" searchlabel="Browse list of countries">[[Category:Country]]</ask></nowiki>
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.
=== Sorting results ===
In the case of [[Special:Ask]], additional input fields were used to specify whether and how the result should be ordered (see [[Help:Semantic search]]). In the case of inline queries, those settings are specified as 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
<pre><ask order="population" sort="descending">
[[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.
=== Configuring labels/table headers ===
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.
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
<pre><ask>
[[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.
<ask limit="1" searchlabel="..."> [[Category:Country]] [[Population:=*|Inhabitants]] [[Area:=*km²|Size in km²]] [[borders::*|next to]] [[Area:=+]] [[Population:=+]] [[Category:*|Category memberships]]</ask>
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.''
The '''display of labels''' can be controlled with the parameter <tt>headers</tt> which currently can take one of two values:
* "show": display labels (default)
* "hide": hide all labels or table headers
=== Introduction and default text ===
Certain texts should be shown or not shown depending on whether the query has results or not. For example, one may want the query to show an output of the following form:
Upcoming conferences: [[IJCAI2007]], [[ICCS2007]], …
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
Upcoming conferences:
which is not desriable. Two parameters exist to prevent this.
* <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
Upcoming conferences: <nowiki><ask default="none">...</ask></nowiki>
: so that, if no result is obtained, the article will display
Upcoming conferences: none
* <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
<nowiki><ask intro="Upcoming conferences:_">...</ask></nowiki>
: so that, if no result is obtained, nothing will be printed at all. Note that we use "_" to encode the final space. This is needed for initial and final spaces in any parameter, since those are otherwise removed internally (not by SMW).
Both of the above solutions will show the intended output if results are found. It is also possible to combine both parameters if desired. Note that the aboe parameters only accept simple texts: neither wiki-markup nor HTML-elements are supported at the moment.
Also note that if the set of pages selected in a query is empty, no header row or blank line, not even any blank space, is produced. This can also be useful to "hide" queries that are not applicable. '''However, it is not recommended to insert great amounts of queries into every page, based on the assumption that this can do no harm since no output is generated.''' Indeed, answering queries requires much computational resources and should not be done without a purpose.
== Output formats ==
The parameter <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:
{| class="smwtable"
! Format
! Description
! Additional parameters
|-
| [[Help:List format|<tt>list</tt>]]
| Comma-separated list, with additional outputs shown in parentheses
| <tt>sep</tt>
|-
| [[Help:List format|<tt>ol</tt>]]
| Ordered list, with additional outputs shown in parentheses
|
|-
| [[Help:List format|<tt>ul</tt>]]
| Bulleted list, with additional outputs shown in parentheses
|
|-
| [[Help:Table format|<tt>table</tt>]]
| Tabular output
|
|-
| [[Help:Table format|<tt>broadtable</tt>]]
| Tabular output, where the table is as wide as the article.
|
|-
| [[Help:Timeline format|<tt>timeline</tt>]]
| Use dates in the output to print a timeline.
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
|-
| [[Help:Timeline format|<tt>eventline</tt>]]
| '''Unstable.''' Use dates in the output to print a timeline that shows more than two dates per article.
| <tt>timlinelinestart</tt>, <tt>timlinelineend</tt>, <tt>timlinelinesize</tt>, <tt>timlinelinebands</tt>, <tt>timlinelineposition</tt>
|-
| [[Help:Embedded format|<tt>embedded</tt>]]
| '''Unstable.''' Embed selected articles.
| <tt>titleformat</tt>
|}
[[Category:Semantic MediaWiki]]
