GenericDocument


class GenericDocument


Represents a document unit.

Documents contain structured data conforming to their AppSearchSchema type. Each document is uniquely identified by a namespace and a String ID within that namespace.

Documents are constructed either by using the GenericDocument.Builder or providing an annotated Document data class.

Summary

Nested types

The builder class for GenericDocument.

Protected constructors

Creates a new GenericDocument from an existing instance.

Public functions

Boolean
equals(other: Any?)
java-static GenericDocument

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

Long

Returns the creation timestamp of the GenericDocument, in milliseconds.

String

Returns the unique identifier of the GenericDocument.

java-static Int

This function is deprecated.

This is no longer a static value, but depends on SDK version and what AppSearch implementation is being used.

String

Returns the namespace of the GenericDocument.

Any?

Retrieves the property value with the given path as Object.

Boolean

Retrieves a boolean property by path.

BooleanArray<Boolean>?

Retrieves a repeated boolean property by path.

ByteArray<Byte>?

Retrieves a byte[] property by path.

Array<ByteArray<Byte>!>?

Retrieves a byte[][] property by path.

GenericDocument?

Retrieves a GenericDocument property by path.

Array<GenericDocument!>?

Retrieves a repeated GenericDocument property by path.

Double

Retrieves a double property by path.

DoubleArray<Double>?

Retrieves a repeated double property by path.

EmbeddingVector?

Retrieves an EmbeddingVector property by path.

Array<EmbeddingVector!>?

Retrieves a repeated EmbeddingVector[] property by path.

Long

Retrieves a long property by path.

LongArray<Long>?

Retrieves a repeated long[] property by path.

(Mutable)Set<String!>

Returns the names of all properties defined in this document.

String?

Retrieves a String property by path.

Array<String!>?

Retrieves a repeated String property by path.

String

Returns the AppSearchSchema type of the GenericDocument.

Int

Returns the score of the GenericDocument.

Long

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

Int
GenericDocument.Builder<GenericDocument.Builder<Any!>!>

This function is deprecated.

This API is not compliant with API guidelines.

T
<T> toDocumentClass(documentClass: Class<T!>)

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

T
<T> toDocumentClass(
    documentClass: Class<T!>,
    documentClassMap: (Mutable)Map<String!, (Mutable)List<String!>!>?
)

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

String

Protected constructors

GenericDocument

Added in 1.1.0-alpha06
protected GenericDocument(document: GenericDocument)

Creates a new GenericDocument from an existing instance.

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

Public functions

equals

fun equals(other: Any?): Boolean

fromDocumentClass

Added in 1.1.0-alpha06
java-static fun fromDocumentClass(document: Any): GenericDocument

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

Parameters
document: Any

An instance of a class annotated with \@Document.

Returns
GenericDocument

an instance of GenericDocument produced by converting document.

Throws
androidx.appsearch.exceptions.AppSearchException

if no generated conversion class exists on the classpath for the given document class or an unexpected error occurs during conversion.

See also
GenericDocument

getCreationTimestampMillis

Added in 1.1.0-alpha06
fun getCreationTimestampMillis(): Long

Returns the creation timestamp of the GenericDocument, in milliseconds.

The value is in the currentTimeMillis time base.

getId

Added in 1.1.0-alpha06
fun getId(): String

Returns the unique identifier of the GenericDocument.

getMaxIndexedProperties

Added in 1.1.0-alpha06
Deprecated in 1.1.0-alpha06
java-static fun getMaxIndexedProperties(): Int

The maximum number of indexed properties a document can have.

Indexed properties are properties which are strings where the getIndexingType value is anything other than INDEXING_TYPE_NONE, as well as long properties where the getIndexingType value is INDEXING_TYPE_RANGE.

getNamespace

Added in 1.1.0-alpha06
fun getNamespace(): String

Returns the namespace of the GenericDocument.

getProperty

Added in 1.1.0-alpha06
fun getProperty(path: String): Any?

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.

Parameters
path: String

The path to look for.

Returns
Any?

The entry with the given path as an object or null if there is no such path. The returned object will be one of the following types: String[], long[], double[], boolean[], byte[][], GenericDocument[].

getPropertyBoolean

Added in 1.1.0-alpha06
fun getPropertyBoolean(path: String): Boolean

Retrieves a boolean property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
Boolean

The first boolean associated with the given path or default value false if there is no such value or the value is of a different type.

getPropertyBooleanArray

Added in 1.1.0-alpha06
fun getPropertyBooleanArray(path: String): BooleanArray<Boolean>?

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[].

Parameters
path: String

The path to look for.

Returns
BooleanArray<Boolean>?

The boolean[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyBytes

Added in 1.1.0-alpha06
fun getPropertyBytes(path: String): ByteArray<Byte>?

Retrieves a byte[] property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
ByteArray<Byte>?

The first byte[] associated with the given path or null if there is no such value or the value is of a different type.

getPropertyBytesArray

Added in 1.1.0-alpha06
fun getPropertyBytesArray(path: String): Array<ByteArray<Byte>!>?

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[][].

Parameters
path: String

The path to look for.

Returns
Array<ByteArray<Byte>!>?

The byte[][] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyDocument

Added in 1.1.0-alpha06
fun getPropertyDocument(path: String): GenericDocument?

Retrieves a GenericDocument property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
GenericDocument?

The first GenericDocument associated with the given path or null if there is no such value or the value is of a different type.

getPropertyDocumentArray

Added in 1.1.0-alpha06
fun getPropertyDocumentArray(path: String): Array<GenericDocument!>?

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[].

Parameters
path: String

The path to look for.

Returns
Array<GenericDocument!>?

The GenericDocument[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyDouble

Added in 1.1.0-alpha06
fun getPropertyDouble(path: String): Double

Retrieves a double property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
Double

The first double associated with the given path or default value 0.0 if there is no such value or the value is of a different type.

getPropertyDoubleArray

Added in 1.1.0-alpha06
fun getPropertyDoubleArray(path: String): DoubleArray<Double>?

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[].

Parameters
path: String

The path to look for.

Returns
DoubleArray<Double>?

The double[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyEmbedding

Added in 1.1.0-alpha06
fun getPropertyEmbedding(path: String): EmbeddingVector?

Retrieves an EmbeddingVector property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
EmbeddingVector?

The first EmbeddingVector[] associated with the given path or null if there is no such value or the value is of a different type.

getPropertyEmbeddingArray

Added in 1.1.0-alpha06
fun getPropertyEmbeddingArray(path: String): Array<EmbeddingVector!>?

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[].

Parameters
path: String

The path to look for.

Returns
Array<EmbeddingVector!>?

The EmbeddingVector[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyLong

Added in 1.1.0-alpha06
fun getPropertyLong(path: String): Long

Retrieves a long property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
Long

The first long associated with the given path or default value 0 if there is no such value or the value is of a different type.

getPropertyLongArray

Added in 1.1.0-alpha06
fun getPropertyLongArray(path: String): LongArray<Long>?

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[].

Parameters
path: String

The path to look for.

Returns
LongArray<Long>?

The long[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyNames

Added in 1.1.0-alpha06
fun getPropertyNames(): (Mutable)Set<String!>

Returns the names of all properties defined in this document.

getPropertyString

Added in 1.1.0-alpha06
fun getPropertyString(path: String): String?

Retrieves a String property by path.

See getProperty for a detailed description of the path syntax.

Parameters
path: String

The path to look for.

Returns
String?

The first String associated with the given path or null if there is no such value or the value is of a different type.

getPropertyStringArray

Added in 1.1.0-alpha06
fun getPropertyStringArray(path: String): Array<String!>?

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[].

Parameters
path: String

The path to look for.

Returns
Array<String!>?

The String[] associated with the given path, or null if no value is set or the value is of a different type.

getSchemaType

Added in 1.1.0-alpha06
fun getSchemaType(): String

Returns the AppSearchSchema type of the GenericDocument.

getScore

Added in 1.1.0-alpha06
fun getScore(): Int

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.

getTtlMillis

Added in 1.1.0-alpha06
fun getTtlMillis(): Long

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.

hashCode

fun hashCode(): Int

toBuilder

Added in 1.1.0-alpha06
Deprecated in 1.1.0-alpha06
fun toBuilder(): GenericDocument.Builder<GenericDocument.Builder<Any!>!>

Copies the contents of this GenericDocument into a new GenericDocument.Builder.

The returned builder is a deep copy whose data is separate from this document.

toDocumentClass

Added in 1.1.0-alpha06
fun <T> toDocumentClass(documentClass: Class<T!>): T

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.

Parameters
documentClass: Class<T!>

a class annotated with Document

Returns
T

an instance of the document class after being converted from a GenericDocument

Throws
androidx.appsearch.exceptions.AppSearchException

if no factory for this document class could be found on the classpath.

toDocumentClass

Added in 1.1.0-alpha06
fun <T> toDocumentClass(
    documentClass: Class<T!>,
    documentClassMap: (Mutable)Map<String!, (Mutable)List<String!>!>?
): T

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 documentClassMap, 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 documentClassMap is null 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 documentClassMap will be passed down to the recursive calls of this method.

Parameters
documentClass: Class<T!>

a class annotated with Document

documentClassMap: (Mutable)Map<String!, (Mutable)List<String!>!>?

a map from AppSearch's type name specified by name to the list of the fully qualified names of the corresponding document classes. In most cases, passing the value returned by getGlobalMap will be sufficient.

Returns
T

an instance of the document class after being converted from a GenericDocument

Throws
androidx.appsearch.exceptions.AppSearchException

if no factory for this document class could be found on the classpath.

toString

fun toString(): String