Search API
Provides a generic framework for creating searches on any Drupal entity using pluggable search backends.
search_api
Install
composer require 'drupal/search_api:8.x-1.40'
Overview
Search API provides a powerful, flexible framework for site search functionality in Drupal. It allows site administrators and developers to create custom search solutions using various backend engines like Apache Solr, Elasticsearch, or the built-in database backend.
The module uses a plugin architecture with seven core plugin types: backends (search engines), datasources (content to index), data types, displays (search pages), parse modes (query interpretation), processors (data transformations), and trackers (change detection). This extensible design enables deep customization of every aspect of the search experience.
Key features include Views integration for building search pages, faceted search support through the Facets module, automatic content tracking and reindexing, full multilingual support, and a comprehensive admin UI for configuration. The module supports indexing any content entity type including nodes, users, taxonomy terms, and custom entities.
Features
- Plugin-based architecture with 7 plugin types: backends, datasources, data types, displays, parse modes, processors, and trackers
- Deep Views integration for creating search pages with exposed filters, sorts, and facets
- Support for multiple search backends including Apache Solr, Elasticsearch, and database search
- 20+ built-in processors for text transformation, access control, highlighting, stemming, and boosting
- Automatic entity tracking and reindexing when content changes
- Full multilingual and multi-site search support
- Flexible field configuration with data type mapping and boost factors
- Cron-based and on-demand batch indexing with configurable batch sizes
- Event-driven extensibility replacing legacy hooks
- 14 Drush commands for complete CLI management
- Comprehensive admin UI with interactive tours
- Read-only index mode for production environments
- Support for hierarchical field indexing (taxonomy hierarchies)
- More Like This functionality for similar content suggestions
- Random sort capability for varied search results
Use Cases
Enterprise site search with Solr
For large sites with millions of nodes, use Search API with the Solr backend. Create indexes for different content types (articles, products, pages), add processors for HTML filtering and stemming, and build multiple Views-based search pages with exposed filters and facets.
E-commerce product search
Create a search index for product entities with fields like title, description, SKU, price, and taxonomy terms. Enable processors for ignore case, stemmer, and type boost to prioritize products. Use Facets module for price range, category, and attribute filters.
Multi-site unified search
Configure multiple indexes on a shared Solr server to search across multiple Drupal sites. Use site-specific prefixes and combine with Search API Pages or custom Views for unified results.
User directory search
Create an index with the User datasource to build a searchable staff directory. Index fields like name, department, role, and profile fields. Use processors for access control based on roles.
Media library search
Index media entities with fields like name, alt text, and taxonomy tags. Enable the file content extraction processor (via Search API Attachments) to search within document content.
Quick site setup with Database Defaults
For simple sites without Solr infrastructure, enable the search_api_db_defaults module to instantly get a working search page. The module creates a database server, content index, and search View at /search/content.
Tips
- Use the Database Search Defaults module for quick initial setup, then uninstall it after configuration
- Enable the 'Index items immediately' option for small sites, but disable it for large sites to prevent performance issues
- Configure cron_limit based on your server capacity - start with 50 and adjust based on cron duration
- Use query tags like 'views_VIEW_ID' to target specific searches in event listeners
- Enable the Highlight processor and use the search_api_excerpt field in Views to show relevant snippets
- For production sites, prefer Solr over database backend for better performance and features
- Use the 'Track changes in referenced entities' option carefully - it can increase reindexing load significantly
- The search_api.settings 'disable_tracking_on_import' setting can speed up config imports on large sites
- Add 'search_api_skip_processor_highlight' tag to queries that don't need highlighting for performance
- Use Drush commands (sapi-*) for efficient index management in deployment scripts
Technical Details
Admin Pages 7
/admin/config/search/search-api
Main administration page listing all search indexes and servers. Shows status of each index (enabled/disabled), indexing progress, connected server, and provides quick actions for managing search configuration.
/admin/config/search/search-api/add-server
Create a new search server by selecting a backend plugin and configuring its connection settings.
/admin/config/search/search-api/server/{server_id}
Displays server status, backend information, and connected indexes. Shows server health and allows performing actions like clearing all indexed data.
/admin/config/search/search-api/add-index
Create a new search index by selecting datasources, tracker, server, and configuring indexing options.
/admin/config/search/search-api/index/{index_id}
Displays index status including indexing progress, datasource statistics, server connection, and cron settings. Provides controls for triggering indexing operations.
/admin/config/search/search-api/index/{index_id}/fields
Configure which fields are indexed and their settings including data type, boost factor, and machine name.
/admin/config/search/search-api/index/{index_id}/processors
Enable and configure processors that transform indexed data and search queries.
Permissions 1
Hooks 7
hook_search_api_backend_info_alter
Alter available Search API backends (deprecated, use event instead)
hook_search_api_server_features_alter
Alter features a search server supports (deprecated)
hook_search_api_datasource_info_alter
Alter available datasource plugins (deprecated)
hook_search_api_processor_info_alter
Alter available processor plugins (deprecated)
hook_search_api_index_items_alter
Alter items before indexing (deprecated)
hook_search_api_query_alter
Alter search query before execution (deprecated)
hook_search_api_results_alter
Alter search results after execution (deprecated)
Drush Commands 16
drush search-api:list
Lists all search indexes with their status, server, and datasources
drush search-api:status [index_id]
Shows indexing status for one or all indexes including completion percentage
drush search-api:index [index_id]
Indexes items for one or all enabled search indexes
drush search-api:enable <index_id>
Enables a disabled search index
drush search-api:disable <index_id>
Disables an enabled search index
drush search-api:enable-all
Enables all disabled search indexes
drush search-api:disable-all
Disables all enabled search indexes
drush search-api:reset-tracker [index_id]
Marks items for reindexing without deleting existing data
drush search-api:rebuild-tracker [index_id]
Completely rebuilds tracker information from scratch
drush search-api:clear [index_id]
Clears all indexed data and marks for reindexing
drush search-api:search <index_id> <keyword>
Searches for a keyword in a given index
drush search-api:server-list
Lists all search servers with their status
drush search-api:server-enable <server_id>
Enables a disabled search server
drush search-api:server-disable <server_id>
Disables an enabled search server
drush search-api:server-clear <server_id>
Clears all indexed data on a search server
drush search-api:set-index-server <index_id> <server_id>
Sets the server for an index
Troubleshooting 8
Check that the index is enabled, cron_limit is > 0, and there are no pending tasks. Run 'drush sapi-s' to check status and 'drush search-api:index' to manually trigger indexing.
Verify items are indexed (check the index View tab), ensure the search View is querying the correct index, and check that field types match query expectations (fulltext vs string).
Ensure the database user has CREATE TEMPORARY TABLES permission. This is required for facet aggregation queries.
Check for multiple datasources or aliases. Ensure entity IDs are unique across datasources. Review View distinct settings.
Reduce cron_limit for memory-constrained environments. Use batch indexing via Drush with appropriate batch-size settings. Consider disabling index_directly option.
Items may be queued but not yet indexed. Check for pending tasks, verify cron is running, or manually trigger reindex. If track_changes_in_references is disabled, changes to referenced entities won't trigger reindex.
For external backends (Solr/Elasticsearch), verify server is running and accessible. Check backend configuration settings. Review Drupal logs for specific error messages.
Reduce batch_size, enable index_directly to spread indexing over time, or increase PHP memory_limit. Database backend is more memory-intensive than Solr.
Security Notes 7
- The 'administer search_api' permission grants full control - assign only to trusted administrators
- Enable the Content access processor to respect node access permissions in search results
- Enable the Entity status processor to exclude unpublished content from indexing
- Enable the Role-based access processor for role-specific content visibility
- Review indexed fields carefully - avoid indexing sensitive data that shouldn't be searchable
- Database backend stores indexed data in database tables - ensure appropriate database security
- When using external backends like Solr, secure the connection and restrict server access