Couchbase Lite C
Couchbase Lite C API
Data Structures | Typedefs | Functions
Collection

A CBLCollection represent a collection which is a container for documents. More...

Data Structures

struct  CBLCollectionChange
 
struct  CBLDocumentChange
 

Typedefs

typedef struct CBLCollection CBLCollection
 A collection, a document container. More...
 

Functions

static const CBLCollectionCBLCollection_Retain (const CBLCollection *t)
 
static void CBLCollection_Release (const CBLCollection *t)
 

Change Listeners

A collection change listener lets you detect changes made to all documents in a collection.

(If you want to observe specific documents, use a CBLCollectionDocumentChangeListener instead.)

Note
If there are multiple CBLCollection instances on the same database file, each one's listeners will be notified of changes made by other collection instances.
Warning
Changes made to the database file by other processes will not be notified.
typedef void(* CBLCollectionChangeListener) (void *_cbl_nullable context, const CBLCollectionChange *change)
 A collection change listener callback, invoked after one or more documents are changed on disk. More...
 
_cbl_warn_unused CBLListenerTokenCBLCollection_AddChangeListener (const CBLCollection *collection, CBLCollectionChangeListener listener, void *_cbl_nullable context)
 Registers a collection change listener callback. More...
 

Document listeners

A document change listener lets you detect changes made to a specific document after they are persisted to the collection.

Note
If there are multiple CBLCollection instances on the same database file, each one's document listeners will be notified of changes made by other collection instances.
typedef void(* CBLCollectionDocumentChangeListener) (void *context, const CBLDocumentChange *change)
 A document change listener callback, invoked after a specific document is changed on disk. More...
 
_cbl_warn_unused CBLListenerTokenCBLCollection_AddDocumentChangeListener (const CBLCollection *collection, FLString docID, CBLCollectionDocumentChangeListener listener, void *_cbl_nullable context)
 Registers a document change listener callback. More...
 

Collection Management

CBL_PUBLIC const FLString kCBLDefaultCollectionName
 The default collection's name. More...
 
FLMutableArray _cbl_nullable CBLDatabase_ScopeNames (const CBLDatabase *db, CBLError *_cbl_nullable outError)
 Returns the names of all existing scopes in the database. More...
 
FLMutableArray _cbl_nullable CBLDatabase_CollectionNames (const CBLDatabase *db, FLString scopeName, CBLError *_cbl_nullable outError)
 Returns the names of all collections in the scope. More...
 
CBLScope *_cbl_nullable CBLDatabase_Scope (const CBLDatabase *db, FLString scopeName, CBLError *_cbl_nullable outError)
 Returns an existing scope with the given name. More...
 
CBLCollection *_cbl_nullable CBLDatabase_Collection (const CBLDatabase *db, FLString collectionName, FLString scopeName, CBLError *_cbl_nullable outError)
 Returns the existing collection with the given name and scope. More...
 
CBLCollection *_cbl_nullable CBLDatabase_CreateCollection (CBLDatabase *db, FLString collectionName, FLString scopeName, CBLError *_cbl_nullable outError)
 Create a new collection. More...
 
bool CBLDatabase_DeleteCollection (CBLDatabase *db, FLString collectionName, FLString scopeName, CBLError *_cbl_nullable outError)
 Delete an existing collection. More...
 
CBLScopeCBLDatabase_DefaultScope (const CBLDatabase *db, CBLError *_cbl_nullable outError)
 Returns the default scope. More...
 
CBLCollection *_cbl_nullable CBLDatabase_DefaultCollection (const CBLDatabase *db, CBLError *_cbl_nullable outError)
 Returns the default collection. More...
 

Collection Accessors

Getting information about a collection.

CBLScopeCBLCollection_Scope (const CBLCollection *collection)
 Returns the scope of the collection. More...
 
FLString CBLCollection_Name (const CBLCollection *collection)
 Returns the collection name. More...
 
uint64_t CBLCollection_Count (const CBLCollection *collection)
 Returns the number of documents in the collection. More...
 

Document lifecycle

_cbl_warn_unused const CBLDocument *_cbl_nullable CBLCollection_GetDocument (const CBLCollection *collection, FLString docID, CBLError *_cbl_nullable outError)
 Reads a document from the collection, creating a new (immutable) CBLDocument object. More...
 
bool CBLCollection_SaveDocument (CBLCollection *collection, CBLDocument *doc, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the collection. More...
 
bool CBLCollection_SaveDocumentWithConcurrencyControl (CBLCollection *collection, CBLDocument *doc, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the collection. More...
 
bool CBLCollection_SaveDocumentWithConflictHandler (CBLCollection *collection, CBLDocument *doc, CBLConflictHandler conflictHandler, void *_cbl_nullable context, CBLError *_cbl_nullable outError)
 Saves a (mutable) document to the collection, allowing for custom conflict handling in the event that the document has been updated since doc was loaded. More...
 
bool CBLCollection_DeleteDocument (CBLCollection *collection, const CBLDocument *document, CBLError *_cbl_nullable outError)
 Deletes a document from the collection. More...
 
bool CBLCollection_DeleteDocumentWithConcurrencyControl (CBLCollection *collection, const CBLDocument *document, CBLConcurrencyControl concurrency, CBLError *_cbl_nullable outError)
 Deletes a document from the collection. More...
 
bool CBLCollection_PurgeDocument (CBLCollection *collection, const CBLDocument *document, CBLError *_cbl_nullable outError)
 Purges a document. More...
 
bool CBLCollection_PurgeDocumentByID (CBLCollection *collection, FLString docID, CBLError *_cbl_nullable outError)
 Purges a document, given only its ID. More...
 
CBLTimestamp CBLCollection_GetDocumentExpiration (CBLCollection *collection, FLSlice docID, CBLError *_cbl_nullable outError)
 Returns the time, if any, at which a given document will expire and be purged. More...
 
bool CBLCollection_SetDocumentExpiration (CBLCollection *collection, FLSlice docID, CBLTimestamp expiration, CBLError *_cbl_nullable outError)
 Sets or clears the expiration time of a document. More...
 

Mutable documents

The type CBLDocument* without a const qualifier refers to a mutable document instance.

A mutable document exposes its properties as a mutable dictionary, so you can change them in place and then call CBLCollection_SaveDocument to persist the changes.

_cbl_warn_unused CBLDocument *_cbl_nullable CBLCollection_GetMutableDocument (CBLCollection *collection, FLString docID, CBLError *_cbl_nullable outError)
 Reads a document from the collection, in mutable form that can be updated and saved. More...
 

Query Indexes

bool CBLCollection_CreateValueIndex (CBLCollection *collection, FLString name, CBLValueIndexConfiguration config, CBLError *_cbl_nullable outError)
 Creates a value index in the collection. More...
 
bool CBLCollection_CreateFullTextIndex (CBLCollection *collection, FLString name, CBLFullTextIndexConfiguration config, CBLError *_cbl_nullable outError)
 Creates a full-text index in the collection. More...
 
bool CBLCollection_DeleteIndex (CBLCollection *collection, FLString name, CBLError *_cbl_nullable outError)
 Deletes an index in the collection by name. More...
 
_cbl_warn_unused FLMutableArray _cbl_nullable CBLCollection_GetIndexNames (CBLCollection *collection, CBLError *_cbl_nullable outError)
 Returns the names of the indexes in the collection, as a Fleece array of strings. More...
 

Detailed Description

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 namespce, 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:

CBLCollection Lifespan

CBLCollection is ref-counted. Same as the CBLDocument, the CBLCollection objects created or retrieved from the database must be released after you are done using them. When the database is closed or released, the collection objects will become invalid, most operations on the invalid CBLCollection object will fail with either the kCBLErrorNotOpen error or null/zero/empty result.

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

Typedef Documentation

◆ CBLCollection

typedef struct CBLCollection CBLCollection

A collection, a document container.

◆ CBLCollectionChangeListener

typedef void(* CBLCollectionChangeListener) (void *_cbl_nullable context, const CBLCollectionChange *change)

A collection change listener callback, invoked after one or more documents are changed on disk.

Warning
By default, this listener may be called on arbitrary threads. If your code isn't prepared for that, you may want to use CBLDatabase_BufferNotifications so that listeners will be called in a safe context.
Parameters
contextAn arbitrary value given when the callback was registered.
changeThe collection change information.

◆ CBLCollectionDocumentChangeListener

typedef void(* CBLCollectionDocumentChangeListener) (void *context, const CBLDocumentChange *change)

A document change listener callback, invoked after a specific document is changed on disk.

Warning
By default, this listener may be called on arbitrary threads. If your code isn't prepared for that, you may want to use CBLDatabase_BufferNotifications so that listeners will be called in a safe context.
Parameters
contextAn arbitrary value given when the callback was registered.
changeThe document change info.

Function Documentation

◆ CBLCollection_AddChangeListener()

_cbl_warn_unused CBLListenerToken * CBLCollection_AddChangeListener ( const CBLCollection collection,
CBLCollectionChangeListener  listener,
void *_cbl_nullable  context 
)

Registers a collection change listener callback.

It will be called after one or more documents are changed on disk.

Parameters
collectionThe collection to observe.
listenerThe callback to be invoked.
contextAn opaque value that will be passed to the callback.
Returns
A token to be passed to CBLListener_Remove when it's time to remove the listener.

◆ CBLCollection_AddDocumentChangeListener()

_cbl_warn_unused CBLListenerToken * CBLCollection_AddDocumentChangeListener ( const CBLCollection collection,
FLString  docID,
CBLCollectionDocumentChangeListener  listener,
void *_cbl_nullable  context 
)

Registers a document change listener callback.

It will be called after a specific document is changed on disk.

Parameters
collectionThe collection to observe.
docIDThe ID of the document to observe.
listenerThe callback to be invoked.
contextAn opaque value that will be passed to the callback.
Returns
A token to be passed to CBLListener_Remove when it's time to remove the listener.

◆ CBLCollection_Count()

uint64_t CBLCollection_Count ( const CBLCollection collection)

Returns the number of documents in the collection.

Parameters
collectionThe collection.
Returns
the number of documents in the collection.

◆ CBLCollection_CreateFullTextIndex()

bool CBLCollection_CreateFullTextIndex ( CBLCollection collection,
FLString  name,
CBLFullTextIndexConfiguration  config,
CBLError *_cbl_nullable  outError 
)

Creates a full-text index in the collection.

If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

Parameters
collectionThe collection.
nameThe name of the index.
configThe index configuration.
outErrorOn failure, an error is written here.
Returns
True on success, false on failure.

◆ CBLCollection_CreateValueIndex()

bool CBLCollection_CreateValueIndex ( CBLCollection collection,
FLString  name,
CBLValueIndexConfiguration  config,
CBLError *_cbl_nullable  outError 
)

Creates a value index in the collection.

If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

Parameters
collectionThe collection.
nameThe name of the index.
configThe index configuration.
outErrorOn failure, an error is written here.
Returns
True on success, false on failure.

◆ CBLCollection_DeleteDocument()

bool CBLCollection_DeleteDocument ( CBLCollection collection,
const CBLDocument document,
CBLError *_cbl_nullable  outError 
)

Deletes a document from the collection.

Deletions are replicated.

Warning
You are still responsible for releasing the CBLDocument.
Parameters
collectionThe collection containing the document.
documentThe document to delete.
outErrorOn failure, the error will be written here.
Returns
True if the document was deleted, false if an error occurred.

◆ CBLCollection_DeleteDocumentWithConcurrencyControl()

bool CBLCollection_DeleteDocumentWithConcurrencyControl ( CBLCollection collection,
const CBLDocument document,
CBLConcurrencyControl  concurrency,
CBLError *_cbl_nullable  outError 
)

Deletes a document from the collection.

Deletions are replicated.

Warning
You are still responsible for releasing the CBLDocument.
Parameters
collectionThe collection containing the document.
documentThe document to delete.
concurrencyConflict-handling strategy.
outErrorOn failure, the error will be written here.
Returns
True if the document was deleted, false if an error occurred.

◆ CBLCollection_DeleteIndex()

bool CBLCollection_DeleteIndex ( CBLCollection collection,
FLString  name,
CBLError *_cbl_nullable  outError 
)

Deletes an index in the collection by name.

Parameters
collectionThe collection.
nameThe name of the index.
outErrorOn failure, an error is written here.
Returns
True on success, false on failure.

◆ CBLCollection_GetDocument()

_cbl_warn_unused const CBLDocument *_cbl_nullable CBLCollection_GetDocument ( const CBLCollection collection,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Reads a document from the collection, creating a new (immutable) CBLDocument object.

Each call to this function creates a new object (which must later be released.)

Note
If you are reading the document in order to make changes to it, call CBLCollection_GetMutableDocument instead.
Parameters
collectionThe collection.
docIDThe ID of the document.
outErrorOn failure, the error will be written here. (A nonexistent document is not considered a failure; in that event the error code will be zero.)
Returns
A new CBLDocument instance, or NULL if the doc doesn't exist or an error occurred.

◆ CBLCollection_GetDocumentExpiration()

CBLTimestamp CBLCollection_GetDocumentExpiration ( CBLCollection collection,
FLSlice  docID,
CBLError *_cbl_nullable  outError 
)

Returns the time, if any, at which a given document will expire and be purged.

Documents don't normally expire; you have to call CBLCollection_SetDocumentExpiration to set a document's expiration time.

Parameters
collectionThe collection.
docIDThe ID of the document.
outErrorOn failure, an error is written here.
Returns
The expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document does not have an expiration, or -1 if the call failed.

◆ CBLCollection_GetIndexNames()

_cbl_warn_unused FLMutableArray _cbl_nullable CBLCollection_GetIndexNames ( CBLCollection collection,
CBLError *_cbl_nullable  outError 
)

Returns the names of the indexes in the collection, as a Fleece array of strings.

Note
You are responsible for releasing the returned Fleece array.
Parameters
collectionThe collection.
outErrorOn failure, an error is written here.
Returns
The index names in the collection, or NULL if an error occurred.

◆ CBLCollection_GetMutableDocument()

_cbl_warn_unused CBLDocument *_cbl_nullable CBLCollection_GetMutableDocument ( CBLCollection collection,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Reads a document from the collection, in mutable form that can be updated and saved.

(This function is otherwise identical to CBLCollection_GetDocument.)

Note
You must release the document when you're done with it.
Parameters
collectionThe collection.
docIDThe ID of the document.
outErrorOn failure, the error will be written here. (A nonexistent document is not considered a failure; in that event the error code will be zero.)
Returns
A new CBLDocument instance, or NULL if the doc doesn't exist or an error occurred.

◆ CBLCollection_Name()

FLString CBLCollection_Name ( const CBLCollection collection)

Returns the collection name.

Parameters
collectionThe collection.
Returns
The name of the collection.

◆ CBLCollection_PurgeDocument()

bool CBLCollection_PurgeDocument ( CBLCollection collection,
const CBLDocument document,
CBLError *_cbl_nullable  outError 
)

Purges a document.

This removes all traces of the document from the collection. Purges are not replicated. If the document is changed on a server, it will be re-created when pulled.

Warning
You are still responsible for releasing the CBLDocument reference.
Note
If you don't have the document in memory already, CBLCollection_PurgeDocumentByID is a simpler shortcut.
Parameters
collectionThe collection containing the document.
documentThe document to delete.
outErrorOn failure, the error will be written here.
Returns
True if the document was purged, false if it doesn't exist or the purge failed.

◆ CBLCollection_PurgeDocumentByID()

bool CBLCollection_PurgeDocumentByID ( CBLCollection collection,
FLString  docID,
CBLError *_cbl_nullable  outError 
)

Purges a document, given only its ID.

Note
If no document with that ID exists, this function will return false but the error code will be zero.
Parameters
collectionThe collection.
docIDThe document ID to purge.
outErrorOn failure, the error will be written here.
Returns
True if the document was purged, false if it doesn't exist or the purge failed.

◆ CBLCollection_Release()

static void CBLCollection_Release ( const CBLCollection t)
inlinestatic

◆ CBLCollection_Retain()

static const CBLCollection * CBLCollection_Retain ( const CBLCollection t)
inlinestatic

◆ CBLCollection_SaveDocument()

bool CBLCollection_SaveDocument ( CBLCollection collection,
CBLDocument doc,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the collection.

Warning
If a newer revision has been saved since the doc was loaded, it will be overwritten by this one. This can lead to data loss! To avoid this, call CBLCollection_SaveDocumentWithConcurrencyControl or CBLCollection_SaveDocumentWithConflictHandler instead.
Parameters
collectionThe collection to save to.
docThe mutable document to save.
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLCollection_SaveDocumentWithConcurrencyControl()

bool CBLCollection_SaveDocumentWithConcurrencyControl ( CBLCollection collection,
CBLDocument doc,
CBLConcurrencyControl  concurrency,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the collection.

If a conflicting revision has been saved since doc was loaded, the concurrency parameter specifies whether the save should fail, or the conflicting revision should be overwritten with the revision being saved. If you need finer-grained control, call CBLCollection_SaveDocumentWithConflictHandler instead.

Parameters
collectionThe collection to save to.
docThe mutable document to save.
concurrencyConflict-handling strategy (fail or overwrite).
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLCollection_SaveDocumentWithConflictHandler()

bool CBLCollection_SaveDocumentWithConflictHandler ( CBLCollection collection,
CBLDocument doc,
CBLConflictHandler  conflictHandler,
void *_cbl_nullable  context,
CBLError *_cbl_nullable  outError 
)

Saves a (mutable) document to the collection, allowing for custom conflict handling in the event that the document has been updated since doc was loaded.

Parameters
collectionThe collection to save to.
docThe mutable document to save.
conflictHandlerThe callback to be invoked if there is a conflict.
contextAn arbitrary value to be passed to the conflictHandler.
outErrorOn failure, the error will be written here.
Returns
True on success, false on failure.

◆ CBLCollection_Scope()

CBLScope * CBLCollection_Scope ( const CBLCollection collection)

Returns the scope of the collection.

Note
You are responsible for releasing the returned scope.
Parameters
collectionThe collection.
Returns
A CBLScope instance.

◆ CBLCollection_SetDocumentExpiration()

bool CBLCollection_SetDocumentExpiration ( CBLCollection collection,
FLSlice  docID,
CBLTimestamp  expiration,
CBLError *_cbl_nullable  outError 
)

Sets or clears the expiration time of a document.

Parameters
collectionThe collection.
docIDThe ID of the document.
expirationThe expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document should never expire.
outErrorOn failure, an error is written here.
Returns
True on success, false on failure.

◆ CBLDatabase_Collection()

CBLCollection *_cbl_nullable CBLDatabase_Collection ( const CBLDatabase db,
FLString  collectionName,
FLString  scopeName,
CBLError *_cbl_nullable  outError 
)

Returns the existing collection with the given name and scope.

Note
You are responsible for releasing the returned collection.
Parameters
dbThe database.
collectionNameThe name of the collection.
scopeNameThe name of the scope.
outErrorOn failure, the error will be written here.
Returns
A CBLCollection instance, or NULL if the collection doesn't exist or an error occurred.

◆ CBLDatabase_CollectionNames()

FLMutableArray _cbl_nullable CBLDatabase_CollectionNames ( const CBLDatabase db,
FLString  scopeName,
CBLError *_cbl_nullable  outError 
)

Returns the names of all collections in the scope.

Note
You are responsible for releasing the returned array.
Parameters
dbThe database.
scopeNameThe name of the scope.
outErrorOn failure, the error will be written here.
Returns
The names of all collections in the scope, or NULL if an error occurred.

◆ CBLDatabase_CreateCollection()

CBLCollection *_cbl_nullable CBLDatabase_CreateCollection ( CBLDatabase db,
FLString  collectionName,
FLString  scopeName,
CBLError *_cbl_nullable  outError 
)

Create a new collection.

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.
    Note
    If the collection already exists, the existing collection will be returned.
    You are responsible for releasing the returned collection.
    Parameters
    dbThe database.
    collectionNameThe name of the collection.
    scopeNameThe name of the scope.
    outErrorOn failure, the error will be written here.
    Returns
    A CBLCollection instance, or NULL if an error occurred.

◆ CBLDatabase_DefaultCollection()

CBLCollection *_cbl_nullable CBLDatabase_DefaultCollection ( const CBLDatabase db,
CBLError *_cbl_nullable  outError 
)

Returns the default collection.

Note
The default collection may not exist if it was deleted. Also, the default collection cannot be recreated after being deleted.
You are responsible for releasing the returned collection.
Parameters
dbThe database.
outErrorOn failure, the error will be written here.
Returns
A CBLCollection instance, or NULL if the default collection doesn't exist or an error occurred.

◆ CBLDatabase_DefaultScope()

CBLScope * CBLDatabase_DefaultScope ( const CBLDatabase db,
CBLError *_cbl_nullable  outError 
)

Returns the default scope.

Note
The default scope always exist even there are no collections under it.
You are responsible for releasing the returned scope.
Parameters
dbThe database.
outErrorOn failure, the error will be written here.
Returns
A CBLScope instance, or NULL if an error occurred.

◆ CBLDatabase_DeleteCollection()

bool CBLDatabase_DeleteCollection ( CBLDatabase db,
FLString  collectionName,
FLString  scopeName,
CBLError *_cbl_nullable  outError 
)

Delete an existing collection.

Note
The default collection cannot be deleted.
Parameters
dbThe database.
collectionNameThe name of the collection.
scopeNameThe name of the scope.
outErrorOn failure, the error will be written here.
Returns
True if success, or False if an error occurred.

◆ CBLDatabase_Scope()

CBLScope *_cbl_nullable CBLDatabase_Scope ( const CBLDatabase db,
FLString  scopeName,
CBLError *_cbl_nullable  outError 
)

Returns an existing scope with the given name.

The scope exists when there is at least one collection created under the scope. The default scope is exception in that it will always exists even there are no collections under it.

Note
You are responsible for releasing the returned scope.
Parameters
dbThe database.
scopeNameThe name of the scope.
outErrorOn failure, the error will be written here.
Returns
A CBLScope instance, or NULL if the scope doesn't exist or an error occurred.

◆ CBLDatabase_ScopeNames()

FLMutableArray _cbl_nullable CBLDatabase_ScopeNames ( const CBLDatabase db,
CBLError *_cbl_nullable  outError 
)

Returns the names of all existing scopes in the database.

The scope exists when there is at least one collection created under the scope. The default scope is exceptional in that it will always exists even there are no collections under it.

Note
You are responsible for releasing the returned array.
Parameters
dbThe database.
outErrorOn failure, the error will be written here.
Returns
The names of all existing scopes in the database, or NULL if an error occurred.

Variable Documentation

◆ kCBLDefaultCollectionName

CBL_PUBLIC const FLString kCBLDefaultCollectionName
extern

The default collection's name.