MONGOC_CLIENT_...TED_COLLECTION(3)

🌸 MONGOC_CLIENT_...TED_COLLECTION(3) 🌸

okay bestie, welcome to this libmongoc page 💅 it's giving encryption, it's giving collection creation, and lowkey it's a convenience wrapper. let's get into it ✨

---

📜 SYNOPSIS 📜

          mongoc_collection_t*
          mongoc_client_encryption_create_encrypted_collection (
                mongoc_client_encryption_t *enc,
                mongoc_database_t *database,
                const char *name,
                const bson_t *in_options,
                bson_t *out_options,
                const char *kms_provider,
                const bson_t *opt_masterKey,
                bson_error_t *error);

so the vibe is: create a new collection with Queryable Encryption enabled 🔐 it requires a valid mongoc_client_encryption_t object to operate, no cap. New in version 1.24.0. 🎀

👀 SEE ALSO 👀

this function is a convenience API wrapping mongoc_database_create_collection() 🫶

🧩 PARAMETERS 🧩

• enc — the mongoc_client_encryption_t that gets used to configure encryption for the new collection 🔑
• database — the mongoc_database_t in which the new collection will be created 🗂️
• name — the name of the new collection, obviously 💖
• in_options — the options for the new collection. (See below). 👇
• out_options — an optional output option for the final create-collection options. Should point to storage for a bson_t. The pointed-to object must be destroyed by the caller 😭 If NULL, has no effect.
• kms_provider — the name of the KMS provider to use for generating new data encryption keys for encrypted fields within the collection 🔐
• opt_masterKey — if provided, used as the masterkey option when data encryption keys need to be created. (See: mongoc_client_encryption_datakey_opts_set_masterkey()) 🗝️
• error — optional output parameter pointing to storage for a bson_error_t. If an error occurs, will be initialized with error information 🚨

🎁 RETURNS 🎁

If successful, this function returns a new mongoc_collection_t object 👑 Upon failure, returns NULL and initializes *error with an error indicating the reason for failure 💀 The returned collection object must be freed by the caller — don't forget, bestie 🫶

🚨 caveat check: the returned collection object must be freed by the caller, and the out_options pointed-to object must be destroyed by the caller. periodt.

🛠️ CREATION OPTIONS 🛠️

the in_options parameter behaves similarly to the opts parameter for mongoc_database_create_collection(), which accepts the options for the create MongoDB command (Documented here). the in_options document accepted here is different in one important way:

the $.encryptedFields.fields array is required by this function, and, unlike the schema documented for the create command, accepts a value of null for the keyId parameter on each array element 👀

this function has the following as-if effect:

1. a new set of options O will be created based on in_options ✨
2. for each element F in the $.encryptedFields.fields array of O:
   1. if F contains a "keyId": null element, a new data encryption key K_f will be created as-if by calling the mongoc_client_encryption_create_datakey(), using the relevant arguments that were given to mongoc_client_encryption_create_encrypted_collection 🔐
   2. the ID of K_f will be used to replace the "keyId": null element within F 🫰
3. a collection will be created using the options O 🎉
4. if out_options is not NULL, O will be written to out_options 💌

✍️ AUTHOR ✍️

MongoDB, Inc — iconic, honestly 💜

©️ COPYRIGHT ©️

2009-present, MongoDB, Inc. 🌈

---

kisses bestie, this page is from libmongoc, version 2.5.6, dated Oct 09, 202 💖🦋✨ slay and read your man pages responsibly 🎀