XunSearch（讯搜）的使用教程步骤 [ 新手入门 ]

XunSearch是一款很不错的中文全文检索工具使用xunsearch快速构建自己的PHP全文搜索引擎。

需要注意的是XunSearch只能在Linux和Unix下运行。官方发布了一个DEMO 直接下载 PHP-SDK 就可以开发测试。

安装服务端

1. 下载&解压安装包：http://www.xunsearch.com/site/download
2. 强烈推荐用 $HOME/xunsearch 或 /usr/local/xunsearch 作为安装目录 ( 以下简称 $prefix) 。无论您是首次安装 xunsearch 还是升级新版本，均只要直接执行我们提供的安装脚本，输入安装目录然后耐心等待即可。 cd xunsearch-full-1.3.3 ; sh setup.sh
3. 安装完毕后，您就可以通过自带的脚本 ($prefix/bin/xs-ctl.sh) 启动/关闭 xunsearch 服务端了。用法举例： $prefix/bin/xs-ctl.sh start # 默认启动，绑定本地的 8383/8384 端口 $prefix/bin/xs-ctl.sh -b inet start # 绑定全部 IP ，适合 SDK/服务端 不同服务器的情况 $prefix/bin/xs-ctl.sh stop # 停止服务器，若启动时指定了 -b inet 此处也必须指定
4. 没错，安装就是这么简单。特别提示，搜索的所有索引数据将被保存到 $prefix/data 目录，因此如果您希望数据目录另行安排，请采用软连接形式确保 $prefix/data 链至真实数据目录。此外，如果服务端启动时使用了 -b inet 参数，那么请借助 iptables 或其它防火墙工具进行保护，xunsearch 本身出于性能考虑不做其它验证处理。 PHP-SDK PHP-SDK 的代码默认包含在服务端安装目录中，即 $prefix/sdk/php 。目录结构如下： |– doc/ — HTML 格式的文档、API手册 |– app/ — 搜索项目 ini 文件的默认存储目录 |– lib/XS.php — 搜索库唯一文件，所有搜索相关功能均必须引入此文件 — util/ — 辅助工具目录

    |–  RequireCheck.php             —  检测您的 PHP  环境是否符合 xunsearch  运行条件
    |–  Quest.php                          —  搜索测试工具
    —  Indexer.php                        —  索引管理工具
   

1. 如果您的搜索应用和服务端在同一机器，则无需其它操作，只需在开发时直接引入$prefix/sdk/php/lib/XS.php 即可。

2. 如果您的搜索应用和服务端不在同一机器，则请复制 $prefix/sdk/php 目录到相应的搜索应用服务器，同时出于安全考虑，建议不要放到 WEB 可访问的目录。

3. 使用 SDK 中的 util 工具要求您的 php(cli) 位于可执行文件默认搜索路径中 ( 即用 which php 可以检测到)，如不在请做好软链接至 /usr/local/bin/php 。

检测运行环境 Xunsearch 要求 PHP 是 5.2.0 及以上版本，强烈推荐使用 5.3.x 系列的 PHP。请在安装完毕后直接执行$prefix/sdk/php/util/RequireCheck.php 看输出即可。如果您的终端编码不是 UTF-8 请在调用时加上 -c gbk 参数。 DEMO 服务器 某些情况下，部分用户未能自己部署安装服务端，而又想体验 xunsearch 。因此，我们从发布 1.3.3 版本起，提供了一台供用户测试的 DEMO 服务器。用户无需安装服务端，直接下载 PHP-SDK 就可以开发测试。特别提示，DEMO 服务器只用于 测试目的，并会不定期重置数据。 单独下载 PHP-SDK 如果您没有安装服务端，想直接体验 DEMO 服务器的，您只要从下面地址下载解压 SDK 压缩包即可。 http://www.xunsearch.com/download/xunsearch-sdk-latest.zip 解压后得到 xunsearch-sdk 目录，相应的搜索库文件为 xunsearch-sdk/php/lib/XS.php 服务器地址 索引服务器：demo.xunsearch.com 端口 9393 搜索服务器：demo.xunsearch.com 端口 9394

开发流程 • 为便于讲解说明，假定 PHP-SDK 代码目录为 $sdk 。 • 分析搜索需求，设计搜索应用必需的字段。 • 编写项目配置文件，项目配置 ini 文件存放在 $sdk/app 目录。 • 引入 $sdk/lib/XS.php 进行搜索功能和界面开发，借助 $sdk/util/*.php 工具进行测试或调试。 认识对象

• XS — 搜索项目总对象，所有相关操作均基于此对象及子方法。 • XSDocument — 搜索结果或索引文档，包括一组字段及值，相当于 SQL 表中的一条记录。 • XSIndex — 索引管理，通过 XS 对象的 index 属性取得。 • XSSearch — 搜索功能，通过 XS 对象的 search 属性取得。 • XSException — 异常类型，必须捕捉此异常以判断操作是否正确，例：

require ‘$sdk/lib/XS.php’; // 引入 xunsearch sdk try {

  $xs = new XS(‘demo’);    // demo  为项目名称，配置文件是：$sdk/app/demo.in i
   // ... 此外为其它 XSIndex/XSSearch  的相关功能代码

} catch (XSException $e) {

   echo $e . “n” . $e->getTraceAsString() . “n”; //  发生异常，输出描述

} 1 2 3 4 5 6 7 require ‘ $ sdk / lib / XS . php’ ; // 引入 xunsearch sdk try {

   $ xs = new XS (‘ demo’ ) ;      // demo  为项目名称，配置文件是：$sdk/app/demo.in i
   // ... 此外为其它 XSIndex/XSSearch  的相关功能代码

} catch ( XSException $ e ) {

   echo $ e . “ n” . $ e -> getTraceAsString ( ) . “ n” ; //  发生异常，输出描述

} 编写配置文件

推荐使用我们的在线工具编写：http://www.xunsearch.com/tools/iniconfig

demo 项目的配置如下：

创建索引

获取 XSIndex 对象

require ‘$sdk/lib/XS.php’; try {

   $xs = new XS(‘demo’); //  创建 XS  对象，项目名称为：demo
   $index = $xs->index;   //  获取索引对象
   // ... 在此编写过索引处理代码 ...

} catch (XSException $e) { } 1 2 3 4 5 6 require ‘ $ sdk / lib / XS . php’ ; try {

   $ xs = new XS (‘ demo’ ) ; //  创建 XS  对象，项目名称为：demo
   $ index = $ xs -> index ;    //  获取索引对象
   // ... 在此编写过索引处理代码 ...

} catch ( XSException $ e ) { } 增删改

$doc = new XSDocument(array( // 创建 XSDocument

   ‘pid’ => 123,  //  主键字段，必须指定
   ‘subject’ => ‘ 测试文档标题’, ‘message’ => ‘ 测试文档内容’,
   ’chrono’ => time()

)); $index->add($doc); // 添加文档，不检测便索引库内是否已有同一主键数据 $index->update($doc); // 更新文档，若有同主键数据则替换之 $index->del(‘123’); // 删除主键值为 234 的文档 $index->del(array(‘123’,‘456’)); // 删除主键值为 123 及 456 的文档 1 2 3 4 5 6 7 8 9 $ doc = new XSDocument ( array ( // 创建 XSDocument

   ‘ pid’ = > 123 ,    //  主键字段，必须指定
   ‘ subject’ = > ‘ 测试文档标题’ , ‘ message’ = > ‘ 测试文档内容’ ,
   ’ chrono’ = > time ( )

) ) ; $ index -> add ( $ doc ) ; // 添加文档，不检测便索引库内是否已有同一主键数据 $ index -> update ( $ doc ) ; // 更新文档，若有同主键数据则替换之 $ index -> del (‘ 123’ ) ; // 删除主键值为 234 的文档 $ index -> del ( array (‘ 123’ ,‘ 456’ ) ) ; // 删除主键值为 123 及 456 的文档 清空索引

当搜索字段文件变更或出现严重不同步时，建议清空索引。

$index->clean(); // 一执行立即生效 1 $ index -> clean ( ) ; // 一执行立即生效 索引同步

出于性能优化设计，上面所看到的索引操作都是异步操作。也就是说您通过 PHP 调用的 API 返回后，索引变动是先保存在服务端的队列中，由服务端根据负荷延迟一并写入索引库。这个时间差我们控制在合理范围内，通常是几秒钟时间。但如果您在批量更新后希望立即同步，可以这样：

$index->flushIndex(); 1 $ index -> flushIndex ( ) ; 使用搜索

获取 XSSearch 对象

require ‘$sdk/lib/XS.php’; try {

   $xs = new XS(‘demo’); //  创建 XS  对象，项目名称为：demo
   $index = $xs->search;   //  获取搜索对象
   // ... 在此编写过搜索处理代码 ...

} catch (XSException $e) { }
1 2 3 4 5 6 require ‘ $ sdk / lib / XS . php’ ; try {

   $ xs = new XS (‘ demo’ ) ; //  创建 XS  对象，项目名称为：demo
   $ index = $ xs -> search ;    //  获取搜索对象
   // ... 在此编写过搜索处理代码 ...

} catch ( XSException $ e ) { }
搜索语法 • 查询语句和流行的搜索引擎相似，通过空格把搜索词、句连接起来即可，字段检索使用 field:XXX 的格式。 • 允许使用 AND/OR/NOT/XOR 等显式地布尔关系组合，可以使用小括号 () 包围表达优先级。 • 支持使用双引号对较长搜索词进行精确匹配，要求字段设计时勾选“精确”项。 $search->search(‘ 杭州 西湖’); // 搜索同时包含这2个词的结果 $search->search(‘ 杭州 OR 西湖’); // 搜索包含其中一个词的结果 $search->search(‘subject:杭州 西湖’); // 包括西湖并且标题包含杭州的结果 获取结果 • 设置数量及偏移 $search->setLimit(5, 15); // 设置最多返回 5 条，并跳过前 15 条，即返回第 16-20 条结果 • 获取搜索结果

$docs = $search->setQuery(‘ 测试’)->search(); // 搜索 ‘ 测试’ foreach ($docs as $doc) {

   $subject = $search->highlight($doc->subject); //  高亮处理标题
   echo $doc->rank() . ‘. ‘ . $subject . ‘ [‘ . $doc->percent() . ‘%] - ‘ . date(‘Y-m-d’) . “n”;
   echo $doc->message . “nn”;

} 1 2 3 4 5 6 $ docs = $ search -> setQuery (‘ 测试’ ) -> search ( ) ; // 搜索 ‘ 测试’ foreach ( $ docs as $ doc ) {

   $ subject = $ search -> highlight ( $ doc -> subject ) ; //  高亮处理标题
   echo $ doc -> rank ( ) . ‘ . ‘ . $ subject . ‘ [‘ . $ doc -> percent ( ) . ‘ % ] - ‘ . date (‘ Y - m - d’ ) . “ n” ;
   echo $ doc -> message . “ nn” ;

}

• 获取搜索结果数量 ( 估算值) $count = $search->getLastCount(); // 获取最后一次 $search->search() 的匹配数量 $count = $search->count(‘测试’); // 直接检索包含 ‘ 测试’ 的数量 搜索日志 关于日志 系统内部会自动记录并分析搜索关键词日志，通过日志衍生出相关的扩展功能。日志同样是异步更新的并且延迟较大，如需要强制刷新请调用以下指令或索引 API 。 php $sdk/util/Indexer.php -p demo –flush-log # 通过辅助工具刷新日志 $index->flushLogging(); // 通过索引 API 更新 热门搜索 通过 XSSearch::getHotQuery 方法获取热门搜索词，返回的数组以关键词为键名，搜索指数为值。 $words = $search->getHotQuery(); // 获取前 6 个总热门搜索词 $words = $search->getHotQuery(6, ‘lastnum’); // 获取前 10 个上周热门词 相关搜索 通过 XSSearch::getRelatedQuery 方法获取热门搜索词，返回相关搜索词组成的数组。 $words = $search->getRelatedQuery(); // 获取前 6 个和最近一次 setQuery() 相关的搜索词 $words = $search->getRelatedQuery(‘测试’, 10); // 获取 10 个和 ‘ 测试’ 相关的搜索词 搜索纠错 由于输入过快或拼音输入中文很容易出现错误，XSSearch::getCorrectedQuery 方法返回纠正后的关键词组成的数组。

$docs = $search->setQuery(‘ 侧试’)->search(); // 正常进行搜索误打的 ‘ 侧试’ $corrected = $search->getCorrectedQuery(); // 尝试修正 if (count($corrected) > 0) { // 有修正词则列出

   echo “ 您是不是要找：n”;
   foreach ($corredted as $word) echo $word . “n”;

} 1 2 3 4 5 6 $ docs = $ search -> setQuery (‘ 侧试’ ) -> search ( ) ; // 正常进行搜索误打的 ‘ 侧试’ $ corrected = $ search -> getCorrectedQuery ( ) ; // 尝试修正 if ( count ( $ corrected ) > 0 ) { // 有修正词则列出

   echo “ 您是不是要找： n” ;
   foreach ( $ corredted as $ word ) echo $ word . “ n” ;

} 搜索建议 类似常见搜索引擎那样，当用户在输入框键入少量字、拼音、声母时进行智能补全，可以节省用户的输入时间。 $words = $search->getExpandedQuery(‘c’); // 返回 array(‘ 测试’) $words = $search->getExpandedQuery(‘ 测’); // 返回 array(‘ 测试’) $words = $search->getExpandedQuery(‘cs’); // 返回 array(‘ 测试’)

源自：http://www.oschina.net/p/xunsearch