AppSearchSession

abstract void close()

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

@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<CommitBlobResponse> commitBlobAsync(@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.

abstract @NonNull ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentIdAsync(@NonNull GetByDocumentIdRequest request)

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

abstract @NonNull Features getFeatures()

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

abstract @NonNull ListenableFuture<Set<String>> getNamespacesAsync()

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

abstract @NonNull ListenableFuture<GetSchemaResponse> getSchemaAsync()

Retrieves the schema most recently successfully provided to setSchemaAsync.

abstract @NonNull ListenableFuture<StorageInfo> getStorageInfoAsync()

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.

@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<OpenBlobForReadResponse> openBlobForReadAsync(@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.

@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.BLOB_STORAGE)
@ExperimentalAppSearchApi
default @NonNull ListenableFuture<OpenBlobForWriteResponse> openBlobForWriteAsync(@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.

abstract @NonNull ListenableFuture<AppSearchBatchResult<String, Void>> 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.

abstract @NonNull ListenableFuture<AppSearchBatchResult<String, Void>> 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.