Solr基础总结 - Solr DIH总结

1. DIH术语

• DataSource:定义Solr索引数据的来源，可以是数据库、http资源、文件。
• Entity:概念上，实体会被处理以生成包含多个字段的Document集合，它们会被传递给Solr进行索引。对一个RDBMS数据源，一个实体是一个视图或者表，他可能会被一或多个SQL语句处理生成一系列具有一或多个列（字段）的行（文档）。
• EntityProcessor:一个实体处理器会完成整个从数据源抽取内容、转换并将其添加到Solr创建索引的工作。可以用自定义实体处理器扩展或者替换Solr提供的默认处理器。
• Transformer:从实体中取得的每个字段的集都可以选择进行转换，这个过程可以修改字段、创建新字段或者从单个行生成多个行/文档。DIH中内置了多个转换器，它们可以执行像修改日期、比例HTML等功能。可以使用公共可用的接口来编写自定义转换器。

2. DIH命令

• abort:取消一个正在运行的dataimport操作。其url为http://<host>:<port>/solr/<collection_name>/dataimport?command=abort
• delta-import:用于增量导入和变更侦查。其命令url为http://<host>:<port>/solr/<collection_name>/dataimport?command=delta-import
• full-import:全量导入操作，他的命令URL为http://<host>:<port>/solr/<collection_name>/dataimport>command=full-import。该命令会立即返回，其操作会启动一个新线程且响应中的status属性应该显示为busy。该操作可能比较耗时。全量导入时对Solr的查询操作不会进行阻塞。当一个全量导入命令被执行时，他会在位于conf/dataimport.properties的配置文件中存储操作的起始时间。这个存储的时间戳在delta-import操作被执行时使用。
• reload-config:若配置有变更且你希望不用重启Solr就重新加载配置文件，可以运行此命令http://<host>:<port>/solr/<collection_name>/dataimport?command=reload-config
• status: 该命令返回创建、删除、查询运行、获取行数、状态等统计状态信息，其url为http://<host>:<port>/solr/<collection_name>/dataimport?command=status

3. Full Import命令参数

• clean:默认为true。表示在索引开始时是否清空索引。
• commit:默认为true。表示在操作后是否提交索引。
• debug:默认为false。以debug模式运行命令，用于交互式开发模式。
• entity:直接在配置文件的<document>标签的实体名称。使用它 可以选择性的执行一或多个实体。可以一次性传入多个entity参数来执行多个实体。若没有该参数，所有的实体都会被执行。
• optimize:默认为true。表示在操作后是否优化索引。

4.propertyWriter属性写入器

propertyWriter元素定义了在delta查询时使用哪种日期格式和地区。这是一个可选配置。直接在DIH配置文件的dataConfig元素下添加该元素。

<propertyWriter dateFormat="yyyy-MM-dd HH:mm:ss" type="SimplePropertiesWriter" directory="data" filename="my_dih.properties" locale="en_US"/>

• dateFomat:用于将日期转换为文本的java.text.SimpleDateFormat，默认为“yyyy-MM-dd HH:mm:ss”；
• type:用于指定propertyWriter的实现类。在非SolrCloud环境使用SimplePropertiesWriter，在SolrCloud环境使用ZKPropertiesWriter。若没有指定，他会根据SolrCloud环境是否启用自动适配合适的实现类；
• directory:仅用于SimplePropertiesWriter。表示属性文件目录。若没有指定，默认为“conf”；
• filename:仅用于SimplePropertiesWriter。属性文件的名称，若没有指定，默认为requestHandler的名称（根据solrconfig.xml中的定义，后缀.properties，即dataimport.properties);
  -locale:地区。若没有定义，则使用ROOT地区。它不许是语言_国家这种格式，如en_US,zh_CN;

5. DataSource数据源

• ContentStreamDataSource:它接收POST数据作为数据源。它可以在任何使用了DataSource<Reader>的EntityProcessor上使用。举个栗子
• FieldReaderDataSource:它可用于数据库字段包含了你希望使用XPathEntityProcessor处理XML内容时使用。你可以在配置中同时配置JDBC和FileReader数据源；

<dataConfig>
<dataSource name="a1" driver="org.hsqldb.jdbcDriver" .../>
<dataSource name="a2" type="FieldReaderDataSource"/>
<document>
<entity name="e1" dataSource="a1" processor="SqlEntityProcessor" pk="docid" query="select * from t1...">
<entity name="e2" dataSource="a2" processor="XPathEntityProcessor" dataField="e1.fieldToUseForXPath">
...
</entity>
</entity>
</document>
</dataConfig>

• JdbcDataSource:默认的数据源，一般配合SqlEntityProcessor一起使用；
• URLDataSource:该数据源长用于XPathEntityProcessor来从一个底层的file://或http://地址获取内容；

<dataConfig>
<dataSource name="a" type="URLDataSource" baseUrl="http://host:port/" encoding="UTF-8" connectionTimeoit="5000" readTimeout="10000"/>
...
</dataConfig>

1.baseUrl:指定路径名称的baseUrl；
2.connectionTimeout:指定连接超时时间的毫秒数；
3.encoding:响应头中使用的默认编码；
4.readTimeout:指定读操作的超时毫秒数；

• 自定义DataSource:可以继承org.apache.solr.handler.dataimport.DataSource类来实现自定义的数据源；

6. EntityProcessor实体处理器

实体处理器提取、转换数据并将其添加到Solr索引中。实体一般可以是数据库的视图或表。 每个处理器有自己的属性集合，任何实体都通用的属性如下。

• dataSource:数据源名称。可以定义多个数据源，使用该属性来给实体配置数据源名称。
• name：必须参数。用于表示实体的唯一名称。
• pk：实体主键。可选参数，尽在需要使用delta-import时需要。它和schema.xml中定义的uniqueKey没有关系，但可以是相同的。如果你要做delta-import时时不需的，且可以以${dataimporter.delta.<column-name>}引用字段名为主键。
• processor：若没有指定则默认值为SqlEntityProcessor。只有当dataSource不是RDBMS类型是需要指定此属性。
• onError：可选值有abort/skip/continue。默认值为abort。‘skip’表示跳过当前的Document不处理。‘continue’表示忽略异常继续处理。
• preImportDeleteQuery：在执行full-import命令之前，使用这个查询来清空索引数据，替代使用deleteByQuery(:)方式清空索引，一般用于子Document的Entity中。
• postImportDeleteQuery：与上面属性类似，唯一区别就是他在full-import完成后执行。
• rootEntity：默认Document元素在的Entity就是rootEntity，如果rootEntity设置为false，rootEntity下的Entity会被归入rootEntity，最终rootEntity
• transformer：可选的，Entity被映射成多个Row后可以配置一个或多个transformers来对每个row对数据进行清晰，筛选，转换。
• cacheImpl：可选的，用于指定缓存实现类，该类必须实现DIHCache。该cache用于缓存Entity对象。默认实现是SortedMapBackedCache。
• cacheKey：如果指定了cacheImpl属性，则需要指定需要缓存的Entity的name作为缓存主键。
• cacheLookup：如果指定了cacheImpl属性，需要使用Entity+name在cache中查找Entity实例。
  DIH提供Entity的缓存以避免对相同名称Entity的重复创建，充分利用缓存提升查询的性能。默认的SortedMapBackedCache是一个HashMap，其Key是row中的一个字段，而其value是具有相同key的一系列的row。
  举个栗子：每个manufacturer实体都使用id属性作为缓存键进行了缓存。对每个product实体的基于产品的manu属性的查询将直接查看缓存。当缓存在特性key上没有数据时，查询缓存并填充缓存。

<entity name="product" query="select description,sku,manu from product">
<entity name="manufacturer" query="select id,name from manufacturer" cacheKey="id" cahceLookup="product.manu" cacheImpl="SortedMapBackedCahce"/>
</entity>

1) SqlEntityProcessor:默认处理器，其关联的数据源应为一个JDBC URL。

• query：必须属性。指定一条SQL语句来返回表中的多条Rows；
• deltaQuery:增量导入时需要指定的SQL语句，此SQL语句会作为增量更新的一部分并返回只包含主键PK的结果集Rows，并且返回的主键PK可以通过${dataimporter.delta.<column-name>}变量在deltaImportQuery中被引用。
• parentDeltaQuery：增量导入时需要指定的SQL语句。
• deletedPkQuery：增量导入时需要指定的SQL语句。
• deltaImportQuery：增量导入时需要指定的SQL语句，如果这个SQL语句没有指定，那么DIH会尝试通过修改query属性来构造SQL语句，此时{dataimporter.delta.id}

2) XPathEntityProcessor:该处理器用于索引xml格式数据，其数据源通常是URLDataSource或FileDataSource。XpathEntityProcessor处理器还可以用于下面FileListEntityProcessor来从每个文件中生成索引文档。

• processor：必需属性且必需设置为XpathEntityProcessor。
• url：必需属性。值为一个http链接或者文件路径。
• stream：可选属性。对于文件下载或者大文件，需要将其设置为true。
• forEach：当你没有指定useSolrAddSchema属性时需要此属性。使用此属性来建立record处理循环，每个循环内可以使用Xpath表达式来提取想要的数据。
• xsl：可选属性，值可以为xsl文件的http链接或者文件系统路径。xsl文件转换功能可以作为xml文件的预处理。
• useSolrAddSchema：如果提供的xml内容是solr更新xml要求的规范格式，那么请将此属性设置为true。
• flatten：可选属性，如果设置为true，xml文件中的所有(该标签下所有子元素)标签都将被当做一个字符串提取出来存入一个域中。

实体中每个字段元素都可以有的属性如下。

• xpath：必需属性。使用xpath表达式为当前域从当前record中提取内容。只支持福分xpath表达式语法。
• commonField：可选属性。若设置为true，则表明当前域是一个通用域，xpath表达式解析出来的内容会被复制到其他document中。

3) MailEntityProcessor
MailEntiyProcessor使用Java Mail API基于IMAP协议索引email消息。MailEntityProcessor通过使用用户名密码来链接到特定的邮箱，获取每个消息的email头部，然后获取完整的email内容来构造一个索引文档（每个邮件对应一个索引文档）。

<dataConfig>
<document>
<entity processor="MailEntityProcessor" user=“email@gmail.com” password=“password” host="imap.gmail.com" protocol="imaps" 
fetchMailsSince="2009-09-20 00:00:00" batchSize="20" folders="inbox" processAttachement="false" name="sample_entity"/>
</document>
</dataConfig>

• processor：必需属性且属性值必需为MailEntityProcessor；
• user：必需属性，表示用于登录认证imap server的用户名；
• password：必须属性，表示用于登录认证imap server的密码；
• host：必须属性，表示imap server的主机名；
• protocol:必须属性，表示使用imap协议，可选imap，imaps，gimap，gimaps；
• fectchMailsSince：可选属性，指定日期或者事件之前的邮件将会被过滤掉不被导入，期望的日期格式为yyyy-MM-dd HH:mm:ss;
• folders：必需属性，表示从那些文件夹拉取邮件信息，比如inbox，多个值逗号分隔；
• recurse：可选属性，默认为 true，用于指示proessor石佛需要递归导入所有子文件夹下的邮件消息；
• include：可选属性，表示那些文件夹下的邮件消息需要被处理导入，支持正则表达式，多个值用逗号分隔；
• exclude：可选参数，与上面的属性类似，表示那些文件夹下的邮件消息需要排除掉不处理；
• processAttachement/processAttachements：可选参数，默认为true，表示使用tika来处理邮件里的附件；
• includeContent：可选参数，默认为true，是否需要对MessageBody进行处理，并构造成solr的document；

在执行full-import之后，MailEntityProcessor处理器会记录上一次导入的时间戳，以便随后的导入操作可以使用fetchMailsSince过滤器保证仅仅只拉取邮件服务器里最新的邮件。这个行为是自动发生的。
4) TikaEntityProcessor
TikaEntityProcessor使用Apache Tika来处理传入的文档。

<dataConfig>
<dataSource type="BinFileDataSource"/>
<document>
<entity name="tika-test" processor="TikaEntityProcessor" url="../contrib/extraction/src/test-files/extraction/solr-word.pdf" format="text">
<field column="Author" name="author" meta="true"/>
<field column="title" name="title" meta="true"/>
<field column="text" name="text"/>
</entity>
</document>
</dataConfig>

• dataSource:此属性用于定义数据源后续的配置中可以使用name属性引用该数据源。

Processor的可用的数据源类型如下：
1） BinURLDataSource：用于http资源或者磁盘文件；
2）BinContentStreamDataSource：用于通过文件流上传的文件；
3）BinFileDataSource：用于本地文件系统的文件；

• url:源文件的网络链接或硬盘路径，必须属性；
• htmlMapper:此属性用于控制Tika如何解析HTML。“default” mapper会剔除document的所有html元素，而“identity”mapper会保留所有html元素不做任何修饰。若需要指定当前属性，那么属性值必须是default或identity；若当前属性为指定，默认值为default。
• format:指定输出格式，可选值有text，xml，html，none。若未指定的话，默认值为text。如果只索引metadata元数据信息不索引document的body，那么format设置为none。
• parser:默认的parser类为org.apache.tika.parser.AutoDetectParser。若你需要指定为其他parser实现类或者自定义的parser实现类，请输入该类的完整包路径。
• fields:用于指定从输入的Document中提取的field列表已经他们是如何映射至solr的field的。若meta属性设置为true，那么field将直接从document的metadata元数据信息里获取，而不是从document body的主文本里解析。
• extractEmbedded:若设为true即表示命令TikaEntityProcessor提取内嵌的Document或附件，否则直接忽略。
• onError:当发生异常时，默认TikaEntityProcessor会停止Document处理操作，当操作失败时，TikaEntityProcessor会跳过该Document不做处理。

5) FileListEntityProcessor
该处理器基本就是一个封装器， 他设计用于生成一系列满足有属性指定条件的文件，然后这些文件可以被传递给另一个处理器，不如XPathEntityProcessor。该处理器的实体信息将内嵌在FileListEntity实体中。它会生成四个隐式的字段：fileAbsolutePath,fileSize,fileLastModified,fileName,它们可用在内嵌的处理器中，该处理器没有使用数据源，该处理器特有的属性如下。

• fileName：必需属性。使用一个正则表达式标示所有匹配的文件。
• basedir：必需属性。设置基准目录（绝对路径）。
• recursive：是否递归搜索目录下的文件，默认为false。
• excludes：一个正则表达式用来表示不被包含进来的文件。
• newerThan：表示一个yyyy-MM-dd HH:mm:ss格式的日期时间或者NOW-2YEARS这种表达式表示的日期，只有在指定日期之前的文件才会被包含。
• olderThan：与newerThan类似，olderThan表示指定日期之后的文件会被包含。
• rootEntity：这个属性应该设置为false，这样可以确保每一行（即文件路径）被当作一个文档。
• dataSource：必须设置为null。

<dataConfig>
<dataSource type="FileDataSource"/>
<document>
<entity name="f" processor="FileListEntityProcessor" fileName=".*xml" newerThan="NOW-30DAYS" recursive="true" rootEntity="false" dagaSource="null" basedir="/my/document/directory">
<entity name="nested" processor="XPathEntityProcessor" forEach="/rootelement" url="${f.fileAbsolutePath}">
<field column="name" xpath="/rootelement/name"/>
<field column="number" xpath="/rootelement/number"/>
</entity>
</entity>
</document>
</dataConfig>

6) LineEntityProcessor
LineEntityProcessor会一次助航读取数据源中的内容，并对每个读取到的行返回名为rawLine的字段，其内容不会被解析，但可以添加转换起来操作rawLine字段的数据，或者创建其他额外的字段。

• url：一个必需的属性，指定输入文件的位置且需要兼容配置的数据源。如果这个值是相对路径且你使用的是FileDataSource或URLDataSouce，那么此属性会被判定为相对路径。
• acceptLineRegex：可选属性，不匹配指定正则表达式的行将被丢弃；
• omitLineRegex：可选属性，匹配指定正则表达式的行将会被忽略不处理；
  7) PlainTextEntityProcessor
  PlainTextEntityProcessor读取数据源中的所有内容作为单个隐式字段plainText，其内容不会被解析；然而你可以添加转换器来操作plainText字段的数据，或创建其他额外的字段。使用PlainTextEntityProcessor处理器请确保数据源是DataSource<Reader>CFileDataSource,URLDataSource类型的。

<entity processor="PlainTextEntityProcessor" name="x" url="http://abc.com/a.txt" dataSource="data-source-name">
<field column="plainText" name="text"/>
</entity>

8) 如何自定义EntityProcessor
当solr内置提供的这些EntityProcessor仍然无法满足你的需求时，你可以通过继承EntityProcessor抽象类或者继承EntityProcessorBase类来实现中自定义EntityProcessor。