AppSearchSession.Search(String, SearchSpec) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Retrieves documents from the open AppSearchSession that match a given query string
and type of search provided.
[Android.Runtime.Register("search", "(Ljava/lang/String;Landroid/app/appsearch/SearchSpec;)Landroid/app/appsearch/SearchResults;", "", ApiSince=31)]
public Android.App.AppSearch.SearchResults Search (string queryExpression, Android.App.AppSearch.SearchSpec searchSpec);[<Android.Runtime.Register("search", "(Ljava/lang/String;Landroid/app/appsearch/SearchSpec;)Landroid/app/appsearch/SearchResults;", "", ApiSince=31)>]
member this.Search : string * Android.App.AppSearch.SearchSpec -> Android.App.AppSearch.SearchResultsParameters
- queryExpression
- String
query string to search.
- searchSpec
- SearchSpec
spec for setting document filters, adding projection, setting term match type, etc.
Returns
a SearchResults object for retrieved matched documents.
- Attributes
Remarks
Retrieves documents from the open AppSearchSession that match a given query string and type of search provided.
Query strings can be empty, contain one term with no operators, or contain multiple terms and operators.
For query strings that are empty, all documents that match the SearchSpec will be returned.
For query strings with a single term and no operators, documents that match the provided query string and SearchSpec will be returned.
The following operators are supported:
<ul> <li>AND (implicit)
AND is an operator that matches documents that contain all provided terms.
<b>NOTE:</b> A space between terms is treated as an "AND" operator. Explicitly including "AND" in a query string will treat "AND" as a term, returning documents that also contain "AND".
Example: "apple AND banana" matches documents that contain the terms "apple", "and", "banana".
Example: "apple banana" matches documents that contain both "apple" and "banana".
Example: "apple banana cherry" matches documents that contain "apple", "banana", and "cherry". <li>OR
OR is an operator that matches documents that contain any provided term.
Example: "apple OR banana" matches documents that contain either "apple" or "banana".
Example: "apple OR banana OR cherry" matches documents that contain any of "apple", "banana", or "cherry". <li>Exclusion (-)
Exclusion (-) is an operator that matches documents that do not contain the provided term.
Example: "-apple" matches documents that do not contain "apple". <li>Grouped Terms
For queries that require multiple operators and terms, terms can be grouped into subqueries. Subqueries are contained within an open "(" and close ")" parenthesis.
Example: "(donut OR bagel) (coffee OR tea)" matches documents that contain either "donut" or "bagel" and either "coffee" or "tea". <li>Property Restricts
For queries that require a term to match a specific AppSearchSchema property of a document, a ":" must be included between the property name and the term.
Example: "subject:important" matches documents that contain the term "important" in the "subject" property. </ul>
The above description covers the basic query operators. Additional advanced query operator features should be explicitly enabled in the SearchSpec and are described below.
LIST_FILTER_QUERY_LANGUAGE: 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:
<ul> <li>addition of explicit 'AND' and 'NOT' operators <li>property restricts are allowed with groupings (ex. "prop:(a OR b)") <li>addition of custom functions to control matching </ul>
The newly added custom functions covered by this feature are:
<ul> <li>createList(String...) <li>search(String, List<String>) <li>propertyDefined(String) </ul>
createList takes a variable number of strings and returns a list of strings. It is for use with search.
search 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 `search("foo bar", createList("subject", "bar"))`.
propertyDefined takes a string specifying the property of interest and matches all documents of any type that defines the specified property (ex. `propertyDefined("sender.name")`). Note that propertyDefined will match so long as the document's type defines the specified property. It does NOT require that the document actually hold any values for this property.
NUMERIC_SEARCH: This feature covers numeric search expressions. In the query language, the values of properties that have AppSearchSchema.LongPropertyConfig#INDEXING_TYPE_RANGE set can be matched with a numeric search expression (the property, a supported comparator and an integer value). Supported comparators are <, <=, ==, >= and >.
Ex. `price < 10` will match all documents that has a numeric value in its price property that is less than 10.
VERBATIM_SEARCH: This feature covers the verbatim string operator (quotation marks).
Ex. `"foo/bar" OR baz` will ensure that 'foo/bar' is treated as a single 'verbatim' token.
Additional search specifications, such as filtering by AppSearchSchema type or adding projection, can be set by calling the corresponding SearchSpec.Builder setter.
This method is lightweight. The heavy work will be done in SearchResults#getNextPage.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.