[Xunsearch PHP-SDK](http://www.xunsearch.com) v1.4.8 權威指南 1. [主要參數和選項](#) 1. [經典用法示例](#) 1. [導入 SQL 數據庫](#) 1. [導入 CSV 數據](#) 1. [導入 JSON 數據](#) 1. [清空、重建索引](#) 1. [自定義數據過濾器](#) 1. [自定義數據源](#) 1. [同義詞管理](#) 1. [存取項目自定義詞庫](#) # 索引管理器 `Indexer` 作為索引管理工具，提供了批量索引導入、清空索引、刷新索引隊列、日志等各項功能，導入索引支持數據源包括：`csv, json, mysql, sqlite` 等，也可以自定義數據源。 運行腳本工具的 --help 選項可查看內置的幫助和說明，如亂碼可在選項后加入 -c gbk 試試。 ~~~ $prefix/sdk/php/util/Indexer.php --help ~~~ ### 1. 主要參數和選項[?]() 要使用索引工具，必須先指定的項目名稱或配置文件，所有的操作都將是作用于該項目，主要選項如下： - *-p|--project <name|file>* 指定項目名稱或配置文件路徑，參數名可以省略不寫，如果僅指定項目名稱，那么將使用 $prefix/sdk/php/app/.ini 文件。 - *-c|--charset <gbk|utf-8>* 指定當前環境、數據源的字符集，默認情況下，索引工具輸出的字符集為 utf-8，并把數據源字符集視為項目的默認字符集。 - *--source <..source..>* 用于指定數據源，數據源有以下 2 種情況。 凡是包含冒號的數據源均視為 SQL 數據源，自動將 *--sql* 選項的值作為參數傳遞給數據源； 其它情況則為文件數據源，自動將 *--file* 選項的值作為參數傳遞給數據源對象。 - *--flush*、*--flush-log*、*--info* 是一些功能選項，與 *--source* 分開使用。 - *-d|--db <..name..>* 指定要更新的索引數據庫名稱，默認是名為 db 的庫。 - *--filter* 指定數據過濾器，針對資深用戶使用，在提交索引前可以處理一次數據。 - *--add-synonym=<raw1:synonym1[,raw2:synonym2]...>* 添加同義詞。 - *--del-synonym=<raw1[:synonym1[,raw2[:synonym2]]]...>* 刪除同義詞。 - *--stop-rebuild* 停止異常中斷的重建任務。 ### 2. 經典用法示例[?]() 以下是一些經典用法舉例： ~~~ # 清空 demo 項目的索引數據 util/Indexer.php --clean demo # 導入 JSON 數據文件 file.json 到 demo 項目 util/Indexer.php --source=json demo file.json # 導入 MySQL 數據庫的 dbname.tbl_post 表到 demo 項目中，并且平滑重建 util/Indexer.php --rebuild --source=mysql://root:pass@localhost/dbname --sql="SELECT * FROM tbl_post" --project=demo # 查看 demo 項目在服務端的相關信息 util/Indexer.php --info -p demo # 強制刷新 demo 項目的搜索日志 util/Indexer.php --flush-log --project demo # 強制停止重建 util/Indexer.php --stop-rebuild demo ~~~ ### 3. 導入 SQL 數據庫[?]() 要導入 SQL 類的數據庫，必須使用 `--source` 指定數據源，視情況用 `--sql` 選項指定查詢語句。其中數據源的格式如下： ~~~ dbtype://[user[:passwd]@]host/dbname[/table] dbtype://dbpath ~~~ `dbtype` 就是相應的數據源名稱，目前支持的有：mysql、sqlite、sqlite3、mysqli、pdo.mysql、pdo.sqlite 。如果您還需要更多的數據庫類型，請參見后面的自定義數據源自行擴充，對于嵌入式的數據庫，僅支持在數據源中設置路徑。 數據源僅僅指定了數據庫連接的有關參數，您應當通過 `--sql` 選項指定查詢語句，查詢得到的每行數據就會被轉換為關聯數組，并作為一條完整的文檔數據提交到索引庫中。查詢語句中允許使用表連接和 LIMIT, OFFSET 等行為，即便數據量很大，內部會作出相應優化。 > **Info:** 如果您在數據源中指定了 `table`，那么可以省略 `--sql` 選項，系統自動把該表的數據導入索引庫。 相當于指定了這樣一條 SQL 語句：SELECT * FROM *table* > 如果您的數據表過于龐大和復雜，強烈建建議您編寫 SQL 語句，僅 SELECT 搜索相關的字段即可， 如果字段名稱有變動，請用 AS 修改它。 用法示例： ~~~ # 導入 mysql 數據源 util/Indexer.php --source=mysql://root@localhost/test --sql="select * from tbl_post" # 導入 sqlite 數據源 util/Indexer.php --source=sqlite:///tmp/test.db --sql="select * from tbl_post" ~~~ ### 4. 導入 CSV 數據[?]() 要導入 CSV 數據庫文件，必須使用 `--source=csv` 來指定數據源，然后使用 `--file` 指定數據文件的路徑，如果沒有指定則自動從標準輸入讀取數據。 對于 CSV 文件，要求必須每行一條數據，字段之間用半角的逗號分開。可以在首行指定字段名稱列表，但要求所有字段均必須是項目中的有效字段；如果沒有指定字段列表，則自動按照默認的所有字段順序讀取。這里所指的**行**是以 `\n (ASCII: 0x0a)` 換行符界定的。 > **Info:** 如果您的 CSV 文件字段分割符不是逗號，您可以使用 `--csv-delimiter` 選項來指定分割符，制表符使用 `\t` 表示，而如果是 `|` 這種引起 shell 解析沖突的， 請使用引號將它包起來。 ~~~ util/Indexer.php --source=csv --csv-delimiter="\t" demo # 使用 \t util/Indexer.php --source=csv --csv-delimiter="\\\\" demo # 使用 \ 分割 ~~~ ### 5. 導入 JSON 數據[?]() 要導入 JSON 數據庫文件，必須使用 `--source=json` 來指定數據源，然后使用 `--file` 指定數據文件的路徑，如果沒有指定則自動從標準輸入讀取數據。 對于 JSON 文件，要求必須每行一條數據完整的 JSON 數據記錄，將自動被轉換為文檔添加到索引中。這里所指的**行**是以 `\n (ASCII: 0x0a)` 換行符界定的。 ### 6. 清空、重建索引[?]() 在批量導入各種數據源時，您可以加入 `--clean` 選項，該工具就會先清空現有索引數據庫。 > **Info:** 清空數據庫可以單獨使用，不一定要搭配導入操作。 由于清空立即生效會導致搜索中斷或不可用一段時間，對于線上服務，建議使用 `--rebuild`選項實現平滑重建，在導入完成后再將新數據庫替換為原數據庫。 ### 7. 自定義數據過濾器[?]() 自從 1.1.1 版本起，在索引工具中引入了過濾器的概念，通過 `--filter` 選項來指定。這項功能以便于批量導入數據時，在數據提交到索引前有一次機會可以處理數據，常見的操作有格式化數據，清除無效的標記標簽等。 內置的過濾器只有一個，就是 `debug`，它相當于在數據提交前執行一次 print_r 函數，打印出數據的實際內容，可用于調試。 我們要求所有自定義過濾器必須實現 [XSDataFilter](#) 這個接口，里面需要實現以下方法： - [XSDataFilter::process](#) 字段數據預處理，在此進行數據調整和過濾不相關的內容然后返回數據 - [XSDataFilter::processDoc](#) 索引文檔處理，在好習慣進行索引相關調整（自 1.3.4 起有效） > **Note:** 當過濾器的 `process` 方法返回 false 時，索引工具不會將此條數據添加到索引庫。 編寫好的過濾器必須單獨以類名為文件名保存，比如您的過濾器對象名稱為 XSXyzFilter，那么請將代碼命名為 XSXyzFilter.php 保存，在索引工具中使用參數 `--filter=/paht/to/XSXyzFilter`來指定這個過濾器。 典型過濾器寫法如下，文件保存為 XSXyzFilter.php ~~~ class XSXyzFilter implements XSDataFilter { public function process($data, $cs) { print_r($data); return $data; } public function processDoc($doc) { // $doc->addTerm('subject', '特殊詞'); } } ~~~ ### 8. 自定義數據源[?]() 目前數據源有兩種類型，一種是文件數據源（如 JSON、CSV），另一種是 SQL 數據庫源（如 MySQL，SQLite）。 自定義數據源均要求必須是抽象類 [XSDataSource](#) 的子類，建議單獨編寫相應的類定義文件并放入 `$prefix/sdk/php/lib` 目錄，以便腳本在使用時自動加載。 數據源對象中包含兩個 `protected` 屬性，可以在初始化時使用它們： - [XSDataSource::type](#) 對應命令行中 *--source* 選項的值 - [XSDataSource::arg](#) 則為相應的 *--sql* 或 *--file* 選項的值。 #### 文件數據源 對于文件數據源，請直接擴展 [XSDataSource](#)，對于名稱為 `Xyz` 的數據源，請命名為 `XSXyzDataSource` 并重載以下方法： - protected [XSDataSource::init](#) 開始讀取數據時調用，用于初始化數據源的相關資源。 - protected [XSDataSource::deinit](#) 讀取數據結束時調用，釋放相關資源。 - protected [XSDataSource::getDataList](#) 讀取一批數據，可以是一條或若干條，組成數組返回，沒有更多數據時返回 false 。 - public [XSDataSource::getCharset](#) 返回精準的數據源字符集，如果不能確定請返回 false 或不重載。 #### 數據庫數據源 對于數據庫數據源，請直接擴展 [XSDatabase](#)，對于名稱為 `Xyz` 的數據源，請命名為 `XSDatabaseXyz` 并重載以下方法： - protected [XSDatabase::connect](#) 連接數據庫，參數是一個數組，包含連接相關的參數(host,user,pass,dbname,table)、數據庫路徑(path) - protected [XSDatabase::close](#) 關閉數據庫連接 - protected [XSDatabase::query](#) 執行數據庫查詢，對于 SELECT 類的操作請將搜索結果以數組方式返回，其它請直接返回 true/false 代表成功/失敗 - protected [XSDatabase::setUtf8](#) 嘗試將數據庫輸出字符集強制設為 UTF-8 ，如數據庫不支持此功能請返回 false 或不重載。 #### PDO 數據庫數據源 對于 PDO 擴展的數據源，請直接擴展 [XSDatabasePDO](#)，對于名稱為 `Xyz` 的數據源，請命名為 `XSDatabasePDO_Xyz` 并重載以下方法： - protected [XSDatabasePDO::makeDsn](#) 生成 PDO 連接字符串，參數和 [XSDatabase::connect](#) 一樣。 - protected [XSDatabase::setUtf8](#) 嘗試將數據庫輸出字符集強制設為 UTF-8 ，如數據庫不支持此功能請返回 false 或不重載。 > **Note:** 由于我們使用 [parse_url](http://php.net/manual/en/function.parse-url.php) 解析 SQL 數據源連接參數，它并不支持用下劃線作 scheme 。 如果要直接使用 PDO 數據源，請把 dbtype 設為 pdo.xxx 而不是 pdo_xxx 。 ### 9. 同義詞管理[?]() 通常每條記錄包含“原詞(標準詞)“和”同義詞”兩個元素，同義詞記錄是和當前索引庫綁定的，并非和項目綁定。如果您通過 [XSIndex::setDb](#) 修改了當前索引庫名，那么您所進行的同義詞變動將作用到該庫上。 #### 添加同義詞 通過帶參數的選項 `--add-synonym` 來實現，參數值為單條或多條同義詞記錄，每條記錄之間用冒號(:)分隔原詞和同義詞，多條記錄之間用逗號分割。您可以對同一個“原詞”增加多個不同的“同義詞”，如果庫內已存在完全一致的記錄，則指令不起作用也不會報錯。用法如下： ~~~ # 給 search 增加同義詞 find util/Indexer.php demo --add-synonym search:find # 再給 search 增加另一個同義詞 seek util/Indexer.php demo --add-synonym search:seek # 給 "搜索" 增加 "檢索" "查找" 兩個同義詞 util/Indexer.php demo -add-synonym 搜索:檢索,搜索:查找 # 給 "Hello world" 增加同義詞 "你好"，參數含空格請用引號包圍 util/Indexer.php demo --add-synonym "Hello world:你好" ~~~ #### 刪除同義詞 刪除同義詞作法和添加同義詞很相似，只不過采用選項 `--del-synonym`，同時參數中的同義詞可以省略表示刪除該“原詞”的所有同義詞記錄。用法如下： ~~~ # 刪除 search 的全部同義詞、同時刪除 "搜索" 的同義詞 "檢索" util/Indexer.php demo --del-synonym search,搜索:檢索 ~~~ #### 瀏覽全部同義詞 查看同義詞列表的功能請參見 [Quest 搜索工具](#) > **Tip:** 同義詞功能是 *1.3.0* 版本引入的新功能，詳情參見[同義詞專題文檔](#)。 通常**原詞(標準詞)**和**同義詞**都必須是獨立的詞匯，也就是最小的索引單位。但對于純英文字母**原詞**， 允許用空格連接多個單詞，英文字母都會統一轉換為**小寫**。 > 單個英文原詞會同時保存詞根同義詞記錄。如：設置 `find` 是 *search* 的同義詞，那么檢索 *searching* 也會匹配包含 `finding` 或 `finds` 等同根詞的結果。 ### 10. 存取項目自定義詞庫[?]() 您也可以通過命令行查看和修改項目的自定義詞庫，具體用法如下： ~~~ # 查看 demo 項目的自定義詞庫 util/Indexer.php demo --custom-dict # 將已有自定義詞庫文件 d.txt 設置為 demo 項目的自定義詞庫，結合 --file 選項 util/Indexer.php demo --custom-dict --file /path/to/d.txt # 清空/刪除自定義詞庫，用 /dev/null util/Indexer.php demo --custom-dict --file /dev/null ~~~ > **Note:** 項目自定義詞庫是 *1.3.4* 引入的新功能 $Id$ [? RequiredCheck 運行檢測](#) [Quest 搜索測試工具 ?](#) Copyright ? 2008-2011 by [杭州云圣網絡科技有限公司](http://www.xunsearch.com) All Rights Reserved.