mongoc_client_encryption_create_encrypted_collection

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)
  BSON_GNUC_WARN_UNUSED_RESULT;

Create a new collection with Queryable Encryption enabled. Requires a valid mongoc_client_encryption_t object to operate.

New in version 1.24.0.

SEE ALSO:

This function is a convenience API wrapping mongoc_database_create_collection().

Parameters

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.

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

Info

Apr 03, 2024 1.26.2 libmongoc