A Collection is a container for documents within a database. More...

#include <cbl++/Collection.hh>

Inheritance diagram for cbl::Collection:

Public Types
using	CollectionChangeListener = cbl::ListenerToken<CollectionChange*>
	Collection Change Listener Token.
using	CollectionDocumentChangeListener = cbl::ListenerToken<DocumentChange*>
	Document Change Listener Token.

Public Member Functions
std::string	name () const
	The collection's name.
std::string	fullName () const
	The collection's fully qualified name in the '<scope-name>.
std::string	scopeName () const
	The scope's name.
Database	database () const
	The collection's database.
uint64_t	count () const
	The number of documents in the collection.
Document	getDocument (std::string_view docID) const
	Reads a document from the collection in an immutable form.
MutableDocument	getMutableDocument (std::string_view docID) const
	Reads a document from the collection in mutable form that can be updated and saved.
void	saveDocument (MutableDocument &doc)
	Saves a (mutable) document to the collection.
bool	saveDocument (MutableDocument &doc, CBLConcurrencyControl concurrency)
	Saves a (mutable) document to the collection.
bool	saveDocument (MutableDocument &doc, CollectionConflictHandler handler)
	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.
void	deleteDocument (Document &doc)
	Deletes a document from the collection.
bool	deleteDocument (Document &doc, CBLConcurrencyControl concurrency)
	Deletes a document from the collection.
void	purgeDocument (Document &doc)
	Purges a document from the collection.
bool	purgeDocument (std::string_view docID)
	Purges a document by its ID from the collection.
time_t	getDocumentExpiration (std::string_view docID) const
	Returns the time, if any, at which a given document in the collection will expire and be purged.
void	setDocumentExpiration (std::string_view docID, time_t expiration)
	Sets or clears the expiration time of a document in the collection.
void	createValueIndex (std::string_view name, ValueIndexConfiguration config)
	Creates a value index in the collection.
void	createFullTextIndex (std::string_view name, FullTextIndexConfiguration config)
	Creates a full-text index in the collection.
void	createArrayIndex (std::string_view name, ArrayIndexConfiguration config)
	Creates an array index for use with UNNEST queries in the collection.
void	createVectorIndex (std::string_view name, VectorIndexConfiguration config)
	Creates a vector index in the collection.
void	deleteIndex (std::string_view name)
	Deletes an index given its name from the collection.
fleece::RetainedArray	getIndexNames ()
	Returns the names of the indexes in the collection, as a Fleece array of strings.
QueryIndex	getIndex (std::string_view name)
	Get an index by name.
CollectionChangeListener	addChangeListener (CollectionChangeListener::Callback callback)
	Registers a collection change listener callback.
CollectionDocumentChangeListener	addDocumentChangeListener (std::string_view docID, CollectionDocumentChangeListener::Callback callback)
	Registers a document change listener callback.
	Collection () noexcept
	Constructs a null reference (one that points to no object).
Collection &	operator= (std::nullptr_t)
	Releases the underlying object and resets this to a null reference.
bool	valid () const
	Returns true if this references an object, or false if it is a null reference.
	operator bool () const
	Returns true if this references an object (same as valid).
bool	operator== (const Collection &other) const
	Returns true if both sides reference the same object, or are both null references.
bool	operator!= (const Collection &other) const
	Returns true if the two sides reference different objects.
CBLCollection *_Nullable	ref () const
	Returns a pointer to the underlying C object (CBLCollection), or NULL if this is a null reference.
	Collection (const Collection &other) noexcept
	Copy constructor: creates another reference to the same object as `other`.
	Collection (Collection &&other) noexcept
	Move constructor: takes over the reference from `other`, leaving it a null reference.
Collection &	operator= (const Collection &other) noexcept
	Copy assignment: replaces this reference with a reference to `other's` object.
Collection &	operator= (Collection &&other) noexcept
	Move assignment: replaces this reference with `other's`, leaving `other` a null reference.

Protected Member Functions
	Collection (CBLCollection *_Nullable ref)
	(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Static Protected Member Functions
static Collection	adopt (const CBLCollection _Nullable d, CBLError error)

Friends
class	Database
class	Document
class	QueryIndex

Detailed Description

A Collection is a container for documents within a database.

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". You may decide to delete the default collection, but noted that the default collection cannot be re-created. The name of the default collection and scope can be referenced by using kCBLDefaultCollectionName and kCBLDefaultScopeName constant.

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:

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.

Member Typedef Documentation

◆ CollectionChangeListener

using cbl::Collection::CollectionChangeListener = cbl::ListenerToken<CollectionChange*>

Collection Change Listener Token.

◆ CollectionDocumentChangeListener

using cbl::Collection::CollectionDocumentChangeListener = cbl::ListenerToken<DocumentChange*>

Document Change Listener Token.

Constructor & Destructor Documentation

◆ Collection() [1/4]

cbl::Collection::Collection ( )

inlinenoexcept

Constructs a null reference (one that points to no object).

◆ Collection() [2/4]

cbl::Collection::Collection ( CBLCollection *_Nullable ref )

inlineexplicitprotected

(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

◆ Collection() [3/4]

cbl::Collection::Collection ( const Collection & other )

inlinenoexcept

Copy constructor: creates another reference to the same object as other.

◆ Collection() [4/4]

cbl::Collection::Collection ( Collection && other )

inlinenoexcept

Move constructor: takes over the reference from other, leaving it a null reference.

Member Function Documentation

◆ addChangeListener()

CollectionChangeListener cbl::Collection::addChangeListener ( CollectionChangeListener::Callback callback )

inlinenodiscard

Registers a collection change listener callback.

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

Parameters

callback The callback to be invoked.

Returns: A Change Listener Token. Call ListenerToken::remove() method to remove the listener.

◆ addDocumentChangeListener()

CollectionDocumentChangeListener cbl::Collection::addDocumentChangeListener	(	std::string_view	docID,
		CollectionDocumentChangeListener::Callback	callback )

inlinenodiscard

Registers a document change listener callback.

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

Parameters

docID	The ID of the document to observe.
callback	The callback to be invoked.

Returns: A Change Listener Token. Call ListenerToken::remove() method to remove the listener.

◆ adopt()

Collection cbl::Collection::adopt	(	const CBLCollection *_Nullable	d,
		CBLError *	error )

inlinestaticprotected

◆ count()

uint64_t cbl::Collection::count ( ) const

inline

The number of documents in the collection.

◆ createArrayIndex()

void cbl::Collection::createArrayIndex	(	std::string_view	name,
		ArrayIndexConfiguration	config )

inline

Creates an array index for use with UNNEST queries in the collection.

Indexes are persistent. 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

name	The index name.
config	The array index config.

◆ createFullTextIndex()

void cbl::Collection::createFullTextIndex	(	std::string_view	name,
		FullTextIndexConfiguration	config )

inline

Creates a full-text index in the collection.

Indexes are persistent. 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

name	The index name.
config	The full-text index config.

◆ createValueIndex()

void cbl::Collection::createValueIndex	(	std::string_view	name,
		ValueIndexConfiguration	config )

inline

Creates a value index in the collection.

Indexes are persistent. 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

name	The index name.
config	The value index config.

◆ createVectorIndex()

void cbl::Collection::createVectorIndex	(	std::string_view	name,
		VectorIndexConfiguration	config )

inline

Creates a vector 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.

Note: ENTERPRISE EDITION ONLY

Parameters

name	The index name.
config	The vector index config.

◆ database()

Database cbl::Collection::database ( ) const

inline

The collection's database.

◆ deleteDocument() [1/2]

void cbl::Collection::deleteDocument ( Document & doc )

inline

Deletes a document from the collection.

Deletions are replicated.

Parameters

doc	The document to delete.

◆ deleteDocument() [2/2]

bool cbl::Collection::deleteDocument	(	Document &	doc,
		CBLConcurrencyControl	concurrency )

inline

Deletes a document from the collection.

Deletions are replicated.

Parameters

doc	The document to delete.
concurrency	Conflict-handling strategy.

Returns: True on success, false on failure.

◆ deleteIndex()

void cbl::Collection::deleteIndex ( std::string_view name )

inline

Deletes an index given its name from the collection.

◆ fullName()

std::string cbl::Collection::fullName ( ) const

inline

The collection's fully qualified name in the '<scope-name>.

<collection-name>' format.

◆ getDocument()

Document cbl::Collection::getDocument ( std::string_view docID ) const

inline

Reads a document from the collection in an immutable form.

Note: If you are reading the document in order to make changes to it, call Collection::getMutableDocument() instead.

Parameters

docID The ID of the document.

Returns: A new Document instance, or a falsy Document if the doc doesn't exist.

Exceptions

cbl::Error On a database error. Note a non-existent document is not an error — that returns a falsy Document rather than throwing.

◆ getDocumentExpiration()

time_t cbl::Collection::getDocumentExpiration ( std::string_view docID ) const

inline

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

Documents don't normally expire; you have to call Collection::setDocumentExpiration(std::string_view docID, time_t expiration) to set a document's expiration time.

Parameters

docID The ID of the document.

Returns: The expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document does not have an expiration.

◆ getIndex()

QueryIndex cbl::Collection::getIndex ( std::string_view name )

inline

Get an index by name.

If the index doesn't exist, a falsy QueryIndex object will be returned.

◆ getIndexNames()

fleece::RetainedArray cbl::Collection::getIndexNames ( )

inline

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

◆ getMutableDocument()

MutableDocument cbl::Collection::getMutableDocument ( std::string_view docID ) const

inline

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

(This function is otherwise identical to Collection::getDocument.)

Parameters

docID The ID of the document.

Returns: A new Document instance, or a falsy Document if the doc doesn't exist.

Exceptions

cbl::Error On a database error. Note a non-existent document is not an error — that returns a falsy Document rather than throwing.

◆ name()

std::string cbl::Collection::name ( ) const

inline

The collection's name.

◆ operator bool()

cbl::Collection::operator bool ( ) const

inlineexplicit

Returns true if this references an object (same as valid).

◆ operator!=()

bool cbl::Collection::operator!= ( const Collection & other ) const

inline

Returns true if the two sides reference different objects.

◆ operator=() [1/3]

Collection & cbl::Collection::operator= ( Collection && other )

inlinenoexcept

Move assignment: replaces this reference with other's, leaving other a null reference.

◆ operator=() [2/3]

Collection & cbl::Collection::operator= ( const Collection & other )

inlinenoexcept

Copy assignment: replaces this reference with a reference to other's object.

◆ operator=() [3/3]

Collection & cbl::Collection::operator= ( std::nullptr_t )

inline

Releases the underlying object and resets this to a null reference.

◆ operator==()

bool cbl::Collection::operator== ( const Collection & other ) const

inline

Returns true if both sides reference the same object, or are both null references.

◆ purgeDocument() [1/2]

void cbl::Collection::purgeDocument ( Document & doc )

inline

Purges a document from the collection.

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

Note: If you don't have the document in memory already, purgeDocument(std::string_view docID) is a simpler shortcut.

Parameters

doc	The document to purge.

◆ purgeDocument() [2/2]

bool cbl::Collection::purgeDocument ( std::string_view docID )

inline

Purges a document by its ID from the collection.

Parameters

docID The document ID to purge.

Returns: True if the document was purged, false if it doesn't exist.

◆ ref()

CBLCollection *_Nullable cbl::Collection::ref ( ) const

inline

Returns a pointer to the underlying C object (CBLCollection), or NULL if this is a null reference.

◆ saveDocument() [1/3]

void cbl::Collection::saveDocument ( MutableDocument & doc )

inline

Saves a (mutable) document to the collection.

Warning: If a newer revision has been saved since doc was loaded, it will be overwritten by this one. This can lead to data loss! To avoid this, call Collection::saveDocument(MutableDocument &doc, CBLConcurrencyControl concurrency) Collection::saveDocument(MutableDocument &doc, ConflictHandler handler) instead.

Parameters

doc	The mutable document to save.

◆ saveDocument() [2/3]

bool cbl::Collection::saveDocument	(	MutableDocument &	doc,
		CBLConcurrencyControl	concurrency )

inline

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 Collection::saveDocument(MutableDocument &doc, ConflictHandler handler) instead.

Parameters

doc	The mutable document to save.
concurrency	Conflict-handling strategy (fail or overwrite).

Returns: True on success, false on failure.

◆ saveDocument() [3/3]

bool cbl::Collection::saveDocument	(	MutableDocument &	doc,
		CollectionConflictHandler	handler )

inline

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

doc	The mutable document to save.
handler	The callback to be invoked if there is a conflict.

Returns: True on success, false on failure.

◆ scopeName()

std::string cbl::Collection::scopeName ( ) const

inline

The scope's name.

◆ setDocumentExpiration()

void cbl::Collection::setDocumentExpiration	(	std::string_view	docID,
		time_t	expiration )

inline

Sets or clears the expiration time of a document in the collection.

Parameters

docID	The ID of the document.
expiration	The expiration time as a CBLTimestamp (milliseconds since Unix epoch), or 0 if the document should never expire.

◆ valid()

bool cbl::Collection::valid ( ) const

inline

Returns true if this references an object, or false if it is a null reference.

◆ Database

friend class Database

friend

◆ Document

friend class Document

friend

◆ QueryIndex

friend class QueryIndex

friend

The documentation for this class was generated from the following files:

include/cbl++/Collection.hh
include/cbl++/Document.hh
include/cbl++/QueryIndex.hh
include/cbl++/VectorIndex.hh

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ CollectionChangeListener

◆ CollectionDocumentChangeListener

Constructor & Destructor Documentation

◆ Collection() [1/4]

◆ Collection() [2/4]

◆ Collection() [3/4]

◆ Collection() [4/4]

Member Function Documentation

◆ addChangeListener()

◆ addDocumentChangeListener()

◆ adopt()

◆ count()

◆ createArrayIndex()

◆ createFullTextIndex()

◆ createValueIndex()

◆ createVectorIndex()

◆ database()

◆ deleteDocument() [1/2]

◆ deleteDocument() [2/2]

◆ deleteIndex()

◆ fullName()

◆ getDocument()

◆ getDocumentExpiration()

◆ getIndex()

◆ getIndexNames()

◆ getMutableDocument()

◆ name()

◆ operator bool()

◆ operator!=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ purgeDocument() [1/2]

◆ purgeDocument() [2/2]

◆ ref()

◆ saveDocument() [1/3]

◆ saveDocument() [2/3]

◆ saveDocument() [3/3]

◆ scopeName()

◆ setDocumentExpiration()

◆ valid()

Friends And Related Symbol Documentation

◆ Database

◆ Document

◆ QueryIndex