Added in API level 31

Builder


class Builder
kotlin.Any
   ↳ android.app.appsearch.SearchSpec.Builder

Builder for objects.

Summary

Public constructors

Constructs a new builder for SearchSpec objects.

Public methods
SearchSpec.Builder
addEmbeddingParameters(vararg searchEmbeddings: EmbeddingVector!)

Adds an embedding search to SearchSpec Entry, which will be referred in the query expression and the ranking expression for embedding search.

SearchSpec.Builder

Adds an embedding search to SearchSpec Entry, which will be referred in the query expression and the ranking expression for embedding search.

SearchSpec.Builder
addFilterNamespaces(vararg namespaces: String!)

Adds a namespace filter to SearchSpec Entry.

SearchSpec.Builder

Adds a namespace filter to SearchSpec Entry.

SearchSpec.Builder
addFilterPackageNames(vararg packageNames: String!)

Adds a package name filter to SearchSpec Entry.

SearchSpec.Builder

Adds a package name filter to SearchSpec Entry.

SearchSpec.Builder
addFilterProperties(schema: String, propertyPaths: MutableCollection<String!>)

Adds property paths for the specified type to the property filter of SearchSpec Entry.

SearchSpec.Builder

Adds property paths for the specified type to the property filter of SearchSpec Entry.

SearchSpec.Builder
addFilterSchemas(vararg schemas: String!)

Adds a Schema type filter to SearchSpec Entry.

SearchSpec.Builder

Adds a Schema type filter to SearchSpec Entry.

SearchSpec.Builder
addInformationalRankingExpressions(vararg informationalRankingExpressions: String!)

Adds informational ranking expressions to be evaluated for each document in the search result.

SearchSpec.Builder
addInformationalRankingExpressions(informationalRankingExpressions: MutableCollection<String!>)

Adds informational ranking expressions to be evaluated for each document in the search result.

SearchSpec.Builder
addProjection(schema: String, propertyPaths: MutableCollection<String!>)

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

SearchSpec.Builder

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

SearchSpec.Builder
addSearchStringParameters(vararg searchStringParameters: String!)

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

SearchSpec.Builder
addSearchStringParameters(searchStringParameters: MutableList<String!>)

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

SearchSpec

Constructs a new SearchSpec from the contents of this builder.

SearchSpec.Builder
setDefaultEmbeddingSearchMetricType(defaultEmbeddingSearchMetricType: Int)

Sets the default embedding metric type used for embedding search (see android.app.appsearch.AppSearchSession#search) and ranking (see android.app.appsearch.SearchSpec.Builder#setRankingStrategy(java.lang.String)).

SearchSpec.Builder
setJoinSpec(joinSpec: JoinSpec)

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

SearchSpec.Builder

Sets the LIST_FILTER_HAS_PROPERTY_FUNCTION feature as enabled/disabled according to the enabled parameter.

SearchSpec.Builder

Sets the LIST_FILTER_QUERY_LANGUAGE feature as enabled/disabled according to the enabled parameter.

SearchSpec.Builder
setMaxSnippetSize(maxSnippetSize: Int)

Sets maxSnippetSize, the maximum snippet size.

SearchSpec.Builder

Sets the NUMERIC_SEARCH feature as enabled/disabled according to the enabled parameter.

SearchSpec.Builder
setOrder(order: Int)

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

SearchSpec.Builder
setPropertyWeightPaths(schemaType: String, propertyPathWeights: MutableMap<PropertyPath!, Double!>)

Sets property weights by schema type and property path.

SearchSpec.Builder
setPropertyWeights(schemaType: String, propertyPathWeights: MutableMap<String!, Double!>)

Sets property weights by schema type and property path.

SearchSpec.Builder
setRankingStrategy(rankingStrategy: Int)

Sets ranking strategy for AppSearch results.

SearchSpec.Builder
setRankingStrategy(advancedRankingExpression: String)

Enables advanced ranking to score based on advancedRankingExpression.

SearchSpec.Builder
setResultCountPerPage(resultCountPerPage: Int)

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

SearchSpec.Builder
setResultGrouping(groupingTypeFlags: Int, limit: Int)

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

SearchSpec.Builder
setSearchSourceLogTag(searchSourceLogTag: String)

Sets an optional log tag to indicate the source of this search.

SearchSpec.Builder
setSnippetCount(snippetCount: Int)

Sets the snippetCount such that the first snippetCount documents based on the ranking strategy will have snippet information provided.

SearchSpec.Builder
setSnippetCountPerProperty(snippetCountPerProperty: Int)

Sets snippetCountPerProperty.

SearchSpec.Builder
setTermMatch(termMatchType: Int)

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

SearchSpec.Builder

Sets the VERBATIM_SEARCH feature as enabled/disabled according to the enabled parameter.

Public constructors

Builder

Added in API level 31
Builder()

Constructs a new builder for SearchSpec objects.

Public methods

addEmbeddingParameters

fun addEmbeddingParameters(vararg searchEmbeddings: EmbeddingVector!): SearchSpec.Builder

Adds an embedding search to SearchSpec Entry, which will be referred in the query expression and the ranking expression for embedding search.

Parameters
searchEmbeddings EmbeddingVector!: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addEmbeddingParameters

fun addEmbeddingParameters(searchEmbeddings: MutableCollection<EmbeddingVector!>): SearchSpec.Builder

Adds an embedding search to SearchSpec Entry, which will be referred in the query expression and the ranking expression for embedding search.

Parameters
searchEmbeddings MutableCollection<EmbeddingVector!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addFilterNamespaces

Added in API level 31
fun addFilterNamespaces(vararg namespaces: String!): SearchSpec.Builder

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.
Return
SearchSpec.Builder This value cannot be null.

addFilterNamespaces

Added in API level 31
fun addFilterNamespaces(namespaces: MutableCollection<String!>): SearchSpec.Builder

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 MutableCollection<String!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addFilterPackageNames

Added in API level 31
fun addFilterPackageNames(vararg packageNames: String!): SearchSpec.Builder

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.
Return
SearchSpec.Builder This value cannot be null.

addFilterPackageNames

Added in API level 31
fun addFilterPackageNames(packageNames: MutableCollection<String!>): SearchSpec.Builder

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 MutableCollection<String!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addFilterProperties

fun addFilterProperties(
    schema: String,
    propertyPaths: MutableCollection<String!>
): SearchSpec.Builder

Adds property paths for the specified type to the property filter of SearchSpec Entry. Only returns documents that have matches under the specified properties. If property paths are added for a type, then only the properties referred to will be searched 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 searched.

Example properties: 'body', 'sender.name', 'sender.emailaddress', etc.

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

Parameters
schema String: the AppSearchSchema that contains the target properties This value cannot be null.
propertyPaths MutableCollection<String!>: The String version of PropertyPath. A dot-delimited sequence of property names. This value cannot be null.

addFilterPropertyPaths

fun addFilterPropertyPaths(
    schema: String,
    propertyPaths: MutableCollection<PropertyPath!>
): SearchSpec.Builder

Adds property paths for the specified type to the property filter of SearchSpec Entry. Only returns documents that have matches under the specified properties. If property paths are added for a type, then only the properties referred to will be searched for results of that type.

Parameters
schema String: the AppSearchSchema that contains the target properties This value cannot be null.
propertyPaths MutableCollection<PropertyPath!>: The PropertyPath to search search over This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addFilterSchemas

Added in API level 31
fun addFilterSchemas(vararg schemas: String!): SearchSpec.Builder

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.
Return
SearchSpec.Builder This value cannot be null.

addFilterSchemas

Added in API level 31
fun addFilterSchemas(schemas: MutableCollection<String!>): SearchSpec.Builder

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 MutableCollection<String!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addInformationalRankingExpressions

fun addInformationalRankingExpressions(vararg informationalRankingExpressions: String!): SearchSpec.Builder

Adds informational ranking expressions to be evaluated for each document in the search result. The values of these expressions will be returned to the caller via android.app.appsearch.SearchResult#getInformationalRankingSignals(). These expressions are purely for the caller to retrieve additional information about the result and have no effect on ranking.

The syntax is exactly the same as specified in android.app.appsearch.SearchSpec.Builder#setRankingStrategy(java.lang.String).

Parameters
informationalRankingExpressions String!: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addInformationalRankingExpressions

fun addInformationalRankingExpressions(informationalRankingExpressions: MutableCollection<String!>): SearchSpec.Builder

Adds informational ranking expressions to be evaluated for each document in the search result. The values of these expressions will be returned to the caller via android.app.appsearch.SearchResult#getInformationalRankingSignals(). These expressions are purely for the caller to retrieve additional information about the result and have no effect on ranking.

The syntax is exactly the same as specified in android.app.appsearch.SearchSpec.Builder#setRankingStrategy(java.lang.String).

Parameters
informationalRankingExpressions MutableCollection<String!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addProjection

Added in API level 31
fun addProjection(
    schema: String,
    propertyPaths: MutableCollection<String!>
): SearchSpec.Builder

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 MutableCollection<String!>: the projections to add. This value cannot be null.

addProjectionPaths

fun addProjectionPaths(
    schema: String,
    propertyPaths: MutableCollection<PropertyPath!>
): SearchSpec.Builder

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.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.

<code>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!"
  }
  </code>

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

<code>{schema: "Email", ["subject", "sender.name", "recipients.name"]}
  </code>

The above document will be returned as:

<code>Email: Document {
    sender: Document {
      name: "Mr. Body"
    }
    recipients: [
      Document {
        name: "John Doe"
      }
      Document {
        name: "Jane Doe"
      }
    ]
    subject: "IMPORTANT"
  }
  </code>
Parameters
schema String: a string corresponding to the schema to add projections to. This value cannot be null.
propertyPaths MutableCollection<PropertyPath!>: the projections to add. This value cannot be null.

addSearchStringParameters

fun addSearchStringParameters(vararg searchStringParameters: String!): SearchSpec.Builder

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

Parameters
searchStringParameters String!: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

addSearchStringParameters

fun addSearchStringParameters(searchStringParameters: MutableList<String!>): SearchSpec.Builder

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

Parameters
searchStringParameters MutableList<String!>: This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

build

Added in API level 31
fun build(): SearchSpec

Constructs a new SearchSpec from the contents of this builder.

Return
SearchSpec This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if property weights are provided with a ranking strategy that isn't RANKING_STRATEGY_RELEVANCE_SCORE.
java.lang.IllegalStateException if the aggregation scoring strategy has been set in android.app.appsearch.JoinSpec#getAggregationScoringStrategy() but the ranking strategy is not RANKING_STRATEGY_JOIN_AGGREGATE_SCORE.

setDefaultEmbeddingSearchMetricType

fun setDefaultEmbeddingSearchMetricType(defaultEmbeddingSearchMetricType: Int): SearchSpec.Builder

Sets the default embedding metric type used for embedding search (see android.app.appsearch.AppSearchSession#search) and ranking (see android.app.appsearch.SearchSpec.Builder#setRankingStrategy(java.lang.String)).

If this method is not called, the default embedding search metric type is android.app.appsearch.SearchSpec#EMBEDDING_SEARCH_METRIC_TYPE_COSINE. Metrics specified within "semanticSearch" or "matchedSemanticScores" functions in search/ranking expressions will override this default.

Parameters
defaultEmbeddingSearchMetricType Int: Value is android.app.appsearch.SearchSpec#EMBEDDING_SEARCH_METRIC_TYPE_COSINE, android.app.appsearch.SearchSpec#EMBEDDING_SEARCH_METRIC_TYPE_DOT_PRODUCT, or android.app.appsearch.SearchSpec#EMBEDDING_SEARCH_METRIC_TYPE_EUCLIDEAN
Return
SearchSpec.Builder This value cannot be null.

setJoinSpec

fun setJoinSpec(joinSpec: JoinSpec): SearchSpec.Builder

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

If the ranking strategy is 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.

setListFilterHasPropertyFunctionEnabled

fun setListFilterHasPropertyFunctionEnabled(enabled: Boolean): SearchSpec.Builder

Sets the LIST_FILTER_HAS_PROPERTY_FUNCTION feature as enabled/disabled according to the enabled parameter.

Parameters
enabled Boolean: Enables the feature if true, otherwise disables it

If disabled, disallows the use of the "hasProperty" function. See android.app.appsearch.AppSearchSession#search for more details about the function.

Return
SearchSpec.Builder This value cannot be null.

setListFilterQueryLanguageEnabled

fun setListFilterQueryLanguageEnabled(enabled: Boolean): SearchSpec.Builder

Sets the LIST_FILTER_QUERY_LANGUAGE feature as enabled/disabled according to the enabled parameter.

Parameters
enabled Boolean: Enables the feature if true, otherwise disables it.

This feature covers the expansion of the query language to conform to the definition of the list filters language (https://aip.dev/160). This includes:

  • addition of explicit 'AND' and 'NOT' operators
  • property restricts are allowed with grouping (ex. "prop:(a OR b)")
  • addition of custom functions to control matching

The newly added custom functions covered by this feature are:

  • createList(String...)
  • termSearch(String, List<String>)

createList takes a variable number of strings and returns a list of strings. It is for use with termSearch.

termSearch takes a query string that will be parsed according to the supported query language and an optional list of strings that specify the properties to be restricted to. This exists as a convenience for multiple property restricts. So, for example, the query "(subject:foo OR body:foo) (subject:bar OR body:bar)" could be rewritten as "termSearch(\"foo bar\", createList(\"subject\", \"bar\"))"

Return
SearchSpec.Builder This value cannot be null.

setMaxSnippetSize

Added in API level 31
fun setMaxSnippetSize(maxSnippetSize: Int): SearchSpec.Builder

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.

For example, 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
Return
SearchSpec.Builder This value cannot be null.

setNumericSearchEnabled

fun setNumericSearchEnabled(enabled: Boolean): SearchSpec.Builder

Sets the NUMERIC_SEARCH feature as enabled/disabled according to the enabled parameter.

Parameters
enabled Boolean: Enables the feature if true, otherwise disables it.

If disabled, disallows use of android.app.appsearch.AppSearchSchema.LongPropertyConfig#INDEXING_TYPE_RANGE and all other numeric querying features.

Return
SearchSpec.Builder This value cannot be null.

setOrder

Added in API level 31
fun setOrder(order: Int): SearchSpec.Builder

Sets the order of returned search results, the default is 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 android.app.appsearch.SearchSpec#ORDER_DESCENDING, or android.app.appsearch.SearchSpec#ORDER_ASCENDING
Return
SearchSpec.Builder This value cannot be null.

setPropertyWeightPaths

fun setPropertyWeightPaths(
    schemaType: String,
    propertyPathWeights: MutableMap<PropertyPath!, Double!>
): SearchSpec.Builder

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 RANKING_STRATEGY_RELEVANCE_SCORE.

Parameters
schemaType String: the schema type to set property weights for. This value cannot be null.
propertyPathWeights MutableMap<PropertyPath!, Double!>: a Map of property paths of the schema type to the weight to set for that property. This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if a weight is equal to or less than 0.0.

setPropertyWeights

fun setPropertyWeights(
    schemaType: String,
    propertyPathWeights: MutableMap<String!, Double!>
): SearchSpec.Builder

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 RANKING_STRATEGY_RELEVANCE_SCORE.

Parameters
schemaType String: the schema type to set property weights for. This value cannot be null.
propertyPathWeights MutableMap<String!, Double!>: a Map of property paths of the schema type to the weight to set for that property. This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if a weight is equal to or less than 0.0.

setRankingStrategy

fun setRankingStrategy(advancedRankingExpression: String): SearchSpec.Builder

Enables advanced ranking to score based on advancedRankingExpression.

This method will set RankingStrategy to 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 supported arithmetic operators:

  • Addition(+)
  • Subtraction(-)
  • Multiplication(*)
  • Floating Point Division(/)

Operator precedences are compliant with the Java Language, and parentheses are supported. For example, "2.2 + (3 - 4) / 2" evaluates to 1.7.

The following are supported basic 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
  • sqrt(x)
  • abs(x)
  • sin(x), cos(x), tan(x)
  • Example: "max(abs(-100), 10) + pow(2, 10)" will be evaluated to 1124

The following variadic mathematical functions are supported, with n > 0. They also accept list value parameters. For example, if V is a value of list type, we can call sum(V) to get the sum of all the values in V. List literals are not supported, so a value of list type can only be constructed as a return value of some particular document-based functions.

  • max(v1, v2, ..., vn) or max(V)
  • min(v1, v2, ..., vn) or min(V)
  • len(v1, v2, ..., vn) or len(V)
  • sum(v1, v2, ..., vn) or sum(V)
  • avg(v1, v2, ..., vn) or avg(V)

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 RANKING_STRATEGY_DOCUMENT_SCORE.

  • this.creationTimestamp()

    Get the creation timestamp of the current document. This is the same score that is returned for 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 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.

  • this.childrenRankingSignals()

    Returns a list of children ranking signals calculated by scoring the joined documents using the ranking strategy specified in the nested SearchSpec. Currently, a document can only be a child of another document in the context of joins. If this function is called without the Join API enabled, a type error will be raised.

  • this.propertyWeights()

    Returns a list of the normalized weights of the matched properties for the current document being scored. Property weights come from what's specified in SearchSpec. After normalizing, each provided weight will be divided by the maximum weight, so that each of them will be <= 1.

  • this.matchedSemanticScores(getEmbeddingParameter({embedding_index}), {metric})

    Returns a list of the matched similarity scores from "semanticSearch" in the query expression (see also AppSearchSession.search) based on embedding_index and metric. If metric is omitted, it defaults to the metric specified in SearchSpec.Builder.setDefaultEmbeddingSearchMetricType(int). If no "semanticSearch" is called for embedding_index and metric in the query, this function will return an empty list. If multiple "semanticSearch"s are called for the same embedding_index and metric, this function will return a list of their merged scores.

    Example: `this.matchedSemanticScores(getEmbeddingParameter(0), "COSINE")` will return a list of matched scores within the range of [0.5, 1], if `semanticSearch(getEmbeddingParameter(0), 0.5, 1, "COSINE")` is called in the query expression.

Some errors may occur when using advanced ranking.

Syntax Error: the expression violates the syntax of the advanced ranking language. Below are some examples.

  • "1 + " - missing operand
  • "2 * (1 + 2))" - unbalanced parenthesis
  • "2 ^ 3" - unknown operator

Type Error: the expression fails a static type check. Below are some examples.

  • "sin(2, 3)" - wrong number of arguments for the sin function
  • "this.childrenRankingSignals() + 1" - cannot add a list with a number
  • "this.propertyWeights()" - the final type of the overall expression cannot be a list, which can be fixed by "max(this.propertyWeights())"
  • "abs(this.propertyWeights())" - the abs function does not support list type arguments
  • "print(2)" - unknown function

Evaluation Error: an error occurred while evaluating the value of the expression. Below are some examples.

  • "1 / 0", "log(0)", "1 + sqrt(-1)" - getting a non-finite value in the middle of evaluation
  • "this.usageCount(1 + 0.5)" - expect the argument to be an integer. Note that this is not a type error and "this.usageCount(1.5 + 1/2)" can succeed without any issues
  • "this.documentScore()" - in case of an IO error, this will be an evaluation error

Syntax errors and type errors will fail the entire search and will cause android.app.appsearch.SearchResults#getNextPage to throw an AppSearchException with the result code of AppSearchResult.RESULT_INVALID_ARGUMENT.

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

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

setResultCountPerPage

Added in API level 31
fun setResultCountPerPage(resultCountPerPage: Int): SearchSpec.Builder

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
Return
SearchSpec.Builder This value cannot be null.

setResultGrouping

Added in API level 31
fun setResultGrouping(
    groupingTypeFlags: Int,
    limit: Int
): SearchSpec.Builder

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 android.app.appsearch.SearchSpec#GROUPING_TYPE_PER_PACKAGE, android.app.appsearch.SearchSpec#GROUPING_TYPE_PER_NAMESPACE, and android.app.appsearch.SearchSpec#GROUPING_TYPE_PER_SCHEMA
limit Int: Number of results to return per groupingTypeFlags.
Return
SearchSpec.Builder This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if groupingTypeFlags is zero.

setSearchSourceLogTag

fun setSearchSourceLogTag(searchSourceLogTag: String): SearchSpec.Builder

Sets an optional log tag to indicate the source of this search.

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 this method 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.

Parameters
searchSourceLogTag String: A String to indicate the source caller of this search. It is used to label the search statsd for performance analysis. It is not the tag we are using in android.util.Log. The length of the teg should between 1 and 100. This value cannot be null.
Return
SearchSpec.Builder This value cannot be null.

setSnippetCount

Added in API level 31
fun setSnippetCount(snippetCount: Int): SearchSpec.Builder

Sets the snippetCount such that 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 android.app.appsearch.SearchResult#getMatchInfos will be empty.

Parameters
snippetCount Int: Value is between 0 and MAX_SNIPPET_COUNT inclusive
Return
SearchSpec.Builder This value cannot be null.

setSnippetCountPerProperty

Added in API level 31
fun setSnippetCountPerProperty(snippetCountPerProperty: Int): SearchSpec.Builder

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 android.app.appsearch.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
Return
SearchSpec.Builder This value cannot be null.

setTermMatch

Added in API level 31
fun setTermMatch(termMatchType: Int): SearchSpec.Builder

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

If this method is not called, the default term match type is android.app.appsearch.SearchSpec#TERM_MATCH_PREFIX.

Parameters
termMatchType Int: Value is android.app.appsearch.SearchSpec#TERM_MATCH_EXACT_ONLY, or android.app.appsearch.SearchSpec#TERM_MATCH_PREFIX
Return
SearchSpec.Builder This value cannot be null.

setVerbatimSearchEnabled

fun setVerbatimSearchEnabled(enabled: Boolean): SearchSpec.Builder

Sets the VERBATIM_SEARCH feature as enabled/disabled according to the enabled parameter.

Parameters
enabled Boolean: Enables the feature if true, otherwise disables it

If disabled, disallows use of android.app.appsearch.AppSearchSchema.StringPropertyConfig#TOKENIZER_TYPE_VERBATIM and all other verbatim search features within the query language that allows clients to search using the verbatim string operator.

For example, The verbatim string operator '"foo/bar" OR baz' will ensure that 'foo/bar' is treated as a single 'verbatim' token.

Return
SearchSpec.Builder This value cannot be null.