SearchSpec.Builder

public final class SearchSpec.Builder


Builder for objects.

Summary

Public constructors

Public methods

@NonNull SearchSpec.Builder
addFilterDocumentClasses(@NonNull Class[] documentClasses)

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

@NonNull SearchSpec.Builder

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

@NonNull SearchSpec.Builder
addFilterNamespaces(@NonNull String[] namespaces)

Adds a namespace filter to SearchSpec Entry.

@NonNull SearchSpec.Builder

Adds a namespace filter to SearchSpec Entry.

@NonNull SearchSpec.Builder
addFilterPackageNames(@NonNull String[] packageNames)

Adds a package name filter to SearchSpec Entry.

@NonNull SearchSpec.Builder

Adds a package name filter to SearchSpec Entry.

@NonNull SearchSpec.Builder
addFilterSchemas(@NonNull String[] schemas)

Adds a Schema type filter to SearchSpec Entry.

@NonNull SearchSpec.Builder

Adds a Schema type filter to SearchSpec Entry.

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

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

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

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

@NonNull SearchSpec.Builder
addProjectionPathsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Collection<PropertyPath> propertyPaths
)

Adds property paths for the specified Document class to be used for projection.

@NonNull SearchSpec.Builder
addProjectionsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Collection<String> propertyPaths
)

Adds property paths for the Document class to be used for projection.

@NonNull SearchSpec

Constructs a new SearchSpec from the contents of this builder.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.JOIN_SPEC_AND_QUALIFIED_ID)
setJoinSpec(@NonNull JoinSpec joinSpec)

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

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.LIST_FILTER_QUERY_LANGUAGE)
setListFilterQueryLanguageEnabled(boolean enabled)

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

@NonNull SearchSpec.Builder
setMaxSnippetSize(@IntRange(from = 0, to = 10000) int maxSnippetSize)

Sets maxSnippetSize, the maximum snippet size.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.NUMERIC_SEARCH)
setNumericSearchEnabled(boolean enabled)

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

@NonNull SearchSpec.Builder
setOrder(int order)

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

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
setPropertyWeightPaths(
    @NonNull String schemaType,
    @NonNull Map<PropertyPathDouble> propertyPathWeights
)

Sets property weights by schema type and property path.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
setPropertyWeightPathsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Map<PropertyPathDouble> propertyPathWeights
)

Sets property weights by schema type and property path.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
setPropertyWeights(
    @NonNull String schemaType,
    @NonNull Map<StringDouble> propertyPathWeights
)

Sets property weights by schema type and property path.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
setPropertyWeightsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Map<StringDouble> propertyPathWeights
)

Sets property weights by schema type and property path.

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_ADVANCED_RANKING_EXPRESSION)
setRankingStrategy(@NonNull String advancedRankingExpression)

Enables advanced ranking to score based on advancedRankingExpression.

@NonNull SearchSpec.Builder
setRankingStrategy(int rankingStrategy)

Sets ranking strategy for AppSearch results.

@NonNull SearchSpec.Builder
setResultCountPerPage(
    @IntRange(from = 0, to = 10000) int resultCountPerPage
)

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

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

@NonNull SearchSpec.Builder
setSnippetCount(@IntRange(from = 0, to = 10000) int snippetCount)

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

@NonNull SearchSpec.Builder
setSnippetCountPerProperty(
    @IntRange(from = 0, to = 10000) int snippetCountPerProperty
)

Sets snippetCountPerProperty.

@NonNull SearchSpec.Builder
setTermMatch(int termMatchType)

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

@NonNull SearchSpec.Builder
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.VERBATIM_SEARCH)
setVerbatimSearchEnabled(boolean enabled)

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

Public constructors

Builder

Added in 1.1.0-alpha04
public Builder()

Public methods

addFilterDocumentClasses

public @NonNull SearchSpec.Builder addFilterDocumentClasses(@NonNull 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.

Merged list available from getFilterSchemas.

Parameters
@NonNull Class[] documentClasses

classes annotated with Document.

addFilterDocumentClasses

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addFilterDocumentClasses(
    @NonNull Collection<Class<Object>> 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.

Merged list available from getFilterSchemas.

Parameters
@NonNull Collection<Class<Object>> documentClasses

classes annotated with Document.

addFilterNamespaces

public @NonNull SearchSpec.Builder addFilterNamespaces(@NonNull 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.

addFilterNamespaces

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addFilterNamespaces(@NonNull 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.

addFilterPackageNames

public @NonNull SearchSpec.Builder addFilterPackageNames(@NonNull 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.

addFilterPackageNames

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addFilterPackageNames(@NonNull 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.

addFilterSchemas

public @NonNull SearchSpec.Builder addFilterSchemas(@NonNull 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.

addFilterSchemas

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addFilterSchemas(@NonNull 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.

addProjection

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addProjection(
    @NonNull String schema,
    @NonNull 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
@NonNull String schema

a string corresponding to the schema to add projections to.

@NonNull Collection<String> propertyPaths

the projections to add.

addProjectionPaths

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addProjectionPaths(
    @NonNull String schema,
    @NonNull Collection<PropertyPath> 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 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
@NonNull String schema

a string corresponding to the schema to add projections to.

@NonNull Collection<PropertyPath> propertyPaths

the projections to add.

addProjectionPathsForDocumentClass

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addProjectionPathsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Collection<PropertyPath> propertyPaths
)

Adds property paths for the specified Document class to be used for projection.

Parameters
@NonNull Class<Object> documentClass

a class, annotated with @Document, corresponding to the schema to add projections to.

@NonNull Collection<PropertyPath> propertyPaths

the projections to add.

addProjectionsForDocumentClass

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder addProjectionsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Collection<String> propertyPaths
)

Adds property paths for the Document class to be used for projection. If property paths are added for a document class, 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
@NonNull Class<Object> documentClass

a class, annotated with @Document, corresponding to the schema to add projections to.

@NonNull Collection<String> propertyPaths

the projections to add.

See also
addProjection

build

Added in 1.1.0-alpha04
public @NonNull SearchSpec build()

Constructs a new SearchSpec from the contents of this builder.

Throws
java.lang.IllegalArgumentException

if property weights are provided with a ranking strategy that isn't RANKING_STRATEGY_RELEVANCE_SCORE.

java.lang.IllegalStateException

if the ranking strategy is RANKING_STRATEGY_JOIN_AGGREGATE_SCORE and setJoinSpec has never been called.

java.lang.IllegalStateException

if the aggregation scoring strategy has been set in getAggregationScoringStrategy but the ranking strategy is not RANKING_STRATEGY_JOIN_AGGREGATE_SCORE.

setJoinSpec

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.JOIN_SPEC_AND_QUALIFIED_ID)
public @NonNull SearchSpec.Builder setJoinSpec(@NonNull JoinSpec joinSpec)

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
@NonNull JoinSpec joinSpec

a specification on how to perform the Join operation.

setListFilterQueryLanguageEnabled

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.LIST_FILTER_QUERY_LANGUAGE)
public @NonNull SearchSpec.Builder setListFilterQueryLanguageEnabled(boolean enabled)

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

Parameters
boolean enabled

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)

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\"))"

setMaxSnippetSize

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setMaxSnippetSize(@IntRange(from = 0, to = 10000) 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.

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.

setNumericSearchEnabled

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.NUMERIC_SEARCH)
public @NonNull SearchSpec.Builder setNumericSearchEnabled(boolean enabled)

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

Parameters
boolean enabled

Enables the feature if true, otherwise disables it.

If disabled, disallows use of INDEXING_TYPE_RANGE and all other numeric querying features.

setOrder

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setOrder(int order)

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.

setPropertyWeightPaths

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
public @NonNull SearchSpec.Builder setPropertyWeightPaths(
    @NonNull String schemaType,
    @NonNull Map<PropertyPathDouble> 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 RANKING_STRATEGY_RELEVANCE_SCORE.

This information may not be available depending on the backend and Android API level. To ensure it is available, call isFeatureSupported.

Parameters
@NonNull String schemaType

the schema type to set property weights for.

@NonNull Map<PropertyPathDouble> propertyPathWeights

a Map of property paths of the schema type to the weight to set for that property.

Throws
java.lang.IllegalArgumentException

if a weight is equal to or less than 0.0.

setPropertyWeightPathsForDocumentClass

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
public @NonNull SearchSpec.Builder setPropertyWeightPathsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Map<PropertyPathDouble> 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 RANKING_STRATEGY_RELEVANCE_SCORE.

This information may not be available depending on the backend and Android API level. To ensure it is available, call isFeatureSupported.

Parameters
@NonNull Class<Object> documentClass

a class, annotated with @Document, corresponding to the schema to set property weights for.

@NonNull Map<PropertyPathDouble> propertyPathWeights

a Map of property paths of the schema type to the weight to set for that property.

Throws
androidx.appsearch.exceptions.AppSearchException

if no factory for this document class could be found on the classpath

java.lang.IllegalArgumentException

if a weight is equal to or less than 0.0.

setPropertyWeights

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
public @NonNull SearchSpec.Builder setPropertyWeights(
    @NonNull String schemaType,
    @NonNull Map<StringDouble> 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 RANKING_STRATEGY_RELEVANCE_SCORE.

This information may not be available depending on the backend and Android API level. To ensure it is available, call isFeatureSupported.

Parameters
@NonNull String schemaType

the schema type to set property weights for.

@NonNull Map<StringDouble> propertyPathWeights

a Map of property paths of the schema type to the weight to set for that property.

Throws
java.lang.IllegalArgumentException

if a weight is equal to or less than 0.0.

setPropertyWeightsForDocumentClass

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_PROPERTY_WEIGHTS)
public @NonNull SearchSpec.Builder setPropertyWeightsForDocumentClass(
    @NonNull Class<Object> documentClass,
    @NonNull Map<StringDouble> 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 RANKING_STRATEGY_RELEVANCE_SCORE.

This information may not be available depending on the backend and Android API level. To ensure it is available, call isFeatureSupported.

Parameters
@NonNull Class<Object> documentClass

a class, annotated with @Document, corresponding to the schema to set property weights for.

@NonNull Map<StringDouble> propertyPathWeights

a Map of property paths of the schema type to the weight to set for that property.

Throws
androidx.appsearch.exceptions.AppSearchException

if no factory for this document class could be found on the classpath

java.lang.IllegalArgumentException

if a weight is equal to or less than 0.0.

setRankingStrategy

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.SEARCH_SPEC_ADVANCED_RANKING_EXPRESSION)
public @NonNull SearchSpec.Builder setRankingStrategy(@NonNull String advancedRankingExpression)

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 reportUsageAsync, and type 2 refers to usages reported by reportSystemUsageAsync.

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

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 getNextPageAsync to throw an AppSearchException with the result code of 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
@NonNull String advancedRankingExpression

a non-empty string representing the ranking expression.

setRankingStrategy

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setRankingStrategy(int rankingStrategy)

Sets ranking strategy for AppSearch results.

setResultCountPerPage

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setResultCountPerPage(
    @IntRange(from = 0, to = 10000) int resultCountPerPage
)

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

The default number of results per page is 10.

setResultGrouping

Added in 1.1.0-alpha04
public @NonNull 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
int groupingTypeFlags

One or more combination of grouping types.

int limit

Number of results to return per groupingTypeFlags.

Throws
java.lang.IllegalArgumentException

if groupingTypeFlags is zero.

setSnippetCount

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setSnippetCount(@IntRange(from = 0, to = 10000) int snippetCount)

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

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

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

setSnippetCountPerProperty

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setSnippetCountPerProperty(
    @IntRange(from = 0, to = 10000) 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 getMatchInfos will be empty.

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

setTermMatch

Added in 1.1.0-alpha04
public @NonNull SearchSpec.Builder setTermMatch(int termMatchType)

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

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

setVerbatimSearchEnabled

Added in 1.1.0-alpha04
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.VERBATIM_SEARCH)
public @NonNull SearchSpec.Builder setVerbatimSearchEnabled(boolean enabled)

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

Parameters
boolean enabled

Enables the feature if true, otherwise disables it

If disabled, disallows use of 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.