用 DataImportHandler 上传结构型数据存储的数据

很多搜索应用都将其待索引内容存储在结构化数据存储中，如关系型数据库。 数据导入处理器(DIH) 提供了从一个数据存储中导入内容并索引它的机制。 除了关系型数据库， DIH 还可以索引来自像 RSS 和 ATOM 种子这样基于 HTTP 的数据源的内容、 e-mail 仓库以及有一个 XPath 处理其可用于生成字段的结构化的 XML。

example/example-DIH 目录包含了多种数据导入处理器特性的集合。 要运行 dih 示例：

bin/solr -e dih

更多数据导入处理器的信息，查看 https://wiki.apache.org/solr/DataImportHandler 。

本节包含的内容有：

• 概念和术语
• 配置
• 数据导入处理器命令
• 属性 Writer
• 数据源
• 实体处理器
• 转换器
• 数据导入处理器的特殊命令

概念和术语

数据导入处理器的描述以特殊的方式使用了多个类似的词，如实体(entity)和处理器(processor)， 其解释如下表。

配置

配置 solrconfig.xml

数据导入处理器需注册在 solrconfig.xml 中。如：

<requestHandler name="/dataimport"
  class="org.apache.solr.handler.dataimport.DataImportHandler">
  <lst name="defaults">
    <str name="config">/path/to/my/DIHconfigfile.xml</str>
  </lst>
</requestHandler>

其唯一必需的参数是 config 参数，它指定了 DIH 配置文件的位置。 DIH 配置文件中包含了数据源规格、如何获取数据、获取什么数据以及如何处理 以生成可被发送给索引的 Solr 文档。

你可以有多个 DIH 配置文件。 每个文件需要在 solrconfig.xml 中有独立的定义，指定其文件路径。

配置 DIH 配置文件

一个 dih 示例中基于 db 集合的带注释的配置文件如下 (example/example-DIH/solr/db/conf/db-data-config.xml)。 这个模式中，它从一个定义的简单的产品的数据库的四个表中提取字段。 这里更多参数和选项的信息会在后续小节中阐述。

<dataConfig>
<!-- The first element is the dataSource, in this case an HSQLDB database.
     The path to the JDBC driver and the JDBC URL and login credentials are all
specified here.
     Other permissible attributes include whether or not to autocommit to Solr,the
batchsize
     used in the JDBC connection, a 'readOnly' flag -->
  <dataSource driver="org.hsqldb.jdbcDriver"
    url="jdbc:hsqldb:./example-DIH/hsqldb/ex" user="sa" />
<!-- a 'document' element follows, containing multiple 'entity' elements.
     Note that 'entity' elements can be nested, and this allows the entity
     relationships in the sample database to be mirrored here, so that we can
     generate a denormalized Solr record which may include multiple features
     for one item, for instance -->
  <document>
<!-- The possible attributes for the entity element are described below.
     Entity elements may contain one or more 'field' elements, which map
     the data source field names to Solr fields, and optionally specify
     per-field transformations -->
<!-- this entity is the 'root' entity. -->
    <entity name="item" query="select * from item"
      deltaQuery="select id from item where last_modified > '${dataimporter.last_index_time}'">
      <field column="NAME" name="name" />
<!-- This entity is nested and reflects the one-to-many relationship between an item
and its multiple features.
     Note the use of variables; ${item.ID} is the value of the column 'ID' for the
current item
     ('item' referring to the entity name) -->
      <entity name="feature"
        query="select DESCRIPTION from FEATURE where ITEM_ID='${item.ID}'"
        deltaQuery="select ITEM_ID from FEATURE where last_modified > '${dataimporter.last_index_time}'"
        parentDeltaQuery="select ID from item where ID=${feature.ITEM_ID}">
        <field name="features" column="DESCRIPTION" />
      </entity>
      <entity name="item_category"
        query="select CATEGORY_ID from item_category where ITEM_ID='${item.ID}'"
        deltaQuery="select ITEM_ID, CATEGORY_ID from item_category where last_modified > '${dataimporter.last_index_time}'"
        parentDeltaQuery="select ID from item where ID=${item_category.ITEM_ID}">
        <entity name="category"
        query="select DESCRIPTION from category where ID = '${item_category.CATEGORY_ID}'"
        deltaQuery="select ID from category where last_modified > '${dataimporter.last_index_time}'"
        parentDeltaQuery="select ITEM_ID, CATEGORY_ID from item_category where CATEGORY_ID=${category.ID}">
          <field column="description" name="cat" />
        </entity>
      </entity>
    </entity>
  </document>
</dataConfig>

数据源也可以在 solrconfig.xml 中指定。 这些必须在 solrconfig.xml 中该处理器的默认部分中指定。 然而它们会在配置被加载时才会被解析。

整个配置本身可以在请求参数中一 dataconfig 参数传入，而不是使用一个文件。 当配置出现错误时，其错误消息会以 XML 格式返回。

还支持一个 reload-config 命令，它在验证新配置文件或者你希望指定文件并加载它而不希望它在导入 时重新加载等情况下会很有用。 若配置中存在 xml 错误，会返回一个友好的 XML 格式的消息。 然后你可以修复问题，重新 reload-config。

你也可以查看 Solr Admin UI 中的 DIH 配置，那里有一个导入内容的接口。

数据导入处理器命令

DIH 命令通过 HTTP 请求发送给 Solr。下面是支持的操作：

full-import 命令的参数

full-import 命令接收以下参数：

属性 Writer

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

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

可用的参数有：

数据源

数据源指定了数据的来源及其类型。 有时会使人迷惑的是，某些数据源可以在相关的实体处理器内部配置。 数据源也可以在 solrconfig.xml 中指定，它在你有多个环境(如开发、QA和产品环境)仅有数据源地址不同时有用。

你可以通过编写扩展了 org.apache.solr.handler.dataimport.DataSource 的类来创建自定义数据源。

数据源定义的必需属性为其名称和类型。名称标识了实体元素对应哪个数据源。

可用的数据源类型如下：

ContentStreamDataSource

它接收 POST 数据作为数据源。它可以在任何使用了 DataSource<Reader> 的 EntityProcessor 上使用。

FieldReaderDataSource

它可用于数据库字段包含了你希望使用 XPathEntityProcessor 来处理的 XML 内容时使用。 你可以在配置中同时设置 JDBC 和 FileReader 数据源，如下：

<dataSource name="a1" driver="org.hsqldb.jdbcDriver" ... />
<dataSource name="a2" type=FieldReaderDataSource" />
<document>
<!-- processor for database -->
  <entity name ="e1" dataSource="a1" processor="SqlEntityProcessor" pk="docid"
    query="select * from t1 ...">
    <!-- nested XpathEntity; the field in the parent which is to be used for
         Xpath is set in the "datafield" attribute in place of the "url" attribute
    -->
    <entity name="e2" dataSource="a2" processor="XPathEntityProcessor"
      dataField="e1.fieldToUseForXPath">
      <!-- Xpath configuration follows -->
      ...
    </entity>
  </entity>

FieldReaderDataSource 可以接收一个 encoding 参数，它默认为 “UTF-8”。 它必须是 语言-国家 格式，如 en-US。

FileDataSource

它可以像 URLDataSource 一样使用，但它用于从硬盘中的文件获取内容。 它和 URLDataSource 的区别只在于在访问硬盘文件时路径名称是如何指定的。

该数据源接收以下可选属性。

JdbcDataSource

默认的数据源。连同 SqlEntityProcessor 使用。 查看 FieldReaderDataSource 小节的配置示例。

URLDataSource

该数据源常用于 XPathEntityProcessor 来从一个底层的 file:// 或 http:// 地址获取内容。 如下例：

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

URLDataSource 类型接收以下可选参数：

实体处理器

实体处理器提取、转换数据并将其添加到 Solr 索引中。 实体的例子包括数据存储中的视图或表。

每个处理器有自己的属性集合，它们会在其自身的小节中描述。 除此之外还有一些对任何实体都通用的属性：

DIH 提供实体的缓存以避免对相同名称实体的重复查看。 默认的 SortedMapBackedCache 是一个 HashMap 其键是行中的一个字段而其值是具有相同键的一系列行。

下例中，每个 manufacturer 实体都使用 id 属性作为缓存键进行了缓存。 对每个 product 实体的基于产品的 manu 属性的查询将查看缓存。 当缓存在特定键上没有数据时，查询会运行并填充缓存。

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

SqlEntityProcessor

SqlEntityProcessor 是默认的处理器。其关联的 数据源 应该为一个 JDBC URL。

该处理器特有的实体属性有：

XPathEntityProcessor

该处理器用于索引 XML 格式的数据。其数据源通常是 URLDataSource 或 FileDataSource。 Xpath 也可用于下面的 FileListEntityProcessor, 来从每个文件中那个生成文档。

该处理器特有的实体属性有：

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

下面是 dih 示例中 rss 集合的配置(example/example-DIH/solr/rss/conf/rss-data-config.xml):

<!-- slashdot RSS Feed --->
<dataConfig>
  <dataSource type="HttpDataSource" />
  <document>
    <entity name="slashdot"
      pk="link"
      url="http://rss.slashdot.org/Slashdot/slashdot"
      processor="XPathEntityProcessor"
<!-- forEach sets up a processing loop ; here there are two expressions-->
      forEach="/RDF/channel | /RDF/item"
      transformer="DateFormatTransformer">
      <field column="source" xpath="/RDF/channel/title" commonField="true" />
      <field column="source-link" xpath="/RDF/channel/link" commonField="true"/>
      <field column="subject" xpath="/RDF/channel/subject" commonField="true" />
      <field column="title" xpath="/RDF/item/title" />
      <field column="link" xpath="/RDF/item/link" />
      <field column="description" xpath="/RDF/item/description" />
      <field column="creator" xpath="/RDF/item/creator" />
      <field column="item-subject" xpath="/RDF/item/subject" />
      <field column="date" xpath="/RDF/item/date"
        dateTimeFormat="yyyy-MM-dd'T'hh:mm:ss" />
      <field column="slash-department" xpath="/RDF/item/department" />
      <field column="slash-section" xpath="/RDF/item/section" />
      <field column="slash-comments" xpath="/RDF/item/comments" />
    </entity>
  </document>
</dataConfig>

MailEntityProcessor

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

下面是 dih 示例中 mail 集合的配置(example/example-DIH/solr/mail/conf/mail-data-config.xml):

<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>

MailEntityProcessor 独有的实体属性有：

仅导入新邮件

After running a full import, the MailEntityProcessor keeps track of the timestamp of the previous import so that subsequent imports can use the fetchMailsSince filter to only pull new messages from the mail server. This occurs automatically using the Data Import Handler dataimport.properties file (stored in conf). For instance, if you set fetchMailsSince=2014-08-22 00:00:00 in your mail-data-config.xml, then all mail messages that occur after this date will be imported on the first run of the importer. Subsequent imports will use the date of the previous import as the fetchMailsSince filter, so that only new emails since the last import are indexed each time.

GMail 扩展

When connecting to a GMail account, you can improve the efficiency of the MailEntityProcessor by setting the protocol to gimap or gimaps . This allows the processor to send the fetchMailsSince filter to the GMail server to have the date filter applied on the server, which means the processor only receives new messages from the server. However, GMail only supports date granularity, so the server-side filter may return previously seen messages if run more than once a day.

TikaEntityProcessor

TikaEntityProcessor 使用 Apache Tika 来处理传入的文档。 它和 用带 Apache Tika 的 SolrCell 上传数据 类似， 但使用的是 DataImportHandler 选项。

下面是 dih 示例中 tika 集合的配置(example/example-DIH/solr/tika/conf/tika-data-config.xml):

<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>

该处理器特有的实体属性有：

FileListEntityProcessor

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

该处理器特有的属性有：

下面的示例组合了 FileListEntityProcessor 和另一个会针对每个找到的文件生成一系列字段的处理器。

<dataConfig>
  <dataSource type="FileDataSource"/>
  <document>
    <!-- this outer processor generates a list of files satisfying the conditions
         specified in the attributes -->
    <entity name="f" processor="FileListEntityProcessor"
      fileName=".*xml"
      newerThan="'NOW-30DAYS'"
      recursive="true"
      rootEntity="false"
      dataSource="null"
      baseDir="/my/document/directory">
      <!-- this processor extracts content using Xpath from each file found -->
      <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>

LineEntityProcessor

LineEntityProcessor 会一行一行地读取数据源中的内容，并对每个读取的行返回名为 rawLine 的字段。 其内容不会被解析；然而你可以添加转换器来操作 rawLine 字段的数据，或创建其它额外的字段。

读取的行可由两个属性 acceptLineRegex 和 omitLineRegex 上指定的正则表达式进行过滤。 下表描述了 LineEntityProcessor 的属性：

例如：

<entity name="jc"
  processor="LineEntityProcessor"
  acceptLineRegex="^.*\.xml$"
  omitLineRegex="/obsolete"
  url="file:///Volumes/ts/files.lis"
  rootEntity="false"
  dataSource="myURIreader1"
  transformer="RegexTransformer,DateFormatTransformer">
  ...

While there are use cases where you might need to create a Solr document for each line read from a file, it is expected that in most cases that the lines read by this processor will consist of a pathname, which in turn will be consumed by another EntityProcessor, such as XPathEntityProcessor.

PlainTextEntityProcessor

PlainTextEntityProcessor 读取数据源中的所有内容为单个隐式字段 plainText。 其内容不会被解析；然而你可以添加转换器来操作 plainText 字段的数据，或创建其它额外的字段。

例如：

<entity processor="PlainTextEntityProcessor" name="x" url="http://abc.com/a.txt"
  dataSource="data-source-name">
  <!-- copies the text to a field called 'text' in Solr-->
  <field column="plainText" name="text"/>
</entity>

确保数据源是 DataSource<Reader>(FileDataSource、URLDataSource) 类型的。

转换器

转换器可以操作有实体返回的文档中字段。一个转换器可以创建新的字段或者修改已有的字段。 你需要通过在 <entity> 元素上添加一个包含逗号分割的属性来告诉实体你的导入操作将使用哪些转换器。

<entity name="abcde" transformer="org.apache.solr....,my.own.transformer,..." />

特定的转换规则随后被添加作为 <field> 元素的属性，如下所示。 多个转换器以其在 transformer 属性所指定的顺序被应用。

数据导入处理器包含多个内置的转换器。 你也可以按 相关 Solr Wiki 所述 编写自定义的转换器。ScriptTransformer (下文会描述) 也提供了编写你自己的转换器的替代方法。

Solr 包含以下内置转换器：

这些转换器会在下文描述。

ClobTransformer

你可以使用 ClobTransformer 从数据库中的 CLOB 创建一个字符串。 CLOB 是字符大对象：字符数据的集合，通常存储在一个由数据库指向的独立的位置。 详见 http://en.wikipedia.org/wiki/Character_large_object。 下面是调用 ClobTransformer 的例子：

<entity name="e" transformer="ClobTransformer" ...>
  <field column="hugeTextField" clob="true" />
  ...
</entity>

ClobTransformer 接收这些参数：

DateFormatTransformer

该转换器将日期从一种格式转换为另一种格式。这在像你需要将一个字段从完整的日期/时间格式 转换成低精度的日期格式时很有用，可用于 faceting。

DateFormatTransformer 仅应用于带有 dateTimeFormat 属性的字段。 其他字段不会修改。

该转换器能识别以下属性：

下面的代码会将日期截取为月份 “2007-JUL”:

<entity name="en" pk="id" transformer="DateFormatTransformer" ... >
  ...
  <field column="date" sourceColName="fulldate" dateTimeFormat="yyyy-MMM"/>
</entity>

HTMLStripTransformer

你可以使用该转换器来剥离一个字段的 HTML。如：

<entity name="e" transformer="HTMLStripTransformer" ... >
  <field column="htmlText" stripHTML="true" />
  ...
</entity>

该转换器只有一个属性，stripHTML,它是一个布尔值，表示 HTMLStripTransformer 是否应该处理该字段。

LogTransformer

你可以使用该转换器将数据记录日志到控制台或者日志文件。如：

<entity ...
  transformer="LogTransformer"
  logTemplate="The name is ${e.name}" logLevel="debug">
   ....
</entity>

不像其它转换器，LogTransformer 不是应用于任何字段上的，因此这些属性应用在实体本身。

NumberFormatTransformer

该转换器从一个字符串中解析成一个数字，将其转换成特殊格式，并可选使用一个不同的地区。

NumberFormatTransformer 只会应用到具有 formatStyle 属性的字段。

该转换器识别以下属性：

如：

<entity name="en" pk="id" transformer="NumberFormatTransformer" ...>
  ...
  <!-- treat this field as UK pounds -->
  <field name="price_uk" column="price" formatStyle="currency" locale="en-UK"/>
</entity>

RegexTransformer

RegexTransformer 使用正则表达式来帮助提取或操作字段(来源)中的值。 其实际类名为 org.apache.solr.handler.dataimport.RegexTransformer， 但因为它属于默认包，因此包名可以忽略。

下表描述了正则转换器所识别的属性。

下面是配置正则转换器的示例：

<entity name="foo" transformer="RegexTransformer"
  query="select full_name, emailids from foo">
  <field column="full_name"/>
  <field column="firstName" regex="Mr(\w*)\b.*" sourceColName="full_name"/>
  <field column="lastName" regex="Mr.*?\b(\w*)" sourceColName="full_name"/>
  <!-- another way of doing the same -->
  <field column="fullName" regex="Mr(\w*)\b(.*)" groupNames="firstName,lastName"/>
  <field column="mailId" splitBy="," sourceColName="emailids"/>
</entity>

本例中，regex 和 sourceColName 是由转换器所使用的特定属性。 该转换器从结果集中读取 full_name 字段并将其转换为两个新的目标字段 firstName 和 lastName。 尽管查询仅返回一个列 full_name，在结果集中 Solr 文档得到了两个额外的”派生”字段 firstName 和 lastName。 这些新字段仅在正则表达式匹配时创建。

表中的 emailids 字段可能是一个逗号分割的值。 它最终会生成一或多个 email IDs，且我们假设 mailId 在 Solr 中是多值字段。

注意这个转换器既可以将一个字符串根据 splitBy 模式分割为多个分词， 也可以用 replaceWith 做字符串替换，还可以给一组具有某个模式的分组赋予一系列 groupNames。 它根据上面属性中的 splitBy、replaceWith以及groupNames 来决定具体应该怎么做， 这三个属性是按照顺序查询的。 第一个找到的会被响应，其他非相关的属性会被忽略。

ScriptTransformer

脚本转换器允许以任何 Java 支持的脚本语言来书写任意的转换函数， 如 Javascript、JRuby、Jython、Groovy 或 BeanShell。 Javascript 已经集成进了 Java 7 中，其他语言你需要自己集成。

每个函数接收一个行变量(对应于 Java 的 Map<String,Object>，因此允许 get、put、remove 操作)。 这样你可以修改已有字段的值或者添加新字段。函数的返回值及被返回的对象。

脚本需要作为 DIH 配置文件的顶级元素插入，且会对每一个行调用一次。

下面是一个简单示例：

<dataconfig>
  <!-- simple script to generate a new row, converting a temperature from Fahrenheit
       to Centigrade -->
  <script><![CDATA[
    function f2c(row) {
      var tempf, tempc;
      tempf = row.get('temp_f');
      if (tempf != null) {
        tempc = (tempf - 32.0)*5.0/9.0;
        row.put('temp_c', temp_c);
      }
      return row;
    }
  ]]></script>
  <document>
    <!-- the function is specified as an entity attribute -->
    <entity name="e1" pk="id" transformer="script:f2c" query="select * from X">
      ....
    </entity>
  </document>
</dataConfig>

TemplateTransformer

你可以使用模板转换器来构造或修改一个字段值，或许是使用其它字段的值。 你可以在模板中插入额外的文本。

<entity name="en" pk="id" transformer="TemplateTransformer" ...>
  ...
  <!-- generate a full address from fields containing the component parts -->
  <field column="full_address" template="${en.street},${en.city},${en.zip}" />
</entity>

数据导入处理器的特殊命令

你可以通过添加下面列出的任何变量给由任何组件所返回的行上来给 DIH 传递特殊命令：