# SearchRequest.Builder
Date: 2012-02-24

## com.google.appengine.api.search
Class SearchRequest.Builder

    java.lang.Object
      com.google.appengine.api.search.SearchRequest.Builder

Enclosing class:
  SearchRequest

    public static final class SearchRequest.Builder

extends java.lang.Object

A builder which constructs SearchRequest objects.

Method Summary
`SearchRequest.Builder` `addExpressionToReturn(FieldExpression.Builder expressionBuilder)` Adds a `FieldExpression` build from the given `expressionBuilder` to return in search results.
`SearchRequest.Builder` `addExpressionToReturn(FieldExpression expression)` Adds a `FieldExpression` to return in search results.
`SearchRequest.Builder` `addSortSpec(SortSpec.Builder sortSpecBuilder)` Adds a `SortSpec.Builder` to the list of sort specifications.
`SearchRequest.Builder` `addSortSpec(SortSpec sortSpec)` Adds a `SortSpec` to the list of sort specifications.
`SearchRequest` `build()` Construct the final message.
`SearchRequest.Builder` `setCursor(java.lang.String cursor)` Sets the cursor.
`SearchRequest.Builder` `setCursorType(SearchRequest.CursorType cursorType)` Sets the `SearchRequest.CursorType`.
`SearchRequest.Builder` `setFieldsToReturn(java.lang.String... fields)` Specifies one or more fields to return in results.
`SearchRequest.Builder` `setFieldsToSnippet(java.lang.String... fieldsToSnippet)` Specifies one or more fields to snippet in results.
`SearchRequest.Builder` `setLimit(int limit)` Sets the limit on the number of documents to return in the `SearchResponse`.
`SearchRequest.Builder` `setMatchedCountAccuracy(int matchedCountAccuracy)` Sets the accuracy requirement for `SearchResponse.getMatchedCount()`.
`SearchRequest.Builder` `setOffset(int offset)` Sets the offset of the first result to return.
`SearchRequest.Builder` `setQuery(java.lang.String query)` Sets the query.
`SearchRequest.Builder` `setReturningIdsOnly(boolean idsOnly)` Sets whether or not the search should return documents or document IDs only.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### setQuery

    public SearchRequest.Builder setQuery(java.lang.String query)

  Sets the query. A query can be as simple as a single term ("foo"), or as complex as a boolean expression, including field names ("title:hello OR body:important -october").

  Parameters:
    `query` - the query to apply to an index
  Returns:
    this builder
  Throws:
    `SearchQueryException` - if the query is invalid

### setLimit

    public SearchRequest.Builder setLimit(int limit)

  Sets the limit on the number of documents to return in the `SearchResponse`.

  Parameters:
    `limit` - the number of documents to return
  Returns:
    this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if numDocumentsToReturn is not within acceptable range

### setCursor

    public SearchRequest.Builder setCursor(java.lang.String cursor)

  Sets the cursor. The cursor is obtained from either a `SearchResponse` or one of the individual `SearchResults` as illustrated from the following code fragment:

       String cursor = ...

       SearchResponse response = index.search(
           SearchRequest.newBuilder()
               .setQuery("some query")
               .setLimit(20)
               .setCursor(cursor)
               .setCursorType(CursorType.RESPONSE_CURSOR)
               .build());

       // CursorType.RESPONSE_CURSOR is populated here
       cursor = response.getCursor();

       for (SearchResult result : response) {
           // CursorType.RESULT_CURSOR is populated here
           result.getCursor();

  Parameters:
    `cursor` - use a cursor returned from a previous set of search results as a starting point to retrieve the next set of results. This can get you better performance, and also improves the consistency of pagination through index updates
  Returns:
    this Builder

### setOffset

    public SearchRequest.Builder setOffset(int offset)

  Sets the offset of the first result to return.

  Parameters:
    `offset` - the offset into all search results to return the limit amount of results
  Returns:
    this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if the offset is negative or is larger than `SearchRequestChecker.MAXIMUM_OFFSET`

### setCursorType

    public SearchRequest.Builder setCursorType(SearchRequest.CursorType cursorType)

  Sets the `SearchRequest.CursorType`. The following two examples illustrate the difference between response and result cursors. The cursor string in these examples, was set in a previous round request-response. In the first example, we set the cursor type to `SearchRequest.CursorType.RESPONSE_CURSOR` and retrieve a cursor from the `SearchResponse` which will continue the search from the end of set of results in the response.

       SearchResponse response = index.search(
           SearchRequest.newBuilder()
               .setCursorType(CursorType.RESPONSE_CURSOR)
               .setCursor(cursor)
               .build());

       cursor = response.getCursor();

  In the following example using a `SearchRequest.CursorType.RESULT_CURSOR` will add a cursor to each `SearchResult` and search can be continued from any one of those results selected.

       SearchResponse response = index.search(
           SearchRequest.newBuilder()
               .setCursorType(CursorType.RESULT_CURSOR)
               .setCursor(cursor)
               .build());

       for (SearchResult result : response) {
           cursor = result.getCursor();

  Parameters:
    `cursorType` - the type of cursor the search results will have
  Returns:
    this Builder

### setMatchedCountAccuracy

    public SearchRequest.Builder setMatchedCountAccuracy(int matchedCountAccuracy)

  Sets the accuracy requirement for `SearchResponse.getMatchedCount()`. If set, `getMatchedCount()` will be accurate up to at least that number. For example, when set to 100, any `getMatchedCount()` <= 100 is accurate. This option may add considerable latency / expense, especially when used with `setFieldsToReturn(String...)`.

  Parameters:
    `matchedCountAccuracy` - the minimum accuracy requirement
  Returns:
    this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if the accuracy is not within acceptable range

### setFieldsToReturn

    public SearchRequest.Builder setFieldsToReturn(java.lang.String... fields)

  Specifies one or more fields to return in results.

  Parameters:
    `fields` - the names of fields to return in results
  Returns:
    this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if any of the field names is invalid

### setFieldsToSnippet

    public SearchRequest.Builder setFieldsToSnippet(java.lang.String... fieldsToSnippet)

  Specifies one or more fields to snippet in results. Snippets will be returned as fields with the same names in `SearchResult.getExpressions()`.

  Parameters:
    `fieldsToSnippet` - the names of fields to snippet in results
  Returns:
    this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if any of the field names is invalid

### addExpressionToReturn

    public SearchRequest.Builder addExpressionToReturn(FieldExpression.Builder expressionBuilder)

  Adds a `FieldExpression` build from the given `expressionBuilder` to return in search results. Snippets will be returned as fields with the same names in `SearchResult.getExpressions()`.

  Parameters:
    `expressionBuilder` - a builder of named expressions to evaluate and return in results
  Returns:
    this Builder

### setReturningIdsOnly

    public SearchRequest.Builder setReturningIdsOnly(boolean idsOnly)

  Sets whether or not the search should return documents or document IDs only. This setting is incompatible with `addExpressionToReturn(FieldExpression)` and with `setFieldsToReturn(String...)` methods.

  Parameters:
    `idsOnly` - whether or not only IDs of documents are returned by search request
  Returns:
    this Builder

### addExpressionToReturn

    public SearchRequest.Builder addExpressionToReturn(FieldExpression expression)

  Adds a `FieldExpression` to return in search results.

  Parameters:
    `expression` - a named expression to compute and return in results
  Returns:
    this Builder

### addSortSpec

    public SearchRequest.Builder addSortSpec(SortSpec sortSpec)

  Adds a `SortSpec` to the list of sort specifications.

  Parameters:
    `sortSpec` - a specification of a field to sort
  Returns:
    this Builder

### addSortSpec

    public SearchRequest.Builder addSortSpec(SortSpec.Builder sortSpecBuilder)

  Adds a `SortSpec.Builder` to the list of sort specifications.

  Parameters:
    `sortSpecBuilder` - a SortSpec.Builder to add
  Returns:
    this Builder

### build

    public SearchRequest build()

  Construct the final message.

  Returns:
    the SearchRequest built from the parameters entered on this Builder
  Throws:
    `java.lang.IllegalArgumentException` - if the search request is invalid