dp2API之Search

Search() – 直接用XML检索式进行检索

        LibraryServerResult Search(
            string strQueryXml,
            string strResultSetName,
            string strOutputStyle);

用途：直接用dp2Kernel所定义的XML检索式进行检索。

参数表：

类型	参数名	说明
string	strQueryXml	检索式。采用dp2Kernel所定义的XML检索式格式
string	strResultSetName	结果集名
string	strOutputStyle	输出方式

返回值：

成员	返回值	说明
LibraryServerResult.Value		
	-1	错误
	0	没有命中
	>=1	命中。返回值为命中的记录条数
LibraryServerResult.ErrorInfo		出错信息

权限

权限： ~~需要search权限。读者身份登录不允许使用本API。~~ 针对检索式中包含的不同类型的书目库，需要不同的权限。详述如下：
书目库 - 需要 searchbiblio 权限;
规范库 - 需要 searchauthority 权限;
读者库 - 需要 searchreader 权限;
实体库 - 需要 searchitem 权限;
订购库 - 需要 searchorder 权限;
期库 - 需要 searchissue 权限;
评注库 - 需要 searchcomment 权限;
违约金库 - 需要 amerce 或 settlement 权限;
预约到书库 - 需要 borrow,return,getreaderinfo,reservation 之一权限;

此外，读者库如果不被当前账户所管辖，则不允许进行检索。

strQueryXml参数值是XML格式的检索式字符串。虽然是采用了dp2Kernel定义的检索式XML格式，但里面还允许指定dp2Library层次的虚拟库进行检索，在XML检索式发送到dp2Kernel以前，dp2Library会进行一定的处理，把虚拟库信息替换为dp2Kernel层次的真实数据库信息。

strQueryXml

strQuery参数指定了检索式。这是一种XML格式的检索语言，详细情况参见https://jihulab.com/DigitalPlatform/dp2doc/-/issues/63#note_2031814

strResultSetName

strResultSetName参数指定了结果集名。如果此参数值为空，表示使用”default”作为结果集名。本API完成操作时，会将检索结果放入结果集。前端再用相关API从结果集中获取命中记录。

strOutputStyle

strOutputStyle参数指定了输出方式。其值为空/ keyid/ keycount 之一。空表示在检索结果中输出命中的记录路径；”keyid”表示在检索结果中输出命中的检索点字符串和对应的记录路径；”keycount”表示在检索结果中输出命中的检索点字符串和对应的命中次数。

检索语言

数据库内核使用了一种专门的XML格式的检索语言来描述检索请求。它可以表达复杂的逻辑检索请求。

在dp2rms前端的检索窗中或者在practice测试工具，可以直接输入这种XML格式的检索式进行检索。

文档主体结构

最重要的元素是<item>元素，它定义了一个最基本的检索单元。

<item>元素之间可以用<operator>元素连接起来，表示逻辑运算。

为了将某个范围内的能够形成检索结果的一个局部组合成一个单元以便参加更大规模的逻辑运算，可以使用<group>元素把<item>和<operator>元素包装起来。

<group>元素和<item>元素之间，以及<group>元素和另一个或多个<group>元素之间，可以用<operator>元素连接起来。

<group>元素有时候像普通算式中的括号，能控制逻辑运算的优先级次和执行顺序。

例1：

<item>…</item>

省略号表示印刷中被略去的细节结构。以上代码为示范用，尚不能实际运行。
这是一个最简单的结构，表示只有一个基本单元的检索。

例2：

<group>
        <item>…</item>
        <operator value=”AND” />
        <item>…</item>
</group>

这表示两个基本单元之间进行AND(与)运算的逻辑检索。因为XML文档必须有一个唯一的根元素，所以这里使用了<group>元素来充当根元素，它同时也是<item>元素和<operator>元素的容器。

例3：

<group>
    <group>
        <item>…</item>
        <operator value=”AND” />
        <item>…</item>
    </group>
    <operator value=”OR” />
    <group>
        <item>…</item>
        <operator value=”AND” />
        <item>…</item>
    </group>
</group>

这表示两个<group>结构之间进行OR(或)运算的逻辑检索。涉及的每个<group>结构本身也是一个逻辑运算构造。一共有四个基本单元参与逻辑运算。

`<item>` 基本检索单元

<item>元素定义了一个基本的检索单元。

<item>元素下面通过<word>、<match>、<relation>、<dataType>、<order>、<originOrder>、<maxCount>元素表达了检索参数。

例4：

<target list="中文图书:题名">
    <item>
        <word>中国</word>
        <match>left</match>
        <relation>=</relation>
        <dataType>string</dataType>
    </item>
    <lang>zh</lang>
</target>

<item>元素检索所针对的目标，是由<target>元素定义的。<target>元素在整个XML结构中的位置比较自由，它可以包围一个或者多个<item>元素。从<item>元素向父元素的方向寻找，第一个遇到的<target>元素就是对这个<item>元素起作用的元素。这样(允许自由位置的)设计的目的是便于在有多个<item>元素的情况下，允许通过共享节省<target>元素的使用频率。

`<target>` -- 检索目标

<target>元素定义了检索目标。<target>元素本身可以充当容器元素，它里面可以包含 <item>、<operator>、<group>等元素。

<target>元素只有一个属性list。list属性定义了检索目标的列表，格式类似：
中文图书:题名,责任者;中文采购:责任者
规则就是用分号连接属于不同数据库的段落；每个段落内，冒号前是数据库名，冒号后是一个或者多个检索途径名。检索途径之间用逗号连接。

多个<item>元素以逻辑运算符OR连接起来的逻辑运算结构，如果它们之间检索词和匹配方式等参数都相同，那可以尽量将它们合并为一个<item>元素，将这些原本分离的<item>元素的检索目标合并为一个检索目标字符串即可。

`<word>` -- 检索词

<word>元素内的正文部分定义了检索词。

`<match>` -- 匹配方式

<match>元素内的正文部分定义了匹配方式。一种有以下几种可能： left/ middle/ right/ exact 分别代表“前方一致”“中间一致”“后方一致”“精确一致”。

`<relation>` -- 关系

<relation>元素内的正文部分定义了检索时和检索词比较所要求的关系。可用值的解释如下：

值	替代形式	说明
>	G	大于
>=	GE	大于等于
<	L	小于
<=	LE	小于等于
=	E	等于
!=	NE	不等于
range		范围

`<dataType>` -- 数据类型

<dataType>元素内的正文部分定义了检索词在检索时的数据类型。为number/ string 之一，分别代表“数值”“字符串”。

数据类型会影响到检索的匹配方式和效果。例如，对于时间字符串的检索点，如果采用number类型进行检索，就能准确比较时间值；而如果采用string类型进行检索，则只能把待匹配的字符串当作普通字符串进行比较，那么有些时候可能会无法正确命中。

`<order>` -- 输出顺序

<order>元素内的正文部分定义了检索结果输出到结果集时的排序方式。为ASC/ DESC 之一，分别代表“升序”“降序”。

如果没有使用<order>元素，则表示在输出检索结果的时候不专门进行排序。

`<originOrder>` -- 原始顺序

<originOrder>元素内的正文部分定义了检索结果输出到结果集时的排序方式。为ASC/ DESC 之一，分别代表“升序”“降序”。

如果没有使用<originOrder>元素，则表示在输出检索结果的时候不专门进行排序。

`<maxCount>` -- 最大命中条数

<maxCount>元素内的正文部分定义了检索命中的最大条数。如果为-1，表示不限制最大命中条数。本元素缺省时，表示不限制最大命中条数。

`<operator>` -- 逻辑运算符

<operator>元素通过其属性value定义了逻辑运算符。

value属性值为OR/ AND/ SUB之一，分别代表或、与、减运算。

减运算的意思是从前一个集合中除去和后一个集合的交叉部分后剩下的部分是运算结果。

`<lang>` -- 语言

<lang>元素内的正文部分定义了语言代码。

本元素缺省时，表示语言代码为”zh”。

这个元素可以出现在检索式XML结构的任何位置。

`<option>` -- 选项

<option>元素定义了选项信息。这个元素可以出现在检索式XML结构的任何位置。

<option>元素的warning属性定义了警告级别数字。缺省为1。

警告级别数字的含义为：0 -- 严厉，遇到检索式信息有矛盾之处，直接出错返回；1 -- 宽容，当检索式信息出现矛盾时，系统自动做出变通修改，尽量继续进行检索。

记录ID的范围检索

检索词中可以使用’-’表示一个范围；<relation>元素指定range关系；<dataType>元素指定为number数据类型，如下：

<target list="中文图书:__id">
    <item>
        <word>1000-2000</word>
        <match>exact</match>
        <relation>range</relation>
        <dataType>number</dataType>
    </item>
</target>

这样就可以针对数据库的__id途径进行范围检索了。__id表示记录ID检索途径，无需在数据库的keys文件中定义，这个检索途径是数据库自含的。

还可以进行大于、小于等数量关系的检索：

<target list="中文图书:__id">
    <item>
        <word>200</word>
        <match>exact</match>
        <relation>&gt;=</relation>
        <dataType>number</dataType>
    </item>
</target>

上例中的<relation>元素中指定了>=这一数量比较关系，将检索出记录ID号大于或等于200的全部记录。

时间检索

如果检索途径不存在会怎么样。返回“未命中”，而不是报错。这一点在调试中要引起注意。这是为了兼容性的目的。可以通过前端获得数据库的检索途径名，来预先筛选发现。 warninglevel的具体例子

为什么检索式的Item元素没有目标数据库属性？

因为当逻辑检索时，item数量会比较多，如果每个item都带一个target属性，这些target都是同样的目标库，则会带来很大的重复和冗余。所以把target设为一个元素包在item外层。target元素充当容器，它里面可以包含item、operator、group等元素，组合起来是括号一层一层包括的思路，整个可以理解为一个长的运算式。

多个目标库时，帐号对某些库有检索权限，对某些库无检索权限，那么是部分返回，还是只要发现某个库无权限，则整体拒绝检索？

思考过程：如果只有OR（或）运算，每个检索结果是直接累加的结果，这种情况比较简单，部分返回也可以。但如果有AND（与）运算，两个结果是一个交叉运算取共同集合的部分，这种情况下如果其中一个库无权限，则没法进行运算。所以检索逻辑采用：只要检索式出现一个库无权限，则整体拒绝检索。

冒烟测试要点

关于search检索各种资料需要的权限，测试了6点，均符合预期。检索式很健壮，没有发现问题。

用例1：一个很大的检索式，包括了8个库，登录帐户无任何权限，检查返回的提示，对各库都提示了需要的权限，符合预期，不过违约金与预期的权限看上去和大家不一致。

用例2：一个很大的检索式，包括了8个库，登录帐户对部分库有权限，部分库无权限，检查返回结果提示需要的权限，只提示了无权限的数据库，并且拒绝检索，符合预期。

用例3：一个嵌套了多层的检索式，并且帐户对部分库有权限，部分库无权限，返回提示正确，符合预期。

Value:-1
ErrorCode:AccessDenied
ErrorInfo:检索被拒绝。当前账户对下列数据库不具备检索权限:
读者:不具备权限 searchreader
中文图书订购:不具备权限 searchorder
读者:不具备权限 searchreader              （嵌套第2层）
中文图书订购:不具备权限 searchorder  （嵌套第3层）
中文图书评注:不具备权限 searchcomment
读者:不具备权限 searchreader

用例4：测试OR运算
1）同一个目标库，两个item，OR运算，结果符合预期。
2）不同目标库，多个Item,OR运算，符合运行。

用例5：测试AND运算
1）同一个目标库，多个item，AND，有交集的情况，结果返回交叉数量，符合预期。
2）同一个目标库，多个item，AND，无交集的情况，结果返回0，符合预期。
3）不同目标库，两个item，AND,无交集，返回0，符合预期。

用例6：复杂的逻辑式，不同库，有AND 又有OR，有嵌套，变化了各种式子，结果均符合人工计算的结果。

各资源检索式