A CBLCollection represent a collection which is a container for documents.
More...
|
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...
|
|
CBLScope * | CBLDatabase_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...
|
|
|
_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...
|
|
|
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...
|
|
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:
- 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.
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.
◆ CBLCollection
A collection, a document container.
◆ CBLCollectionChangeListener
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
-
context | An arbitrary value given when the callback was registered. |
change | The 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
-
context | An arbitrary value given when the callback was registered. |
change | The document change info. |
◆ CBLCollection_AddChangeListener()
Registers a collection change listener callback.
It will be called after one or more documents are changed on disk.
- Parameters
-
collection | The collection to observe. |
listener | The callback to be invoked. |
context | An 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()
Registers a document change listener callback.
It will be called after a specific document is changed on disk.
- Parameters
-
collection | The collection to observe. |
docID | The ID of the document to observe. |
listener | The callback to be invoked. |
context | An 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()
Returns the number of documents in the collection.
- Parameters
-
collection | The collection. |
- Returns
- the number of documents in the collection.
◆ CBLCollection_CreateFullTextIndex()
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
-
collection | The collection. |
name | The name of the index. |
config | The index configuration. |
outError | On failure, an error is written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_CreateValueIndex()
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
-
collection | The collection. |
name | The name of the index. |
config | The index configuration. |
outError | On failure, an error is written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_DeleteDocument()
Deletes a document from the collection.
Deletions are replicated.
- Warning
- You are still responsible for releasing the CBLDocument.
- Parameters
-
collection | The collection containing the document. |
document | The document to delete. |
outError | On failure, the error will be written here. |
- Returns
- True if the document was deleted, false if an error occurred.
◆ CBLCollection_DeleteDocumentWithConcurrencyControl()
Deletes a document from the collection.
Deletions are replicated.
- Warning
- You are still responsible for releasing the CBLDocument.
- Parameters
-
collection | The collection containing the document. |
document | The document to delete. |
concurrency | Conflict-handling strategy. |
outError | On failure, the error will be written here. |
- Returns
- True if the document was deleted, false if an error occurred.
◆ CBLCollection_DeleteIndex()
Deletes an index in the collection by name.
- Parameters
-
collection | The collection. |
name | The name of the index. |
outError | On failure, an error is written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_GetDocument()
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
-
collection | The collection. |
docID | The ID of the document. |
outError | On 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()
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
-
collection | The collection. |
docID | The ID of the document. |
outError | On 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()
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
-
collection | The collection. |
outError | On failure, an error is written here. |
- Returns
- The index names in the collection, or NULL if an error occurred.
◆ CBLCollection_GetMutableDocument()
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
-
collection | The collection. |
docID | The ID of the document. |
outError | On 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()
Returns the collection name.
- Parameters
-
collection | The collection. |
- Returns
- The name of the collection.
◆ CBLCollection_PurgeDocument()
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
-
collection | The collection containing the document. |
document | The document to delete. |
outError | On 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()
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
-
collection | The collection. |
docID | The document ID to purge. |
outError | On 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()
◆ CBLCollection_Retain()
◆ CBLCollection_SaveDocument()
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
-
collection | The collection to save to. |
doc | The mutable document to save. |
outError | On failure, the error will be written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_SaveDocumentWithConcurrencyControl()
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
-
collection | The collection to save to. |
doc | The mutable document to save. |
concurrency | Conflict-handling strategy (fail or overwrite). |
outError | On failure, the error will be written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_SaveDocumentWithConflictHandler()
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
-
collection | The collection to save to. |
doc | The mutable document to save. |
conflictHandler | The callback to be invoked if there is a conflict. |
context | An arbitrary value to be passed to the conflictHandler . |
outError | On failure, the error will be written here. |
- Returns
- True on success, false on failure.
◆ CBLCollection_Scope()
Returns the scope of the collection.
- Note
- You are responsible for releasing the returned scope.
- Parameters
-
collection | The collection. |
- Returns
- A CBLScope instance.
◆ CBLCollection_SetDocumentExpiration()
Sets or clears the expiration time of a document.
- Parameters
-
collection | The collection. |
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. |
outError | On failure, an error is written here. |
- Returns
- True on success, false on failure.
◆ CBLDatabase_Collection()
Returns the existing collection with the given name and scope.
- Note
- You are responsible for releasing the returned collection.
- Parameters
-
db | The database. |
collectionName | The name of the collection. |
scopeName | The name of the scope. |
outError | On 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()
Returns the names of all collections in the scope.
- Note
- You are responsible for releasing the returned array.
- Parameters
-
db | The database. |
scopeName | The name of the scope. |
outError | On failure, the error will be written here. |
- Returns
- The names of all collections in the scope, or NULL if an error occurred.
◆ CBLDatabase_CreateCollection()
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
-
db | The database. |
collectionName | The name of the collection. |
scopeName | The name of the scope. |
outError | On failure, the error will be written here. |
- Returns
- A CBLCollection instance, or NULL if an error occurred.
◆ CBLDatabase_DefaultCollection()
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
-
db | The database. |
outError | On 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()
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
-
db | The database. |
outError | On failure, the error will be written here. |
- Returns
- A CBLScope instance, or NULL if an error occurred.
◆ CBLDatabase_DeleteCollection()
Delete an existing collection.
- Note
- The default collection cannot be deleted.
- Parameters
-
db | The database. |
collectionName | The name of the collection. |
scopeName | The name of the scope. |
outError | On failure, the error will be written here. |
- Returns
- True if success, or False if an error occurred.
◆ CBLDatabase_Scope()
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
-
db | The database. |
scopeName | The name of the scope. |
outError | On 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()
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
-
db | The database. |
outError | On failure, the error will be written here. |
- Returns
- The names of all existing scopes in the database, or NULL if an error occurred.
◆ kCBLDefaultCollectionName
The default collection's name.