ShadowWolf: creating another help page for the semantic extensions - this time all about how to use it's search facilities

2009-02-14T22:59:49Z

creating another help page for the semantic extensions - this time all about how to use it's search facilities

New page

Semantic properties are useless if you can't use them in some way, so the creators of the [http://semantic-mediawiki.org Semantic MediaWiki] extension have provided three facilities for querying the database about them: [[Special:Ask|The 'Ask' Special Page]],the <nowiki>{{#ask}}</nowiki> parser function and the <nowiki>{{#show}}</nowiki> parser function.
__TOC__{{help}}
== Special:Ask ==
=== Overview ===
This page has two panes — the left is where you enter your query and the right is where you can ask for it to output additional pieces of semantic information. The left pane expects the query in a certain format — it is almost a complete database query language, but the advanced features need not be used. On the other hand the right pane is much simpler, and while it also expects input to be in a certain format, it is not as complex as the query setting.
=== Queries ===
The queries are actually a bit simpler than I have made them sound, though constructing a proper query can be tricky. By default you just enter a series of terms–similar to what you are used to with [http://www.google.com Google] but the terms are required to be in a specific format–and the system will use the "AND" principle to find pages that match every one of the specified terms.
=== Extra Information ===
The right-hand page is meant to be used to detail extra properties you want displayed in the results. These are formatted as: ?<property name>
== <nowiki>{{#ask}}</nowiki> ==
=== Overview ===
This is how you can create an "inline query" that is embedded on a page. The basic format of this really special tag is:
<pre><nowiki>{{#ask: <query>
| ?<property name>
}}</nowiki></pre>
=== Specifically ===
The 'query' parameter of the tag can be any valid query that you'd pass to [[Special:Ask]] and the 'property name' parameters are what you would enter into the right-hand pane of the [[Special:Ask]] page.

There are other parameters available and these let you specify the format of the output and a lot of other factors… An example of a quick&dirty query without any of the extra parameters is:
<nowiki>{{#ask: [[Category:Story]][[setting::Xanadu]][[author::ShadowWolf]] | ?title | ?setting | ?author }}</nowiki>
Which produces the following results:
{{#ask: [[Category:Story]][[setting::Xanadu]][[author::ShadowWolf]] | ?title | ?setting | ?author }}
But by adding the 'format' parameter we get:
<nowiki>{{#ask: [[Category:Story]][[setting::Xanadu]][[author::ShadowWolf]] | ?title | ?setting | ?author | format=broadtable }}</nowiki>
Which generates:
{{#ask: [[Category:Story]][[setting::Xanadu]][[author::ShadowWolf]] | ?title | ?setting | ?author | format=broadtable }}
Big difference, no?

The 'format' parameter and the demonstrated possible value for it of 'broadtable' is just an example. See the [http://semantic-mediawiki.org/wiki/Help:Inline_queries Semantic MediaWiki Help Page] for more information on the possible values and more.
== <nowiki>{{#show}}</nowiki> ==
The <nowiki>{{#show}}</nowiki> parser function allows for directly inserting the results of a semantic query inline into a page. The basic format is the same as that of the <nowiki>{{#ask}}</nowiki> function, with the exception that you give it a page name (what you'd put inside the double-brackets to create a link) instead of a query. For instance, if you want to know the setting of '[[User:ShadowWolf/Ripples in Time|Ripples in Time]]' you could just do <nowiki>{{#show: User:ShadowWolf/Ripples in Time|?setting}}</nowiki> — {{#show: User:ShadowWolf/Ripples in Time|?setting}}

A different form, and one that is slightly more powerful, is by using a special form of the <nowiki>{{#ask}}</nowiki> – <nowiki>{{#ask:<page link>|?<property>=}}</nowiki>. Taking the previous example, that would be <nowiki>{{#ask:[[User:ShadowWolf/Ripples in Time]]|?setting=}}</nowiki> - which generates the result: {{#ask:[[User:ShadowWolf/Ripples in Time]]|?setting=}}
== General Information ==
=== Category Matches ===
To match against a category, you enter it in the same format you would use to add the category to a page—ie:<nowiki>[[Category:Story]]</nowiki>. This will return every page that is either directly or indirectly<ref>Indirectly, in this case, means 'is not in the category, but is in a sub-category (add as many sub-'s as you want) of that category</ref> in that category.
=== Property Matches ===
Matching against properties is very similar–the format is <nowiki>[[<property name>::<property value>]]</nowiki>.<ref>This is, technically, also the format for adding a property directly. However, because this creates links to pages with the name of the property value, we ask that you use the [[Template:SMW Base|Semantic Property Template]] (<nowiki>{{SMW Base}}</nowiki></ref>
=== Comparisons ===
Say, for instance, you want to match every page that is fiction and not in the [[Paradise (setting)|Paradise]] setting–with just property matches and category matches this isn't possible. However there is a way to do it—by using a 'comparison operator'. The solution to the problem I set would be to have <nowiki>[[setting::!Paradise]]</nowiki> as one of the terms. The available comparison operators are:
<dl>
<dt><</dt>
<dd>The value is less than the specified value. (<nowiki>[[height::<6 ft]]</nowiki>, for instance, would match any 'height' property that was set to a value under six feet.</dd>
<dt>></dt>
<dd>The exact opposite of the 'less than' operator.</dd>
<dt>!</dt>
<dd>The value is not the same as what the property is set to. (see the opening example)</dd>
<dt>~</dt>
<dd>This is the "similarity" operator, used for matching a small piece of text in a larger value. (<nowiki>[[name::~*Xanadu*]]</nowiki> would match all properties that had the word 'Xanadu' in them)</dd>
</dl>
=== Wildcards ===
There is only one wildcard defined for matching semantic properties and that is the plus sign (+). It is used to mean 'any value' – ie: <nowiki>[[setting::+]]</nowiki> would match any page that had the 'setting' property set.
=== Alternation ===
If you want to match a series of properties—perhaps you're looking for a story that is either set in [[Xanadu (setting)|Xanadu]] or [[Paradise (setting)|Paradise]] then the 'AND' method that the most basic of searches occurs in won't work—you need an 'OR' type of search. To do that, simply put the word 'OR'<ref>Yes, without the quotes :P</ref> in between the terms.

To simplify things you could format the above example as: <nowiki>[[setting::Paradise||Xanadu]]</nowiki> – this form is what I'd recommend be used.
=== Namespace Restriction ===
On Shifti this isn't that useful in general. However, if you are trying to spot a [[Special:SpecialPages|Special Page]] or a [[Help:Contents|Help Page]] then this will be very handy. To restrict a search to a namespace you'd add <nowiki>[[<namespace name>:+]]</nowiki> to the list of search terms.(ie: to restrict the search to the 'Help' namespace, you'd add <nowiki>[[Help:+]]</nowiki> to the list of search terms)
=== Chained Queries ===
You can also 'chain' queries together. Suppose, for a moment, that Shifti offered the same breadth of articles as [http://en.wikipedia.org Wikipedia] and you wanted to find a list of all actors born in Italy. You know there is a list of cities located in Italy and also know that there is a 'born in' property, but the classic query syntax doesn't let you feed the output of one query into another.

By chaining the queries together you can solve this problem. The solution to the above problem would be a query with the terms: <nowiki>[[Category:Actor]] [[born in::<q>[[cities in::Italy]]</q>]]</nowiki>. Yes—the <q> tag gets wrapped around the query! And this can be nested to any depth. (ie: to extend the above to all of europe you'd just change the <nowiki>[[born in]]</nowiki> term to: <nowiki>[[born in::<q>[[cities in::<q>[[countries in::Europe]]</q>]]</q>]]</nowiki>)
=== Templates and Variables ===
Templates and Template Variables can be used in queries. You can just insert them into the "value" side of things when you want to use them.<ref><nowiki>{{#vardefine}}</nowiki> style variables could possibly be used, but there is no information available as to whether this is true or not, so we'd recommend you not use them in queries.</ref>
== References ==
<references/>

Help:Semantic search - Revision history

ShadowWolf: creating another help page for the semantic extensions - this time all about how to use it's search facilities