README

Table of Contents

• Overview
• Requirements
• Installation
• Upgrading
• Setup
• Schema Updates
• Core Reloading
• Pantheon Environments
• Diagnostic Commands
• Troubleshooting
• Solr Jargon
• Feedback and Collaboration

Overview

This module provides Drupal 10+ integration with Apache Solr (versions 8 and 9) on Pantheon's Platform, simplifying the usage of Search API and Search API Solr.

Search API Solr provides the ability to connect to any Solr server by providing numerous configuration options. This module automatically sets the Solr connection options by extending the plugin from Search API Solr. The module also changes its connection information based on different Pantheon environments and each Pantheon Environment has its own Solr Core. Doing so eliminates the need to do extra work setting up Solr servers for each environment.

Solr Versions on Pantheon

• Solr 8: Apache Solr 8.11.4
• Solr 9: Apache Solr 9.10.1

Requirements

• Drupal 10 or 11
• PHP 8.1 or later (tested through PHP 8.5)
• Search API Solr 4.3.x
• Hosting on Pantheon's platform
• Composer-based workflow using one of the following:
  • Pantheon's integrated composer (build step: true in your pantheon.yml)
  • A CI/CD service (e.g., GitHub Actions, CircleCI)
• Dashboard access to the platform (necessary to deploy code changes)

Installation

Stable Release

composer require 'drupal/search_api_pantheon:^8'

Development Version

composer require 'drupal/search_api_pantheon:8.5.x-dev@dev'

Upgrading

Upgrading from an earlier version? See UPGRADE.md for detailed migration guides:

• Upgrading from 8.4.x to 8.5.x
• Upgrading from Solr 8 to Solr 9
• Schema incompatibility with Search API Solr 4.3.x

Setup

Enable Solr on Pantheon

Under "Settings" in your Pantheon site dashboard, enable Solr as an add on. This feature is available for sandbox sites as well as paid plans at the Professional level and above.

Configure pantheon.yml

Add or update the following in your pantheon.yml file:

search:
  version: 9

Or, to use Solr 8:

search:
  version: 8

As you deploy code, the pantheon.yml file will follow the code through environments enabling the Solr server. However you will need to create an index for each environment and ensure the content is indexed after creation. Solr indices are environment-specific and cannot be exported or moved once created.

Enable the Modules

• Go to admin/modules and enable "Search API Pantheon."
• Doing so will also enable Search API and Search API Solr if they are not already enabled.

OPTIONAL: Disable Drupal Core's search module

If you are using Search API, you probably will not be using Drupal Core's Search module. Uninstall it to save some confusion in the further configuration steps: admin/modules/uninstall.

Verify Installation

• Navigate in the Drupal interface to CONFIG => SEARCH & METADATA => SEARCH API
• Validate that the PANTHEON SEARCH server and Primary Index exist and are "enabled".

Use the Server with an Index

When you enable the Search API Pantheon module, a Primary index is automatically created and linked to the Pantheon search server. You can use this default index or create your own custom index.

To use the default 'Primary' index:

• Go to admin/config/search/search-api and select the "Primary" index
• Configure fields to be indexed by selecting the "Fields" tab
• Add fields you want to search (e.g., "Title", "Body", etc.)
• Click "Save" to save your field configuration
• Post the schema (see Schema Updates below)
• Click "Index now" to populate the index with your content. Alternatively, content will be indexed automatically when cron runs.

To create a custom index:

• Go to admin/config/search/search-api/add-index
• Name your index and choose a data source. If this is your first time using Search API, start by selecting "Content" as a data source. That option will index the articles, basic pages, and other node types you have configured.
• Select "Pantheon Search" as the server
• Save the index
• Configure fields to be searched by selecting the "Fields" tab. You may want to index many fields. "Title" is a good field to start with.
• Click "Save" to save your field configuration
• Post the schema (see Schema Updates below)
• Click "Index now" to populate the index with your content. Alternatively, content will be indexed automatically when cron runs.

Search the Index

• Create a new view using the search index of type 'Index'.
• Add fields to be included in the search results. Include the 'relevance' field to enable sorting by relevance.
• Expose the search keywords filter to allow users to enter search terms.
• Sort results by the "relevance" field. Solr assigns higher relevance ratings to documents that better match the search terms.

Export Your Changes

It is a best practice in Drupal to export your changes to yml files. Using Terminus while in SFTP mode, you can run terminus drush <site>.<env> -- "config:export -y" to export the configuration changes you have made. Once committed, these changes can be deployed out to Test and Live environments.

Schema Updates

The default schema Pantheon provisions with a new Solr container depends on the Solr version:

• Solr 9: The 4.3.10 version of the Solr 9 jump-start config-set from Search API Solr module
• Solr 8: The 4.2.1 version of the Solr 8 jump-start config-set from Search API Solr module

When you first create your index or alter it significantly, you will need to update the schema on the Solr server.

Running with an outdated schema can cause broken search, indexing errors, and missing features such as highlighting or autocomplete. Specifically, you should update the schema:

• After initial module installation
• After adding new Solr field types (e.g., custom analyzers or tokenizers) that are not already defined in the schema
• After upgrading search_api_solr to a version that changes the generated schema (e.g., 4.2.x → 4.3.x)
• After switching Solr versions (8 ↔ 9) — see UPGRADE.md
• After enabling or disabling Search API Solr sub-modules (e.g., multilingual, autocomplete)

Schema updates can be performed using:

terminus drush <site>.<env> -- search-api-pantheon:postSchema [path]

The [path] argument is optional. Provide it only if you want to use a custom config-set directory. If omitted, the module uses Search API Solr to generate config files that match your installed module version and Solr version.

Once you have enabled the Search API Pantheon module, when you reload the schema the module will use the config-set for the version of the Search API Solr module installed in your codebase. See the Search API Solr 4.3.0 release notes for more information about upgrading to a 4.3.0+ compatible schema.

Examples

Auto-generated config: Generates schema files based on your Solr version, Search API Solr version, and index configuration.

terminus drush <site>.<env> -- search-api-pantheon:postSchema

Jump-start config-set from Search API Solr: Uses the pre-built config-set bundled with the Search API Solr module. Useful if you want a known baseline without any site-specific customizations.

terminus drush <site>.<env> -- search-api-pantheon:postSchema /code/web/modules/contrib/search_api_solr/jump-start/solr9/config-set/
terminus drush <site>.<env> -- search-api-pantheon:postSchema /code/web/modules/contrib/search_api_solr/jump-start/solr8/config-set/

Custom config-set directory: Uses your own schema files. For advanced use cases where you need custom analyzers, tokenizers, or field types beyond what the module generates.

terminus drush <site>.<env> -- search-api-pantheon:postSchema /code/solr/config

For more details on using custom Solr configurations, see Pantheon's custom config guide.

Core Reloading

Automatic Core Reload

Search API Pantheon automatically reloads the Solr core after schema updates to prevent schema reversions and maintain index integrity.

Manual Core Reload

If needed, manually reload the core using:

terminus drush <site>.<env> -- search-api-solr:reload

Pantheon Environments

Each Pantheon environment (Dev, Test, Live, and Multidevs) has its own Solr server. Indexing and searching in one environment does not impact any other environment.

When you enable the Search API Pantheon module, 'Pantheon Search' server is automatically installed by default. The Pantheon connector supports only a single Search API server per environment. Creating additional servers using the Pantheon connector will cause all servers to point to the same Solr core, which may result in schema conflicts or unexpected indexing behavior.

Diagnostic Commands

Diagnostic commands automatically use the first server connected via Pantheon connector. The server_id argument is no longer needed or accepted.

Troubleshooting

Common Issues

Solr Jargon

Feedback and Collaboration

Bug reports, feature requests, and feedback should be posted in the drupal.org issue queue. For code changes, please submit pull requests against the GitHub repository.