Super Search 3.x

Legacy documentation for Super Search 3.x.

Relevance Ordering

Super Search allows you to create simple and advanced algorithms to control ranking of entries in search results. This is done by using the relevance-related parameters in the Super_Search:Results tag. First and foremost, the relevance functionality only works on Keyword searches, and all relevance-related parameters mentioned below refer to usage in the Super_Search:Results tag. This page serves as a detailed explanation for how to implement this in your site.

Ordering by Relevance

The relevance parameter tells Super Search to rank entry results in order of their relevance. The relevance algorithm is fairly simple in that it merely counts the frequency your keywords appear in the fields you indicate in the parameter. An entry where your keywords occur more frequently ranks higher than entries with lesser keyword frequency.

Because relevance ranking is slower than normal searching, it is turned off in Super Search by default. Turn it on, simply by providing the relevance parameter with field names and numeric weights as the value of the parameter. You can indicate title field and all custom fields for relevance searching.

relevance="title=5+summary=1+body=2"

In the above example, entries will be ranked by relevance where the title, summary and body fields are considered. Keywords appearing in the title field will get a 5 points awarded for each term match, 1 point for each term match in summary, and 2 points for each term match in body.

For example, if you have an entry with the following data:

Title: The Bird Is The Word

Summary: A-well everybody's heard about the bird. Bird bird bird, b-bird's the word.

Body: Well don't you know about the bird? Well everybody knows that the bird is the word! A-well-a bird bird, b-bird's the word.

With the above relevance algorithm, and a search of Bird, points would be awarded as following:

Title: The Bird (5) Is The Word

Summary: A-well everybody's heard about the bird (1). Bird (1) bird (1) bird (1), b-bird's the word.

Body: Well don't you know about the bird (2)? Well everybody knows that the bird (2) is the word! A-well-a bird (2) bird (2), b-bird's the word.

Add that all up and this entry's total relevance score would be: 17.

You probably noticed that in the above example, b-bird's was excluded from the count. This is because by default, the relevance parameter does NOT look for keywords that exist within other words. For example, if an entry contains the word caterpillar, and the user searches for cat, it will not be counted as a relevance match. To change this behavior, you can add +count_words_within_words to the end of your values in the relevance parameter. Example:

relevance="title=5+summary=1+body=2+count_words_within_words"

With the above relevance algorithm, and a search of Bird, points would be awarded as following:

Title: The Bird (5) Is The Word

Summary: A-well everybody's heard about the bird (1). Bird (1) bird (1) bird (1), b-bird's (1) the word.

Body: Well don't you know about the bird (2)? Well everybody knows that the bird (2) is the word! A-well-a bird (2) bird (2), b-bird's (2) the word.

Add that all up and this entry's total relevance score would be: 20.

Advanced Relevance Algorithms

You might, for example, have a classifieds site. Within that context, you might have two different types of listings - those that are posted as a premium account member, and ones posted as a free account member. It's very likely that you would want to provide your premium account members the advantage of their listings always showing up above listings posted by free account members.

Super Search has a special relevance_multiplier parameter that lets you adjust the relevance ranking. It allows you to increase the relevance rank of entries based on a value in a custom field. What you can do is have an additional custom field that stores a numeric value. Let's say that field is named account_type. You could have that field store a value of 1 for listings (channel entries) created by free member accounts, and a value of 10 for listings created by premium member accounts. You would then specify this parameter (in conjunction with relevance parameter):

relevance_multiplier="account_type"

Whatever the relevance value becomes based on the search query, will then be multiplied by the value in the account_type multiplier field. So if a listing posted from a free account gets a score of 9, it will stay at 9 (9 x 1 = 9), and the if the entry posted from a premium account gets a score of 4, it will turn into 40 (4 x 10 = 40), and actually end up being ranked higher. Multiple weighting fields can be specified for this parameter. Separate multiples with the plus character (+). Example:

relevance_multiplier="account_type+another_weighting_field+yet_another"

If you wish to take relevance proximity into account, the relevance_proximity parameter is available for use in the Results tag. Relevance proximity only gets used when there are multiple keywords searched upon (ex: blue sweater). When it’s enabled and multiple keywords are passed, it takes into account how far apart the keywords are in the entry text (ex: i like my blue sweater is ranked higher than the sky is blue, and I’m wearing a sweater). The intention being that multi-word searches are more relevant when the search terms are closer together. To enable relevance proximity, specify a value of yes (default value of 1.3), or you can specify your own numeric value. The value you specify should be higher than 1, as the extra points are applied to entries with closer proximity keyword matches. By default, this parameter is set to no. This must be used in conjunction with the relevance parameter.

Going Deeper

If that's not enough for you, it's also possible to set an override multiplier onto a weighting field multiplier. So going off of the example above, if you set the parameter like this:

relevance_multiplier="account_type=0.2"

The value in the custom field holding the multiplier value would be multiplied by the value in the relevance_multiplier parameter. So if an entry posted from a free account gets a score of 9, it will be reduced to 1.8 (9 x (1 x 0.2 = 0.2) = 1.8), and the if the entry posted from a premium account gets a score of 4, it will turn into 8 (4 x (10 x 0.2 = 2) = 8).

This is a very special use-case, and only really makes sense when you're creating a complex weighting algorithm for your results. You would likely be working with several weighting fields, and you would be trying to scale values to be in line with each other. For example, if you wanted to base relevance multiplying on a field that contained an account type value (such as premium, etc) with numbers anywhere between 1 and 10, and also set ranking on product price with numbers anywhere between 100 and 500, you might want to bring the price multiplier more in line with the account type field value. In that case, you might multiply the account_type field by 2, and multiply the price field by 0.1. That would bring a price value of $200 down to only multiplying the relevance score by 20, and an account type of 10 up to multiplying the relevance score by 20. The parameter would look like this:

relevance_multiplier="account_type=2+price=0.2"

And lastly, you also reduce an entry's relevance score by using a negative multiplier. You might want to do this to lower the positioning/rank of an entry based on a higher number it contains in the weighting field. The parameter might end up looking like this:

relevance_multiplier="weighting_field=-3"

So if an entry had a relevance score of 12, and the weighting field contained a value of 10, the entry would actually end up with a relevance score of -360 (12 x (10 x -3 = -30) = -360).

Showing Relevance Scores

Your entries will already be re-ordered within the search results page, based on their relevance score. If you wish to display the actual total relevance score for each entry, you can use the relevance_count variable within the Super_Search:Results loop:

{relevance_count}

Code Examples

Using the basic relevance functionality, your Super_Search:Results loop might look something like this:

{exp:super_search:results
    channel="listings"
    status="open"
    paginate="both"
    limit="20"
    relevance="title=5+summary=1+body=2+count_words_within_words"
}

<div class="search_result">
    <h3>{title}</h3>
    <p>{body}</p>
    <p>Relevance Score: {relevance_count}</p>
</div>

{paginate}
    <p>
        Page {current_page} of
        {total_pages} pages
        {pagination_links}
    </p>
{/paginate}

{if super_search_no_results}
    <p>No results matched your query.</p>
{/if}

{/exp:super_search:results}

Using the some advanced relevance multiplier functionality, your Super_Search:Results loop might look something like this:

{exp:super_search:results
    channel="listings"
    status="open"
    paginate="both"
    limit="20"
    relevance="title=5+summary=1+body=2+count_words_within_words"
    relevance_multiplier="account_type=2+price=0.2"
}

<div class="search_result">
    <h3>{title}</h3>
    <p>Price: ${price}</p>
    <p>{body}</p>
    <p>Relevance Score: {relevance_count}</p>
</div>

{paginate}
    <p>
        Page {current_page} of
        {total_pages} pages
        {pagination_links}
    </p>
{/paginate}

{if super_search_no_results}
    <p>No results matched your query.</p>
{/if}

{/exp:super_search:results}