AppSearchManager

AI-generated Key Takeaways

• AppSearchManager provides access to a centralized, offline, on-device search index for managing structured data.

• AppSearch supports indexing, full-text search retrieval, data visibility control for other applications, and opting in/out of System UI display.

• Applications interact with AppSearch by creating an AppSearchClient, setting a schema to define data structure, and using GenericDocument objects as the basic unit of data.

• Documents can be added, retrieved by ID or query, and removed based on time-to-live or explicit remove operations.

public class AppSearchManager extends Object

Provides access to the centralized AppSearch index maintained by the system.

AppSearch is an offline, on-device search library for managing structured data featuring:

• APIs to index and retrieve data via full-text search.
• An API for applications to explicitly grant read-access permission of their data to other applications. See: SetSchemaRequest.Builder.setSchemaTypeVisibilityForPackage(String, boolean, PackageIdentifier)
• An API for applications to opt into or out of having their data displayed on System UI surfaces by the System-designated global querier. See: SetSchemaRequest.Builder.setSchemaTypeDisplayedBySystem(String, boolean)

Applications create a database by opening an AppSearchClient.

Example:

 AppSearchManager appSearchManager = context.getSystemService(AppSearchManager.class);

 AppSearchManager.SearchContext searchContext = new AppSearchManager.SearchContext.Builder().
    setDatabaseName(dbName).build());
 appSearchManager.createSearchSession(searchContext, mExecutor, AppSearchClientResult -> {
      mAppSearchClient = AppSearchClientResult.getResultValue();
 });

After opening the session, a schema must be set in order to define the organizational structure of data. The schema is set by calling AppSearchClient.setSchema(SetSchemaRequest, String). The schema is composed of a collection of AppSearchSchema objects, each of which defines a unique type of data.

Example:

 AppSearchSchema emailSchemaType = new AppSearchSchema.Builder("Email")
     .addProperty(new StringPropertyConfig.Builder("subject")
        .setCardinality(PropertyConfig.CARDINALITY_OPTIONAL)
        .setIndexingType(PropertyConfig.INDEXING_TYPE_PREFIXES)
        .setTokenizerType(PropertyConfig.TOKENIZER_TYPE_PLAIN)
    .build()
 ).build();

 SetSchemaRequest request = new SetSchemaRequest.Builder().addSchema(emailSchemaType).build();
 mAppSearchClient.set(request, mExecutor, appSearchResult -> {
      if (appSearchResult.isSuccess()) {
           // Schema has been successfully set.
      }
 });

The basic unit of data in AppSearch is represented as a GenericDocument object, containing an ID, namespace, time-to-live, score, and properties. A namespace organizes a logical group of documents. For example, a namespace can be created to group documents on a per-account basis. An ID identifies a single document within a namespace. The combination of namespace and ID uniquely identifies a GenericDocument in the database.

Once the schema has been set, GenericDocument objects can be put into the database and indexed by calling AppSearchClient.put(PutDocumentsRequest, String).

Example:

 // Although for this example we use GenericDocument directly, we recommend extending
 // GenericDocument to create specific types (i.e. Email) with specific setters/getters.
 GenericDocument email = new GenericDocument.Builder<>(NAMESPACE, ID, EMAIL_SCHEMA_TYPE)
     .setPropertyString(“subject”, EMAIL_SUBJECT)
     .setScore(EMAIL_SCORE)
     .build();

 PutDocumentsRequest request = new PutDocumentsRequest.Builder().addGenericDocuments(email)
     .build();
 mAppSearchClient.put(request, mExecutor, appSearchBatchResult -> {
      if (appSearchBatchResult.isSuccess()) {
           // All documents have been successfully indexed.
      }
 });

Searching within the database is done by calling AppSearchClient.search(String, SearchSpec, String) and providing the query string to search for, as well as a SearchSpec.

Alternatively, AppSearchClient.getByDocumentId(GetByDocumentIdRequest, String) can be called to retrieve documents by namespace and ID.

Document removal is done either by time-to-live expiration, or explicitly calling a remove operation. Remove operations can be done by namespace and ID via AppSearchClient.remove(RemoveByDocumentIdRequest, String), or by query via AppSearchClient.remove(String, SearchSpec, String).

Nested Class Summary

class

AppSearchManager.SearchContext

Contains information about how to create the search session.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()