Basic index settings
Start from Search API's configuration at /admin/config/search/search-api and click the + Add index button at the top of the page. Or go to /admin/config/search/search-api/add-index
For more information, see the Search API documentation on Adding an index.
Name and Machine name
Start by entering an Index name. A Machine name for the Index will be generated automatically (but you can edit it by clicking the [Edit] link).
Unless you set the Index to Read-only (below), when you click Save or Save and add fields at the bottom of this page, Drupal will try to create an Elasticsearch index with a name with the following pattern:
{{server prefix}}{{index machine name}}{{server suffix}}... the server prefix and server suffix can be set in the Server advanced settings.
If you plan to connect to an index created by another piece of software (e.g.: Kibana), make sure that the index contains only lowercase characters and underscores (_).
In particular, Elasticsearch permits hyphens (-) in index names, but Elasticsearch Connector doesn't currently support them.
Datasources and datasource configuration
Choose one or more Search API Datasources by checking the checkbox in the list. You must select at least one datasource. For each datasource that you select, Search API will add a details element to this configuration page to configure it.
For most Drupal sites, you will only want to check the Content datasource (i.e.: Drupal nodes).
You only need to check the datasources that you want to show up as stand-alone search results: Search API will track reference fields automatically unless you disable the Track changes in referenced entities option below.
For example, suppose you have a site that only contains 2 pieces of content: a taxonomy term with the title "Conference"; and node with the title "DrupalCon" that is tagged with the "Conference" term.
If you check only the Content datasource on the Index, then searching for Conference will return 1 result: the "DrupalCon" node.
If you check both the Content and the Taxonomy term datasources on the Index, then searching for Conference will return 2 results: the taxonomy term landing page (e.g.: at /taxonomy/term/1) as the first result, and the "DrupalCon" node as the second result.
For many sites, a separate search result for a taxonomy term landing page is undesirable.
Out of the box, Search API displays a datasource for each Drupal content entity type (but it is possible to add additional datasource plugins to index other things in Drupal).
On a Standard Drupal Core 11.2 installation, the available data sources are Comment, Contact message, Content, Content block, Custom menu link, File, Search task, Shortcut link, Taxonomy term, URL alias, and User; but this list will vary based on which modules you have installed.
The datasource that you select tells Search API what it should expect to find in the index, and/or what it should track and upload to the index when there are changes.
Configure the type datasource
For each datasource that you check, Search API will add a details element to the configuration page to configure it.
For Drupal content entity types, this details element contains a way to:
- include/exclude certain bundles (e.g.: content types), and
- include/exclude certain languages.
If you have a multilingual site, and you don't (yet) need to use any of Elasticsearch's language analyzers, try putting all of your content into a single index to start, and see how that works for your languages and content.
It requires a bit more planning and work to switch which Search API Index you send queries to based on Drupal's Language detection and selection configuration.
Configure the Default tracker
Search API has a Tracker sub-system that sends updates to a Search API Index when Drupal's content changes. The Configure the Default tracker details element lets you change which order Drupal's content gets indexed in.
Server chooser
The Server radio-button lets you choose which Search API Server that the index is attached to.
If you have separate Elasticsearch clusters for local, staging, and production environments, you can create multiple Search API Servers (i.e.: one Search API Server for each Elasticsearch cluster); and then, for each index, use the Configuration Split module to change which Server that Index is attached to in each environment.
Enabled toggle
The Enabled checkbox allows you to quickly enable/disable the Index. Search API checks to see if an Index is enabled before doing anything with it.
Description
The optional Description text area allows you to enter a description for the Index. This is most useful when you have set up more than one index.
Some sites have a site-wide search index, and a separate, smaller index for a specific type of content.
Index options
The Index options details element contains some advanced options for the index.
Read-only
A Read-only index can only be searched: Search API won't try to send content changes to the index.
Use the Read-only option if you intend for something other than Drupal to make changes to the index (e.g.: Elastic web crawler).
Index items immediately
The Index items immediately checkbox lets you choose whether Search API's tracker sends new/changed content to this search index when the content is saved, or if it waits until the next cron run to send it.
If your index is Read-only, then Index items immediately does nothing.
Track changes in referenced entities
The Track changes in referenced entities checkbox tells Search API that it should re-index content which references another piece of content if the downstream content changes.
For example, suppose you have a site that only contains 2 pieces of content: a taxonomy term with the title "Conference"; and node with the title "DrupalCon" that is tagged with the "Conference" term.
If you change the title of the Conference term to Event, and Track changes in referenced entities is checked, then the node with the title "DrupalCon" will be reindexed automatically.
If your index is Read-only, then Track changes in referenced entities does nothing.
Cron batch size
If Index items immediately is unchecked, or you queue all content in an index for reindexing but don't perform the reindexing manually, then Search API will index content when cron runs instead. You can change how many pieces of content it indexes at a time by changing the Cron batch size.
While it is possible to change the Cron batch size to -1 to index everything at once, on a real site, you probably don't want to do this on a real site: as you add content to the site, Search API will need more and more time to index the site, until cron-runs time out, or you over-load Drupal or Elasticsearch.
Next steps
If you're creating an index, then you should see buttons to Save and Save and add fields at the bottom of the basic index settings page — in most cases you should Save and add fields, then proceed with Adding fields.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion
