索引管理器
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 的库。
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
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. 自定义数据源?
目前数据源有两种类型,一种是文件数据源(如 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 解析 SQL 数据源连接参数,它并不支持用下划线作 scheme 。 如果要直接使用 PDO 数据源,请把 dbtype 设为 pdo.xxx 而不是 pdo_xxx 。