drupal-search-api

What this skill does

# Drupal Search API Patterns

This skill documents Search API configuration patterns, boosting strategies, and custom processor development for Drupal sites.

## Index Configuration

### Field Type Requirements

**Boolean Fields for Boosting**
- Boolean fields work best with custom boost processors
- Integer fields can cause issues with boolean-based boost logic
- Always configure boolean fields as `type: boolean` in index settings

```yaml
field_settings:
  field_featured:
    label: Featured
    datasource_id: 'entity:node'
    property_path: field_featured
    type: boolean  # NOT integer
    boost: 8.0
```

**Configuration Command**
```bash
ddev drush config:set search_api.index.{index_name} \
  field_settings.field_featured.type boolean
```

### Numeric Fields for Engagement Boosting

**Flag Count Fields**
- Use `type: integer` for count fields
- Managed by `flag_search_api` module
- Automatically indexed and updated

```yaml
field_settings:
  flag_bookmark_count:
    label: 'Bookmark count'
    property_path: flag_bookmark_count
    type: integer
  flag_favorite_count:
    label: 'Favorite count'
    property_path: flag_favorite_count
    type: integer
```

## Boost Processors

### Custom Boolean Boost Processor

**When to Use**
- Boolean field boosting (featured flags, promoted content)
- Needs 100% control over boost logic
- Complex conditional boosting

**Pattern: FeaturedContentBoost.php**

```php
<?php

namespace Drupal\custom_search\Plugin\search_api\processor;

use Drupal\search_api\Item\ItemInterface;
use Drupal\search_api\Processor\ProcessorPluginBase;

/**
 * @SearchApiProcessor(
 *   id = "featured_content_boost",
 *   label = @Translation("Featured content boost"),
 *   description = @Translation("Adds a boost to indexed items marked as featured."),
 *   stages = {
 *     "preprocess_index" = 0,
 *   },
 *   locked = false,
 *   hidden = false,
 * )
 */
class FeaturedContentBoost extends ProcessorPluginBase {

  /**
   * {@inheritdoc}
   */
  public function preprocessIndexItems(array $items) {
    /** @var \Drupal\search_api\Item\ItemInterface $item */
    foreach ($items as $item) {
      try {
        $entity = $item->getOriginalObject()->getValue();

        // Check if entity has featured field and it's set to TRUE.
        if ($entity->hasField('field_featured') &&
            !$entity->get('field_featured')->isEmpty() &&
            $entity->get('field_featured')->value == 1) {
          $old_boost = $item->getBoost();
          // Apply 2x boost to featured content.
          $item->setBoost($old_boost * 2.0);
        }
      }
      catch (\Exception $e) {
        // Skip items that can't be loaded.
        continue;
      }
    }
  }
}
```

**Key Points**
- Use multiplicative boost: `$item->setBoost($old_boost * boost_factor)`
- Pattern from `search_api_boolean_field_boost` module
- Boost at index time via `preprocess_index` stage
- Always get old boost first to preserve other boosts

**Recommended Boost Factors**
- Featured content: `2.0x` (modest but effective)
- Featured content: `1.5x - 3.0x`
- Premium content: `1.5x - 2.0x`

### Number Field Boost Processor

**When to Use**
- Engagement metrics (likes, bookmarks, views)
- Numeric quality scores
- Time-based decay factors

**Configuration Pattern**

```yaml
processor_settings:
  number_field_boost:
    weights:
      preprocess_index: 0
    boosts:
      flag_bookmark_count:
        boost_factor: 0.01
        aggregation: max
      flag_favorite_count:
        boost_factor: 0.1
        aggregation: max
```

**How It Works**
- Adds to boost based on field value
- Formula: `boost += (field_value * boost_factor)`
- Example: 138 bookmarks x 0.01 = +1.38 boost

**Configuration Commands**
```bash
# Set bookmark count boost (0.01 per bookmark)
ddev drush config:set search_api.index.{index_name} \
  processor_settings.number_field_boost.boosts.flag_bookmark_count.boost_factor 0.01

# Set favorite count boost (0.1 per favorite)
ddev drush config:set search_api.index.{index_name} \
  processor_settings.number_field_boost.boosts.flag_favorite_count.boost_factor 0.1
```

**Recommended Boost Factors**
- Bookmark count: `0.01 - 0.05` (for counts in 10-1000 range)
- Favorite count: `0.1 - 0.5` (for counts in 1-50 range)
- View count: `0.001 - 0.01` (for counts in 100-10000 range)

### Processor Conflicts

**Problem: Multiple Processors on Same Field**

If multiple processors target the same field, they can conflict:
- One overrides the other
- Boosts don't combine as expected
- Unpredictable results

**Solution: Remove Conflicting Configuration**

```bash
# Remove field from number_field_boost if using custom processor
ddev drush config:set search_api.index.{index_name} \
  processor_settings.number_field_boost.boosts.field_featured null
```

**Best Practice**
- Use custom processor for boolean/complex logic
- Use number_field_boost for simple numeric boosts
- Don't configure same field in multiple processors

## Configuration Management

### Direct Config Updates with PHP

When `drush config:set` fails or produces unexpected results (e.g., side effects on unrelated config), use PHP to directly update active configuration:

```bash
ddev drush php:eval "
\$config = \Drupal::configFactory()->getEditable('search_api.index.{index_name}');

// Set field type
\$config->set('field_settings.field_featured.type', 'boolean');

// Remove from number_field_boost
\$boosts = \$config->get('processor_settings.number_field_boost.boosts');
unset(\$boosts['field_featured']);
\$config->set('processor_settings.number_field_boost.boosts', \$boosts);

// Set boost factors
\$config->set('processor_settings.number_field_boost.boosts.flag_bookmark_count.boost_factor', 0.01);
\$config->set('processor_settings.number_field_boost.boosts.flag_favorite_count.boost_factor', 0.1);

\$config->save();
echo \"Configuration updated\n\";
"
```

**When to Use PHP Instead of drush config:set:**
- When config:set creates unwanted side effects (e.g., changing `server: {server_name}` to `server: null`)
- When removing array keys (unset pattern works better than `null`)
- When making multiple related changes atomically
- When field type changes cause Drupal to fallback to generic types

**After PHP Config Updates:**
1. Verify changes: `ddev drush config:get search_api.index.{index_name} field_settings.field_featured`
2. Export to files: `ddev drush config:export -y`
3. Review exported changes: `git diff config/default/`
4. Revert any unintended changes (e.g., ngram fields changed to plain text)

### Field Type Preservation

**Problem:** When Solr server config is modified (e.g., pointing to a different backend), config export may downgrade custom field types to generic types:

```yaml
# BEFORE (correct)
field_display_name:
  type: 'solr_text_custom:ngramstring'

# AFTER export (incorrect)
field_display_name:
  type: text
```

**Solution:** After exporting, restore custom field types via PHP:

```bash
ddev drush php:eval "
\$config = \Drupal::configFactory()->getEditable('search_api.index.{index_name}');
\$config->set('field_settings.field_display_name.type', 'solr_text_custom:ngramstring');
\$config->set('field_settings.label.type', 'solr_text_custom:ngramstring');
\$config->set('field_settings.name.type', 'solr_text_custom:ngramstring');
\$config->set('field_settings.title.type', 'solr_text_custom:ngramstring');
\$config->save();
"
ddev drush config:export -y
```

**Fields Using ngram Tokenization:**
- `field_display_name` - Display names (partial matching for autocomplete)
- `label` - Entity labels/titles
- `name` - User account names
- `title` - Node titles

**Never change these to `type: text`** - it breaks partial name matching (e.g., "mich" won't find "Michael").

### Config Export Side Effects

When modifying Search API server config (e.g., for local development), Drupal may update index configs to remove server dependencies:

```yaml
# Unintended change in search_api.index.{index_name}.yml
dependencies:
  config:
-