AppSearchSession

public interface AppSearchSession
implements Closeable

androidx.appsearch.app.AppSearchSession


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.createSearchSession() or PlatformStorage.createSearchSession().

All implementations of this interface must be thread safe.

Summary

Public methods

abstract void close()

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

abstract ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentId(GetByDocumentIdRequest request)

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

abstract ListenableFuture<Set<String>> getNamespaces()

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

abstract ListenableFuture<GetSchemaResponse> getSchema()

Retrieves the schema most recently successfully provided to setSchema(SetSchemaRequest).

abstract ListenableFuture<StorageInfo> getStorageInfo()

Gets the storage info for this AppSearchSession database.

abstract ListenableFuture<AppSearchBatchResult<String, Void>> put(PutDocumentsRequest request)

Indexes documents into the AppSearchSession database.

abstract ListenableFuture<Void> remove(String queryExpression, SearchSpec searchSpec)

Removes GenericDocuments from the index by Query.

abstract ListenableFuture<AppSearchBatchResult<String, Void>> remove(RemoveByDocumentIdRequest request)

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

abstract ListenableFuture<Void> reportUsage(ReportUsageRequest request)

Reports usage of a particular document by namespace and ID.

abstract ListenableFuture<Void> requestFlush()

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

abstract SearchResults search(String queryExpression, SearchSpec searchSpec)

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

abstract ListenableFuture<SetSchemaResponse> setSchema(SetSchemaRequest request)

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

Inherited methods

Public methods

close

public abstract void close ()

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

getByDocumentId

public abstract ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentId (GetByDocumentIdRequest request)

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

Parameters
request GetByDocumentIdRequest: a request containing a namespace and IDs to get documents for.

Returns
ListenableFuture<AppSearchBatchResult<String, GenericDocument>> 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: AppSearchResult.RESULT_NOT_FOUND.

getNamespaces

public abstract ListenableFuture<Set<String>> getNamespaces ()

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

Returns
ListenableFuture<Set<String>> The pending result of performing this operation.

getSchema

public abstract ListenableFuture<GetSchemaResponse> getSchema ()

Retrieves the schema most recently successfully provided to setSchema(SetSchemaRequest).

Returns
ListenableFuture<GetSchemaResponse> The pending GetSchemaResponse of performing this operation.

getStorageInfo

public abstract ListenableFuture<StorageInfo> getStorageInfo ()

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
ListenableFuture<StorageInfo> a ListenableFuture which resolves to a StorageInfo object.

put

public abstract ListenableFuture<AppSearchBatchResult<String, Void>> put (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 setSchema(SetSchemaRequest) method.

Parameters
request PutDocumentsRequest: containing documents to be indexed.

Returns
ListenableFuture<AppSearchBatchResult<String, Void>> 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.

remove

public abstract ListenableFuture<Void> remove (String queryExpression, 
                SearchSpec searchSpec)

Removes GenericDocuments from the index by Query. Documents will be removed if they match the queryExpression in given namespaces and schemaTypes which is set via SearchSpec.Builder.addFilterNamespaces(String...) and SearchSpec.Builder.addFilterSchemas(String...).

An empty queryExpression matches all documents.

An empty set of namespaces or schemaTypes matches all namespaces or schemaTypes in the current database.

Parameters
queryExpression String: Query String to search.

searchSpec SearchSpec: Spec containing schemaTypes, namespaces and query expression indicates how document will be removed. All specific about how to scoring, ordering, snippeting and resulting will be ignored.

Returns
ListenableFuture<Void> The pending result of performing this operation.

remove

public abstract ListenableFuture<AppSearchBatchResult<String, Void>> remove (RemoveByDocumentIdRequest request)

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

Removed documents will no longer be surfaced by search(String, SearchSpec) or getByDocumentId(GetByDocumentIdRequest) calls.

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

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

Returns
ListenableFuture<AppSearchBatchResult<String, Void>> 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 AppSearchResult.RESULT_NOT_FOUND.

reportUsage

public abstract ListenableFuture<Void> reportUsage (ReportUsageRequest request)

Reports usage of a particular document by namespace and ID.

A usage report represents an event in which a user interacted with or viewed a document.

For each call to reportUsage(ReportUsageRequest), AppSearch updates usage count and usage recency metrics for that particular document. These metrics are used for ordering search(String, SearchSpec) results by the SearchSpec.RANKING_STRATEGY_USAGE_COUNT and SearchSpec.RANKING_STRATEGY_USAGE_LAST_USED_TIMESTAMP ranking strategies.

Reporting usage of a document is optional.

Parameters
request ReportUsageRequest: The usage reporting request.

Returns
ListenableFuture<Void> The pending result of performing this operation which resolves to null on success.

requestFlush

public abstract ListenableFuture<Void> requestFlush ()

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

The request is not guaranteed to be handled and may be ignored by some implementations of AppSearchSession.

Returns
ListenableFuture<Void> The pending result of performing this operation. AppSearchException with AppSearchResult.RESULT_INTERNAL_ERROR will be set to the future if we hit error when save to disk.

search

public abstract SearchResults search (String queryExpression, 
                SearchSpec searchSpec)

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

Query strings can be empty, contain one term with no operators, or contain multiple terms and operators.

For query strings that are empty, all documents that match the SearchSpec will be returned.

For query strings with a single term and no operators, documents that match the provided query string and SearchSpec will be returned.

The following operators are supported:

  • AND (implicit)

    AND is an operator that matches documents that contain all provided terms.

    NOTE: A space between terms is treated as an "AND" operator. Explicitly including "AND" in a query string will treat "AND" as a term, returning documents that also contain "AND".

    Example: "apple AND banana" matches documents that contain the terms "apple", "and", "banana".

    Example: "apple banana" matches documents that contain both "apple" and "banana".

    Example: "apple banana cherry" matches documents that contain "apple", "banana", and "cherry".

  • OR

    OR is an operator that matches documents that contain any provided term.

    Example: "apple OR banana" matches documents that contain either "apple" or "banana".

    Example: "apple OR banana OR cherry" matches documents that contain any of "apple", "banana", or "cherry".

  • Exclusion (-)

    Exclusion (-) is an operator that matches documents that do not contain the provided term.

    Example: "-apple" matches documents that do not contain "apple".

  • Grouped Terms

    For queries that require multiple operators and terms, terms can be grouped into subqueries. Subqueries are contained within an open "(" and close ")" parenthesis.

    Example: "(donut OR bagel) (coffee OR tea)" matches documents that contain either "donut" or "bagel" and either "coffee" or "tea".

  • Property Restricts

    For queries that require a term to match a specific AppSearchSchema property of a document, a ":" must be included between the property name and the term.

    Example: "subject:important" matches documents that contain the term "important" in the "subject" property.

Additional search specifications, such as filtering by AppSearchSchema type or adding projection, can be set by calling the corresponding SearchSpec.Builder setter.

This method is lightweight. The heavy work will be done in SearchResults.getNextPage().

Parameters
queryExpression String: query string to search.

searchSpec SearchSpec: spec for setting document filters, adding projection, setting term match type, etc.

Returns
SearchResults a SearchResults object for retrieved matched documents.

setSchema

public abstract ListenableFuture<SetSchemaResponse> setSchema (SetSchemaRequest request)

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

Upon creating an AppSearchSession, setSchema(SetSchemaRequest) should be called. If the schema needs to be updated, or it has not been previously set, then the provided schema will be saved and persisted to disk. Otherwise, setSchema(SetSchemaRequest) is handled efficiently as a no-op call.

Parameters
request SetSchemaRequest: the schema to set or update the AppSearch database to.

Returns
ListenableFuture<SetSchemaResponse> a ListenableFuture which resolves to a SetSchemaResponse object.