AppSearchSession
class AppSearchSession : Closeable
kotlin.Any | |
↳ | android.app.appsearch.AppSearchSession |
Provides a connection to a single AppSearch database.
An AppSearchSession
instance provides access to database operations such as setting a schema, adding documents, and searching.
This class is thread safe.
Summary
Public methods | |
---|---|
Unit |
close() Closes the |
Unit |
getByDocumentId(request: GetByDocumentIdRequest, executor: Executor, callback: BatchResultCallback<String!, GenericDocument!>) Gets |
Unit |
getNamespaces(executor: Executor, callback: Consumer<AppSearchResult<MutableSet<String!>!>!>) Retrieves the set of all namespaces in the current database with at least one document. |
Unit |
getSchema(executor: Executor, callback: Consumer<AppSearchResult<GetSchemaResponse!>!>) Retrieves the schema most recently successfully provided to |
Unit |
getStorageInfo(executor: Executor, callback: Consumer<AppSearchResult<StorageInfo!>!>) Gets the storage info for this |
Unit |
put(request: PutDocumentsRequest, executor: Executor, callback: BatchResultCallback<String!, Void!>) Indexes documents into the |
Unit |
remove(request: RemoveByDocumentIdRequest, executor: Executor, callback: BatchResultCallback<String!, Void!>) Removes |
Unit |
remove(queryExpression: String, searchSpec: SearchSpec, executor: Executor, callback: Consumer<AppSearchResult<Void!>!>) Removes |
Unit |
reportUsage(request: ReportUsageRequest, executor: Executor, callback: Consumer<AppSearchResult<Void!>!>) Reports usage of a particular document by namespace and ID. |
SearchResults |
search(queryExpression: String, searchSpec: SearchSpec) Retrieves documents from the open |
Unit |
searchSuggestion(suggestionQueryExpression: String, searchSuggestionSpec: SearchSuggestionSpec, executor: Executor, callback: Consumer<AppSearchResult<MutableList<SearchSuggestionResult!>!>!>) Retrieves suggested Strings that could be used as |
Unit |
setSchema(request: SetSchemaRequest, workExecutor: Executor, callbackExecutor: Executor, callback: Consumer<AppSearchResult<SetSchemaResponse!>!>) Sets the schema that represents the organizational structure of data within the AppSearch database. |
Public methods
close
fun close(): Unit
Closes the AppSearchSession
to persist all schema and document updates, additions, and deletes to disk.
Exceptions | |
---|---|
java.lang.Exception |
if this resource cannot be closed |
java.io.IOException |
if an I/O error occurs |
getByDocumentId
fun getByDocumentId(
request: GetByDocumentIdRequest,
executor: Executor,
callback: BatchResultCallback<String!, GenericDocument!>
): Unit
Gets GenericDocument
objects by document IDs in a namespace from the AppSearchSession
database.
Parameters | |
---|---|
request |
GetByDocumentIdRequest: a request containing a namespace and IDs to get documents for. This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
BatchResultCallback<String!, GenericDocument!>: Callback to receive the pending result of performing this operation. The keys of the returned AppSearchBatchResult are the input IDs. The values are the returned GenericDocument s on success, or a failed AppSearchResult otherwise. IDs that are not found will return a failed AppSearchResult with a result code of AppSearchResult#RESULT_NOT_FOUND . If an unexpected internal error occurs in the AppSearch service, BatchResultCallback#onSystemError will be invoked with a Throwable . This value cannot be null . |
getNamespaces
fun getNamespaces(
executor: Executor,
callback: Consumer<AppSearchResult<MutableSet<String!>!>!>
): Unit
Retrieves the set of all namespaces in the current database with at least one document.
Parameters | |
---|---|
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<MutableSet<String!>!>!>: Callback to receive the namespaces. This value cannot be null . |
getSchema
fun getSchema(
executor: Executor,
callback: Consumer<AppSearchResult<GetSchemaResponse!>!>
): Unit
Retrieves the schema most recently successfully provided to setSchema
.
Parameters | |
---|---|
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<GetSchemaResponse!>!>: Callback to receive the pending results of schema. This value cannot be null . |
getStorageInfo
fun getStorageInfo(
executor: Executor,
callback: Consumer<AppSearchResult<StorageInfo!>!>
): Unit
Gets the storage info for this AppSearchSession
database.
This may take time proportional to the number of documents and may be inefficient to call repeatedly.
Parameters | |
---|---|
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<StorageInfo!>!>: Callback to receive the storage info. This value cannot be null . |
put
fun put(
request: PutDocumentsRequest,
executor: Executor,
callback: BatchResultCallback<String!, Void!>
): Unit
Indexes documents into the AppSearchSession
database.
Each GenericDocument
object must have a schemaType
field set to an AppSearchSchema
type that has been previously registered by calling the setSchema
method.
Parameters | |
---|---|
request |
PutDocumentsRequest: containing documents to be indexed. This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
BatchResultCallback<String!, Void!>: Callback to receive pending result of performing this operation. The keys of the returned AppSearchBatchResult are the IDs of the input documents. The values are null if they were successfully indexed, or a failed AppSearchResult otherwise. If an unexpected internal error occurs in the AppSearch service, android.app.appsearch.BatchResultCallback#onSystemError will be invoked with a Throwable . |
remove
fun remove(
request: RemoveByDocumentIdRequest,
executor: Executor,
callback: BatchResultCallback<String!, Void!>
): Unit
Removes GenericDocument
objects by document IDs in a namespace from the AppSearchSession
database.
Removed documents will no longer be surfaced by search
or getByDocumentId
calls.
Once the database crosses the document count or byte usage threshold, removed documents will be deleted from disk.
Parameters | |
---|---|
request |
RemoveByDocumentIdRequest: RemoveByDocumentIdRequest with IDs in a namespace to remove from the index. This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
BatchResultCallback<String!, Void!>: Callback to receive the pending result of performing this operation. The keys of the returned AppSearchBatchResult are the input document IDs. The values are null on success, or a failed AppSearchResult otherwise. IDs that are not found will return a failed AppSearchResult with a result code of android.app.appsearch.AppSearchResult#RESULT_NOT_FOUND . If an unexpected internal error occurs in the AppSearch service, BatchResultCallback#onSystemError will be invoked with a Throwable . |
remove
fun remove(
queryExpression: String,
searchSpec: SearchSpec,
executor: Executor,
callback: Consumer<AppSearchResult<Void!>!>
): Unit
Removes GenericDocument
s from the index by Query. Documents will be removed if they match the queryExpression
in given namespaces and schemaTypes which is set via android.app.appsearch.SearchSpec.Builder#addFilterNamespaces and android.app.appsearch.SearchSpec.Builder#addFilterSchemas.
An empty queryExpression
matches all documents.
An empty set of namespaces or schemaTypes matches all namespaces or schemaTypes in the current database.
Parameters | |
---|---|
queryExpression |
String: Query String to search. This value cannot be null . |
searchSpec |
SearchSpec: Spec containing schemaTypes, namespaces and query expression indicates how document will be removed. All specific about how to scoring, ordering, snippeting and resulting will be ignored. This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<Void!>!>: Callback to receive errors resulting from removing the documents. If the operation succeeds, the callback will be invoked with null . |
reportUsage
fun reportUsage(
request: ReportUsageRequest,
executor: Executor,
callback: Consumer<AppSearchResult<Void!>!>
): Unit
Reports usage of a particular document by namespace and ID.
A usage report represents an event in which a user interacted with or viewed a document.
For each call to reportUsage
, AppSearch updates usage count and usage recency metrics for that particular document. These metrics are used for ordering search
results by the SearchSpec#RANKING_STRATEGY_USAGE_COUNT
and android.app.appsearch.SearchSpec#RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP
ranking strategies.
Reporting usage of a document is optional.
Parameters | |
---|---|
request |
ReportUsageRequest: The usage reporting request. This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<Void!>!>: Callback to receive errors. If the operation succeeds, the callback will be invoked with null . |
search
fun search(
queryExpression: String,
searchSpec: SearchSpec
): SearchResults
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:
- AND (implicit)
AND is an operator that matches documents that contain all provided terms.
NOTE: 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".
- 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".
- Exclusion (-)
Exclusion (-) is an operator that matches documents that do not contain the provided term.
Example: "-apple" matches documents that do not contain "apple".
- 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".
- 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.
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:
- addition of explicit 'AND' and 'NOT' operators
- property restricts are allowed with groupings (ex. "prop:(a OR b)")
- addition of custom functions to control matching
The newly added custom functions covered by this feature are:
- createList(String...)
- search(String, List<String>)
- propertyDefined(String)
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 android.app.appsearch.SearchResults#getNextPage
.
Parameters | |
---|---|
queryExpression |
String: query string to search. This value cannot be null . |
searchSpec |
SearchSpec: spec for setting document filters, adding projection, setting term match type, etc. This value cannot be null . |
Return | |
---|---|
SearchResults |
a SearchResults object for retrieved matched documents. This value cannot be null . |
searchSuggestion
fun searchSuggestion(
suggestionQueryExpression: String,
searchSuggestionSpec: SearchSuggestionSpec,
executor: Executor,
callback: Consumer<AppSearchResult<MutableList<SearchSuggestionResult!>!>!>
): Unit
Retrieves suggested Strings that could be used as queryExpression
in search(java.lang.String,android.app.appsearch.SearchSpec)
API.
The suggestionQueryExpression
can contain one term with no operators, or contain multiple terms and operators. Operators will be considered as a normal term. Please see the operator examples below. The suggestionQueryExpression
must end with a valid term, the suggestions are generated based on the last term. If the input suggestionQueryExpression
doesn't have a valid token, AppSearch will return an empty result list. Please see the invalid examples below.
Example: if there are following documents with content stored in AppSearch.
- document1: "term1"
- document2: "term1 term2"
- document3: "term1 term2 term3"
- document4: "org"
Search suggestions with the single term suggestionQueryExpression
"t", the suggested results are:
- "term1" - Use it to be queryExpression in
search
could get 3SearchResult
s, which contains document 1, 2 and 3. - "term2" - Use it to be queryExpression in
search
could get 2SearchResult
s, which contains document 2 and 3. - "term3" - Use it to be queryExpression in
search
could get 1SearchResult
, which contains document 3.
Search suggestions with the multiple term suggestionQueryExpression
"org t", the suggested result will be "org term1" - The last token is completed by the suggested String.
Operators in search
are supported.
NOTE: Exclusion and Grouped Terms in the last term is not supported.
example: "apple -f": This Api will throw an with android.app.appsearch.AppSearchResult#RESULT_INVALID_ARGUMENT
.
example: "apple (f)": This Api will return an empty results.
Invalid example: All these input suggestionQueryExpression
don't have a valid last token, AppSearch will return an empty result list.
- "" - Empty
suggestionQueryExpression
. - "(f)" - Ending in a closed brackets.
- "f:" - Ending in an operator.
- "f " - Ending in trailing space.
Parameters | |
---|---|
suggestionQueryExpression |
String: the non empty query string to search suggestions This value cannot be null . |
searchSuggestionSpec |
SearchSuggestionSpec: spec for setting document filters This value cannot be null . |
executor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<MutableList<SearchSuggestionResult!>!>!>: Callback to receive the pending result of performing this operation, which is a List of SearchSuggestionResult on success. The returned suggestion Strings are ordered by the number of SearchResult you could get by using that suggestion in search . This value cannot be null . |
See Also
setSchema
fun setSchema(
request: SetSchemaRequest,
workExecutor: Executor,
callbackExecutor: Executor,
callback: Consumer<AppSearchResult<SetSchemaResponse!>!>
): Unit
Sets the schema that represents the organizational structure of data within the AppSearch database.
Upon creating an AppSearchSession
, setSchema
should be called. If the schema needs to be updated, or it has not been previously set, then the provided schema will be saved and persisted to disk. Otherwise, setSchema
is handled efficiently as a no-op call.
Parameters | |
---|---|
request |
SetSchemaRequest: the schema to set or update the AppSearch database to. This value cannot be null . |
workExecutor |
Executor: Executor on which to schedule heavy client-side background work such as transforming documents. This value cannot be null . |
callbackExecutor |
Executor: Executor on which to invoke the callback. This value cannot be null . Callback and listener events are dispatched through this Executor , providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor() . Otherwise, provide an Executor that dispatches to an appropriate thread. |
callback |
Consumer<AppSearchResult<SetSchemaResponse!>!>: Callback to receive errors resulting from setting the schema. If the operation succeeds, the callback will be invoked with null . |