util.indexer.html 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  3. <head>
  4. <meta http-equiv="Content-Type" content="text/html; charset=gbk" />
  5. <meta name="language" content="zh-cn" />
  6. <link rel="stylesheet" type="text/css" href="../api/css/style.css" />
  7. <link rel="stylesheet" type="text/css" href="../api/css/guide.css" />
  8. <link rel="stylesheet" type="text/css" href="../api/css/highlight.css" />
  9. <title>索引管理器</title>
  10. </head>
  11. <body>
  12. <div id="apiPage">
  13. <div id="apiHeader">
  14. <a href="http://www.xunsearch.com" target="_blank">Xunsearch PHP-SDK</a> v1.3.2 权威指南
  15. </div><!-- end of header -->
  16. <div id="content" class="markdown">
  17. <div class="toc"><ol><li><a href="#ch0">主要参数和选项</a></li><li><a href="#ch1">经典用法示例</a></li><li><a href="#ch2">导入 SQL 数据库</a></li><li><a href="#ch3">导入 CSV 数据</a></li><li><a href="#ch4">导入 JSON 数据</a></li><li><a href="#ch5">清空、重建索引</a></li><li><a href="#ch6">自定义数据过滤器</a></li><li><a href="#ch7">自定义数据源</a></li><li><a href="#ch8">同义词管理</a></li></ol></div><h1 id="-">索引管理器</h1>
  18. <p><code>Indexer</code> 作为索引管理工具,提供了批量索引导入、清空索引、刷新索引队列、日志等各项功能,
  19. 导入索引支持数据源包括:<code>csv, json, mysql, sqlite</code> 等,也可以自定义数据源。</p>
  20. <p>运行脚本工具的 --help 选项可查看内置的帮助和说明,如乱码可在选项后加入 -c gbk 试试。</p>
  21. <pre>$prefix/sdk/php/util/Indexer.php --help
  22. </pre>
  23. <h2 id="ch0">1. 主要参数和选项<a name="ch0" class="anchor">?</a></h2>
  24. <p>要使用索引工具,必须先指定的项目名称或配置文件,所有的操作都将是作用于该项目,主要选项如下:</p>
  25. <ul>
  26. <li><p><em>-p|--project &lt;name|file></em> 指定项目名称或配置文件路径,参数名可以省略不写,
  27. 如果仅指定项目名称,那么将使用 $prefix/sdk/php/app/<name>.ini 文件。</p></li>
  28. <li><p><em>-c|--charset &lt;gbk|utf-8></em> 指定当前环境、数据源的字符集,默认情况下,
  29. 索引工具输出的字符集为 utf-8,并把数据源字符集视为项目的默认字符集。</p></li>
  30. <li><p><em>--source &lt;..source..></em> 用于指定数据源,数据源有以下 2 种情况。<br />
  31. 凡是包含冒号的数据源均视为 SQL 数据源,自动将 <em>--sql</em> 选项的值作为参数传递给数据源;<br />
  32. 其它情况则为文件数据源,自动将 <em>--file</em> 选项的值作为参数传递给数据源对象。</p></li>
  33. <li><p><em>--flush</em>、<em>--flush-log</em>、<em>--info</em> 是一些功能选项,与 <em>--source</em> 分开使用。</p></li>
  34. <li><p><em>-d|--db &lt;..name..></em> 指定要更新的索引数据库名称,默认是名为 db 的库。</p></li>
  35. <li><p><em>--filter</em> 指定数据过滤器,针对资深用户使用,在提交索引前可以处理一次数据。</p></li>
  36. <li><p><em>--add-synonym=&lt;raw1:synonym1[,raw2:synonym2]...></em> 添加同义词。</p></li>
  37. <li><p><em>--del-synonym=&lt;raw1[:synonym1[,raw2[:synonym2]]]...></em> 删除同义词。</p></li>
  38. </ul>
  39. <h2 id="ch1">2. 经典用法示例<a name="ch1" class="anchor">?</a></h2>
  40. <p>以下是一些经典用法举例:</p>
  41. <pre># 清空 demo 项目的索引数据
  42. util/Indexer.php --clean demo
  43. # 导入 JSON 数据文件 file.json 到 demo 项目
  44. util/Indexer.php --source=json demo file.json
  45. # 导入 MySQL 数据库的 dbname.tbl_post 表到 demo 项目中,并且平滑重建
  46. util/Indexer.php --rebuild --source=mysql://root:pass@localhost/dbname --sql=&quot;SELECT * FROM tbl_post&quot; --project=demo
  47. # 查看 demo 项目在服务端的相关信息
  48. util/Indexer.php --info -p demo
  49. # 强制刷新 demo 项目的搜索日志
  50. util/Indexer.php --flush-log --project demo
  51. </pre>
  52. <h2 id="ch2">3. 导入 SQL 数据库<a name="ch2" class="anchor">?</a></h2>
  53. <p>要导入 SQL 类的数据库,必须使用 <code>--source</code> 指定数据源,视情况用 <code>--sql</code> 选项指定查询语句。
  54. 其中数据源的格式如下:</p>
  55. <pre>dbtype://[user[:passwd]@]host/dbname[/table]
  56. dbtype://dbpath
  57. </pre>
  58. <p><code>dbtype</code> 就是相应的数据源名称,目前支持的有:mysql、sqlite、sqlite3、mysqli、pdo.mysql、pdo.sqlite 。
  59. 如果您还需要更多的数据库类型,请参见后面的自定义数据源自行扩充,对于嵌入式的数据库,
  60. 仅支持在数据源中设置路径。</p>
  61. <p>数据源仅仅指定了数据库连接的有关参数,您应当通过 <code>--sql</code> 选项指定查询语句,
  62. 查询得到的每行数据就会被转换为关联数组,并作为一条完整的文档数据提交到索引库中。
  63. 查询语句中允许使用表连接和 LIMIT, OFFSET 等行为,即便数据量很大,内部会作出相应优化。</p>
  64. <blockquote class="info">
  65. <p><strong>Info:</strong> 如果您在数据源中指定了 <code>table</code>,那么可以省略 <code>--sql</code> 选项,系统自动把该表的数据导入索引库。<br />
  66. 相当于指定了这样一条 SQL 语句:SELECT * FROM <em>table</em></p>
  67. <p>如果您的数据表过于庞大和复杂,强烈建建议您编写 SQL 语句,仅 SELECT 搜索相关的字段即可,
  68. 如果字段名称有变动,请用 AS 修改它。</p>
  69. </blockquote>
  70. <p>用法示例:</p>
  71. <pre># 导入 mysql 数据源
  72. util/Indexer.php --source=mysql://root@localhost/test --sql=&quot;select * from tbl_post&quot;
  73. # 导入 sqlite 数据源
  74. util/Indexer.php --source=sqlite:///tmp/test.db --sql=&quot;select * from tbl_post&quot;
  75. </pre>
  76. <h2 id="ch3">4. 导入 CSV 数据<a name="ch3" class="anchor">?</a></h2>
  77. <p>要导入 CSV 数据库文件,必须使用 <code>--source=csv</code> 来指定数据源,然后使用 <code>--file</code>
  78. 指定数据文件的路径,如果没有指定则自动从标准输入读取数据。</p>
  79. <p>对于 CSV 文件,要求必须每行一条数据,字段之间用半角的逗号分开。可以在首行指定字段名称列表,
  80. 但要求所有字段均必须是项目中的有效字段;如果没有指定字段列表,则自动按照默认的所有字段顺序读取。
  81. 这里所指的<strong>行</strong>是以 <code>\n (ASCII: 0x0a)</code> 换行符界定的。</p>
  82. <blockquote class="info">
  83. <p><strong>Info:</strong> 如果您的 CSV 文件字段分割符不是逗号,您可以使用 <code>--csv-delimiter</code>
  84. 选项来指定分割符,制表符使用 <code>\t</code> 表示,而如果是 <code>|</code> 这种引起 shell 解析冲突的,
  85. 请使用引号将它包起来。</p>
  86. <pre>util/Indexer.php --source=csv --csv-delimiter=&quot;\t&quot; demo # 使用 \t
  87. util/Indexer.php --source=csv --csv-delimiter=&quot;\\\\&quot; demo # 使用 \ 分割
  88. </pre>
  89. </blockquote>
  90. <h2 id="ch4">5. 导入 JSON 数据<a name="ch4" class="anchor">?</a></h2>
  91. <p>要导入 JSON 数据库文件,必须使用 <code>--source=json</code> 来指定数据源,然后使用 <code>--file</code>
  92. 指定数据文件的路径,如果没有指定则自动从标准输入读取数据。</p>
  93. <p>对于 JSON 文件,要求必须每行一条数据完整的 JSON 数据记录,将自动被转换为文档添加到索引中。
  94. 这里所指的<strong>行</strong>是以 <code>\n (ASCII: 0x0a)</code> 换行符界定的。</p>
  95. <h2 id="ch5">6. 清空、重建索引<a name="ch5" class="anchor">?</a></h2>
  96. <p>在批量导入各种数据源时,您可以加入 <code>--clean</code> 选项,该工具就会先清空现有索引数据库。</p>
  97. <blockquote class="info">
  98. <p><strong>Info:</strong> 清空数据库可以单独使用,不一定要搭配导入操作。</p>
  99. </blockquote>
  100. <p>由于清空立即生效会导致搜索中断或不可用一段时间,对于线上服务,建议使用 <code>--rebuild</code>
  101. 选项实现平滑重建,在导入完成后再将新数据库替换为原数据库。</p>
  102. <h2 id="ch6">7. 自定义数据过滤器<a name="ch6" class="anchor">?</a></h2>
  103. <p>自从 1.1.1 版本起,在索引工具中引入了过滤器的概念,通过 <code>--filter</code> 选项来指定。
  104. 这项功能以便于批量导入数据时,在数据提交到索引前有一次机会可以处理数据,常见的操作有
  105. 格式化数据,清除无效的标记标签等。</p>
  106. <p>内置的过滤器只有一个,就是 <code>debug</code>,它相当于在数据提交前执行一次 print_r 函数,
  107. 打印出数据的实际内容,可用于调试。</p>
  108. <p>我们要求所有自定义过滤器必须实现 <a href="../api/XSDataFilter.html">XSDataFilter</a> 这个接口,里面只有一个函数方法,
  109. 那就是 <a href="../api/XSDataFilter.html#process">XSDataFilter::process</a> 它接收 2 个参数,第一个参数是字段键值组成的数组,
  110. 第二个字段是当前的字符集,如果不能确定则为 false 值。</p>
  111. <p>您可以在这个方法函数中对数据进行处理再返回。此外,编写好的过滤器必须单独以类名为文件名
  112. 保存,比如您的过滤器对象名称为 XSXyzFilter,那么您必须将代码命名为 XSXyzFilter.php
  113. 保存。使用的时候用 --filter=/paht/to/XSXyzFilter 作为参数。</p>
  114. <blockquote class="note">
  115. <p><strong>Note:</strong> 当过滤器处理完数据返回 false 时,索引工具将跳过此条数据不添加到索引中。</p>
  116. </blockquote>
  117. <p>典型过滤器写法如下,文件保存为 XSXyzFilter.php</p>
  118. <div class="hl-code"><div class="php-hl-main"><pre><span class="php-hl-reserved">class</span> <span class="php-hl-identifier">XSXyzFilter</span> <span class="php-hl-reserved">implements</span> <span class="php-hl-identifier">XSDataFilter</span>
  119. <span class="php-hl-brackets">{</span>
  120. <span class="php-hl-reserved">public</span> <span class="php-hl-reserved">function</span> <span class="php-hl-identifier">process</span><span class="php-hl-brackets">(</span><span class="php-hl-var">$data</span><span class="php-hl-code">, </span><span class="php-hl-var">$cs</span><span class="php-hl-brackets">)</span>
  121. <span class="php-hl-brackets">{</span>
  122. <span class="php-hl-identifier">print_r</span><span class="php-hl-brackets">(</span><span class="php-hl-var">$data</span><span class="php-hl-brackets">)</span><span class="php-hl-code">;
  123. </span><span class="php-hl-reserved">return</span> <span class="php-hl-var">$data</span><span class="php-hl-code">;
  124. </span><span class="php-hl-brackets">}</span>
  125. <span class="php-hl-brackets">}</span></pre></div></div>
  126. <h2 id="ch7">8. 自定义数据源<a name="ch7" class="anchor">?</a></h2>
  127. <p>目前数据源有两种类型,一种是文件数据源(如 JSON、CSV),另一种是 SQL 数据库源(如 MySQL,SQLite)。</p>
  128. <p>自定义数据源均要求必须是抽象类 <a href="../api/XSDataSource.html">XSDataSource</a> 的子类,建议单独编写相应的类定义文件并放入
  129. <code>$prefix/sdk/php/lib</code> 目录,以便脚本在使用时自动加载。</p>
  130. <p>数据源对象中包含两个 <code>protected</code> 属性,可以在初始化时使用它们:</p>
  131. <ul>
  132. <li><a href="../api/XSDataSource.html#type">XSDataSource::type</a> 对应命令行中 <em>--source</em> 选项的值</li>
  133. <li><a href="../api/XSDataSource.html#arg">XSDataSource::arg</a> 则为相应的 <em>--sql</em> 或 <em>--file</em> 选项的值。</li>
  134. </ul>
  135. <h4 id="-">文件数据源</h4>
  136. <p>对于文件数据源,请直接扩展 <a href="../api/XSDataSource.html">XSDataSource</a>,对于名称为 <code>Xyz</code> 的数据源,请命名为
  137. <code>XSXyzDataSource</code> 并重载以下方法:</p>
  138. <ul>
  139. <li>protected <a href="../api/XSDataSource.html#init">XSDataSource::init</a> 开始读取数据时调用,用于初始化数据源的相关资源。</li>
  140. <li>protected <a href="../api/XSDataSource.html#deinit">XSDataSource::deinit</a> 读取数据结束时调用,释放相关资源。</li>
  141. <li>protected <a href="../api/XSDataSource.html#getDataList">XSDataSource::getDataList</a> 读取一批数据,可以是一条或若干条,组成数组返回,没有更多数据时返回 false 。</li>
  142. <li>public <a href="../api/XSDataSource.html#getCharset">XSDataSource::getCharset</a> 返回精准的数据源字符集,如果不能确定请返回 false 或不重载。</li>
  143. </ul>
  144. <h4 id="-">数据库数据源</h4>
  145. <p>对于数据库数据源,请直接扩展 <a href="../api/XSDatabase.html">XSDatabase</a>,对于名称为 <code>Xyz</code> 的数据源,请命名为
  146. <code>XSDatabaseXyz</code> 并重载以下方法:</p>
  147. <ul>
  148. <li>protected <a href="../api/XSDatabase.html#connect">XSDatabase::connect</a> 连接数据库,参数是一个数组,包含连接相关的参数(host,user,pass,dbname,table)、数据库路径(path)</li>
  149. <li>protected <a href="../api/XSDatabase.html#close">XSDatabase::close</a> 关闭数据库连接</li>
  150. <li>protected <a href="../api/XSDatabase.html#query">XSDatabase::query</a> 执行数据库查询,对于 SELECT 类的操作请将搜索结果以数组方式返回,其它请直接返回 true/false 代表成功/失败</li>
  151. <li>protected <a href="../api/XSDatabase.html#setUtf8">XSDatabase::setUtf8</a> 尝试将数据库输出字符集强制设为 UTF-8 ,如数据库不支持此功能请返回 false 或不重载。</li>
  152. </ul>
  153. <h4 id="pdo-">PDO 数据库数据源</h4>
  154. <p>对于 PDO 扩展的数据源,请直接扩展 <a href="../api/XSDatabasePDO.html">XSDatabasePDO</a>,对于名称为 <code>Xyz</code> 的数据源,请命名为
  155. <code>XSDatabasePDO_Xyz</code> 并重载以下方法:</p>
  156. <ul>
  157. <li>protected <a href="../api/XSDatabasePDO.html#makeDsn">XSDatabasePDO::makeDsn</a> 生成 PDO 连接字符串,参数和 <a href="../api/XSDatabase.html#connect">XSDatabase::connect</a> 一样。</li>
  158. <li>protected <a href="../api/XSDatabase.html#setUtf8">XSDatabase::setUtf8</a> 尝试将数据库输出字符集强制设为 UTF-8 ,如数据库不支持此功能请返回 false 或不重载。</li>
  159. </ul>
  160. <blockquote class="note">
  161. <p><strong>Note:</strong> 由于我们使用 <a href="http://php.net/manual/en/function.parse-url.php">parse_url</a> 解析 SQL 数据源连接参数,它并不支持用下划线作 scheme 。
  162. 如果要直接使用 PDO 数据源,请把 dbtype 设为 pdo.xxx 而不是 pdo_xxx 。</p>
  163. </blockquote>
  164. <h2 id="ch8">9. 同义词管理<a name="ch8" class="anchor">?</a></h2>
  165. <p>通常每条记录包含“原词(标准词)“和”同义词”两个元素,同义词记录是和当前索引库绑定的,并非和项目绑定。
  166. 如果您通过 <a href="../api/XSIndex.html#setDb">XSIndex::setDb</a> 修改了当前索引库名,那么您所进行的同义词变动将作用到该库上。</p>
  167. <h4 id="-">添加同义词</h4>
  168. <p>通过带参数的选项 <code>--add-synonym</code> 来实现,参数值为单条或多条同义词记录,每条记录之间用冒号(:)
  169. 分隔原词和同义词,多条记录之间用逗号分割。您可以对同一个“原词”增加多个不同的“同义词”,
  170. 如果库内已存在完全一致的记录,则指令不起作用也不会报错。用法如下:</p>
  171. <pre># 给 search 增加同义词 find
  172. util/Indexer.php demo --add-synonym search:find
  173. # 再给 search 增加另一个同义词 seek
  174. util/Indexer.php demo --add-synonym search:seek
  175. # 给 &quot;搜索&quot; 增加 &quot;检索&quot; &quot;查找&quot; 两个同义词
  176. util/Indexer.php demo -add-synonym 搜索:检索,搜索:查找
  177. # 给 &quot;Hello world&quot; 增加同义词 &quot;你好&quot;,参数含空格请用引号包围
  178. util/Indexer.php demo --add-synonym &quot;Hello world:你好&quot;
  179. </pre>
  180. <h4 id="-">删除同义词</h4>
  181. <p>删除同义词作法和添加同义词很相似,只不过采用选项 <code>--del-synonym</code>,同时参数中的同义词可以
  182. 省略表示删除该“原词”的所有同义词记录。用法如下:</p>
  183. <pre># 删除 search 的全部同义词、同时删除 &quot;搜索&quot; 的同义词 &quot;检索&quot;
  184. util/Indexer.php demo --del-synonym search,搜索:检索
  185. </pre>
  186. <h4 id="-">浏览全部同义词</h4>
  187. <p>查看同义词列表的功能请参见 <a href="util.Quest#ch2">Quest 搜索工具</a></p>
  188. <blockquote class="tip">
  189. <p><strong>Tip:</strong> 同义词功能是 <em>1.3.0</em> 版本引入的新功能,详情参见<a href="special.synonym.html">同义词专题文档</a>。<br />
  190. 通常<strong>原词(标准词)</strong>和<strong>同义词</strong>都必须是独立的词汇,也就是最小的索引单位。但对于纯英文字母<strong>原词</strong>,
  191. 允许用空格连接多个单词,英文字母都会统一转换为<strong>小写</strong>。</p>
  192. <p>单个英文原词会同时保存词根同义词记录。如:设置 <code>find</code> 是 <em>search</em> 的同义词,那么检索 <em>searching</em>
  193. 也会匹配包含 <code>finding</code> 或 <code>finds</code> 等同根词的结果。</p>
  194. </blockquote>
  195. <div class="revision">$Id$</div>
  196. <div class="clear"></div>
  197. </div><!-- end of content -->
  198. <div id="guideNav">
  199. <div class="prev"><a href="util.check.html">&laquo; RequiredCheck 运行检测</a></div>
  200. <div class="next"><a href="util.quest.html">Quest 搜索测试工具 &raquo;</a></div>
  201. <div class="clear"></div>
  202. </div><!-- end of nav -->
  203. <div id="apiFooter">
  204. Copyright &copy; 2008-2011 by <a href="http://www.xunsearch.com" target="_blank">杭州云圣网络科技有限公司</a><br/>
  205. All Rights Reserved.<br/>
  206. </div><!-- end of footer -->
  207. </div><!-- end of page -->
  208. <div style="display:none;">
  209. <img src="../api/css/info.gif" />
  210. <img src="../api/css/tip.gif" />
  211. <img src="../api/css/note.gif" />
  212. </div>
  213. </body>
  214. </html>