This document provides a guide on integrating your applications with TellusR.
The tellusr/search image is based on the official Solr docker image, and creating and populating a core (or collection) may be done as described in the official Solr documentation. When tellusr/search is running, you can create a core by doing the following:
docker exec -it tellusr-solr-8983 solr create_core -c my_collection
The core created by tellusr/search in this way will have TellusR preconfigured. You may find further information about creating cores while running Solr with docker in the official Solr documentation here.
Populating the new core with data can also be done as described in the official Solr documentation:
curl -X POST -H 'Content-Type: application/json' 'http://localhost:8983/solr/my_collection/update' --data-binary '
[
{
"id": "1",
"title": "Doc 1"
},
{
"id": "2",
"title": "Doc 2"
}
]'
Please consult the official Solr documentation here.
We also maintain a TellusR toolbelt that you may use to develop TellusR-configured cores and keep them in a git repository. It is available via github.
While this is not required, you can enhance the quality of Query Reporter and AB-testing functionality of TellusR by extending your Solr requests with the following parameter:
user_id=<string>
The string should be a value that is constant for the user between a search and click or sale/conversion. Meaning that the same user_id should be supplied when searching and when reporting a click or sale/conversion. This could be either an actual (or hashed) user ID or some kind of session ID.
In AB-testing user_id is used as seed for the random generator, making sure that the same user is always forwarded to the same search handler during AB-testing. In Query Reporter it is used for the calculation of click to sale conversion.
The TellusR suggester is a normal search handler with some extra funtionality, like misspell tolerance and duplicate filtering. Like with normal solr requests above, you could send a user_id parameter for improved statistics in the TellusR Dashboard.
Which fields and the relative weight of each field is configured in the Dashboard. Before it is used, the suggester should be indexed. This is also done in the “Suggest Setup”-widget in the Dashboard. Alternatively it is possible to start indexing by sending suggest.build=true to the suggest handler.
A typical query to the suggest handler if the user has typed “gra” might look like this, given that solr is running on localhost port 8983 and the core is named yourcore and the suggestion you want to offer is contained in a field named title:
http://localhost:8983/solr/yourcore/autosuggest?user_id=NN&q=gra&fl=title
The TellusR Central provides the following endpoint for registration of clicks and sales/conversions.
POST /api/hit/register
{
"hitType": "",
"coreName": "",
"handlerPath": "",
"userId": "",
"docId": ""
}
Where the fields are all strings with the following meanings:
hitType - Type of action. Can only have one of the following values: click or sale.coreName - Name of Solr core that has generated the search.handlerPath - Solr request handler that has generated the search.userId - User or session ID that was passed to the search.docId - ID of the document that was clicked or generated a sale.There is also a GET version of the this interface:
GET /api/hit/register/$hitType/$coreName/$handlerPath/$userId/$docId
If using this, please make sure that the handlerPath is URI encoded.