Rewriting Queries

This page describes how to change or respond to your users' queries to deliver search results that are more relevant or that suit your site's requirements.

1. Overview
2. Appending Search Queries with Refinement Labels
3. Expanding Search Queries with Synonyms
4. Autocompleting Queries

Overview

If you know your audience well, you can roughly predict the kinds of things they might search for. You can anticipate their queries and help them find more relevant results.

Programmable Search Engine enables you append search terms to your users' queries and create synonyms of your users' queries. The first feature is implemented through refinements, which your users can apply or ignore; while the synonym features act on your users' queries without requiring any user action.

Appending Search Queries with Refinement Labels

To provide refinement links that add helpful search terms to user queries, use the Rewrite element in the Programmable Search XML annotations file. 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, except for uppercase search operators such as OR. To learn more about search operators, see Advanced Search Made Easy. To learn more about refinements, see Refining Searches.

The following example shows you how you can use Rewrite.

<CustomSearchEngine>
  <Title>Universities</Title>
  <Context>
    <Facet>
      <FacetItem title="Homework">
        <Label name="assignments" mode="BOOST">
          <Rewrite>homework OR assignment</Rewrite>
        </Label>
      </FacetItem>
    </Facet>
  </Context>
</CustomSearchEngine>

The example shows how to help users who click the refinement link called "Homework". It appends the additional search terms "homework" and "assignment" to the search query that your users type.

A refinements with the Rewrite element has the following structure:

• Facet
  • FacetItem
    • Label name
      • Rewrite

Back to top

Expanding Search Queries with Synonyms

You can expand your users' search queries by using synonyms, which are variants of a search term. For example, the finance-related search query, "interest", could have the following equivalent alternatives: "yield", "dividend", "coupon", and so on. If you create synonyms for "interest" in your financial search engine, your users will not need to type multiple variants to find information they are seeking. The Programmable Search Engine will automatically search for all sites that are relevant to "interest", "yield", "dividend", "coupon", and other related terms.

A search term with synonyms you defined automatically triggers a search expansion, whether or not the user enters the search term on its own or along with a series of other words. Let's say you've defined "ninja" as a search term with the synonym variant, "assassin". Any search query that includes the word "ninja"—such as just "ninja" alone or "ninja hotdog eating contest"—would expand the query to include the synonymous variants. It is as though the user had searched for "ninja OR assassin" or "ninja OR assassin hotdog eating contest".

Best Practices

Popular query terms, common acronyms (such as "CD" for "certificate of deposit"), and familiar abbreviations (such as "munis" for "municipal bonds") that are idiosyncratic to your specialized field or interest are great candidates for having synonyms. If your search engine is popular enough and receives many searches for the same queries, you can get data about your most popular queries from the statistics page. Go to the Control Panel and for your search engine, and click the statistics link. Popular queries are listed at the bottom of the page.

You don't need to create synonyms for popular query terms. For example, the terms "UK", "Britain", "United Kingdom", "United Kingdom of Great Britain" are fairly well-known variants (if not technically synonyms) to most web users. Google already has a large body of synonyms for such terms, and you don't need to replicate this work. Instead, create synonyms for common terms that are specific to the interests of the users of your search engine. For example, in a financial search engine, "bond" would be a great candidate. Google may not know if users are looking for "James Bond", "chemical bond", "adhesive bond", or "emotional bond". You, on the other hand, know that they are looking for a financial instrument and can easily come up with synonyms such as "fixed-income security" and "issue".

If you cannot discern whether a term is common or idiosyncratic, you can test the term and its variants on Google search. Type the query term (such as "san francisco") on Google search and then open a new browser window. In the Google search box, type the query term, the search operator OR, and the variant of the query term (for example, "san francisco OR sf"). Compare the two results pages. If they are exactly the same, then Google has the synonymous terms covered.

Creating Synonyms

As with any XML file, you can use a simple text editor to create and edit the synonyms file. Just save the text file with the file extension .xml (for example, syn_finance.xml).

Here is an example of a synonyms file:

<Synonyms>
  <Synonym term="stock">
    <Variant>equity</Variant>
    <Variant>share</Variant>
  </Synonym>
  <Synonym term="bond">
    <Variant>fixed-income security</Variant>
    <Variant>issue</Variant>
    <Variant>high yield debt</Variant>
  </Synonym>
</Synonyms>

A synonyms file has one element and one child element that can have multiple siblings, as described in the following hierarchy:

• Synonyms (1 only)
  • Synonym term (multiple siblings allowed)
    • Variant (up to 10 for each Synonym)

You create the search term in the attribute value of the Synonym child element and define each of its synonyms in the Variant element. The search term and its synonym variants could be a single word (such as "cookie") or phrases (such as "buttermilk cookie" or "crying over spilled milk").

Limits

The following table lists the limits for synonym files:

Back to top

Autocompleting Queries

Autocompletion is a list of suggested queries that appear as users type in the search box.

Figure 1: Typing just a few characters in the search box brings up a drop-down list that provides options for different search queries.

The list of optional queries used for autocompletion is derived partly from the contents of the website and the popularity of the query term. However, you can customize autocompletion by adding or removing terms from it, either in the control panel or through a bulk upload in an XML file.

Enabling Autocompletions

To enable autocompletion in search engines using the Programmable Search Element:

1. In the Search Features page of your search engine, scroll to the Autocomplete section.
2. Select the Enable autocomplete check box.

You can add or remove individual terms in the Autocomplete section of your search engine's Search Features page or upload all the terms using an XML. The terms that you add appear above the algorithmically generated terms for all queries.

It might take up to 48 hours before autocompletion terms start appearing in your search engine.

To add or remove terms in bulk, upload an autcompletion XML file. As with any XML file, you can use a simple text editor to create and edit the autcompletion file. Just save the text file with the file extension .xml (for example, autocompletion_finance.xml).

Adding and Removing Autocompletion Terms

Here is an example of a autocompletions file that you can upload.

<Autocompletions>
  <Autocompletion term="cake" type="1"/>
  <Autocompletion term="strawberry.*" type="2" match="2"/>
  <Autocompletion term="vanilla" type="2"/>
</Autocompletions>

In the sample code, "apple" is included in the list of possible autocompletion terms, whereas "vanilla" and any term starting with "strawberry" will never be presented to the user as an autocompletion term.

An autocompletion file has one element and one child element that can have multiple siblings, as described in the following hierarchy:

• Autocompletions (1 only)
  • Autocompletion (multiple siblings allowed)

The following table lists the autocompletion attribute names.

Back to top