Relevanssi

Integrate search facets with the Relevanssi search plugin. Relevanssi greatly improves the quality and relevancy of search results by maintaining its own search index in the database.

Setup

Because of the way Relevanssi plugs itself into WordPress core search, the Relevanssi add-on integration must be installed when you use FacetWP together with Relevanssi. Without the add-on, Search facets and the site-wide search results page will not work correctly.

When the Relevanssi add-on is activated, each Search facet will show a new “Relevanssi” option within its “Search engine” setting. This new “Relevanssi” engine must be selected, otherwise the facet will return no results. If you have reasons to want to use the “WP Default” engine instead, the only way to make this work is to disable Relevanssi on the page where the Search facet is placed.

If your site-wide search results page (the page with /?s=searchterm in the URL) has facets, the above is all you need to do. But if it does not have facets, the search result page will not show results. To fix this, you need to disable FacetWP on the search results page.

Relevanssi limits

Be aware that using Relevanssi may require large amounts (hundreds of MBs) of database space (for a reasonable estimate, multiply the size of your wp_posts database table by three). If your hosting setup has a limited amount of space for database tables, using Relevanssi may cause problems. The following information is from the Relevanssi site:

“The upper limit of how big a site Relevanssi can support depends on your hardware. On shared hosting accounts with limited resources, tens of thousands of posts can be too much. If your hardware is solid, especially your database, there’s probably no upper boundary. The biggest site we’ve heard run Relevanssi without problems had two million posts, using a dedicated database server with SSD drives.”

Fix search issues

Test and fix unexpected search results

If you are using a Search facet with its search engine set to use Relevanssi, FacetWP asks Relevanssi to provide the post IDs to show in the results. This means that if you see unexpected search results, the first place to look is the Relevanssi settings.

To test the search results with the settings currently used, you can also use Relevanssi’s “Admin search” feature, located under: Dashboard > Admin search.

Turn off results snippets

Some users have reported issues with Relevanssi’s “Create custom search result snippets” feature.

If your results don’t show, try disabling that setting, as demonstrated below:

Prevent FacetWP interference with the search query on search result pages with no facets

If you have the FacetWP Relevanssi integration add-on installed, and your search results page (the page with /?s=searchterm in the URL) does not have facets, the search will not work properly: most often it will show no results, or other unexpected query interference may happen, like a different order of results than expected.

This is caused by FacetWP’s integration having to intercept the search query before it can know if facets are being used on the page. To fix this issue, you have to disable FacetWP for the search results page only, by adding the following code to your (child) theme’s functions.php:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'facetwp_is_main_query', function( $is_main_query, $query ) {
  if ( $query->is_search() && $query->is_main_query() ) {
    $is_main_query = false;
  }
  return $is_main_query;
}, 5, 2 );

Using Relevanssi with WooCommerce

If you are using Relevanssi together with WooCommerce, some things will not work immediately.

This article in the Relevanssi documentation gives a good overview of common compatibility issues and their fixes.

Fix search results for WooCommerce product SKUs

If you are using Relevanssi with WooCommerce, with product variations enabled, you may run into issues when searching variation product SKUs with the Search facet.

Relevanssi can index product and product variation SKUs for WooCommerce products: just add _sku to the list of custom fields to index. But Relevanssi will index SKUs for the variations only, so the parent product will not be found when searching for the variation SKU.

The following code (source) uses the relevanssi_content_to_index filter hook to index the product variation SKUs for the main product, so you will be able to find the parent product when searching for the variation SKU.

Add this code to your (child) theme’s functions.php, rebuild the Relevanssi index and re-index FacetWP:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'relevanssi_content_to_index', 'rlv_index_variation_skus', 10, 2 );

function rlv_index_variation_skus( $content, $post ) {
  if ( 'product' === $post->post_type ) {
    $args       = array(
      'post_parent'    => $post->ID,
      'post_type'      => 'product_variation',
      'posts_per_page' => -1
    );
    $variations = get_posts( $args );
    if ( ! empty( $variations ) ) {
      foreach ( $variations as $variation ) {
        $sku      = get_post_meta( $variation->ID, '_sku', true );
        $content .= " $sku";
      }
    }
  }
  return $content;
}

How to disable Relevanssi on certain pages

If you need to disable Relevanssi on specific pages or templates, all you need to do is unhook two Relevanssi filters. To do so, add the following code to your (child) theme’s functions.php. If you want to apply this code only to specific pages or templates, use a Conditional Tag. In this example the code is only applied to a page with ID 4814.

With this code in place, it is also possible to use the “WP Default” Search engine setting in Search facets when you have Relevanssi installed, which normally does not work.

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'wp_head', function() {
  if ( is_page( 4814 ) ) { // Optionally limit this code to a specific page or template, with a Conditional Tag.
    // Disable Relevanssi entirely
    remove_filter( 'posts_request', 'relevanssi_prevent_default_request' );
    remove_filter( 'posts_pre_query', 'relevanssi_query', 99 );
  }
} );

Change the minimum word length

By default, Relevanssi does not index words shorter than three characters. So search terms with less than three characters will not return any results in Search facets that use the Relevanssi engine.

You can change this with the “Minimum word length” setting. To find this setting, navigate to
Settings > Relevanssi > Indexing, then scroll down to “Advanced indexing settings”, then click “Show advanced settings”:

After making changes to this setting, make sure to rebuild Relavanssi’s index.

If you want to allow one-letter searches, you can do so with the “relevanssi_block_one_letter_searches” hook:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_filter( 'relevanssi_block_one_letter_searches', '__return_false' );

Note that (according to the above-linked documentation) this filter does not work if fuzzy matching is enabled (in Settings > Relevanssi > Searching > Keyword matching > “Partial words”).

Modify the Relevanssi search query

There may be situations in which you need to manipulate the Relevanssi search query. Using a pre_get_posts filter will not work in this case. It will lead to wrong post counts and pagination issues. Due to how FacetWP integrates with the Relevanssi query, also Relevanssi’s own relevanssi_modify_wp_query will not work.

The solution is to use FacetWP’s facetwp_relevanssi_do_query hook. This hook will run for both the default search page and when Relevanssi is set as the the engine in a search facet.

The following example adds a meta_query argument to exclude past events from the search results, based on an ACF end_date date field:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
add_action( 'facetwp_relevanssi_do_query', 'filter_past_events' );

function filter_past_events( $query ) {
  $query->set( 'meta_query', array (
    array(
      'meta_key' => 'end_date',
      'value' => date('Y-m-d'),
      'compare' => '>=',
      'type' => 'DATE'
    )
  ));
  return $query;
}

Display Relevanssi excerpts

When using a Search facet with Relevanssi set as its search engine, FacetWP only asks Relevanssi to provide post IDs as results, which means Relevanssi-generated excerpts are not included and automatically generated when you display post excerpts with the_excerpt().

The following code snippet can be used to generate and display Relevanssi-generated excerpts in your listing template. Make sure to replace my_search_facet with the name of your Search facet, in line 2.

The third parameter of relevanssi_do_excerpt() is the excerpt length in words or chars, as set in the fourth parameter:

How to use custom PHP code?
PHP code can be added to your (child) theme's functions.php file. Alternatively, you can use the Custom Hooks add-on, or a code snippets plugin. More info
// global $post;  // Add if not available
$searchfacet = FWP()->facet->facets['my_search_facet']; // Replace 'my_search_facet' with the name of your Search facet
$query = isset( $searchfacet ) ? $searchfacet['selected_values'] : '';
echo relevanssi_do_excerpt( $post, $query, 30, 'words' );  // Excerpt length of 30 'words'. The last parameter can also be set to 'chars'.

See also

• The Search facet type
• Using FacetWP with WooCommerce
• Using FacetWP with SearchWP
• Redirect a search box to a FacetWP results page
• How to add a “Clear” button to a Search facet
• Add search suggestions below a Search facet
• How to filter WP attachments and draft, pending or private posts
• Using FacetWP with Advanced Custom Fields