Builder for objects
.
Public Constructor Summary
Builder()
Constructs a new builder for
SearchSpec
objects.
|
Public Method Summary
SearchSpec.Builder | |
SearchSpec.Builder | |
SearchSpec.Builder | |
SearchSpec.Builder |
addFilterPackageNames(Collection<String>
packageNames)
Adds a package name filter to
SearchSpec
Entry.
|
SearchSpec.Builder |
addFilterProperties(String schema,
Collection<String>
propertyPaths)
Adds property paths for the specified type to the property filter of
SearchSpec
Entry.
|
SearchSpec.Builder |
addFilterPropertyPaths(String schema,
Collection<PropertyPath>
propertyPaths)
Adds property paths for the specified type to the property filter of
SearchSpec
Entry.
|
SearchSpec.Builder | |
SearchSpec.Builder | |
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 | |
SearchSpec.Builder |
setListFilterHasPropertyFunctionEnabled(boolean enabled)
Sets the LIST_FILTER_HAS_PROPERTY_FUNCTION feature as enabled/disabled
according to the enabled parameter.
|
SearchSpec.Builder |
setListFilterQueryLanguageEnabled(boolean enabled)
Sets the LIST_FILTER_QUERY_LANGUAGE feature as enabled/disabled according to
the enabled parameter.
|
SearchSpec.Builder |
setMaxSnippetSize(int maxSnippetSize)
Sets
maxSnippetSize , the maximum snippet size.
|
SearchSpec.Builder |
setNumericSearchEnabled(boolean enabled)
Sets the NUMERIC_SEARCH feature as enabled/disabled according to the enabled
parameter.
|
SearchSpec.Builder |
setOrder(int order)
Sets 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 |
setSearchSourceLogTag(String
searchSourceLogTag)
Sets an optional log tag to indicate the source of this search.
|
SearchSpec.Builder |
setSnippetCount(int snippetCount)
Sets the
snippetCount such that 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)
Sets how the query terms should match
TermMatchCode in the index.
|
SearchSpec.Builder |
setVerbatimSearchEnabled(boolean enabled)
Sets the VERBATIM_SEARCH feature as enabled/disabled according to the enabled
parameter.
|
Inherited Method Summary
Public Constructors
public Builder ()
Constructs a new builder for SearchSpec
objects.
Public Methods
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.
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.
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.
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.
public SearchSpec.Builder addFilterProperties (String schema, Collection<String> propertyPaths)
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 | the AppSearchSchema
that contains the target properties |
---|---|
propertyPaths | The String version of PropertyPath .
A dot-delimited sequence of property names. |
public SearchSpec.Builder addFilterPropertyPaths (String schema, Collection<PropertyPath> propertyPaths)
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 | the AppSearchSchema
that contains the target properties |
---|---|
propertyPaths | The PropertyPath
to search search over |
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.
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.
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 | a string corresponding to the schema to add projections to. |
---|---|
propertyPaths | the projections to add. |
public SearchSpec.Builder addProjectionPaths (String schema, 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
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.
Email: Document {
sender: Document {
name: "Mr. Person"
email: "[email protected]"
}
recipients: [
Document {
name: "John Doe"
email: "[email protected]"
}
Document {
name: "Jane Doe"
email: "[email protected]"
}
]
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 | a string corresponding to the schema to add projections to. |
---|---|
propertyPaths | the projections to add. |
public SearchSpec build ()
Constructs a new SearchSpec
from the contents of this builder.
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. |
IllegalStateException | if the aggregation scoring strategy has been set in
JoinSpec.getAggregationScoringStrategy() but the ranking strategy is not
SearchSpec.RANKING_STRATEGY_JOIN_AGGREGATE_SCORE . |
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 | a specification on how to perform the Join operation. |
---|
public SearchSpec.Builder setListFilterHasPropertyFunctionEnabled (boolean enabled)
Sets the LIST_FILTER_HAS_PROPERTY_FUNCTION feature as enabled/disabled according to the enabled parameter.
Parameters
enabled |
Enables the feature if true, otherwise disables it
If disabled, disallows the use of the "hasProperty" function. See
|
---|
public SearchSpec.Builder setListFilterQueryLanguageEnabled (boolean enabled)
Sets the LIST_FILTER_QUERY_LANGUAGE feature as enabled/disabled according to the enabled parameter.
Parameters
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 (//aip.dev/160). This includes:
The newly added custom functions covered by this feature are:
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\"))" |
---|
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.
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.
public SearchSpec.Builder setNumericSearchEnabled (boolean enabled)
Sets the NUMERIC_SEARCH feature as enabled/disabled according to the enabled parameter.
Parameters
enabled |
Enables the feature if true, otherwise disables it.
If disabled, disallows use of |
---|
public SearchSpec.Builder setOrder (int order)
Sets 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
.
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 | the schema type to set property weights for. |
---|---|
propertyPathWeights | a Map of property
paths of the schema type to the weight to set for that property. |
Throws
IllegalArgumentException | if a weight is equal to or less than 0.0. |
---|
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.
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 | the schema type to set property weights for. |
---|---|
propertyPathWeights | a Map of property
paths of the schema type to the weight to set for that property. |
Throws
IllegalArgumentException | if a weight is equal to or less than 0.0. |
---|
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 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
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
AppSearchClient.reportUsage(ReportUsageRequest, String)
, and type 2 refers to usages reported byGlobalSearchClient.reportSystemUsage(ReportSystemUsageRequest)
. - 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
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 SearchSpec.ORDER_DESCENDING
,
the default score will be 0, for SearchSpec.ORDER_ASCENDING
the default score will be infinity.
Parameters
advancedRankingExpression | a non-empty string representing the ranking expression. |
---|
public SearchSpec.Builder setRankingStrategy (int rankingStrategy)
Sets ranking strategy for AppSearch results.
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.
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 | One or more combination of grouping types. |
---|---|
limit | Number of results to return per groupingTypeFlags . |
Throws
IllegalArgumentException | if groupingTypeFlags is zero. |
---|
public SearchSpec.Builder setSearchSourceLogTag (String searchSourceLogTag)
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 | 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
Log . The
length of the teg should between 1 and 100. |
---|
public SearchSpec.Builder setSnippetCount (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
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.
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.
public 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
SearchSpec.TERM_MATCH_PREFIX
.
public SearchSpec.Builder setVerbatimSearchEnabled (boolean enabled)
Sets the VERBATIM_SEARCH feature as enabled/disabled according to the enabled parameter.
Parameters
enabled |
Enables the feature if true, otherwise disables it
If disabled, disallows use of For example, The verbatim string operator '"foo/bar" OR baz' will ensure that 'foo/bar' is treated as a single 'verbatim' token. |
---|