Collection class abstract interface

A container for Documents.

A collection can be thought as a table in the relational database. Each collection belongs to a Scope which is simply a namespace, and has a name which is unique within its Scope.

When a new Database is created, a default collection named _default will be automatically created. The default collection is created under the default scope named _default. The name of the default collection and scope can be referenced by using Collection.defaultName and Scope.defaultName constant.

Note: The default collection cannot be deleted.

When creating a new collection, the collection name, and the scope name are required. The naming rules of 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.

Lifecycle

A collection and its reference remain valid until either the database is closed or the collection itself is deleted. Once deleted Collection will throw a DatabaseException with the DatabaseErrorCode.notOpen code when accessing its APIs.

Legacy Database and API

When opening a pre-collection database, the existing documents and indexes in the database will be automatically migrated to the default collection.

Any pre-collection database APIs that refer to documents, listeners, and indexes without specifying a collection such as Database.document will implicitly operate on the default collection. In other words, they behave exactly the way they used to, but collection-aware code should avoid them and use the new collection APIs instead. These legacy APIs are deprecated and will be removed eventually.

Implementers

Properties

count FutureOr<int>
The total number of documents in this collection.
no setter
hashCode int
The hash code for this object.
no setterinherited
indexes FutureOr<List<String>>
The names of all existing indexes for this collection.
no setter
name String
The name of this collection.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
scope Scope
The Scope this collection belongs to.
no setter

Methods

addChangeListener(CollectionChangeListener listener) FutureOr<ListenerToken>
Adds a listener to be notified of all changes to Documents in this collection.
addDocumentChangeListener(String id, DocumentChangeListener listener) FutureOr<ListenerToken>
Adds a listener to be notified of changes to the Document with the given id.
changes() Stream<CollectionChange>
Returns a Stream to be notified of all changes to Documents in this collection.
createIndex(String name, Index index) FutureOr<void>
Creates a value or full-text search index with the given name for the documents in this collection.
deleteDocument(Document document, [ConcurrencyControl concurrencyControl = ConcurrencyControl.lastWriteWins]) FutureOr<bool>
Deletes a document from this collection, resolving conflicts through ConcurrencyControl.
deleteIndex(String name) FutureOr<void>
Deletes the Index of the given name.
document(String id) FutureOr<Document?>
Returns the Document with the given id, if it exists.
documentChanges(String id) Stream<DocumentChange>
Returns a Stream to be notified of changes to the Document with the given id.
getDocumentExpiration(String id) FutureOr<DateTime?>
Gets the expiration date of a Document by its id, if it exists.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
purgeDocument(Document document) FutureOr<void>
Purges a document from this collection.
purgeDocumentById(String id) FutureOr<void>
Purges a Document from this collection by its id.
removeChangeListener(ListenerToken token) FutureOr<void>
Removes a previously added change listener.
saveDocument(MutableDocument document, [ConcurrencyControl concurrencyControl = ConcurrencyControl.lastWriteWins]) FutureOr<bool>
Saves a document to this collection, resolving conflicts through ConcurrencyControl.
saveDocumentWithConflictHandler(MutableDocument document, SaveConflictHandler conflictHandler) FutureOr<bool>
Saves a document to this collection, resolving conflicts with a conflictHandler.
setDocumentExpiration(String id, DateTime? expiration) FutureOr<void>
Sets an expiration date for a Document by its id.
toString() String
A string representation of this object.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited
operator [](String id) FutureOr<DocumentFragment>
Returns the DocumentFragment for the Document with the given id.

Constants

defaultName → const String
The name of the default collection.