Sorting
| Sorting | |
|---|---|
| This help page informs about how sorting of queried results can be done. | |
| Keywords | |
| Table of Contents | |
Semantic MediaWiki will usually attempt to sort results by the natural order that the values of the selected property may have:
- "numbers" are sorted numerically,
- "text" is sorted alphabetically and
- "dates" are sorted chronologically.
The order therefore is the same as in the case of the < and > comparators in queries. If no specific sorting condition is provided, results will be ordered by their page name.
It is possible to provide more than one sorting condition. If multiple results turn out to be equal regarding the first sorting condition, the next condition is used to order them and so on. For example we could get a list of cities by their average number of rainy days per year, but grouped by the country they are in, with the following query:
{{#ask:
[[Category:City]]
|?Located in=Country
|?Average rainy days
|sort=Located in,Average rainy days
|order=asc,desc
}}
resulting in
Sorting a query also influences the result of a query, because it is only possible to sort by property values that a page actually has (See also the info box below). Therefore, if a query is ordered by a property (say «Population») then SMW will usually restrict the query results to those pages that have at least one value for this property (i.e. only pages with specified population appear). Therefore, if the query does not require yet that the property is present in each query result, then SMW will silently add this condition. But SMW will always try to find the ordering property within the given query first, and it is even possible to order query results by subproperties. Some examples should illustrate this:
[[Category:City]] [[Population::+]]ordered by "Population" will present the cities with population in ascending order. The query result is the same as without the sorting.
[[Category:City]]ordered by "Population" will again present the cities with population in ascending order. The query result may be modified due to the sorting condition: if there are cities without a population provided, then these will no longer appear in the result.
[[Category:City]] [[has location country.population::+]]ordered by "Population" will present the cities ordered by the population of the countries they are located in. The query result is not changed, but "population" now refers to a property used in a subquery. Again the population must be annotated for the countries to avoid it being omitted due to the sorting condition.
Query results displayed in a result table can also be ordered dynamically by clicking on the small sort icons found in the table heading of each column. This function requires JavaScript to be enabled in the browser and will sort only the displayed results. So if, e.g., a query has retrieved the twenty world-largest cities by population, it is possible to sort these twenty cities alphabetically or in reverse order of population, but the query will certainly not show the twenty world-smallest cities when reversing the order of the population column. The dynamic sorting of tables attempts to use the same order as used in SMW queries, and in particular orders numbers and dates in a natural way. However, the alphabetical order of strings and page names may slightly vary from the wiki's alphabetic order, simply because there are many international alphabets that can be ordered in different ways depending on the language preference.
SMW_QSORT_UNCONDITIONAL to configuration parameter $smwgQSortFeaturesSets the behaviour for the sorting features of the semantic search is available that will make sorting by a property work unconditionally even if the respective property was not set to all pages selected, i.e. all pages will be shown.
Sorting by default[edit]
Query results are typically pages, subobjects and/or values of datatype "Page"[1] If no specific sorting condition is provided, then these are sorted alphabetically, in ascending order.
The alphabetical sorting order, or collation to be precise, is dictated by MediaWiki's $wgCategoryCollation setting, if this is set to uppercase or identity. Semantic MediaWiki supports uca-default and of its language-specific adjustments since version 3.0.0 (#1383). For details see $smwgEntityCollation.
Natural sorting of pages may not be supported out of the box. An example is the alphanumeric kind by which numeric portions of a page title are treated as numbers - e.g. so that b9 comes before rather than after b1000.[2] As a possible halfway solution, note that the sortkey of a page may be overridden using the {{DEFAULTSORT:}} magic word. If you add a sortkey using {{DEFAULTSORT:}} you do not need to specify extra sorting in your query since Semantic MediaWiki will adhere to the values thus set.1
- Example
The natural sort order / results (for U.S. landmarks) might be:
* Freedom Tower * Statue of Liberty * The Pentagon * The U.S. Capitol Building * The White House
What you want to do is go to the respective pages, and using the magic word {{DEFAULTSORT:}} change the default to things like:
- {{DEFAULTSORT:Pentagon, The}}
- {{DEFAULTSORT:Capitol Building, U.S.}}
- {{DEFAULTSORT:White House, The}}
Then the results are:
* The U.S. Capitol Building * Freedom Tower * The Pentagon * Statue of Liberty * The White House
Names of subobjects usually consist of the title of the page on which they are declared, followed by a hashtag (#) and a custom identifier or autogenerated series of numbers (hash-numbering). Beginning with SMW 2.0, subobjects may also be assigned a custom sortkey: see Help:Adding subobjects#Specifying a sortkey.
Providing sorting conditions: using parameters[edit]
The following query parameters let you specify sorting conditions for a query.
| Parameter | Possible values | Description |
|---|---|---|
| sort |
|
The name of the property, property chain or category to be used for sorting queries. A comma-separated list of values is possible to allow for secondary (and tertiary, etc.) sorting orders. The values provided for order will then follow the same sequence.
|
| order |
ascending (short: asc) |
Defines whether results should be ordered in ascending, descending or random order. Default: ascending. |
| offset | number | where to start |
The sort parameter takes a property name or a comma-separated list of property names. It lets you sort results by the order in which the values of any selected property are "naturally" sorted. By "natural" sorting is meant that:
- sorting by a property of datatype "Page"Holds names of wiki pages, and displays them as a link is alphabetical (the note above about Configuration parameter
$wgCategoryCollation(MediaWiki.org) and the{{DEFAULTSORT:}}variable also applies here)2 - sorting by a property of datatype "Text"Holds text of arbitrary length is alphabetical
- sorting by a property of datatype "Number"Holds integer and decimal numbers, with an optional exponent is numerical
- sorting by a property of datatype "Date"Holds particular points in time is chronological.
- and so on...
(Use of < and > comparators in queries follow the same "natural" sorting order)
- Example
You have pages about cities and you want to present a list of cities sorted by population size. The sort parameter would then take the property that is used for storing population size. If this list is to be shown in reverse order of population size, from the city that has the largest population downwards, the order parameter would be set to descending. Such a query would look like:
{{#ask:
[[Category:City]]
|?Population size
|sort=Population size
|order=descending
}}
Providing multiple sorting conditions[edit]
It is possible to provide more than one sorting condition. If multiple results turn out to be equal regarding the first sorting condition, the next condition is used to order them and so on.
- Example
We want to get a list of cities by their average number of rainy days per year, but grouped by the country they are in, with the following query:
{{#ask:
[[Category:City]]
|?Located in=Country
|?Average rainy days
|sort=Located in,Average rainy days
|order=asc,desc
}}
resulting in Restrictive implications of using sort[edit]
Sorting a query also influences the result of a query, because, by default, it is only possible to sort by property values that a page actually has. Therefore, if a query is ordered by a property (say Population) then SMW will usually restrict the query results to those pages that have at least one value for this property (i.e. only pages with specified population appear). Therefore, if the query does not require yet that the property is present in each query result, then SMW will silently add this condition. See the option SMW_QSORT_UNCONDITIONAL of configuration parameter $smwgQSortFeaturesSets the behaviour for the sorting features of the semantic search to change that behaviour.3
What if there are multiple property values per page?[edit]
If a property that is used for sorting has more than one value per page, then this page will still appear only once in the result list. The position that the page takes in this case is not defined by SMW and may correspond to either of the property values. In the above examples, this would occur if one city has multiple population numbers specified, or if one city is located in multiple countries each of which has a population. It may be best to avoid such situations.
Sorting the main column[edit]
If sorting should include the mainlabel and properties at the same time, you can treat the mainlabel as empty string (as there is no identifier for it). So this works, it sorts first after the mainlabel and second after the Average rainy days
{{#ask:
[[Category:City]]
|?Located in=Country
|?Average rainy days
|sort=,Average rainy days
|order=asc,desc
}}
resulting in
Providing sorting conditions: alternatives[edit]
Sortable tables[edit]
Query results displayed in a result table can also be ordered dynamically by clicking on the small sort icons found in the table heading of each column. This function requires JavaScript to be enabled in the browser and will sort only the displayed results. So if, e.g., a query has retrieved the twenty world-largest cities by population, it is possible to sort these twenty cities alphabetically or in reverse order of population, but the query will certainly not show the twenty world-smallest cities when reversing the order of the population column. The dynamic sorting of tables attempts to use the same order as used in SMW queries, and in particular orders numbers and dates in a natural way. However, the alphabetical order of strings and page names may slightly vary from the wiki's alphabetic order, simply because there are many international alphabets that can be ordered in different ways depending on the language preference.
Demo[edit]
The special page "Ask" has a simple interface to add one or more sorting conditions to a query. The name of the property to sort by is entered into a text input, and ascending or descending order can be selected.
Notes[edit]
- ↑ The latter may be true if an inverse property is used, even if the page does not exist.
- ↑ See Bugzilla, e.g. #T8948
See also[edit]
- Help page on specifying a sortkey for subobjects
- Help page on configuration parameter
$smwgQSortFeaturesSets the behaviour for the sorting features of the semantic search - Help page on Sequence map
- Mailing list
- Maintain order of property values4
References
- ^ Semantic MediaWiki: User mailing list thread "category format sorting results"
- ^ Sorting example - Showing the effect of using the
'"`UNIQ--nowiki-00000015-QINU`"'variable. - ^ Semantic MediaWiki: GitHub pull request gh:smw:2823
- ^ Semantic MediaWiki: Developer mailing list thread "Maintain order of property values"
