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

IChangeObservable<CollectionChangedEventArgs>

IDocumentChangeObservable

IChangeObservableRemovable

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 with the given name, using one of the various specializations of IndexConfiguration 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

IChangeObservable<TEventType>

IDocumentChangeObservable

IChangeObservableRemovable

System.IDisposable