AppSearch

O AppSearch é uma solução de pesquisa no dispositivo de alto desempenho para gerenciamento local dados estruturados e armazenados. Ele contém APIs para indexar e recuperar dados usando a pesquisa de texto completo. Os aplicativos podem usar o AppSearch para oferecer anúncios personalizados no aplicativo recursos de pesquisa, permitindo que os usuários pesquisem conteúdo mesmo off-line.

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 consultas 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 uma aplicativo que gerencia as músicas favoritas dos usuários e permite que eles pesquisem facilmente para eles. Usuários ouvem músicas de todo o mundo com títulos em diferentes linguagens, que o AppSearch oferece suporte nativo a indexação e consultas. Quando o o usuário pesquisar uma música por título ou nome do artista, o aplicativo simplesmente passará a solicitação ao AppSearch para recuperar as músicas correspondentes de maneira rápida e eficiente. A o aplicativo exibe os resultados, permitindo que os usuários comecem a jogar suas músicas favoritas.

Configurar

Para usar o AppSearch no seu aplicativo, adicione as seguintes dependências ao seu arquivo build.gradle do aplicativo:

Groovy

dependencies {
    def appsearch_version = "1.1.0-alpha05"

    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-alpha05"

    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 dos conceitos do AppSearch: banco de dados, esquema, esquemas, documentos, sessão e pesquisa.

Banco de dados e sessão

Um banco de dados do AppSearch é uma coleção de documentos que estão em conformidade com o banco de dados esquema. Os aplicativos clientes criam um banco de dados fornecendo o aplicativo contexto 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 o banco de dados. A sessão é o ponto de entrada para chamar as APIs AppSearch e permanece aberto até ser fechado pelo aplicativo cliente.

Esquema e tipos de esquema

Um esquema representa a estrutura organizacional de dados em um AppSearch no seu banco de dados.

O esquema é composto por tipos que representam tipos únicos de dados. Os tipos de esquema consistem em propriedades que contêm um nome, tipo de dados e cardinalidade. Depois que um tipo de esquema é adicionado ao esquema do banco de dados, os documentos de esse tipo de esquema pode ser criado e adicionado ao banco de dados.

Documentos

No AppSearch, uma unidade de dados é representada como um documento. Cada documento em um O banco de dados AppSearch é identificado de forma exclusiva pelo namespace e ID. Namespaces são usados para separar dados de diferentes fontes quando apenas uma precisa que serão consultados, como contas de usuário.

Os documentos contêm um carimbo de data/hora da criação, um time to live (TTL) e uma pontuação que pode ser usada para classificação durante a recuperação. Um esquema também é atribuído a um documento que descreve as propriedades de dados adicionais que o documento deve ter.

Uma classe de documento é uma abstração de um documento. Contém campos com anotações que representam o conteúdo de um documento. Por padrão, o nome do documento define o nome do tipo de esquema.

Pesquisar

Os documentos são indexados e podem ser pesquisados através de uma consulta. Um documento é correspondentes e incluídos nos resultados da pesquisa se contiverem os termos da consulta ou corresponde a outra especificação de pesquisa. Os resultados são ordenados com base em e a estratégia de classificação. Os resultados da pesquisa são representados por páginas que você pode recuperar sequencialmente.

O AppSearch oferece personalizações para pesquisa, como filtros, configuração do tamanho da página e snippeting.

Armazenamento da plataforma vs. armazenamento local

O AppSearch oferece duas soluções de armazenamento: LocalStorage e PlatformStorage. Com o LocalStorage, seu aplicativo gerencia um índice específico do aplicativo que reside o diretório de dados do aplicativo. Com o PlatformStorage, seu aplicativo contribui para um índice central de todo o sistema. Acesso a dados no índice central é restrito aos dados que seu aplicativo contribuiu e aos dados que foram compartilhados explicitamente com você por outro aplicativo. Tanto a LocalStorage quanto O PlatformStorage compartilham a mesma API e pode ser trocado com base no versão:

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()));
}

Ao usar o PlatformStorage, seu aplicativo pode compartilhar dados de forma segura com outros para permitir que eles pesquisem os dados do app também. Somente leitura o compartilhamento de dados de aplicativo é concedido por um handshake de certificado para garantir que o outro aplicativo tem permissão para ler os dados. Leia mais sobre esta API na documentação de setSchemaTypeVisibilityForPackage().

Além disso, os dados indexados podem ser mostrados nas plataformas da interface do sistema. Os aplicativos podem desativar a exibição de alguns ou de todos os dados no sistema Plataformas de interface. Leia 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 vantagens e desvantagens a serem consideradas ao escolher entre LocalStorage e PlatformStorage. Como o PlatformStorage une as APIs do Jetpack ao AppSearch, o impacto no tamanho do APK é mínimo em comparação com o uso Armazenamento local. No entanto, isso também significa que as operações do AppSearch geram latência do binder ao chamar o serviço do sistema AppSearch. Com o PlatformStorage, O AppSearch limita o número de documentos e o tamanho de documentos que um aplicativo possa indexar para garantir um índice central eficiente.

Comece a usar o AppSearch

O exemplo nesta seção mostra como usar as APIs AppSearch para fazer a integração com um aplicativo hipotético de anotações.

Escrever uma classe de documentos

A primeira etapa para fazer a integração com o AppSearch é criar uma classe de documento para descrever os dados a serem inseridos no banco de dados. Marcar uma turma como uma classe de documento usando o @Document anotação.Você pode usar instâncias da classe document para colocar documentos em e e recuperar documentos do banco de dados.

O código a seguir define uma classe de documento Note com uma com a anotação @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

É necessário definir um esquema antes de colocar documentos e recuperá-los documentos do banco de dados. O esquema do banco de dados consiste em tipos diferentes de dados estruturados, chamados de "tipos de esquema". O código a seguir define fornecendo a classe Document 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 que um tipo de esquema é adicionado, é possível adicionar documentos desse tipo ao banco de dados. O código a seguir cria um documento do tipo de esquema Note usando a Note Builder de classes de documentos. Ele define o namespace do documento user1 para representar um usuário arbitrário desta amostra. Em seguida, 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

Você pode pesquisar documentos indexados usando as operações de pesquisa abordadas em nesta seção. O código a seguir executa consultas pelo termo "fruit" sobre 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 com SearchResults

As pesquisas retornam SearchResults. que dá acesso às páginas dos objetos SearchResult. Cada SearchResult contém o GenericDocument correspondente, a forma geral de uma no qual todos os documentos são convertidos. O código a seguir recebe a primeira página de resultados da pesquisa e converte o resultado de volta 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 observação, o aplicativo exclui a Note correspondente documento do banco de dados. Isso garante que a nota não será mais exibida consultas. O código a seguir faz uma solicitação explícita para remover o Note. documento do banco de dados por 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 devem ser mantidas periodicamente no disco chamando requestFlush() A O código a seguir chama requestFlush() com um listener para determinar se a chamada deu certo.

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 precisará ser fechado quando um aplicativo não chamar mais nenhum banco de dados. as operações. O código a seguir fecha a sessão do AppSearch que foi aberta 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 recursos a seguir:

Amostras

• Exemplo do Android AppSearch (Kotlin), um aplicativo de anotações que usa o AppSearch para indexar notas de um usuário e permite que usuários pesquisar nas anotações.

Enviar feedback

Envie comentários e ideias usando os recursos abaixo:

Issue Tracker (link em inglês)

Informe os bugs para que possamos corrigi-los.