Complex queries

A complex search combines a text query with rules about which results are eligible. Relevanssi searches its index for the words, then applies restrictions such as post type, taxonomy, metadata, or publication date. Start by confirming that the intended content is indexed; adding query parameters cannot make unindexed text searchable.

Queries visitors can enter

Quoted phrases

Enclose several words in double quotes to request a phrase, for example "indigo harbor". Phrase searching is available in Free and Premium. Relevanssi checks stored titles and content, with additional sources such as indexed custom fields and taxonomy names according to the configuration.

Phrase checking uses the stored source text, so a phrase visible on the rendered page may not exist as one contiguous string in the database. For example, indigo <em>harbor</em> does not contain the literal string indigo harbor. Text generated by shortcodes or a page builder can have similar limitations. Inspect the stored content and relevant field values when an ordinary word search succeeds but a phrase search does not.

When a query contains several phrases, AND requires all of them and OR permits a match to any of them. Choose the default under Relevanssi > Settings > Searching > Default operator. An AND search can fall back to OR if it finds nothing. In the Fallback to OR row, check the switch described as Disable the OR fallback when all terms must remain mandatory; this row is shown when AND is selected. Other configured fallback filters can also affect the final result.

Required and excluded words (Premium)

• orchard +cobalt: in an OR search, cobalt must occur in each returned document. In an AND search, the positive terms are already required.
• orchard -cobalt: find matches for orchard while excluding documents containing the indexed term cobalt. This works with AND and OR.

Attach the sign directly to the word. These operators work with indexed terms; do not treat them as a general Boolean expression language for nested parentheses, arbitrary phrases, or every wildcard combination.

Internal wildcards (Premium)

Wildcard operators are disabled by default. Enable them in a site plugin or child theme with:

add_filter( 'relevanssi_wildcard_search', '__return_true' );

The supported wildcard must be inside a word, with a word character on each side. w?rd matches a single character in that position, such as word or ward. w*rd matches zero or more characters, including wrd, word, and weird. This does not make *word or word* a supported leading or trailing wildcard pattern.

Wildcard matching and the Keyword matching setting are different features. See Wildcard matching for the dedicated guide.

Parameters in a search form

A normal WordPress search form submits its text as s. Additional inputs can provide public query variables such as post_type, cat, category_name, tag, author, year, monthnum, and day. Premium also registers operator for an AND or OR override.

For example, a hidden post_type input with value post requests ordinary posts. A hidden input is still editable by the visitor through the URL; it is useful for form defaults, not access control. Apply restrictions that must always hold on the server, and enforce permissions independently.

The Searching tab’s Ignore theme post type settings option can remove a post_type restriction. Developers can use Relevanssi’s post_types query variable when an explicit allowed-type list is needed. Check Respect exclude_from_search too when an indexed type is absent from frontend results.

You can build dropdowns yourself or use the search form shortcode. Nested tax_query, meta_query, and date_query arrays belong in server-side query construction; they are not automatically supported as arbitrary URL parameters.

Modify the main search query

Use relevanssi_modify_wp_query to change the query before Relevanssi runs. Return the query object. The following example targets only the main frontend search and adds a category restriction while preserving an existing taxonomy query:

add_filter( 'relevanssi_modify_wp_query', 'rlv_manual_limit_categories' );
function rlv_manual_limit_categories( $query ) {
    if ( is_admin() || ! $query->is_main_query() || ! $query->is_search() ) {
        return $query;
    }

    $restriction = array(
        'taxonomy' => 'category',
        'field'    => 'slug',
        'terms'    => array( 'poetry', 'nonfiction' ),
    );
    $existing = $query->get( 'tax_query' );
    $query->set(
        'tax_query',
        $existing
            ? array( 'relation' => 'AND', $existing, $restriction )
            : array( $restriction )
    );
    return $query;
}

Replace the category slugs with terms that exist on your site. The two terms within this one clause use the default IN operator: a post may belong to either category. The outer AND, when needed, combines this restriction with the existing taxonomy conditions.

WordPress’s pre_get_posts action is another way to set query parameters. Scope it carefully to the intended query. Do not run a second search merely to replace results that the main query has already fetched.

Run a separate Relevanssi query

When you need an independent search, set relevanssi to true on a WP_Query. For example:

$query = new WP_Query(
    array(
        's'              => 'orchard cobalt',
        'post_type'      => 'post',
        'post_status'    => 'publish',
        'posts_per_page' => 20,
        'relevanssi'     => true,
    )
);
// $query->posts contains this page of results.

post_type names a type such as post, page, or a registered custom type. publish is a post status, so it belongs in post_status. If Relevanssi is inactive, WordPress can still run the query, but its ordinary search behaviour differs.

If you iterate using $query->the_post(), call wp_reset_postdata() afterwards. For direct control without automatically executing an initial query, see relevanssi_do_query().

Combine taxonomy conditions

This example searches for orchard and accepts either a post in the “quotes” category, or a post that has both the “quote” post format and the “wisdom” category:

$query = new WP_Query(
    array(
        's'           => 'orchard',
        'post_type'   => 'post',
        'post_status' => 'publish',
        'relevanssi'  => true,
        'tax_query'   => array(
            'relation' => 'OR',
            array(
                'taxonomy' => 'category',
                'field'    => 'slug',
                'terms'    => array( 'quotes' ),
            ),
            array(
                'relation' => 'AND',
                array(
                    'taxonomy' => 'post_format',
                    'field'    => 'slug',
                    'terms'    => array( 'post-format-quote' ),
                ),
                array(
                    'taxonomy' => 'category',
                    'field'    => 'slug',
                    'terms'    => array( 'wisdom' ),
                ),
            ),
        ),
    )
);

The taxonomies and terms must exist, and posts must have the corresponding assignments. A taxonomy filter restricts eligibility even if taxonomy names are not selected for full-text indexing. Text search and taxonomy filtering are separate parts of the query.

Metadata and date filters

Use meta_query to compare stored field values, and date_query for publication-date ranges. For a numeric field comparison, declare a numeric type:

$query = new WP_Query(
    array(
        's'           => 'orchard',
        'post_type'   => 'post',
        'post_status' => 'publish',
        'relevanssi'  => true,
        'meta_query'  => array(
            array(
                'key'     => 'price',
                'value'   => 15,
                'compare' => '>=',
                'type'    => 'NUMERIC',
            ),
        ),
    )
);

This checks the stored price value; it does not require that field to be selected for full-text indexing. Searching for words within that field does require indexing it. Serialized arrays and formatted display values may not be suitable for a direct numeric comparison.

For sorting, set orderby and order explicitly when needed, for example orderby => 'date' and order => 'DESC'. Otherwise Relevanssi’s configured ordering applies. Consult the WordPress WP_Query reference for array structure and parameter meanings, and verify that Relevanssi supports the particular combination you use.

Test the intended result set

Use known examples that should match and examples that should be excluded. Inspect $query->posts, found_posts, and pagination. Check AND-to-OR fallback, fuzzy matching, synonyms, post type restrictions, and access rules when results are broader or narrower than expected.

Complex metadata conditions can be expensive on a large database. Measure with representative data before replacing them with result filtering. relevanssi_hits_filter is an alternative for conditions best evaluated in PHP, but fetching a large candidate set can also be expensive. Neither approach is automatically faster for every site.

Forms supplied by other plugins depend on that plugin’s integration and query construction. Test the installed versions and the actual form, including any Ajax requests, rather than assuming every combination behaves like a standard WordPress search.