Using Facet Information in Amazon CloudSearch

You can display facet information to enable users to more easily browse search results and zero in on the information they are interested in. For example, if a user is trying to find one of the Star Trek movies, but can't remember the full title, he might start by searching for "star". If you want to display top facets for actor and genre, you would specify those facets in the query, along with the number of facet values you want to retrieve for each facet:

search?q=star&facet=actor,genre&facet-actor-top-n=10&facet-genre-top-n=5&size=5&results-type=xml

This gives you the following information in the search response:

<results xmlns="http://cloudsearch.amazonaws.com/
    2011-02-01/results">
    <rank>-text_relevance</rank>
    <match-expr>(label 'star')</match-expr>
    <hits found="26" start="0">
        <hit id="tt1408101"/>
        <hit id="tt0069945"/>
        <hit id="tt1185834"/>
        <hit id="tt0092007"/>
        <hit id="tt0098382"/>
    </hits>
    <facets>
        <facet name="actor"/>
        <facet name="genre">
            <constraint value="Sci-Fi" count="20"/>
            <constraint value="Action" count="18"/>
            <constraint value="Adventure" count="17"/>
            <constraint value="Thriller" count="10"/>
            <constraint value="Fantasy" count="5"/>
        </facet>
    </facets>
    <info rid="3c5a461d28b76874a756e4d419a38646955da47864afeeef172add882f
     712bb0b7c9e486627e07e2" time-ms="3" cpu-time-ms="0"/>
</results>

Using the document ids, you can retrieve the data you want to display for each hit from a separate system. By displaying the facet information, you can provide a way for the user to zero on in the movie he's looking for. For example, he might click "William Shatner" in the list of actors to see the subset of movies that William Shatner appeared in. To retrieve the subset, you can use the bq search parameter to perform a fielded search against the actor field and find the matches that contain star in any text field and William Shatner in the actor field.

search?bq=(and 'star' actor:'William Shatner')&facet=actor,genre
&facet-actor-top-n=10&facet-genre-top-n=5&size=5
&results-type=xml

This retrieves the subset of hits along with the actor and genre facet information:

<results>
  <rank>-text_relevance</rank>
  <match-expr>(and 'star' actor:'William Shatner')</match-expr>
  <hits found="6" start="0">
    <hit id="tt0092007"/>
    <hit id="tt0098382"/>
    <hit id="tt0088170"/>
    <hit id="tt0079945"/>
    <hit id="tt0084726"/>
  </hits>
  <facets>
    <facet name="actor">
      <constraint value="Doohan, James" count="6"/>
      <constraint value="Kelley, DeForest" count="6"/>
      <constraint value="Koenig, Walter" count="6"/>
      <constraint value="Nichols, Nichelle" count="6"/>
      <constraint value="Nimoy, Leonard" count="6"/>
      <constraint value="Shatner, William" count="6"/>
      <constraint value="Takei, George" count="6"/>
      <constraint value="Butrick, Merritt" count="2"/>
      <constraint value="Lenard, Mark" count="2"/>
      <constraint value="Adamson, Joseph" count="1"/>
    </facet>
    <facet name="genre">
      <constraint value="Sci-Fi" count="6"/>
      <constraint value="Action" count="5"/>
      <constraint value="Adventure" count="5"/>
      <constraint value="Thriller" count="4"/>
      <constraint value="Mystery" count="2"/>
    </facet>
  </facets>
  <info rid="ccd66a5219f938d2d27598352059d8c34094e7b0695b7c51dc91631555cb382dc17ef8064dbc9fdd" 
        time-ms="3" cpu-time-ms="0"/>
</results>

At this point, the user might remember that the movie he's trying to find also had Joseph Adamson in it and click on Joseph Adamson in the actor list. Again, you would use his selection to further refine the query:

search?bq=(and 'star' actor:'William Shatner' actor:'Adamson, Joseph')
&return-fields=title&facet=actor,genre&facet-actor-top-n=10
&facet-genre-top-n=5&size=5&results-type=xml

Now, there's just a single match that you can display to the user Star Trek IV: The Voyage Home:

<results>
  <rank>-text_relevance</rank>
  <match-expr>(and 'star' actor:'William Shatner' actor:'Adamson, Joseph')</match-expr>
  <hits found="1" start="0">
    <hit id="tt0092007">
      <d name="title">Star Trek IV: The Voyage Home</d>
    </hit>
  </hits>
  <facets>
    ...
  </facets>
</results>