Autocomplete with Categories/Entities Configuration

Owned by Cedric
Last updated: 14 Mar, 2024 by Cedric
6 min read

Valid from 4.4 for EE and 5.0 for CE

The documentation below is valid from Datafari v4.4 EE and 5.0 CE - For older versions, please refer to Semantic implementation - Enterprise Edition [DEPRECATED]

A new feature has appeared in beta version in Datafari 4.4, it is the entities terms for search. It is splitted in two parts : a suggester and a corresponding category that defines a search behavior for the term(s) that belongs to the category.

  1. The suggester

    The suggester is used to suggest entities that may match with the last term typed by the user in the search bar.

    To configure a suggester for an entity you first need to create a new suggest request handler in Solr, based on the desired category field. Then you will need to edit AUTOCOMPLETESUGGESTERS variable in the configuration file DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties :

    AUTOCOMPLETESUGGESTERS=[\ {\ "i18nKey":"asAuthor", \ "serverUrl":"", \ "servlet":"suggestAuthors", \ "suggestComponent":"suggesterEntityAuthors", \ "maxSuggest":1, \ "categoryKey":"authors", \ "categoryi18nKey":"authors", \ "cssClass":""\ }\ ]

    This variable must contain a json array, composed by a list of json objects having the following fields :
    - i18nKey - Mandatory : the i18n key to use fort the autocomplete label. The autocomplete label is built like this : [Proposal] [i18n label]. For example, for the author category, an autocomplete proposal could be : Hawkins as author.  The "as author" sentence would be retrieved thanks to the "asAuthor" entry in the i18n files located in DATAFARI_HOME/tomcat/webapp/Datafari/js/AjaxFranceLabs/locale/. Of course you will need to create your desired i18n key and associated label in each language file
    - serverUrl : if the targeted suggest request handler is located and reachable from another server than the Datafari main one, you will need to enter the server address in this variable (like: https://1.2.3.4:8989/External_Sample_Solr_Path)
    - servlet - Mandatory: the servlet name associated to the suggest request handler
    - maxSuggest - Mandatory : maximum number of category suggestions to be displayed within the autocomplete
    - categoryKey - Mandatory : the key name of the category corresponding to the suggester request handler. The key name must match to a category name in the CATEGORIES variable of the DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties file (see below for more info)
    - categoryi18nKey - Mandatory : i18 key name for the category. This is used for the dropdown on the left of the searchfield, that lists the existing categories. This field must have a matching entry in the language files located in DATAFARI_HOME/tomcat/webapp/Datafari/js/AjaxFranceLabs/locale/
    - cssClass : the css class name you want to add to each term suggested by this suggester (see description of the suggester role below)
    Detailed suggesters role explanation:
    When the user type in the input search bar, the last term typed is sent to each autocomplete suggesters defined in the DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties. If there are suggestions, they are added to the autocomplete. An entity suggestion contains a term, the categoryKey value, and the cssClass value (if any defined). Once a user selects an entity suggestion, these additional values are used to build an "entity span tag" in the "entities-highlight-content" div (see [DEPRECATED] Categories/Entities feature - France Labs Only for more details about that div) which look like this:

    <span class="entity-hl [cssClass]" entity-id="[categoryKey]">[term]</span>

    This kind of "entity span tag" allow to "fake" an highlight in the input search bar like this :

    The default highlight style and color are defined by the css "entity-hl" class but the [cssClass] value that you (may) have defined is there to allow you to override default style and color of the highlight effect. 

  2. The category

    Like described above, each suggester must be associated to a category. The categories are defined in the CATEGORIES variable of the DATAFARi_HOME/tomcat/conf/entity-autocomplete.properties file :

    CATEGORIES={\ "authors":{\ "queryPrefix":"author_search:(", \ "querySuffix":")"\ }\ }

    This variable must contain a json object composed of categories keyname as fields (like "authors" in the above example), and json objects as values representing the categories specific options that are :
    - queryPrefix : a prefix to add to each entity term that belongs to this category
    - querySuffix : a suffix to add to each entity term that belongs to this category
    Detailed categories role explanation:
    Once a user performs a query containing entity term(s), the SearchProxy servlet receive the content of the "entities-highlight-content" div with entity terms encapsulated in "entity span tags" (containing the categoryKey associated with the term). For each span tag, the category configuration is retrieved thanks to the categoryKey and the entity span tag is replaced by the following pattern : 

    Once all the entity span tags are processed, the original query is replaced by the one obtained after this quick process.

To enable or disable the categories feature you will need to change the value of the ACTIVATED variable of the DATAFARi_HOME/tomcat/conf/entity-autocomplete.properties file to true or false. By default, it is set to false.

Not functionnal with STT

As of July 2019, this functionnality is not usable with the STT based Tagging for Queries - Enterprise Edition

Valid from 4.1 up to 4.3

The documentation below is valid from Datafari v4.1 to v4.3

A new feature has appeared in beta version in Datafari 4.1, it is the categories context for search. It is splitted in two parts : a suggester and a corresponding category that defines a search behavior when the category is selected.

  1. The suggester

    The suggester is used to predict whether the user search term belongs to a category and propose a "special option" in the autocomplete to perform the user search in that specific category.

    To configure a suggester for a category you first need to create a new suggest request handler in Solr, based on the desired category field. Then you will need to edit AUTOCOMPLETESUGGESTERS variable in the configuration file DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties :

    This variable must contain a json array, composed by a list of json objects having the following fields :
    - i18nKey - Mandatory : the i18n key to use fort the autocomplete label. The autocomplete label is built like this : [Proposal] [i18n label]. For example, for the author category, an autocomplete proposal could be : Hawkins as author.  The "as author" sentence would be retrieved thanks to the "asAuthor" entry in the i18n files located in DATAFARI_HOME/tomcat/webapp/Datafari/js/AjaxFranceLabs/locale/. Of course you will need to create your desired i18n key and associated label in each language file
    - serverUrl : if the targeted suggest request handler is located and reachable from another server than the Datafari main one, you will need to enter the server address in this variable (like: https://1.2.3.4:8989/External_Sample_Solr_Path)
    - servlet - Mandatory: the servlet name associated to the suggest request handler
    - maxSuggest - Mandatory : maximum number of category suggestions to be displayed within the autocomplete
    - categoryKey - Mandatory : the key name of the category corresponding to the suggester request handler. The key name must match to a field name in the CATEGORIES variable of the DATAFARI_HOME/tomcat/conf/entity-autocomplete.properties file (see below for more info)
    - categoryi18nKey - Mandatory : i18 key name for the category. This is used for the dropdown on the left of the searchfield, that lists the existing categories. This field must have a matching entry in the language files located in DATAFARI_HOME/tomcat/webapp/Datafari/js/AjaxFranceLabs/locale/

  2. The category
    Like described above, each suggester must be associated to a category. The categories are defined in the CATEGORIES variable of the DATAFARi_HOME/tomcat/conf/entity-autocomplete.properties file :

    This variable must contain a json object composed of categories keyname as fields and json objects as values representing the categories specific options :
    - queryPrefix : a query prefix to add to each search for this category
    - querySuffix : a query suffix to add to each search for this category
    - solrCore : the Solr Core to request if it differs from the default one "FileShare". This Solr Core must be local to your Datafari install.
    - requestHandler : the request handler that executes the query if it differs from the default one "/select". This request handler must be local to your Datafari install.

These are the pre-configured options of the beta version of the categories features. You can add more options like filter queries, field list etc. but you will need to write some code to handle them in the SearchProxy servlet of Datafari

To enable or disable the categories feature you will need to change the value of the ACTIVATED variable of the DATAFARi_HOME/tomcat/conf/entity-autocomplete.properties file to true or false. By default, it is set to false.