HowTo: Add an index

Go to Search API's adminstration page at Administration > Configuration > Search and metadata > Search API (or http://example.com/admin/config/search/search-api).
If you are on this page the first time after installing the module, you will notice there is already a default index set up by the module, the Default node index. You can use this index and edit it to your needs instead of creating a new one. Its default settings should be appropriate for most basic cases when you want to search content on your site.

Adding an index

Click Add index to go to the index creation form. Here, you have to enter some information for your new index:

Index name

Any human-readable name by which your index will in the future be referenced. A good choice is to specify what kind of data will be indexed in it. E.g., Node index, Profile index, etc. This name can later be changed and is only used internally, so mistakes don't matter much.

Machine-readable name

This name will be used as a unique internal identifier for the index (e.g., in administration paths) and cannot be changed afterwards. It is usually automatically created based on the human-readable name you choose, but you can also manually edit it by clicking Edit next to the created name (once you entered something in the Index name field). It is usually only used internally.

Item type

Select the type of data you want to index and search with this index. This is the most important setting and cannot be changed afterwards.

Enabled

Here you can select whether the index will initially be enabled. Since indexes without a server cannot be enabled, this will only take effect if you also select an enabled server for the index.

Index description

This can help you make some notes on the index's purpose, e.g., for other administrators or for future reference. It will only be displayed on the index's main page and can also be left empty.

Server

The server to which the index will be initially connected, and which will therefore be used to index and search its data. You can also create an index without a server, and later change an index's server.

Read only

This allows you to create indexes which will only be used for searching existing data on a remote server. No data will be indexed to the server, or deleted from it, via the Search API. This setting can later be changed.

Index items immediately

Usually, when new items (of the index's type) are created, or old items changed, they are marked internally as dirty.

Cron batch size

When items are indexed during cron runs, this setting will determine how many items will be indexed in a single batch. Too low values for this setting might decrease indexing performance, especially with some types of servers; with too high values, on the other hand, cron runs might run out of time or memory, and no indexing at all could occur.
Use a number of items that can be indexed in about 5 to 10 seconds. You can manually index items (on the index's Status tab) to test this out.

Click Create index to finish this first step of the process. You will be automatically redirected to the new index's Fields form.

Selecting the index fields

You will see a list of all fields available for the item type of the index. Select Indexed for those fields for which you want to store data on the search server. These fields can then be searched, used for filtering and sorting, and maybe also used for other purposes.

Note that only fields of type Fulltext can be used in fulltext searches. So when you want to find individual words contained in this field, not just the whole field value, use this type. Other types can be used, e.g., for filtering and sorting.

Add related fields

Items of a certain type might be connected to, or might reference, other kinds of data. For instance, content will always have an author, could also contain references to taxonomy terms, etc. With the Add related fields form at the bottom of the page you can add the fields of those related items to the list, so they can be indexed, too. Use this if you want, e.g., to index the user roles of a node's author. You can also add nested related fields, e.g., the node's author's profile's image's file type.

Note: When indexing site content (item type Node), the actual body text is also stored as a related field in Drupal 7. Therefore, you will have to add The main body text as a related field and then index The main body text » Text to be able to search the body text.

Customizing the workflow

After selecting the fields to index, you will automatically be asked to customize the index's workflow and taken to the Filters tab. There, you can add two different kinds of plugins to the index: data alterations and processors.

Data alterations

These modify what is being indexed, by either adding or modifying fields, or filtering out certain items that would be indexed. Fields added by data alterations can also be seen on the Fields tab, and customized (or even set to unindexed) there.

You can also set the order of data alterations, which can be important in some situations. For example, you should always order data alterations that filter out items first, so other data alterations aren't run unnecessarily. Also, when a data alteration uses field data another data alteration provides/modifies, you'll have to order these two data alterations accordingly.

Processors

Processors are used for three different things: preprocessing data that is being indexed, preprocessing search queries, and postprocessing search results. The descriptions of processors should always clearly state their effect.
For processors, the order in which they are executed is often more important than for data alterations. In such cases, the processor description should indicate these considerations, too.

Note that some servers already have data processing built in. When using an index with such a kind of server, most processors should be deactivated for it. However, such cases should usually also be explained in the service class documentation, so refer to that if unsure.

Descriptions

Short descriptions of all known data alterations and processors can be found under Data alterations and processors in this handbook.

Status

The View tab is not needed while creating an index, however, it can be useful later (or immediately afterwards, to check if everything went well).

Below the information on whether the index is currently enabled, you see the current index status. (At least if the index is enabled—if it is disabled, you will see almost no other options.) This contains the number of items indexed so far in its latest state (i.e., that were not edited after being indexed the last time) as well as the total number of items to be indexed. (Note, however, that this doesn't take data alterations into account that may filter the items to be indexed.)

Below that, unless all items are already indexed, you have the option to manually index items. You can use that to index items without running cron, if you don't want to wait for that (and don't want the additional overhead of running cron manually).

Finally, you have the options to mark all items as "dirty" using the Queue all items for reindexing button (done automatically as needed, but might be necessary manually due to external modifications) or to completely clear the index (which will not only mark all items as "dirty" (i.e., unindexed), but also delete all indexed data for this index from the server).
Use these options with care, as re-indexing might take some time, depending on the size of your data set. Clearing the index might be necessary, though, when index data has become corrupt in some way. And re-indexing might be necessary when external changes to the server are made.