public final class

PutDocumentsRequest.Builder

extends java.lang.Object

 java.lang.Object

↳androidx.appsearch.app.PutDocumentsRequest.Builder

Overview

Builder for PutDocumentsRequest objects.

Summary

Constructors
publicBuilder()

Methods
public PutDocumentsRequest.BuilderaddDocuments(java.util.Collection<java.lang.Object> documents)

Adds a collection of annotated Document documents to the request.

public PutDocumentsRequest.BuilderaddDocuments(java.lang.Object documents[])

Adds one or more annotated Document documents to the request.

public PutDocumentsRequest.BuilderaddGenericDocuments(java.util.Collection<GenericDocument> documents)

Adds a collection of GenericDocument objects to the request.

public PutDocumentsRequest.BuilderaddGenericDocuments(GenericDocument documents[])

Adds one or more GenericDocument objects to the request.

public PutDocumentsRequest.BuilderaddTakenActionGenericDocuments(java.util.Collection<GenericDocument> takenActionGenericDocuments)

Adds a collection of GenericDocument objects containing taken action metrics to the request.

public PutDocumentsRequest.BuilderaddTakenActionGenericDocuments(GenericDocument takenActionGenericDocuments[])

Adds one or more GenericDocument objects containing taken action metrics to the request.

public PutDocumentsRequest.BuilderaddTakenActions(java.util.Collection<TakenAction> takenActions)

Adds a collection of TakenAction objects to the request.

public PutDocumentsRequest.BuilderaddTakenActions(TakenAction takenActions[])

Adds one or more TakenAction objects to the request.

public PutDocumentsRequestbuild()

Creates a new PutDocumentsRequest object.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

public Builder()

Methods

public PutDocumentsRequest.Builder addGenericDocuments(GenericDocument documents[])

Adds one or more GenericDocument objects to the request.

public PutDocumentsRequest.Builder addGenericDocuments(java.util.Collection<GenericDocument> documents)

Adds a collection of GenericDocument objects to the request.

public PutDocumentsRequest.Builder addDocuments(java.lang.Object documents[])

Adds one or more annotated Document documents to the request.

Parameters:

documents: annotated Document documents.

public PutDocumentsRequest.Builder addDocuments(java.util.Collection<java.lang.Object> documents)

Adds a collection of annotated Document documents to the request.

Parameters:

documents: annotated Document documents.

public PutDocumentsRequest.Builder addTakenActions(TakenAction takenActions[])

Adds one or more TakenAction objects to the request.

Clients can construct TakenAction documents to report the user's actions on search results, and these actions can be used as signals to boost result ranking in future search requests. See TakenAction for more details.

Clients should report search and click actions together sorted by TakenAction.getActionTimestampMillis() in chronological order.

For example, if there are 2 search actions, with 1 click action associated with the first and 2 click actions associated with the second, then clients should report [searchAction1, clickAction1, searchAction2, clickAction2, clickAction3].

Certain anonymized information about actions reported using this API may be uploaded using statsd and may be used to improve the quality of the search algorithms. Most of the information in this class is already non-identifiable, such as durations and its position in the result set. Identifiable information which you choose to provide, such as the query string, will be anonymized using techniques like Federated Analytics to ensure only the most frequently searched terms across the whole user population are retained and available for study.

You can alternatively use the PutDocumentsRequest.Builder.addDocuments(Object...) API with TakenAction document to retain the benefits of joining and using it on-device, without triggering any of the anonymized stats uploading described above.

Parameters:

takenActions: one or more TakenAction objects.

public PutDocumentsRequest.Builder addTakenActions(java.util.Collection<TakenAction> takenActions)

Adds a collection of TakenAction objects to the request.

Parameters:

takenActions: a collection of TakenAction objects.

See also: PutDocumentsRequest.Builder.addTakenActions(TakenAction...)

public PutDocumentsRequest.Builder addTakenActionGenericDocuments(GenericDocument takenActionGenericDocuments[])

Adds one or more GenericDocument objects containing taken action metrics to the request.

It is recommended to use taken action document classes in Jetpack library to construct taken action documents.

The document creation timestamp of the GenericDocument should be set to the actual action timestamp via GenericDocument.Builder.setCreationTimestampMillis(long).

Clients should report search and click actions together sorted by GenericDocument.getCreationTimestampMillis() in chronological order.

For example, if there are 2 search actions, with 1 click action associated with the first and 2 click actions associated with the second, then clients should report [searchAction1, clickAction1, searchAction2, clickAction2, clickAction3].

Different types of taken actions and metrics to be collected by AppSearch:

  • Search action
    • actionType: LONG, the enum value of the action type.

      Requires to be 1 for search actions.

    • query: STRING, the user-entered search input (without any operators or rewriting).
    • fetchedResultCount: LONG, the number of SearchResult documents fetched from AppSearch in this search action.
  • Click action
    • actionType: LONG, the enum value of the action type.

      Requires to be 2 for click actions.

    • query: STRING, the user-entered search input (without any operators or rewriting) that yielded the SearchResult on which the user took action.
    • referencedQualifiedId: STRING, the qualified id of the SearchResult document that the user takes action on.

      A qualified id is a string generated by package, database, namespace, and document id. See DocumentIdUtil.createQualifiedId(String, String, GenericDocument) for more details.

    • resultRankInBlock: LONG, the rank of the SearchResult document among the user-defined block.

      The client can define its own custom definition for block, for example, corpus name, group, etc.

      For example, a client defines the block as corpus, and AppSearch returns 5 documents with corpus = ["corpus1", "corpus1", "corpus2", "corpus3", "corpus2"]. Then the block ranks of them = [1, 2, 1, 1, 2].

      If the client is not presenting the results in multiple blocks, they should set this value to match resultRankGlobal.

    • resultRankGlobal: LONG, the global rank of the SearchResult document.

      Global rank reflects the order of SearchResult documents returned by AppSearch.

      For example, AppSearch returns 2 pages with 10 SearchResult documents for each page. Then the global ranks of them will be 1 to 10 for the first page, and 11 to 20 for the second page.

    • timeStayOnResultMillis: LONG, the time in milliseconds that user stays on the SearchResult document after clicking it.

Certain anonymized information about actions reported using this API may be uploaded using statsd and may be used to improve the quality of the search algorithms. Most of the information in this class is already non-identifiable, such as durations and its position in the result set. Identifiable information which you choose to provide, such as the query string, will be anonymized using techniques like Federated Analytics to ensure only the most frequently searched terms across the whole user population are retained and available for study.

You can alternatively use the PutDocumentsRequest.Builder.addGenericDocuments(GenericDocument...) API to retain the benefits of joining and using it on-device, without triggering any of the anonymized stats uploading described above.

Parameters:

takenActionGenericDocuments: one or more GenericDocument objects containing taken action metric fields.

public PutDocumentsRequest.Builder addTakenActionGenericDocuments(java.util.Collection<GenericDocument> takenActionGenericDocuments)

Adds a collection of GenericDocument objects containing taken action metrics to the request.

Parameters:

takenActionGenericDocuments: a collection of GenericDocument objects containing taken action metric fields.

See also: PutDocumentsRequest.Builder.addTakenActionGenericDocuments(GenericDocument...)

public PutDocumentsRequest build()

Creates a new PutDocumentsRequest object.