Introducing Facet API

cpliakas's picture

The Problem

The search community is fragmented. The problem stems from a core search module that doesn't facilitate third party backends, so each project is forced to solve similar problems in slightly different ways. Each contributed module has its own isolated sub-community, which is detrimental to Drupal as a whole.

Drupal search is one of the most important aspects of the platform, yet it rarely gets the attention it deserves. As a result, the search interface presented to the end user has suffered immensely leading to misconceptions that search-enabled applications are a weakness of Drupal. Developers are forced to program for individual modules, so innovation lags behind trends since collaboration is split.

The Goal

The main goal of Facet API is to improve the perception Drupal search by facilitating intuitive UIs presented to the end user. Instead of trying to re-invent the wheel yet again, the Facet API module pulls from the strengths of existing code bases to provide a backend-agnostic solution that all projects can leverage. Facet API integrates with Apache Solr, Search Lucene API (integration pending), and any other project that implements the adapter (core Search? Search API???). By reducing the duplication of effort and allowing for contributions to be reused across projects, the interfaces available to Drupal search solutions will hopefully catch up to the latest trends.

The Technology

Existing search patterns exist throughout the web but are difficult to replicate in Drupal. It would be impossible for Facet API to satisfy all use cases, so it uses a pluggable architecture to facilitate contributions in order to satisfy the diverse requirements. Facet API leverages CTools plugins to provide a consistent, standard method of integrating with the module, and the following plugins are made available to developers:

  • Adapters: Adapters are a standard interface through which modules can interact with Facet API.
  • Widgets: Facets are represented by many different UI components called widgets. Each facet is configurable as to which widget is used to render it.
  • Query types: Each backend implements different query types, such as wildcard queries and range queries. Query type plugins allow modules to define which types are available for the backends they are providing, and developers can plug in new types, for example location queries.
  • Dependencies: The progressive disclosure pattern exposes more facets over time, so the dependency plugins allow for configurable conditions as to when a facet is processed and displayed.
  • Empty behaviors: When a facet has no items, the administrator might choose to either hide the facet or display text.
  • Search info (to be implemented in beta4): The current search block displays information about the search being executed. Search info plugins allows site builders to configure the information that is displayed in the block.

In addition to the plugins listed above, Facet API allows developers to create different realms that facets can be rendered in. For example, the blocks realm displays facets as a list of clickable links in a block, whereas the fieldset realm displays facets as form elements similar to the core search module's advanced search implementation. There is also an initiative to create a page realm which displays facets on separate pages. This has implications for mobile sites rendered on smaller screens.

Facet API also leverages CTools exportables so configurations can be managed across environments. CTools is the most standardized system for exportable configurations available to Drupal 7, so it has a familiar API that developers will feel comfortable working with.


I would like to thank Acquia for giving me time to work on Facet API. A very special thanks goes to Peter Wolanin whose architectural guidance and engineering contributions are invaluable to Facet API. Peter's decision to strip out Apache Solr's internal facet building code in favor of leveraging Facet API shows a deep commitment to working with the various search communities and consolidating code.


Chris, I've been working with

milesw's picture


I've been working with Facet API the past couple weeks and I'm overwhelmed by how awesome the module is. The concept itself is great, but most impressive is how well it's been implemented. It's really a game-changer. The Drupal community is lucky to have you guys working on this stuff because you're right –  search is a critical component in Drupal that rarely gets enough attention.


cpliakas's picture

Thanks milesw.

The project is definitely fueled by people such as yourself who post use cases, file bug report, and submit code, so please keep the contributions coming!

Thanks again for your kind words,

This is true game changer

Ravi.J's picture

Hi Chris,

Thanks for the great module. Truely awsome!!


Chris gives me too much

pwolanin's picture

Chris gives me too much credit for help in terms of the architecture - that's really his work.