This page describes how to help your users refine their search queries using refinement labels. Unlike search engine labels, refinement labels are visible to your users, and appear at the top of the search results page.
- Overview
- Creating Refinement Labels
- Tagging Sites with Labels
- Controlling the Number of Displayed Refinement Labels
Overview
Even after you've assembled the result set for your search engine and tweaked the rankings, your users might still type queries that are too broad. For example, if users search for a health condition, it is not clear what kind of information they are looking for. Are they looking for information about symptoms, treatments, or risk factors? However, if they can select refinements, or categories of search results, they can narrow their searches and get to the answers quickly.
![Search results page
with a selection of refinement links](https://developers-dot-devsite-v2-prod.appspot.com/static/custom-search/images/refinements.png?authuser=5)
Refinements are labels that you apply to sites to categorize them. The refinement labels you create appear as links at the top of your search results pages. When a user clicks one of the refinement links, sites that you have tagged with the refinement label are—depending on how you have defined the label—either searched exclusively or promoted above other results. You can even append your users' queries with additional search terms to help them retrieve more targeted results or redirect them to a different page.
Creating Refinement Labels
You can create refinement labels and tag sites with them in the Refinements tab of the control panel, but you can have greater control over the ranking if you are using the Programmable Search XML annotations file. As with the search engine labels, you define refinement labels in the context file and apply them to sites in the annotations file.
As the following example shows, refinement labels are defined using
Facet
elements within the Context
section.
<CustomSearchEngine> <Title>Universities</Title> <Context> <Facet> <FacetItem title="Lectures"> <Label name="lectures" mode="BOOST" weight="0.8"> <Rewrite>lecture OR lectures</Rewrite> </Label> </FacetItem> </Facet> <Facet> <FacetItem title="Assignments"> <Label name="assignments" mode="BOOST" weight="0.8"> <Rewrite>homework OR assignment OR assignments</Rewrite> </Label> </FacetItem> </Facet> <Facet> <FacetItem title="Reference"> <Label name="reference" mode="FILTER"> </Label> </FacetItem> </Facet> <Facet> <FacetItem title="Papers"> <Label name="papers" mode="FILTER"/> <Redirect url="http://scholar.google.com/scholar?q=$q"/> </FacetItem> </Facet> <BackgroundLabels> <Label name="_cse_omuauf_lfve" mode="FILTER"/> <Label name="_cse_exclude_omuauf_lfve" mode="ELIMINATE"/> </BackgroundLabels> </Context> </CustomSearchEngine>
The Facet
element has the following structure:
Facet
Each Facet
elements can have up to four FacetItem
child elements. You can create as many refinement labels as you want. You can
also control how many labels appear on search results pages
.
Example: Refinement Labels
A basic refinement labels look like the following:
<Facet> <FacetItem title="Lectures"> <Label name="lectures" mode="BOOST" weight="0.8"/></Label> </FacetItem> </Facet>
Figure 3: The sample code produces a search results page with a label.
Elements of Refinement Labels
The following are the child elements of Facet
.
Element | Attribute | Description | Value |
---|---|---|---|
FacetItem |
title |
The refinement link that is displayed at the top of the results page. | The title of the link. In the example above, that is "Lectures" link at the top of the result page. The title should be descriptive and as short as possible. The refinement links might be truncated to save space, particularly if the search results page has many refinement links. You could also use the term |
Label |
name |
The name of the refinement label.
You use this name to tag sites in the annotations file.
In addition, Programmable Search Engine appends the label name to the queries of
your users after they click a refinement link. If you were to look back at
the Overview section, the sample search results
page show a search box with "pimple more:condition_treatment". The
"more:condition_treatment" part indicates use of a label, and
"condition_treatment" is the value of the |
A descriptive name for your label. When you look at your annotations file, it would be good for you to be able to discern the purpose of the labels without having to refer back to the context files. You must follow the naming convention, which includes the following:
|
mode |
Modes in search engine labels and refinement labels work in the same
manner.
You can create all three types—boost, filter, and eliminate refinements—in the same search engine. For more detailed documentation about how weights work, see Ranking Search Results page. |
Specify a mode value for each label:
|
|
weight |
Weights in search engine labels and refinement labels work in the same manner. For more detailed documentation about how weights works, see Ranking Search Results. | For boost and filter labels only. Any value between
-1.0 and + 1.0 . If you do not define the value,
the label has an implicit value of +0.7 . Although you can apply
a wide range of weights to a label, it is better to apply a high weight to
promote the refined results.
If you want to refine the search results to show only certain sites,
use a weight close or equal to If you want to use negative weights with filter labels, you might have
empty results. Filter labels restrict the search to a limited number of
sites, and a weight of |
Tagging Sites with Labels
You can tag sites with refinement labels. Each annotation can have multiple labels, which means that the same site can be used in other search engines and be ranked differently. The scores you apply to annotations to modulate the search engine labels also apply to the refinement labels.
XML Annotations
The following shows how you can tag sites with labels in XML format.
<Annotations> <Annotation about="webcast.berkeley.edu/*" score="1"> <Label name="university_boost_highest"/> <Label name="lectures"/> </Annotation> <Annotation about="www.youtube.com/ucberkeley/*" score="1"> <Label name="university_boost_highest"/> <Label name="videos_boost_mid"/> <Label name="lectures"/> </Annotation> </Annotations>
Other Ways to Help Your Users
Besides refining search results, you can use refinement links to help your users get more targeted results. You can append search terms to your users' queries or redirect your users to a different search engine or website.
Appending Search Queries
If you would like to help your users by adding helpful search terms to their
queries, you can use the Rewrite
element.
The element appends the search terms to your users'
queries when they click a refinement link. The Rewrite
element
can have up to 100 characters, all of which should be lowercase. Uppercase
search operators such as OR
are the only exceptions. To learn more
about search operators, see
Advanced Search
Made Easy.
The following example shows you how you can use Rewrite
.
<Facet> <FacetItem title="Homework"> <Label name="assignments" mode="BOOST"> <Rewrite>homework OR assignment OR assignments</Rewrite> </Label> </FacetItem> </Facet>
The example shows how to help users who click the refinement link called "Homework". It adds the words, "homework", "assignment", or "assignments" to the search queries that your users typed.
Controlling the Number of Displayed Refinement Labels
If you have defined refinements, Programmable Search Engine displays the refinement labels at the top of the search results. You have the option of showing either all of the refinement labels or just a subset of them.
If you choose to display only a subset of refinement labels, Programmable Search Engine displays the refinement labels with the largest number of search results. For example, if you have three refinement labels called "HTML," "CSS," and "JavaScript," but set your search engine to display only two, Programmable Search Engine displays the two refinement labels with the largest number of results for the specific user query.
This means that although the number of refinement labels that are displayed are fixed, the refinement labels themselves change according to the query of the user.
To set the number of refinement labels in the XML definition, add a
top_refinements
attribute to your context definition's
CustomSearchEngine
tag.
<CustomSearchEngine top_refinements="n"></CustomSearchEngine>
n
is the number of
refinements
you want to show.
Setting the number to 0
shows no refinement label with search
result. Without
the setting in context definition, your search engine displays all
refinement labels you have defined for any user query, regardless if any
search result for those labels.
You can also set the number of refinement labels on the Refinements page of the Control Panel.