Solr Configuration

Blacklight configuration

The example Blacklight configuration is a simple application for displaying library holdings. In this section, we will describe the Blacklight configuration settings that determine how the Blacklight interface works with your data.

Connecting to Solr

Blacklight's default Solr connection parameters are configured globally in config/blacklight.yml. It looks something like other Rails YAML configurations:

# config/blacklight.yml
development:
  adapter: 'solr'
  url: <%= ENV['SOLR_URL'] || "http://127.0.0.1:8983/solr" %>
test: &test
  adapter: 'solr'
  url: <%= "http://127.0.0.1:#{ENV['TEST_JETTY_PORT'] || 8888}/solr" %>

When using the solr adapter, additional parameters are passed through to configure the RSolr::Client, including:

• url
• proxy
• open_timeout
• read_timeout
• retry_503
• retry_after_limit

Note that Blacklight pre-parses the YAML file using ERB, which means you can use environment variables to configure the Solr location. With the default configuration above, this means you can start Blacklight and point it at an external solr index without changing the blacklight.yml file: $ SOLR_URL="http://my.production.server/solr/core/" rails server

Run-time configuration

The blacklight.yml configuration is applied globally to all Solr connections from your application. If you need to configure dynamic (e.g. per-user or per-controller) connections, the Blacklight::Configuration object provides accessor methods that can be set using configure_blacklight or directly on the blacklight_config object:

class CatalogController < ApplicationController
  include Blacklight::Catalog

  configure_blacklight do |config|
    config.connection_config = { url: 'https://...' }
  end
end

More sophisticated configuration is also possible by setting the blacklight_config.repository_class to a locally defined implementation:

class CatalogController < ApplicationController
  include Blacklight::Catalog

  configure_blacklight do |config|
    config.repository_class = MyCustomSolrRepository
  end
end

class MyCustomSolrRepository < Blacklight::Solr::Repository
  def build_connection
    RSolr::Custom::Client.new(connection_config.merge())
  end
end

Solr Configuration

Blacklight is compatible with and should work with any Solr configuration, and the out-of-the-box defaults work with most typical configurations.

A typical Solr request handler configuration for search likely includes:

• defType should be edismax or dismax. These query parsers are designed to handle arbitrary user input in reasonable ways, and are usually a reasonable choice for Blacklight applications.
• q.alt should be *:*. In the absence of a user-provided search parameter (and for a reasonably sized data set), you should probably select all documents by default. This will allow Blacklight to populate the default home page with a list of facet, and allow your users to get an overview of the contents of your data without needing a search query.
• facet.mincount should be set to 1. If it is set to 0, every facet will appear in your UI, regardless of whether it matches any documents or not.

By default, Blacklight uses Solr's Real-Time Get request handler at /get to retrieve individual documents.

Blacklight provides some additional configuration options to change what parameters are sent and to which Solr API endpoints requests are made:

          # === Search request configuration
          # HTTP method to use when making requests to solr; valid
          # values are :get and :post.
          http_method: :get,
          # The path to send requests to solr.
          solr_path: 'select',
          # Default values of parameters to send with every search request
          default_solr_params: {},
          # === Single document request configuration
          # The solr request handler to use when requesting only a single document
          document_solr_request_handler: nil,
          # The path to send single document requests to solr
          document_solr_path: 'get',
          document_unique_id_param: :ids,
          # Default values of parameters to send when requesting a single document
          default_document_solr_params: {},
          fetch_many_document_params: {},
          document_pagination_params: {},

Schema: Solr Unique Key

If your solr configuration uses a unique field other than id, you must configure your SolrDocument (in app/models/solr_document.rb) to set the unique key:

# app/models/solr_document.rb

class SolrDocument
  include Blacklight::Solr::Document

  self.unique_key = 'my_unique_key_field'
 
  ...
end

Request handlers

Blacklight supports rapid application development by allowing you to configure Blacklight to send every parameter in every solr request. One of the ways to productionize this is to move the static logic into Solr request handlers. Request Handlers are configured in the solrconfig.xml.

Request handler parameters can be configured three different ways:

• defaults - provides default param values that will be used if the param does not have a value specified at request time.
• appends - provides param values that will be used in addition to any values specified at request time (or as defaults.
• invariants - provides param values that will be used in spite of any values provided at request time. They are a way of letting the Solr maintainer lock down the options available to Solr clients. Any params values specified here are used regardless of what values may be specified in either the query, the "defaults", or the "appends" params.

Here is an example request handler demonstrating all types of configuration:

  <requestHandler name="standard" class="solr.StandardRequestHandler">
     <lst name="defaults">
       <!-- assume they want 50 rows unless they tell us otherwise -->
       <int name="rows">50</int>
       <!-- assume they only want popular products unless they provide a different fq -->
       <str name="fq">popularity:[1 TO *]</str>
     </lst>
    <lst name="appends">
      <!-- no matter what other fq are also used, always restrict to only inStock products -->
      <str name="fq">inStock:true</str>
    </lst>
    <lst name="invariants">
      <!-- don't let them turn on faceting -->
      <bool name="facet">false</bool>
    </lst>

  </requestHandler>

Document request handler

Similar to the search request handler, we strongly encourage you to configure a request handler for retrieving single documents. By default, Blacklight uses the Solr Real-Time Get request handler:

<requestHandler name="/get" class="solr.RealTimeGetHandler">
  <lst name="defaults">
    <str name="omitHeader">true</str>
    <str name="wt">json</str>
    <str name="indent">true</str>
  </lst>
</requestHandler>

You can also define a separate request handler, makes it easier to understand the Solr request log, and allows you to easily change request parameters for search and single-item behaviors separately.

The blacklight document request handler looks like this:

<requestHandler name="document" class="solr.SearchHandler" >
  <lst name="defaults">
    <str name="echoParams">all</str>
    <str name="fl">*</str>
    <str name="rows">1</str>
    <bool name="facet">false</bool>
    <str name="q">{!raw f=id v=$id}</str> <!-- use id=666 instead of q=id:666 -->
  </lst>
</requestHandler>

And you can configure Blacklight to use that endpoint with:

class CatalogController < ApplicationController
  include Blacklight::Catalog

  configure_blacklight do |config|
    config.document_solr_request_handler = 'document'
    config.document_solr_path = 'select'
    config.document_unique_id_param = 'id'
  end
end