Client class for AppSearch. An instance of this class can be created using AppSearch
to
provide a connection to a single AppSearch database.
Public Method Summary
abstract Task<Void> |
close()
Closes the
AppSearchClient
to persist all schema and document updates, additions, and deletes to disk.
|
abstract Task<AppSearchBatchResult<String, GenericDocument>> |
getByDocumentId(GetByDocumentIdRequest
getByDocumentIdRequest, String
databaseName)
Gets
GenericDocument
objects by document IDs in a namespace from the specified database.
|
abstract Task<Set<String>> |
getNamespaces(String
databaseName)
Retrieves the set of all namespaces in the target database with at least one
document.
|
abstract Task<GetSchemaResponse> |
getSchema(String
databaseName)
Retrieves the schema most recently successfully provided to
setSchema(SetSchemaRequest, String) .
|
abstract Task<StorageInfo> | |
abstract Task<AppSearchBatchResult<String, Void>> |
put(PutDocumentsRequest
putDocumentsRequest, String
databaseName)
Indexes documents into the specified database.
|
abstract Task<Void> |
remove(String
queryExpression, SearchSpec
searchSpec, String
databaseName)
Removes
GenericDocument s
from the index by Query.
|
abstract Task<AppSearchBatchResult<String, Void>> |
remove(RemoveByDocumentIdRequest
removeByDocumentIdRequest, String
databaseName)
Removes
GenericDocument
objects by document IDs in a namespace from the AppSearchClient
database.
|
abstract Task<Void> |
reportUsage(ReportUsageRequest
reportUsageRequest, String
databaseName)
Reports usage of a particular document by namespace and ID.
|
abstract SearchResults |
search(String
queryExpression, SearchSpec
searchSpec, String
databaseName)
Retrieves documents from the specified database that match a given query string
and type of search provided.
|
abstract Task<List<SearchSuggestionResult>> |
searchSuggestion(String
suggestionQueryExpression, SearchSuggestionSpec
searchSuggestionSpec, String
databaseName)
Retrieves suggested Strings that could be used as
queryExpression
in
search(String, SearchSpec, String) API.
|
abstract Task<SetSchemaResponse> |
setSchema(SetSchemaRequest
setSchemaRequest, String
databaseName)
Sets the schema that represents the organizational structure of data within the
Google Play services AppSearch database.
|
Public Methods
public abstract Task<Void> close ()
Closes the AppSearchClient
to persist all schema and document updates, additions, and deletes to disk.
public abstract Task<AppSearchBatchResult<String, GenericDocument>> getByDocumentId (GetByDocumentIdRequest getByDocumentIdRequest, String databaseName)
Gets GenericDocument
objects by document IDs in a namespace from the specified database.
Parameters
getByDocumentIdRequest | a request containing a namespace and IDs to get documents for. |
---|---|
databaseName | the name of the database requested documents belong to. |
public abstract Task<Set<String>> getNamespaces (String databaseName)
Retrieves the set of all namespaces in the target database with at least one document.
Parameters
databaseName | the name of the database all namespaces belong to. |
---|
public abstract Task<GetSchemaResponse> getSchema (String databaseName)
Retrieves the schema most recently successfully provided to
setSchema(SetSchemaRequest, String)
.
Parameters
databaseName | the name of the database retrieved schema belongs to. |
---|
public abstract Task<StorageInfo> getStorageInfo (String databaseName)
Gets the storage info for the specified database.
This may take time proportional to the number of documents and may be inefficient to call repeatedly.
Parameters
databaseName | the name of the database. |
---|
public abstract Task<AppSearchBatchResult<String, Void>> put (PutDocumentsRequest putDocumentsRequest, String databaseName)
Indexes documents into the specified database.
Each GenericDocument
object must have a schemaType
field set to an AppSearchSchema
type that has been previously registered by calling the
setSchema(SetSchemaRequest, String)
method.
Parameters
putDocumentsRequest | containing documents to be indexed. |
---|---|
databaseName | the name of the database documents should be indexed into. |
public abstract Task<Void> remove (String queryExpression, SearchSpec searchSpec, String databaseName)
Removes GenericDocument
s
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 specified database.
Parameters
queryExpression | Query String to search. |
---|---|
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. |
databaseName | the name of the database this remove targets. |
public abstract Task<AppSearchBatchResult<String, Void>> remove (RemoveByDocumentIdRequest removeByDocumentIdRequest, String databaseName)
Removes GenericDocument
objects by document IDs in a namespace from the AppSearchClient
database.
Removed documents will no longer be surfaced by
search(String, SearchSpec, String)
or
getByDocumentId(GetByDocumentIdRequest, String)
calls.
Once the database crosses the document count or byte usage threshold, removed documents will be deleted from disk.
Parameters
removeByDocumentIdRequest |
RemoveByDocumentIdRequest with IDs in a namespace to remove from the
index. |
---|---|
databaseName | the name of the database this remove targets. |
public abstract Task<Void> reportUsage (ReportUsageRequest reportUsageRequest, String databaseName)
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, String)
, Google Play services AppSearch
updates usage count and usage recency metrics for that particular document. These
metrics are used for ordering
search(String, SearchSpec, String)
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
reportUsageRequest | The usage reporting request. |
---|---|
databaseName | the name of the database the reported documents belong to. |
public abstract SearchResults search (String queryExpression, SearchSpec searchSpec, String databaseName)
Retrieves documents from the specified database 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 | query string to search. |
---|---|
searchSpec | spec for setting document filters, adding projection, setting term match type, etc. |
databaseName | the name of the database retrieved documents belong to. |
Returns
- a
SearchResults
object for retrieved matched documents.
public abstract Task<List<SearchSuggestionResult>> searchSuggestion (String suggestionQueryExpression, SearchSuggestionSpec searchSuggestionSpec, String databaseName)
Retrieves suggested Strings that could be used as queryExpression
in
search(String, SearchSpec, String)
API.
The suggestionQueryExpression
can contain one term with no operators,
or contain multiple terms and operators. Operators will be considered as a normal term.
Please see the operator examples below. The suggestionQueryExpression
must
end with a valid term, the suggestions are generated based on the last term. If the
input suggestionQueryExpression
doesn't have a valid token, AppSearch will
return an empty result list. Please see the invalid examples below.
Example: if there are following documents with content stored in AppSearch.
- document1: "term1"
- document2: "term1 term2"
- document3: "term1 term2 term3"
- document4: "org"
Search suggestions with the single term suggestionQueryExpression
"t",
the suggested results are:
- "term1" - Use it to be queryExpression in
search(String, SearchSpec, String)
could get 3SearchResult
s, which contains document 1, 2 and 3. - "term2" - Use it to be queryExpression in
search(String, SearchSpec, String)
could get 2SearchResult
s, which contains document 2 and 3. - "term3" - Use it to be queryExpression in
search(String, SearchSpec, String)
could get 1SearchResult
, which contains document 3.
Search suggestions with the multiple term suggestionQueryExpression
"org t", the suggested result will be "org term1" - The last token is completed by the
suggested String.
Operators in
search(String, SearchSpec, String)
are supported.
NOTE: Exclusion and Grouped Terms in the last term is not supported.
example: "apple -f": This Api will throw an
AppSearchException
with
AppSearchResult.RESULT_INVALID_ARGUMENT
.
example: "apple (f)": This Api will return an empty results.
Invalid example: All these input suggestionQueryExpression
don't have a
valid last token, AppSearch will return an empty result list.
- "" - Empty
suggestionQueryExpression
. - "(f)" - Ending in a closed brackets.
- "f:" - Ending in an operator.
- "f " - Ending in trailing space.
Parameters
suggestionQueryExpression | the non empty query string to search suggestions |
---|---|
searchSuggestionSpec | spec for setting document filters |
databaseName |
See Also
public abstract Task<SetSchemaResponse> setSchema (SetSchemaRequest setSchemaRequest, String databaseName)
Sets the schema that represents the organizational structure of data within the Google Play services AppSearch database.
Upon creating an AppSearchClient
,
setSchema(SetSchemaRequest, String)
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, String)
is handled efficiently as a no-op
call.
Parameters
setSchemaRequest | the schema to set or update the AppSearch database to. |
---|---|
databaseName | the name of the target database. |