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


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.

Custom Search enables you append search terms to your users' queries, redirect users to another website or search engine, and create synonyms of your users' queries. The first two features are 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 Custom 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.

      <FacetItem title="Homework">
        <Label name="assignments" mode="BOOST">
          <Rewrite>homework OR assignment</Rewrite>

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 (up to four)
      • 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 custom 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

Unlike other Custom Search features, you create the XML for synonyms not in the context file nor the annotations file, but in its own file. 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, cse_syn_finance.xml).

Here is an example of a synonyms file:

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

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").

If you are programmatically uploading synonyms using HTTP methods, you have to use additional elements that tell the Custom Search API what to do with the synonyms, such as whether they should be added or removed. For more information, see Programmatically Creating Custom Search Engines.


The following table lists the limits for synonym files:

Item Maximum allowed
Number of search terms (Synonym term element) Multiple search terms, so long as the total number of variants do not exceed 500 for each search engine.
Number of variants (Variant elements) for each search term 10


Total number of variants (Variant elements) for the search engine 500
File size 500KB
Number of files As many as you need, so long as the aggregate size of all files in the account does not exceed 4MB

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 Custom Search Element:

  1. In the Control Panel, click the Autocompletions section.
  2. Select the Enable autocompletions check box.
  3. Click Save Changes.
  4. Click the Get code tab and copy the generated code snippet, and insert it your webpage.

You can add or remove individual terms in the Autocompletions section of the Control Panel 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 12 hours before autocompletion terms start appearing in your search engine.

To add or remove terms in bulk, upload an autcompletions XML file. 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, cse_autocompletion_finance.xml).

Adding and Removing Autocompletion Terms

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

  <Autocompletion term="cake" type="1" language=""/>
  <Autocompletion term="strawberry.*" type="2" match="2" language=""/>
  <Autocompletion term="vanilla" type="2" language=""/>
  <Autocompletion term="apple" type="3" language="">
    <Promotion id="1" queries="dessert" title="Apple pie for dessert!" url=""
        start_date="" end_date="" image_url=""  description="Apple pie is the best dessert ever!"/>
    <Promotion id="2" queries="apple" title="Buy Apple pie" url=""
        start_date="" end_date="" image_url="" description="We stock the best apple pie in the world, right here."/>

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. In addition, a promotion for the URL will appear whenever users search for "apple".

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)
      • Promotion

The following table lists the autocompletion attribute names.

Attribute name Description Value
term The individual term or regular expression to include or exclude. Autocompletion term to include or exclude. For example, if you want to add "storm shadow" to the list of autocompletion terms presented to your users, add "storm shadow" as the value. Note that using the same term in multiple Autocompletion entries will result in an error. A term can consist of up to 100 characters. Terms with more than 100 characters will be ignored.
type Specify whether the term should be included or excluded from the autocompletion. Specify either:
  • 1 - include a term
  • 2 - exclude a term
  • 3 - add a promotion in autocomplete.
  • match Optional. Specify whether you want the term to be matched exactly or with regular expression. Specify either:
  • 1 - Default. Exact match.
  • 2 - for Regular expression. Only excluded terms can have use regular expression.
  • language Optional. Specify the language of the autocompletion. Leave this undefined, because, by default, Custom Search uses the language you have defined on the Basics section of the Control Panel.

    To enable promotions in autocomplete, add the Promotion element.

    The following table lists the Promotion attribute names. More information about promotions.

    Attribute name Description
    id A unique string identifier of the promotion to display in autocomplete.
    queries A set of comma-separated user queries, any of which will trigger the promotion. For example, if queries are specified as apple,orange, then a promotion will be triggered when the user types any of the following:
    • a
    • ap
    • apple
    • o
    • ora
    title The title of the promotion.
    start_date Optional. The date on which the promotion should first appear.
    end_date Optional. The last date on which the promotion should appear.
    image_url Optional. A URL pointing to the image to be displayed in the promotion.
    description Optional. A text description of the promotion.

    Back to top

    Send feedback about...

    Custom Search