Configurando campos UNIÓN en Drupal Search API: Una guía práctica sobre campos agregados

Todo comenzó con un problema común en búsquedas. El cliente quería que todos los eventos, tanto los del tipo de contenido Events como los de la entidad personalizada Event Series, aparecieran juntos en una sola página de resultados, ordenados por fecha.

Parecía una solicitud sencilla... hasta que descubrí que cada entidad almacenaba la fecha en un campo distinto:

field_event_date en Events
field_event_start en Event Series

Ahí fue donde el plan se vino abajo. Los resultados de búsqueda se veían inconsistentes y el orden por fecha simplemente no funcionaba.
Search API no podía usar dos campos de fecha diferentes para construir un único ordenamiento unificado.

La solución: campos agregados con UNIÓN

Después de probar varios enfoques, la opción más limpia y confiable fue usar campos agregados con operador UNION en Drupal Search API. Esto permite unificar valores equivalentes en un solo campo que puede usarse para filtros, facetas y ordenamientos.

Esta solución sigue las buenas prácticas de Drupal, mantiene la lógica dentro del índice, estandariza la experiencia de filtrado, evita soluciones frágiles en Views o código personalizado, y funciona con cualquier backend de Search API: Database, Solr o Elasticsearch/OpenSearch (módulos contribuidos).

¿Qué es un campo agregado y qué significa “UNIÓN”?

Un campo agregado (aggregated field) es un campo virtual dentro del índice que combina valores de otros campos indexados.

El operador UNIÓN le indica a Search API que agregue los valores de todos los campos fuente dentro de ese campo virtual.
Otros operadores pueden combinar los valores de manera diferente (por ejemplo, sumando números).

En nuestro caso, UNIÓN resolvió el problema de unificar field_event_date y field_event_start en un único campo que se ordena por fecha.

Pero este enfoque no solo sirve para eso. También es útil para:

Búsquedas combinadas de texto
Filtros basados en taxonomías
Facetas de fechas unificadas o por rango

Y todo puede configurarse directamente desde la interfaz de Drupal, sin escribir una sola línea de código.

¿Por qué importa? (Y por qué es una buena práctica en Drupal 10)

Te ayuda a mantener la lógica de búsqueda en el índice, a evitar filtros duplicados en las vistas y a simplificar el mantenimiento.

Experiencia de búsqueda consistente: Facetas unificadas de “Tipo”, “Tema” o “Fecha” entre entidades y bundles.
Menos deuda técnica: Toda la lógica vive en el índice, no dispersa entre Views o controladores.
Escalable: Funciona con cualquier backend de Search API.
Mantenible: Toda la configuración es exportable y versionable, alineada con el sistema de configuración de Drupal.

Cómo configurarlo desde la interfaz de administración

Ve a Configuración → Búsqueda y Metadatos → Search API, y edita tu índice (por ejemplo, “Content”).
En la pestaña Fields, haz clic en Add fields → Aggregated field.

Search API aggregation field configuration form

Configura el campo con:
1. Aggregated field type: union
2. Processors → Aggregated field: habilitado con las rutas completas a los campos fuente.

En la pestaña Index, selecciona Re-index.
Actualiza tu vista para usar el nuevo campo agregado.

Ejemplos de configuración (multi-tipo de dato)

Los siguientes ejemplos ilustran cómo configurar campos agregados UNIÓN en la API de búsqueda.

Nota: Estos fragmentos representan la configuración de Drupal en formato YAML, similar a los archivos que se exportan mediante la Administración de configuración (normalmente al directorio `config/sync/`) o que se generan al crear campos a través de la interfaz de usuario de la API de búsqueda. Puede usarlos como referencia para comprender la estructura o para editar/exportar manualmente su propia configuración.

Tipos de contenido y entidades relacionadas

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'

Taxonomías en distintas entidades

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

Fechas (normalizar múltiples fuentes de fechas)

 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'

Texto combinado (título + resumen + resaltado)

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'

Regiones/Ubicaciones

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

Sugerencia: Puede exportar cualquiera de sus configuraciones de índice de la API de búsqueda a través de la Administración de configuración de Drupal (/admin/config/development/configuration/single/export) para ver la estructura YAML y adaptarla a su proyecto.

Alternativa: Combinar varios índices (Views Combine UNION ALL)

Si realmente necesita combinar varios índices en una sola lista de resultados, puede usar Views Combine (que realiza una operación UNION ALL a nivel SQL).

Sin embargo, es mejor resolver la unificación dentro de un solo índice usando campos agregados, ya que es más simple, rápido y fácil de mantener.

Extender mediante código (opcional)

Si no puede resolver su problema completamente a través de la interfaz de usuario, puede extender la lógica de la API de búsqueda usando hook_search_api_query_alter() o eventos del backend.

Esto es útil cuando necesita un comportamiento más avanzado, por ejemplo, normalizar términos, aplicar sinónimos o agregar filtros dinámicos, manteniendo la coherencia con la arquitectura de Drupal.

Contexto del archivo: Coloque este código en el archivo .module de su módulo personalizado (por ejemplo, my_module.module). Asegúrese de que su módulo está habilitado.

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');
    }
  }
}

Buenas prácticas

Usa nombres de campo claros y orientados a la UI.
Facilita que los site builders y editores entiendan el propósito de cada campo unificado.
Une solo campos con el mismo significado.
Por ejemplo, “Topic” y “Event Category”.
Asegura un análisis de texto consistente.
Si unes varios campos de texto, usa los mismos analizadores (minúsculas, eliminación de HTML, stemming).
Mantén la configuración versionada.
Usa el sistema de Configuration Management de Drupal para desplegar cambios de forma segura.
Reindexa y valida.
Después de modificar campos agregados, reindexa y comprueba que facetas y filtros funcionen como se espera.

Conclusiones clave

Los campos UNIÓN son independientes del backend: funcionan igual con Database, Solr o Elasticsearch/OpenSearch.
Resuelve la unificación dentro del índice primero antes de recurrir a Views Combine o código personalizado.
Configura desde la UI: el código solo es necesario para casos avanzados (por ejemplo, sinónimos o filtros condicionales).

Micro‑FAQ

¿Funciona UNIÓN con cualquier backend de Search API?
Sí. La funcionalidad se implementa a nivel de Search API, aunque el rendimiento puede variar ligeramente según el backend.
¿Cuándo debo usar campos agregados vs. Views Combine?
Se recomienda usar campos agregados dentro de un solo índice. Usa Views Combine únicamente para fusionar múltiples índices.
¿Puedo unificar fechas y taxonomías con UNIÓN?
Sí. Usa type: date para campos de fecha y type: string para campos de taxonomía.

¿Se necesita código o solo configuración?
La configuración a través de la UI de administración es suficiente. El código es opcional y solo necesario para personalizaciones avanzadas (por ejemplo, sinónimos o filtros condicionales).

Recursos recomendados

_______

Diana Casanova is a senior Drupal developer at Rootstack.

Read in English.