CBLDatabase

@interface CBLDatabase : NSObject

A Couchbase Lite database.

  • The database’s name.

    Declaration

    Objective-C

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

  • The database’s path. If the database is closed or deleted, nil value will be returned.

    Declaration

    Objective-C

    @property (readonly, nullable) NSString *path;

  • The number of documents in the database.

    Declaration

    Objective-C

    @property (readonly) uint64_t count;

  • The database’s configuration. The returned configuration object is readonly; an NSInternalInconsistencyException exception will be thrown if the configuration object is modified.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLDatabaseConfiguration *_Nonnull config;

Initializers

  • Initializes a database object with a given name and the default database configuration. If the database does not yet exist, it will be created.

    Declaration

    Objective-C

    - (nullable instancetype)initWithName:(nonnull NSString *)name
                                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The name of the database.
    error

    On return, the error if any.

  • Initializes a Couchbase Lite database with a given name and database configuration. If the database does not yet exist, it will be created.

    Declaration

    Objective-C

    - (nullable instancetype)initWithName:(nonnull NSString *)name
                               config:
                                   (nullable CBLDatabaseConfiguration *)config
                                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The name of the database.
    config

    The database configuration, or nil for the default configuration.
    error

    On return, the error if any.

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;

Get Existing Document

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

    Declaration

    Objective-C

    - (nullable CBLDocument *)documentWithID:(nonnull NSString *)id;

    Parameters

    id

    The document ID.

    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

  • Saves a document to the database. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling the -saveDocument:concurrencyControl:error: method with kCBLConcurrencyControlLastWriteWins concurrency control.

    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.

  • Saves a document to the database. When used with kCBLConcurrencyControlLastWriteWins concurrency control, the last write operation will win if there is a conflict. When used with kCBLConcurrencyControlFailOnConflict concurrency control, save will fail with ‘CBLErrorConflict’ error code returned.

    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.

  • Saves a document to the database. When write operations are executed concurrently and if conflicts occur, the conflict handler will be called. Use the conflict handler to directly edit the document to resolve the conflict. When the conflict handler returns ‘true’, the save method will save the edited document as the resolved document. If the conflict handler returns ‘false’, the save operation will be canceled with ‘false’ value returned as the conflict wasn’t resolved.

    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.

  • Deletes a document from the database. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling the -deleteDocument:concurrencyControl:error: method with kCBLConcurrencyControlLastWriteWins concurrency control.

    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.

  • Deletes a document from the database. When used with kCBLConcurrencyControlLastWriteWins concurrency control, the last write operation will win if there is a conflict. When used with kCBLConcurrencyControlFailOnConflict concurrency control, delete will fail with ‘CBLErrorConflict’ error code returned.

    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.

  • Purges the given document from the database. This is more drastic than deletion: it removes all traces of the document. The purge will NOT be replicated to other databases.

    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.

  • Purges the document for the given documentID from the database. This is more drastic than deletion: it removes all traces of the document. The purge will NOT be replicated to other databases.

    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.

Blob Save/Get

  • Save a blob object directly into the database without associating it with any documents.

    Note: Blobs that are not associated with any documents will be removed from the database when compacting the database.

    @Note (UNCOMMITTED) Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API.

    Declaration

    Objective-C

    - (BOOL)saveBlob:(nonnull CBLBlob *)blob
           error:(NSError *_Nullable *_Nullable)error;

    Parameters

    blob

    The blob to save.
    error

    On return, the error if any.

    Return Value

    /True on success, false on failure.

  • Get a blob object using a blob’s metadata. If the blob of the specified metadata doesn’t exist, the nil value will be returned.

    @Note

    Key | Value | Mandatory | Description

    @type | constant string “blob” | Yes | Indicate Blob data type. content_type | String | No | Content type ex. text/plain. length | Number | No | Binary length of the Blob in bytes. digest | String | Yes | The cryptographic digest of the Blob’s content.

    @Note (UNCOMMITTED) Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API.

    Declaration

    Objective-C

    - (nullable CBLBlob *)getBlob:(nonnull NSDictionary *)properties;

    Parameters

    properties

    The properties for getting the blob object. If dictionary is not valid, it will throw InvalidArgument exception. See the note section

    Return Value

    Blob on success, otherwise nil.

Batch Operation

  • Runs a group of database operations in a batch. Use this when performing bulk write operations like multiple inserts/updates; it saves the overhead of multiple database commits, greatly improving performance.

    Declaration

    Objective-C

    - (BOOL)inBatch:(NSError *_Nullable *_Nullable)error
     usingBlock:(nonnull void (^)(void))block;

    Parameters

    error

    On return, the error if any.
    block

    The block to execute a group of database operations.

    Return Value

    True on success, false on failure.

Databaes Maintenance

  • Close database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

    Declaration

    Objective-C

    - (BOOL)close:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Close and delete the database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

    Declaration

    Objective-C

    - (BOOL)delete:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Performs database maintenance.

    Declaration

    Objective-C

    - (BOOL)performMaintenance:(CBLMaintenanceType)type
                     error:(NSError *_Nullable *_Nullable)error;

    Parameters

    type

    Maintenance type.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Deletes a database of the given name in the given directory.

    Declaration

    Objective-C

    + (BOOL)deleteDatabase:(nonnull NSString *)name
           inDirectory:(nullable NSString *)directory
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Checks whether a database of the given name exists in the given directory or not.

    Declaration

    Objective-C

    + (BOOL)databaseExists:(nonnull NSString *)name
           inDirectory:(nullable NSString *)directory;

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.

    Return Value

    True on success, false on failure.

  • Copies a canned databaes from the given path to a new database with the given name and the configuration. The new database will be created at the directory specified in the configuration. Without given the database configuration, the default configuration that is equivalent to setting all properties in the configuration to nil will be used.

    @Note This method will copy the database without changing the encryption key of the original database. The encryption key specified in the given config is the encryption key used for both the original and copied database. To change or add the encryption key for the copied database, call [Database changeEncryptionKey:error:] for the copy.

    Declaration

    Objective-C

    + (BOOL)copyFromPath:(nonnull NSString *)path
          toDatabase:(nonnull NSString *)name
          withConfig:(nullable CBLDatabaseConfiguration *)config
               error:(NSError *_Nullable *_Nullable)error;

    Parameters

    path

    The source database path.
    name

    The name of the new database to be created.
    config

    The database configuration for the new database.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

Logging

  • Log object used for configuring console, file, and custom logger.

    Declaration

    Objective-C

    + (nonnull CBLLog *)log;

    Return Value

    log object

Change Listener

  • Adds a database change listener. Changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)addChangeListener:
    (nonnull void (^)(CBLDatabaseChange *_Nonnull))listener;

    Parameters

    listener

    The listener to post the changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a database change listener with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addChangeListenerWithQueue:(nullable dispatch_queue_t)queue
                      listener:(nonnull void (^)(CBLDatabaseChange *_Nonnull))
                                   listener;

    Parameters

    queue

    The dispatch queue.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a document change listener for the document with the given ID. Changes will be posted on the main queue.

    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.

  • Adds a document change listener for the document with the given ID and the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

    Declaration

    Objective-C

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

    Parameters

    id

    The document ID.
    queue

    The dispatch queue.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Removes a change listener with the given listener token.

    Declaration

    Objective-C

    - (void)removeChangeListenerWithToken:(nonnull id<CBLListenerToken>)token;

    Parameters

    token

    The listener token.

Index

  • All index names.

    Declaration

    Objective-C

    @property (readonly) NSArray<NSString *> *_Nonnull indexes;

  • Creates an index which could be a value index or a full-text search index with the given name. The name can be used for deleting the index. Creating a new different index with an existing index name will replace the old index; creating the same index with the same name will be no-ops.

    Declaration

    Objective-C

    - (BOOL)createIndex:(nonnull CBLIndex *)index
           withName:(nonnull NSString *)name
              error:(NSError *_Nullable *_Nullable)error;

    Parameters

    index

    The index.
    name

    The index name.
    error

    error On return, the error if any.

    Return Value

    True on success, false on failure.

  • Creates an index using IndexConfiguration, which could be a value index or a full-text search index with the given name. Creating a new different index with an existing index name will replace the old index; creating the same index with the same name will be no-ops.

    Declaration

    Objective-C

    - (BOOL)createIndexWithConfig:(nonnull CBLIndexConfiguration *)config
                         name:(nonnull NSString *)name
                        error:(NSError *_Nullable *_Nullable)error;

    Parameters

    config

    The index configuration
    name

    The index name.
    error

    error On return, the error if any.

    Return Value

    True on success, false on failure.

  • Deletes the index of the given index name.

    Declaration

    Objective-C

    - (BOOL)deleteIndexForName:(nonnull NSString *)name
                     error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The index name.
    error

    error On return, the error if any.

    Return Value

    True on success, false on failure.

DOCUMENT EXPIRATION

  • Sets an expiration date on a document. After this time the document will be purged from the database.

    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

    error On return, the error if any.

    Return Value

    True on success, false on failure.

  • Returns the expiration time of a document, if exists, else nil.

    Declaration

    Objective-C

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

    Parameters

    documentID

    The ID of the document to set the expiration date for

    Return Value

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

Query

  • Creates a Query object from the given query string.

    Declaration

    Objective-C

    - (nullable CBLQuery *)createQuery:(nonnull NSString *)query
                             error:(NSError *_Nullable *_Nullable)error;

    Parameters

    query

    Query expression
    error

    error On return, the given query string is invalid.

    Return Value

    query created using the given expression string.

Encryption

  • ENTERPRISE EDITION ONLY.

    Changes the database’s encryption key, or removes encryption if the new key is nil.

    Declaration

    Objective-C

    - (BOOL)changeEncryptionKey:(nullable CBLEncryptionKey *)key
                      error:(NSError *_Nullable *_Nullable)error;

    Parameters

    key

    The encryption key.
    error

    On return, the error if any.

    Return Value

    True if the database was successfully re-keyed, or false on failure.

Prediction

  • ENTERPRISE EDITION ONLY

    The predictive model manager for registering and unregistering predictive models.

    Declaration

    Objective-C

    + (nonnull CBLPrediction *)prediction;