GenericDocument

protected GenericDocument(@NonNull GenericDocument document)

Creates a new GenericDocument from an existing instance.

This method should be only used by constructor of a subclass.

public static @NonNull GenericDocument fromDocumentClass(@NonNull Object document)

Converts an instance of a class annotated with \@Document into an instance of GenericDocument.

public long getCreationTimestampMillis()

Returns the creation timestamp of the GenericDocument, in milliseconds.

The value is in the currentTimeMillis time base.

public @NonNull String getId()

Returns the unique identifier of the GenericDocument.

public @NonNull String getNamespace()

Returns the namespace of the GenericDocument.

public @Nullable Object getProperty(@NonNull String path)

Retrieves the property value with the given path as Object.

A path can be a simple property name, such as those returned by getPropertyNames. It may also be a dot-delimited path through the nested document hierarchy, with nested GenericDocument properties accessed via '.' and repeated properties optionally indexed into via [n].

For example, given the following GenericDocument:

    (Message) {
        from: "sender@example.com"
        to: [{
            name: "Albert Einstein"
            email: "einstein@example.com"
          }, {
            name: "Marie Curie"
            email: "curie@example.com"
          }]
        tags: ["important", "inbox"]
        subject: "Hello"
    }

Here are some example paths and their results:

• "from" returns "sender@example.com" as a String array with one element
• "to" returns the two nested documents containing contact information as a GenericDocument array with two elements
• "to[1]" returns the second nested document containing Marie Curie's contact information as a GenericDocument array with one element
• "to[1].email" returns "curie@example.com"
• "to[100].email" returns null as this particular document does not have that many elements in its "to" array.
• "to.email" aggregates emails across all nested documents that have them, returning ["einstein@example.com", "curie@example.com"] as a String array with two elements.

If you know the expected type of the property you are retrieving, it is recommended to use one of the typed versions of this method instead, such as getPropertyString or getPropertyStringArray.

If the property was assigned as an empty array using one of the Builder#setProperty functions, this method will return an empty array. If no such property exists at all, this method returns null.

@ExperimentalAppSearchApi
public @Nullable AppSearchBlobHandle getPropertyBlobHandle(@NonNull String path)

Retrieves an AppSearchBlobHandle property by path.

See getProperty for a detailed description of the path syntax.

See openBlobForReadAsync for how to use AppSearchBlobHandle to retrieve blob data.

@ExperimentalAppSearchApi
public @Nullable AppSearchBlobHandle[] getPropertyBlobHandleArray(@NonNull String path)

Retrieves a repeated AppSearchBlobHandle[] property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyBlobHandle, this method returns null.

If it has been set via setPropertyBlobHandle to an empty AppSearchBlobHandle[], this method returns an empty AppSearchBlobHandle[].

public boolean getPropertyBoolean(@NonNull String path)

Retrieves a boolean property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable boolean[] getPropertyBooleanArray(@NonNull String path)

Retrieves a repeated boolean property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyBoolean, this method returns null.

If it has been set via setPropertyBoolean to an empty boolean[], this method returns an empty boolean[].

public @Nullable byte[] getPropertyBytes(@NonNull String path)

Retrieves a byte[] property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable byte[][] getPropertyBytesArray(@NonNull String path)

Retrieves a byte[][] property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyBytes, this method returns null.

If it has been set via setPropertyBytes to an empty byte[][], this method returns an empty byte[][].

public @Nullable GenericDocument getPropertyDocument(@NonNull String path)

Retrieves a GenericDocument property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable GenericDocument[] getPropertyDocumentArray(@NonNull String path)

Retrieves a repeated GenericDocument property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyDocument, this method returns null.

If it has been set via setPropertyDocument to an empty GenericDocument[], this method returns an empty GenericDocument[].

public double getPropertyDouble(@NonNull String path)

Retrieves a double property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable double[] getPropertyDoubleArray(@NonNull String path)

Retrieves a repeated double property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyDouble, this method returns null.

If it has been set via setPropertyDouble to an empty double[], this method returns an empty double[].

public @Nullable EmbeddingVector getPropertyEmbedding(@NonNull String path)

Retrieves an EmbeddingVector property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable EmbeddingVector[] getPropertyEmbeddingArray(@NonNull String path)

Retrieves a repeated EmbeddingVector[] property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyEmbedding, this method returns null.

If it has been set via setPropertyEmbedding to an empty EmbeddingVector[], this method returns an empty EmbeddingVector[].

public long getPropertyLong(@NonNull String path)

Retrieves a long property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable long[] getPropertyLongArray(@NonNull String path)

Retrieves a repeated long[] property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyLong, this method returns null.

If it has been set via setPropertyLong to an empty long[], this method returns an empty long[].

public @NonNull Set<String> getPropertyNames()

Returns the names of all properties defined in this document.

public @Nullable String getPropertyString(@NonNull String path)

Retrieves a String property by path.

See getProperty for a detailed description of the path syntax.

public @Nullable String[] getPropertyStringArray(@NonNull String path)

Retrieves a repeated String property by path.

See getProperty for a detailed description of the path syntax.

If the property has not been set via setPropertyString, this method returns null.

If it has been set via setPropertyString to an empty String[], this method returns an empty String[].

public @NonNull String getSchemaType()

Returns the AppSearchSchema type of the GenericDocument.

public int getScore()

Returns the score of the GenericDocument.

The score is a query-independent measure of the document's quality, relative to other GenericDocument objects of the same AppSearchSchema type.

Results may be sorted by score using setRankingStrategy. Documents with higher scores are considered better than documents with lower scores.

Any non-negative integer can be used a score.

public long getTtlMillis()

Returns the TTL (time-to-live) of the GenericDocument, in milliseconds.

The TTL is measured against getCreationTimestampMillis. At the timestamp of creationTimestampMillis + ttlMillis, measured in the currentTimeMillis time base, the document will be auto-deleted.

The default value is 0, which means the document is permanent and won't be auto-deleted until the app is uninstalled or removeAsync is called.

public @NonNull T <T> toDocumentClass(@NonNull Class<T> documentClass)

Converts this GenericDocument into an instance of the provided document class.

It is the developer's responsibility to ensure the right kind of document class is being supplied here, either by structuring the application code to ensure the document type is known, or by checking the return value of getSchemaType.

Document properties are identified by String names. Any that are found are assigned into fields of the given document class. As such, the most likely outcome of supplying the wrong document class would be an empty or partially populated result.

@ExperimentalAppSearchApi
public @NonNull T <T> toDocumentClass(
    @NonNull Class<T> documentClass,
    @NonNull DocumentClassMappingContext documentClassMappingContext
)

Converts this GenericDocument into an instance of the provided document class.

It is the developer's responsibility to ensure the right kind of document class is being supplied here, either by structuring the application code to ensure the document type is known, or by checking the return value of getSchemaType.

Document properties are identified by String names. Any that are found are assigned into fields of the given document class. As such, the most likely outcome of supplying the wrong document class would be an empty or partially populated result.

If this GenericDocument's type is recorded as a subtype of the provided documentClass, the method will find an AppSearch document class, using the provided documentClassMappingContext, that is the most concrete and assignable to documentClass, and then deserialize to that class instead. This allows for more specific and accurate deserialization of GenericDocuments. If documentClassMappingContext has information missing or we are not able to find a candidate assignable to documentClass, the method will deserialize to documentClass directly.

Assignability is determined by the programing language's type system, and which type is more concrete is determined by AppSearch's type system specified via addParentType or the annotation parameter parent.

For nested document properties, this method will be called recursively, and documentClassMappingContext will be passed down to the recursive calls of this method.

For most use cases, it is recommended to utilize getDocument instead of calling this method directly. This avoids the need to manually create a DocumentClassMappingContext.