- Introduction
- Requirements
- Installation
- Configuration
- Developers
- Maintainers
This module provides a framework for easily creating searches on any entity known to Drupal, using any kind of search engine. For site administrators, it is a great alternative to other search solutions, since it already incorporates faceting support (with Facets) and the ability to use the Views module for displaying search results, filters, etc. Also, with the Apache Solr integration, a high-performance search engine is available for this module.
Developers, on the other hand, will be impressed by the large flexibility and numerous ways of extension the module provides. Hence, the growing number of additional contrib modules, providing additional functionality or helping users customize some aspects of the search process.
- For a full description of the module, visit the project page.
- To submit bug reports and feature suggestions, or to track changes, use the issue queue.
No other modules are required. If you want to use a different backend than the database (for instance, Apache Solr or Elasticsearch), you will need to install the respective module providing the required backend plugin.
- Install as you would normally install a contributed Drupal module. For further information, see Installing Drupal Modules.
After installation, for a quick start, just install the “Database Search Defaults” module provided with this project. This will automatically set up a search view for node content, using a database server for indexing.
Otherwise, you need to enable at least a module providing integration with a search backend (like database, Solr, Elasticsearch, …). Possible options are listed at Server backends and features.
Then, go to /admin/config/search/search-api on your site and create a search
server and search index. Afterwards, you can create a view based on your index
to enable users to search the content you configured to be indexed. More details
are available in Getting started. There, you can also find answers to
frequently asked questions and common pitfalls to avoid.
The Search API provides a lot of ways for developers to extend or customize the framework.
All available hooks are listed in search_api.api.php. They have been
deprecated at this point, though, and replaced by events. Hooks will be removed
from the module in version 2.0.0.
All events defined by this module are documented in
\Drupal\search_api\Event\SearchApiEvents.
In addition, the Search API’s task system (for reliably executing necessary
system tasks) makes use of events. Every time a task is executed, an event will
be fired based on the task’s type and the sub-system that scheduled the task is
responsible for reacting to it. This system is extensible and can therefore also
easily be used by contrib modules based on the Search API. For details, see the
description of the \Drupal\search_api\Task\TaskManager class, and the other
classes in src/Task for examples.
The Search API defines several plugin types, all listed in its
search_api.plugin_type.yml file. Here is a list of them, along with the
directory in which you can find their definition files (interface, plugin base
and plugin manager):
| Plugin type | Directory |
|---|---|
| Backends | src/Backend |
| Datasources | src/Datasource |
| Data types | src/DataType |
| Displays | src/Display |
| Parse modes | src/ParseMode |
| Processors | src/Processor |
| Trackers | src/Tracker |
The display plugins are a bit of a special case there, because they aren’t
really “extending” the framework, but are rather a way of telling the Search API
(and all modules integrating with it) about search pages your module defines.
They can then be used to provide, for example, faceting support for those pages.
Therefore, if your module provides any search pages, it’s a good idea to provide
display plugins for them. For an example (for Views pages), see
\Drupal\search_api\Plugin\search_api\display\ViewsPage.
For more information, see the handbook documentation for developers.
To know which parts of the module can be relied upon as its public API, please read the Drupal 8 backwards compatibility and internal API policy and the module’s issue regarding potential module-specific changes to that policy.
Server backend features are a way for other contrib modules to cleanly define ways in which the Search API can be extended. For more information, see Server backends and features.
The Search API module itself currently defines two features:
-
More Like This (
search_api_mlt) This feature can be used to retrieve a list of search results that are similar to a given indexed item. A backend that supports this feature has to recognize thesearch_api_mltquery option. If present, it contains an associative array with the following keys:id: The Search API item ID (consisting of the datasource ID and the datasource-specific item ID – passing a plain entity ID will NOT work!) of the item for which similar results should be found.fields: A simple array of fields which should be used for determining similarity. Backends can choose to ignore this field.field boosts: (optional) An associative array mapping fields to a numeric “boost” value that determines how important they should be considered when determining similarity. Backends can choose to ignore this field.
The feature can be used in the UI via the “More like this” Views contextual filter.
-
Random Sort (
search_api_random_sort) This feature allows sorting a search query randomly. Backends supporting this feature should accept sorts on fieldsearch_api_randomand, if present, apply a random sort to the search query. Optionally, they can also check thesearch_api_random_sortquery option for additional specifications, which (if present) will be an associative array with any of the following keys:seed: The seed value to use for the random function. This is important to support proper paging for randomly sorted search results.