Advertising sustains the DA. Ads are hidden for members. Join today

On this page

Adding fields

Last updated on
3 September 2025

After the basic index settings, choose which Drupal fields should be indexed. See the section on Selecting the indexed fields in Search API's documentation on Adding an index for more information.

If you've set your Index to Read-only because you intend for something other than Drupal to make changes to the index (e.g.: Elastic web crawler), then you can skip this page (i.e.: the process of adding fields to the index and configuring their data type).

Start by clicking Save and add fields from the basic index settings form, or edit an existing index and click the Fields action.

Field selection part 1: Choosing fields to index

In the first step, you choose which fields to add to the index: you will choose their data types in the second step.

If you are editing an existing index, you won't see this step when you click Fields in the primary tabs for the index: if you want to select additional fields, click the Add Fields button at the top of the page.

Datasources and field tables

On the Add fields to index form, you see several tables: the first table has a General label, and there is an additional table for each Datasource you chose in the basic index settings. Each row in the table represents a field that you can add to the search index.

By selecting fields here, you are beginning the process of Mapping in Elasticsearch terminology (you will specify the Field data types in the next step of Search API's field selection process.

The General table has a list of extra / meta fields provided by Search API. See Search API's documentation on Creating custom fields using a custom processor for information about some of these fields.

Each field has a Label, Machine name, and an Add [field] button. Fields that reference other entities have an Expand button: clicking it will show the fields in the referenced entity.

Clicking the Add button for a field doesn't currently produce much visual feedback in this step.

A status message gets added to the top of the page that says "Field NAME was added to the index." — but you may not notice the new status message if you've scrolled past the top of the page.

You can add fields more than once: this may be useful if you want to process the same data in multiple ways (e.g.: a string as both a fulltext field and a keyword field). In the next step, you can also remove fields that you've added multiple times by mistake.

Which fields should I add?

Exactly which fields to add depends on your use-case.

Adding all fields won't necessarily produce better search results.

In fact, it may start producing unexpected results, e.g.: if you get search matches on a banner image's alternate text (which is often entered when a Drupal media entity is added to the media library, and likely forgotten by the time that a piece of media gets attached to a page, for example).

More fields also make Elasticsearch take up more resources, and search queries take longer.

Start with the highest-value fields, like Title, and Body, and only add additional fields you are certain that you will need to display, or that you know will produce expected results.

Most Drupal entity types have a Title, Label, or Name field: users often expect to see that in search results.

You may want to add the Title, Label, or Name field twice, so you can index it as both Fulltext (i.e.: so you can give it a Boost), and as a String. See below for what this means.

If your Drupal entity type has a Body or Content field (or similar), that's also a good choice: it gives Elasticsearch a bunch of text to match on.

If you're setting up faceted searching (i.e.: with Drupal's Facets module and Elasticsearch's Aggregations), you should add the fields that you want to facet on.

You may also add other fields if you want them to be displayed in search results.

When designing how search results should look, try to only pick fields that exist in all content types, otherwise your search results will look inconsistent.

To give an example of a more-advanced use case: if you want to use how-recently a piece of content was created or modified in your search query scoring, for example, then you might add the Authored on or Changed fields respectively to ensure the data in those fields is stored in the index for use in this advanced scoring algorithm. Note that this guide will not cover how to set up search query scoring: setting this up is left as an exercise to the user.

Next steps

When you're finished choosing fields to index, click the Done field at the bottom of the page/popup.

Field selection part 2: Assigning field data types

In the second step, you assign data types to the fields you selected in the first step.

If you are editing an existing index, you will see this page when you click Fields in the primary tabs for the index. If you want to select additional fields, click the Add Fields button at the top of the page.

Field data type selection

On the Manage fields for search index form, you see a details element for each Datatype that you selected fields for in the previous step. These details elements contain a table with one row for each field you added in the previous step. Each field has a Label, Machine name, Property path, Type, Boost, and a link to Remove that field.

There is an additional Data types details element at the bottom with some details about the data types that are available to select, and what they mean.

How should I set up the fields?

Exactly how to set up the fields depends on your use-case.

Most of the time, the default Label, Machine name, and Property path are fine.

The Label is the default label for the field on the search results page. The typical way of setting up a search results page (i.e.: with Views) lets you choose whether to show the label or not, so don't worry about removing the label from any fields.

The Machine name is the name that gets sent to Elasticsearch as part of the Mapping.

The Property path is intended to show you where Search API will be getting the data from when it sends the data to Elasticsearch.

For most use-cases, the most-important fields are the Type and Boost.

The Boost field

The Boost configures how much a match in that field affects the scoring of the document. Boost is available for fields with types Search-as-you-type, Elasticsearch Spellcheck, and Fulltext.

In situations where you've added both a Title and a Body field, it is common to give a slightly higher boost to the Title field.

This is because in many situations, a match on the Title of a document is a strong indicator that the document is relevant to the user's search query.

For example, if a user searches for "Cat", a document titled "How to care for your Cat" is more likely to be relevant to the user's search than a document that simply mentions "cat" in the body field.

The Type field

The type field affects how the data in that field is parsed by Elasticsearch.

Search API defines the Integer, Fulltext, Boolean, Decimal, String, and Date data types: please see the section on Selecting the indexed fields in the Search API documentation on Adding an index for more information about these data types.

Other Drupal modules (for example, Search API Location) can add additional data types — see the documentation for those modules for more information about the data types they add.

The Elasticsearch Connector module adds the following data types:

Next steps

When you're finished this step, click the Save changes button at the bottom of the page. Proceed to Adding processors.

Help improve this page

Page status: No known problems

You can: