Collection

expect class Collection : AutoCloseable(source)

A Collection is a container for documents similar to a table in a relational database. Collections are grouped into namespaces called scopes and have a unique name within that scope.

Every database contains a default collection named "_default" (the constant Collection.DEFAULT_NAME) in the default scope (also named "_default", the constant Scope.DEFAULT_NAME)

While creating a new collection requires the name of the collection and the name of its scope, there are convenience methods that take only the name of the collection and create the collection in the default scope.

The naming rules for collections and scopes are as follows:

Must be between 1 and 251 characters in length.
Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.
Cannot start with _ or %.
Both scope and collection names are case-sensitive.

Collection objects are only valid during the time the database that contains them is open. An attempt to use a collection that belongs to a closed database will throw an IllegalStateException. An application can hold references to multiple instances of a single database. Under these circumstances, it is possible that a collection will be deleted in one instance before an attempt to use it in another. Such an attempt will also cause an IllegalStateException to be thrown.

Collections are AutoCloseable. While garbage collection will manage them correctly, developers are strongly encouraged to use them in try-with-resources blocks or to close them explicitly, after use.

actual class Collection : DelegatedClass<<Error class: unknown class>> , AutoCloseable(source)

actual class Collection : AutoCloseable(source)

Types

Companion

expect object Companion

actual object Companion

Properties

count

expect val count: Long

The number of documents in the collection.

actual val count: Long

database

expect val database: Database

Database

actual val database: Database

fullName

expect val fullName: String

The collection name, prefixed by scope: "scope.collection"

actual val fullName: String

indexes

expect val indexes: Set<String>

Get a list of the names of indices in the collection.

actual val indexes: Set<String>

name

expect val name: String

The collection name

actual val name: String

scope

expect val scope: Scope

Scope

actual val scope: Scope

Functions

addChangeListener

expect fun addChangeListener(listener: CollectionChangeListener): ListenerToken

expect fun addChangeListener(context: CoroutineContext, listener: CollectionChangeSuspendListener): ListenerToken

Add a change listener to listen to change events occurring to any documents in the collection. To remove the listener, call remove() function on the returned listener token.

expect fun addChangeListener(scope: CoroutineScope, listener: CollectionChangeSuspendListener)

Add a change listener to listen to change events occurring to any documents in the collection.

actual fun addChangeListener(listener: CollectionChangeListener): ListenerToken

actual fun addChangeListener(context: CoroutineContext, listener: CollectionChangeSuspendListener): ListenerToken

actual fun addChangeListener(scope: CoroutineScope, listener: CollectionChangeSuspendListener)

actual fun addChangeListener(listener: CollectionChangeListener): ListenerToken

actual fun addChangeListener(context: CoroutineContext, listener: CollectionChangeSuspendListener): ListenerToken

actual fun addChangeListener(scope: CoroutineScope, listener: CollectionChangeSuspendListener)

addDocumentChangeListener

expect fun addDocumentChangeListener(id: String, listener: DocumentChangeListener): ListenerToken

Add a change listener to listen to change events occurring to a document of the given document id. To remove the listener, call remove() function on the returned listener token.

expect fun addDocumentChangeListener(id: String, context: CoroutineContext, listener: DocumentChangeSuspendListener): ListenerToken

expect fun addDocumentChangeListener(id: String, scope: CoroutineScope, listener: DocumentChangeSuspendListener)

Add a change listener to listen to change events occurring to a document of the given document id.

actual fun addDocumentChangeListener(id: String, listener: DocumentChangeListener): ListenerToken

actual fun addDocumentChangeListener(id: String, context: CoroutineContext, listener: DocumentChangeSuspendListener): ListenerToken

actual fun addDocumentChangeListener(id: String, scope: CoroutineScope, listener: DocumentChangeSuspendListener)

actual fun addDocumentChangeListener(id: String, listener: DocumentChangeListener): ListenerToken

actual fun addDocumentChangeListener(id: String, context: CoroutineContext, listener: DocumentChangeSuspendListener): ListenerToken

actual fun addDocumentChangeListener(id: String, scope: CoroutineScope, listener: DocumentChangeSuspendListener)

expect open override fun close()

actual open override fun close()

collectionChangeFlow

fun Collection.collectionChangeFlow(coroutineContext: CoroutineContext? = null): Flow<CollectionChange>

A Flow of Collection changes.

createIndex

expect fun createIndex(name: String, index: Index)

expect fun createIndex(name: String, config: IndexConfiguration)

Add an index to the collection.

actual fun createIndex(name: String, index: Index)

actual fun createIndex(name: String, config: IndexConfiguration)

actual fun createIndex(name: String, index: Index)

actual fun createIndex(name: String, config: IndexConfiguration)

delete

expect fun delete(document: Document)

Delete a document from the collection. The default concurrency control, lastWriteWins, will be used when there is conflict during delete. If the document doesn't exist in the collection, the NotFound error will be thrown.

expect fun delete(document: Document, concurrencyControl: ConcurrencyControl): Boolean

Delete a document from the collection with a specified concurrency control. When specifying the failOnConflict concurrency control, and conflict occurred, the delete operation will fail with 'false' value returned.

actual fun delete(document: Document)

actual fun delete(document: Document, concurrencyControl: ConcurrencyControl): Boolean

deleteIndex

expect fun deleteIndex(name: String)

Delete the named index from the collection.

actual fun deleteIndex(name: String)

documentChangeFlow

fun Collection.documentChangeFlow(documentId: String, coroutineContext: CoroutineContext? = null): Flow<DocumentChange>

A Flow of document changes

equals

open operator override fun equals(other: Any?): Boolean

get

operator fun Collection.get(key: String): DocumentFragment

Gets document fragment object by the given document ID.

getDocument

expect fun getDocument(id: String): Document?

Gets an existing Document object with the given ID. If the document with the given ID doesn't exist in the collection, the value returned will be null.

actual fun getDocument(id: String): Document?

getDocumentExpiration

expect fun getDocumentExpiration(id: String): Instant?

Get the expiration date set to the document of the given id.

actual fun getDocumentExpiration(id: String): Instant?

hashCode

open override fun hashCode(): Int

purge

expect fun purge(document: Document)

When purging a document, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

expect fun purge(id: String)

Purge a document by id from the collection. If the document doesn't exist in the collection, the NotFound error will be thrown.

actual fun purge(document: Document)

actual fun purge(id: String)

actual fun purge(document: Document)

actual fun purge(id: String)

save

expect fun save(document: MutableDocument)

Save a document into the collection. The default concurrency control, lastWriteWins, will be used when there is conflict during save.

expect fun save(document: MutableDocument, concurrencyControl: ConcurrencyControl): Boolean

Save a document into the collection with a specified concurrency control. When specifying the failOnConflict concurrency control, and conflict occurred, the save operation will fail with 'false' value returned. When saving a document that already belongs to a collection, the collection instance of the document and this collection instance must be the same, otherwise, the InvalidParameter error will be thrown.

expect fun save(document: MutableDocument, conflictHandler: ConflictHandler): Boolean

Save a document into the collection with a specified conflict handler. The specified conflict handler will be called if there is conflict during save. If the conflict handler returns 'false', the save operation will be canceled with 'false' value returned.

actual fun save(document: MutableDocument)

actual fun save(document: MutableDocument, conflictHandler: ConflictHandler): Boolean

actual fun save(document: MutableDocument)

actual fun save(document: MutableDocument, concurrencyControl: ConcurrencyControl): Boolean

actual fun save(document: MutableDocument, conflictHandler: ConflictHandler): Boolean

setDocumentExpiration

expect fun setDocumentExpiration(id: String, expiration: Instant?)

Set an expiration date to the document of the given id. Setting a nil date will clear the expiration.

actual fun setDocumentExpiration(id: String, expiration: Instant?)

toString

open override fun toString(): String