AppSearchSession


public interface AppSearchSession extends Closeable


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.

Instances of this interface are usually obtained from a storage implementation, e.g. LocalStorage.createSearchSessionAsync() or PlatformStorage.createSearchSessionAsync().

All implementations of this interface must be thread safe.

Summary

Public methods

abstract void

Closes the AppSearchSession to persist all schema and document updates, additions, and deletes to disk.

default @NonNull ListenableFuture<CommitBlobResponse>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
commitBlobAsync(@NonNull Set<AppSearchBlobHandle> handles)

Commits the blobs to make it retrievable and immutable.

abstract @NonNull ListenableFuture<AppSearchBatchResult<StringGenericDocument>>

Gets GenericDocument objects by document IDs in a namespace from the AppSearchSession database.

abstract @NonNull Features

Returns the Features to check for the availability of certain features for this session.

abstract @NonNull ListenableFuture<Set<String>>

Retrieves the set of all namespaces in the current database with at least one document.

abstract @NonNull ListenableFuture<GetSchemaResponse>

Retrieves the schema most recently successfully provided to setSchemaAsync.

abstract @NonNull ListenableFuture<StorageInfo>

Gets the storage info for this AppSearchSession database.

default @NonNull ListenableFuture<OpenBlobForReadResponse>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
openBlobForReadAsync(@NonNull Set<AppSearchBlobHandle> handles)

Opens a batch of AppSearch Blobs for reading.

default @NonNull ListenableFuture<OpenBlobForWriteResponse>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
openBlobForWriteAsync(@NonNull Set<AppSearchBlobHandle> handles)

Opens a batch of AppSearch Blobs for writing.

abstract @NonNull ListenableFuture<AppSearchBatchResult<StringVoid>>

Indexes documents into the AppSearchSession database.

abstract @NonNull ListenableFuture<AppSearchBatchResult<StringVoid>>

Removes GenericDocument objects by document IDs in a namespace from the AppSearchSession database.

abstract @NonNull ListenableFuture<Void>
removeAsync(
    @NonNull String queryExpression,
    @NonNull SearchSpec searchSpec
)

Removes GenericDocuments from the index by Query.

default @NonNull ListenableFuture<RemoveBlobResponse>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
removeBlobAsync(@NonNull Set<AppSearchBlobHandle> handles)

Removes the blob data from AppSearch.

abstract @NonNull ListenableFuture<Void>

Reports usage of a particular document by namespace and ID.

abstract @NonNull ListenableFuture<Void>

Flush all schema and document updates, additions, and deletes to disk if possible.

abstract @NonNull SearchResults
search(@NonNull String queryExpression, @NonNull SearchSpec searchSpec)

Retrieves documents from the open AppSearchSession that match a given query string and type of search provided.

abstract @NonNull ListenableFuture<List<SearchSuggestionResult>>
searchSuggestionAsync(
    @NonNull String suggestionQueryExpression,
    @NonNull SearchSuggestionSpec searchSuggestionSpec
)

Retrieves suggested Strings that could be used as queryExpression in search API.

default @NonNull ListenableFuture<Void>
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
setBlobVisibilityAsync(@NonNull SetBlobVisibilityRequest request)

Sets the visibility configuration for all blob namespaces within an appsearch database.

abstract @NonNull ListenableFuture<SetSchemaResponse>

Sets the schema that represents the organizational structure of data within the AppSearch database.

Public methods

close

Added in 1.1.0
abstract void close()

Closes the AppSearchSession to persist all schema and document updates, additions, and deletes to disk.

commitBlobAsync

Added in 1.1.0
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<CommitBlobResponsecommitBlobAsync(@NonNull Set<AppSearchBlobHandle> handles)

Commits the blobs to make it retrievable and immutable.

After this call, the blob is readable via openBlobForReadAsync. Any change to the content or rewrite via openBlobForWriteAsync of this blob won't be allowed.

If the blob is already stored in AppSearch and committed. A failed AppSearchResult with error code RESULT_ALREADY_EXISTS will be associated with the AppSearchBlobHandle.

If the blob content doesn't match the digest in AppSearchBlobHandle, a failed AppSearchResult with error code RESULT_INVALID_ARGUMENT will be associated with the AppSearchBlobHandle. The pending Blob file will be removed from AppSearch.

Pending blobs won't be lost or auto-commit if AppSearchSession closed. Pending blobs will store in disk rather than memory. You can re-open AppSearchSession and re-write the pending blobs.

The default time to recycle pending and orphan blobs is 1 week. A blob will be considered as an orphan if no GenericDocument references it.

Both pending blob files and committed blob files can be manually removed via removeBlobAsync.

Parameters
@NonNull Set<AppSearchBlobHandle> handles

The AppSearchBlobHandles that identifies the blobs.

Returns
@NonNull ListenableFuture<CommitBlobResponse>

a response containing the commit results.

getByDocumentIdAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<AppSearchBatchResult<StringGenericDocument>> getByDocumentIdAsync(@NonNull GetByDocumentIdRequest request)

Gets GenericDocument objects by document IDs in a namespace from the AppSearchSession database.

Parameters
@NonNull GetByDocumentIdRequest request

a request containing a namespace and IDs to get documents for.

Returns
@NonNull ListenableFuture<AppSearchBatchResult<StringGenericDocument>>

A ListenableFuture which resolves to an AppSearchBatchResult. The keys of the AppSearchBatchResult represent the input document IDs from the GetByDocumentIdRequest object. The values are either the corresponding GenericDocument object for the ID on success, or an AppSearchResult object on failure. For example, if an ID is not found, the value for that ID will be set to an AppSearchResult object with result code: RESULT_NOT_FOUND.

getFeatures

Added in 1.1.0
abstract @NonNull Features getFeatures()

Returns the Features to check for the availability of certain features for this session.

getNamespacesAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<Set<String>> getNamespacesAsync()

Retrieves the set of all namespaces in the current database with at least one document.

Returns
@NonNull ListenableFuture<Set<String>>

The pending result of performing this operation.

getSchemaAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<GetSchemaResponsegetSchemaAsync()

Retrieves the schema most recently successfully provided to setSchemaAsync.

Returns
@NonNull ListenableFuture<GetSchemaResponse>

The pending GetSchemaResponse of performing this operation.

getStorageInfoAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<StorageInfogetStorageInfoAsync()

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.

Returns
@NonNull ListenableFuture<StorageInfo>

a ListenableFuture which resolves to a StorageInfo object.

openBlobForReadAsync

Added in 1.1.0
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<OpenBlobForReadResponseopenBlobForReadAsync(@NonNull Set<AppSearchBlobHandle> handles)

Opens a batch of AppSearch Blobs for reading.

Only blobs committed via commitBlobAsync are available for reading.

The returned OpenBlobForReadResponse must be closed after use to avoid resource leaks. Failing to close it will result in system file descriptor exhaustion.

Parameters
@NonNull Set<AppSearchBlobHandle> handles

The AppSearchBlobHandles that identifies the blobs.

Returns
@NonNull ListenableFuture<OpenBlobForReadResponse>

a response containing the readable file descriptors.

openBlobForWriteAsync

Added in 1.1.0
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<OpenBlobForWriteResponseopenBlobForWriteAsync(@NonNull Set<AppSearchBlobHandle> handles)

Opens a batch of AppSearch Blobs for writing.

A "blob" is a large binary object. It is used to store a significant amount of data that is not searchable, such as images, videos, audio files, or other binary data. Unlike other fields in AppSearch, blobs are stored as blob files on disk rather than in memory, and use android.os.ParcelFileDescriptor to read and write. This allows for efficient handling of large, non-searchable content.

Once done writing, call commitBlobAsync to commit blob files.

This call will create a empty blob file for each given AppSearchBlobHandle, and a android.os.ParcelFileDescriptor of that blob file will be returned in the OpenBlobForWriteResponse.

If the blob file is already stored in AppSearch and committed. A failed AppSearchResult with error code RESULT_ALREADY_EXISTS will be associated with the AppSearchBlobHandle.

If the blob file is already stored in AppSearch but not committed. A android.os.ParcelFileDescriptor of that blob file will be returned for continue writing.

For given duplicate AppSearchBlobHandle, the same android.os.ParcelFileDescriptor pointing to the same blob file will be returned.

Pending blob files won't be lost or auto-commit if AppSearchSession closed. Pending blob files will be stored in disk rather than memory. You can re-open AppSearchSession and re-write the pending blob files.

A committed blob file will be considered as an orphan if no GenericDocument references it. Uncommitted pending blob files and orphan blobs files will be cleaned up if they has been created for an extended period (default is 1 week).

Both pending blob files and committed blob files can be manually removed via removeBlobAsync.

The returned OpenBlobForWriteResponse must be closed after use to avoid resource leaks. Failing to close it will result in system file descriptor exhaustion.

Parameters
@NonNull Set<AppSearchBlobHandle> handles

The AppSearchBlobHandles that identifies the blobs.

Returns
@NonNull ListenableFuture<OpenBlobForWriteResponse>

a response containing the writeable file descriptors.

putAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<AppSearchBatchResult<StringVoid>> putAsync(@NonNull PutDocumentsRequest request)

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 setSchemaAsync method.

Parameters
@NonNull PutDocumentsRequest request

containing documents to be indexed.

Returns
@NonNull ListenableFuture<AppSearchBatchResult<StringVoid>>

a ListenableFuture which resolves to an AppSearchBatchResult. The keys of the returned AppSearchBatchResult are the IDs of the input documents. The values are either null if the corresponding document was successfully indexed, or a failed AppSearchResult otherwise.

removeAsync

Added in 1.1.0
abstract @NonNull ListenableFuture<AppSearchBatchResult<StringVoid>> removeAsync(@NonNull RemoveByDocumentIdRequest request)

Removes GenericDocument objects by document IDs in a namespace from the AppSearchSession database.

Removed documents will no longer be surfaced by search or getByDocumentIdAsync calls.

Once the database crosses the document count or byte usage threshold, removed documents will be deleted from disk.

Parameters
@NonNull RemoveByDocumentIdRequest request

RemoveByDocumentIdRequest with IDs in a namespace to remove from the index.

Returns
@NonNull ListenableFuture<AppSearchBatchResult<StringVoid>>

a ListenableFuture which resolves to an AppSearchBatchResult. The keys of the AppSearchBatchResult represent the input IDs from the RemoveByDocumentIdRequest object. The values are either null on success, or a failed AppSearchResult otherwise. IDs that are not found will return a failed AppSearchResult with a result code of RESULT_NOT_FOUND.

removeAsync

Added in 1.1.0