| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Search Requests
You submit search requests to your domain's search endpoint via HTTP GET. To construct a search request, you append the Amazon CloudSearch API version and the name of the resource you are accessing, 2011-02-01/search, and a query string that specifies the terms and constraints for your search and what you want to get back in the response. The maximum size of a search request is 8190 bytes, including the HTTP method, URI, and protocol version.
For example, the following request performs a simple text search of the search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com domain and gets the contents of the title field:
http://search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch. amazonaws.com/2011-02-01/search?q=star+wars&return-fields=title
Note
The API version must be specified in all search requests. When there are updates to the Amazon CloudSearch Search API, you access them using a new API version.
The query string in a search request must be URL-encoded. You can use any method you want to send GET requests to your domain's search endpoint—you can enter the request URL directly in a Web browser, use cURL to submit the request, or generate an HTTP call using your favorite HTTP library.
By default, Amazon CloudSearch returns the response in JSON. You can also get the results formatted in XML by specifying the results-type parameter, results-type=xml.
Note
You can also use the Search Tester in the Amazon CloudSearch console to search your data, browse the results, and view the generated request URLs and JSON and XML responses. For more information, see Searching with the Search Tester.
Amazon CloudSearch can return up to 2 KB of data from a text field—if the contents of the field exceed 2 KB, only the first 2 KB is included in the results. (All of the data is searchable, only the result data is truncated.)
Search Syntax
GET /2011-02-01/search
Search Request Headers
| Name | Description | Required |
|---|---|---|
| Cache-Control | Forces revalidation of results when a cached result document would otherwise be returned. | No |
| HOST | The search request endpoint for the domain you're querying. You can use DescribeDomains to retrieve your domain's search request endpoint. | Yes |
Search Request Parameters
| Name | Description | Required |
|---|---|---|
bq | One or more match expressions that define a Boolean search. Multiple expressions are joined with a top-level Within a match expression, you can use the Condition: Required if the Type: String | Conditional |
facet | A comma-separated list of the fields for which you want to compute facets. The specified fields must be numeric fields or defined as facet enabled in the domain configuration. By default, counts are computed for all field values. If you want to specify the field values that you want counted for a particular field, use the You can specify the maximum number of constraints to include in the results with the Type: String | No |
facet- | The field values (facet constraints) that you want to count for a particular field. FIELD is the name of the field. Constraints are specified as a comma-separated list of ranges or single-quoted strings. For example, facet-year-constraints=2000..2011 calculates facet counts for the years 2000 through 2011, inclusive. You can omit the lower end of a range to count all of the values less than or equal to the specified value. Similarly, you can omit the upper end of a range to count all of the values greater than or equal to the specified value. To specify constraints for a text field, enclose the values in single quotes. For example, facet-color-constraints='red','blue','green'.
If you don't specify facet constraints, counts are computed for all field values.
Type: String | No |
facet- | How you want to sort facet values for a particular field. FIELD is the name of the field. There are four sorting options:
Type: String | No |
facet- | Set the maximum number of facet constraints to be included for the specified field in the search results. By default, the results include counts for the top 40 constraints.
Type: Integer | No |
q | The string to search for. You use the If you separate search terms with plus (+) or a space, Amazon CloudSearch matches documents that contain all of the specified search terms—they are ANDed together. For example, You can use the Condition: Required if the Type: String | Conditional |
rank | A comma-separated list of fields or rank expressions to use for ranking. A maximum of 10 fields and rank expressions can be specified. You can use any uint field to rank results numerically. Any result-enabled text or literal field can be used to rank results alphabetically. To rank results by relevance, you can specify the name of a custom rank expression or text_relevance. Hits are ordered according to the specified rank field(s). By default, hits are ranked in ascending order. You can prefix a field name with a minus (-) to rank in descending order. If no rank parameter is specified, it defaults to rank=-text_relevance, which lists results according to their text_relevance scores with the highest-scoring documents first.
Type: String | No |
rank- | Define a rank expression that can be used with the rank parameter. You can also specify the new rank expression as a return field and use it to set thresholds for the search results with the t- parameter. For more information about constructing rank expressions, see Customizing Result Ranking with Amazon CloudSearch.
Specifying a rank expression as part of the search request enables you to quickly test and tune new rank expressions. Once you have finished tuning your rank expression, you should configure it for use in all requests with the You can define and use multiple rank expressions in a search request. For example, the following request creates two rank expressions that are used to rank the results and returns one of them in the search results: search?q=terminator &rank-expression1=sin(text_relevance) &rank-expression2=cos(text_relevance) &rank=expression1,expression2 &return-fields=title,text_relevance,expression2 Type: String | No |
results-type | Controls the content type of the response, json or xml. The default is json.
Type: String | No |
return-fields | The document fields to include in the response. Up to 2 KB of data can be returned from a text field. If the field contents exceed 2 KB, only the first 2 KB is included in the results.
Specified as a comma-separated list of field names. If no return-fields are specified, only the document ids of the hits are returned.
Type: String | No |
size | The maximum number of search hits to return. The default is 10.
Type: Positive Integer | No |
start | The offset of the first search hit you want to return. The default is 0 (the first hit).
Type: Positive Integer | No |
t- | Restrict the match set used in subsequent post-processing steps according to the specified rank expression. Only hits that have a score within the specified RANGE are included. Ranges are specified as described in Expression Syntax for Boolean Queries.
Type: RANGE | No |
Expression Syntax for Boolean Queries
| Expression Syntax | Description |
|---|---|
| Search for a string in the specified text or literal field. For example, bq=title:'star'. Any single quotation marks or backslashes in the string must be escaped with a backslash. |
| Search for a string in the specified text or literal field. For example, (field title 'star'). Any single quotation marks or backslashes in the string must be escaped with a backslash. You can use this alternate fielded search syntax when you're specifying multiple fielded search expressions as part of Boolean expression. For example, bq=(and (field title 'star') (filter year ..2000)). |
| Search for an integer value in the specified uint field. For example, bq=year:2000. Matches documents that have at least one value in the field that equals the specifed value. You can specify a single value or a range of values. A pair of nonnegative integers separated by two dots matches documents that have at least one attribute in the field that falls in the specified range. You can omit one value to specify an open-ended upper or lower limit. The range is inclusive on both ends. For example, bq=year:1998..2000. |
|
| Search for an integer in the specified uint field. For example, (filter year 2000). Matches documents that have at least one value in the field that equals the specifed value. You can use this alternate fielded search syntax when you're specifying multiple fielded search expressions as part of Boolean expression. For example, bq=(and (field title 'star') (filter year ..2000)). You can specify a single value or a range of values. A pair of nonnegative integers separated by two dots matches documents that have at least one attribute in the field that falls in the specified range. You can omit one value to specify an open-ended upper or lower limit. The range is inclusive on both ends. For example, (filter year 1998..2000). |
| Include hits only if they match all of the specified expressions. (Boolean AND operator.) For example, bq=(and (field title 'star') (field actor 'Ford, Harrison') (filter year ..2000)). |
| Exclude hits that match the specified expression. (Boolean NOT operator.) For example, bq=(not (and (field actor 'Guinness, Alec') (field actor 'Ford, Harrison'))). |
| Include hits that match any of the specified expressions. (Boolean OR operator.) For example, bq=(or (field actor 'Guinness, Alec') (field actor 'Ford, Harrison') (field actor 'Jones, James Earl')). |
