| 目录 | |
|---|---|
Semantic MediaWiki之中含有一种用于语义搜索的，简单的查询语言， 用户因此可以直接请求当前维基站点当中的特定信息。不愿学习其查询语法的读者已经受益于这种功能特性：嵌入式查询（inline queries，内嵌式查询，内联查询）可动态地将查询结果包含到页面当中。因此，为数众多的读者可以享用少数几位编者所创建的查询。
嵌入式查询类似于其他的语义搜索功能，为了保证足够的性能，亦可将其限制在某一网站之上。嵌入式查询可利用MediaWiki现有的高速缓存机制，在不对性能产生任何影响的情况下，可满足对于带有此类动态内容的页面的大多数请求。
解析器函数#ask[edit]
编写嵌入式查询的基本方法就是利用解析器函数#ask。如以下例子所示，查询字符串（有关语法请参见选择页面）和任何的打印输出语句都是以参数的形式而直接给出的：
{{#ask: [[Category:City]] [[located in::Germany]]
| ?population
| ?area#km² = Size in km²
}}
其中，我们查询的是所有位于德国国内的城市，并且还使用了两个附加的打印输出语句（一个简单，另一个则额外带有一些设置）。该查询将在页面上显示如下结果：
| 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:之后的第一个参数。 就像其他的解析器函数那样，所有其他的参数之间均采用竖线或者说通道符|加以分隔。 上述嵌入式查询具体的格式编排并不是必需的，但最好利用换行符（line breaks）来提高其对于其他编者的易读性。 与所有的模板一样，实际当中最令人接受的做法就是，每个参数占一行，并以|开头。
请注意：页面解析过程将会忽略解析器函数#ask:的所有变量，因此上述例子并不会给本页面新增一个类别或一条«located in»属性标注。还要注意的几点就是：
- 通道符'|'用于将查询条件与所要显示的属性分隔开来。
- 用于显示的那些查询条件整体上只是解析器函数#ask的单独一个变量，因此这些查询条件之间并没有通道符'|'。
- 在解析器函数#ask内部，可以使用空格和换行符，SMW在这方面相当灵活。
- 当您请求显示额外的属性时，查询结果显示格式会发生变化。SMW会为查询结果挑选一种合适的默认格式，但您也可以详细控制查询结果的外观。
因此，了解了查询字符串和打印输出语句 基本知识，就足以编写出许许多多种类的查询。 但是，在许多情况下，查询结果的标准表格输出形式可能并不是最佳的选择，或者还需要进一步的设置（比如，应当加以显示的结果的最大数量）。 正是出于这个目的，嵌入式查询备有大量其他可能的参数，可用于详细控制其外观。 因此，解析器函数#ask:的一般语法如下所示：
{{#ask: argument 1 | argument 2 | … }}
本页面的大多数内容解释的是那些可能在嵌入式查询当中使用的各种变量。
解析器函数#show[edit]
查询的一种常见的用途是为单独一个页面显示仅仅单独一个属性取值。例如，我们可能要在某一文章当中插入柏林的人口数量，并且采用的是查询而不是手工复制的方法来实现。SMW备有一个专门的快捷方式来简化此类查询。比如，可以写成：
{{#show: Berlin | ?population}}
来显示柏林的人口数量（该查询实际的运行结果为：«3,520,061»）。 此函数的工作方式类似于嵌入式查询，如果需要的话，嵌入式查询所有可用的参数均可用于#show:。上述函数亦可写作如下像#ask查询的形式：
{{#ask: [[Berlin]] | ?population = }}
其中，等号赋予的是用于显示该属性的另一个标签，而该标签实际为空白（其作用是因此默认的标签«Population:»）；没有这个的话，结果将会在实际数值前面显示«Population:»。
嵌入式查询的标准参数[edit]
一般来说，嵌入式查询是一种用于找出许多满足特定要求的页面的请求。这种查询必须回答下列三个问题：
在相应的手册页面当中已经对前两点加以了解释。要顺利地在页面之中包含查询结果，第三点相当重要，不过其在很大程度上独立于前两点。在未加进一步设置的情况下，查询常常产生的是与上面类似的表格或者是简单的列表（如果没有使用附加的打印输出语句的话）。关于另一种可能的格式的例子就是带项目符号的列表（bulleted lists），可采用参数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)
SMW为嵌入式查询实现了种类多样的输出格式，而且您还可以采用MediaWiki模板对结果显示进一步加以控制。对于查询结果外观的选择来说，最重要的参数之一就是format。参见结果格式。
下表旨在对可用于基本上所有查询的常见参数进行概述：
| 参数 | 中文名称 | 可能取值 | 说明 |
|---|---|---|---|
| format | 格式 | 一个格式名称 | 所选择的输出格式；某些格式还允许采用更多的参数（参见结果格式） |
| limit | 限值 | 非负整数 | 所选页面的最大数量（对于表格则指的是行数） |
| offset | 偏移 | 整数 | 从何处开始 |
| sort | 排序属性 | 属性名称，或者是由英文逗号分隔属性名称列表 | 用于对查询结果进行排序的属性的名称，以空白为取值时表示排序依据为主结果列（参见选择页面） |
| order | 排序方式 | ascending/asc（升序）、descending/desc/reverse（降序）、random/rand（随机） 如果排序依据不止一个属性，则为这些参数值的列表 |
用来规定如何对结果进行排序；在没有使用参数"sort"时，默认为ascending（升序），将设置的是主结果列的排列顺序（参见选择页面） |
| align | 对齐方式 | right（右对齐）、center（居中）、left（左对齐） | 规定结果的对齐方式，仅适用于结果格式table和broadtable（参见结果格式） |
| headers | 表头 | show（显示）、plain（普通）、hide（隐藏） | 显示表头（带链接），显示表头（仅文字）或隐藏表头。默认为show |
| mainlabel | 主标签 | 普通文本 | 首列标题（页面标题所在列）；默认无标题；设置为-即可禁止打印输出页面标题 |
| index | 索引 | 正整数 | 规定究竟应当显示记录当中的哪个取值，仅适用于记录型属性。 |
| link | 链接 | none（无）、subject（主题）、all（全部） | 规定究竟结果当中的哪些文章名称要加上超级链接，通常默认为all（全部） 注意：如显示信息所述，亦可利用plain output format（普通输出格式）来控制具体打印输出的链接操作。 |
| default | 默认文本 | 普通文本 | 无论任何原因，如果查询未返回任何结果，则打印输出此文本 |
| intro | 起始文本 | 普通文本 | 假如至少存在一些结果时，预置在输出之前的开头文字 |
| outro | 收尾文本 | 普通文本 | 假如至少存在一些结果时，追加在输出之后的结尾文字 |
| searchlabel | 搜索标签 | 普通文本 | 用于继续搜索结果的文字（默认值为«… further results»，即“进一步的结果”或“更多结果”） |
除上述参数外，一些格式还备有自己的参数，用于控制相应格式的特殊方面。各个格式的文档里面描述有这些专门的设置。
结果数量限制以及指向更多结果的链接[edit]
您可以通过设置参数limit，来限制所要返回的结果的最大数量。例如，下列查询：
{{#ask: [[Category:City]] [[located in::Germany]]
| limit=3
}}
最多显示德国国内的3个城市。即使是您没有为limit指定取值，SMW也总会对查询所返回的结果加以某种限制。根据网站设置的不同，有可能通过指定较大的limit取值，从而增加所显示结果的数量。然而，基于性能方面的考虑，通常不能超过维基站点管理员所设定的最大限值。
上述查询的运行结果为：Berlin, Cologne, Frankfurt... further results
这表明，无论何时，只要查询因为某一限值而不能全部显示所有结果，通常都会显示一个指向«further results»（更多结果）的链接。通过设置搜索标签参数searchlabel，可修改该链接的文字。如果searchlabel取值为空，则不会显示指向更多结果的链接。一些输出格式（参见下文）绝不会显示这种搜索链接，或者是只有当指定了searchlabel的时候，才会显示。
limit和searchlabel的一个有趣的应用就是，仅仅显示一条指向搜索结果的链接，而并不采用嵌入方式显示任何结果。将限值设为«0»或«-1»，即可实现这种效果。例如，如下查询：
{{#ask: [[Category:City]] | limit=0 | searchlabel=单击此处浏览城市列表 }}
实际显示的是：单击此处浏览城市列表。只有当有任何结果的时候，才会显示该链接。换句话说，SMW仍会处理查询，以检查是否存在任何结果。 如果不需要这样，或者如果在任何情况下都要显示一条链接，则可以使用限值«-1»。 这时，即使是不存在任何结果，SMW也会打印输出一条指向更多结果的链接。 同时，这也节省了服务器的一些计算时间。
起始文本与默认文本[edit]
如果没有任何文章满足一个查询的那些条件，什么都不显示。 有时，这是一种有用的行为，而往往的情况就是，要根据查询是否有结果返回，应当显示或不显示特定的文字。 例如，可能希望查询采取下列形式来显示输出：
即将举行的会议：DEBS 2012, PODS2012, …
其中，会议列表是采用合适的查询而生成的。如果该查询（无论出于何种原因）没有返回任何结果，则该结果页面可能显示如下：
即将举行的会议：
这并非所期望的输出形式。有两个参数可以防止这种情况的发生。
- default（默认文本）：可将该参数设置成当没有获得任何结果时所应当返回的默认文本。对于上述示例，也许可以将查询写成如下样子：
即将举行的会议：{{#ask: ... | default=未找到任何结果}}
- 这样，假如没有获得任何结果，相应的文章就会显示：
即将举行的会议：未找到任何结果
- intro（起始文本）：该参数规定的是，只有当存在一个或更多结果时，应当在查询输出之前预置的文字。对于上述示例，可以将查询写成如下样子：
{{#ask: ... | intro=即将举行的会议： }}
- 这样，假如没有获得任何结果，什么都不会显示。请注意：我们采用" "来编码最后的空格（" "也同样有效），因为解析器函数参数取值首尾的普通空格会被裁减掉。
在找到结果的情况下，上述两种办法都会显示预定的输出。 如果需要的话，亦可将两个参数组合起来使用。 参数当中亦可包括链接或模板之类的MediaWiki置标（markup），只要不会让MediaWiki在识别#ask函数时混淆即可。
还要注意的是，如果在一个查询之中所选择的页面集合为空，将不会产生任何的标题行或空行，甚至也没有任何的空格（空白）。将不合适的查询«隐藏»起来也可能有用。 不过，建议不要因为不产生任何输出，因而不会有任何害处，从而在每个页面之中插入大量的查询。 实际上，对查询的应答确实需要很多的计算资源，因此切勿盲目这么做。
一般来说，对查询使用默认文本也是个好习惯，因为有可能发生的情况就是，在将来某个时候，一个查询将不再返回任何结果，比如因为当前维基站点对其数据的组织方式发生了改变。曾经正常有效的此类查询可能会被遗忘，从而没人注意到，页面上的这种查询费劲不小却什么也不显示。
请注意，当您希望为单独一个页面仅仅显示单独一个属性取值时（参见#show），默认文本参数default并不起作用，因为实际上您并没有查询页面。
结果排序[edit]
在[[Help:页面选择]当中我们解释过，可依据一个或多个属性对查询结果进行排序。 正如那里所讲的，Special:Ask页面备有额外的输入栏，用于规定排序属性和排序方式。 在嵌入式查询中，排序属性石采用参数sort来规定的，而排序方式则可采用参数order来设置。 参数order的取值应当为«ascending»或«descending»（降序亦可写作«reverse»），或者是其简写形式之一，即«asc»或«desc»。 亦可将其取值设为«random»（或简写为«rand»），从而采取实质上为随机的方式来对结果加以排序（网站管理员可禁用该功能，参见配置）。 一个例子就是如下对德国国内三个最大城市的查询：
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?Population
| sort=Population
| order=descending
| limit=3
}}
如[[Help:页面选择]当中所述，排序条件可能对查询结果集合施加若干的限制。 在上述示例当中，只有那些具有人口数量取值的德国城市才在考虑之列。 如果用于排序的属性不止一个，则可将参数sort和order分别设置为采用逗号分隔的属性名称列表和排序方式列表。 如下是一个相应的例子：
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?State
| ?Population
| sort=State,Population
| order=ascending,descending
}}
该查询返回的是所有说明了人口数量和所在州的德国城市。 这些结果将按照它们所在州的名称进行排序（按字母顺序）。 位于同一州的城市则按其人口数量来排序，人口最多者优先（«descending»）。
当应当使用不止一个排序条件时，亦可明确规定要用于排序的主结果列。 这只需在空语句之前预置或其后追加一个英文逗号即可实现。例如：
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?State
| ?Population
| sort=State,
| order=ascending,descending
}}
该查询返回的是所有说明了某个州的德国城市 这些结果将按照它们所在州的名称进行排序（按字母顺序）。 位于同一州的城市则按城市名称来排序（«descending»）。
配置标签/表头[edit]
那些不仅仅返回所选文章的查询（如上述示例之中的人口数量），将会显示用于描述各个输出字段的标签。 默认情况下，这种标签仅仅显示所请求属性的名称，或者当显示若干的类别时，显示文本«Category»。 属性标签通常显示为指向Property:命名空间当中相应页面的链接。
采用表格格式（table format）时，标签显示为列标题。 采用其他格式时，标签则可能会就显示在相应的输出字段之前。 如显示信息所述，可在打印输出语句之后采用等号，对这些标签的文字加以控制。例如：
{{#ask: [[Category:City]] [[Population::+]] [[Area::+]]
| ?Population= 人口数量
| ?Area#km²=面积（km²）
| ?Category=所属类别
| format=table
| default=在Category:City之中没有找到任何结果
}}
该查询将产生的是：
| 人口数量The number of inhabitants of some geographical place. | 面积（km²） | 所属类别 | |
|---|---|---|---|
| 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（隐藏）：隐藏所有的标签和表头
这项设置对于表格以及其他输出形式都有效。对于后者，参数取值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亦可用来彻底隐藏首列。 将其取值设置为«-»（英文减号或者说连字符）即可。 要在别的位置插入主要结果列表，可采用打印输出语句«?»，即英文问号，且不添加任何东西。 例如，更改上述示例，以便在人口数量之后显示城市名称：
{{#ask: [[Category:City]] [[Located in::Germany]]
| ?Population=居民人数
| ?=城市
| mainlabel=-
| limit=3
}}
该查询将产生如下表格：
| 居民人数The number of inhabitants of some geographical place. | 城市 |
|---|---|
| 3,520,061 | Berlin |
| 1,080,394 | Cologne |
| 679,664 | Frankfurt |
| ... further results | |
结果格式[edit]
参数format决定的是如何在文章之中显示查询结果。详情请参见结果格式。
导出查询结果[edit]
一些SMW的结果格式（csv, dsv, json, rdf）允许从维基站点之中导出数据。 而且，语义结果格式扩展所定义的其他格式（）也允许导出数据。 这些格式有两个方面区别于其他格式：
- 它们不是在页面上显示数据，而是仅仅产生一条指向Special:Ask页面的链接，从而采取可下载的形式来输出数据。（尽管这种链接采用不同的默认文本，如«RSS»，但其却类似于通常的«further results»（更多结果）链接；可利用搜索标签参数searchlabel来更改其链接文字。）
- 它们采用固定的标准格式来导出（非固定且形式自由的）维基站点内容。因此，对于CSV和DSV以外的格式，必须对究竟哪些维基站点属性属于相应数据导出格式的哪个组成部分加以解释。
其中，第二条使得我们有必要将打印输出语句（属性）与相应导出格式之中可用的数据字段关联起来。例如，数据格式vCard可编码许多种类关于某个人的联系方式数据，但其不能表示任意的属性。要规定哪个维基站点数据属于哪个可用的数据字段，可采用属性打印输出标签。例如，vCard支持的数据字段当中有«firstname»（名字）、«lastname»（姓氏）以及«homepage»（主页）。因此，可以编写如下查询：
{{#ask: [[Category:Person]]
| ?firstname
| ?lastname
| ?url = homepage
| format=vcard
}}
这里，该维基站点拥有分别称为«firstname»（名字）和«lastname»（姓氏）的属性，而人员的主页则存储在一个称为«url»的属性当中。 其中，赋予了后者（即«url»）以标签«homepage»，从而vCard可以识别出该属性的特殊含义。采用这种方法，维基站点可以使用任意的属性名称（采用任何语言），而又可以采用标准格式导出数据。关于上述格式所支持的数据字段，详情请参见相应格式的页面。
相关提示[edit]
