com.google.appengine.api.search
Class QueryOptions.Builder

java.lang.Object
  extended by 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
 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 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 QueryOptionsChecker.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

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