Added in API level 31

Summary: Nested Classes | Constants | Inherited Constants | Fields | Methods | Inherited Methods

SearchSpec

---

Kotlin |Java

public final class SearchSpec
extends Object implements Parcelable

java.lang.Object
↳	android.app.appsearch.SearchSpec

---

This class represents the specification logic for AppSearch. It can be used to set the type of search, like prefix or exact only or apply filters to search for a specific schema type only etc.

Summary

Nested classes
class	SearchSpec.Builder Builder for objects.

Constants
int	EMBEDDING_SEARCH_METRIC_TYPE_COSINE Cosine similarity as metric for embedding search and ranking.
int	EMBEDDING_SEARCH_METRIC_TYPE_DOT_PRODUCT Dot product similarity as metric for embedding search and ranking.
int	EMBEDDING_SEARCH_METRIC_TYPE_EUCLIDEAN Euclidean distance as metric for embedding search and ranking.
int	GROUPING_TYPE_PER_NAMESPACE Results should be grouped together by namespace for the purpose of enforcing a limit on the number of results returned per namespace.
int	GROUPING_TYPE_PER_PACKAGE Results should be grouped together by package for the purpose of enforcing a limit on the number of results returned per package.
int	GROUPING_TYPE_PER_SCHEMA Results should be grouped together by schema type for the purpose of enforcing a limit on the number of results returned per schema type.
int	ORDER_ASCENDING Search results will be returned in an ascending order.
int	ORDER_DESCENDING Search results will be returned in a descending order.
String	PROJECTION_SCHEMA_TYPE_WILDCARD This constant was deprecated in API level Baklava. use SCHEMA_TYPE_WILDCARD instead.
int	RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION Ranked by the advanced ranking expression provided.
int	RANKING_STRATEGY_CREATION_TIMESTAMP Ranked by document creation timestamps.
int	RANKING_STRATEGY_DOCUMENT_SCORE Ranked by app-provided document scores.
int	RANKING_STRATEGY_JOIN_AGGREGATE_SCORE Ranked by the aggregated ranking signal of the joined documents.
int	RANKING_STRATEGY_NONE No Ranking, results are returned in arbitrary order.
int	RANKING_STRATEGY_RELEVANCE_SCORE Ranked by document relevance score.
int	RANKING_STRATEGY_SYSTEM_USAGE_COUNT Ranked by number of usages from a system UI surface.
int	RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP Ranked by timestamp of last usage from a system UI surface.
int	RANKING_STRATEGY_USAGE_COUNT Ranked by number of usages, as reported by the app.
int	RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP Ranked by timestamp of last usage, as reported by the app.
String	SCHEMA_TYPE_WILDCARD Schema type to be used in SearchSpec.Builder.addFilterProperties(String, Collection) and SearchSpec.Builder.addProjection to apply property paths to all results, excepting any types that have had their own, specific property paths set.
int	TERM_MATCH_EXACT_ONLY Query terms will only match exact tokens in the index.
int	TERM_MATCH_PREFIX Query terms will match indexed tokens when the query term is a prefix of the token.

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".

Fields
public static final Creator<SearchSpec>	CREATOR Creator class for SearchSpec.

Public methods
String	getAdvancedRankingExpression() Get the advanced ranking expression, or "" if Builder.setRankingStrategy(String) was not called.
int	getDefaultEmbeddingSearchMetricType() Returns the default embedding metric type used for embedding search (see AppSearchSession.search(String, SearchSpec)) and ranking (see SearchSpec.Builder.setRankingStrategy(java.lang.String)).
List<EmbeddingVector>	getEmbeddingParameters() Returns the list of EmbeddingVector that can be referenced in the query through the "getEmbeddingParameter({index})" function.
List<String>	getFilterNamespaces() Returns the list of namespaces to search over.
List<String>	getFilterPackageNames() Returns the list of package name filters to search over.
Map<String, List<String>>	getFilterProperties() Returns the map of schema and target properties to search over.
List<String>	getFilterSchemas() Returns the list of schema types to search for.
List<String>	getInformationalRankingExpressions() Returns the informational ranking expressions.
JoinSpec	getJoinSpec() Returns specification on which documents need to be joined.
int	getMaxSnippetSize() Returns the maximum size of a snippet in characters.
int	getOrder() Returns the order of returned search results (descending or ascending).
Map<String, List<PropertyPath>>	getProjectionPaths() Returns a map from schema type to property paths to be used for projection.
Map<String, List<String>>	getProjections() Returns a map from schema type to property paths to be used for projection.
Map<String, Map<PropertyPath, Double>>	getPropertyWeightPaths() Returns properties weights to be used for scoring.
Map<String, Map<String, Double>>	getPropertyWeights() Returns properties weights to be used for scoring.
int	getRankingStrategy() Returns the ranking strategy.
int	getResultCountPerPage() Returns the number of results per page in the result set.
int	getResultGroupingLimit() Get the maximum number of results to return for each group.
int	getResultGroupingTypeFlags() Get the type of grouping limit to apply, or 0 if Builder.setResultGrouping was not called.
String	getSearchSourceLogTag() Gets a tag to indicate the source of this search, or null if SearchSpec.Builder.setSearchSourceLogTag(java.lang.String) was not called.
List<String>	getSearchStringParameters() Returns the list of String parameters that can be referenced in the query through the "getSearchStringParameter({index})" function.
int	getSnippetCount() Returns how many documents to generate snippets for.
int	getSnippetCountPerProperty() Returns how many matches for each property of a matching document to generate snippets for.
int	getTermMatch() Returns how the query terms should match terms in the index.
boolean	isListFilterHasPropertyFunctionEnabled() Returns whether the LIST_FILTER_HAS_PROPERTY_FUNCTION feature is enabled.
boolean	isListFilterQueryLanguageEnabled() Returns whether the LIST_FILTER_QUERY_LANGUAGE feature is enabled.
boolean	isNumericSearchEnabled() Returns whether the NUMERIC_SEARCH feature is enabled.
boolean	isVerbatimSearchEnabled() Returns whether the VERBATIM_SEARCH feature is enabled.
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

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.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Constants

EMBEDDING_SEARCH_METRIC_TYPE_COSINE

Added in Android Baklava

public static final int EMBEDDING_SEARCH_METRIC_TYPE_COSINE

Cosine similarity as metric for embedding search and ranking.

Constant Value: 1 (0x00000001)

EMBEDDING_SEARCH_METRIC_TYPE_DOT_PRODUCT

Added in Android Baklava

public static final int EMBEDDING_SEARCH_METRIC_TYPE_DOT_PRODUCT

Dot product similarity as metric for embedding search and ranking.

Constant Value: 2 (0x00000002)

EMBEDDING_SEARCH_METRIC_TYPE_EUCLIDEAN

Added in Android Baklava

public static final int EMBEDDING_SEARCH_METRIC_TYPE_EUCLIDEAN

Euclidean distance as metric for embedding search and ranking.

Constant Value: 3 (0x00000003)

GROUPING_TYPE_PER_NAMESPACE

Added in API level 31

public static final int GROUPING_TYPE_PER_NAMESPACE

Results should be grouped together by namespace for the purpose of enforcing a limit on the number of results returned per namespace.

Constant Value: 2 (0x00000002)

GROUPING_TYPE_PER_PACKAGE

Added in API level 31

public static final int GROUPING_TYPE_PER_PACKAGE

Results should be grouped together by package for the purpose of enforcing a limit on the number of results returned per package.

Constant Value: 1 (0x00000001)

GROUPING_TYPE_PER_SCHEMA

Added in API level 35
Also in T Extensions 13

public static final int GROUPING_TYPE_PER_SCHEMA

Results should be grouped together by schema type for the purpose of enforcing a limit on the number of results returned per schema type.

Constant Value: 4 (0x00000004)

ORDER_ASCENDING

Added in API level 31

public static final int ORDER_ASCENDING

Search results will be returned in an ascending order.

Constant Value: 1 (0x00000001)

ORDER_DESCENDING

Added in API level 31

public static final int ORDER_DESCENDING

Search results will be returned in a descending order.

Constant Value: 0 (0x00000000)

PROJECTION_SCHEMA_TYPE_WILDCARD

Added in API level 31
Deprecated in API level Baklava

public static final String PROJECTION_SCHEMA_TYPE_WILDCARD

This constant was deprecated in API level Baklava.
use SCHEMA_TYPE_WILDCARD instead.

Schema type to be used in SearchSpec.Builder.addProjection to apply property paths to all results, excepting any types that have had their own, specific property paths set.

Constant Value: "*"

RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION

Added in API level 34
Also in T Extensions 7

public static final int RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION

Ranked by the advanced ranking expression provided.

Constant Value: 9 (0x00000009)

RANKING_STRATEGY_CREATION_TIMESTAMP

Added in API level 31

public static final int RANKING_STRATEGY_CREATION_TIMESTAMP

Ranked by document creation timestamps.

Constant Value: 2 (0x00000002)

RANKING_STRATEGY_DOCUMENT_SCORE

Added in API level 31

public static final int RANKING_STRATEGY_DOCUMENT_SCORE

Ranked by app-provided document scores.

Constant Value: 1 (0x00000001)

RANKING_STRATEGY_JOIN_AGGREGATE_SCORE

Added in API level 34
Also in T Extensions 7

public static final int RANKING_STRATEGY_JOIN_AGGREGATE_SCORE

Ranked by the aggregated ranking signal of the joined documents.

Which aggregation strategy is used to determine a ranking signal is specified in the JoinSpec set by Builder.setJoinSpec. This ranking strategy may not be used if no JoinSpec is provided.

See also:

• SearchSpec.Builder.build()

Constant Value: 8 (0x00000008)

RANKING_STRATEGY_NONE

Added in API level 31

public static final int RANKING_STRATEGY_NONE

No Ranking, results are returned in arbitrary order.

Constant Value: 0 (0x00000000)

RANKING_STRATEGY_RELEVANCE_SCORE

Added in API level 31

public static final int RANKING_STRATEGY_RELEVANCE_SCORE

Ranked by document relevance score.

Constant Value: 3 (0x00000003)

RANKING_STRATEGY_SYSTEM_USAGE_COUNT

Added in API level 31

public static final int RANKING_STRATEGY_SYSTEM_USAGE_COUNT

Ranked by number of usages from a system UI surface.

Constant Value: 6 (0x00000006)

RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP

Added in API level 31

public static final int RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP

Ranked by timestamp of last usage from a system UI surface.

Constant Value: 7 (0x00000007)

RANKING_STRATEGY_USAGE_COUNT

Added in API level 31

public static final int RANKING_STRATEGY_USAGE_COUNT

Ranked by number of usages, as reported by the app.

Constant Value: 4 (0x00000004)

RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP

Added in API level 31

public static final int RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP

Ranked by timestamp of last usage, as reported by the app.

Constant Value: 5 (0x00000005)

SCHEMA_TYPE_WILDCARD

Added in API level 35
Also in T Extensions 13

public static final String SCHEMA_TYPE_WILDCARD

Schema type to be used in SearchSpec.Builder.addFilterProperties(String, Collection) and SearchSpec.Builder.addProjection to apply property paths to all results, excepting any types that have had their own, specific property paths set.

Constant Value: "*"

TERM_MATCH_EXACT_ONLY

Added in API level 31

public static final int TERM_MATCH_EXACT_ONLY

Query terms will only match exact tokens in the index.

For example, a query term "foo" will only match indexed token "foo", and not "foot" or "football".

Constant Value: 1 (0x00000001)

TERM_MATCH_PREFIX

Added in API level 31

public static final int TERM_MATCH_PREFIX

Query terms will match indexed tokens when the query term is a prefix of the token.

For example, a query term "foo" will match indexed tokens like "foo", "foot", and "football".

Constant Value: 2 (0x00000002)

Fields

CREATOR

Added in API level 35
Also in T Extensions 13

public static final Creator<SearchSpec> CREATOR

Creator class for SearchSpec.

Public methods

getAdvancedRankingExpression

Added in API level 34
Also in T Extensions 7

public String getAdvancedRankingExpression ()

Get the advanced ranking expression, or "" if Builder.setRankingStrategy(String) was not called.

Returns
String	This value cannot be null.

getDefaultEmbeddingSearchMetricType

Added in Android Baklava

public int getDefaultEmbeddingSearchMetricType ()

Returns the default embedding metric type used for embedding search (see AppSearchSession.search(String, SearchSpec)) and ranking (see SearchSpec.Builder.setRankingStrategy(java.lang.String)).

Returns
int	Value is EMBEDDING_SEARCH_METRIC_TYPE_COSINE, EMBEDDING_SEARCH_METRIC_TYPE_DOT_PRODUCT, or EMBEDDING_SEARCH_METRIC_TYPE_EUCLIDEAN

getEmbeddingParameters

Added in Android Baklava

public List<EmbeddingVector> getEmbeddingParameters ()

Returns the list of EmbeddingVector that can be referenced in the query through the "getEmbeddingParameter({index})" function.

Returns
List<EmbeddingVector>	This value cannot be null.

See also:

• AppSearchSession.search(String, SearchSpec)

getFilterNamespaces

Added in API level 31

public List<String> getFilterNamespaces ()

Returns the list of namespaces to search over.

If empty, the query will search over all namespaces.

Returns
List<String>	This value cannot be null.

getFilterPackageNames

Added in API level 31

public List<String> getFilterPackageNames ()

Returns the list of package name filters to search over.

If empty, 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.

Returns
List<String>	This value cannot be null.

getFilterProperties

Added in API level 35
Also in T Extensions 13

public Map<String, List<String>> getFilterProperties ()

Returns the map of schema and target properties to search over.

If empty, will search over all schema and properties.

Calling this function repeatedly is inefficient. Prefer to retain the Map returned by this function, rather than calling it multiple times.

Returns
Map<String, List<String>>	This value cannot be null.

getFilterSchemas

Added in API level 31

public List<String> getFilterSchemas ()

Returns the list of schema types to search for.

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

Returns
List<String>	This value cannot be null.

getInformationalRankingExpressions

Added in Android Baklava

public List<String> getInformationalRankingExpressions ()

Returns the informational ranking expressions.

Returns
List<String>	This value cannot be null.

See also:

• SearchSpec.Builder.addInformationalRankingExpressions(String)

getJoinSpec

Added in API level 34
Also in T Extensions 7

public JoinSpec getJoinSpec ()

Returns specification on which documents need to be joined.

Returns
JoinSpec	This value may be null.

getMaxSnippetSize

Added in API level 31

public int getMaxSnippetSize ()

Returns the maximum size of a snippet in characters.

Returns
int

getOrder

Added in API level 31

public int getOrder ()

Returns the order of returned search results (descending or ascending).

Returns
int	Value is ORDER_DESCENDING, or ORDER_ASCENDING

getProjectionPaths

Added in API level 34
Also in T Extensions 7

public Map<String, List<PropertyPath>> getProjectionPaths ()

Returns a map from schema type to property paths to be used for projection.

If the map is empty, then all properties will be retrieved for all results.

Calling this function repeatedly is inefficient. Prefer to retain the Map returned by this function, rather than calling it multiple times.

Returns
Map<String, List<PropertyPath>>	A mapping of schema types to lists of projection PropertyPath objects. This value cannot be null.

getProjections

Added in API level 31

public Map<String, List<String>> getProjections ()

Returns a map from schema type to property paths to be used for projection.

If the map is empty, then all properties will be retrieved for all results.

Calling this function repeatedly is inefficient. Prefer to retain the Map returned by this function, rather than calling it multiple times.

Returns
Map<String, List<String>>	A mapping of schema types to lists of projection strings. This value cannot be null.

getPropertyWeightPaths

Added in API level 34
Also in T Extensions 7

public Map<String, Map<PropertyPath, Double>> getPropertyWeightPaths ()

Returns properties weights to be used for scoring.

Calling this function repeatedly is inefficient. Prefer to retain the Map returned by this function, rather than calling it multiple times.

Returns
Map<String, Map<PropertyPath, Double>>	a Map of schema type to an inner-map of property paths of the schema type to the weight to set for that property. This value cannot be null.

getPropertyWeights

Added in API level 34
Also in T Extensions 7

public Map<String, Map<String, Double>> getPropertyWeights ()

Returns properties weights to be used for scoring.

Calling this function repeatedly is inefficient. Prefer to retain the Map returned by this function, rather than calling it multiple times.

Returns
Map<String, Map<String, Double>>	a Map of schema type to an inner-map of property paths of the schema type to the weight to set for that property. This value cannot be null.

getRankingStrategy

Added in API level 31

public int getRankingStrategy ()

Returns the ranking strategy.

Returns
int	Value is RANKING_STRATEGY_NONE, RANKING_STRATEGY_DOCUMENT_SCORE, RANKING_STRATEGY_CREATION_TIMESTAMP, RANKING_STRATEGY_RELEVANCE_SCORE, RANKING_STRATEGY_USAGE_COUNT, RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP, RANKING_STRATEGY_SYSTEM_USAGE_COUNT, RANKING_STRATEGY_SYSTEM_USAGE_LAST_USED_TIMESTAMP, RANKING_STRATEGY_JOIN_AGGREGATE_SCORE, or RANKING_STRATEGY_ADVANCED_RANKING_EXPRESSION

getResultCountPerPage

Added in API level 31

public int getResultCountPerPage ()

Returns the number of results per page in the result set.

Returns
int

getResultGroupingLimit

Added in API level 31

public int getResultGroupingLimit ()

Get the maximum number of results to return for each group.

Returns
int	the maximum number of results to return for each group or Integer.MAX_VALUE if SearchSpec.Builder.setResultGrouping(int, int) was not called.

getResultGroupingTypeFlags

Added in API level 31

public int getResultGroupingTypeFlags ()

Get the type of grouping limit to apply, or 0 if Builder.setResultGrouping was not called.

Returns
int	Value is either 0 or a combination of GROUPING_TYPE_PER_PACKAGE, GROUPING_TYPE_PER_NAMESPACE, and GROUPING_TYPE_PER_SCHEMA

getSearchSourceLogTag

Added in API level 35
Also in T Extensions 13

public String getSearchSourceLogTag ()

Gets a tag to indicate the source of this search, or null if SearchSpec.Builder.setSearchSourceLogTag(java.lang.String) was not called.

Some AppSearch implementations may log a hash of this tag using statsd. This tag may be used for tracing performance issues and crashes to a component of an app.

Call Builder.setSearchSourceLogTag and give a unique value if you want to distinguish this search scenario with other search scenarios during performance analysis.

Under no circumstances will AppSearch log the raw String value using statsd, but it will be provided as-is to custom AppSearchLogger implementations you have registered in your app.

Returns
String

getSearchStringParameters

Added in Android Baklava

public List<String> getSearchStringParameters ()

Returns the list of String parameters that can be referenced in the query through the "getSearchStringParameter({index})" function.

Returns
List<String>	This value cannot be null.

See also:

• AppSearchSession.search(String, SearchSpec)

getSnippetCount

Added in API level 31

public int getSnippetCount ()

Returns how many documents to generate snippets for.

Returns
int

getSnippetCountPerProperty

Added in API level 31

public int getSnippetCountPerProperty ()

Returns how many matches for each property of a matching document to generate snippets for.

Returns
int

getTermMatch

Added in API level 31

public int getTermMatch ()

Returns how the query terms should match terms in the index.

Returns
int	Value is TERM_MATCH_EXACT_ONLY, or TERM_MATCH_PREFIX

isListFilterHasPropertyFunctionEnabled

Added in API level 35
Also in T Extensions 13

public boolean isListFilterHasPropertyFunctionEnabled ()

Returns whether the LIST_FILTER_HAS_PROPERTY_FUNCTION feature is enabled.

Returns
boolean

isListFilterQueryLanguageEnabled

Added in API level 34
Also in T Extensions 7

public boolean isListFilterQueryLanguageEnabled ()

Returns whether the LIST_FILTER_QUERY_LANGUAGE feature is enabled.

Returns
boolean

isNumericSearchEnabled

Added in API level 34
Also in T Extensions 7

public boolean isNumericSearchEnabled ()

Returns whether the NUMERIC_SEARCH feature is enabled.

Returns
boolean

isVerbatimSearchEnabled

Added in API level 34
Also in T Extensions 7

public boolean isVerbatimSearchEnabled ()

Returns whether the VERBATIM_SEARCH feature is enabled.

Returns
boolean

writeToParcel

Added in API level 35

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest	Parcel: This value cannot be null.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES