How Results Are Ordered

AI Search ranks results in three strict tiers. A result in a higher tier always outranks everything in the tiers below it, no matter the scores. This page documents the pipeline and every filter you can use to customize it.

The three tiers

Tier 0 – Exact matches

Before anything else, the raw query is checked against product SKUs (exact match, and prefix match when the query is a single token of 4+ characters; variation SKUs resolve to their parent product) and against exact post titles, case-insensitively. Matches are pinned to the top with score 1.0. This tier is always on and runs on the unmodified query – synonym expansion never touches a literal SKU. Editors see a green “Exact Match” badge; results carry the ai-search-exact-match CSS class.

Tier 1 – Traditional keyword results

Everything WordPress’s own search finds is kept – never discarded – and re-ranked by keyword relevance (title matches weigh most, then content, taxonomies and custom fields) instead of publish date. Products hidden from search in WooCommerce catalog visibility are excluded. Editors see a blue “Keyword Match” badge; the CSS class is ai-search-lexical-match.

Tier 2 – Semantic results

The query is embedded and compared (cosine similarity) against every indexed post’s embedding. Results above the similarity threshold that are not already in Tiers 0-1 are appended, sorted by score. Term embeddings, when enabled, add a boost from the post’s best-matching taxonomy term. If all three tiers are empty, a multi-tier fallback runs so shoppers never hit a blank page.

Developer filters

All filters live in the free plugin. The most useful, in pipeline order:

ai_search_exact_matches

Add or remove pinned Tier 0 results – for example, pin products matching an EAN stored in custom meta:

add_filter( 'ai_search_exact_matches', function ( $ids, $query, $post_type ) {
    $ean_match = get_posts( [
        'post_type'  => 'product',
        'fields'     => 'ids',
        'meta_key'   => '_ean',
        'meta_value' => $query,
    ] );
    return array_merge( $ean_match, $ids );
}, 10, 3 );

ai_search_query_before_embedding

Rewrite the query before it is embedded – synonym expansion, spell correction, stopword removal. Runs after Tier 0, so SKUs are safe:

add_filter( 'ai_search_query_before_embedding', function ( $query ) {
    return str_replace( 'tshirt', 'tshirt t-shirt tee', $query );
} );

ai_search_similarity_threshold

add_filter( 'ai_search_similarity_threshold', function ( $threshold, $query, $post_type ) {
    return $post_type === 'product' ? 0.45 : $threshold; // stricter for products
}, 10, 3 );

ai_search_results

Re-rank or filter the final ordered results – boost in-stock products, hide restricted content:

add_filter( 'ai_search_results', function ( $posts, $query, $scores ) {
    usort( $posts, function ( $a, $b ) {
        $stock_a = get_post_meta( $a->ID, '_stock_status', true ) === 'instock' ? 0 : 1;
        $stock_b = get_post_meta( $b->ID, '_stock_status', true ) === 'instock' ? 0 : 1;
        return $stock_a <=> $stock_b;
    } );
    return $posts;
}, 10, 3 );

Also available: ai_search_searchable_post_types, ai_search_should_generate_embedding, ai_search_embedding_content and ai_search_term_embedding_content. Each has inline PHPDoc with an example in the plugin source.

Last updated: August 2026. Applies to AI Search 1.28.0 and later.