Getting Started with Search API in Drupal

Implementing powerful search functionality in Drupal requires more than the default search module. Search API provides flexible search capabilities with support for multiple backends, faceted filtering, and advanced content indexing.

In the video above, you’ll learn how to install and configure Search API, create search indexes with custom processors, display search results using Views, implement faceted filtering, and integrate Apache Solr using DDEV for enhanced search.

Understanding Search in Drupal

Drupal core includes a basic search module, enabled by default, offering simple keyword search on the /search page for content and users. While adequate for small sites with basic needs, its limited customization and lack of features like faceted filtering, relevance tuning, or external integration mean most production sites opt for Search API.

Why Search API

Search API abstracts the search backend from your search configuration, enabling you to switch between different search engines without rebuilding your search interface. You can start with database search and migrate to Apache Solr or Elasticsearch as your site scales.

The module provides granular control over:

• Field selection: Choose exactly which fields to index.
• Content processing: Apply filters and transformations to indexed content.
• Relevance boosting: Control which content appears higher in results.
• Multiple indexes: Create separate indexes for different content types or use cases.

Search API integrates seamlessly with Views, allowing you to build custom search pages using familiar Drupal tools.

Installing Search API

Composer Installation

Install Search API and the database search backend using Composer:

composer require 'drupal/search_api:^1.40'

Navigate to Extend and enable these modules:

• Search API: Core functionality for indexing and searching.
• Database Search: Backend that stores indexed content in your Drupal database.

The Database Search Defaults module provides example configuration. Install it to see how Search API can be configured, then uninstall it after reviewing the settings.

Configuring the Search Server

Creating a Database Server

Navigate to Configuration > Search API to access the Search API configuration page.

To create a search server:

1. Click Add server in the top right corner.
2. Enter a server name (e.g., “Database”).
3. Select Database as the backend.
4. Configure these settings:
   • Minimum word length: Set to 3 to exclude very short words from indexing.
   • Partial matching: Configure prefix/suffix matching options.
   • Phrase indexing: Control how phrase searches work.
5. Click Save.

Start with default settings for these advanced options. Only modify them when specific client requirements emerge. Making too many changes initially can produce unexpected results that are difficult to debug.

Backend Options

The database backend stores indexed content in your Drupal database tables. This approach works well for sites with moderate content volumes (up to several thousand items).

After installing Search API Solr, you’ll see Apache Solr as an additional backend option.

Creating the Search Index

Index Configuration

From the Search API configuration page, click Add index to create a new search index.

Configure these basic settings:

1. Enter an Index name (e.g., “Content”).
2. Select Content from the Data sources dropdown.
3. Choose Bundles (content types) to include in the index.
4. Select your Server (the database server you created).
5. Enable Index items immediately or configure cron-based indexing.
6. Click Save.

You can create multiple search indexes on a single site. Some implementations use separate indexes for different content types or different backends for various purposes.

Content Type Selection

The Bundles section controls which content types get indexed. On a standard Drupal site, you might have five to ten content types. Select only the content types that should appear in search results.

Excluding certain content types from search improves performance and search results.

Adding Fields to the Index

Field Selection

Click the Fields tab to specify which fields to index.

Click Add fields to access the field browser.

The interface organizes fields by category:

General Fields:

• Authored by: User reference for filtering by author.
• Authored on: Date field for filtering by publication date.
• Content type: The bundle machine name.

Content Fields:

• Title: The content title.
• Body: Main content field.
• Category: Taxonomy term reference.
• Tags: Additional taxonomy references.

Entity Reference Fields

Entity reference fields like Category and Tags require special consideration. Click Expand next to these fields to access nested properties.

For basic faceting functionality, add the entity reference field itself (which stores the entity ID). For full-text searching of taxonomy term names, expand the field and add the Name property (or any field you want to search).

The entity ID works perfectly for faceted filtering, where you filter by specific terms or categories. The name property enables keyword searches that match taxonomy term names.

Rendered HTML Output

Most of the time you’ll want to add the Rendered HTML output field to your index. This field provides complete coverage for complex content structures, particularly when using paragraphs.

To configure the rendered item:

1. Click Add fields.
2. Locate Rendered HTML output in the field list.
3. Select Anonymous as the user role (Drupal renders the content as an anonymous user would see it).
4. Choose a View mode (typically Default) that displays all content you want indexed.
5. Click Save.

The rendered HTML output helps with indexing paragraphs. Rather than adding every paragraph field individually (which becomes unmanageable with 10+ paragraph types), this field indexes the complete HTML output of your content, capturing all paragraph content automatically.

Field Types

The Type column determines how Search API processes each field:

• Fulltext: Enables fuzzy searching and keyword matching. Use for body fields, titles, and rendered items.
• String: Stores exact text values. Use for content type names.
• Integer: Stores numeric values. Use for entity references (user IDs, term IDs, node IDs).
• Date: Stores date values for date-based filtering.

Advanced search backends like Apache Solr offer additional field types with specialized search capabilities.

Boosting Fields

The Boost column controls field importance in search relevance calculations. Higher boost values make matches in that field appear higher in search results.

You might boost:

• Title: 8.0 (keyword matches in titles should rank very high).
• Body: 1.0 (default relevance).
• Tags: 2.0 (moderate boost for categorization keywords).

Adjust boosting values after testing search behavior. Start with defaults and refine based on actual usage patterns.

After configuring fields, click Save changes.

Configuring Processors

Understanding Processors

Processors transform and filter content before indexing. They control how Search API handles text, enforces access permissions, and prepares content for searching.

Click the Processors tab to configure these options. The available processors vary based on your backend. Some processors apply specifically to database search, while others work with Apache Solr.

Essential Processors

Enable these processors for most search implementations:

Content access: Ensures only published, accessible content appears in search results. This processor prevents unpublished nodes or content the user lacks permission to view from appearing in results.

Entity status: Filters out unpublished entities automatically.

Highlight: Highlights search keywords in result excerpts, making it easier for users to see why results matched their query.

HTML filter: Processes the rendered item field, extracting text from HTML and applying element-specific boosting. This processor proves critical when indexing rendered HTML output.

Ignore case: Converts all text to lowercase, making searches case-insensitive.

Stopwords: Removes common words (the, a, an, of, etc.) from the index to reduce index size and improve relevance.

Tokenizer: Splits text into individual words for indexing.

Type-specific boosting: Applies different relevance weights to different content types.

HTML Filter Configuration

The HTML filter enables sophisticated relevance tuning based on HTML structure. If your content uses proper semantic HTML with heading tags (H1, H2, H3) and strong tags, you can boost these elements.

Configure element weights in the HTML filter settings:

• H1: 8 boost.
• H2: 5 boost.
• H3: 3 boost.
• Strong: 2 boost.

This configuration works well on structured content and enables content editors to influence search relevance by using proper heading hierarchy and emphasis.

Processor Order

Processors execute in a specific order. Search API displays the processor order and allows you to reorder processors when necessary. The default order works well for most implementations.

After configuring processors, click Save to apply your changes.

Indexing Content

Manual Indexing

Click the View tab to see indexing status. The status display shows total items and indexed items.

To index content immediately:

1. Scroll to the bottom of the page.
2. Click Index now.
3. Search API processes all pending items.

For sites with thousands of items, indexing may take several minutes. The progress indicator shows how many items have been processed.

Automated Indexing

Configure cron-based indexing for automatic updates:

1. Navigate to Configuration > Search API.
2. Click Edit on your index.
3. Set Index items immediately to control when new content gets indexed.
4. Configure Cron batch size to control how many items index per cron run.

Running cron (drush cron) automatically indexes pending content based on these settings.

Reindexing After Changes

Any change to indexed fields or processors requires reindexing. Search API displays a warning message when reindexing becomes necessary.

To reindex all content:

1. Navigate to your index.
2. Click the View tab.
3. Scroll to the bottom.
4. Click Queue all items for reindexing.
5. Click Index now or wait for cron to process the queue.

Viewing Indexed Data

To see how Search API stores your indexed content, access your database using a tool like Adminer or phpMyAdmin.

Search for tables beginning with search_api_db_. The database backend creates multiple tables:

• search_api_db_INDEX: Main index table with metadata.
• search_api_db_INDEX_text: Full-text fields with individual words.
• search_api_db_INDEX_[field_name]: Individual tables for specific fields.

The text table typically contains the most rows. A site with 200 content items might generate 100,000+ rows in the text table as each word from each field creates a separate row.

Creating Search Views

View Configuration

Navigate to Structure > Views > Add view to create a search results page.

Configure the view:

1. Set View name to “Search index”.
2. Select Index Content as the show option.
3. Choose your Search API index from the dropdown.
4. Check Create a page.
5. Set Page title to “Search index”.
6. Set Path to “/search-index”.
7. Set Display format to “Table” or “Unformatted list”.
8. Click Save and edit.

Adding Fields

Remove the default fields and add search-specific fields:

1. Remove Body (indexed field) if it appears by default.
2. Add Title (indexed field).
3. Add Search: Excerpt to display matched text snippets with highlighted keywords.

The excerpt field automatically generates text snippets containing the search keywords with highlighting applied by the Highlight processor.

Configure the Title field:

1. Click Settings on the Title field.
2. Check Link to entity to make titles clickable.
3. Click Apply.

Adding Exposed Filters

Create the search box by adding an exposed filter:

1. Click Add in the Filter criteria section.
2. Select Fulltext search (from the Search category).
3. Check Expose this filter to visitors.
4. Set Label to “Search” or “Keywords”.
5. Configure Placeholder text if desired.
6. Click Apply.

The fulltext search filter searches across all full-text fields in your index (Body, Rendered HTML output).

Sort Criteria

Add relevance-based sorting:

1. Remove any existing sort criteria.
2. Click Add in Sort criteria.
3. Select Relevance from the Search category.
4. Set order to Descending (highest relevance first).
5. Click Apply.

No Results Behavior

Configure the empty results message:

1. Click Add in No results behavior.
2. Select Global: Text area.
3. Enter “No results returned” or customize your message.
4. Click Apply.

Result Summary

Add a result count to the header:

1. Click Add in Header.
2. Select Global: Result summary.
3. Configure the display text (default shows “Displaying @start – @end of @total”).
4. Click Apply.

Save the view to make your search page available at /search-index.

Installing and Configuring Facets

Facets Module Installation

Install the Facets (3.0.2) and Better Exposed Filters (7.1.1) modules using Composer:

composer require 'drupal/facets:^3.0'
composer require 'drupal/better_exposed_filters:^7.1'

Navigate to Extend and enable:

• Facets: Core faceting functionality.
• Facets Exposed Filters: Integration with Views exposed filters.

Better Exposed Filters provides enhanced styling and control options for exposed filters, including checkbox and radio button displays.

Adding Facets to Views

Edit your search view and add faceted filters:

1. Click Add in Filter criteria.
2. Select fields from the Facets section:
   • Authored by (user reference).
   • Category (taxonomy term).
   • Content type.
   • Tags (taxonomy term).
3. Click Apply.

Transforming Entity IDs to Labels

By default, facets display entity IDs (numbers) rather than readable labels. To show user names, taxonomy term names, and content type labels:

1. Click Settings on each facet filter.
2. Check Transform entity ID to label.
3. Click Apply.

This transformation ensures users see “Article” instead of “article” and “Tag name” instead of “5”.

Displaying Result Counts

Show the number of results for each facet option:

1. Click Settings on each facet.
2. Check Show the amount of results.
3. Click Apply.

Result counts appear next to each facet option (e.g., “Article (45)”), helping users understand how filtering will affect their results.

Changing to Checkboxes

Multi-select elements provide a poor user experience. Convert facets to checkboxes using Better Exposed Filters:

1. Expand Advanced in your view.
2. Change from Basic to Better Exposed Filters.
3. Click Settings on Better Exposed Filters.
4. For each facet field:
   • Change Exposed filter widget to Checkboxes/Radio Buttons.
5. Click Apply.

Checkboxes enable users to select multiple filter options simultaneously and see applied filters clearly.

Configuring Soft Limits

For facets with many options (tags with hundreds of terms), use soft limits to show only the most relevant options initially:

1. Click Settings on the facet.
2. Find the Soft limit dropdown.
3. Set a reasonable limit (5-10 items).
4. Adjust Show more / Show less labels.
5. Click Apply.

This configuration prevents overwhelming users with extensive lists while maintaining access to all options through the “Show more” link.

Additional Facet Options

Other useful facet settings include:

• Hide facet when only one result exists: Prevents pointless filtering when only one option appears.
• Sort by: Choose to sort by count (most results first) or alphabetically.
• Active state: Controls whether selected facets appear at the top of the list.

Save your view after configuring all facets.

Displaying Facets as Blocks

Views exposed filters appear above the results by default. To place facets in a sidebar:

1. Expand Advanced in your view.
2. Click No on Exposed form in block and set to Yes.
3. Navigate to Structure > Block layout.
4. Click Place block in your desired region (Sidebar first, etc.).
5. Find your view’s exposed filters block.
6. Configure block settings.
7. Click Save block.

This placement creates a familiar faceted search interface with filters in a sidebar and results in the main content area.

Integrating Apache Solr with DDEV

Why Apache Solr

The database backend works adequately for small to medium sites. As your content grows beyond several thousand items, database search performance degrades. Full-text searches across 100,000+ database rows become slow and resource-intensive.

Apache Solr provides:

• Superior performance: Optimized for search workloads.
• Advanced features: Fuzzy matching, wildcard searches, spell correction.
• Scalability: Handles millions of documents efficiently.
• Dedicated resources: Separates search load from your database.

For production sites expecting significant traffic or content growth, Apache Solr is the recommended solution.

Installing Solr in DDEV

DDEV provides an official Solr add-on that simplifies local Solr development.

Install the DDEV Solr addon:

ddev add-on get ddev/ddev-solr
ddev restart

This command downloads and configures a Solr instance accessible from your Drupal site. The Solr server runs at http://solr:8983 from within the DDEV environment.

Installing Search API Solr

Install the Search API Solr (4.3.10) module:

composer require 'drupal/search_api_solr:^4.3'

Navigate to Extend and enable:

• Search API Solr: Core Solr integration.
• Search API Solr Admin: Upload configuration files to Solr.

The Admin module enables you to upload Solr configuration sets directly from Drupal’s interface, simplifying initial setup.

Creating a Solr Server

Navigate to Configuration > Search API and create a new server:

1. Click Add server.
2. Enter a server name (e.g., “Solr”).
3. Select Solr as the backend.
4. Configure the connection settings:
   • HTTP protocol: http.
   • Solr node: solr (not localhost when using DDEV).
   • Solr port: 8983.
   • Solr path: /.
   • Solr core: drupal (or create a custom core name).
5. Add HTTP basic authentication (default values):
   • Username: solr
   • Password: SolrRocks
6. Click Save.

Critical: Change the host from “localhost” to “solr” when using DDEV. The Drupal container communicates with the Solr container using the internal Docker network name.

Uploading the Configuration Set

After creating the Solr server, upload the configuration files:

1. Navigate to your Solr server view page.
2. Click Upload Configset.
3. Search API Solr generates a configuration package specific to your Solr version.
4. The configuration uploads automatically to your Solr core.

This configuration includes schema definitions, field types, and Solr-specific settings optimized for Drupal search.

Note: You’ll only see the Upload Configset button if you enable Search API Solr Admin.

Switching Index Backend

To migrate your existing index to use Solr:

1. Navigate to Configuration > Search API.
2. Click Edit on your content index.
3. Change Server from “Database” to “Solr”.
4. Click Save.
5. Click Queue all items for reindexing on the View tab.
6. Click Index now to reindex with Solr.

Search API uses the configured field and processor settings in the new backend automatically. Some processors may require reconfiguration as Solr handles certain operations (like case normalization) internally.

Verifying Solr Integration

Test the Solr integration:

1. Visit your search view at /search-index.
2. Perform searches to verify results appear correctly.
3. Test faceted filtering to ensure facets update properly.

Using Solr Admin

Access the Solr administration interface to monitor and debug your search:

1. Navigate to http://[your-site].ddev.site:8943 in your browser (get the correct path by running ddev status).
2. Select your core from the Collection Selector dropdown.
3. Use the Query interface to test searches directly against Solr.

Summary

Search API provides enterprise-grade search functionality for Drupal, abstracting backend complexity so you can build sophisticated search interfaces with familiar tools. Start with the database backend for development, then migrate to Apache Solr as your site scales.

The Search API ecosystem includes additional modules for autocomplete, spell checking, and geographic search as your requirements grow.