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.

Here’s a simple example:

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

$query = new WP_Query();
$query->parse_query( $args );

relevanssi_do_query( $query );

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

Note that the code does new WP_Query() and then parse_query( $args ), instead of doing new WP_Query( $args ). This is the preferred way. If you give the arguments to the WP_Query constructor, the query is immediately run. With parse_query(), the query isn’t run; this saves resources.

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.

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.