RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://couchbase.github.io/couchbase-lite-core/C/html/group___collection.html below:

LiteCore: Collections and Scopes

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

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

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.