AppSearch es una solución de búsqueda de alto rendimiento integrada en el dispositivo para administrar datos estructurados almacenados de forma local. Contiene APIs para indexar y recuperar datos mediante la búsqueda en el texto completo. Las aplicaciones pueden usar AppSearch para ofrecer funciones personalizadas de búsqueda integrada en la app, lo que permite a los usuarios buscar contenido incluso sin conexión.
![Diagrama en el que se ilustra la indexación y la búsqueda dentro de AppSearch](https://developer.android.com/static/images/guide/topics/search/appsearch.png?authuser=7&hl=es)
AppSearch proporciona las siguientes funciones:
- Implementación rápida de almacenamiento mobile first con bajo uso de E/S
- Indexación y consultas muy eficientes en grandes conjuntos de datos
- Compatibilidad en varios idiomas, como inglés y español
- Clasificación de relevancia y puntuación de uso
Debido al menor uso de E/S, AppSearch ofrece menor latencia para la indexación y la búsqueda en grandes conjuntos de datos en comparación con SQLite. AppSearch simplifica las consultas entre tipos, ya que admite consultas únicas, mientras que SQLite combina los resultados de varias tablas.
Para ilustrar las funciones de AppSearch, tomemos el ejemplo de una aplicación de música que administra las canciones favoritas de los usuarios y permite que los usuarios las busquen fácilmente. Los usuarios disfrutan de la música de todo el mundo con títulos de canciones en diferentes idiomas, que AppSearch admite de forma nativa la indexación y las consultas. Cuando el usuario busca una canción por su título o nombre de artista, la aplicación simplemente pasa la solicitud a AppSearch para recuperar las canciones coincidentes de forma rápida y eficiente. La aplicación muestra los resultados, lo que permite a los usuarios comenzar rápidamente a reproducir sus canciones favoritas.
Configuración
Para usar AppSearch en tu aplicación, agrega las siguientes dependencias al archivo build.gradle
de tu aplicación:
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") }
Conceptos de AppSearch
En el siguiente diagrama, se ilustran los conceptos de AppSearch y sus interacciones.
Figura 1: Diagrama de conceptos de AppSearch: base de datos, esquema,
tipos de esquema, documentos, sesión y búsqueda de AppSearch
Base de datos y sesión
Una base de datos de AppSearch es una colección de documentos que se ajusta al esquema de la base de datos. Las aplicaciones cliente crean una base de datos cuando proporcionan el contexto de la aplicación y un nombre de base de datos. Solo la aplicación que creó las bases de datos puede abrirlas. Cuando se abre una base de datos, se muestra una sesión para interactuar con la base de datos. La sesión es el punto de entrada para llamar a las APIs de AppSearch y permanece abierta hasta que la aplicación cliente la cierra.
Esquemas y tipos de esquemas
Un esquema representa la estructura organizativa de los datos dentro de una base de datos de AppSearch.
El esquema se compone de tipos de esquema que representan tipos de datos únicos. Los tipos de esquema constan de propiedades que contienen un nombre, un tipo de datos y una cardinalidad. Una vez que se agrega un tipo de esquema al esquema de la base de datos, se pueden crear documentos de ese tipo de esquema y agregarlos a la base de datos.
Documentos
En AppSearch, una unidad de datos se representa como un documento. Cada documento de una base de datos de AppSearch se identifica de forma única por su ID y espacio de nombres. Los espacios de nombres se usan para separar datos de diferentes fuentes cuando solo se debe consultar una fuente, como las cuentas de usuario.
Los documentos contienen una marca de tiempo de creación, un tiempo de actividad (TTL) y una puntuación que se puede usar para clasificar durante la recuperación. A los documentos también se les asigna un tipo de esquema que describe las propiedades de datos adicionales que debe tener el documento.
Una clase de documento es una abstracción de un documento. Contiene campos anotados que representan el contenido de un documento. De forma predeterminada, el nombre de la clase de documento establece el nombre del tipo de esquema.
Buscar
Los documentos se indexan y se pueden buscar proporcionando una consulta. Un documento tiene una coincidencia y se incluye en los resultados de la búsqueda si contiene los términos de la consulta o si coincide con otra especificación de búsqueda. Los resultados se ordenan según su puntuación y estrategia de clasificación. Los resultados de la búsqueda están representados por páginas que puedes recuperar de forma secuencial.
AppSearch ofrece personalizaciones para la búsqueda, como los filtros, la configuración del tamaño de la página y la creación de fragmentos.
Comparación entre el almacenamiento en la plataforma y el almacenamiento local
AppSearch ofrece dos soluciones de almacenamiento: LocalStorage y PlatformStorage. Con LocalStorage, tu aplicación administra un índice específico de la app que se encuentra en el directorio de datos de tu aplicación. Con PlatformStorage, tu aplicación contribuye a un índice central en todo el sistema. El acceso a los datos dentro del índice central se restringe a los datos que contribuyó tu aplicación y a los que otra aplicación compartió contigo de forma explícita. Tanto LocalStorage como PlatformStorage comparten la misma API y se pueden intercambiar según la versión del 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())); }
Con PlatformStorage, tu aplicación puede compartir datos de forma segura con otras aplicaciones para permitirles buscar también en los datos de tu app. El uso compartido de datos de aplicación de solo lectura se otorga a través de un protocolo de enlace de certificados a fin de garantizar que la otra aplicación tenga permiso para leer los datos. Obtén más información sobre esta API en la documentación de setSchemaTypeVisibilityForPackage().
Además, los datos que se indexan se pueden mostrar en las plataformas de la IU del sistema. Las aplicaciones pueden inhabilitar la visualización de algunos o todos sus datos en las superficies de la IU del sistema. Obtén más información sobre esta API en la documentación de setSchemaTypeDisplayedBySystem().
Funciones | 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 |
Existen compensaciones adicionales que debes tener en cuenta cuando eliges entre LocalStorage y PlatformStorage. Debido a que PlatformStorage une las APIs de Jetpack sobre el servicio del sistema AppSearch, el impacto del tamaño del APK es mínimo en comparación con el uso de LocalStorage. Sin embargo, esto también significa que las operaciones de AppSearch incurren en latencia de Binder adicional cuando se llama al servicio del sistema de AppSearch. Con PlatformStorage, AppSearch limita la cantidad y el tamaño de los documentos que una aplicación puede indexar para garantizar un índice central eficiente.
Comienza a usar AppSearch
En el ejemplo de esta sección, se muestra cómo usar las APIs de AppSearch para integrarla a una aplicación hipotética de notas.
Cómo escribir una clase de documento
El primer paso para integrar AppSearch es escribir una clase de documento a fin de describir los datos que se insertarán en la base de datos. Para marcar una clase como clase de documento, usa la anotación @Document
.Puedes usar instancias de la clase de documento para colocarlos y recuperarlos de la base de datos.
El siguiente código define una clase de documento de Note con un campo @Document.StringProperty
anotado para indexar el texto de un objeto de 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; } }
Abre una base de datos
Debes crear una base de datos antes de trabajar con documentos. Con el siguiente código, se crea una base de datos nueva con el nombre notes_app
y se obtiene un ListenableFuture
para un AppSearchSession
, que representa la conexión a la base de datos y proporciona las APIs para las operaciones de base de datos.
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() );
Configura un esquema
Debes configurar un esquema antes de colocar y recuperar documentos de la base de datos. El esquema de la base de datos consta de diferentes tipos de datos estructurados, denominados “tipos de esquema”. El siguiente código establece el esquema proporcionando la clase de documento como un 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);
Coloca un documento en la base de datos
Una vez que se agrega un tipo de esquema, puedes agregar documentos de ese tipo a la base de datos.
Con el siguiente código, se compila un documento de tipo de esquema Note
con el compilador de clases de documentos Note
. Configura el espacio de nombres del documento user1
para representar a un
usuario arbitrario de esta muestra. Luego, el documento se inserta en la base de datos
y se adjunta un objeto de escucha para procesar el resultado de la operación 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);
Buscar
Puedes buscar documentos indexados con las operaciones de búsqueda que se abordan en esta sección. El siguiente código realiza consultas sobre el término “fruta” en la base de datos para documentos que pertenecen al espacio de nombres 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);
Cómo iterar con SearchResults
Las búsquedas muestran una instancia de SearchResults
, que da acceso a las páginas de objetos SearchResult
. Cada SearchResult
contiene su GenericDocument
coincidente, la forma general de un documento al que se convierten todos los documentos. Con el siguiente código, se obtiene la primera página de los resultados de la búsqueda y se vuelve a convertir en un 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);
Cómo quitar un documento
Cuando el usuario borra una nota, la aplicación borra el documento Note
correspondiente de la base de datos. Esto garantiza que la nota ya no aparecerá en las consultas. Con el siguiente código, se realiza una solicitud explícita para quitar el documento Note
de la base de datos 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);
Conservar en el disco
Las actualizaciones de una base de datos deben conservarse de forma periódica en el disco llamando a requestFlush()
. El siguiente código llama a requestFlush()
con un objeto de escucha para determinar si la llamada se realizó de forma correcta.
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);
Cómo cerrar una sesión
Se debe cerrar una AppSearchSession
cuando una aplicación ya no llame a ninguna operación de la base de datos. El siguiente código cierra la sesión de AppSearch que se abrió antes y conserva todas las actualizaciones en el 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);
Recursos adicionales
Para obtener más información sobre AppSearch, consulta los siguientes recursos adicionales:
Ejemplos
- Ejemplo de Android AppSearch (Kotlin), una app para tomar notas que usa AppSearch a fin de indexar las notas de un usuario y les permite buscar en ellas.
Envía comentarios
Usa estos recursos para compartir tus comentarios y tus ideas con nosotros:
Herramienta de seguimiento de errores
Informa los errores para que podamos corregirlos.