Using RNI with Solr

To index and search documents with RNI in a Solr application, you must add JARs to the Solr classpath, add the name fields to the schema.xml, and modify the solrconfig.xml.

 <!--Adjust the sharedlib setting if you move bt-rni-solr9x-plugins.jar to a different location.-->  
<str name="sharedLib">${bt.root}/rlpnc/data/rnm/sample/solr_shared_lib</str>

<fieldType name="bt_rni_name" class="com.basistech.rni.solr.NameField" needNameStore="true"/>

<fieldType name="bt_rni_addr" class="com.basistech.rni.solr.AddressField" needAddressStore="true"/>

<fieldType name="bt_rni_date" class="com.basistech.rni.solr.DateField" needDateStore="true"/>

<field name="primaryName" type="bt_rni_name" indexed="true" stored="true" multiValued="false"/>
<field name="aka" type="bt_rni_name" indexed="true" stored="true" multiValued="true"/>
<field name="residence" type="bt_rni_addr" indexed="true" stored="true" multiValued="false"/>
<field name="dateOfBirth" type="bt_rni_date" indexed="true" stored="true" multiValued="false"/>

<queryParser name="rniRerank" class="com.basistech.rni.solr.RNIReRankQParserPlugin"/>
<queryParser name="rniAddrRerank" class="com.basistech.rni.solr.RNIAddressReRankQParserPlugin"/>
<queryParser name="rniDateRerank" class="com.basistech.rni.solr.RNIDateReRankQParserPlugin"/>
<valueSourceParser name="rniMatch" class="com.basistech.rni.solr.NameMatchValueSourceParser"/>
<valueSourceParser name="rniAddrMatch" class="com.basistech.rni.solr.AddressMatchValueSourceParser"/>
<valueSourceParser name="rniDateMatch" class="com.basistech.rni.solr.DateMatchValueSourceParser"/>

<updateRequestProcessorChain name="RNIName">
  <processor class="com.basistech.rni.solr.MultiValueNameUpdateRequestProcessorFactory"/>
  <processor class="solr.LogUpdateProcessorFactory"/>
  <processor class="solr.RunUpdateProcessorFactory"/>
</updateRequestProcessorChain>

<requestHandler name="/update" 
      class="solr.UpdateRequestHandler">
  <lst name="defaults">
    <str name="update.chain">RNIName</str>
  </lst>
</requestHandler>

<updateRequestProcessorChain name="RNIAddr">
 <!--Custom processor required when using multivalued address fields-->
  <processor class="com.basistech.rni.solr.MultiValueAddressUpdateRequestProcessorFactory"/>
  <processor class="solr.LogUpdateProcessorFactory"/>
  <processor class="solr.RunUpdateProcessorFactory"/>
</updateRequestProcessorChain>

<requestHandler name="/update"
      class="solr.UpdateRequestHandler">
 <lst name="defaults">
   <str name="update.chain">RNIAddr</str>
 </lst>
</requestHandler>

<updateRequestProcessorChain name="RNIDate">
  <!--Custom processor required when using multivalued date fields-->
  <processor class="com.basistech.rni.solr.MultiValueDateUpdateRequestProcessorFactory"/>
  <processor class="solr.LogUpdateProcessorFactory"/>
  <processor class="solr.RunUpdateProcessorFactory"/>
</updateRequestProcessorChain>

<requestHandler name="/update"
      class="solr.UpdateRequestHandler">
 <lst name="defaults">
  <str name="update.chain">RNIDate</str>
 </lst>
</requestHandler>

<updateRequestProcessorChain name="RNI">
  <!--Custom processor required when using multivalued name fields-->
  <processor class="com.basistech.rni.solr.MultiValueNameUpdateRequestProcessorFactory"/>
  <!--Custom processor required when using multivalued address fields-->
  <processor   class="com.basistech.rni.solr.MultiValueAddressUpdateRequestProcessorFactory"/>
  <!--Custom processor required when using multivalued date fields-->
  <processor class="com.basistech.rni.solr.MultiValueDateUpdateRequestProcessorFactory"/>
  <processor class="solr.LogUpdateProcessorFactory"/>
  <processor class="solr.RunUpdateProcessorFactory"/>
</updateRequestProcessorChain>

<requestHandler name="/update"
      class="solr.UpdateRequestHandler">
 <lst name="defaults">
  <str name="update.chain">RNI</str>
 </lst>
</requestHandler>

bin/solr -a "-Dbt.root=$BT_ROOT -Djava.security.manager=allow" -m 2g

bin/solr -a "-Dbt.root=$BT_ROOT -XX:+IgnoreUnrecognizedVMOptions" -m 2g

It is often necessary to query on other fields besides names fields, such as date of birth and address. The plugin enables the seamless integration of RNI into your Solr queries. To apply Boolean logic to queries, combine multiple fields with Boolean operators. The plugin supports all Boolean operators supported by the standard Lucene query parser (AND, OR, NOT, + , -). The OR operator is the default conjunction operator; if there is no Boolean operator between two terms (fields), the OR operator is used.

Example of a query with name and date fields:

primaryName:"Chuy Lopez A Deyas~entityType=PERSON" AND dateOfBirth:"1960-09-30"

Example of a query including an address field:

primaryName:"Chuy Lopez A Deyas~entityType=PERSON" AND residence:"road<Avenida Const. Pedro L Zavala 1957>
 house<Colonia Libertad>city<Culiacan>region<Sinaloa>postalCode<80180>country<Mexico>~fielded=true"

You can include name fields and other fields in your base query in conjunction with an RNI Solr reRank query and a custom valueSourceParser. The base query identifies candidate documents. The reRank query sends the top N candidates to the rniMatch valueSourceParser for pairwise matching. You can combine multiple fields in function queries which enable you to generate a relevancy score of those fields. The plugin supports all the functions available for function queries in Solr.

In a pairwise name match we return the maximum score of querying for primaryName and contactName:

&rq={!rniRerank reRankQuery=$rrq reRankMode=replace reRankWeight=1.0}
  &rrq={!func}max(rniMatch(primaryName, "Chuy Lopez A Deyas"), rniMatch(contactName, "Chuy Lopez"))

In a pairwise address match we return the maximum score of querying for primaryAddress and residence:

&rq={!rniAddrRerank reRankQuery=$rrq reRankMode=replace reRankWeight=1.0}
  &rrq={!func}max(rniAddrMatch(primaryAddress, "road<Calle Lago Cuitzeo 1394>house<Colonia Las Quintas>
 city<Culiacan>region<Sinaloa>postalCode<80060>country<Mexico>~fielded=true"),
rniAddrMatch(residence, "road<Avenida Const. Pedro L Zavala 1957>house<Colonia Libertad>
 city<Culiacan>region<Sinaloa>postalCode<80180>country<Mexico>~fielded=true"))

In a pairwise date match we return the maximum score of querying for dateOfBirth and dob:

&rq={!rniDateRerank reRankQuery=$rrq reRankMode=replace reRankWeight=1.0}
&rrq={!func}max(rniDateMatch(dateOfBirth, "01/07/42~format=dd/MM/yy"), rniDateMatch(dob, "1/7/1940"))

You can combine the score of multiple RNI fields of the same type where each field can be given a weight to reflect its importance in the overall matching logic.

For example, in a pairwise name match we can return the combined score of querying for aka and primaryName where aka has a weight of 0.3 and the remaining 0.7 is assigned to primaryName field:

&rq={!rniRerank reRankQuery=$rrq reRankMode=replace reRankWeight=1.0} 
  &rrq={!func}sum(linear(rniMatch(aka, "Jesus Alfonso Diaz"), 0.3, 0),
  linear(rniMatch(primaryName, "Jesus Diaz"), 0.7, 0))

q=primaryName:"Lopez Diaz"
fl=primaryName,aka,score
&rq={!rniRerank reRankQuery=$rrq reRankDocs=200 reRankWeight=3}
&rrq={!func}rniMatch(primaryName, "Lopez Diaz")

This example walks you through the steps for using the Solr 9 Admin example to perform queries.

Solr Admin displays a response.

For this query, Solr returns the appropriate Diaz document.

{
{
  "responseHeader": {
    "status": 0,
    "QTime": 387,
    "params": {
      "rrq": "{!func}rniMatch(name, \"Chuy Lopez A Deyas~entityType=PERSON\\")",
      "q": "name:\"Chuy Lopez A Deyas~entityType=PERSON\" AND dateOfBirth:[1960-09-30T00:00:00Z TO *]",
      "fl": "name,aka,dateOfBirth,address,nationality,score",  
      "_": "1631115490163",   
      "rq": "{!rniRerank reRankQuery=$rrq reRankMode=replace reRankWeight=1.0} "
    }
  },
  "response": {
    "numFound": 145,
    "start": 0,
    "maxScore":0.6820811,
    "numFoundExact":true,
    "docs": [
      {
        "name": "Jesus Alfonso LOPEZ DIAZ~uid=10353,entityType=PERSON",
        "address": [
          "c/o ESTABLO PUERTO RICO S.A. DE C.V.\nCuliacan Sinaloa\nMexico",
          "Avenida Const. Pedro L Zavala 1957\nColonia Libertad\nCuliacan Sinaloa 80180\nMexico"
        ],
        "nationality": [
          "Mexico"
        ],
        "dateOfBirth": [
          "1962-09-30T00:00:00Z"
        ],
        "score": 0.6820811
      },
      ...
    ]
  }
}

You can use the org.apache.solr.client.solrj API to integrate the RNI Solr plugin into a Solr application.

The basic steps are as follows:

The following sample code snippets use these imports:

import org.apache.solr.client.solrj.SolrQuery;
import org.apache.solr.client.solrj.embedded.EmbeddedSolrServer;
import org.apache.solr.client.solrj.response.QueryResponse;
import org.apache.solr.common.SolrDocument;
import org.apache.solr.common.SolrInputDocument;
import org.apache.solr.common.params.CommonParams;
import org.apache.solr.core.CoreContainer;

Setup:

// Set the bt.root property to point to the RNI installation
String btRoot = args[0];
System.setProperty("bt.root", btRoot);
// Set solr.solr.home to the parent of a collection1/conf directory that contains
// a modified schema.xml and solrconfig.xml.
String solrHome = btRoot + "/rlpnc/data/rnm/sample/solr8x_home";
System.setProperty("solr.solr.home", solrHome);
CoreContainer coreContainer = new CoreContainer(solrHome);
coreContainer.load();
// For simplicity, use an embedded SolrServer rather than an HTTPSolrServer.
EmbeddedSolrServer server = new EmbeddedSolrServer(coreContainer, "");

Add a Solr document with fields of interest, including name fields:

SolrInputDocument doc = new SolrInputDocument();
// Primary name field
doc.addField("primaryName", "Midiam Patricia ZAMBADA NIEBLA");
// Multivalued also-known-as name field
doc.addField("aka", "Midian Patricia ZAMBADA NIEBLA");
doc.addField("aka", "Miriam ZAMBADA NIEBLA");
doc.addField("aka", "Midian Patricia LOPEZ LANDEY");
doc.addField("id", "3");
// Entity id field.
doc.addField("uid", "10358");
// Date field
doc.addField("dob", "1971-03-04");
// Address field
doc.addField("address", "road<Calle Lago Cuitzeo 1394>house<Colonia Las Quintas>"
             + "city<Culiacan>region<Sinaloa>postalCode<80060>"
             + "country<Mexico>~fielded=true");
doc.addField("nationality", "Mexico");

// Add the document to the index.
server.add(createInputDoc());

Commit updates:

// When you have completed updates, commit the updates.
server.commit();

Define and run a query against name and other fields, using RNI pairwise matching to rerank the documents returned:

// Define a query that combines name fields and other fields, and uses RNI
// pairwise matching to rerank the documents returned.
String queryName = "Chuy A Lopez";
SolrQuery solrQuery = new SolrQuery("aka" + ":\"" + queryName +
 "\" AND dob:[1960-09-30T00:00:00Z TO *]");
// Set the rerank query parser parameters
solrQuery.set(CommonParams.RQ,
 "{!rniRerank reRankQuery=$rrq reRankDocs=100 reRankWeight=1}");
// Create a rerank query that uses the RNI pairwise matching function
solrQuery.set("rrq", "{!func}rniMatch(" + "aka" + ", \"" + queryName + "\")");
// Set which fields to include in the results
solrQuery.setFields("uid", "primaryName", "address", "dob", "score");
QueryResponse qResults = server.query(solrQuery);
//QueryResponse qResults = server.query(createQuery());

Define and run a query against name, address, and other fields, using RNI pairwise matching to rerank the documents returned:

// Define a query that combines name, address and other fields, and uses RNI
// pairwise matching to rerank the documents returned.
String queryName = "Chuy A Lopez";
String queryAddress = "road<Avenida Const. Pedro L Zavala 1957>house<Colonia Libertad>"
           + "city<Culiacan>country<Mexico>~fielded=true";
SolrQuery solrQuery = new SolrQuery("aka" + ":\"" + queryName +
                    "\" AND dob:\"1960-09-30\"");
// Set the rerank query parser parameters
solrQuery.set(CommonParams.RQ,
        "{!rniAddrRerank reRankQuery=$rrq reRankMode=replace reRankDocs=100 reRankWeight=1}");
// Create a rerank query that uses the RNI pairwise matching function
solrQuery.set("rrq", "{!func}rniAddrMatch(" + "address" + ", \"" + queryAddress + "\")");
// Set which fields to include in the results
solrQuery.setFields("uid", "primaryName", "address", "dob", "score");
QueryResponse qResults = server.query(solrQuery);
//QueryResponse qResults = server.query(createQuery());

Define and run a query against name, date, and other fields, using RNI pairwise matching to rerank the documents returned.

// Define a query that combines name, address and other fields, and uses RNI
// pairwise matching to rerank the documents returned.
String queryName = "Chuy A Lopez";
String queryDate = "04/03/1971~format=dd/MM/yyyy";
SolrQuery solrQuery = new SolrQuery("aka" + ":\"" + queryName +
                    "\" AND dob:\"1960-09-30\"");
// Set the rerank query parser parameters
solrQuery.set(CommonParams.RQ,
          "{!rniDateRerank reRankQuery=$rrq reRankMode=replace reRankDocs=100 reRankWeight=1}");
// Create a rerank query that uses the RNI pairwise matching function
solrQuery.set("rrq", "{!func}rniDateMatch(" + "dob" + ", \"" + queryDate + "\")");
// Set which fields to include in the results
solrQuery.setFields("uid", "primaryName", "address", "dob", "score");
QueryResponse qResults = server.query(solrQuery);
//QueryResponse qResults = server.query(createQuery());

Display the results:

// Print information about the documents returned with their Solr score.
for (SolrDocument rdoc : qResults.getResults()) {
 System.out.println("Returned Entity: " + rdoc.getFieldValue("uid")+ 
       "\n Name: " + rdoc.getFieldValue("primaryName") + 
       "\n Address: " + rdoc.getFieldValue("address") + 
       "\n DOB: " + rdoc.getFieldValue("dob") + 
       "\n Document Score: " + rdoc.getFieldValue("score"));
}

The RNI-RNT SDK ships with an example that illustrates the use of the org.apache.solr.client.solrj API to integrate the RNI Solr plugin into a Solr application. See RNISolrjSample. This sample also illustrates a procedure for posting Solr documents from an xml file.

For convenience utilities for working with RNI names in a Solrj environment, see the Javadoc for com.basistech.rni.solr.index.