Collections and Scopes

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.

Indexes
NODISCARD CBL_CORE_API bool	c4coll_createIndex (C4Collection *collection, C4String name, C4String indexSpec, C4QueryLanguage queryLanguage, C4IndexType indexType, const C4IndexOptions *indexOptions, C4Error *outError)
	Creates a collection index, of the values of specific expressions across all documents.
NODISCARD CBL_CORE_API bool	c4coll_deleteIndex (C4Collection *collection, C4String name, C4Error *outError)
	Deletes an index that was created by c4coll_createIndex.
CBL_CORE_API C4SliceResult	c4coll_getIndexesInfo (C4Collection *collection, C4Error *outError)
	Returns information about all indexes in the collection.

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.

Other Documentation

A few Collection functions are documented in other sections of the API docs:

• Enumeration-related functions (in c4DocEnumerator.h):
  • c4coll_enumerateChanges
  • c4coll_enumerateAllDocs
• Observer-related functions (in c4Observer.h):
  • c4dbobs_createOnCollection
  • c4docobs_createWithCollection

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

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_createIndex()

NODISCARD CBL_CORE_API bool c4coll_createIndex	(	C4Collection *	collection,
		C4String	name,
		C4String	indexSpec,
		C4QueryLanguage	queryLanguage,
		C4IndexType	indexType,
		const C4IndexOptions *	indexOptions,
		C4Error *	outError
	)

Creates a collection index, of the values of specific expressions across all documents.

The name is used to identify the index for later updating or deletion; if an index with the same name already exists, it will be replaced unless it has the exact same expressions.

Parameters

collection	The collection to index.
name	The name of the index. Any existing index with the same name will be replaced, unless it has the identical expressions (in which case this is a no-op.)
indexSpec	The definition of the index in JSON or N1QL form. (See above.)
queryLanguage	The language of indexSpec, either JSON or N1QL.
indexType	The type of index (value or full-text.)
indexOptions	Options for the index. If NULL, each option will get a default value.
outError	On failure, will be set to the error status.

Returns

True on success, false on failure.

c4coll_deleteIndex()

NODISCARD CBL_CORE_API bool c4coll_deleteIndex	(	C4Collection *	collection,
		C4String	name,
		C4Error *	outError
	)

Deletes an index that was created by c4coll_createIndex.

Parameters

collection	The collection to index.
name	The name of the index to delete
outError	On failure, will be set to the error status.

Returns

True on success, false on failure.

c4coll_getDatabase()

CBL_CORE_API C4Database * c4coll_getDatabase

(

C4Collection *

)

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

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

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

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.

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.

c4coll_getIndexesInfo()

CBL_CORE_API C4SliceResult c4coll_getIndexesInfo	(	C4Collection *	collection,
		C4Error *	outError
	)

Returns information about all indexes in the collection.

The result is a Fleece-encoded array of dictionaries, one per index. Each dictionary has keys "name", "type" (a C4IndexType), and "expr" (the source expression).

Parameters

collection	The collection to check
outError	On failure, will be set to the error status.

Returns

A Fleece-encoded array of dictionaries, or NULL on failure.

c4coll_getLastSequence()

CBL_CORE_API C4SequenceNumber c4coll_getLastSequence

(

C4Collection *

)

Returns the latest sequence number allocated to a revision.

c4coll_getSpec()

CBL_CORE_API C4CollectionSpec c4coll_getSpec

(

C4Collection *

)

Returns the name and scope of the collection.

c4coll_isValid()

CBL_CORE_API bool c4coll_isValid

(

C4Collection *

)

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

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.

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.

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.

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.

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

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.

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

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

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

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

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

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.

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.

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

You are responsible for releasing the returned Fleece array.