2,646
edits
Changes
MyWikiBiz, Author Your Legacy — Friday November 22, 2024
Jump to navigationJump to searchUpdate ASK overview for SMW 0.7
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 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.
== Introduction ==
== Introduction ==
<nowiki><ask>[[Category:Country]] [[located in::Africa]] [[Population:=*]]</ask></nowiki>
<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.
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 similar 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:
In general, an inline query is a request to find a number of '''pages''' that satisfy certain requirements. The query must answer three questions:
== Standard settings ==
== Standard settings ==
A couple of standard parameters are always available for customising the result of inline queries. Here is a short overview:
A number of standard parameters are always available for customising the result of inline queries. They are:
{| class="smwtable"
{| class="smwtable"
! Description
! Description
|-
|-
| limit
| <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>sort</tt>
| attribute name
| attribute name
| name of attribute to use for sorting queries; this attribute must occur in the query in a statement without "*"
| name of attribute to use for sorting queries; this attribute must occur in the query in a statement without "*"
|-
|-
| order
| <tt>order</tt>
| "ascending"/"asc", "descending"/"desc"/"reverse"
| "ascending"/"asc", "descending"/"desc"/"reverse"
| defines how results should be ordered, only used if <tt>sort</tt> is used, "ascending" is the default
| defines how results should be ordered, only used if <tt>sort</tt> is used, "ascending" is the default
|-
|-
| headers
| <tt>count</tt>
| none
| specifies that only the number of results should be displayed, not the results themselves
|-
| <tt>headers</tt>
| "show", "hide"
| "show", "hide"
| shows or hides the labels/headers used in the output, "hide" is deault
| shows or hides the labels/headers used in the output, "hide" is default
|-
|-
| mainlabel
| <tt>mainlabel</tt>
| 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)
|-
|-
| link
| <tt>link</tt>
| "none", "subject", "all"
| "none", "subject", "all"
| defines which article names in the result are hyperlinked, "subject" normally is the default
| defines which article names in the result are hyperlinked, "subject" normally is the default
|-
|-
| 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, no result is being created, this will be returned
|-
|-
| intro
| <tt>intro</tt>
| plain text
| plain text
| initial text that is prepended the output, if at least some results exist
| initial text that is prepended the output, if at least some results exist
|-
|-
| debug
| <tt>debug</tt>
| "true"
| "true"
| gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results
| '''[only SMW≤0.6]''' gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results
|-
|-
| format
| <tt>format</tt>
| a format name (see below)
| a format name (see below)
| selected output format, some formats allow further parameters (see below)
| selected output format; some formats allow further parameters (see below)
|}
|}
</ask></pre>
</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.
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 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. 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.
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
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. 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>
<nowiki><ask limit="0" searchlabel="Browse list of countries">[[Category:Country]]</ask></nowiki>
=== Sorting results ===
=== 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
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 parameters. 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">
<pre><ask sort="population" order="descending">
[[Category:Country]]
[[Category:Country]]
[[located in::Africa]]
[[located in::Africa]]
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.
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
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 alternative labels, as it is known for links in MediaWiki. For example, the query
<pre><ask>
<pre><ask>
Upcoming conferences: [[IJCAI2007]], [[ICCS2007]], …
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
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:
Upcoming conferences:
which is not desriable. Two parameters exist to prevent this.
which is not desirable. 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
* <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
| '''Unstable.''' Embed selected articles.
| '''Unstable.''' Embed selected articles.
| <tt>titleformat</tt>
| <tt>titleformat</tt>
|-
| [[Help:Template format|<tt>template</tt>]]
| '''Unstable.''' Print results by passing result fields as parameters to a given template.
| <tt>template</tt> (mandatory)
|-
| [[Help:Table debug|<tt>debug</tt>]]
| Debugging information for analysing problems in query answering.
|
|}
|}
[[Category:Semantic MediaWiki]]
=== Using templates ===
In an inline query, when <nowiki>format=template</nowiki> or <nowiki>format=list</nowiki>, wiki templates may be used to format the output of the query, using the following syntax (SMW 0.7):
:::<nowiki><ask format=template template=templatename></nowiki> ... </ask> or
:::<nowiki><ask format=list template=templatename> ... </ask></nowiki>.
The variables used in the template are numbered in the same order that the output of the inline query would have without the template format. (that is, <nowiki>{{{1}}}, {{{2}}}, ... {{{3}}}</nowiki> etc.)
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;
:*Using variables to display images;
:*Using variables to create links for attributes;
:*Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables.
When output is limited, the template format will not be carried forward to the continuation link.
[[Category:Semantic MediaWiki]]
[[Category:Semantic MediaWiki]]
