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.

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

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