---
name: kimaai_keyword_search_providers
type: filter
since: 1.5.4
tier: premium
feature: knowledge-base
area: embedding-search
summary: Adds an own engine for the keyword search of hybrid search, or changes the order the engines are tried in.
parameters:
  - name: providers
    type: KeywordSearchProviderInterface[]
    description: The engines in the order Automatic tries them, ElasticPress, SearchWP, Relevanssi and WordPress's own search.
returns:
  type: KeywordSearchProviderInterface[]
  description: The engines.
surfaces: [chatbot, search]
---

# kimaai_keyword_search_providers

## When it fires

Once per request, when KimaAI sets up its knowledge search on `init`. Add the callback before that, in the theme's `functions.php` or when a plugin loads. The list matters only when hybrid search is on (Chatbot, Knowledge base, Hybrid search).

An engine is an object of a class that implements `KimaAI\Pro\FunctionCall\KeywordSearch\KeywordSearchProviderInterface` (Pro): `id()`, `label()`, `isAvailable()` and `search($query, $limit, $scope)`, which returns rows with `id`, `score`, `post_id`, `title`, `url` and `snippet`. "Keyword search engine" set to Automatic uses the first available engine of the list; the setting offers only the engines KimaAI ships, so put your own first. `$scope` holds `post_type`, `lang` and `tax_<taxonomy>` lists to search in.

KimaAI checks every row afterwards: rows outside the scope and posts the visitor may not see are dropped, and an engine that throws an error gives no keyword hits instead of breaking the answer.

## Example

```php
use KimaAI\Pro\FunctionCall\KeywordSearch\KeywordSearchProviderInterface;

// Questions name article numbers: the keyword search looks them up in the products' SKU field.
class My_Sku_Search implements KeywordSearchProviderInterface {

  public function id(): string {
    return 'my_sku_search';
  }

  public function label(): string {
    return 'SKU search';
  }

  public function isAvailable(): bool {
    return true;
  }

  public function search(string $query, int $limit, array $scope = []): array {
    if (!preg_match('/\b[A-Z]{2}-\d{4}\b/', $query, $match)) {
      return [];
    }

    $products = get_posts([
      'post_type' => 'product',
      'posts_per_page' => $limit,
      'meta_query' => [['key' => 'sku', 'value' => $match[0]]],
    ]);

    return array_map(
      static fn(WP_Post $product): array => [
        'id' => 'sku-' . $product->ID,
        'score' => 0.0,
        'post_id' => $product->ID,
        'title' => $product->post_title,
        'url' => get_permalink($product),
        'snippet' => wp_trim_words(wp_strip_all_tags($product->post_content), 60),
      ],
      $products
    );
  }
}

add_filter(
  'kimaai_keyword_search_providers',
  function (array $providers): array {
    array_unshift($providers, new My_Sku_Search());

    return $providers;
  }
);
```

The engine replaces the others while it is available: a question without an article number gets no keyword hits, and the answer comes from the vector search alone.

## Related

- `kimaai_keyword_search_query_args`: changes the query of the engines KimaAI ships.
- `kimaai_kb_search_meta_filter`: narrows the vector search the keyword hits are merged with.
