CBLCollection

@interface CBLCollection
    : NSObject <CBLCollectionChangeObservable, CBLIndexable, NSCopying>

A CBLCollection 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 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 kCBLDefaultCollectionName and kCBLDefaultScopeName 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 return CBLErrorNotOpen 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 \ref [database documentWithID:]] 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.

  • Collection name.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull name;

  • The scope of the collection.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLScope *_Nonnull scope;

Document Management

  • The number of documents in the collection.

    Declaration

    Objective-C

    @property (readonly) uint64_t count;

  • Gets an existing document with the given ID. If a document with the given ID doesn’t exist in the collection, the value returned will be nil.

    Declaration

    Objective-C

    - (nullable CBLDocument *)documentWithID:(nonnull NSString *)documentID
                                   error:(NSError *_Nullable *_Nullable)error;

    Parameters

    documentID

    The document ID.
    error

    On return, the error if any.

    Return Value

    The CBLDocument object.

Subscript

  • Gets a document fragment with the given document ID.

    Declaration

    Objective-C

    - (nonnull CBLDocumentFragment *)objectForKeyedSubscript:
    (nonnull NSString *)documentID;

    Parameters

    documentID

    The document ID.

    Return Value

    The CBLDocumentFragment object.

Save, Delete, Purge

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

    Declaration

    Objective-C

    - (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
               error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

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

    Declaration

    Objective-C

    - (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
    concurrencyControl:(CBLConcurrencyControl)concurrencyControl
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document.
    concurrencyControl

    The concurrency control.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

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

    Declaration

    Objective-C

    - (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
     conflictHandler:(nonnull BOOL (^)(CBLMutableDocument *_Nonnull,
                                       CBLDocument *_Nonnull))conflictHandler
               error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document.
    conflictHandler

    The conflict handler block which can be used to resolve it.
    error

    On return, error if any.

    Return Value

    True if successful. False if there is a conflict, but the conflict wasn’t resolved as the conflict handler returns ‘false’ value.

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

    Declaration

    Objective-C

    - (BOOL)deleteDocument:(nonnull CBLDocument *)document
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document.
    error

    On return, the error if any.

    Return Value

    /True on success, false on failure.

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

    Declaration

    Objective-C

    - (BOOL)deleteDocument:(nonnull CBLDocument *)document
    concurrencyControl:(CBLConcurrencyControl)concurrencyControl
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document.
    concurrencyControl

    The concurrency control.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

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

    Declaration

    Objective-C

    - (BOOL)purgeDocument:(nonnull CBLDocument *)document
                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    document

    The document to be purged.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

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

    Declaration

    Objective-C

    - (BOOL)purgeDocumentWithID:(nonnull NSString *)documentID
                      error:(NSError *_Nullable *_Nullable)error;

    Parameters

    documentID

    The ID of the document to be purged.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

DOCUMENT EXPIRATION

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

    Declaration

    Objective-C

    - (BOOL)setDocumentExpirationWithID:(nonnull NSString *)documentID
                         expiration:(nullable NSDate *)date
                              error:(NSError *_Nullable *_Nullable)error;

    Parameters

    documentID

    The ID of the document to set the expiration date for
    date

    The expiration date. Set nil date will reset the document expiration.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

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

    Declaration

    Objective-C

    - (nullable NSDate *)getDocumentExpirationWithID:(nonnull NSString *)documentID
                                           error:(NSError *_Nullable *_Nullable)
                                                     error;

    Parameters

    documentID

    The ID of the document to set the expiration date for
    error

    On return, the error if any.

    Return Value

    the expiration time of a document, if one has been set, else nil.

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.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addDocumentChangeListenerWithID:(nonnull NSString *)id
                           listener:(nonnull void (^)(
                                        CBLDocumentChange *_Nonnull))listener;

    Parameters

    id

    The document ID.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

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

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addDocumentChangeListenerWithID:(nonnull NSString *)documentID
                              queue:(nullable dispatch_queue_t)queue
                           listener:(nonnull void (^)(
                                        CBLDocumentChange *_Nonnull))listener;

    Parameters

    documentID

    The document ID.
    queue

    The dispatch queue.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;