A C4Collection represents a Collection, a named grouping of documents in a database. More...

Lifecycle
CBL_CORE_API C4Collection *	c4db_getDefaultCollection (C4Database db, C4Error outError)
	Returns the default collection, whose name is "`_default`" (`kC4DefaultCollectionName`).

CBL_CORE_API bool	c4db_hasCollection (C4Database *db, C4CollectionSpec spec)
	Returns true if the collection exists.

CBL_CORE_API bool	c4db_hasScope (C4Database *db, C4String name)
	Returns true if the named scope exists.

CBL_CORE_API C4Collection *	c4db_getCollection (C4Database db, C4CollectionSpec spec, C4Error outError)
	Returns the existing collection with the given name & scope, or NULL if it doesn't exist.

NODISCARD CBL_CORE_API C4Collection *	c4db_createCollection (C4Database db, C4CollectionSpec spec, C4Error outError)
	Creates and returns an empty collection with the given name & scope.

NODISCARD CBL_CORE_API bool	c4db_deleteCollection (C4Database db, C4CollectionSpec spec, C4Error outError)
	Deletes the collection with the given name & scope.

NODISCARD CBL_CORE_API FLMutableArray	c4db_collectionNames (C4Database db, C4String inScope, C4Error outError)
	Returns the names of all existing collections in the given scope, in the order in which they were created.

NODISCARD CBL_CORE_API FLMutableArray	c4db_scopeNames (C4Database db, C4Error outError)
	Returns the names of all existing scopes, in the order in which they were created.

Accessors
CBL_CORE_API bool	c4coll_isValid (C4Collection *)
	Returns false if this collection has been deleted, or its database closed.

CBL_CORE_API C4CollectionSpec	c4coll_getSpec (C4Collection *)
	Returns the name and scope of the collection.

CBL_CORE_API C4Database *	c4coll_getDatabase (C4Collection *)
	Returns the database containing the collection, or NULL if the collection is invalid.

CBL_CORE_API uint64_t	c4coll_getDocumentCount (C4Collection *)
	Returns the number of (undeleted) documents in the collection.

CBL_CORE_API C4SequenceNumber	c4coll_getLastSequence (C4Collection *)
	Returns the latest sequence number allocated to a revision.

Documents
NODISCARD CBL_CORE_API C4Document *	c4coll_getDoc (C4Collection collection, C4String docID, bool mustExist, C4DocContentLevel content, C4Error outError)
	Gets a document from the collection given its ID.

NODISCARD CBL_CORE_API C4Document *	c4coll_getDocBySequence (C4Collection collection, C4SequenceNumber, C4Error outError)
	Gets a document from the collection given its sequence number.

NODISCARD CBL_CORE_API C4Document *	c4coll_putDoc (C4Collection collection, const C4DocPutRequest request, size_t outCommonAncestorIndex, C4Error outError)
	A high-level Put operation, to insert a new or downloaded revision.

NODISCARD CBL_CORE_API C4Document *	c4coll_createDoc (C4Collection collection, C4String docID, C4Slice body, C4RevisionFlags revisionFlags, C4Error error)
	Convenience function to create a new document.

NODISCARD CBL_CORE_API bool	c4coll_moveDoc (C4Collection collection, C4String docID, C4Collection toCollection, C4String newDocID, C4Error *error)
	Moves a document to another collection, possibly with a different docID.

Purging and Expiration
NODISCARD CBL_CORE_API bool	c4coll_purgeDoc (C4Collection collection, C4String docID, C4Error outError)
	Removes all trace of a document and its revisions from the collection.

NODISCARD CBL_CORE_API bool	c4coll_setDocExpiration (C4Collection collection, C4String docID, C4Timestamp timestamp, C4Error outError)
	Sets an expiration date on a document.

CBL_CORE_API C4Timestamp	c4coll_getDocExpiration (C4Collection collection, C4String docID, C4Error outError)
	Returns the expiration time of a document, if one has been set, else 0.

CBL_CORE_API C4Timestamp	c4coll_nextDocExpiration (C4Collection *)
	Returns the time at which the next document expiration in this collection should take place, or 0 if there are no documents with expiration times.

NODISCARD CBL_CORE_API int64_t	c4coll_purgeExpiredDocs (C4Collection , C4Error )
	Purges all documents that have expired.

Detailed Description

A C4Collection represents a Collection, a named grouping of documents in a database.

You can think of them as "folders" or "directories" for documents, or as SQL tables.

Each Collection provides:

a namespace for documents (a "docID" is only unique within its Collection)
a queryable container, named in FROM and JOIN clauses.
a scope for indexes
a scope for document enumerators
independent sequence numbers

Likewise, a Scope is a grouping of Collections, like a "parent folder".

Every database starts with a default Collection, whose name is _default, which exists in a default Scope, also named _default. If the database was created by an earlier version of LiteCore, all existing documents will be in the default Collection.

Collection Naming

In this API, collections are named by a C4CollectionSpec struct, which simply contains two FLStrings, first a collection name and second a scope name. Note that the collection name comes first (unlike in a N1QL query), so that the scope name can be left out if you're referring to the default scope. You can give a collection spec literally as e.g. {C4STR("mycoll")}, or with a scope, {C4STR("mycoll"), C4STR("myscope")}.

There are no API calls to create or delete Scopes. A Scope is created implicitly when you create the first Collection inside it, and deleted implicitly when you delete its last Collection.

Legacy `C4Database` Functions

Pre-existing functions that refer to documents / sequences / indexes without referring to Collections – such as c4doc_get and c4db_getLastSequence – still exist, but 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 functions will eventually be deprecated, then removed. As an aid in updating your code, you can define the C preprocessor symbol C4_STRICT_COLLECTION_API to suppress the definitions of those functions, which will turn all calls to them into errors.

`C4Collection` Lifespan

C4Collection is ref-counted, but most of the time you don't need to retain or release it. The C4Database owns its collections, so a C4Collection reference remains valid until either the database is closed, or that collection is deleted. At that point it becomes a dangling pointer :( If you keep a collection reference long-term, you should retain it so that the reference remains valid until you release it.

A retained C4Collection object still becomes invalid after it's deleted or its database closes. After that, most operations on it will fail (safely), returning kC4ErrorNotOpen or some null/zero result. You can tell whether a C4Collection is valid by calling c4coll_isValid, or by checking whether c4coll_getDatabase returns non-NULL.

Function Documentation

◆ c4coll_createDoc()

NODISCARD CBL_CORE_API C4Document * c4coll_createDoc	(	C4Collection *	collection,
		C4String	docID,
		C4Slice	body,
		C4RevisionFlags	revisionFlags,
		C4Error *	error )

Convenience function to create a new document.

This just a wrapper around c4coll_putDoc. If the document already exists, it will fail with the error kC4ErrorConflict.

Note: The caller must use a lock for Database when this function is called.; You must call c4doc_release when finished with the document.

Parameters

collection	The collection to create the document in
docID	Document ID to create; if null, a UUID will be generated
body	Body of the document
revisionFlags	The flags of the new revision
error	Information about any error that occurred

Returns: On success, a new C4Document with the new revision selected; else NULL.

◆ c4coll_getDatabase()

CBL_CORE_API C4Database * c4coll_getDatabase ( C4Collection * )

Returns the database containing the collection, or NULL if the collection is invalid.

Note: This function is thread-safe.

◆ c4coll_getDoc()

NODISCARD CBL_CORE_API C4Document * c4coll_getDoc	(	C4Collection *	collection,
		C4String	docID,
		bool	mustExist,
		C4DocContentLevel	content,
		C4Error *	outError )

Gets a document from the collection given its ID.

The current revision is selected (if the document exists.)

Note: The caller must use a lock for Database when this function is called.; You must call c4doc_release when finished with the document.

Parameters

collection	The collection to read from.
docID	The document's ID.
mustExist	Governs behavior if no document with that ID exists. If true, the call fails with error kC4NotFound. If false, a C4Document with no contents is returned.
content	How much content to retrieve: metadata only, current revision, or all revisions.
outError	On failure, error information is stored here.

Returns: A new C4Document instance (which must be released), or NULL.

◆ c4coll_getDocBySequence()

NODISCARD CBL_CORE_API C4Document * c4coll_getDocBySequence	(	C4Collection *	collection,
		C4SequenceNumber	,
		C4Error *	outError )

Gets a document from the collection given its sequence number.

Note: The caller must use a lock for Database when this function is called.; You must call c4doc_release() when finished with the document.

◆ c4coll_getDocExpiration()

CBL_CORE_API C4Timestamp c4coll_getDocExpiration	(	C4Collection *	collection,
		C4String	docID,
		C4Error *	outError )

Returns the expiration time of a document, if one has been set, else 0.

Note: The caller must use a lock for Database when this function is called.

Parameters

collection	The collection to set the expiration date in
docID	The ID of the document to check
outError	Information about any error that occurred

Returns: The timestamp of the expiration date, in milliseconds since 1/1/1970, or 0 if the document does not expire, or -1 if an error occurred.

◆ c4coll_getDocumentCount()

CBL_CORE_API uint64_t c4coll_getDocumentCount ( C4Collection * )

Returns the number of (undeleted) documents in the collection.

Note: The caller must use a lock for Database when this function is called.

◆ c4coll_getLastSequence()

CBL_CORE_API C4SequenceNumber c4coll_getLastSequence ( C4Collection * )

Returns the latest sequence number allocated to a revision.

Note: The caller must use a lock for Database when this function is called.

◆ c4coll_getSpec()

CBL_CORE_API C4CollectionSpec c4coll_getSpec ( C4Collection * )

Returns the name and scope of the collection.

Note: This function is thread-safe.

◆ c4coll_isValid()

CBL_CORE_API bool c4coll_isValid ( C4Collection * )

Returns false if this collection has been deleted, or its database closed.

Note: This function is thread-safe.

◆ c4coll_moveDoc()

NODISCARD CBL_CORE_API bool c4coll_moveDoc	(	C4Collection *	collection,
		C4String	docID,
		C4Collection *	toCollection,
		C4String	newDocID,
		C4Error *	error )

Moves a document to another collection, possibly with a different docID.

Note: The caller must use a lock for Database when this function is called.

Parameters

collection	The document's original collection.
docID	The ID of the document to move.
toCollection	The collection to move to.
newDocID	The docID in the new collection, or a NULL slice to keep the original ID.
error	Information about any error that occurred

Returns: True on success, false on failure.

◆ c4coll_nextDocExpiration()

CBL_CORE_API C4Timestamp c4coll_nextDocExpiration ( C4Collection * )

Returns the time at which the next document expiration in this collection should take place, or 0 if there are no documents with expiration times.

Note: The caller must use a lock for Database when this function is called.

◆ c4coll_purgeDoc()

NODISCARD CBL_CORE_API bool c4coll_purgeDoc	(	C4Collection *	collection,
		C4String	docID,
		C4Error *	outError )

Removes all trace of a document and its revisions from the collection.

Note: The caller must use a lock for Database when this function is called.

◆ c4coll_purgeExpiredDocs()

NODISCARD CBL_CORE_API int64_t c4coll_purgeExpiredDocs	(	C4Collection *	,
		C4Error *	)

Purges all documents that have expired.

Returns: The number of documents purged, or -1 on error.

Note: The caller must use a lock for Database when this function is called.

◆ c4coll_putDoc()

NODISCARD CBL_CORE_API C4Document * c4coll_putDoc	(	C4Collection *	collection,
		const C4DocPutRequest *	request,
		size_t *	outCommonAncestorIndex,
		C4Error *	outError )

A high-level Put operation, to insert a new or downloaded revision.

If request->existingRevision is true, then request->history must contain the revision's history, with the revision's ID as the first item.
Otherwise, a new revision will be created and assigned a revID. The parent revision ID, if any, should be given as the single item of request->history. Either way, on success the document is returned with the inserted revision selected.

Note that actually saving the document back to the database is optional – it only happens if request->save is true. You can set this to false if you want to review the changes before saving, e.g. to run them through a validation function.

Note: The caller must use a lock for Database when this function is called.; You must call c4doc_release when finished with the returned document.

◆ c4coll_setDocExpiration()

NODISCARD CBL_CORE_API bool c4coll_setDocExpiration	(	C4Collection *	collection,
		C4String	docID,
		C4Timestamp	timestamp,
		C4Error *	outError )

Sets an expiration date on a document.

After this time the document will be purged from the database.

Note: The caller must use a lock for Database when this function is called.

Parameters

collection	The collection to set the expiration date in
docID	The ID of the document to set the expiration date for
timestamp	The timestamp of the expiration date, in milliseconds since 1/1/1970. A value of 0 indicates that the expiration should be cancelled.
outError	Information about any error that occurred

Returns: true on sucess, false on failure

◆ c4db_collectionNames()

NODISCARD CBL_CORE_API FLMutableArray c4db_collectionNames	(	C4Database *	db,
		C4String	inScope,
		C4Error *	outError )

Returns the names of all existing collections in the given scope, in the order in which they were created.

Note: The caller must use a lock for Database when this function is called.; You are responsible for releasing the returned Fleece array.

◆ c4db_createCollection()

NODISCARD CBL_CORE_API C4Collection * c4db_createCollection	(	C4Database *	db,
		C4CollectionSpec	spec,
		C4Error *	outError )

Creates and returns an empty collection with the given name & scope.

If the collection already exists, it just returns it. If the scope doesn't exist, it is implicitly created.

Note: The caller must use a lock for Database when this function is called.; Be sure to read C4Collection Lifespan in c4Collection.h.

◆ c4db_deleteCollection()

NODISCARD CBL_CORE_API bool c4db_deleteCollection	(	C4Database *	db,
		C4CollectionSpec	spec,
		C4Error *	outError )

Deletes the collection with the given name & scope.

Deleting the last collection from a scope implicitly deletes the scope.

Note: The caller must use a lock for Database when this function is called.; It is legal to delete the default collection, but it cannot be re-created.

◆ c4db_getCollection()

CBL_CORE_API C4Collection * c4db_getCollection	(	C4Database *	db,
		C4CollectionSpec	spec,
		C4Error *	outError )

Returns the existing collection with the given name & scope, or NULL if it doesn't exist.

Note: The caller must use a lock for Database when this function is called.; Be sure to read C4Collection Lifespan in c4Collection.h.

◆ c4db_getDefaultCollection()

CBL_CORE_API C4Collection * c4db_getDefaultCollection	(	C4Database *	db,
		C4Error *	outError )

Returns the default collection, whose name is "`_default`" (kC4DefaultCollectionName).

This is the one collection that exists in every newly created database. When a pre-existing database is upgraded to support collections, all its documents are put in the default collection.

Note: This function is thread-safe.; Be sure to read C4Collection Lifespan in c4Collection.h.

◆ c4db_hasCollection()

CBL_CORE_API bool c4db_hasCollection	(	C4Database *	db,
		C4CollectionSpec	spec )

Returns true if the collection exists.

Note: The caller must use a lock for Database when this function is called.

◆ c4db_hasScope()

CBL_CORE_API bool c4db_hasScope	(	C4Database *	db,
		C4String	name )

Returns true if the named scope exists.

Note that _default will always return true.

Note: The caller must use a lock for Database when this function is called.

◆ c4db_scopeNames()

NODISCARD CBL_CORE_API FLMutableArray c4db_scopeNames	(	C4Database *	db,
		C4Error *	outError )

Returns the names of all existing scopes, in the order in which they were created.

Note: The caller must use a lock for Database when this function is called.; You are responsible for releasing the returned Fleece array.

Lifecycle

Accessors

Documents

Purging and Expiration

Detailed Description

Collection Naming

Legacy C4Database Functions

C4Collection Lifespan

Other Documentation

Function Documentation

◆ c4coll_createDoc()

◆ c4coll_getDatabase()

◆ c4coll_getDoc()

◆ c4coll_getDocBySequence()

◆ c4coll_getDocExpiration()

◆ c4coll_getDocumentCount()

◆ c4coll_getLastSequence()

◆ c4coll_getSpec()

◆ c4coll_isValid()

◆ c4coll_moveDoc()

◆ c4coll_nextDocExpiration()

◆ c4coll_purgeDoc()

◆ c4coll_purgeExpiredDocs()

◆ c4coll_putDoc()

◆ c4coll_setDocExpiration()

◆ c4db_collectionNames()

◆ c4db_createCollection()

◆ c4db_deleteCollection()

◆ c4db_getCollection()

◆ c4db_getDefaultCollection()

◆ c4db_hasCollection()

◆ c4db_hasScope()

◆ c4db_scopeNames()

Legacy `C4Database` Functions

`C4Collection` Lifespan