TellusR integrates with Solr using isolated components that may be enabled and configured independently.
This component can be added to the search-handler stack. It will automatically synchronize with and search among indexes generated via the GUI:
<!-- Semantic search -->
<searchComponent name="semanticSearch" class="tellusr.semantic2.HnswSearchComponent">
</searchComponent>
TellusR needs to catch documents passed Solr for TellusR specific processing. An example where this is used is in incremental updating of semantic indexes.
<!-- TellusR's update handler (extends the default solr update handler) -->
<updateHandler class="tellusr.UpdateHandler">
<!-- Same configuration as you would use in your Solr updatehandler.
If in doubt, use default settings. -->
</updateHandler>
This component is required. If it is not defined in a core, the TellusR Central will not be able to connect to that core. Installing it is a matter of introducing this single line in the core’s solrconfig.xml file:
<requestHandler name="/tellusr_config" class="com.sannsyn.solrplugins.TellusRConfig"/>
The the installation script inserts this if your cores are running. Otherwise, (or if you didn’t insert it while installing the integrator manually), remember to restart Solr after inserting it in relevant files.
This component is responsible for the aggregation of search metrics. It gets configured in two phases: declaration of a search component and its listing within search handlers.
The declaration is about referring to the QueryReporter class, providing a name for the component (we suggest queryReporter) and configuring it. In the configuration, you can optionally specify either the excludeFields or includeFields list. Exclusion implies that terms from all fields but the ones specified will be reported. Inclusion means that only the terms from the specified fields will be reported. If both lists are configured for a component, the component will only use the excludeFields list, and ignore includeFields. You can also filter searches that have or lack a specific parameter with filterIfParams and filterIfNotParams.
excludeFields - (Optional) arr of str fields naming search fields that should not have terms reported as search terms. This might be useful if you have implemented category search by adding a category field.
includeFields - (Optional) arr of str fields naming which search fields should have terms reported. If this is used, only searches on the named fields and the wildcard field will be sent.
filterIfParams - (Optionial) arr of str of parameter names. Do not report terms for searches that include these parameters.
filterIfNotParams - (Optionial) arr of str of parameter names. Only report terms for searches that include these parameters. You may for example only want to report terms for searches that include the user_id parameter.
Here’s an example:
<searchComponent name="queryReporter" class="com.sannsyn.solrplugins.QueryReporter">
<arr name="excludeFields">
<str>genre</str>
<str>name</str>
</arr>
</searchComponent>
The configured search component must be added to existing search handler declarations by referring to it by name in the last-components field. E.g. like this:
<requestHandler name="/select" class="solr.SearchHandler">
<!-- ... -->
<arr name="last-components">
<str>queryReporter</str>
</arr>
</requestHandler>
This component will cache the latest query a user makes to a suggest handler. This cache is later used by the Query Reporter and TellusR Central to improve search term statistics, so that an educated guess for which term the user started to type is logged, rather than the autocompleted term. The Suggest Reporter will log both normal queries (with the q param) and queries using Solr’s suggester api (with the suggest.q param).
For the Suggest Reporter to work, both the suggester query (with the Suggest Reporter in the component stack) and the final search (with the Query Reporter in the component stack) must have a session id (or user id) supplied in a user_id parameter.
<searchComponent name="suggestReporter" class="com.sannsyn.solrplugins.SuggestReporter">
</searchComponent>
<requestHandler name="/suggest" class="solr.SearchHandler">
<!-- ... -->
<arr name="last-components">
<str>suggestReporter</str>
<!-- ... -->
</arr>
</requestHandler>
A query to the suggest handler might look something like this:
http://yourserver.example.com:8983/yourcore/suggest?user_id=sessionXX&suggest.q=incompl
A query to the select handler might look like this:
http://yourserver.example.com:8983/yourcore/select?user_id=sessionXYZ&q=incomplete+search+autocompleted+via+suggest+handler
(The user_id parameter is also needed by the Action registration functionality.)
AB-testing (also referred to as split testing) enables the administrator of a Solr server to forward users to different search handlers randomly. When used in combination with a query reporter, this enables the administrator to analyse the performance of different handlers.
To enable this functionality, you need to declare an ABTestHandler, specifying a fallback handler that will be forwarded to if there is no active AB-tests or if the integrator for some reason cannot get in touch with the TellusR Central.
AB-testing is only supported for handlers that include statistics reporting.
For AB-testing to make sense, there must be at least two search handlers configured. A complete configuration may look something like this:
<requestHandler name="/abtest_select" class="com.sannsyn.solrplugins.ABTestHandler">
<str name="abtest_fallback">/abtest_a</str>
</requestHandler>
<requestHandler name="/abtest_a" class="solr.SearchHandler">
<!-- ... -->
<arr name="last-components">
<!-- ... -->
<str>queryReporter</str>
</arr>
</requestHandler>
<requestHandler name="/abtest_b" class="solr.SearchHandler">
<!-- ... -->
<arr name="last-components">
<!-- ... -->
<str>queryReporter</str>
</arr>
</requestHandler>
The BoostedSearch component adds the ability to boost some matches so that they are shown
higher in the search results. Boosting will not add new matches to the search, but if a
search result that matches the boosting criteria is found, its match score will be modified. This
results in a reordering of the first few pages of the search based on the active boosting rules.
The boosting rules are configured in the tellusR administration panel.
<searchComponent name="boostedSearch" class="com.sannsyn.solrplugins.BoostedSearch">
</searchComponent>
<requestHandler name="/boosted_select" class="solr.SearchHandler">
<arr name="last-components">
<str>boostedSearch</str>
</arr>
</requestHandler>
The following is a snippet with all the aforementioned TellusR features enabled. If you use
this snippet as a template, you should remove the original /select handler (or rename it
to /select_fallback, for example, if you want to keep it as a reference). Important
configuration from the original /select handler should be reimplemented in the
SearchHandler below. (Please note that the new /select in the snippet is not a
SearchHandler but an ABTestHandler that will redirect SearchHandlers, so such config should
not be reimplemented for this).
<config>
<searchComponent name="elevator" class="solr.QueryElevationComponent">
<str name="queryFieldType">string</str>
<str name="config-file">elevate.xml</str>
</searchComponent>
<!-- Sannsyn TellusR -->
<!-- Enable tellusR functionality in this core -->
<requestHandler name="/tellusr_config" class="com.sannsyn.solrplugins.TellusRConfig">
</requestHandler>
<requestHandler name="/tellusr" class="tellusr.TellusR">
</requestHandler>
<!-- TellusR components -->
<!-- Sends statistics about requests to the TellusR backend -->
<searchComponent name="queryReporter" class="com.sannsyn.solrplugins.QueryReporter">
<str name="parsingStrategy">standard</str>
</searchComponent>
<!-- Semantic search -->
<searchComponent name="semanticSearch" class="tellusr.semantic2.HnswSearchComponent">
</searchComponent>
<!-- Enables search boosting of documents via the TellusR admin console -->
<searchComponent name="boostedSearch" class="com.sannsyn.solrplugins.BoostedSearch">
</searchComponent>
<!-- Logs requests to solr.log in an extractable format -->
<searchComponent name="requestLogger" class="com.sannsyn.solrplugins.RequestLogger">
</searchComponent>
<!-- Cache Last suggest request from user for inclustion with Query Reporter -->
<searchComponent name="suggestReporter" class="com.sannsyn.solrplugins.SuggestReporter">
<str name="parsingStrategy">standard</str>
</searchComponent>
<!-- Make the default select handler an AB-test handler -->
<requestHandler name="/select" class="com.sannsyn.solrplugins.ABTestHandler">
<str name="abtest_fallback">/select_a</str>
</requestHandler>
<!-- Application specific params -->
<initParams path="/select_a,/select_b,/select_c">
<lst name="defaults">
<str name="df">_text_</str>
<str name="defType">edismax</str>
</lst>
</initParams>
<!-- TellusR specific params -->
<initParams path="/select_a,/select_b,/select_c">
<arr name="last-components">
<str>queryReporter</str>
<str>spellcheck</str>
<str>semanticSearch</str>
<str>boostedSearch</str>
<str>elevator</str>
</arr>
</initParams>
<!-- Define three TellusR-enabled handlers to enable AB(C)-testing -->
<requestHandler name="/select_a" class="solr.SearchHandler">
</requestHandler>
<requestHandler name="/select_b" class="solr.SearchHandler">
</requestHandler>
<requestHandler name="/select_c" class="solr.SearchHandler">
</requestHandler>
</config>