SearchSpec.Builder

public static final class SearchSpec.Builder
extends Object

java.lang.Object
   ↳ androidx.appsearch.app.SearchSpec.Builder


Builder for objects.

Summary

Public constructors

Builder()

Creates a new SearchSpec.Builder.

Public methods

SearchSpec.Builder addFilterDocumentClasses(Class...<?> documentClasses)

Adds the Schema names of given document classes to the Schema type filter of SearchSpec Entry.

SearchSpec.Builder addFilterDocumentClasses(Collection<? extends Class<?>> documentClasses)

Adds the Schema names of given document classes to the Schema type filter of SearchSpec Entry.

SearchSpec.Builder addFilterNamespaces(String... namespaces)

Adds a namespace filter to SearchSpec Entry.

SearchSpec.Builder addFilterNamespaces(Collection<String> namespaces)

Adds a namespace filter to SearchSpec Entry.

SearchSpec.Builder addFilterPackageNames(String... packageNames)

Adds a package name filter to SearchSpec Entry.

SearchSpec.Builder addFilterPackageNames(Collection<String> packageNames)

Adds a package name filter to SearchSpec Entry.

SearchSpec.Builder addFilterSchemas(Collection<String> schemas)

Adds a Schema type filter to SearchSpec Entry.

SearchSpec.Builder addFilterSchemas(String... schemas)

Adds a Schema type filter to SearchSpec Entry.

SearchSpec.Builder addProjection(String schema, Collection<String> propertyPaths)

Adds property paths for the specified type to be used for projection.

SearchSpec build()

Constructs a new SearchSpec from the contents of this builder.

SearchSpec.Builder setMaxSnippetSize(int maxSnippetSize)

Sets maxSnippetSize, the maximum snippet size.

SearchSpec.Builder setOrder(int order)

Indicates the order of returned search results, the default is SearchSpec.ORDER_DESCENDING, meaning that results with higher scores come first.

SearchSpec.Builder setRankingStrategy(int rankingStrategy)

Sets ranking strategy for AppSearch results.

SearchSpec.Builder setResultCountPerPage(int numPerPage)

Sets the number of results per page in the returned object.

SearchSpec.Builder setResultGrouping(int groupingTypeFlags, int limit)

Set the maximum number of results to return for each group, where groups are defined by grouping type.

SearchSpec.Builder setSnippetCount(int snippetCount)

Only the first snippetCount documents based on the ranking strategy will have snippet information provided.

SearchSpec.Builder setSnippetCountPerProperty(int snippetCountPerProperty)

Sets snippetCountPerProperty.

SearchSpec.Builder setTermMatch(int termMatchTypeCode)

Indicates how the query terms should match TermMatchCode in the index.

Inherited methods

Public constructors

Builder

public Builder ()

Creates a new SearchSpec.Builder.

Public methods

addFilterDocumentClasses

public SearchSpec.Builder addFilterDocumentClasses (Class...<?> documentClasses)

Adds the Schema names of given document classes to the Schema type filter of SearchSpec Entry. Only search for documents that have the specified schema types.

If unset, the query will search over all schema types.

Parameters
documentClasses Class: classes annotated with Document.

Returns
SearchSpec.Builder

Throws
AppSearchException

addFilterDocumentClasses

public SearchSpec.Builder addFilterDocumentClasses (Collection<? extends Class<?>> documentClasses)

Adds the Schema names of given document classes to the Schema type filter of SearchSpec Entry. Only search for documents that have the specified schema types.

If unset, the query will search over all schema types.

Parameters
documentClasses Collection: classes annotated with Document.

Returns
SearchSpec.Builder

Throws
AppSearchException

addFilterNamespaces

public SearchSpec.Builder addFilterNamespaces (String... namespaces)

Adds a namespace filter to SearchSpec Entry. Only search for documents that have the specified namespaces.

If unset, the query will search over all namespaces.

Parameters
namespaces String

Returns
SearchSpec.Builder

addFilterNamespaces

public SearchSpec.Builder addFilterNamespaces (Collection<String> namespaces)

Adds a namespace filter to SearchSpec Entry. Only search for documents that have the specified namespaces.

If unset, the query will search over all namespaces.

Parameters
namespaces Collection

Returns
SearchSpec.Builder

addFilterPackageNames

public SearchSpec.Builder addFilterPackageNames (String... packageNames)

Adds a package name filter to SearchSpec Entry. Only search for documents that were indexed from the specified packages.

If unset, the query will search over all packages that the caller has access to. If package names are specified which caller doesn't have access to, then those package names will be ignored.

Parameters
packageNames String

Returns
SearchSpec.Builder

addFilterPackageNames

public SearchSpec.Builder addFilterPackageNames (Collection<String> packageNames)

Adds a package name filter to SearchSpec Entry. Only search for documents that were indexed from the specified packages.

If unset, the query will search over all packages that the caller has access to. If package names are specified which caller doesn't have access to, then those package names will be ignored.

Parameters
packageNames Collection

Returns
SearchSpec.Builder

addFilterSchemas

public SearchSpec.Builder addFilterSchemas (Collection<String> schemas)

Adds a Schema type filter to SearchSpec Entry. Only search for documents that have the specified schema types.

If unset, the query will search over all schema types.

Parameters
schemas Collection

Returns
SearchSpec.Builder

addFilterSchemas

public SearchSpec.Builder addFilterSchemas (String... schemas)

Adds a Schema type filter to SearchSpec Entry. Only search for documents that have the specified schema types.

If unset, the query will search over all schema types.

Parameters
schemas String

Returns
SearchSpec.Builder

addProjection

public SearchSpec.Builder addProjection (String schema, 
                Collection<String> propertyPaths)

Adds property paths for the specified type to be used for projection. If property paths are added for a type, then only the properties referred to will be retrieved for results of that type. If a property path that is specified isn't present in a result, it will be ignored for that result. Property paths cannot be null.

If no property paths are added for a particular type, then all properties of results of that type will be retrieved.

If property path is added for the SearchSpec.PROJECTION_SCHEMA_TYPE_WILDCARD, then those property paths will apply to all results, excepting any types that have their own, specific property paths set.

Suppose the following document is in the index.

Email: Document {
   sender: Document {
     name: "Mr. Person"
     email: "mrperson123@google.com"
   }
   recipients: [
     Document {
       name: "John Doe"
       email: "johndoe123@google.com"
     }
     Document {
       name: "Jane Doe"
       email: "janedoe123@google.com"
     }
   ]
   subject: "IMPORTANT"
   body: "Limited time offer!"
 }
 

Then, suppose that a query for "important" is issued with the following projection type property paths:

{schema: "Email", ["subject", "sender.name", "recipients.name"]}
 

The above document will be returned as:

Email: Document {
   sender: Document {
     name: "Mr. Body"
   }
   recipients: [
     Document {
       name: "John Doe"
     }
     Document {
       name: "Jane Doe"
     }
   ]
   subject: "IMPORTANT"
 }
 

Parameters
schema String

propertyPaths Collection

Returns
SearchSpec.Builder

build

public SearchSpec build ()

Constructs a new SearchSpec from the contents of this builder.

After calling this method, the builder must no longer be used.

Returns
SearchSpec

setMaxSnippetSize

public SearchSpec.Builder setMaxSnippetSize (int maxSnippetSize)

Sets maxSnippetSize, the maximum snippet size. Snippet windows start at maxSnippetSize/2 bytes before the middle of the matching token and end at maxSnippetSize/2 bytes after the middle of the matching token. It respects token boundaries, therefore the returned window may be smaller than requested.

Setting maxSnippetSize to 0 will disable windowing and an empty string will be returned. If matches enabled is also set to false, then snippeting is disabled.

Ex. maxSnippetSize = 16. "foo bar baz bat rat" with a query of "baz" will return a window of "bar baz bat" which is only 11 bytes long.

Parameters
maxSnippetSize int

Value is 10000 or less.

Returns
SearchSpec.Builder

setOrder

public SearchSpec.Builder setOrder (int order)

Indicates the order of returned search results, the default is SearchSpec.ORDER_DESCENDING, meaning that results with higher scores come first.

This order field will be ignored if RankingStrategy = RANKING_STRATEGY_NONE.

Parameters
order int

Returns
SearchSpec.Builder

setRankingStrategy

public SearchSpec.Builder setRankingStrategy (int rankingStrategy)

Sets ranking strategy for AppSearch results.

Parameters
rankingStrategy int

Returns
SearchSpec.Builder

setResultCountPerPage

public SearchSpec.Builder setResultCountPerPage (int numPerPage)

Sets the number of results per page in the returned object.

The default number of results per page is 10.

Parameters
numPerPage int

Value is 10000 or less.

Returns
SearchSpec.Builder

setResultGrouping

public SearchSpec.Builder setResultGrouping (int groupingTypeFlags, 
                int limit)

Set the maximum number of results to return for each group, where groups are defined by grouping type.

Calling this method will override any previous calls. So calling setResultGrouping(GROUPING_TYPE_PER_PACKAGE, 7) and then calling setResultGrouping(GROUPING_TYPE_PER_PACKAGE, 2) will result in only the latter, a limit of two results per package, being applied. Or calling setResultGrouping (GROUPING_TYPE_PER_PACKAGE, 1) and then calling setResultGrouping (GROUPING_TYPE_PER_PACKAGE | GROUPING_PER_NAMESPACE, 5) will result in five results per package per namespace.

Parameters
groupingTypeFlags int: One or more combination of grouping types.

limit int: Number of results to return per groupingTypeFlags.

Returns
SearchSpec.Builder

Throws
IllegalArgumentException if groupingTypeFlags is zero.

setSnippetCount

public SearchSpec.Builder setSnippetCount (int snippetCount)

Only the first snippetCount documents based on the ranking strategy will have snippet information provided.

If set to 0 (default), snippeting is disabled and SearchResult.getMatches() will return null for that result.

Parameters
snippetCount int

Value is 10000 or less.

Returns
SearchSpec.Builder

setSnippetCountPerProperty

public SearchSpec.Builder setSnippetCountPerProperty (int snippetCountPerProperty)

Sets snippetCountPerProperty. Only the first snippetCountPerProperty snippets for each property of GenericDocument will contain snippet information.

If set to 0, snippeting is disabled and SearchResult.getMatches() will return null for that result.

Parameters
snippetCountPerProperty int

Value is 10000 or less.

Returns
SearchSpec.Builder

setTermMatch

public SearchSpec.Builder setTermMatch (int termMatchTypeCode)

Indicates how the query terms should match TermMatchCode in the index.

If this method is not called, the default term match type is SearchSpec.TERM_MATCH_PREFIX.

Parameters
termMatchTypeCode int

Returns
SearchSpec.Builder