O AppSearch é uma solução de pesquisa no dispositivo de alto desempenho para gerenciar dados estruturados e armazenados localmente. Ela contém APIs para indexar e recuperar dados usando a pesquisa de texto completo. Os aplicativos podem usar o AppSearch para oferecer recursos de pesquisa personalizados no app, permitindo que os usuários pesquisem conteúdo mesmo off-line.
![Diagrama ilustrando a indexação e a pesquisa com o AppSearch](https://developer.android.com/static/images/guide/topics/search/appsearch.png?authuser=7&hl=pt)
O AppSearch oferece os seguintes recursos:
- Uma implementação de armazenamento rápida e mobile-first com baixo uso de E/S
- Indexação e consulta altamente eficientes em grandes conjuntos de dados
- suporte a vários idiomas, como inglês e espanhol;
- Classificação de relevância e pontuação de uso
Devido ao menor uso de E/S, o AppSearch oferece menor latência para indexação e pesquisa em grandes conjuntos de dados em comparação com o SQLite. O AppSearch simplifica as consultas entre tipos oferecendo suporte a consultas únicas, enquanto o SQLite mescla resultados de várias tabelas.
Para ilustrar os recursos do AppSearch, vamos pegar o exemplo de um aplicativo de música que gerencia as músicas favoritas dos usuários e permite que os usuários as pesquisem facilmente. Os usuários ouvem músicas do mundo todo com títulos em diferentes idiomas, que têm suporte nativo para indexação e consulta. Quando o usuário pesquisa uma música pelo título ou nome do artista, o app simplesmente transmite a solicitação ao AppSearch para recuperar as músicas correspondentes de maneira rápida e eficiente. O app mostra os resultados, permitindo que os usuários comecem a tocar rapidamente as músicas favoritas.
Configurar
Para usar o AppSearch no seu app, adicione as dependências abaixo ao
arquivo build.gradle
do seu app:
Groovy
dependencies { def appsearch_version = "1.1.0-alpha04" implementation "androidx.appsearch:appsearch:$appsearch_version" // Use kapt instead of annotationProcessor if writing Kotlin classes annotationProcessor "androidx.appsearch:appsearch-compiler:$appsearch_version" implementation "androidx.appsearch:appsearch-local-storage:$appsearch_version" // PlatformStorage is compatible with Android 12+ devices, and offers additional features // to LocalStorage. implementation "androidx.appsearch:appsearch-platform-storage:$appsearch_version" }
Kotlin
dependencies { val appsearch_version = "1.1.0-alpha04" implementation("androidx.appsearch:appsearch:$appsearch_version") // Use annotationProcessor instead of kapt if writing Java classes kapt("androidx.appsearch:appsearch-compiler:$appsearch_version") implementation("androidx.appsearch:appsearch-local-storage:$appsearch_version") // PlatformStorage is compatible with Android 12+ devices, and offers additional features // to LocalStorage. implementation("androidx.appsearch:appsearch-platform-storage:$appsearch_version") }
Conceitos do AppSearch
O diagrama a seguir ilustra os conceitos do AppSearch e as interações deles.
Figura 1. Diagrama de conceitos do AppSearch: banco de dados do AppSearch, esquema,
tipos de esquema, documentos, sessão e pesquisa.
Banco de dados e sessão
Um banco de dados do AppSearch é uma coleção de documentos que está em conformidade com o esquema do banco de dados. Os aplicativos clientes criam um banco de dados fornecendo o contexto do aplicativo e um nome de banco de dados. Os bancos de dados só podem ser abertos pelo aplicativo que os criou. Quando um banco de dados é aberto, uma sessão é retornada para interagir com ele. A sessão é o ponto de entrada para chamar as APIs AppSearch e permanece aberta até ser fechada pelo aplicativo cliente.
Tipos de esquema e esquema
Um esquema representa a estrutura organizacional de dados em um banco de dados do AppSearch.
O esquema é composto por tipos de esquema que representam tipos exclusivos de dados. Os tipos de esquema consistem em propriedades que contêm um nome, um tipo de dados e uma cardinalidade. Depois que um tipo de esquema é adicionado ao esquema do banco de dados, os documentos desse tipo podem ser criados e adicionados ao banco de dados.
Documentos
No AppSearch, uma unidade de dados é representada como um documento. Cada documento em um banco de dados do AppSearch é identificado exclusivamente por seu namespace e ID. Os namespaces são usados para separar dados de origens diferentes quando apenas uma origem precisa ser consultada, como contas de usuário.
Os documentos contêm um carimbo de data/hora de criação, um time to live (TTL) e uma pontuação que pode ser usada para classificação durante a recuperação. Um documento também recebe um tipo de esquema que descreve propriedades de dados adicionais que o documento precisa ter.
Uma classe de documento é uma abstração de um documento. Ele contém campos anotados que representam o conteúdo de um documento. Por padrão, o nome da classe de documento define o nome do tipo de esquema.
Pesquisar
Os documentos são indexados e podem ser pesquisados com uma consulta. Um documento é correspondido e incluído nos resultados da pesquisa se contiver os termos na consulta ou corresponder a outra especificação de pesquisa. Os resultados são ordenados com base na pontuação e estratégia de classificação. Os resultados da pesquisa são representados por páginas que você pode recuperar em sequência.
O AppSearch oferece personalizações para pesquisa, como filtros, configuração de tamanho de página e criação de snippets.
Platform Storage vs. armazenamento local
O AppSearch oferece duas soluções de armazenamento: LocalStorage e PlatformStorage. Com o LocalStorage, seu aplicativo gerencia um índice específico que reside no diretório de dados do aplicativo. Com o PlatformStorage, seu aplicativo contribui para um índice central do sistema. O acesso aos dados no índice central é restrito aos dados que seu aplicativo contribuiu e aos que foram explicitamente compartilhados com você por outro aplicativo. Tanto o LocalStorage quanto o PlatformStorage compartilham a mesma API e podem ser trocados com base na versão de um dispositivo:
Kotlin
if (BuildCompat.isAtLeastS()) { appSearchSessionFuture.setFuture( PlatformStorage.createSearchSession( PlatformStorage.SearchContext.Builder(mContext, DATABASE_NAME) .build() ) ) } else { appSearchSessionFuture.setFuture( LocalStorage.createSearchSession( LocalStorage.SearchContext.Builder(mContext, DATABASE_NAME) .build() ) ) }
Java
if (BuildCompat.isAtLeastS()) { mAppSearchSessionFuture.setFuture(PlatformStorage.createSearchSession( new PlatformStorage.SearchContext.Builder(mContext, DATABASE_NAME) .build())); } else { mAppSearchSessionFuture.setFuture(LocalStorage.createSearchSession( new LocalStorage.SearchContext.Builder(mContext, DATABASE_NAME) .build())); }
Com o PlatformStorage, seu aplicativo pode compartilhar dados de maneira segura com outros aplicativos para permitir que eles também pesquisem os dados do seu app. O compartilhamento de dados de aplicativos somente leitura é concedido por meio de um handshake de certificado para garantir que o outro aplicativo tenha permissão para ler os dados. Saiba mais sobre essa API na documentação de setSchemaTypeVisibilityForPackage().
Além disso, os dados indexados podem ser mostrados nas superfícies da interface do sistema. Os aplicativos podem desativar a exibição de alguns ou todos os dados nas superfícies da IU do sistema. Saiba mais sobre essa API na documentação de setSchemaTypeDisplayedBySystem().
Recursos | LocalStorage (compatible with Android 4.0+) |
PlatformStorage (compatible with Android 12+) |
---|---|---|
Efficient full-text search |
||
Multi-language support |
||
Reduced binary size |
||
Application-to-application data sharing |
||
Capability to display data on System UI surfaces |
||
Unlimited document size and count can be indexed |
||
Faster operations without additional binder latency |
Há outras compensações a serem consideradas ao escolher entre LocalStorage e PlatformStorage. Como o PlatformStorage envolve as APIs do Jetpack no serviço do sistema AppSearch, o impacto no tamanho do APK é mínimo em comparação com o uso do LocalStorage. No entanto, isso também significa que as operações do AppSearch geram mais latência de binder ao chamar o serviço do sistema AppSearch. Com o PlatformStorage, o AppSearch limita o número de documentos e o tamanho dos documentos que um aplicativo pode indexar para garantir um índice central eficiente.
Começar a usar o AppSearch
O exemplo nesta seção mostra como usar as APIs AppSearch para integrar a um aplicativo hipotético de anotações.
Escrever uma classe de documentos
A primeira etapa para integrar com o AppSearch é escrever uma classe de documento para
descrever os dados a serem inseridos no banco de dados. Marque uma classe como de documento
usando a anotação @Document
.Você pode usar instâncias dessa classe para colocar e
extrair documentos do banco de dados.
O código a seguir define uma classe de documento Note com um campo anotado @Document.StringProperty
para indexar o texto de um objeto Note.
Kotlin
@Document public data class Note( // Required field for a document class. All documents MUST have a namespace. @Document.Namespace val namespace: String, // Required field for a document class. All documents MUST have an Id. @Document.Id val id: String, // Optional field for a document class, used to set the score of the // document. If this is not included in a document class, the score is set // to a default of 0. @Document.Score val score: Int, // Optional field for a document class, used to index a note's text for this // document class. @Document.StringProperty(indexingType = AppSearchSchema.StringPropertyConfig.INDEXING_TYPE_PREFIXES) val text: String )
Java
@Document public class Note { // Required field for a document class. All documents MUST have a namespace. @Document.Namespace private final String namespace; // Required field for a document class. All documents MUST have an Id. @Document.Id private final String id; // Optional field for a document class, used to set the score of the // document. If this is not included in a document class, the score is set // to a default of 0. @Document.Score private final int score; // Optional field for a document class, used to index a note's text for this // document class. @Document.StringProperty(indexingType = StringPropertyConfig.INDEXING_TYPE_PREFIXES) private final String text; Note(@NonNull String id, @NonNull String namespace, int score, @NonNull String text) { this.id = Objects.requireNonNull(id); this.namespace = Objects.requireNonNull(namespace); this.score = score; this.text = Objects.requireNonNull(text); } @NonNull public String getNamespace() { return namespace; } @NonNull public String getId() { return id; } public int getScore() { return score; } @NonNull public String getText() { return text; } }
Abrir um banco de dados
É necessário criar um banco de dados antes de trabalhar com documentos. O código a seguir
cria um novo banco de dados com o nome notes_app
e recebe um ListenableFuture
para um AppSearchSession
,
que representa a conexão com o banco de dados e fornece as APIs para
operações de banco de dados.
Kotlin
val context: Context = getApplicationContext() val sessionFuture = LocalStorage.createSearchSession( LocalStorage.SearchContext.Builder(context, /*databaseName=*/"notes_app") .build() )
Java
Context context = getApplicationContext(); ListenableFuture<AppSearchSession> sessionFuture = LocalStorage.createSearchSession( new LocalStorage.SearchContext.Builder(context, /*databaseName=*/ "notes_app") .build() );
Definir um esquema
Defina um esquema antes de colocar documentos e recuperar documentos do banco de dados. O esquema do banco de dados consiste em diferentes tipos de dados estruturados, chamados de "tipos de esquema". O código a seguir define o esquema fornecendo a classe do documento como um tipo de esquema.
Kotlin
val setSchemaRequest = SetSchemaRequest.Builder().addDocumentClasses(Note::class.java) .build() val setSchemaFuture = Futures.transformAsync( sessionFuture, { session -> session?.setSchema(setSchemaRequest) }, mExecutor )
Java
SetSchemaRequest setSchemaRequest = new SetSchemaRequest.Builder().addDocumentClasses(Note.class) .build(); ListenableFuture<SetSchemaResponse> setSchemaFuture = Futures.transformAsync(sessionFuture, session -> session.setSchema(setSchemaRequest), mExecutor);
Colocar um documento no banco de dados
Depois de adicionar um tipo de esquema, é possível incluir documentos desse tipo ao banco de dados.
O código a seguir cria um documento do tipo de esquema Note
usando o builder de classe de documento Note
. Ele define o namespace do documento user1
para representar um usuário arbitrário dessa amostra. O documento é inserido no banco de dados
e um listener é anexado para processar o resultado da operação put.
Kotlin
val note = Note( namespace="user1", id="noteId", score=10, text="Buy fresh fruit" ) val putRequest = PutDocumentsRequest.Builder().addDocuments(note).build() val putFuture = Futures.transformAsync( sessionFuture, { session -> session?.put(putRequest) }, mExecutor ) Futures.addCallback( putFuture, object : FutureCallback<AppSearchBatchResult<String, Void>?> { override fun onSuccess(result: AppSearchBatchResult<String, Void>?) { // Gets map of successful results from Id to Void val successfulResults = result?.successes // Gets map of failed results from Id to AppSearchResult val failedResults = result?.failures } override fun onFailure(t: Throwable) { Log.e(TAG, "Failed to put documents.", t) } }, mExecutor )
Java
Note note = new Note(/*namespace=*/"user1", /*id=*/ "noteId", /*score=*/ 10, /*text=*/ "Buy fresh fruit!"); PutDocumentsRequest putRequest = new PutDocumentsRequest.Builder().addDocuments(note) .build(); ListenableFuture<AppSearchBatchResult<String, Void>> putFuture = Futures.transformAsync(sessionFuture, session -> session.put(putRequest), mExecutor); Futures.addCallback(putFuture, new FutureCallback<AppSearchBatchResult<String, Void>>() { @Override public void onSuccess(@Nullable AppSearchBatchResult<String, Void> result) { // Gets map of successful results from Id to Void Map<String, Void> successfulResults = result.getSuccesses(); // Gets map of failed results from Id to AppSearchResult Map<String, AppSearchResult<Void>> failedResults = result.getFailures(); } @Override public void onFailure(@NonNull Throwable t) { Log.e(TAG, "Failed to put documents.", t); } }, mExecutor);
Pesquisar
É possível pesquisar documentos indexados usando as operações de pesquisa abordadas nesta
seção. O código a seguir executa consultas pelo termo "fruit" no banco de dados para documentos que pertencem ao namespace user1
.
Kotlin
val searchSpec = SearchSpec.Builder() .addFilterNamespaces("user1") .build(); val searchFuture = Futures.transform( sessionFuture, { session -> session?.search("fruit", searchSpec) }, mExecutor ) Futures.addCallback( searchFuture, object : FutureCallback<SearchResults> { override fun onSuccess(searchResults: SearchResults?) { iterateSearchResults(searchResults) } override fun onFailure(t: Throwable?) { Log.e("TAG", "Failed to search notes in AppSearch.", t) } }, mExecutor )
Java
SearchSpec searchSpec = new SearchSpec.Builder() .addFilterNamespaces("user1") .build(); ListenableFuture<SearchResults> searchFuture = Futures.transform(sessionFuture, session -> session.search("fruit", searchSpec), mExecutor); Futures.addCallback(searchFuture, new FutureCallback<SearchResults>() { @Override public void onSuccess(@Nullable SearchResults searchResults) { iterateSearchResults(searchResults); } @Override public void onFailure(@NonNull Throwable t) { Log.e(TAG, "Failed to search notes in AppSearch.", t); } }, mExecutor);
Iterar usando SearchResults
As pesquisas retornam uma instância de SearchResults
, que fornece acesso às páginas de objetos SearchResult
. Cada SearchResult
contém o GenericDocument
correspondente, a forma geral de um
documento em que todos os documentos são convertidos. O código a seguir acessa a primeira
página de resultados da pesquisa e converte o resultado em um documento Note
.
Kotlin
Futures.transform( searchResults?.nextPage, { page: List<SearchResult>? -> // Gets GenericDocument from SearchResult. val genericDocument: GenericDocument = page!![0].genericDocument val schemaType = genericDocument.schemaType val note: Note? = try { if (schemaType == "Note") { // Converts GenericDocument object to Note object. genericDocument.toDocumentClass(Note::class.java) } else null } catch (e: AppSearchException) { Log.e( TAG, "Failed to convert GenericDocument to Note", e ) null } note }, mExecutor )
Java
Futures.transform(searchResults.getNextPage(), page -> { // Gets GenericDocument from SearchResult. GenericDocument genericDocument = page.get(0).getGenericDocument(); String schemaType = genericDocument.getSchemaType(); Note note = null; if (schemaType.equals("Note")) { try { // Converts GenericDocument object to Note object. note = genericDocument.toDocumentClass(Note.class); } catch (AppSearchException e) { Log.e(TAG, "Failed to convert GenericDocument to Note", e); } } return note; }, mExecutor);
Remover um documento
Quando o usuário exclui uma nota, o aplicativo exclui o documento Note
correspondente do banco de dados. Isso garante que a observação não apareça mais nas
consultas. O código a seguir faz uma solicitação explícita para remover o documento Note
do banco de dados pelo ID.
Kotlin
val removeRequest = RemoveByDocumentIdRequest.Builder("user1") .addIds("noteId") .build() val removeFuture = Futures.transformAsync( sessionFuture, { session -> session?.remove(removeRequest) }, mExecutor )
Java
RemoveByDocumentIdRequest removeRequest = new RemoveByDocumentIdRequest.Builder("user1") .addIds("noteId") .build(); ListenableFuture<AppSearchBatchResult<String, Void>> removeFuture = Futures.transformAsync(sessionFuture, session -> session.remove(removeRequest), mExecutor);
Manter no disco
As atualizações em um banco de dados precisam ser mantidas periodicamente no disco chamando
requestFlush()
. O
código a seguir chama requestFlush()
com um listener para determinar se a chamada
foi bem-sucedida.
Kotlin
val requestFlushFuture = Futures.transformAsync( sessionFuture, { session -> session?.requestFlush() }, mExecutor ) Futures.addCallback(requestFlushFuture, object : FutureCallback<Void?> { override fun onSuccess(result: Void?) { // Success! Database updates have been persisted to disk. } override fun onFailure(t: Throwable) { Log.e(TAG, "Failed to flush database updates.", t) } }, mExecutor)
Java
ListenableFuture<Void> requestFlushFuture = Futures.transformAsync(sessionFuture, session -> session.requestFlush(), mExecutor); Futures.addCallback(requestFlushFuture, new FutureCallback<Void>() { @Override public void onSuccess(@Nullable Void result) { // Success! Database updates have been persisted to disk. } @Override public void onFailure(@NonNull Throwable t) { Log.e(TAG, "Failed to flush database updates.", t); } }, mExecutor);
Encerrar uma sessão
Um AppSearchSession
precisa ser fechado quando um aplicativo não for mais chamar nenhuma operação
do banco de dados. O código a seguir fecha a sessão do AppSearch que foi aberta
anteriormente e mantém todas as atualizações no disco.
Kotlin
val closeFuture = Futures.transform<AppSearchSession, Unit>(sessionFuture, { session -> session?.close() Unit }, mExecutor )
Java
ListenableFuture<Void> closeFuture = Futures.transform(sessionFuture, session -> { session.close(); return null; }, mExecutor);
Outros recursos
Para saber mais sobre o AppSearch, consulte os seguintes recursos extras:
Exemplos
- Exemplo do Android AppSearch (Kotlin) (link em inglês), um app de anotações que usa o AppSearch para indexar as notas de um usuário e permite que os usuários pesquisem as notas.
Enviar feedback
Envie comentários e ideias usando os recursos abaixo:
Informe bugs para que possamos corrigi-los.