Database

Database

A Couchbase Lite Database.

Syntax


@interface CBLDatabase : NSObject
class CBLDatabase : NSObject
public class Database
public class Database
public class Database

Summary


Constants
String
The name of the event raised by a Database in response to Document changes.
Events
The type of event raised when a Database changes.
Properties
Replication[]
allReplications { get; }
Gets all the running Replications for this Database. This includes all continuous Replications and any non-continuous Replications that have been started and are still running.
int
documentCount { get; }
Gets the number of Documents in the Database.
static CompileFilterDelegate
filterCompiler { get; set; }
Gets or sets an object that can compile source code into a FilterDelegate.
long
Gets the latest sequence number used by the Database. Every new Revision is assigned a new sequence number, so this property increases monotonically as changes are made to the Database. This can be used to check whether the Database has changed between two points in time.
Manager
manager { get; }
Gets the Manager that owns this Database.
long
maxRevTreeDepth { get; set; }
The maximum depth of the revision-history metadata that will be remembered (per document) in the local database. The default is 20. Larger values help prevent false conflicts if the database may be offline for a long time, but will somewhat increase the size of the database and reduce performance. Changes to this property are persistent.
String
name { get; }
Gets the Database name.
Methods
void
Adds a Database change delegate that will be called whenever a Document within the Database changes.
boolean
close()
Closes a Database.
void
Compacts the Database file by purging non-current Revisions and deleting unused Attachments.
Query
Creates a Query that matches all Documents in the Database.
Document
Creates a Document with a unique id.
Replication
Creates a new Replication that will pull from the source Database at the given url.
Replication
Creates a new Replication that will push to the target Database at the given url.
void
delete()
Deletes the Database. If the Database is encrypted then it must be opened with the encryption key first in order to delete it.
void
deleteLocalDocument(String id)
Deletes the local document with the given id.
Document
getDocument(String id)
Gets or creates the Document with the given id.
Document
getExistingDocument(String id)
Gets the Document with the given id, or null if it does not exist.
Map<String, Object>
Gets the local document with the given id, or null if it does not exist.
View
getExistingView(String name)
Gets the View with the given name, or null if it does not exist.
FilterDelegate
getFilter(String name)
Returns the filter delegate for the given name, or null if it does not exist.
ValidateDelegate
getValidation(String name)
Returns the validation delegate for the given name, or null if it does not exist.
View
getView(String name)
Gets or creates the View with the given name. New Views won't be added to the Database until a map function is assigned.
void
putLocalDocument(String id, Map<String, Object> properties)
Sets the contents of the local document with the given id. If properties is null, the document is deleted.
void
Removes the specified delegate as a listener for the Database change event.
void
Performs a block of code asynchronously.
boolean
Runs the delegate within a transaction. If the delegate returns false, the transaction is rolled back.
void
setFilter(String name, FilterDelegate delegate)
Sets the filter delegate for the given name. If delegate is null, the filter with the given name is deleted. Before a Revision is replicated via a push Replication, its filter delegate is called and given a chance to exclude it from the Replication.
void
setMaxRevTreeDepth(int maxRevTreeDepth)
Set the maximum depth of a document's revision tree or, max length of its revision history. Revisions older than this limit will be deleted during a compact operation.
void
setValidation(String name, ValidateDelegate delegate)
Sets the validation delegate for the given name. If delegate is null, the validation with the given name is deleted. Before any change to the Database is committed, including incoming changes from a pull Replications, all of its validation delegates are called and given a chance to reject it.
Delegates
void
ChangeDelegate(ChangeEvent event)
A delegate that can be used to listen for Database changes.
FilterDelegate
CompileFilterDelegate(String source, String language)
A delegate that can be invoked to compile source code into a FilterDelegate.
boolean
FilterDelegate( SavedRevision revision, Map<String, Object> params)
A delegate that can be used to include/exclude Revisions during push Replication.
void
A delegate that can be run asynchronously on a Database.
boolean
A delegate that can be run in a transaction on a Database.
void
A delegate that can be used to accept/reject new Revisions being added to a Database.

Constants


String Change
The name of the event raised by a Database in response to Document changes.

Syntax

extern NSString * const kCBLDatabaseChangeNotification
let kCBLDatabaseChangeNotification: String!
Not applicable.
Not applicable.
Not applicable.

Events


event ChangeEvent
The type of event raised when a Database changes.

Syntax

@interface NSNotification : NSObject <NSCopying, NSCoding>
class NSNotification : NSObject, NSCopying, NSCoding
public interface ChangeEvent
public interface ChangeEvent
public class DatabaseChangeEventArgs : EventArgs

Properties


Replication[] allReplications { get; }
Gets all the running Replications for this Database. This includes all continuous Replications and any non-continuous Replications that have been started and are still running.

Syntax

-(NSArray *)allReplications
func allReplications() -> [AnyObject]!
public List<Replication> getAllReplications()
public List<Replication> getAllReplications()
public IEnumerable<Replication> AllReplications { get; }
int documentCount { get; }
Gets the number of Documents in the Database.

Syntax

@property (readonly) NSUInteger documentCount
var documentCount: UInt
public int getDocumentCount()
public int getDocumentCount()
public int DocumentCount { get; }
static CompileFilterDelegate filterCompiler { get; set; }
Gets or sets an object that can compile source code into a FilterDelegate.

Syntax

+(id<CBLFilterCompiler>)filterCompiler
+(void)setFilterCompiler:(id<CBLFilterCompiler>)compiler
class func filterCompiler() -> CBLFilterCompiler
class func setFilterCompiler(compiler: CBLFilterCompiler!)
public static ReplicationFilterCompiler getFilterCompiler()
public static void setFilterCompiler(ReplicationFilterCompiler compiler)
public static ReplicationFilterCompiler getFilterCompiler()
public static void setFilterCompiler(ReplicationFilterCompiler compiler)
public static CompileFilterDelegate FilterCompiler { get; set; }
long lastSequenceNumber { get; }
Gets the latest sequence number used by the Database. Every new Revision is assigned a new sequence number, so this property increases monotonically as changes are made to the Database. This can be used to check whether the Database has changed between two points in time.

Syntax

@property (readonly) SInt64 lastSequenceNumber
var lastSequenceNumber: Int64
public long getLastSequenceNumber()
public long getLastSequenceNumber()
public long LastSequenceNumber { get; }
Manager manager { get; }
Gets the Manager that owns this Database.

Syntax

@property (readonly) CBLManager * manager
var manager: CBLManager!
public Manager getManager()
public Manager getManager()
public Manager Manager { get; }
long maxRevTreeDepth { get; set; }
The maximum depth of the revision-history metadata that will be remembered (per document) in the local database. The default is 20. Larger values help prevent false conflicts if the database may be offline for a long time, but will somewhat increase the size of the database and reduce performance. Changes to this property are persistent.

Syntax

@property NSUInteger maxRevTreeDepth
var maxRevTreeDepth: UInt64
public int getMaxRevTreeDepth();
public void setMaxRevTreeDepth(int maxRevTreeDepth);
public int getMaxRevTreeDepth();
public void setMaxRevTreeDepth(int maxRevTreeDepth);
public int maxRevTreeDepth { get; set; }
String name { get; }
Gets the Database name.

Syntax

@property (readonly) NSString * name
var name: String!
public String getName()
public String getName()
public String Name { get; }

Methods


void addChangeListener( ChangeDelegate delegate)
Adds a Database change delegate that will be called whenever a Document within the Database changes.

Parameters

delegate The Database change delegate to add.

Syntax

NSNotificationCenter -(void)addObserver:(id)notificationObserver selector:(SEL)notificationSelector name:kCBLDatabaseChangeNotification object:(id)notificationSender
NSNotificationCenter func addObserver(observer: AnyObject, selector: Selector, name: kCBLDatabaseChangeNotification, object: AnyObject?)
public void addChangeListener(ChangeListener listener)
public void addChangeListener(ChangeListener listener)
public event EventHandler<DatabaseChangeEventArgs> Change
boolean close()
Closes a Database.

Errors

Returns an error if there was an error while closing the Database.

Syntax

- (BOOL) close: (NSError**)error
func close(_ error: Error?) -> Bool
public boolean close()
public boolean close()
public Task Close()
void compact()
Compacts the Database file by purging non-current Revisions and deleting unused Attachments.

Errors

Returns an error if an issue occurs while compacting the Database.

Syntax

-(BOOL)compact:(NSError **)outError
func compact(outError: NSErrorPointer) -> Bool
public void compact() throws CouchbaseLiteException
public void compact() throws CouchbaseLiteException
public void Compact()
Query createAllDocumentsQuery()
Creates a Query that matches all Documents in the Database.

Returns

Returns a Query that matches all Documents in the Database.

Syntax

-(CBLQuery *)createAllDocumentsQuery
func createAllDocumentsQuery() -> CBLQuery!
public Query createAllDocumentsQuery()
public Query createAllDocumentsQuery()
public Query CreateAllDocumentsQuery()
Document createDocument()
Creates a Document with a unique id.

Returns

A Document with a unique id.

Syntax

-(CBLDocument *)createDocument
func createDocument() -> CBLDocument!
public Document createDocument()
public Document createDocument()
public Document CreateDocument()
Replication createPullReplication(URL url)
Creates a new Replication that will pull from the source Database at the given url.

Parameters

url The url of the source Database.

Returns

A new Replication that will pull from the source Database at the given url.

Syntax

-(CBLReplication *)createPullReplication:(NSURL *)url
func createPullReplication(url: NSURL!) -> CBLReplication!
public Replication getPullReplication(URL url)
public Replication getPullReplication(URL url)
public Replication GetPullReplication(Uri url)
Replication createPushReplication(URL url)
Creates a new Replication that will push to the target Database at the given url.

Parameters

url The url of the target Database.

Returns

A new Replication that will push to the target Database at the given url.

Syntax

-(CBLReplication *)createPushReplication:(NSURL *)url
func createPushReplication(url: NSURL!) -> CBLReplication!
public Replication getPushReplication(URL url)
public Replication getPushReplication(URL url)
public Replication GetPushReplication(Uri url)
void delete()
Deletes the Database. If the Database is encrypted then it must be opened with the encryption key first in order to delete it.

Errors

Returns an error if an issue occurs while deleting the Database.

Syntax

-(BOOL)deleteDatabase:(NSError **)outError
func deleteDatabase(outError: NSErrorPointer) -> Bool
public void delete() throws CouchbaseLiteException
public void delete() throws CouchbaseLiteException
public void Delete()
void deleteLocalDocument(String id)
Deletes the local document with the given id.

Parameters

id The id of the local document to delete.

Errors

Returns an error if an issue occurs while deleting the local document.

Syntax

-(BOOL)deleteLocalDocumentWithID:(NSString *)localDocID error:(NSError **)outError
func deleteLocalDocumentWithID(localDocID: String!, error: NSErrorPointer) -> Bool
public boolean deleteLocalDocument(String id) throws CouchbaseLiteException
public boolean deleteLocalDocument(String id) throws CouchbaseLiteException
public Boolean DeleteLocalDocument(String id)
Document getDocument(String id)
Gets or creates the Document with the given id.

Parameters

id The id of the Document to get or create.

Returns

The Document with the given id.

Syntax

-(CBLDocument *)documentWithID:(NSString *)docID
func documentWithID(docID: String!) -> CBLDocument!
public Document getDocument(String id)
public Document getDocument(String id)
public Document GetDocument(String id)
Document getExistingDocument(String id)
Gets the Document with the given id, or null if it does not exist.

Parameters

id The id of the Document to get.

Returns

The Document with the given id, or null if it does not exist.

Syntax

-(CBLDocument *)existingDocumentWithID:(NSString *)docID
func existingDocumentWithID(docID: String!) -> CBLDocument!
public Document getExistingDocument(String id)
public Document getExistingDocument(String id)
public Document GetExistingDocument(String id)
Map<String, Object> getExistingLocalDocument(String id)
Gets the local document with the given id, or null if it does not exist.

Parameters

id The id of the local document to get.

Returns

The local document with the given id, or null if it does not exist.

Syntax

-(NSDictionary *)existingLocalDocumentWithID:(NSString *)docID
func existingLocalDocumentWithID(docID: String!) -> [NSObject : AnyObject]!
public Map<String, Object> getExistingLocalDocument(String id)
public Map<String, Object> getExistingLocalDocument(String id)
public Dictionary<String, Object> GetExistingLocalDocument(String id)
View getExistingView(String name)
Gets the View with the given name, or null if it does not exist.

Parameters

name The name of the View to get.

Returns

The View with the given name, or null if it does not exist.

Syntax

-(CBLView *)existingViewNamed:(NSString *)name
func existingViewNamed(name: String!) -> CBLView!
public View getExistingView(String name)
public View getExistingView(String name)
public View GetExistingView(String name)
FilterDelegate getFilter(String name)
Returns the filter delegate for the given name, or null if it does not exist.

Parameters

name The name of the filter delegate to get.

Returns

The filter delegate for the given name, or null if it does not exist.

Syntax

-(CBLFilterBlock)filterNamed:(NSString *)filterName
func filterNamed(filterName: String!) -> CBLFilterBlock!
public FilterDelegate getFilter(String name)
public FilterDelegate getFilter(String name)
public FilterDelegate GetFilter(String name)
ValidateDelegate getValidation(String name)
Returns the validation delegate for the given name, or null if it does not exist.

Parameters

name The name of the validation delegate to get.

Returns

The validation delegate for the given name, or null if it does not exist.

Syntax

-(CBLValidationBlock)validationNamed:(NSString *)validationName
func validationNamed(validationName: String!) -> CBLValidationBlock!
public ValidateDelegate getValidation(String name)
public ValidateDelegate getValidation(String name)
public ValidateDelegate GetValidation(String name)
View getView(String name)
Gets or creates the View with the given name. New Views won't be added to the Database until a map function is assigned.

Parameters

name The name of the View to get or create.

Returns

The View with the given name.

Syntax

-(CBLView *)viewNamed:(NSString *)name
func viewNamed(name: String!) -> CBLView!
public View getView(String name)
public View getView(String name)
public View GetView(String name)
void putLocalDocument(String id, Map<String, Object> properties)
Sets the contents of the local document with the given id. If properties is null, the document is deleted.

Parameters

id The id of the local document whos contents to set.
properties The contents to set for the local document.

Errors

Returns an error if an issue occurs while setting the contents of the local document.

Syntax

-(BOOL)putLocalDocument:(NSDictionary *)properties withID:(NSString *)localDocID error:(NSError **)outError
func putLocalDocument(properties: [NSObject : AnyObject]!, withID: String!, error: NSErrorPointer) -> Bool
public void putLocalDocument(String id, Map<String, Object> properties) throws CouchbaseLiteException
public void putLocalDocument(String id, Map<String, Object> properties) throws CouchbaseLiteException
public void PutLocalDocument(String id, Dictionary<String, Object> properties)
void removeChangeListener( ChangeDelegate delegate)
Removes the specified delegate as a listener for the Database change event.

Parameters

delegate The Database change delegate to remove.

Syntax

NSNotificationCenter -(void)removeObserver:(id)observer name:kCBLDatabaseChangeNotification object:(id)anObject
NSNotificationCenter func removeObserver:(observer: AnyObject, name: kCBLDatabaseChangeNotification, object: AnyObject?)
public void removeChangeListener(ChangeListener listener)
public void removeChangeListener(ChangeListener listener)
public event EventHandler<DatabaseChangeEventArgs> Change
void runAsync( RunAsyncDelegate delegate)
Performs a block of code asynchronously.

Parameters

delegate The code to run asynchronously; a language-dependent delegate / function / block.

Syntax

-(void)doAsync:(void(^)())block
func doAsync(block: (() -> Void))
public Future runAsync(AsyncTask asyncTask)
public Future runAsync(AsyncTask asyncTask)
public void RunAsync(RunAsyncDelegate runAsyncDelegate)
boolean runInTransaction( RunInTransactionDelegate delegate)
Runs the delegate within a transaction. If the delegate returns false, the transaction is rolled back.

Parameters

delegate The delegate to run within a transaction.

Returns

True if the transaction was committed, otherwise false.

Syntax

-(BOOL)inTransaction:(BOOL(^)(void))block
func inTransaction(block: (() -> Bool)) -> Bool
public boolean runInTransaction(TransactionalTask transactionalTask)
public boolean runInTransaction(TransactionalTask transactionalTask)
public Boolean RunInTransaction(RunInTransactionDelegate transactionDelegate)
void setFilter(String name, FilterDelegate delegate)
Sets the filter delegate for the given name. If delegate is null, the filter with the given name is deleted. Before a Revision is replicated via a push Replication, its filter delegate is called and given a chance to exclude it from the Replication.

Parameters

name The name of the filter delegate to set.
delegate The filter delegate to set.

Syntax

-(void)setFilterNamed:(NSString *)filterName asBlock:(CBLFilterBlock)filterBlock
func setFilterNamed(filterName: String!, asBlock: CBLFilterBlock!)
public void setFilter(String name, FilterDelegate delegate)
public void setFilter(String name, FilterDelegate delegate)
public void SetFilter(String name, FilterDelegate filterDelegate)
void setMaxRevTreeDepth(int maxRevTreeDepth)
Set the maximum depth of a document's revision tree or, max length of its revision history. Revisions older than this limit will be deleted during a compact operation.

Syntax

@property NSUInteger maxRevTreeDepth
var maxRevTreeDepth
int maxRevTreeDepth {get; set;}
int maxRevTreeDepth {get; set;}
int maxRevTreeDepth {get; set;}
void setValidation(String name, ValidateDelegate delegate)
Sets the validation delegate for the given name. If delegate is null, the validation with the given name is deleted. Before any change to the Database is committed, including incoming changes from a pull Replications, all of its validation delegates are called and given a chance to reject it.

Parameters

name The name of the validation delegate to set.
delegate The validation delegate to set.

Syntax

-(void)setValidationNamed:(NSString *)validationName asBlock:(CBLValidationBlock)validationBlock
func setValidationNamed(validationName: String!, asBlock: CBLValidationBlock!)
public void setValidation(String name, ValidateDelegate delegate)
public void setValidation(String name, ValidateDelegate delegate)
public void SetValidation(String name, ValidateDelegate validationDelegate)

Delegates


void ChangeDelegate(ChangeEvent event)
A delegate that can be used to listen for Database changes.

Parameters

event The Database change event.

Syntax

-(void)databaseChangeNotification:(NSNotification *)notification
func databaseChangeNotification(notification: NSNotification)
public interface ChangeListener {
    void changed(ChangeEvent event);
}
public interface ChangeListener {
    void changed(ChangeEvent event);
}
Not applicable.
FilterDelegate CompileFilterDelegate(String source, String language)
A delegate that can be invoked to compile source code into a FilterDelegate.

Parameters

source The source code to compile into a FilterDelegate.
language The language of the source.

Returns

A compiled FilterDelegate.

Syntax

@protocol CBLFilterCompiler <NSObject>
    - (CBLFilterBlock)compileFilterFunction:(NSString *)filterSource language:(NSString *)language;
@end
protocol CBLFilterCompiler {
    func compileFilterFunction(filterSource: String!, language: String!) -> CBLFilterBlock!
}
public interface ReplicationFilterCompiler {
    ReplicationFilter compile(String source, String language);
}
public interface ReplicationFilterCompiler {
    ReplicationFilter compile(String source, String language);
}
public delegate FilterDelegate CompileFilterDelegate(String source, String language);
boolean FilterDelegate( SavedRevision revision, Map<String, Object> params)
A delegate that can be used to include/exclude Revisions during push Replication.

Parameters

revision The Revision being validated.
params User defined set of parameters specified on the Replication.

Returns

True if the Revision should be included in the pushed, otherwise false.

Syntax

typedef BOOL (^CBLFilterBlock) (CBLSavedRevision * revision, NSDictionary * params);
typealias CBLFilterBlock = (CBLSavedRevision!, [NSObject : AnyObject]!) -> Bool
public interface ReplicationFilter {
    boolean filter(SavedRevision revision, Map<String, Object> params);
}
public interface ReplicationFilter {
    boolean filter(SavedRevision revision, Map<String, Object> params);
}
public delegate Boolean FilterDelegate(SavedRevision revision, Dictionary<String, Object> filterParams);
void RunAsyncDelegate( Database database)
A delegate that can be run asynchronously on a Database.

Parameters

database The Database the delegate is being invoked against.

Syntax

^(CBLDatabase * database) {
    ...
}
{ () -> Void in
}
public interface AsyncTask {
    void run(Database database);
}
public interface AsyncTask {
    void run(Database database);
}
public delegate void RunAsyncDelegate(Database database);
boolean RunInTransactionDelegate()
A delegate that can be run in a transaction on a Database.

Returns

True if the transaction should be committed, otherwise false.

Syntax

^BOOL {
    ...
}
{ () -> Bool in
}
public interface TransactionalTask {
    boolean run();
}
public interface TransactionalTask {
    boolean run();
}
public delegate Boolean RunInTransactionDelegate();
void ValidateDelegate( Revision newRevision, ValidationContext context)
A delegate that can be used to accept/reject new Revisions being added to a Database.

Parameters

newRevision The new Revision being added to the Database.
context The validation context used to provide additional information about what's being updated and members for validating and rejecting the new Revision.

Syntax

typedef void (^CBLValidationBlock) (CBLRevision * newRevision, id<CBLValidationContext> context);
typealias CBLValidationBlock = (CBLRevision!, CBLValidationContext!) -> Void
public interface Validator {
    void validate(Revision newRevision, ValidationContext context);
}
public interface Validator {
    void validate(Revision newRevision, ValidationContext context);
}
public delegate void ValidateDelegate(Revision newRevision, IValidationContext context);