relevanssi_match

apply_filters( 'relevanssi_match', object $match, int $idf, string $term )

Filters the Relevanssi post term matches, giving lots of power over the weights of the results.

Parameters

$match
(object) The match object, with the post ID in the doc attribute, the term in term, term frequency in tf, the weight in weight and the term occurrances in various other attributes (see below).

$idf
(int) The inverse document frequency for this term, to recalculate TF × IDF values.

$term
(string) The search term.

The match object

The match objects this hook filters are actually rows from the wp_relevanssi database table. This means they have the following fields:

  • doc – the post ID; for users, user ID prefixed with u_, for post type archives the name of the post type prefixed with p_, for taxonomy terms **{taxonomy}**{term ID}
  • term – the word
  • term_reverse – the word, reversed
  • content – occurrances for the word in post content
  • title – occurrances in the title
  • excerpt – occurrances in the excerpt
  • comment – occurrances in content
  • tag – occurrances in tags assigned to this post
  • category – occurrances in categories of this post
  • taxonomy – occurrances in other taxonomies
  • link – occurrances in internal links from other posts
  • author – occurrances in author name
  • customfield – occurrances in custom fields
  • mysqlcolumn – occurrances in other MySQL columns (Premium only)
  • customfield_detail – a JSON object detailing which custom fields match the word (Premium only)
  • taxonomy_detail – a JSON object detailing which taxonomies match the word (Premium only)
  • type – “post” for all posts, “user” for users, taxonomy slug for terms, “attachment” for attachment content
  • item – the ID number for non-post matches (Premium only)

There are also some calculated values:

  • tf – the term frequency, with weight boosts from the settings applied
  • weight – the relevancy score, TF × IDF and possibly some adjustments included

More information

When Relevanssi searches, it splits the search query into individual search terms and does a database query for each term to find the results that match that search term. These matches are then looped through and for each match, the weight is calculated and stored: now Relevanssi knows that post N has some bit of weight for this term.

This is repeated for all search terms. After that Relevanssi sums up all weights for each post, and this is the total relevancy score of each post.

This filter hook is applied to the key part of the process. Each individual match passes through this filter hook, so this is an excellent place for adjusting the weights of the matches. For many cases, this is the best spot for adjusting the weights. Not for all cases, though: this filter may fire multiple times for each post, so if your adjustment is based on posts, you want to use some other filter hook (for example relevanssi_results).

To use this filter hook, you usually want to modify the $match->weight somehow, either to increase it or to decrease it. If you set the weight to 0, this term match will be removed from the result set. Modifying other parts of the $match object doesn’t have any effect on Relevanssi; it may have an effect on other filter functions running on a later priority for this hook. The only values from the $match object Relevanssi uses after this filter hook runs are weight, doc and item, and you definitely don’t want to modify doc or item. Make sure you return the full object after you’re done modifying it.

There are lots of examples of using this filter hook and relevanssi_results here.

More examples:

Performance

Note that the relevanssi_match filter can run hundreds of times per search query. If you’re doing something here that involves database queries, be aware that this may be a significant performance hit. You can find good tips on creating more robust filter functions here.