Help:Inline queries 1.0

From Edge of Darkness Wiki

You do not have permission to edit this page, for the following reason:

You can view and copy the source of this page:

{{SMW user TOC}} [[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. == Introduction == 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 <nowiki>{{</nowiki>#ask: <i>argument 1</i> | <i>argument 2</i> | &hellip; <nowiki>}}</nowiki> where the arguments &hellip; describe the query. (Note that prior to Semantic MediaWiki version 1.0 there was a different syntax for inline queries using an <tt><nowiki><ask></nowiki></tt> 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 [[Help:Semantic search|semantic search]]. For example, one can write <nowiki>{{#ask: [[Category:City]] [[located in::Germany]] }}</nowiki> 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 here: '''Result:''' {{#ask: [[Category:City]] [[located in::Germany]] }} 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. To display additional properties of the pages matching the condition, you add additional arguments of the form ?''property name'', for example <pre>{{#ask: [[Category:City]] [[located in::Germany]] | ?Population }}</pre> '''Result:''' {{#ask: [[Category:City]] [[located in::Germany]] | ?Population }} A few things to note: * We use the pipe ''''|'''' symbol 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. * As you can see, you can add white space within the #ask function, the parsing is fairly flexible. * 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 have extensive control of the appearance of query results. == Inline query arguments == 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 formatted within the page? The first two points are explained at [[Help:Semantic search]]. The third point is largely independent of the first two, but is important to smoothly include query results in pages. In our above example, we might wish to get a bulleted list of countries, which we can achieve using <tt>format=ol</tt>: <pre>{{#ask: [[Category:Vampire]] [[Clan::Daeva]] [[Character Status::Active]] | ?Covenant | format=ul }}</pre> '''Result:''' {{#ask: [[Category:Vampire]] [[Clan::Daeva]] [[Character Status::Active]] | ?Covenant | format=ul }} SMW implements a wide variety of output formats for inline queries, and allows you to futher control results display using a MediaWiki template. In addition to this "format" parameter, inline queries accept other parameters that affect results display, e.g. for sorting the results or for limiting the number of returned items. == Standard parameters == A number of standard parameters are always available for customising the result of inline queries. They are: {| class="smwtable" ! Parameter ! Possible values ! Description |- | <tt>limit</tt> | non-negative number | maximal number of pages selected (in the case of a table: rows) |- | <tt>offset</tt> | number | where to start |- | <tt>sort</tt> | property name | name of property to use for sorting queries |- | <tt>order</tt> | <tt>ascending</tt>/<tt>asc</tt>, <tt>descending</tt>/<tt>desc</tt>/<tt>reverse</tt> | defines how results should be ordered, only applicable if <tt>sort</tt> is used, <tt>ascending</tt> is the default |- | <tt>headers</tt> | <tt>show</tt>, <tt>hide</tt> | shows or hides the labels/headers used in some output formats such as "table", <tt>hide</tt> is default |- | <tt>mainlabel</tt> | plain text | title of the first column (the one with the page titles in it), default is no title; set to <tt>-</tt> to suppress printing the page titles |- | <tt>link</tt> | <tt>none</tt>, <tt>subject</tt>, <tt>all</tt> | defines which article names in the result are hyperlinked, <tt>all</tt> normally is the default |- | <tt>default</tt> | plain text | if, for any reason, the query returns no results, this will be printed instead |- | <tt>intro</tt> | plain text | initial text that is prepended the output, if at least some results exist |- | <tt>searchlabel</tt> | plain text | text for continuing the search (default is "&hellip; further results") |- | <tt>debug</tt> | <tt>true</tt> | '''[only SMW&le;0.6]''' gives an [[wikipedia:SQL|SQL]] statement for debugging instead of the query results |- | <tt>format</tt> | a format name (see below) | selected output format; some formats allow further parameters (see [[#Output formats]]) |} === Result limits and further results === You can set the parameter <tt>limit</tt> to restrict the maximum number of results that are returned. For example, the query <pre>{{#ask: [[Category:City]] [[located in::Germany]] | limit=3 }}</pre> displays at most 3 cities in Germany. Even if you do not specify a value for <tt>limit</tt>, 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 <tt>limit</tt>. However, there is usually a maximum limit that cannot be exceeded, set by the wiki administratorbased on performance considerations. Let's run the above query, '''Result:''' {{#ask: [[Category:City]] [[located in::Germany]] | limit=3 }} As you should see, when a query does not display all matches due to a limit, it will often show a link to "further results". The text of this link can be modified by setting the parameter <tt>searchlabel</tt>. If the value of <tt>searchlabel</tt> is "", 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 <tt>limit</tt> and <tt>searchlabel</tt> is to display ''only'' a link to the results of a search, without showing any result inline. You achive this by specifying a limit of "0". For instance, the query <nowiki>{{#ask: [[Category:City]] | limit="0" | searchlabel=Click to browse a list of cities }}</nowiki> displays '''Result:''' {{#ask: [[Category:City]] | limit="0" | searchlabel=Click to browse a list of cities }}. === Nothing returned, nothing appears === If no articles satisfy the conditions of a query, ''nothing appears''. This can be useful, but more often an inline query drifts out of sync with semantic notations on the wiki and nobody notices the query on a page laboring to display nothing. To ensure a query always displays something, you should specify text for the <tt>default</tt> parameter, for example <pre>{{#ask: [[Category:City]] [[Located in::Antarctica]] | intro=All about cities in the Antarctic |?Population |?Area | default=Apparently there are no cities in the Antarctic }}</pre> '''Result:''' {{#ask: [[Category:City]] [[Located in::Antarctica]] | intro=All about cities in the Antarctic |?Population |?Area | default=Apparently there are no cities in the Antarctic }} === Sorting results === 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 <tt>sort</tt>, and the order with the parameter <tt>order</tt>; the value of <tt>order</tt> should be "ascending" or "descending" (or the short forms "asc" and "desc", or "reverse"). Sorting on a property implicitly sets a condition that pages must have a value for that property (a condition which you would otherwise set with <tt><nowiki>[[</nowiki>''Prop name''::+]]</tt>). For example, this query for cities sorted by area only shows cities that have a value for [[Property:Area]]: <pre>{{#ask: mainlabel=cities sorted by area | [[Category:City]] [[Located in::Germany]] | ?Population | sort=Area }}</pre> '''Result:''' {{#ask: mainlabel=cities sorted by area | [[Category:City]] [[Located in::Germany]] | ?Population | sort=Area }} === Configuring labels/table headers === 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. In the table format, the labels appear as column headers. In other formats, the labels might appear right before the output fields. 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 By default, the label just displays the name of the requested property, or the text "Category" if categories are displayed. The [[Help:Semantic_search#Header_label|Header label section of the Semantic search page]] tells you how to specify alternate text for labels. For example,<pre>{{#ask: [[Category:City]] |?Population= |?Area#km²=Size in km² |?Category=Category memberships |format=table |default=nothing found in category City }}</pre> '''Result:''' {{#ask: [[Category:City]] |?Population= |?Area#km²=Size in km² |?Category=Category memberships |format=table |default=nothing found in category City }} Labels for properties display as a link to the respective pages in the Property: namespace. ===Page title display=== When you query to select pages and display using table format, the first column is usually the page titles matching the query with a blank column header. To set the label for the page titles, use the parameter <tt>mainlabel</tt>. If you don't want the page titles to appear, set mainlabel to the magic value '<tt>'''-'''</tt>'. ''This might change in future versions to provide an additional simpler method with the |-syntax.'' If you want to show the page titles elsewhere than the first column, disable their default display in the first column with <tt>mainlabel=-</tt>, then explicitly request their display using <tt><b>| ?</b></tt> (i.e. display the "unnamed" column). For example, modifying the example above to display the city name after Population,<pre>{{#ask: [[Category:City]] [[Located in::Germany]] |?Population=This many people |?=Live in |format=table |mainlabel=- }}</pre> '''Result:''' {{#ask: [[Category:City]] [[Located in::Germany]] |?Population=This many people |?=Live in |format=table |mainlabel=- }} === 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]], &hellip; 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. * <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 above 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-separated 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>, <tt>template</tt> |- | [[Help:List format|<tt>ol</tt>]] | Ordered list, with additional outputs shown in parentheses | <tt>sep</tt>, <tt>template</tt> |- | [[Help:List format|<tt>ul</tt>]] | Bulleted list, with additional outputs shown in parentheses | <tt>sep</tt>, <tt>template</tt> |- | [[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>timelinestart</tt>, <tt>timelineend</tt>, <tt>timelinesize</tt> (default "300px"), <tt>timelinebands</tt>, <tt>timelineposition</tt> (default "middle") |- | [[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>timelinestart</tt>, <tt>timelineend</tt>, <tt>timelinesize</tt> (default "300px"), <tt>timelinebands</tt>, <tt>timelineposition</tt> (default "middle") |- | [[Help:Embedded format|<tt>embedded</tt>]] | '''Unstable.''' Embed selected articles. | <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>]] | '''Unstable.''' Print results by passing result fields as parameters to a given template. | <tt>template</tt> (mandatory) |- | [[Help:Count format|<tt>count</tt>]] | Just the number of results (a count of the number of matching pages), instead of the results themselves | |- | [[Help:Table debug|<tt>debug</tt>]] | Debugging information for analysing problems in query answering. | |- | [[Help:Rss format|<tt>rss</tt>]] | Print links to RSS feeds for query results. | <tt>rsstitle</tt>, <tt>rssdescription</tt> |- | [[Help:Googlebar format|<tt>googlebar</tt>]] | A bar chart comparing numerical results | <tt>width</tt> (optional) |- | [[Help:Googlepie format|<tt>googlepie</tt>]] | A pie chart showing shares | <tt>width</tt> (optional), <tt>height</tt> (optional) |} === Using templates === You can create a wiki [[meta:Help:Template|template]] to control the display of an inline query. This works for <tt>format=template</tt> or <tt>format=list</tt>/<tt>ol</tt>/<tt>ul</tt>. In the inline query you specify the wiki template using the following syntax: <nowiki>{{#ask: ... | format=template/list/ol/ul | template=templatename }}</nowiki> Semantic MediaWiki performs the inline query and passes each selected page to your template in turn. In the template you put the text and formatting you want to display around query results; where you want to display part of the query results you use numbered parameters <tt>{{{1}}}</tt>, <tt>{{{2}}}</tt>, etc. Each parameter refers to one "field" or column in the results that would be displayed by the inline query for each selected page. Normally the first field a query displays is the page title (see [[#Page title display]]), so parameter <tt>{{{1}}}</tt> is the page title, and <tt>{{{2}}}, {{{3}}}, ...</tt> are the other properties displayed by the query. The template feature allows greater flexibility in the display 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 property values; *Using CSS styles to vary font-size, alignment, background-color, etc. by column in tables. Notes: *In the template, you cannot apply parser functions to parameters (e.g. for computations and branching), they do not work. *Some queries do not display the page title of the matching page, for example if you directly specify the pages in the query. Without the page title, <tt>{{{1}}}</tt> would refer to the first displayed field about the page. In order to reuse the same template in this case, you can force the query results to include the page title by adding ? (i.e. the "unnamed" column for the page title) as the first field to display. See the last example. These examples all use [[Template:Query output demo]], view its source. <pre>{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] | ?Population=Inhabitants | ?Area#km²=Size in km² | format=template | template=Query output demo | limit=3 }}</pre> '''Result:''' {{#ask: [[Category:City]] [[Area::+]] [[Population::+]] | ?Population=Inhabitants | ?Area#km²=Size in km² | format=template | template=Query output demo | limit=3 }} In the above example you can see how the template ignores any header labels specified in the query such as "Size in km²". But the values the template displays do use the units display format specified in <tt>?Area'''#km²'''=Size in km²</tt> (see [[Help:Semantic_search#Display_format | Display format in Semantic search help]]). Below is a similar query sorted by population that uses <tt>format=ol</tt> to produce a numbered list. <pre>{{#ask: [[Category:City]] [[Area::+]] [[Population::+]] | ?Population | ?Area#km² | format=ol | template=Query output demo | limit=3 | sort=population | order=desc }}</pre> '''Result:''' {{#ask: [[Category:City]] [[Area::+]] [[Population::+]] | ?Population | ?Area#km² | format=ol | template=Query output demo | limit=3 | sort=population | order=desc }} If we directly specify a single page, then normally the query results do not include the page, so to reuse the same template in the query below we must tell the query to display the page title as the first column by adding <tt>|?</tt> <pre>{{#ask: [[Berlin]] [[Area::+]] [[Population::+]] | ? | ?Population | ?Area#km² | format=template | template=Query output demo }}</pre> '''Result:''' {{#ask: [[Berlin]] [[Area::+]] [[Population::+]] | ? | ?Population | ?Area#km² | format=template | template=Query output demo }} ==Using a query to produce annotations == When querying for a property, SMW does not (currently) automatically query for transitive or inverse properties. Pages must have the properties in the query being made. For example, even if there are pages for architects with the property ''Architect of'', you must still annotate pages for buildings with ''<nowiki>[[Has architect::Le Corbusier]]</nowiki>'' to make this 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 <nowiki>Its architect is [[Has architect::{{#ask: [[Architect of::{{PAGENAMEE}}]]|link=none}} ]]</nowiki> If there is more than one inverse property, this will not work. It's possible to do this more directly using templates, see [[Germany (inverse example)]]. == Old <nowiki><ask></nowiki> tag format == Prior to SMW version 1.0, you would write inline queries inside an ask tag. <nowiki><ask</nowiki> ''params''>...</ask> where the &hellip; 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 [[Help:Semantic search|semantic search]]. For example, <nowiki><ask>[[Category:City]] [[located in::Germany]]</ask></nowiki> Unlike the <nowiki>{{#ask:}}</nowiki> function, * you specify additional properties to display by mentioning them in annotation format with a '*' in place of any condition, and use '|' syntax to introduce the column label * you specify additional parameters in the opening ask tag.

Return to Help:Inline queries 1.0.