Search API Synonym
Allows editors and administrators to manage search synonyms and spelling corrections directly in Drupal, with support for import/export functionality.
search_api_synonym
Install
composer require 'drupal/search_api_synonym:^2.0'
Overview
Search API Synonym provides a comprehensive solution for managing search synonyms and spelling error corrections within Drupal. The module creates a custom content entity type for storing synonym definitions, which can be used with search backends like Apache Solr.
Administrators can create synonym entries that associate a word with related synonyms or correct common spelling errors. The module supports both manual entry through an administrative interface and bulk import from external files in multiple formats including Solr synonyms.txt, CSV, and JSON.
Exported synonym files can be generated via Drush commands, Drupal Console commands, or automated cron jobs. The Solr export format is compatible with Apache Solr's synonyms.txt configuration, making it easy to deploy synonyms to your search infrastructure.
Features
- Custom Synonym entity type with fields for word, synonyms, type (synonym or spelling error), language, and active status
- Administrative interface with Views-based listing, filtering by word, synonyms, type, status, and language
- Import functionality supporting multiple file formats: Solr synonyms.txt, CSV with configurable delimiters, and JSON
- Export functionality to Solr-compatible synonyms.txt format with support for language-specific files
- Drush command (search-api-synonym:export) for command-line synonym exports
- Drupal Console command (searchapi:synonym:export) for exports
- Cron-based automatic export with configurable intervals and incremental export options
- Support for synonyms with and without spaces, exportable to separate files
- Views integration with comprehensive field, filter, and sort handlers
- Multilingual support with per-language synonym definitions
- Plugin system allowing developers to add custom import and export formats
- Hook for reacting when synonym files are saved (hook_search_api_synonym_synonyms_file_saved)
Use Cases
E-commerce Product Search Enhancement
Create synonyms for product categories and common terminology. For example, 'laptop' could be synonymous with 'notebook computer', 'portable computer'. This ensures customers find products regardless of the specific term they search for.
Spelling Error Correction
Define common misspellings that should be corrected during search. For example, 'recieve' => 'receive' or 'accomodation' => 'accommodation'. The spelling error type uses replacement mappings so searches for misspelled words return results for the correct spelling.
Multilingual Synonym Management
For multilingual sites, create language-specific synonym sets. German synonyms can be managed separately from English, with each language exporting to its own synonyms file for the appropriate Solr core or collection.
Technical Documentation Search
In technical documentation sites, create synonyms for abbreviations and full terms. For example, 'API' could be synonymous with 'Application Programming Interface', and 'REST' with 'Representational State Transfer'.
Automated Solr Deployment
Configure cron-based export to automatically generate updated synonym files. Use the hook_search_api_synonym_synonyms_file_saved hook to automatically deploy the file to your Solr server when changes are detected.
Bulk Synonym Import from Existing Systems
Use the import functionality to migrate synonyms from an existing Solr synonyms.txt file, a CSV export from another system, or a JSON file from a synonym database. The merge option allows combining imported synonyms with existing entries.
Tips
- Use the 'Separate files' option when exporting to Solr if you have both single-word and multi-word synonyms, as Solr may handle these differently depending on your tokenizer configuration.
- For large synonym sets, use the 'Only export if changes' option to avoid unnecessary file regeneration during cron runs.
- When importing from CSV, use semicolon as delimiter if your synonym values contain commas to avoid parsing issues.
- The hook_search_api_synonym_synonyms_file_saved hook is ideal for integrating with deployment pipelines to automatically push synonym files to remote Solr servers.
- Use the incremental export option in Drush commands for faster exports when only checking for recent changes.
- Consider creating separate synonym entries for each direction if bidirectional synonyms are needed, as the Solr format treats each line as its own mapping.
Technical Details
Admin Pages 6
/admin/config/search/search-api-synonyms
Main administration page for managing search synonyms. Displays a Views-based table listing all synonyms with columns for word, synonyms, type, language, author, status, and last updated date. Includes exposed filters for searching and filtering the list.
/admin/config/search/search-api-synonyms/add
Form for creating a new synonym entry. Allows specifying the word, its synonyms, type (synonym or spelling error), language, and active status.
/admin/config/search/search-api-synonyms/{search_api_synonym}/edit
Form for editing an existing synonym entry. Same fields as the add form.
/admin/config/search/search-api-synonyms/settings
Configure cron-based automatic export of synonyms. Settings control how often exports run, which plugin format to use, and filtering options.
/admin/config/search/search-api-synonyms/import
Form for bulk importing synonyms from external files. Supports multiple file formats and provides options for handling existing synonyms.
/admin/config/search/search-api-synonyms/delete-all
Confirmation form for deleting all synonym entries. This action cannot be undone.
Permissions 4
Hooks 1
hook_search_api_synonym_synonyms_file_saved
Invoked after a synonyms file has been saved during export. Allows modules to react to file changes, for example to deploy the file to a search server.
Drush Commands 1
drush search-api-synonym:export
Export search synonyms to a file in the specified format. Supports filtering by language, type, and word spacing.
Troubleshooting 5
Verify the export directory exists and is writable. Check the 'File Export location' setting in /admin/config/search/search-api-synonyms/settings. The default location is 'public://synonyms'. Ensure the web server has write permissions to this directory.
Check the 'Export synonyms every' setting is not set to 'Never'. Verify that cron is running on your site. If using 'Only export if changes', ensure there are actually new or modified synonyms since the last export.
Verify the file extension matches the selected import plugin (txt for Solr, csv/txt for CSV, json for JSON). Check PHP upload limits (upload_max_filesize, post_max_size) if the file is large.
Ensure synonyms are marked as 'active'. Export the synonyms file and verify it contains the expected entries. Deploy the exported file to your Solr configuration and reload the Solr core/collection.
Spelling errors use replacement mapping format (misspelling => correct). Verify your Solr schema is configured to use the synonyms file in the appropriate analyzer chain, typically in the query analyzer.
Security Notes 3
- Import functionality allows file uploads - ensure the 'import search api synonyms' permission is granted only to trusted users.
- The module validates file extensions during import based on the selected plugin to prevent upload of unauthorized file types.
- Exported synonym files are saved to the public files directory by default - consider using a private directory if synonym data should not be publicly accessible.