SearchSpec.Builder | Android Developers [proxy]

The Wayback Machine - https://web.archive.org/web/20230208220441/https://developer.android.com/reference/android/app/appsearch/SearchSpec.Builder

Summary: Ctors | Methods | Inherited Methods

public static final class SearchSpec.Builder
extends Object

Builder for objects.

Summary

Public constructors
`Builder()`

Public methods
`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.Builder`	`addProjectionPaths(String schema, Collection<PropertyPath> 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`	`setJoinSpec(JoinSpec joinSpec)` Specifies which documents to join with, and how to join.
`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`	`setPropertyWeightPaths(String schemaType, Map<PropertyPath, Double> propertyPathWeights)` Sets property weights by schema type and property path.
`SearchSpec.Builder`	`setPropertyWeights(String schemaType, Map<String, Double> propertyPathWeights)` Sets property weights by schema type and property path.
`SearchSpec.Builder`	`setRankingStrategy(String advancedRankingExpression)` Enables advanced ranking to score based on `advancedRankingExpression`.
`SearchSpec.Builder`	`setRankingStrategy(int rankingStrategy)` Sets ranking strategy for AppSearch results.
`SearchSpec.Builder`	`setResultCountPerPage(int resultCountPerPage)` Sets the number of results per page in the returned object.
`SearchSpec.Builder`	`setResultGrouping(int groupingTypeFlags, int limit)` Sets 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 termMatchType)` Indicates how the query terms should match `TermMatchCode` in the index.

Inherited methods

From class java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

public Builder ()

Public methods

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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.

Parameters
`schema`	`String`: a string corresponding to the schema to add projections to. This value cannot be `null`.
`propertyPaths`	`Collection`: the projections to add. This value cannot be `null`.

Returns
`SearchSpec.Builder`

addProjectionPaths

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

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`: a string corresponding to the schema to add projections to. This value cannot be `null`.
`propertyPaths`	`Collection`: the projections to add. This value cannot be `null`.

Returns
`SearchSpec.Builder`

build

public SearchSpec build ()

Constructs a new SearchSpec from the contents of this builder.

Returns
`SearchSpec`	This value cannot be `null`.

Throws
`IllegalArgumentException`	if property weights are provided with a ranking strategy that isn't RANKING_STRATEGY_RELEVANCE_SCORE.
`IllegalStateException`	if the ranking strategy is `SearchSpec.RANKING_STRATEGY_JOIN_AGGREGATE_SCORE` and `setJoinSpec(JoinSpec)` has never been called.

setJoinSpec

public SearchSpec.Builder setJoinSpec (JoinSpec joinSpec)

Specifies which documents to join with, and how to join.

If the ranking strategy is SearchSpec.RANKING_STRATEGY_JOIN_AGGREGATE_SCORE, and the JoinSpec is null, build() will throw an AppSearchException.

Parameters
`joinSpec`	`JoinSpec`: a specification on how to perform the Join operation. This value cannot be `null`.

Returns
`SearchSpec.Builder`

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 between 0 and MAX_SNIPPET_SIZE_LIMIT inclusive

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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`: Value is `SearchSpec.ORDER_DESCENDING`, or `SearchSpec.ORDER_ASCENDING`

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setPropertyWeightPaths

public SearchSpec.Builder setPropertyWeightPaths (String schemaType, 
                Map<PropertyPath, Double> propertyPathWeights)

Sets property weights by schema type and property path.

Property weights are used to promote and demote query term matches within a GenericDocument property when applying scoring.

Property weights must be positive values (greater than 0). A property's weight is multiplied with that property's scoring contribution. This means weights set between 0.0 and 1.0 demote scoring contributions by a term match within the property. Weights set above 1.0 promote scoring contributions by a term match within the property.

Properties that exist in the AppSearchSchema, but do not have a weight explicitly set will be given a default weight of 1.0.

Weights set for property paths that do not exist in the AppSearchSchema will be discarded and not affect scoring.

NOTE: Property weights only affect scoring for query-dependent scoring strategies, such as SearchSpec.RANKING_STRATEGY_RELEVANCE_SCORE.

Parameters
`schemaType`	`String`: the schema type to set property weights for. This value cannot be `null`.
`propertyPathWeights`	`Map`: a `Map` of property paths of the schema type to the weight to set for that property. This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

Throws
`IllegalArgumentException`	if a weight is equal to or less than 0.0.

setPropertyWeights

public SearchSpec.Builder setPropertyWeights (String schemaType, 
                Map<String, Double> propertyPathWeights)

Sets property weights by schema type and property path.

Property weights are used to promote and demote query term matches within a GenericDocument property when applying scoring.

Properties that exist in the AppSearchSchema, but do not have a weight explicitly set will be given a default weight of 1.0.

Weights set for property paths that do not exist in the AppSearchSchema will be discarded and not affect scoring.

NOTE: Property weights only affect scoring for query-dependent scoring strategies, such as SearchSpec.RANKING_STRATEGY_RELEVANCE_SCORE.

Parameters
`schemaType`	`String`: the schema type to set property weights for. This value cannot be `null`.
`propertyPathWeights`	`Map`: a `Map` of property paths of the schema type to the weight to set for that property. This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

Throws
`IllegalArgumentException`	if a weight is equal to or less than 0.0.

setRankingStrategy

public SearchSpec.Builder setRankingStrategy (String advancedRankingExpression)

Enables advanced ranking to score based on advancedRankingExpression.

This method will set RankingStrategy to SearchSpec.RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION.

The ranking expression is a mathematical expression that will be evaluated to a floating-point number of double type representing the score of each document.

Numeric literals, arithmetic operators, mathematical functions, and document-based functions are supported to build expressions.

The following are examples of numeric literals:

Integer
Example: 0, 1, 2, 13
Floating-point number
Example: 0.333, 0.5, 123.456
Negative number
Example: -5, -10.5, -100.123

The following are supported arithmetic operators:

Addition(+)
Example: "1 + 1" will be evaluated to 2.
Subtraction(-)
Example: "2 - 1.5" will be evaluated to 0.5.
Multiplication(*)
Example: "2 * -2" will be evaluated to -4.
Division(/)
Example: "5 / 2" will be evaluated to 2.5.

Multiplication and division have higher precedences than addition and subtraction, but multiplication has the same precedence as division, and addition has the same precedence as subtraction. Parentheses are supported to change precedences.

For example:

"2 + 3 - 4 * 5" will be evaluated to -15
"(2 + 3) - (4 * 5)" will be evaluated to -15
"2 + (3 - 4) * 5" will be evaluated to -3

The following are supported mathematical functions:

log(x) - the natural log of x
log(x, y) - the log of y with base x
pow(x, y) - x to the power of y
max(v1, v2, ..., vn) with n > 0 - the maximum value among v1, ..., vn
min(v1, v2, ..., vn) with n > 0 - the minimum value among v1, ..., vn
sqrt(x) - the square root of x
abs(x) - the absolute value of x
sin(x), cos(x), tan(x) - trigonometric functions of x
Example: "max(abs(-100), 10) + pow(2, 10)" will be evaluated to 1124

Document-based functions must be called via "this", which represents the current document being scored. The following are supported document-based functions:

this.documentScore()
Get the app-provided document score of the current document. This is the same score that is returned for SearchSpec.RANKING_STRATEGY_DOCUMENT_SCORE.
this.creationTimestamp()
Get the creation timestamp of the current document. This is the same score that is returned for SearchSpec.RANKING_STRATEGY_CREATION_TIMESTAMP.
this.relevanceScore()
Get the BM25F relevance score of the current document in relation to the query string. This is the same score that is returned for SearchSpec.RANKING_STRATEGY_RELEVANCE_SCORE.
this.usageCount(type) and this.usageLastUsedTimestamp(type)
Get the number of usages or the timestamp of last usage by type for the current document, where type must be evaluated to an integer from 1 to 2. Type 1 refers to usages reported by AppSearchSession#reportUsage, and type 2 refers to usages reported by GlobalSearchSession#reportSystemUsage.

Some errors may occur when using advanced ranking.

Syntax Error: the expression violates the syntax of the advanced ranking language, such as unbalanced parenthesis.
Type Error: the expression fails a static type check, such as getting the wrong number of arguments for a function.
Evaluation Error: an error occurred while evaluating the value of the expression, such as getting a non-finite value in the middle of evaluation. Expressions like "1 / 0" and "log(0) fall into this category.

Syntax errors and type errors will fail the entire search and will cause SearchResults.getNextPage(Executor, Consumer>>) to throw an AppSearchException.

Evaluation errors will result in the offending documents receiving the default score. For SearchSpec.ORDER_DESCENDING, the default score will be 0, for SearchSpec.ORDER_ASCENDING the default score will be infinity.

Parameters
`advancedRankingExpression`	`String`: a non-empty string representing the ranking expression. This value cannot be `null`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setRankingStrategy

public SearchSpec.Builder setRankingStrategy (int rankingStrategy)

Sets ranking strategy for AppSearch results.

Parameters

rankingStrategy int: Value is SearchSpec.RANKING_STRATEGY_NONE, SearchSpec.RANKING_STRATEGY_DOCUMENT_SCORE, SearchSpec.RANKING_STRATEGY_CREATION_TIMESTAMP, SearchSpec.RANKING_STRATEGY_RELEVANCE_SCORE, SearchSpec.RANKING_STRATEGY_USAGE_COUNT, SearchSpec.RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP, SearchSpec.RANKING_STRATEGY_SYSTEM_USAGE_COUNT, SearchSpec.RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP, SearchSpec.RANKING_STRATEGY_JOIN_AGGREGATE_SCORE, or SearchSpec.RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION

Parameters
`rankingStrategy`	`int`: Value is `SearchSpec.RANKING_STRATEGY_NONE`, `SearchSpec.RANKING_STRATEGY_DOCUMENT_SCORE`, `SearchSpec.RANKING_STRATEGY_CREATION_TIMESTAMP`, `SearchSpec.RANKING_STRATEGY_RELEVANCE_SCORE`, `SearchSpec.RANKING_STRATEGY_USAGE_COUNT`, `SearchSpec.RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP`, `SearchSpec.RANKING_STRATEGY_SYSTEM_USAGE_COUNT`, `SearchSpec.RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP`, `SearchSpec.RANKING_STRATEGY_JOIN_AGGREGATE_SCORE`, or `SearchSpec.RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION`

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setResultCountPerPage

public SearchSpec.Builder setResultCountPerPage (int resultCountPerPage)

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

The default number of results per page is 10.

Parameters
`resultCountPerPage`	`int`: Value is between 0 and MAX_NUM_PER_PAGE inclusive

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setResultGrouping

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

Sets 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. Value is either `0` or a combination of `SearchSpec.GROUPING_TYPE_PER_PACKAGE`, and `SearchSpec.GROUPING_TYPE_PER_NAMESPACE`
`limit`	`int`: Number of results to return per `groupingTypeFlags`.

Returns
`SearchSpec.Builder`	This value cannot be `null`.

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.

The list returned from SearchResult#getMatchInfos will contain at most this many entries.

If set to 0 (default), snippeting is disabled and the list returned from SearchResult.getMatchInfos() will be empty.

Parameters
`snippetCount`	`int`: Value is between 0 and MAX_SNIPPET_COUNT inclusive

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setSnippetCountPerProperty

public SearchSpec.Builder setSnippetCountPerProperty (int snippetCountPerProperty)

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

If set to 0, snippeting is disabled and the list returned from SearchResult.getMatchInfos() will be empty.

The default behavior is to snippet all matches a property contains, up to the maximum value of 10,000.

Parameters
`snippetCountPerProperty`	`int`: Value is between 0 and MAX_SNIPPET_PER_PROPERTY_COUNT inclusive

Returns
`SearchSpec.Builder`	This value cannot be `null`.

setTermMatch

public SearchSpec.Builder setTermMatch (int termMatchType)

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
`termMatchType`	`int`: Value is `SearchSpec.TERM_MATCH_EXACT_ONLY`, or `SearchSpec.TERM_MATCH_PREFIX`

Returns
`SearchSpec.Builder`	This value cannot be `null`.

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2023-02-08 UTC.