Class Collection

A class representing a Couchbase Lite collection. A collection is a logical group of documents segregated in a domain specific way inside of a Scope. It is comparable to a SQL table in a document based database world.

Inheritance
System.Object
Collection
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Couchbase.Lite
Assembly: Couchbase.Lite.dll
Syntax
public sealed class Collection : IChangeObservable<CollectionChangedEventArgs>, IDocumentChangeObservable, IChangeObservableRemovable, IDisposable

Fields

| Improve this Doc View Source

DefaultCollectionName

The name of the default Collection that exists in every Scope

Declaration
public static readonly string DefaultCollectionName
Field Value
Type Description
System.String
| Improve this Doc View Source

DefaultScopeName

The name of the default Scope that exists in every Database

Declaration
public static readonly string DefaultScopeName
Field Value
Type Description
System.String

Properties

| Improve this Doc View Source

Count

Gets the total documents in the Collection

Declaration
public ulong Count { get; }
Property Value
Type Description
System.UInt64
| Improve this Doc View Source

Database

Gets the database that this collection belongs to

Declaration
public Database Database { get; }
Property Value
Type Description
Database
| Improve this Doc View Source

FullName

Gets the Collection Full Name The format of the collection's full name is {scope-name}.{collection-name}.

Declaration
public string FullName { get; }
Property Value
Type Description
System.String
| Improve this Doc View Source

Item[String]

Gets a DocumentFragment with the given document ID

Declaration
public DocumentFragment this[string id] { get; }
Parameters
Type Name Description
System.String id

The ID of the DocumentFragment to retrieve
Property Value
Type Description
DocumentFragment

The DocumentFragment object
| Improve this Doc View Source

Name

Gets the Collection Name

Declaration
public string Name { get; }
Property Value
Type Description
System.String
Remarks

Naming rules: 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 %. Case sensitive.

| Improve this Doc View Source

Scope

Gets the Scope of the Collection belongs to

Declaration
public Scope Scope { get; }
Property Value
Type Description
Scope

Methods

| Improve this Doc View Source

AddChangeListener(EventHandler<CollectionChangedEventArgs>)

Adds a change listener for the changes that occur in this collection. Signatures are the same as += style event handlers. The callback will be invoked on a thread pool thread.

Declaration
public ListenerToken AddChangeListener(EventHandler<CollectionChangedEventArgs> handler)
Parameters
Type Name Description
System.EventHandler<CollectionChangedEventArgs> handler

The handler to invoke
Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the handler later
Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler is null
System.InvalidOperationException

Thrown if this method is called after the database is closed
| Improve this Doc View Source

AddChangeListener(TaskScheduler, EventHandler<CollectionChangedEventArgs>)

Adds a change listener for the changes that occur in this collection. Signatures are the same as += style event handlers, but the callbacks will be called using the specified System.Threading.Tasks.TaskScheduler. If the scheduler is null, the default task scheduler will be used (scheduled via thread pool).

Declaration
public ListenerToken AddChangeListener(TaskScheduler scheduler, EventHandler<CollectionChangedEventArgs> handler)
Parameters
Type Name Description
System.Threading.Tasks.TaskScheduler scheduler

The scheduler to use when firing the change handler
System.EventHandler<CollectionChangedEventArgs> handler

The handler to invoke
Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the handler later
Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler is null
System.InvalidOperationException

Thrown if this method is called after the database is closed
| Improve this Doc View Source

AddDocumentChangeListener(String, EventHandler<DocumentChangedEventArgs>)

Adds a document change listener for the document with the given ID. The callback will be invoked on a thread pool thread.

Declaration
public ListenerToken AddDocumentChangeListener(string id, EventHandler<DocumentChangedEventArgs> handler)
Parameters
Type Name Description
System.String id

The document ID
System.EventHandler<DocumentChangedEventArgs> handler

The logic to handle the event
Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the listener later
Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler or id is null
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

AddDocumentChangeListener(String, TaskScheduler, EventHandler<DocumentChangedEventArgs>)

Adds a document change listener for the document with the given ID and the System.Threading.Tasks.TaskScheduler that will be used to invoke the callback. If the scheduler is not specified, then the default scheduler will be used (scheduled via thread pool)

Declaration
public ListenerToken AddDocumentChangeListener(string id, TaskScheduler scheduler, EventHandler<DocumentChangedEventArgs> handler)
Parameters
Type Name Description
System.String id

The document ID
System.Threading.Tasks.TaskScheduler scheduler

The scheduler to use when firing the event handler
System.EventHandler<DocumentChangedEventArgs> handler

The logic to handle the event
Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the listener later
Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler or id is null
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

CreateIndex(String, IndexConfiguration)

Creates an index which could be a value index from ValueIndex(IValueIndexItem[]) or a full-text search index from FullTextIndex(IFullTextIndexItem[]) 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
public void CreateIndex(string name, IndexConfiguration indexConfig)
Parameters
Type Name Description
System.String name

The index name
IndexConfiguration indexConfig

The index configuration
Exceptions
Type Condition
System.ArgumentNullException

Thrown if name or indexConfig is null
CouchbaseException

Thrown if an error condition is returned from LiteCore
System.InvalidOperationException

Thrown if this method is called after the collection is closed
System.NotSupportedException

Thrown if an implementation of IIndex other than one of the library provided ones is used
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

CreateIndex(String, IIndex)

Creates an index which could be a value index from ValueIndex(IValueIndexItem[]) or a full-text search index from FullTextIndex(IFullTextIndexItem[]) 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
public void CreateIndex(string name, IIndex index)
Parameters
Type Name Description
System.String name

The index name
IIndex index

The index
Exceptions
Type Condition
System.ArgumentNullException

Thrown if name or index is null
CouchbaseException

Thrown if an error condition is returned from LiteCore
System.InvalidOperationException

Thrown if this method is called after the database is closed
System.NotSupportedException

Thrown if an implementation of IIndex other than one of the library provided ones is used
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

CreateQuery(String)

Create an IQuery object using the given SQL++ query expression.

Declaration
public IQuery CreateQuery(string queryExpression)
Parameters
Type Name Description
System.String queryExpression

The SQL++ query expression (e.g. SELECT * FROM _)
Returns
Type Description
IQuery

THe initialized query object, ready to execute
| Improve this Doc View Source

Delete(Document)

Deletes a document from the collection. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling Delete(Document, ConcurrencyControl) with LastWriteWins

Declaration
public void Delete(Document document)
Parameters
Type Name Description
Document document

The document
Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.InvalidParameter when trying to save a document into a collection other than the one it was previously added to
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotFound when trying to delete a document that hasn't been saved into a Collection yet
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Delete(Document, ConcurrencyControl)

Deletes the given Document from this collection

Declaration
public bool Delete(Document document, ConcurrencyControl concurrencyControl)
Parameters
Type Name Description
Document document

The document to save
ConcurrencyControl concurrencyControl

The rule to use when encountering a conflict in the collection
Returns
Type Description
System.Boolean

true if the delete succeeded, false if there was a conflict
Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.InvalidParameter when trying to save a document into a collection other than the one it was previously added to
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotFound when trying to delete a document that hasn't been saved into a Collection yet
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

DeleteIndex(String)

Deletes the index with the given name

Declaration
public void DeleteIndex(string name)
Parameters
Type Name Description
System.String name

The name of the index to delete
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
| Improve this Doc View Source

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
System.Object obj
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)
| Improve this Doc View Source

Finalize()

Finalizer

Declaration
protected void Finalize()
| Improve this Doc View Source

GetDocument(String)

Gets the Document with the specified ID

Declaration
public Document GetDocument(string id)
Parameters
Type Name Description
System.String id

The ID to use when creating or getting the document
Returns
Type Description
Document

The instantiated document, or null if it does not exist
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

GetDocumentExpiration(String)

Returns the expiration time of the document. null will be returned if there is no expiration time set

Declaration
public DateTimeOffset? GetDocumentExpiration(string docId)
Parameters
Type Name Description
System.String docId

The ID of the Document

Returns
Type Description
System.Nullable<System.DateTimeOffset>

Nullable expiration timestamp as a System.DateTimeOffset of the document or null if time not set.

Exceptions
Type Condition
CouchbaseLiteException

Throws NOT FOUND error if the document doesn't exist
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()
| Improve this Doc View Source

GetIndex(String)

Gets an existing index in a collection by name.

Declaration
public IQueryIndex GetIndex(string name)
Parameters
Type Name Description
System.String name

The name of the index to retrieve.
Returns
Type Description
IQueryIndex

The index object, or null if nonexistent
| Improve this Doc View Source

GetIndexes()

Gets a list of index names that are present in the collection

Declaration
public IList<string> GetIndexes()
Returns
Type Description
System.Collections.Generic.IList<System.String>

The list of created index names
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Purge(Document)

Purges the given Document from the collection. This leaves no trace behind and will not be replicated

Declaration
public void Purge(Document document)
Parameters
Type Name Description
Document document

The document to purge
Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to purge a document from a collection other than the one it was previously added to
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Purge(String)

Purges the given document id of the Document from the collection. This leaves no trace behind and will not be replicated

Declaration
public void Purge(string docId)
Parameters
Type Name Description
System.String docId

The id of the document to purge
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

RemoveChangeListener(ListenerToken)

Removes a collection changed listener by token

Declaration
public void RemoveChangeListener(ListenerToken token)
Parameters
Type Name Description
ListenerToken token

The token received from AddChangeListener(TaskScheduler, EventHandler<CollectionChangedEventArgs>) and family
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Save(MutableDocument)

Saves the given MutableDocument into this collection. This call is equivalent to calling Save(MutableDocument, ConcurrencyControl) with a second argument of LastWriteWins

Declaration
public void Save(MutableDocument document)
Parameters
Type Name Description
MutableDocument document

The document to save
Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to save a document into a collection other than the one it was previously added to
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Save(MutableDocument, ConcurrencyControl)

Saves the given MutableDocument into this collection

Declaration
public bool Save(MutableDocument document, ConcurrencyControl concurrencyControl)
Parameters
Type Name Description
MutableDocument document

The document to save
ConcurrencyControl concurrencyControl

The rule to use when encountering a conflict in the collection
Returns
Type Description
System.Boolean

true if the save succeeded, false if there was a conflict
Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to save a document into a collection other than the one it was previously added to
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

Save(MutableDocument, Func<MutableDocument, Document, Boolean>)

Saves a document to the collection. When write operations are executed concurrently, and if conflicts occur, conflict handler will be called. Use the handler to directly edit the document.Returning true, will save the document. Returning false, will cancel the save operation.

Declaration
public bool Save(MutableDocument document, Func<MutableDocument, Document, bool> conflictHandler)
Parameters
Type Name Description
MutableDocument document

The document to save
System.Func<MutableDocument, Document, System.Boolean> conflictHandler

The conflict handler block which can be used to resolve it.
Returns
Type Description
System.Boolean

true if the save succeeded, false if there was a conflict
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

SetDocumentExpiration(String, Nullable<DateTimeOffset>)

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

Declaration
public bool SetDocumentExpiration(string docId, DateTimeOffset? expiration)
Parameters
Type Name Description
System.String docId

The ID of the Document

System.Nullable<System.DateTimeOffset> expiration

Nullable expiration timestamp as a System.DateTimeOffset, set timestamp to null to remove expiration date time from doc.
Returns
Type Description
System.Boolean

Whether successfully sets an expiration date on the document
Exceptions
Type Condition
CouchbaseLiteException

Throws NOT FOUND error if the document doesn't exist
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotOpen if this method is called after the collection is closed
| Improve this Doc View Source

ToString()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

Implements

System.IDisposable