Most Common Uses of Relevanssi Hooks & Filters

Relevanssi is one of the most powerful search plugins available for WordPress. It replaces the default search with a more advanced, customizable engine that supports fuzzy matching, highlights, custom post types, and much more.

In this post, we’ll explore the most useful and frequently used Relevanssi hooks and filters, along with real-world examples to help you implement them on your site.

Whether you’re customizing what gets indexed, changing how results are ranked, or fine-tuning the search output—Relevanssi makes it all possible through filters.

1. relevanssi_indexing_restriction

This filter lets you control which posts or custom post types get indexed.

add_filter( 'relevanssi_indexing_restriction', function( $restriction ) {
    global $wpdb;
    return "post_type = 'post' OR post_type = 'page'";
});

Use this if you only want to index posts and pages while excluding other post types like products or attachments.

2. relevanssi_do_not_index

This is another way to exclude specific posts or pages based on dynamic logic.

add_filter( 'relevanssi_do_not_index', function( $do_not_index, $post_id ) {
    if ( get_post_meta( $post_id, '_exclude_from_search', true ) === '1' ) {
        return true;
    }
    return $do_not_index;
}, 10, 2 );

You can combine this with a custom field or ACF toggle to allow editors to exclude specific posts from the search results easily.

3. relevanssi_hits_filter

Modify the list of search results before they are returned. Great for reordering, filtering, or even limiting results.

add_filter( 'relevanssi_hits_filter', function( $hits ) {
    // Remove posts from category ID 10
    $hits[0] = array_filter( $hits[0], function( $hit ) {
        return !has_category( 10, $hit->ID );
    });
    return $hits;
});

4. relevanssi_excerpt

Customize the excerpt shown in search results.

add_filter( 'relevanssi_excerpt', function( $excerpt, $post, $query ) {
    return wp_trim_words( $excerpt, 20, '...' );
}, 10, 3 );

This is helpful when you want to trim the output length or add custom formatting to the excerpt.

5. relevanssi_content_to_index

Control what content gets indexed from each post. This lets you append, modify, or strip specific content elements.

add_filter( 'relevanssi_content_to_index', function( $content, $post ) {
    $custom_field = get_post_meta( $post->ID, 'custom_field_name', true );
    return $content . ' ' . $custom_field;
}, 10, 2 );

You can use this to index custom fields, repeater fields, or ACF content that normally wouldn’t appear in search.

6. relevanssi_match

This advanced filter lets you manipulate the match logic itself during a search query.

add_filter( 'relevanssi_match', function( $match ) {
    if ( $match['term'] === 'free' ) {
        $match['weight'] = 0; // Reduce weight for certain terms
    }
    return $match;
});

7. Protecting Relevanssi Search from Abuse

Relevanssi can attract spammy queries or automated bot traffic, especially on larger sites. You can harden your search functionality by blocking bots from crawling search result pages and blacklisting certain search terms.

Block Bots in robots.txt

This code outputs search restrictions directly into your virtual robots.txt file, preventing search engines and bad bots from crawling unnecessary search pages:

add_action( 'do_robots', 'rlv_block_bots_robots_txt' );
function rlv_block_bots_robots_txt() {
	?>
User-agent: *
Disallow: /search/
Disallow: /?s=
	<?php
}

Block Specific Search Terms

You can block harmful or suspicious search terms by intercepting them early in the query lifecycle and halting the request with a 410 Gone status code:

add_filter( 'pre_get_posts', 'rlv_block_search' );
function rlv_block_search( $query ) {
    if ( ! empty( $query->query_vars['s'] ) ) {
        $blacklist = array( '大奖', 'q82' ); // add blacklist entries here; no need for whole words, use the smallest part you can
        foreach ( $blacklist as $term ) {
            if ( mb_stripos( $query->query_vars['s'], $term ) !== false ) {
                http_response_code( 410 );
                exit();
            }
        }
     }
}

These two simple functions can drastically reduce unwanted indexing and suspicious traffic from low-quality bots or scraper tools targeting your internal search.

Final Thoughts

Relevanssi offers a level of customization that’s hard to beat. Whether you’re a developer building a custom search interface or a site owner looking to improve relevance and user experience, these filters are your best tools.

The key to mastering Relevanssi lies in combining filters strategically—filter what gets indexed, adjust how it’s scored, and format how it’s presented.

With just a few well-placed filters and actions, you can tailor Relevanssi to match the exact needs of your site and audience. From excluding content types to boosting relevance and blocking abuse, the flexibility is unmatched. Start small, test each tweak, and you’ll quickly discover how powerful and efficient your WordPress search can become.