Implementing Solr with Facets in Drupal 8

This post will go into some background and then details about how to configure Facets with Solr Search on a Drupal 8 site. Drupal 8 is awesome and new, and only recently has the dust settled on a clear path to getting Solr Search with Facets. I personally found both a lack of documentation for this on Drupal 8, as well as some non-obvious quirks to the process. This article will attempt to fill that need. I’ll talk through the concepts so you know what is going on. If you want to skip right to the configuration details, skip to "Actual Implementation Steps."

What is Solr and When do you need it? 

Drupal 8 comes with robust search functionality right out of the box. The basic search indexes your nodes and entities and allows basic full-text searching. This is all fine and good for small or medium sized sites. However, core search does not scale well, or scale in a linear manner. The core search relies on database queries, and as your traffic and number of items in your database expands, the time to complete the searches will also increase, generally adding query load and processing time to your server. 

Solr search is a great solution to this, and well used by the Drupal community. Solr itself is an open source search platform built on Apache’s Lucene Core, which is written in Java. In practical terms, Solr runs as a separate web service. Solr gives your search functionality many more powerful features, including facets, which we’ll cover shortly. When set up, your Drupal site hands off search queries to the Solr instance, which searches and retrieves results from its own index. This completely offloads any query processing from your own site and database. 

While you can always set up and run Solr yourself, what’s nice is that the major Drupal hosting providers have pre-configured Solr services set up and ready to easily integrate into your site.

What are facets?

Facets are a feature of Faceted search. Faceted search is an important tool in the toolbox of information architecture. While it is a feature of search, it can also be a key idea behind the whole way the content on your Drupal site is structured and architected. 

“A faceted classification system classifies each information element along multiple explicit dimensions, called facets, enabling the classifications to be accessed and ordered in multiple ways rather than in a single, pre-determined, taxonomic order.[1]”

You’ve probably dealt with facets plenty of times already, shopping at online retailers such as Zappos, Amazon, or any retailer that presents a series of categories that you drill-down into smaller and smaller sets of what you are looking for. 

A picture of a page from a popular website showing facets.


Why use facets?

As mentioned, the most obvious and widely format of using facets is in the context of shopping and e-commerce. In cases where the job of the site is to present a large database of products, or any well structured and easily categorized data, facets are a great choice. Facets both present and inform, at the same time. They indicate what categories of items the site contains and they present an immediate path to more specific content. Additionally, well structured facets paired with a well thought-out information architecture, can make multiple paths available to the same content, and aid visitor engagement with the content. 

More in-depth articles on facets from an information architecture perspective are available here and here

 

Actual implementation steps

This article assumes you already have an installed and working Drupal 8.3.5 site and you know how to perform basic tasks such as installing and uninstalling modules. It also assumes you are familiar with configuring views and placing blocks. 

1. Disable core search module

The first thing you'll want to do is disable the basic search that comes with Drupal core:

A picture of a Drupal page presenting the option to disable the Search module.
Disable this one. 

 

2. Install the modules you'll need

In order to connect to a Solr service, You may need extra modules depending on hosting provider. 
Pantheon users will need: search_api_pantheon
Acquia users will need: acquia_search

Also, get the following modules for Drupal 8 installed and enabled:
Facets (facets)
Search API (search_api)
Search API Solr Search (search_api_solr)


 

A Drupal configuration page showing certain modules enabled.

 

3. Configure your Solr Search

Once the modules are installed, there will be provider-specific steps to get your Drupal site talking to the Solr service. You'll need to find and complete your provider's steps for getting this done. The indication that this is complete and you can move on is when you see messages confirming communication with the Solr server.

So on /admin/reports/status you should see:

A picture of text on a status page.

Or on /admin/config/search/search-api you should see:

A picture of text on a status page.

 

Pro-Tip for Acquia users: If you're *not* an enterprise customer and you get messages about auto-switching and your Solr index keeps put in Read-Only mode, be sure to read this and the README in the Acquia Search module. 

 

4. Add an Index and the fields you want as facets 

The goal here is to make sure that the exact fields you want to serve as facets are included in your index. An index may already be created by the defaults of your provider-specific Solr modules. Make sure you have one and Edit it to check and make sure everything you want included in your index is set up. (This is on /admin/config/search/search-api)

A picture of text on a status page.

When you edit an individual Index, you'll get a list of Data Sources. Make sure you select Content, as well as "Taxonomy Term" if you want taxonomy terms as facets:

 

A picture of text on a status page.

 

After doing that, go to the 'Fields' tab for your index. You'll see a list of all the fields your index is currently set up to store results for.

A picture of text on a status page.

Any field that you want as a facet needs to be here. If it is not, click the '+Add Fields' button. You'll get a list of all the possible fields from the data sources you specified on the index's 'Edit' page. Add any fields you want indexed here. If you want taxonomy terms indexed and as facets, make sure you add the taxonomy term Name field:

A picture of text on a status page.

 

If you're indexing a lot of text-based content (Articles, Basic Pages, etc.) you're probably going to want search-engine style excepts of the content to show up in your search results. This is controlled in the 'Processor' tab, so take a look and add highlighting and choose whatever other options you'd like. 

A picture of a page within the Drupal Administrative Interface.

If you've added fields to your index, you'll want to be sure to re-index them so they show up in your search results. Go back to the 'View' tab for your index and click the link to 'Queue all items for reindexing.'

A picture of text on a status page.

Now What? 

Now that you have the Solr connection set up and your content indexed, how do we get a search page made or results to show up? This part confused me for a while. You may be tempted to install and go with the search_api_pages module, which allows you to configure multiple search pages. However, what is non-obvious is that a starting point for the next step is to use a view. 

I'm going to repeat it, because it stumped me for so long (avoid my pain, retain sanity):

Go look at your Views. 
 

Check your list of views in /admin/structure/views. If you've used Acquia Search, the Acquia search module will have created a new view for you for a basic search page.

If you don't see an existing view, click the "+Add View" button to add a new view. Under the 'View Settings' section, in the "Show:" drop-down, you should now see the index you configured in the previous step. Use this to create a new view, if you don't already have one. Now, either create a page or a block for this view and place it on your site. At this point, you should be able to confirm that your view renders a search box and returns results from your index. 

A picture of a Drupal view.

With this view, you can control the outputting for search results using all the standard configuration options of Drupal views. When you take a look at the output of the view, you may wonder the following:

Where is my fulltext search box? 

The fulltext search box does not automatically show up on the page. It's actually in a block. If you go to your Block Layout page (/admin/structure/block), and pick a region, and click the 'Place Block' button, there will be a block for the exposed form from your view. So use Drupal's block placing and configuring mechanics to place the block on your search page as you want. 

Moving on...

To be sure you're ready to move on, at this point you should have a page you can visit where the view shows up (either as a block of a page). You should be able to get results from your index and you should be able to search for an and retrieve data from the fields you added to your index above. The point here is to confirm that the fields you want indexed are actually in your index. If you're not seeing that data in your search results, stop here and re-examine your config.

5. Configure the facets

Next it's time to configure some facets. Go to /admin/config/search/facets and click the "+Add Facet" button to add a facet. What you should see is the View that you configured above as an option to be the facet source. Select the view. You should then see a list of fields. These should be fields that you've already set up to be indexed. Select the field you want to become a facet. It will want a name for the facet and will auto-generate one. Usually the auto-generated ones are fine. 

Once you save the facet, you'll get taken to the facet 'Edit' page. This provides a slew of options for the facet, relating to the appearance, logic options, and behavior. If you're configuring a taxonomy vocabulary as a set of facets, be sure the "List Item Label" and "Transform entity id into label" boxes are checked:

A picture of a page within the Drupal Administrative Interface.

 

Where are my facets?

When you create a new facet and configure it, behind the scenes, a new block for the facet set is created for you. Since the facet set is in a block you can place it anywhere a block can be placed. So go to /admin/structure/block, and pick a region where you want the facet to be placed. Click the "Place Block" button and you'll get a list of blocks you can place. Lo and Behold, if you scroll down, you should see a block for every facet you configured: 

A picture of a page within the Drupal Administrative Interface.

 

That should be the last piece of the puzzle to getting facets to show up on your site, with results fed from your Solr index. You can now style and place the facets just as you would any other block content. 
 

Conclusion

The steps above should get you going adding Solr search to your site and getting facets from your Solr index displayed. It's awesome that these pieces are in place and working for Drupal 8. I hope this article helps your Drupal projects harness these powerful tools.