relevanssi_do_query()

relevanssi_do_query( WP_Query &$query )

Takes a WP_Query object and runs the search query based on that.

Source: /lib/search.php

Parameters

&$query
(WP_Query) (required) A WP_Query object passed as a reference, a source for the query parameters and the results are stored in the posts attribute.

Returns

No return value; the results are placed in the posts attribute of the WP_Query object.

Usage

This function can be used to run Relevanssi searches anywhere. Just create an empty WP_Query object, give it some parameters, make sure the ‘s’ parameter is set and contains the search query and then run relevanssi_do_query() on the query object.

In general, you don’t need to call this function. It’s better to just set the relevanssi flag to true for WP_Query:

$args  = array(
    's'           => 'search terms',
    'numberposts' => 10,
    'post_types'  => array( 'post', 'page', 'custom_cpt' ),
    'relevanssi'  => true,
    // add other parameters here...
);

$query = new WP_Query( $args );

// Now the posts found are in $query->posts.

You can use relevanssi_do_query() without a search query parameter, but in general, it doesn’t make much sense. If you’re just doing filtering with taxonomy queries or meta queries, you usually don’t need Relevanssi, as plain WP_Query can do the same without extra overhead.

The query object is like expected: the number of found posts is reported in $query->found_posts and so on. The post objects in $query->posts have a couple of extra features:

• The relevance scores Relevanssi has calculated are stored in $post->relevance_score.
• If you use Relevanssi-generated excerpts, those are placed in $post->post_excerpt and the original excerpt can be found in $post->original_excerpt.
• If title highlighting is used, the highlighted title is in $post->post_highlighted_title.

If you wish to use different options for the query run through relevanssi_do_query(), the best way is to use the pre_option_ hooks. For example, if you normally use Relevanssi-generated excerpts but don’t want excerpts in the relevanssi_do_query() search, you can do this:

$args  = array( // parameters here );
$query = new WP_Query();
$query->parse_query( $args );
  
add_filter( 'pre_option_relevanssi_excerpts', '__return_false' );
relevanssi_do_query( $query );
remove_filter( 'pre_option_relevanssi_excerpts', '__return_false' );

If you don’t need post objects and only want to use post IDs, it’s highly recommended to set the fields parameter to ids.

Note on relevanssi_modify_wp_query

Note that if you have filters on relevanssi_modify_wp_query, these do not run when you call relevanssi_do_query() directly. If you need these filters, you need to run them manually:

$args  = array( // parameters here );
$query = new WP_Query();
$query->parse_query( $args );
  
apply_filters( 'relevanssi_modify_wp_query', $query );
relevanssi_do_query( $query );

Whenever you feel like using relevanssi_do_query(), do consider first if what you want can be done with a filter function on relevanssi_modify_wp_query. If it can be done that, that’s almost always the right way to do it.

Query parameters

Relevanssi understands most of the parameters WP_Query does. Here’s the complete list:

• Taxonomies:
  • tax_query
  • cats (comma-separated list of category IDs)
  • tags (comma-separated list of tag IDs for OR logic, combined with + for AND logic)
  • tag_slug__not_in
• Custom fields:
  • meta_query
  • customfield_key
  • customfield_value
  • meta_key
  • meta_value
  • meta_value_num
  • meta_compare
• Author:
  • author
  • author_name
• Post parameters:
  • p
  • page_id
  • post__in
  • post__not_in
  • post_parent
  • post_parent__in
  • post_parent__not_in
  • post_type
  • post_types (same as post_type, but more reliable)
  • post_status
• Phrases:
  • sentence
• Dates:
  • date_query
  • year
  • monthnum
  • week
  • day
  • hour
  • minute
  • second
  • m
  • by_date (digit followed by h, d, w, m, or y for simple recentness filtering)
• Search logic:
  • operator (only in Premium)
• Pagination:
  • offset
  • paged
  • posts_per_page
• Sorting:
  • order (either string or array with orderby)
  • orderby
• Return fields:
  • fields
• Other:
  • relevanssi_admin_search (forces admin search logic)
  • include_attachments

Relevant options

• relevanssi_log_queries – if enabled, log queries.
• relevanssi_excerpts – if enabled, create excerpts, unless this is an admin search.
• relevanssi_hilite_title – if enabled and fields is not set, highlight the title, if relevanssi_highlight is also enabled.
• relevanssi_excerpt_length and relevanssi_excerpt_type – these adjust the excerpt length.
• relevanssi_show_matches – if enabled, the search breakdown is added to the post excerpt (whether or not custom excerpts are used).

Global variables

• $relevanssi_active – This is set to true at the beginning of the function and false at the end and can be used to check if Relevanssi is currently searching.
• $relevanssi_admin_test – If this boolean is true, Relevanssi behaves like the WP_ADMIN constant was set to true. This is for testing purposes.

Filters

relevanssi_hits_filter ( array $filter_data )
Filters the search results relevanssi_do_query() gets from relevanssi_search() which does the actual searching. The array has two items in it: in index 0, there’s an array of post objects, and in index 1 there’s the search query string. The filter needs to return a similar array back: other filters may follow and expect the search query string to be there. Relevanssi itself does not use the query string, so modifying does not have an effect on Relevanssi. Note: instead of post objects, the array may also contain post IDs or parent=>ID pairs, depending on the fields parameter. Write your functions so that they can manage all these cases.

The searching process is controlled by many other filters that are applied in other functions.