com.google.appengine.api.search

## Class QueryOptions.Builder

- java.lang.Object
- - com.google.appengine.api.search.QueryOptions.Builder

- Enclosing class:
    QueryOptions

      public static final class QueryOptions.Builder
      extends java.lang.Object

  A builder which constructs QueryOptions objects.

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `QueryOptions.Builder` | `addExpressionToReturn(FieldExpression.Builder expressionBuilder)` Adds a `FieldExpression` build from the given `expressionBuilder` to return in search results.
    `QueryOptions.Builder` | `addExpressionToReturn(FieldExpression expression)` Adds a `FieldExpression` to return in search results.
    `QueryOptions` | `build()` Construct the final message.
    `QueryOptions.Builder` | `clearNumberFoundAccuracy()` Clears any accuracy requirement for `Results.getNumberFound()`.
    `QueryOptions.Builder` | `setCursor(Cursor.Builder cursorBuilder)` Sets a cursor built from the builder.
    `QueryOptions.Builder` | `setCursor(Cursor cursor)` Sets the cursor.
    `QueryOptions.Builder` | `setFieldsToReturn(java.lang.String... fields)` Specifies one or more fields to return in results.
    `QueryOptions.Builder` | `setFieldsToSnippet(java.lang.String... fieldsToSnippet)` Specifies one or more fields to snippet in results.
    `QueryOptions.Builder` | `setLimit(int limit)` Sets the limit on the number of documents to return in `Results`.
    `QueryOptions.Builder` | `setNumberFoundAccuracy(int numberFoundAccuracy)` Sets the accuracy requirement for `Results.getNumberFound()`.
    `QueryOptions.Builder` | `setOffset(int offset)` Sets the offset of the first result to return.
    `QueryOptions.Builder` | `setReturningIdsOnly(boolean idsOnly)` Sets whether or not the search should return documents or document IDs only.
    `QueryOptions.Builder` | `setSortOptions(SortOptions.Builder builder)` Sets a `SortOptions` using a builder.
    `QueryOptions.Builder` | `setSortOptions(SortOptions sortOptions)` Sets a `SortOptions` to sort documents with.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### setLimit

          public QueryOptions.Builder setLimit(int limit)

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

    - #### setCursor

          public QueryOptions.Builder setCursor(Cursor cursor)

      Sets the cursor. The cursor is obtained from either a `Results` or one of the individual `ScoredDocuments`. This is illustrated from the following code fragment:

           Cursor cursor = Cursor.newBuilder().build();

           SearchResults results = index.search(
               Query.newBuilder()
                   .setOptions(QueryOptions.newBuilder()
                       .setLimit(20)
                       .setCursor(cursor)
                       .build())
                   .build("some query"));

           // If the Cursor is built without setPerResult(true), then
           // by default a single Cursor is returned with the
           // Results.
           cursor = results.getCursor();

           for (ScoredDocument result : results) {
               // If you set Cursor.newBuilder().setPerResult(true)
               // then a cursor is returned with each result.
               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

    - #### setCursor

          public QueryOptions.Builder setCursor(Cursor.Builder cursorBuilder)

      Sets a cursor built from the builder.
      Parameters:
        `cursorBuilder` - a `Cursor.Builder` that is used to build a `Cursor`.
      Returns:
        this Builder
      See Also:
        `setCursor(Cursor)`

    - #### setOffset

          public QueryOptions.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 `SearchApiLimits.SEARCH_MAXIMUM_OFFSET`

    - #### setNumberFoundAccuracy

          public QueryOptions.Builder setNumberFoundAccuracy(int numberFoundAccuracy)

      Sets the accuracy requirement for `Results.getNumberFound()`. If set, `getNumberFound()` will be accurate up to at least that number. For example, when set to 100, any `getNumberFound() <= 100` is accurate. This option may add considerable latency / expense, especially when used with `setFieldsToReturn(String...)`.
      Parameters:
        `numberFoundAccuracy` - the minimum accuracy requirement
      Returns:
        this Builder
      Throws:
        `java.lang.IllegalArgumentException` - if the accuracy is not within acceptable range

    - #### clearNumberFoundAccuracy

          public QueryOptions.Builder clearNumberFoundAccuracy()

      Clears any accuracy requirement for `Results.getNumberFound()`.

    - #### setFieldsToReturn

          public QueryOptions.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 QueryOptions.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 `ScoredDocument.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 QueryOptions.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 `ScoredDocument.getExpressions()`.
      Parameters:
        `expressionBuilder` - a builder of named expressions to evaluate and return in results
      Returns:
        this Builder

    - #### setReturningIdsOnly

          public QueryOptions.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 QueryOptions.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

    - #### setSortOptions

          public QueryOptions.Builder setSortOptions(SortOptions sortOptions)

      Sets a `SortOptions` to sort documents with.
      Parameters:
        `sortOptions` - specifies how to sort the documents in `Results`
      Returns:
        this Builder

    - #### setSortOptions

          public QueryOptions.Builder setSortOptions(SortOptions.Builder builder)

      Sets a `SortOptions` using a builder.
      Parameters:
        `builder` - a builder of a `SortOptions`
      Returns:
        this Builder

    - #### build

          public QueryOptions build()

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