Solr DIH使用说明

DIH（Data Import Handler）是Solr附带的用来从关系型数据库、XML、email等目标导入数据的工具，本文仅说明Solr5.3.1中使用DIH从关系型数据库中导入数据的方式。

一、      配置Solr

1.  安装JDK1.7以上版本，此处略。

2.  安装应用服务器，如tomcat7以上版本，此处略。

3.  部署Solr Web应用：

a)   解压官方下载包solr-5.3.1.zip

b)   将solr-5.3.1\server\solr-webapp\webapp下所有内容拷贝到服务器WEB应用目录

c)   将solr-5.3.1\server\lib\ext目录下的Jar包全复制到WEB-INF\lib

d)   将solr-5.3.1\server\resources\log4j.properties复制到WEB-INF\lib

e)   创建一个用于存放Solr数据的目录（任意可访问位置），例如/srv/www/app/solr_home;

f)   将solr-5.3.1\server\solr\中的内容复制到上一步创建的目录

修改WEB-INF/web.xml
取消env-entry标签的注释，并修改子标签env-entry-value的值
本例中中改成/srv/www/app/solr_home
注意：该处不能填错，填错后不能正常启动
<env-entry>

    <env-entry-name>solr/home</env-entry-name>

    <env-entry-value>/srv/www/app/solr_home</env-entry-value>

    <env-entry-type>java.lang.String</env-entry-type>

</env-entry>

g)   在/srv/www/app/solr_home创建一个目录，例如core,并将solr-5.3.1\server\solr\configsets\basic_configs下的conf文件夹放入core中

h)   启动服务器，并在浏览器中访问，出现solr管理界面

i)  

创建Core，步骤如下：

j)   Solr在Tomcat部署完成

二、      配置schema.xml

Solr索引的内容是以Document为单位的，由于我们使用Solr索引数据库中表的数据，一个Document相当于一条记录，而这条记录所拥有的字段由schema.xml配置。

Schema.xml的配置比较简单，在模版的基础上修改即可。本文前面配置的Solr的Schema.xml文件位于solr_home/core/conf中。

我们使用Field标签来定义Document的字段。模版中的Field一条Field配置如下：

<field name="id"type="string" indexed="true" stored="true"required="true" multiValued="false" />

属性解释分别如下：

Type:字段类型，引用的类型必须在Schema.xml中配置，模版中已经配置了常用的type。直接使用即可

Indexed:该字段是否索引

Stored:该字段是否在solr中存储

Required:该字段是否必须，即是否能为空

multivalued:该字段是否能为多值（关联表一对多）。

模版中配置了很多dynamicField，该字段的的名称支持模糊匹配。由于我们从数据库中导入数据，不需要该类标签。

三、      配置DIH

a.  将solr-5.3.1\dist\solr-dataimporthandler-5.3.1.jar和数据库驱动拷贝到WEB-INF/lib中

b.  将solr-5.3.1\example\example-DIH\solr\db\conf\db-data-config.xml拷贝到solr_home/core/conf中

c.  在solrconfig.xml中注册声明DIH，如下：
<requestHandler name="/dataimport"
class="org.apache.solr.handler.dataimport.DataImportHandler">

c.  <lst name="defaults">

c.    <strname="config">db-data-config.xml</str>
  </lst>

c.</requestHandler>

d.  配置DIH配置文件db-data-config.xml，该文件配置了数据导入的数据源，导入规则（全量导入和增量导入），是DIH的核心配置文件。

四、      DIH控制命令

DIH提供了通过Http请求控制DIH的方式，包含以下功能：

命令	描述
Abort	终止正在执行的操作。
Delta-import	增量导入数据
Full-import	全量导入数据
Reload-config	重载DIH配置文件
status	查询状态，返回文档创建数，文档删除数等状态信息

执行DIH控制命令的url格式如下：

http://ip:port/[webdir/]CoreName/dataimport?command=command[&params]

Full-import和delta-import导入还有额外的参数，如下表：

参数	描述
clean	默认为true,表示是否在建立下一次索引前清除原有索引。
commit	默认为true,表示是否在操作过后提交。
debug	默认为false。表示是否以Debug模式运行。此模式commit默认为false。
entity	用以指定操作的entity。只能制定DIH配置文件中<document>内首层<entity>元素的name。如果传空值，则对所有entity执行操作
optimize	默认为true。表示在操作之后是否optimize（优化索引）

如果执行全量导入操作，导入前清除索引，导入后提交结果，则发送如下Url请求：

http://ip:port/[webdir/]CoreName/dataimport?command=full-import&clean=true&commit=true

如果执行增量导入操作，导入前不清除索引，导入后提交结果，发送url如下：

http://ip:port/[webdir/]CoreName/dataimport?command=delta-import&clean=false&commit=true

五、      配置数据源

在DIH配置文件的dataConfig标签下的dataSource标签内配置数据源，标签属性解释如下：

name:数据源引用名称，DIH支持多数据源；

type:数据源类型，从数据库导入一般使用JdbcDataSource，必须

driver:数据库驱动，必须

url:数据库JDBC连接url，如果后面没有设置jndiName，此项必须

user:数据库用户名

password:数据库密码

jndiName:预配置数据源的JNDI名称

batchSize:在JDBC连接中使用。如果不指定，可以设为-1以防止setFetchSize()异常

convertType:默认为false。与读取数据转换数据类型相关

autoCommit:如果设置为false。将对连接setAutoCommit(false)

readOnly:设置为true，则对数据库连接setReadOnly(true), setAutoCommit(true),setTransactionIsolation(TRANSACTION_READ_UNCOMMITTED),setHoldability(CLOSE_CURSORS_AT_COMMIT)

transactionIsolation:可能值为[TRANSACTION_READ_UNCOMMITTED,TRANSACTION_READ_COMMITTED,TRANSACTION_REPEATABLE_READ,TRANSACTION_SERIALIZABLE,TRANSACTION_NONE]

六、      配置导入规则

每个Solr文档（document）可以看作是一个具有从不同表获得的字段的非规范的表格。

数据导入的规则定义在DIH的配置文件的document标签中，每个docoment标签代表一种document。每个document标签包含一个或者多个根entity。每个根Entity可以包含多个子Entity，子Entity可以嵌套Entity。一个Entity对应关系型数据库中的表/视图。每个Entity标签内可以有多个field标签。每个Field对应一个使用Entity中定义的query语句查询获得结果集的一个字段（column）。对于每个field，如果Column名与Solr定义的field名称不同，则需要在Field标签内增加属性name，用来指定对应的field名字。Field中其他必要的属性例如字段类型（type）会直接使用schema.xml的定义。

此外，根Entity对应的表的column被用作与子Entity对应表关联。

用作数据导入的配置并没有固定的模式，Entity/field标签中的属性可以改变，并且根据所采用的processor 和transformer改变。

Entity标签默认支持的属性如下：

Name:（必须）唯一的名称，用来区分Entity。

Processor:如果不定义，默认值为SqlEntityProcessor，用于从关系型数据库导入数据。如果从关系型数据库以外的源导入数据，需要指定对应的Processor。

Transformer:应用在此字段上的transformer。

dataSource:Entity对应表或者视图所用的数据源。引用数据源配置的name。

threads:该参数在Solr3.6版本中废弃。

Pk：Entity中的主键，与数据库中的主键不完全对应。该字段可选，用于增量导入（delta-import）。

RootEntity:默认document标签下的Entity标签的该属性为True。如果该层Entity的属性为False。则接下来一层的Entity的该属性为Ture。（嵌套时直到该属性为True）。根Entity每有一条记录满足条件，就会在Solr中创建一个文档（Document）。

onError:可能值为三个，abort,skip和continue。默认值为abort,表示终止导入；skip表示跳过导入错误的Document。Continue表示忽略错误，继续执行导入。

preImportDeltaQuery:在全导入前，如果未定义该属性，则使用“*:*”作为条件Clean索引。如果定义该属性，则使用该属性定义值清除索引。不用或慎用。

postImportDeltaQuery:在全导入后，该属性被用来清理索引<!>(此处意义不明，需要查看源码)。不用或慎用。

当从关系型数据库中导入数据时，默认使用SqlEntityProcessor，由于此Processor所引入的属性如下：

query：（必须），用来查询DB的Sql语句。该语句查询得到该Entity所需要的记录和字段。对于子Entity，需要引用父Entity中的某个字段，以实现表间关联。

DeltaQuery：只在增量导入中使用。该语句提供该Entity中对应表的修改记录的主键值的集合。数据库需要有修改时间的字段，该Sql根据修改时间查询满足条件的记录。

parentDeltaQuery：只在增量导入中有效。该语句使用deltaQuery中得到的主键值集合获得父Entity改变记录的主键值的集合。

deletePkQuery: 只在增量导入中有效。该属性提供数据库中标记为删除记录的主键值。为了实现能够删除记录的同步，需要在数据库每个表中增加字段用来标识该记录需要删除。

deltaImportQuery: 只在增量导入中有效。该属性用于根Entity，如果该属性不存在，DIH会使用尝试使用query属性中的Sql语句生成查询。该属性中可以使用变量${dih.delta.<column_name>}。

强调：

A．由于Qurey定义的语句的查询每得到一行结果，子Entity中定义的Query语句都会执行一次；

B．对与每个Entity，每个DeltaQuery返回的每一行，都会对应的执行一次parentDeltaQuery定义的语句。

C．如果任何行该表，包括根/子Entity对应表的记录改变。Solr都会重建整个Document。即查询到更改后，Docment是重新查询数据库并赋值的。

七、      数据导入配置示例

该示例使用的表以及相互关系如下：

全导入配置示例：

<dataConfig>

<dataSource driver="oracle.jdbc.driver.OracleDriver"

url="jdbc:oracle:thin:@127.0.0.1/orcl"user="sa" password="password" />

   <document name="products">

       <entity name="item" query="select * fromitem">

           <field column="ID" name="id" />

           <field column="NAME" name="name" />

           <field column="MANU" name="manu" />

           <field column="WEIGHT" name="weight" />

           <field column="PRICE" name="price" />

           <field column="POPULARITY" name="popularity"/>

           <field column="INSTOCK" name="inStock" />

           <field column="INCLUDES" name="includes" />

           <entity name="feature" query="select description fromfeature where item_id='${item.ID}'">

               <field name="features" column="description" />

           </entity>

           <entity name="item_category" query="select CATEGORY_IDfrom item_category where item_id='${item.ID}'">

               <entity name="category" query="select description fromcategory where id = '${item_category.CATEGORY_ID}'">

                   <field column="description" name="cat" />

                </entity>

           </entity>

       </entity>

   </document>

</dataConfig>

 

如果schema中配置的字段name与数据库结果集column name一致，则配置可以简化为：

<dataConfig>

   <dataSource driver="oracle.jdbc.driver.OracleDriver"

url="jdbc:oracle:thin:@127.0.0.1/orcl"user="sa" password="password" />

   <document>

       <entity name="item" query="select * fromitem">

           <entity name="feature" query="select description asfeatures from feature where item_id='${item.ID}'"/>

           <entity name="item_category" query="select CATEGORY_IDfrom item_category where item_id='${item.ID}'">

               <entity name="category" query="select description ascat from category where id = '${item_category.CATEGORY_ID}'"/>

           </entity>

       </entity>

   </document>

</dataConfig>

 

增量导入示例：

<dataConfig>

   <dataSource driver="oracle.jdbc.driver.OracleDriver"

 url="jdbc:oracle:thin:@127.0.0.1/orcl"user="sa" password="password" />

   <document>

       <entity name="item" pk="ID" query="select *from item"

          deltaImportQuery="select * from item whereID=='${dih.delta.id}'"

               deltaQuery="select id from item where last_modified  >'${dih.last_index_time}'">

               <entity name="feature" pk="ITEM_ID"

                   query="select DESCRIPTION as features from FEATURE whereITEM_ID='${item.ID}'"

                   deltaQuery="select ITEM_ID from FEATURE where last_modified >'${dih.last_index_time}'"

                   parentDeltaQuery="select ID from item where ID=${feature.ITEM_ID}"/>

           <entity name="item_category" pk="ITEM_ID,CATEGORY_ID"

                   query="select CATEGORY_ID from item_category whereITEM_ID='${item.ID}'"

                   deltaQuery="select ITEM_ID, CATEGORY_ID from item_category wherelast_modified > '${dih.last_index_time}'"

                   parentDeltaQuery="select ID from item whereID=${item_category.ITEM_ID}">

               <entity name="category" pk="ID"

                        query="selectDESCRIPTION as cat from category where ID ='${item_category.CATEGORY_ID}'"

                        deltaQuery="selectID from category where last_modified &gt; '${dih.last_index_time}'"

                       parentDeltaQuery="select ITEM_ID, CATEGORY_ID from item_categorywhere CATEGORY_ID=${category.ID}"/>

           </entity>

       </entity>

   </document>

</dataConfig>

八、      参考

http://wiki.apache.org/solr/DataImportHandler

Solr官方文档：apache-solr-ref-guide-5.3.pdfP187~