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

使用 PHP 而非 drush config:set 的场景：

• 当 config:set 产生不需要的副作用时（例如将 server: {server_name} 改为 server: null）
• 当需要移除数组键时（使用 unset 模式比设为 null 更有效）
• 当需要原子性地进行多项相关更改时
• 当字段类型更改导致 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）→ 已完成完整重新索引 → 没有冲突的处理器 → 已清除缓存。