5 Drush Commands for Drupal Search API and Solr

GWW Opinion

September 26, 2024

Application Development

By Jason Safro

So you’ve built a robust Drupal site incorporating Solr to optimize search capabilities. Your client loves the rich search features, but the Drupal Search API and Solr functionality brings complexity for the development team. It’s especially challenging when a site is hosted on Pantheon, because they don’t provide access to Solr administrative dashboards.

We wanted to share five Drush commands to make your life easier. These commands help you manage the internal functioning of Solr when hosting on Pantheon. Here’s how we use them to update the Solr Schema and clear malformed indexes.

The update

The Solr instance used by your Drupal site has a configuration called a schema. The Search API Solr module periodically requires schema updates. Why? Not only do updates improve search performance, but they also ensure compatibility with new versions of the Search API.

Here’s how we know when to update:

Navigate to the Search API admin screen in Drupal.
Compare the Schema Version with the Minimal and Preferred Schema Versions.
If it’s time to update, we use Composer to pull the latest version of Search API Solr, copy the schema files locally, and push the updates to Pantheon.

Screenshot of the Search API admin screen in Drupal.

The error

Solr generates indexes which are massive files that allow it to quickly respond to searches and find the data you want. These indexes can become malformed. This is particularly likely after schema updates. Error messages like the following are barely readable and highly stress inducing:

Drupal\search_api_solr\SearchApiSolrException while indexing item entity:node/10009:und: Solr endpoint http://solr:8983/ bad request (code: 400, body: Exception writing document id 31wu6z-my_solr_index-entity:node/10009:und to the index; possible analysis error: cannot change field "tm_X3b_und_title" from index options=DOCS_AND_FREQS_AND_POSITIONS to inconsistent index options=DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS

Stay with us and see below. Solr built the indexes for you, and Solr can be instructed to rebuild them.

The challenge

In this example, my team at GovWebWorks has been managing a large, content rich site for a long-time client. This site hosts tens of thousands of nodes, media, and other entities. The client opted for Search API and Solr and the site is hosted on Pantheon.

As part of regular maintenance, we just upgraded to the latest version of the Search API Solr module, which required a Solr Schema update. After the update, we found that the search indexing was failing. Solr has an administrative dashboard that is great for fixing these issues, but Pantheon, a top-tier Drupal hosting provider, does not allow direct access to the Solr administrative dashboard. What now?

The solution

Getting to a solution required a whole lot of research, trial, and error. Credit to scottsawyer (https://www.drupal.org/u/scottsawyer) for the blog post that led us in the right direction.

Our solution boiled down to five Drush commands.

Send a new schema to Solr.
```
@command search-api-pantheon:postSchema
```
Temporarily disable a search server.
```
@command search-api:server-disable
```
Dump the Solr Core (aka the index inside Solr) and rebuild it.
```
@command search-api-solr:reinstall-fieldtypes
```
Re-enables a search server.
```
@command search-api:server-enable
```
Force the Solr server to reload the core, applying config changes.
```
@command search-api-solr:reload
```

By following these steps, we cleared the indexing failures, rebuilt tracking information, and re-indexed the content.

Put together, the drush commands look like this:

# Post a schema.
terminus drush . -- sapps  /code/config/solr8


# Disable the Solr Server.
terminus drush . -- sapi-sd 


# Delete and reinstall all fields in the Solr core.
terminus drush . -- search-api-solr:reinstall-fieldtypes


# Enable the Solr Server.
terminus drush . -- sapi-se 


# Reload the Solr Server.
terminus drush . -- search-api-solr:reload

In summary

Solr may throw curveballs, but with the right tools, you can manage it successfully even in a limited environment like Pantheon. We’ve learned how to make the best of Solr with Drupal Search API. If you’re managing a complex, content-rich Drupal site, these strategies will help you keep your search running smoothly.