Skip to main content
Kinetic Community

Solr Adapter

Overview

The Solr Adapter for Bridgehub is an adapter that allows retrieving indexed documents from Solr to be pulled back using bridging.

The examples on this page for field or qualification mapping uses the tech products example data sets from Solr (solr start -e techproducts from the solr directory). This five minute tutorial uses an old version of Solr, but the newer versions (6 and 7) support this same command.

Installation

Note: Check to ensure that this adapter isn't already installed into your bridgehub as part of the base installation before undertaking the installation tasks.

  • Download the kinetic-bridges-adapter-solr.zip file here
  • Unzip the file into the WEB-INF/lib folder for you kinetic-bridgehub installation
  • Restart the tomcat that your kinetic-bridgehub installation is located in

Setup

Configuration Values

Name Description
Solr URL URL to the Solr instance.
Username Optional username to specify for basic authentication if your Solr implementation requires it.
Password Optional password to specify for basic authentication if your Solr implementation requires it.

Example Configuration

Name Value
Solr URL http://solr.yourdomain.com:8983/solr
Username  
Password  

Structures, Fields, and Queries

Structures

  • Any valid Solr core. 
  • Examples
    • techproducts

Fields

  • JsonPath is used for mapping field values. The default JsonPath root path is set to $.hits.hits. Both bracket, e.g. $['response']['docs'] , and dot notation, e.g. $.response.docs , are supported. A different JsonPath root path can be specified in the qualification mapping, please see the Queries section below for details. Changing the root path is not necessary unless you're using the Solr DSL query type and your Solr query is complicated / uses facets.

    If the root path evaluates to an array (such as the default root path $.response.docs) then this as seen as matching multiple records if the array size is greater than one. If the root path evaluates to an object instead of an array then this as seen as matching only one result for the bridge.
  • If you'd like to practice using JsonPath, you can use the jsonpath online evaluator webpage

Shakespeare data set examples:

  • ${fields('price')}
  • ${fields('name')}
  • ${fields('description')}
  • ${fields('keywords')}

Qualification Mapping

The following qualification mapping syntax options are supported:

  1. Lucene query syntax.
  2. A JSON Object.

 

  1. Lucene query syntax
    1. This is the most straight forward qualification mapping option.
    2. The query syntax directly maps to the Solr Query Syntax
    3. All parameter values have the Solr reserved characters are escaped. This is to protect against any input parameters possibly changing the structure or the intentions of a bridge query.
    4. Example tech products qualification mappings:
      1. Find all products where the price is in a specified range:
        1. price[${parameters('lower price limit')} TO ${parameters('upper price limit')}]
      2. Find all products where the name is close to what a user is looking for and is very popular.
        1. name:${parameters('product name')}~4 && popularity[3 TO *]
           
  2. JSON Object
    • Example tech products data set qualification mappings:

      • mapping qualification: {"type": "Kinetic DSL", "query": "${parameters('kinetic dsl json')}"}
        ${parameters('kinetic dsl json')} : {"name": {"value": "ipod", "matcher": "like"}, "features": {"value": "mp3", "matcher": "exact"}}
        dynamic Lucene query produced: name:*ipod* && features:mp3
         

      • mapping qualification: {"type": "Kinetic DSL", "concateOperator": "||", "query": "${parameters('kinetic dsl json')}"}
        ${parameters('kinetic dsl json')} : {"name": {"value": "ipod", "matcher": "like"}, "features": {"value": "mp3", "matcher": "exact"}}
        dynamic Lucene query produced: name:*ipod* || features:mp3
         

      • mapping qualification: {"type": "Kinetic DSL", "whitelistFields": ["name", "features"], "query": "${parameters('kinetic dsl json')}"}
        ${parameters('kinetic dsl json')} : {"name": {"value": "ipod", "matcher": "like"}, "features": {"value": "mp3", "matcher": "exact"}, "includes": {"value": "earbuds", "matcher": "like"}}
        dynamic Lucene query produced: name:*ipod* && features:mp3

      • mapping qualification: {"type": "Kinetic DSL", "queryPrefix": "price:[* TO 20]", "query": "${parameters('kinetic dsl json')}"}
        ${parameters('kinetic dsl json')} : {"name": {"value": "ipod", "matcher": "like"}, "features": {"value": "mp3", "matcher": "exact"}}
        dynamic Lucene query produced: price:[* TO 20] && (name:*ipod* && features:mp3)
         
      • mapping qualification: {"type": "Solr DSL", "query": "${parameters('solr dsl json')}"}
        ${parameters('solr dsl json')} : {"size":0,"query":{"bool":{"must":[{"term":{"play_name":"Henry IV"}}]}},"aggs":{"lines per character":{"field":"speaker"}}}
        Solr query produced: {"size":0,"query":{"bool":{"must":[{"term":{"play_name":"Henry IV"}}]}},"aggs":{"lines per character":{"terms": {"field":"speaker"}}}}
         
    • The expected JSON Object expected structure looks like the following:

      {
        "type": "...",
        "concateOperator": "...",
        "jsonRootPath": "...",
        "queryPrefix": "...",
        "whitelistFields": ["..."],
        "query": "{...}"
      }

    • type (required)

      • Either Solr JSON API or Kinetic DSL. Changes the expected syntax of the query key value

    • concateOperator (optional)

      • Only used for the Kinetic DSL type

      • Controls the logical operator used between defined field comparisons.

      • Valid values are && or ||. && is the default value if the concateOperator is not defined.

    • jsonRootPath (optional)

      • Only potentially necessary for the Solr DSL query type option. See the last mapping qualification example above for an example.

      • Specifies the starting JsonPath position for the Solr results returned.

      • Defaults to $.response.docs

    • queryPrefix (optional)

      • Only used for the Kinetic DSL type

      • Any lucence query you want to prefix to the dynamically built query. The && operator will automatically be added to the end of the queryPrefix value and before the dynamically generated query from the 'query' key.

      • Useful as a security / scoping measure to 'jail' any query  an end-user may define on their own if the query is left wide open by setting it to ${parameters('json parameter')}

    • whitelistFields (optional)

      • Only used for the KInetic DSL type
      • An array of solr core fields that are allowed to queried against.
      • If not specified, all fields are valid to query against in the query key
      • Useful as a security / scoping feature to 'jail' any query a user may define.
      • Parameters cannot be used here.
    • query (required)

      • Expected value is a JSON object. Note that while the expected value is in the form of a JSON object, the JSON object must be inside a string.

      • Object keys and values are dependent on the key type (Kinetic DSL or Solr DSL) value.

      • Solr DSL JSON format maps directly to the Solr JSON Request API. The JSON specified will be passed as the value for the 'json' HTTP Request parameter in the query request body.

      • Kinetic DSL JSON follows this format:
        {
          "field_one": {
            "isPhrase": true|false,
            "matcher": "...",
            "value": "..."
          },
          "field_two": {
            ...
          }

        • Kinetic DSL is parsed and then converted to the Lucene query syntax in a structured way.

        • isPhraseOptional. Valid options are either true or false. Controls whether quotes are placed around the field value match or not. Default value is false, no quotes.

        • matcherOptional. Controls how astrisk wild cards are placed around the field value. Valid options are startsWith, endsWith, exact, and like. startsWith places an asterisk after the field value. endsWith places an asterisk before the field value. exact does not append any asterisks. like spaces asterisks before and after the field value in the query. Default value is exact.

        • valueRequiredThe value that the field should be matched against. 

Changelog

v1.0.0 (2017-08-15)

  • Initial version