Frequently asked questions

This page tries to answer questions frequently asked by new users, either in the issue queue or elsewhere.

• Why aren't my facets showing?
• Why don't data alterations reduce the number of items to index?
• Why can't I index field X? / Why can't I create a search index for entity type Y?
• Why don't Search API searches find partial matches/substrings?
• Why can't I sort by field X?
• What is the "Server index status" for a search index?
• Can I index nested field collections?

Why aren't my facets showing?

First off, there are a number of reasons that apply for all facets. Check whether you've properly enabled the facet blocks to be shown somewhere (either in Admin > Structure > Blocks or using something like Panels), and that the facets are configured to be displayed for the search in question (using "Display for searches"/"Search IDs" in the facet display settings). Other settings (like "Minimum facet count" or a faulty field or workflow configuration in the index) might also lead to empty facets, depending on the site in question.

However, when your search isn't the main content on the page, or when you're using something like Panels to arrange the content on the page, there might be another, harder-to-solve problem, which has its source in the way the Search API Facets module works: the module provides blocks for all enabled facets (which can, of course, also be used by Panels or the like). When a block is requested, the module checks whether a (matching) Search API search was executed on this page request and, if so, provides facets for it. Otherwise, it returns an empty block, which won't be displayed.

However, when the search isn't the main page content, or the facets aren't in normal blocks, it can happen that the facet blocks will be requested before the search takes place. Then, they have no way of telling that a search will later be executed in the same page request, and act as if they weren't on a search page – i.e, the blocks aren't showing.
Regrettably, this problem cannot be fixed in the Search API. You have to make sure yourself, in some way, that the search on your page will be executed before the facet blocks are requested.

For further information and possible solutions, see #1066278-28: Problems with Context/Panels and facets and the rest of that issue.

Why don't data alterations reduce the number of items to index?

E.g., you have an index configured with the "Bundle filter" data alteration to only index nodes of type "Article". Still, on the index's status page the "Progress" note mentions the total number of nodes (of all content types) as the total number of items to index, and maybe even as the number of items already indexed. (This is also the same for all other data alterations that filter the items to be indexed, like "Exclude unpublished nodes" and "Language control".) Therefore, you might wonder whether the data alteration is working properly, or not filtering the indexed items at all.

However, this is not a bug, the data alteration is (most likely) working correctly! It is just a regrettable, but hard to remove restriction in the design of the Search API that data alterations won't change the listed total number of items, and that items filtered out from indexing will still count to the number of items indexed. If you want to know the number of items that are really indexed, and whether the data alteration is working correctly, look at the "Server index status" item further down on the page.

Why can't I index field X? / Why can't I create a search index for entity type Y?

For achieving its aim of being as generic a search framework as possible and supporting as many types of data as possible, Search API relies on the Entity API for providing the metadata of search items, most importantly the fields/properties attached to them. However, this is no magic process, Entity API, too, can only know of fields and entity types if other modules expose this information to it. If you are a developer, see the Entity API documentation for how this is achieved.

Basically, the Entity API lets modules retrieve information of the properties of entity types it knows about. If a module defines a new entity type, but doesn't tell the Entity API about the properties entities of this type have, the Entity API – and, consequently, the Search API – knows nothing about the properties of this entity type. And therefore it will not be possible to index entities of this type with the Search API (without special integration).

Properties of entities aren't just defined by the module that creates them, though – the Field API also allows site builders to add custom fields to entities. The fields attached to an entity can easily be retrieved – however, the type of data stored in the field (whether an integer, a list of dates, a more complex structure or …) cannot be inferred so easily, here the Entity API (and, thus, the Search API) again has to rely on a module (in this case the one defining the field type in question) to specify what type of data these fields contain.
Since the Search API cannot index data of which it doesn't know the type (most importantly, because the data structures needed for single and for multiple values are inherently different), fields which don't specify that information will not appear in the index's Fields form.

So, in both cases, if you encounter a missing entity type / field, create an issue in the issue queue of the module responsible for that entity type / field. If the module maintainers don't know how to integrate with the Entity API, refer them to the corresponding handbook entry.

Why don't Search API searches find partial matches/substrings?

E.g., when searching for "break", why aren't items containing "breakpoint" (or "unbreakable") found.

This is not actually a problem of the Search API module itself. The Search API only supplies the framework, and passes the search string on to the service class (database, Solr, Xapian, etc.) for the actual searching. The service classes therefore determine whether partial matches will be returned or not. You should therefore refer to the service class' documentation or ask in their issue queue (if they aren't listed below).

For the Database search, it has been added in early 2014 (see #1299238: Add option for partial matching for current work on this). Also, there is the Fuzzy search service class which also uses the database but does support substring matches.
Solr search, see here.

Why can't I sort by field X?

There are three restrictions on what fields you can use for sorting (no matter whether in Views, or through the Search API Sorts module, or through other means):

• The field has to be indexed.
• The field must not be indexed as type “Fulltext”.
• The field must not be multi-valued.

These are internal restrictions inherent to the way most search backends work, so they cannot be "resolved" directly.
However, you can use the "Aggregated fields" data alteration to create a copy of a field (which will be single-valued) and then use that copied field for sorting.

While the first two restrictions are usually easy to check, it is often not easy to see whether or not a field is multi-valued. This is because fields can seem single-valued in the UI, but still be multi-valued internally. E.g., if you set the "Number of values " of a Field API field to "Unlimited" (or any other value greater than 1) the field will count as multi-valued, even if you in practice only ever enter one value for any item. Also, single-valued fields nested inside of multi-valued ones (e.g., the taxonomy term name in a multi-valued term reference field) count as multi-valued.
If you're unsure, you can view the HTML source code of the respective field's "Type" dropdown and see whether the values are normal types (text, string, …) or list types (list<text>, list<string>, …).

(Also, please note that custom data types added by other modules which default to being handled as fulltext also count as type "Fulltext" for this purpose. However, this will probably affect only very few users.)

What is the "Server index status" for a search index?

Since Search API 1.10, the index's "View" tab displays some additional information. One value that might need some explanation here is the "Server index status". This is the result count which the server returns for a completely unfiltered query for this index, so it represents the total count of items indexed on the server.

So, how can you use that to diagnose problems? This depends a lot on your current setup, which is why initial warning messages to automatically detect problems using this metric were soon removed again since the detection mechanisms didn't apply in some setups.

In general, the item count on the server should be between the number of indexed items and the total number of items displayed for the index. However, when using indexing filters like the "Bundle filter" or "Exclude unpublished nodes", not all items markes as "indexed" internally are really sent to the server. In these cases, you would have to verify yourself the total number of items that should be indexed, and whether the "Server index status" reaches that number (when the index displays "All items have been indexed.").
A second complication is Solr's commit behavior which means that (in some setups), for about two minutes after indexing, the "Server index status" won't yet reflect the real number of items indexed on the server.
Finally, if you are indexing data (most likely on a Solr server) with an external program, bypassing Drupal and the Search API for the indexing part, Search API will of course not know about your externally indexed items and show a too low total item amount (0, when indexing happens exclusively external). You would then have to check your external source for whether the "Server index status" you are seeing is correct and as expected.

Can I index nested field collections?

Yes, it is possible to index the fields of field collections that have been nested within a node, product, or entity. Use the Add related fields select dropdown to choose any field collections to be added for indexing.

Due to technical restrictions, every possible combination of entity and field will be shown in the dropdown. It is important to ensure the selected field does have a relationship with the entity, otherwise the field will not be indexed. For example, if "Newspaper » Chapter" is chosen as an entity and its related field to be indexed, yet Chapters are only associated with Books, no Chapter data will be indexed.

More can be read about this particular consideration here.