WordPress.org

Knowledge Base

You can find solutions and answers at the Relevanssi Knowledge Base.

Relevanssi doesn't work

If you the results don't change after installing and activating Relevanssi, the most likely reason is that you have a call to query_posts() on your search results template. This confuses Relevanssi. Try removing the query_posts call and see what happens.

Where are the user search logs?

See the top of the admin menu. There's 'User searches'. There. If the logs are empty, please note showing the results needs at least MySQL 5.

Displaying the number of search results found

The typical solution to showing the number of search results found does not work with Relevanssi. However, there's a solution that's much easier: the number of search results is stored in a variable within $wp_query. Just add the following code to your search results template:

<?php echo 'Relevanssi found ' . $wp_query->found_posts . ' hits'; ?>

Advanced search result filtering

If you want to add extra filters to the search results, you can add them using a hook. Relevanssi searches for results in the _relevanssi table, where terms and post_ids are listed. The various filtering methods work by listing either allowed or forbidden post ids in the query WHERE clause. Using the relevanssi_where hook you can add your own restrictions to the WHERE clause.

These restrictions must be in the general format of

AND doc IN (' . {a list of post ids, which could be a subquery} . ')

For more details, see where the filter is applied in the relevanssi_search() function. This is stricly an advanced hacker option for those people who're used to using filters and MySQL WHERE clauses and it is possible to break the search results completely by doing something wrong here.

There's another filter hook, relevanssi_hits_filter, which lets you modify the hits directly. The filter passes an array, where index 0 gives the list of hits in the form of an array of post objects and index 1 has the search query as a string. The filter expects you to return an array containing the array of post objects in index 0 (return array($your_processed_hit_array)).

Direct access to query engine

Relevanssi can't be used in any situation, because it checks the presence of search with the is_search() function. This causes some unfortunate limitations and reduces the general usability of the plugin.

You can now access the query engine directly. There's a new function relevanssi_do_query(), which can be used to do search queries just about anywhere. The function takes a WP_Query object as a parameter, so you need to store all the search parameters in the object (for example, put the search terms in $your_query_object->query_vars['s']). Then just pass the WP_Query object to Relevanssi with relevanssi_do_query($your_wp_query_object);.

Relevanssi will process the query and insert the found posts as $your_query_object->posts. The query object is passed as reference and modified directly, so there's no return value. The posts array will contain all results that are found.

Sorting search results

If you want something else than relevancy ranking, you can use orderby and order parameters. Orderby accepts $post variable attributes and order can be "asc" or "desc". The most relevant attributes here are most likely "post_date" and "comment_count".

If you want to give your users the ability to sort search results by date, you can just add a link to http://www.yourblogdomain.com/?s=search-term&orderby=post_date&order=desc to your search result page.

Order by relevance is either orderby=relevance or no orderby parameter at all.

Filtering results by date

You can specify date limits on searches with by_date search parameter. You can use it your search result page like this: http://www.yourblogdomain.com/?s=search-term&by_date=1d to offer your visitor the ability to restrict their search to certain time limit (see RAPLIQ for a working example).

The date range is always back from the current date and time. Possible units are hour (h), day (d), week (w), month (m) and year (y). So, to see only posts from past week, you could use by_date=7d or by_date=1w.

Using wrong letters for units or impossible date ranges will lead to either defaulting to date or no results at all, depending on case.

Thanks to Charles St-Pierre for the idea.

Caching

Relevanssi has an included cache feature that'll store search results and post excerpts in the database for reuse. It's something of an experimental feature right now, but should work and if there are lots of repeat queries, it'll give some actual boost in performance.

Displaying the relevance score

Relevanssi stores the relevance score it uses to sort results in the $post variable. Just add something like

echo $post->relevance_score

to your search results template inside a PHP code block to display the relevance score.

Did you mean? suggestions

To use Google-style "did you mean?" suggestions, first enable search query logging. The suggestions are based on logged queries, so without good base of logged queries, the suggestions will be odd and not very useful.

To use the suggestions, add the following line to your search result template, preferably before the have_posts() check:

<?php if (function_exists('relevanssi_didyoumean')) { relevanssi_didyoumean(get_search_query(), "<p>Did you mean: ", "?</p>", 5); }?>

The first parameter passes the search term, the second is the text before the result, the third is the text after the result and the number is the amount of search results necessary to not show suggestions. With the default value of 5, suggestions are not shown if the search returns more than 5 hits.

Search shortcode

Relevanssi also adds a shortcode to help making links to search results. That way users can easily find more information about a given subject from your blog. The syntax is simple:

[search]John Doe[/search]

This will make the text John Doe a link to search results for John Doe. In case you want to link to some other search term than the anchor text (necessary in languages like Finnish), you can use:

[search term="John Doe"]Mr. John Doe[/search]

Now the search will be for John Doe, but the anchor says Mr. John Doe.

One more parameter: setting [search phrase="on"] will wrap the search term in quotation marks, making it a phrase. This can be useful in some cases.

Restricting searches to categories and tags

Relevanssi supports the hidden input field cat to restrict searches to certain categories (or tags, since those are pretty much the same). Just add a hidden input field named cat in your search form and list the desired category or tag IDs in the value field - positive numbers include those categories and tags, negative numbers exclude them.

This input field can only take one category or tag id (a restriction caused by WordPress, not Relevanssi). If you need more, use cats and use a comma-separated list of category IDs.

The same works with post types. The input fields are called post_type and post_types.

You can also set the restriction from general plugin settings (and then override it in individual search forms with the special field). This works with custom taxonomies as well, just replace cat with the name of your taxonomy.

If you want to restrict the search to categories using a dropdown box on the search form, use a code like this:

<form method="get" action="<?php bloginfo('url'); ?>">
    <div><label class="screen-reader-text" for="s">Search</label>
    <input type="text" value="<?php the_search_query(); ?>" name="s" id="s" />
<?php
    wp_dropdown_categories(array('show_option_all' => 'All categories'));
?>
    <input type="submit" id="searchsubmit" value="Search" />
    </div>
</form>

This produces a search form with a dropdown box for categories. Do note that this code won't work when placed in a Text widget: either place it directly in the template or use a PHP widget plugin to get a widget that can execute PHP code.

Restricting searches with taxonomies

You can use taxonomies to restrict search results to posts and pages tagged with a certain taxonomy term. If you have a custom taxonomy of "People" and want to search entries tagged "John" in this taxonomy, just use ?s=keyword&people=John in the URL. You should be able to use an input field in the search form to do this, as well - just name the input field with the name of the taxonomy you want to use.

It's also possible to do a dropdown for custom taxonomies, using the same function. Just adjust the arguments like this:

wp_dropdown_categories(array('show_option_all' => 'All people', 'name' => 'people', 'taxonomy' => 'people'));

This would do a dropdown box for the "People" taxonomy. The 'name' must be the keyword used in the URL, while 'taxonomy' has the name of the taxonomy.

Automatic indexing

Relevanssi indexes changes in documents as soon as they happen. However, changes in shortcoded content won't be registered automatically. If you use lots of shortcodes and dynamic content, you may want to add extra indexing. Here's how to do it:

if (!wp_next_scheduled('relevanssi_build_index')) {
    wp_schedule_event( time(), 'daily', 'relevanssi_build_index' );
}

Add the code above in your theme functions.php file so it gets executed. This will cause WordPress to build the index once a day. This is an untested and unsupported feature that may cause trouble and corrupt index if your database is large, so use at your own risk. This was presented at forum.

Highlighting terms

Relevanssi search term highlighting can be used outside search results. You can access the search term highlighting function directly. This can be used for example to highlight search terms in structured search result data that comes from custom fields and isn't normally highlighted by Relevanssi.

Just pass the content you want highlighted through relevanssi_highlight_terms() function. The content to highlight is the first parameter, the search query the second. The content with highlights is then returned by the function. Use it like this:

if (function_exists('relevanssi_highlight_terms')) {
    echo relevanssi_highlight_terms($content, get_search_query());
}
else { echo $content; }

What is tf * idf weighing?

It's the basic weighing scheme used in information retrieval. Tf stands for term frequency while idf is inverted document frequency. Term frequency is simply the number of times the term appears in a document, while document frequency is the number of documents in the database where the term appears.

Thus, the weight of the word for a document increases the more often it appears in the document and the less often it appears in other documents.

What are stop words?

Each document database is full of useless words. All the little words that appear in just about every document are completely useless for information retrieval purposes. Basically, their inverted document frequency is really low, so they never have much power in matching. Also, removing those words helps to make the index smaller and searching faster.