Help:Встраиваемые запросы
В Semantic MediaWiki есть простой, но мощный язык запросов SMW-QL, открывающий поистине безграничные возможности семантического поиска в вики. В то время как семантические свойства и категории позволяют структурировать данные в вики, запросы нужны для того, чтобы использовать эту информацию: они помогают вики-пользователям и вики-администраторам комбинировать данные и визуализировать их. Разумеется, рядовые посетители вики не обязаны учить язык запросов, и могут даже не знать о его существовании. Однако и они могут почувствовать разницу в работе с сайтом на Semantic MediaWiki благодаря возможности сохранять запросы прямо в тексте вики-статьи (мы будем называть такие запросы встраиваемыми или хранимыми). Созданные технически подкованными пользователями запросы будут динамически отбирать информацию из вики и форматировать свои результаты в виде диаграмм, географических карт, таблиц и схем. По мере изменения информации в вики, результаты запросов будут также автоматически обновляться, обеспечивая непротиворечивость и согласованность данных. Semantic MediaWiki позволяет разделить обязанности между пользователями, чтобы создание структурированных запросов досталось вики-администраторам и редакторам, знающим язык запросов: потреблять и смотреть на результаты запросов может любой посетитель вашего вики-сайта.
Вики-администраторы могут ограничивать возможности семантического поиска в случаях, когда возникают проблемы с производительностью. Следует, однако, заметить, что встраиваемые запросы используют систему кэширования MediaWiki, а потому не должно возникать серьёзных проблем с быстродействием.
Contents
Функция #ask[edit]
Чаще всего встраиваемые запросы используются в сочетании с функцией ask. Эта функция используется так же как и другие функции синтаксического анализатора MediaWiki: её вызов заключается в двойные фигурные скобки, до имени ставится знак решетки #, а после - двоеточие. Вначале передается сама строка запроса, отбирающая нужную информацию из вики, а затем все параметры запроса, разделенные символами вертикальной черты |. Запрос населения и площади всех городов, находящихся в Германии будет выглядеть следующим образом:
{{#ask: [[Category:City]] [[located in::Germany]]
| ?population
| ?area#km² = Size in km²
}}
Как видно, здесь у функции ask три параметра. Первый параметр отбирает из всего множества страниц лишь те, что помечены категорией City и имеют семантическое свойство located in со значением, Germany. Второй параметр говорит о том, что у каждой статьи о немецком городе нужно спросить значение свойства population. Третий параметр говорит о том, что нас интересует также значение свойства area, переведенное в квадратные километры.
Результат этого запроса выглядит следующим образом:
| PopulationThe number of inhabitants of some geographical place. | Size in km² | |
|---|---|---|
| Berlin | 3,520,061 | 891.85 km²344.34 sqmi <br /> |
| Cologne | 1,080,394 | 405.02 km²156.38 sqmi <br /> |
| Frankfurt | 679,664 | 248.31 km²95.87 sqmi <br /> |
| Munich | 1,353,186 | 310.43 km²119.86 sqmi <br /> |
| Stuttgart | 606,588 | 207.35 km²80.06 sqmi <br /> |
| Würzburg | 126,635 | 87.63 km²33.83 sqmi <br /> |
Обратите внимание на следующие вещи:
- Каждый параметр функции ask начинается с новой строчки. Так запрос выглядит аккуратнее и легче читается.
- Если вы поместили этот запрос на страницу, она НЕ будет помечена категорией City или семантическим свойством located in со значением Germany: в данном случае и то и другое является параметрами самого запроса.
- по умолчанию запрос выводит данные в виде таблицы. У вас есть целый арсенал других способов форматирования результатов запроса, см. форматы вывода.
Таким образом, базового понимания того как запрашивать данные и отображать их вполне достаточно для того, чтобы писать большинство видов встраиваемых запросов. Иногда, правда, недостаточно лишь этой базы: порой необходимо вывести только часть результатов запроса, отсортировать их, отформатировать результаты определенным образом.
Большая часть этого руководства описывает то, какие параметры можно передавать во встраиваемый запрос, и как они будут себя в нем вести.
Функция #show[edit]
Часто нам нужно всего лишь отобразить значение одного семантического свойства для одной страницы. Пусть, к примеру, у вас есть страница о Берлине, и на ней имеется информация о населении этого города. Само собой, она сохранена в качестве значения семантического свойства population. Вы начинаете писать другую вики-статью и вдруг вам понадобилось население Берлина. Можно, конечно, вручную скопировать конкретное количество жителей на данный момент. Однако, тогда придется следить за согласованностью данных и вручную обновлять информацию о населении на всех страницах. Гораздо лучше, просто запросить население Берлина небольшим запросом со страницы Berlin, и пусть Semantic MediaWiki позаботится о том, чтобы поддерживать эту информацию в актуальном состоянии на всех зависимых страницах. Для того, чтобы сделать подобного рода запросы проще, в SMW есть специальная функция #show. В нашем примере мы напишем следующее:
По результатам последней переписи в Берлине {{#show: Berlin | ?population}} человек.Результат:
По результатам последней переписи в Берлине 3,520,061 человек.
На самом деле, для выполнения этого запроса можно использовать и функцию #ask, но получится чуть длиннее:
По результатам последней переписи в Берлине {{#ask: [[Berlin]] | ?population = }}Здесь используется знак "равно" и затем пробел, для того, чтобы не показывать название свойства Population в результате запроса. Если исполнить этот запрос без знака равно, то перед количеством жителей выведется строка Population:.
Общая схема встраиваемого запроса =[edit]
По своему смыслу семантический запрос должен отобрать множество страниц, удовлетворяющих определенным требованиям. При составлении запроса вы должны ответить на следующие вопросы:
- Какие вики-страницы вас интересуют, каким условиям они должны удовлетворять? (см. Выборка страниц)
- Какую информацию, связанную с этими страницами вы хотите получить? (см. Отображение информации)
- В каком виде и формате следует вывести эти данные? (см. Форматы вывода)
Прочитав соответствующие главы руководства вы с легкостью научитесь выбирать нужные страницы и выводить только ту информацию о них, которая вам необходима. А как насчет формата вывода? Эти форматы нужны в первую очередь для того, чтобы гармонично встраивать результаты семантических запросов в тексты вики-статей.
Основные параметры запроса[edit]
По умолчанию ответом на запрос является таблица или простой список. Для того, чтобы управлять форматом вывода результатов, необходимо использовать опцию format. Например, результаты запроса городов, находящихся в Германии, можно отформатировать как маркированный список. Для этого задайте в качестве формата format=ul:
{{#ask: [[Category:City]] [[located in::Germany]]
| ?Population
| format=ul
}}
Этот запрос выведет следующее:
- Berlin (PopulationThe number of inhabitants of some geographical place.: 3,520,061)
- Cologne (PopulationThe number of inhabitants of some geographical place.: 1,080,394)
- Frankfurt (PopulationThe number of inhabitants of some geographical place.: 679,664)
- Munich (PopulationThe number of inhabitants of some geographical place.: 1,353,186)
- Stuttgart (PopulationThe number of inhabitants of some geographical place.: 606,588)
- Würzburg (PopulationThe number of inhabitants of some geographical place.: 126,635)
Само собой, данные, представленные в этом списке, будут меняться о обновляться по мере того, как вики-редакторы будут добавлять и удалять немецкие города, или обновлять информацию об их населении.
В Semantic MediaWiki уже встроены многие другие форматы вывода результатов; более того, не представляет труда создавать собственные форматы вывода, не прибегая к программированию, а пользуясь лишь встроенным в MediaWiki языком шаблонов. За подробностями по тому, какие форматы бывают и как ими пользоваться, можете пройти на страницу Форматы вывода.
Кроме форматов вывода есть и другие параметры, которые могут использоваться практически в любых видах запросов Semantic MediaWiki. В таблице ниже приведены названия этих параметров, их кратные описания и допустимые значения.
| Параметр | Возможные значения | Описание |
|---|---|---|
| format | название формата вывода результатов | позволяет выбрать формат вывода. Некоторые форматы допускают дополнительные параметры, см. страницу руководства Форматы вывода |
| limit | неотрицательное число | максимальное количество страниц, которое требуется вывести (в случае с таблицами: максимальное количество строк) |
| offset | целое число | смещение: показывает, сколько результатов нужно пропустить |
| sort | имя семантического свойства или список свойств, разделенных запятыми | позволяет отсортировать результаты по значениям свойств. Для сортировки по главному столбцу вместо имени свойства нужно использовать пробел (см. Выборка страниц) |
| order | ascending/asc, descending/desc/reverse, random/rand или список этих значений разделенных запятыми в случае сортировки по нескольким столбцам |
задает то, как должны быть отсортированы результаты, здесь ascending использует по умолчанию и означает сортировку по возрастанию. Для того, чтобы определить способ сортировки по названию страницы, используйте параметр sort (см. Выборка страниц) |
| align | right, center, left | определяет то, как должны быть выравнены результаты. Опция имеет смысл для форматов table и broadtable (см. Форматы вывода) |
| headers | show, plain, hide | Определяет, нужно ли показывать заголовки: показывать со ссылкой, показывать только текст или вовсе скрывать.По умолчанию выставлено значение show - показывать со ссылкой. |
| mainlabel | текст | заголовок первой колонки (в ней показываются названия страниц, удовлетворяющих запросу). По умолчанию там ничего не пишется. Установите значение - если не хотите отображать названия страниц |
| index | целое число | определяет, какое из значений записи (record) должно быть показано. Имеет смысл только для свойств, имеющих тип Record |
| link | none, subject, all | определяет то, какие названия страниц в результатах запроса должны превратиться в ссылки на эти страницы. По умолчанию используется значение all, то есть все названия страниц превращаются в вики-ссылки.
Замечание: linking can also be controlled for individual printouts using the plain output format as described in Displaying information. |
| default | текст | если запрос не возвратит никакой информации, то вместо результата запроса будет выведено то, что вы запишите в этот параметр |
| intro | текст | текст, который следует напечатать перед результатами запроса (если они есть) |
| outro | текст | текст, который следует напечатать после результатов запроса (если они есть) |
| searchlabel | plain text | текст для ссылки "смотри далее" (по умолчанию задано значение «… further results») |
Вдобавок к вышеперечисленным параметрам, многие форматы вывода результатов имеют дополнительные параметры, применимые только для них. За подробностями о том, как использовать эти параметры, обратитесь к документации каждого из форматов вывода.
Ограничение количества выводимых результатов.[edit]
Запросы порой могут выводить очень большое количество результатов, а потому нужны средства для того, чтобы ограничивать его. В Semantic MediaWiki для этого используется параметр limit, например
{{#ask: [[Category:City]] [[located in::Germany]]
| limit=3
}}Строка limit=3 означает, что следует вывести максимум три найденных немецких города. Обратите внимание, что даже если вы имеете дело с запросом без явно указанного лимита, Semantic MediaWiki все равно не выводит абсолютно все найденные значения. В настройках SMW администратор вики может увеличить это ограничение по умолчанию, однако здесь следует быть осторожным: лимит задан из соображений производительности.
Приведенный выше запрос выведет следующий результат:
Berlin, Cologne, Frankfurt... further results
Обратите внимание на ссылку «further results». По умолчанию всякий раз когда вы используете опцию limit, выводится ссылка на полную версию результата запроса. Вы можете настраивать текст, который будет отображаться в этих случая с помощью параметра searchlabel. Если значение этого параметра пустое, то ссылка на полные результаты запроса отображаться не будет. Some output formats (see below) never display the search link, or display it only if a searchlabel was specified. Есть довольно интересно применение опции limit совместно с searchlabel: можно показывать только ссылку на результаты запроса (если они есть) и не вставлять этих результатов в текст. Для того, чтобы этого добиться надо установить значение параметра limit в "0" или "-1". Например запрос
{{#ask: [[Category:City]] | limit=0 | searchlabel=Кликните для того чтобы увидеть все города }}выведет следующее:
Кликните для того чтобы увидеть все города
Эта ссылка будет появляться только в том случае, если в категории City есть хоть один город. Иными словами, SMW все еще будет проверять наличие результатов, и если их нет, то читателю страницы ничего не выведется. Установите значение параметра в "-1" - и тогда ссылка на все результаты будет выводится вне зависимости от то, сколько результатов было выдано запросом. Это позволяет немного снизить нагрузку на сервер.
Текст по умолчанию и текст-вступление[edit]
Как вы могли заметить, Semantic MediaWiki не печатает на страницу никаких сообщений в случае, если результат семантического запроса пуст. Обычно это поведение допустимо и нормально, однако часто определённый текст должен появляться только в случае, если по запросу что-то нашлось. Например, у нас есть вики, посвященная конференциям, и ней должен присутствовать примерно следующий текст:
Предстоящие конференции: DEBS 2012, PODS2012 FOIS_2012, …
Разумеется, хочется, чтобы список конференций формировался автоматически с помощью запроса. Однако, в случае если запрос не даст никаких результатов, на вики-страницу будет выведено следующее:
Предстоящие конференции:
Это выглядит неряшливо и не всегда понятно посетителям вики. Значит, требуется параметр, с помощью которого можно было бы определять поведение Semantic MediaWiki в случаях, когда запросы не выдают результатов.
На самом деле, есть сразу два параметра, созданных для решения этой проблемы.
default: этот параметр определяет текст, который будет выведен, если запрос не дал результатов. В приведенном примере можно написать примерно следующее:
Предстоящие конференции: {{#ask: ... | default=нет событий}}
В таком случае, если запрос не даст результатов, на страницу будет выведено:
Предстоящие конференции: нет событий
intro: этот параметр определяет текст, который будет вставлен перед началом результатов запроса, если результаты были. В нашем примере мы можем написать:
{{#ask: ... | intro=Предстоящие конференции: }}
и тогда при нулевом результате запроса в текст вики-страницы не будет выведено ничего. Обратите внимание, как используется код знака "пробел": " " - придется использовать его, иначе MediaWiki съест пробел в конце строки. Если вам больше нравится код " ", можете использовать его.
Вы можете комбинировать эти два параметра в своих запросах. Обратите внимание, что значениями этих параметров может быть любая вики-разметка: ссылки, шаблоны, картинки.
Использование параметров по умолчанию для запросов - это хорошая привычки, ведь таким образом вы думаете о том, что вики и данные на ней могут измениться и эволюционировать, так что старые запросы не будут возвращать результатов. Без параметра по умолчанию в случае с пустыми результатами запрос не будет выводить на страницу ничего, а потому его легко будет потерять из виду и не исправить вовремя.
Обратите внимание, что если вы выводите одно свойство одной страницы с помощью ask или show, параметр default использовать не получится, поскольку при этом фактически не производится никакая выборка страниц.
Сортировка результатов[edit]
Если вы читаете это руководство по порядку, то вы уже сталкивались с сортировкой. В главе Help:Выборка страниц говорилось, что результаты запроса могут быть отсортированы по одному или нескольким свойствам. Пользуясь спецстраницей Special:Ask вы, наверное, заметили дополнительные поля, в которые можно добавить порядок сортировки. Во встраиваемых запросах свойства, по которым надо сортировать результаты задаются с помощью параметра sort, а порядок сортировки - с помощью параметра order.
Параметр order может принимать следующие значения: ascending (по возрастанию), descending или reverse (по убыванию) и random (в случайном порядке), а также сокращения asc и desc. Обратите внимание, что возможность сортировки в случайном порядке администратор вики может отключить (см. раздел Настройка). Например, следующим запросом можно вывести три самых крупных города Германии:
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?Population
| sort=Population
| order=descending
| limit=3
}}Как уже объяснялось в главе Выборка страниц сортировка накладывает определенные ограничения на данные. В рассмотренном примере в качестве результатов запроса будут учитываться только те немецкие города, на страницах которых указано число жителей.
Для сортировки можно указать несколько семантических свойств. В этом случае названия свойств для сортировки и её порядок указываются через запятую в свойствах sort и order. Взгляните на следующий пример:
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?State
| ?Population
| sort=State,Population
| order=ascending,descending
}}Этот запрос вернет немецкие города, для которых явно указана провинция и количество жителей. Значения в итоговой таблице будут отсортированы по названию провинции в алфавитном порядке (по возрастанию). Города, относящиеся к одной провинции будут отсортированы в порядке убывания населения в них.
Настройка заголовков таблиц и подписей[edit]
Когда вы создаёте запросы, которые возвращают не только название страницы, а что-то еще, то возвращаемые поля подписываются в соответствии с их названиями. В случае простого вывода результатов в таблицу в её заголовке отображаются названия свойств или надпись "Категория", если запрос выводит категории. При этом названия свойств и категорий превращаются в ссылки на их вики-странички. Порой требуется, чтобы в качестве полей заголовков таблиц выводилось что-то другое.
Этого легко достичь, используя знак = ("равно") после названия свойства. Значение после знака "равно" станет заголовком соответствующего столбца в таблице или подписью свойства, если вы используете другие форматы вывода. Проиллюстрируем это на примере:
{{#ask: [[Category:City]] [[Population::+]] [[Area::+]]
| ?Population=
| ?Area#km²=Площадь в км²
| ?Category=Участие в Категориях
| format=table
| default=ничего не найдено в Category:City
}}В результате этого запроса будет выведено следующее
| Площадь в км² | Участие в Категориях | ||
|---|---|---|---|
| Amsterdam | 783,364 | 219.00 km²84.56 sqmi <br /> | Europe Sample pages City |
| Berlin | 3,520,061 | 891.85 km²344.34 sqmi <br /> | Sample pages City |
| Cologne | 1,080,394 | 405.02 km²156.38 sqmi <br /> | City |
| Frankfurt | 679,664 | 248.31 km²95.87 sqmi <br /> | Sample pages City |
| Karlsruhe | 294,761 | 173.46 km²66.97 sqmi <br /> | Sample pages City |
| London | 7,825,200 | 1,706.80 km²659.00 sqmi <br /> | Sample pages City |
| Munich | 1,353,186 | 310.43 km²119.86 sqmi <br /> | Sample pages City |
| Paris | 2,234,105 | 105.40 km²40.69 sqmi <br /> | Sample pages City Popular City |
| Porto | 237.584 | 41.66 km²16.08 sqmi <br /> | Sample pages City |
| Rome | 2,761,477 | 1,285.31 km²496.26 sqmi <br /> | Sample pages City |
| San Diego | 1,307,402 | 963.60 km²372.05 sqmi <br /> | Sample pages City |
| Stuttgart | 606,588 | 207.35 km²80.06 sqmi <br /> | Sample pages City |
| Sydney | 4,575,532 | 2,058.00 km²794.59 sqmi <br /> | Sample pages City |
| Vienna | 1,897 1,888,776 | 414.87 km²160.18 sqmi <br /> 1,073,815,073.82 km²414,600,000.00 sqmi <br /> | Sample pages City Capital |
| Warsaw | 1,720,398 | 516.90 km²199.58 sqmi <br /> | Sample pages City |
| Würzburg | 126,635 | 87.63 km²33.83 sqmi <br /> | City |
Если вы не хотите, чтобы подпись выводилась, просто поставьте знак равенства после него. Однако, если вы используете табличный формат вывода, то вы обратите внимание, что заголовок таблицы всегда будет торчать на самом видном месте — даже если вы скроете все названия свойств и сделаете заголовок пустым.
Для скрытия заголовка у таблиц и скрытия всех подписей есть специальный параметр headers. Он может принимать три различных значения:
- show: отображать подписи (по умолчанию)
- plain: отображать подписи, но не превращать их в ссылки (доступно с версии SMW 1.4.3)
- hide: скрывать подписи и заголовки.
Параметр headers работает и для таблиц, и для других форматов вывода. Обратите внимание, что при значении hide все подписи будут скрыты - даже если вы явно задали их после знака равенства.
Изменение первой колонки результатов[edit]
Большинство запросов в первой колонке результатов отображают те страницы, которые подошли условиям запроса. Заголовок первого столбца по умолчанию остаётся пустым. Для того, чтобы изменить его, вы можете использовать параметр mainlabel.
Давайте изменим запрос про немецкие города так, чтобы первый столбец назывался "Название города":
{{#ask: [[Category:City]] [[Located in::Germany]]
| mainlabel=Название города
| ?Population=Количество жителей
| limit=3
}}Результат будет вот таким:
| Название города | Количество жителейThe number of inhabitants of some geographical place. |
|---|---|
| Berlin | 3,520,061 |
| Cologne | 1,080,394 |
| Frankfurt | 679,664 |
| ... further results | |
Параметр mainlabel можно использовать и для того, чтобы скрыть первый столбец с названиями страниц. Для этого нужно в качестве значения mainlabel указать - (знак "минус"). Если же вам нужно показывать названия найденных страниц не в первом столбце, а в каком-то другом, вы просто должны указать ? (вопросительный знак) в качестве параметра вывода. В нашем примере:
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?Population=Количество жителей
| ?=City
| mainlabel=-
| limit=3
}}Результатом будет вот такая таблица:
| Количество жителейThe number of inhabitants of some geographical place. | City |
|---|---|
| 3,520,061 | Berlin |
| 1,080,394 | Cologne |
| 679,664 | Frankfurt |
| ... further results | |
Обратите внимание, что если в приведенном запросе не указать mainlabel=-, то столбец с заголовками страниц будет продублирован.
Форматы вывода[edit]
С помощью параметра format вы можете управлять тем, в каком виде данные будут выводиться на вики-страницу. По умолчанию они выводятся в виде таблиц и списков, однако вы не пожалеете, если зайдете на страницу Форматы вывода!
Экспортирование результатов запросов[edit]
Некоторые форматы вывода в SMW позволяют экспортировать результаты запроса в файлы. К таковым относятся форматы rss, csv, dsv, json и rdf, а также форматы icalendar и vcard, предоставляемые расширением Semantic Result Formats. От прочих форматов вывода они отличаются в двух важных пунктах:
- Данные не выводятся непосредственно на вики-страницу. Вместо этого система генерирует ссылку на служебную страницу Ask, которая в свою очередь выдает файл, пригодный для скачивания.
- Используется жесткие фиксированные форматы для экспорта текстового, заданного в свободной форме вики-контента. Для всех форматов кроме CSV необходимо будет дополнительно объяснять, к каким вики-свойствам относится та или иная часть экспортированных данных.
Второй пункт очень важен, а потому при экспорте стоит позаботиться о том, чтобы установить соответствие между свойстами вики и полями в выбраном формате вывода. Возьмем, например, формат вывода vCard. Это формат данных, в котором можно представить много разной информации о человеке, этот формат часто используется для представления контактов в адресных книгах. В vcard есть жестко заданные названия для атрибутов человека, например «firstname», «lastname» и «homepage». Когда вы производите экспорт в этот формат, названия свойств или их псевдонимы после знака "равно" должны в точности совпадать с полями формата вывода. В примере с фамилией, именем и домашней страницей код запроса может быть таким:
{{#ask: [[Category:Person]]
| ?firstname
| ?lastname
| ?url = homepage
| format=vcard
}}На гипотетической вики уже есть свойства «firstname» и «lastname», поэтому эта часть экспортируется в vcard без проблем. А вот адрес домашней страницы хранится в значении свойства «url». Для того, чтобы подружить наше свойство с соответствующим полем в vCard мы изменяем подпись свойства url, добавляя «homepage» после знака равенства. Это особенно удобно для неанглоязычных вики: вы всегда можете использовать, например, русские подписи для свойств и не иметь никаких проблем с экспортом.
Свойства, содержащие определенные символы[edit]
Может случиться, что название свойства содержит символы <, ≤, >, ≥, =, ! и ~. SMW путает их с компараторами. Для того, чтобы так не случилось, свойства сделаны чувствительными к регистру. Вы можете, использовать пробел после двоеточия, как в этом примере: [[testproperty:: <br>]] найдет значение "<br>" для свойства testproperty.
Дополнительные советы[edit]
| The revision id is not annotated properly in the master page! The template {{Docinfo}} may not be embedded in: Inline queries |
