Configuring UNION fields in Drupal Search API: A practical guide to aggregated fields

This all started with a pretty common search problem: the client wanted all events from Events (Content type) and Event Series (Custom entity) to show up together on one search result page, sorted by date. 

Ah, a simple request … until I realized each entity stores its date in a different field:

• field_event_date in Events
• field_event_start in Event Series

That’s where my plan fell apart. The search results looked inconsistent, and sorting by date didn't work. Search API couldn’t use two different date fields from separate entities to build a single, unified sort order. 

After testing different approaches, the cleanest and most reliable solution was to use UNION aggregated fields in the Drupal Search API to unify equivalent values into a single facetable and queryable field.

This approach follows Drupal best practices — keeping logic within the index, standardizing filter UX, and avoiding brittle workarounds in Views or custom code. It works with any Search API backend: Database, Solr, or Elasticsearch/OpenSearch (via contrib).

What Is an Aggregated Field (and What “UNION” Means)

An aggregated field is a virtual index field that combines values from other indexed fields.

The UNION operator tells Search API to add each value from every source field to the virtual index. Other operators combine values differently (for example, summing numeric values).

In our example, it solved the issue of unifying two separate date fields (field_event_date and field_event_start) into a single sortable value.

But that’s just one use case. In addition to solving our specific problem of combining fields for a single facet, this technique is also useful for:

• Combined text searches
• Taxonomy filters
• Unified or range based date filters

All of this can be configured through the UI — no code required.

Why It Matters (and Why It’s a Drupal 10 Best Practice)

It helps you keep search logic within the index, avoid duplicated filters in Views, and simplify maintenance.

• Consistent search experience: Unified “Type”, “Topics”, or “Date” facets across entities/bundles.
• Reduced technical debt: Logic resides in the index, not scattered across Views or controllers.
• Scalable: Works with any Search API backend (DB, Solr, Elasticsearch/OpenSearch).
• Maintainable: Configuration is exportable, versionable, and aligned with Drupal’s config system.

Implementation (admin UI)

Compatibility note:
Aggregated fields with UNION are part of the Search API core feature set, though availability may vary slightly across minor versions. If you don’t see the “Aggregated field” option, review your installed version’s documentation.

Configuration Steps

1. Go to Configuration → Search and Metadata → Search API, and edit your index (e.g., “Content”).
2. Under the Fields tab, click Add fields → Aggregated field.

3. Configure:
   • Aggregated field with UNION, configuration.type: union
   • Processors → Aggregated field enabled, fields: full paths to sources

4. Go to the Index tab → click Index now or Re-index.
5. Update the View (Index Search) to use the aggregated field. 

Configuration examples (generic, multiple data types)

The following examples illustrate how you can configure UNION aggregated fields in Search API.

Note: These snippets represent Drupal configuration in YAML format, like the files you would export via Configuration Management (usually to the config/sync/ directory) or generate when creating fields through the Search API UI. You can use these as references to understand the structure or to manually edit/export your own configuration. 

Content Types and Related Entities

resource_type_unified:
  label: 'Resource Type (Unified)'
  property_path: aggregated_field
  type: string
  configuration:
    type: union
    fields:
      - 'entity:node/sitewide_content_type'
      - 'entity:eventseries/field_event_category'

Taxonomies across entities

 topics_unified:
  label: 'Topics (Unified)'
  property_path: aggregated_field
  type: string
  configuration:
    type: union
    fields:
      - 'entity:node/field_topics'
      - 'entity:eventseries/field_topics'

Dates (normalize multiple date sources)

 reference_date_unified:
  label: 'Reference Date (Unified)'
  property_path: aggregated_field
  type: date
  configuration:
    type: union
    fields:
      - 'entity:node/created'
      - 'entity:eventinstance/field_event_start'

Combined text (title + summary + highlight)

combined_text_search:
  label: 'Combined Text Search'
  property_path: aggregated_field
  type: text
  configuration:
    type: union
    fields:
      - 'entity:node/title'
      - 'entity:node/field_summary'
      - 'entity:node/field_highlight_text'

Regions/Locations

 region_unified:
  label: 'Region (Unified)'
  property_path: aggregated_field
  type: string
  configuration:
    type: union
    fields:
      - 'entity:node/field_region'
      - 'entity:eventinstance/field_location_region'

Tip: You can export any of your Search API index configurations via Drupal Configuration Management (/admin/config/development/configuration/single/export) to see the YAML structure and adapt it for your project. 

Alternative: Merge multiple indexes (Views Combine UNION ALL)

If you truly need to merge multiple indexes into a single result list, you can use Views Combine (which performs a UNION ALL at the SQL level).

However, it’s best to solve unification within a single index using aggregated fields, as this is simpler, faster, and easier to maintain.

Extend via code (optional)

If you aren’t able to solve your problem entirely through the UI, you can extend Search API logic using hook_search_api_query_alter() or backend events.

This is useful when you need more advanced behavior — for example, normalizing terms, applying synonyms, or adding dynamic filters — while staying fully aligned with Drupal’s architecture.

File context: Place this code in your custom module’s .module file (e.g., my_module.module). Make sure your module is enabled. 

use Drupal\search_api\Query\QueryInterface;

/**
 * Implements hook_search_api_query_alter().
 */
function my_module_search_api_query_alter(QueryInterface $query) {
  $index = $query->getIndex();
  if ($index && $index->id() === 'content') {
    if ($index->getField('topics_unified')) {
      $query->addCondition('topics_unified', 'Historical Memory', 'CONTAINS');
    }
  }
}

Best practices

• Use clear, UI-oriented field names.
Make it easy for site builders and editors to understand what each unified field represents.
• Only unify semantically equivalent fields.
Combine fields that represent the same concept (for example, “Topic” from one entity and “Event Category” from another), to keep filters meaningful.
• Ensure consistent text analysis across source fields.
When unifying multiple text fields, make sure they use the same analyzers — such as lowercase filters, HTML stripping, or stemming — so the aggregated field behaves predictably in searches and facets.
• Keep configuration exportable and version-controlled. Use Drupal’s Configuration Management system to track and deploy changes safely across environments.
• Reindex after configuration changes and validate performance.
Always reindex your content after modifying aggregated fields, and check that filters and facets respond as expected.

Key takeaways

• UNION aggregated fields are backend-independent: they work consistently across all supported search backends; Database, Solr or Elasticsearch/Open Search. This means you can define filters, facets or combined fields once in the index, and they will behave the same regardless of the engine. Being backend-independent simplifies maintenance, avoids duplication logic, and ensures your configuration is portable.
• Solve it inside the index first: use aggregated fields before resorting to Views Combine or custom code — it’s cleaner and faster.

Micro‑FAQ

• Does UNION work with any Search API backend?
  Yes. The feature is implemented at the Search API layer; performance may vary slightly by backend.
• When should I use aggregated fields vs. Views Combine?
  Prefer aggregated fields within a single index. Use Views Combine only to merge multiple indexes.
• Can I unify dates and taxonomies with UNION?
  Yes. Use type: date for dates and type: string for taxonomy fields.
• Does it require code or just configuration?
  Configuration via the admin UI is sufficient. Code is optional for advanced customization (e.g., synonyms, conditional filters).

Related articles 

• How to combine 2 entity fields in Search API (single valued)
• Drupal and Search API: Unleash the power of Aggregated fields

_______

Diana Casanova is a senior Drupal developer at Rootstack. 

Leer en español