drupal-search-api

Drupal Search API

インデックス設定

フィールド型の要件

ブーストにはブール値フィールドを使用

• ブール値フィールドは、カスタムブーストプロセッサーとの相性が最適です
• 整数フィールドは、ブール値ベースのブーストロジックで問題を起こすことがあります
• インデックス設定では、ブール値フィールドを必ず type: boolean として設定してください

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

設定コマンド

ddev drush config:set search_api.index.{index_name} \
  field_settings.field_featured.type boolean

エンゲージメントブースト用の数値フィールド

フラグ数フィールド

• 件数フィールドには type: integer を使用してください
• flag_search_api モジュールによって管理されます
• 自動的にインデックス化され、更新されます

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

ブーストプロセッサー

カスタムブール値ブーストプロセッサー

使用する場合

• ブール値フィールドのブースト（注目フラグ、プロモーションコンテンツ）
• ブーストロジックを完全に制御する必要がある場合
• 複雑な条件付きブースト

パターン：FeaturedContentBoost.php — ProcessorPluginBase を拡張し、ステージは preprocess_index

// Use #[SearchApiProcessor(...)] attribute (use Drupal\search_api\Attribute\SearchApiProcessor) — see README for full class
final class FeaturedContentBoost extends ProcessorPluginBase {
  public function preprocessIndexItems(array $items) {
    foreach ($items as $item) {
      try {
        $entity = $item->getOriginalObject()->getValue();
        if ($entity->hasField('field_featured') &&
            !$entity->get('field_featured')->isEmpty() &&
            $entity->get('field_featured')->value == 1) {
          $item->setBoost($item->getBoost() * 2.0);
        }
      }
      catch (\Exception $e) {
        continue;
      }
    }
  }
}

要点

• 乗算ブーストを使用します：$item->setBoost($old_boost * boost_factor)
• search_api_boolean_field_boost モジュールのパターンを使用します
• インデックス作成時に preprocess_index ステージでブーストします
• 他のブーストを維持するため、必ず最初に既存のブーストを取得します

推奨ブースト係数

• 注目コンテンツ：2.0x（控えめながら効果的）
• 注目コンテンツ：1.5x - 3.0x
• プレミアムコンテンツ：1.5x - 2.0x

数値フィールドブーストプロセッサー

使用する場合

• エンゲージメント指標（いいね、ブックマーク、閲覧数）
• 数値による品質スコア
• 時間ベースの減衰係数

設定パターン

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

仕組み

• フィールド値に基づいてブーストを加算します
• 数式：boost += (field_value * boost_factor)
• 例：ブックマーク数 138 x 0.01 = ブースト +1.38

設定コマンド

# 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

推奨ブースト係数

• ブックマーク数：0.01 - 0.05（件数が 10-1000 の場合）
• お気に入り数：0.1 - 0.5（件数が 1-50 の場合）
• 閲覧数：0.001 - 0.01（件数が 100-10000 の場合）

プロセッサーの競合

問題：同じフィールドに複数のプロセッサーを設定

複数のプロセッサーが同じフィールドを対象にしていると、競合することがあります：

• 一方が他方を上書きする
• ブーストが想定どおりに組み合わさらない
• 予測できない結果になる

解決策：競合する設定を削除する

# 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

ベストプラクティス

• ブール値や複雑なロジックにはカスタムプロセッサーを使用します
• 単純な数値ブーストには number_field_boost を使用します
• 同じフィールドを複数のプロセッサーに設定しないでください

設定管理

PHP による設定の直接更新

drush config:set が失敗する場合や、予期しない結果（無関係な設定への副作用など）が生じる場合は、PHP を使ってアクティブな設定を直接更新します：

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\";
"

drush config:set の代わりに PHP を使用する場合：

• config:set によって望ましくない副作用が生じる場合（例：server: {server_name} が server: null に変更される）
• 配列のキーを削除する場合（null よりも unset パターンのほうが適しています）
• 関連する複数の変更を不可分な処理として行う場合
• フィールド型の変更により Drupal が汎用型にフォールバックする場合

PHP による設定更新後：

1. 変更を確認します：ddev drush config:get search_api.index.{index_name} field_settings.field_featured
2. ファイルにエクスポートします：ddev drush config:export -y
3. エクスポートされた変更を確認します：git diff config/sync/
4. 意図しない変更（ngram フィールドがプレーンテキストに変更された場合など）を元に戻します

フィールド型の保持

問題： Solr サーバーの設定を変更すると（別のバックエンドを指定する場合など）、設定のエクスポート時にカスタムフィールド型が汎用型にダウングレードされることがあります：

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

# AFTER export (incorrect)
field_display_name:
  type: text

解決策： エクスポート後、PHP を使ってカスタムフィールド型を復元します：

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

ngram トークン化を使用するフィールド：

• field_display_name - 表示名（オートコンプリートで部分一致）
• label - エンティティのラベル／タイトル
• name - ユーザーアカウント名
• title - ノードのタイトル

これらを type: text に変更しないでください。部分的な名前の一致が機能しなくなります（例：「mich」で「Michael」が見つからなくなります）。

設定エクスポートの副作用

Search API サーバーの設定を変更すると（例：ローカル開発用）、Drupal がインデックス設定を更新して、サーバーへの依存関係を削除することがあります。

# Unintended change in search_api.index.{index_name}.yml
dependencies:
  config:
-    - search_api.server.{server_name}  # Removed
server: null  # Changed from {server_name}

防止策：

1. ローカル開発用に search_api.server.{server_name}.yml を変更しないでください
2. サーバー設定を変更せずに、DDEV 組み込みの Solr サービスを使用してください
3. サーバー設定の変更が必要な場合は、環境固有の設定に設定スプリットを使用してください
4. コミット前に必ず git diff config/sync/ を確認してください

復元：

# Revert index files if server was set to null
git checkout HEAD -- config/sync/search_api.index.*.yml

変更後の再インデックス

再インデックスが必要な場合

次の場合は必ず再インデックスしてください：

• フィールドタイプの変更（integer → boolean）
• ブースト係数の変更
• プロセッサーの追加／削除
• プロセッサー設定の変更

再インデックスコマンド

# Full reindex workflow
ddev drush cr
ddev drush search-api:clear {index_name}
ddev drush search-api:index {index_name}

# Check index status
ddev drush search-api:status {index_name}

デバッグコマンド

# Check processor configuration
ddev drush config:get search_api.index.{index_name} processor_settings

# Check field configuration
ddev drush config:get search_api.index.{index_name} field_settings

# Verify index status
ddev drush search-api:status {index_name}

ブーストが適用されない場合のチェックリスト： プロセッサーが有効 → フィールドタイプが正しい（boolean／integer） → 全件再インデックスが完了 → 競合するプロセッサーがない → キャッシュをクリア済み。