Collection

public final class Collection : CollectionChangeObservable, Indexable, Equatable, Hashable

A Collection represent a collection which is 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 namespce, 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.defaultCollectionName and Scope.defaultScopeName 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 the 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.

CBLCollection Lifespan

A Collection object and its reference remain valid until either the database is closed or the collection itself is deleted, in that case it will throw an NSError with the CBLError.notOpen code while accessing the collection APIs.

Legacy Database and API

When using the legacy database, the existing documents and indexes in the database will be automatically migrated to the default collection.

Any pre-existing database functions that refer to documents, listeners, and indexes without specifying a collection such as database.document(id:) 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 API instead. These legacy functions are deprecated and will be removed eventually.

  • The default scope name constant

    Declaration

    Swift

    public static let defaultCollectionName: String

  • Collection name.

    Declaration

    Swift

    public var name: String { get }

  • The scope of the collection.

    Declaration

    Swift

    public let scope: Scope

Document Management

  • Total number of documents in the collection.

    Declaration

    Swift

    public var count: UInt64 { get }

  • Get an existing document by document ID.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func document(id: String) throws -> Document?

  • Gets document fragment object by the given document ID.

    Declaration

    Swift

    public subscript(key: String) -> DocumentFragment { get }

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

    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.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func save(document: MutableDocument) throws

  • 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.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func save(document: MutableDocument, concurrencyControl: ConcurrencyControl) throws -> Bool

  • 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.

    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.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func save(document: MutableDocument,
          conflictHandler: @escaping (MutableDocument, Document?) -> Bool) throws -> Bool

  • 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.

    When deleting 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.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func delete(document: Document) throws

  • 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.

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

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func delete(document: Document, concurrencyControl: ConcurrencyControl) throws -> Bool

  • 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.

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func purge(document: Document) throws

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

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func purge(id: String) throws

Document Expiry

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

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func setDocumentExpiration(id: String, expiration: Date?) throws

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

    Throws an NSError with the CBLError.notOpen code, if the collection is deleted or the database is closed.

    Declaration

    Swift

    public func getDocumentExpiration(id: String) throws -> Date?

Document Change Publisher

  • 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.

    If the collection is deleted or the database is closed, a warning message will be logged.

    Declaration

    Swift

    public func addDocumentChangeListener(id: String,
                               listener: @escaping (DocumentChange) -> Void) -> ListenerToken

  • Add a change listener to listen to change events occurring to a document of the given document id. If a dispatch queue is given, the events will be posted on the dispatch queue. To remove the listener, call remove() function on the returned listener token.

    If the collection is deleted or the database is closed, a warning message will be logged.

    Declaration

    Swift

    public func addDocumentChangeListener(id: String, queue: DispatchQueue?,
                               listener: @escaping (DocumentChange) -> Void) -> 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 . If the collection is deleted or the database is closed, a warning message will be logged.

    Declaration

    Swift

    public func addChangeListener(listener: @escaping (CollectionChange) -> Void) -> ListenerToken

  • Add a change listener to listen to change events occurring to any documents in the collection. If a dispatch queue is given, the events will be posted on the dispatch queue. To remove the listener, call remove() function on the returned listener token.

    If the collection is deleted or the database is closed, a warning message will be logged.

    Declaration

    Swift

    public func addChangeListener(queue: DispatchQueue?,
                              listener: @escaping (CollectionChange) -> Void) -> ListenerToken

Indexable

  • Return all index names

    Declaration

    Swift

    public func indexes() throws -> [String]

  • Create an index with the index name and config.

    Declaration

    Swift

    public func createIndex(withName name: String, config: IndexConfiguration) throws

  • Create an index with the index name and index instance.

    Declaration

    Swift

    public func createIndex(_ index: Index, name: String) throws

  • Delete an index by name.

    Declaration

    Swift

    public func deleteIndex(forName name: String) throws

Equatable

  • Declaration

    Swift

    public static func == (lhs: Collection, rhs: Collection) -> Bool

Hashable

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)