For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Create an Encrypted Collection and Insert Documents

This guide shows you how to create a Queryable Encryption-enabled collection and insert a document with encrypted fields.

After you complete the steps in this guide, you should be able to create an encrypted collection and insert a document with fields that are encrypted with your Customer Master Key.

Create your Queryable Encryption-enabled application before creating an encrypted collection.

If you are using explicit encryption, you must also create a unique Data Encryption Key for each encrypted field in advance. For more information, see Encryption Keys and Key Vaults.

1

To encrypt a field, add it to the encryption schema. To enable queries on a field, add the queries property. You can enable fields to be queryable by either equality queries or range queries. The following steps demonstrate how to specify fields to encrypt with each query type.

  1. Specify Fields for Equality Queries

    To enable equality queries on a field, add the field to the encryption schema with a queryType of "equality". The following code sample encrypts both the ssn and billing fields, but only the ssn field is queryable:

    const collectionOpts = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, ], },};
  2. Specify Fields for Range Queries

    To enable range queries on a field, add the field to the encryption schema with a queryType of "range". The following example adds the billAmount field to the encryption schema created in the preceding step and enables range queries on it:

    const collectionOpts = { encryptedFields: { fields: [ { path: "patientRecord.ssn", bsonType: "string", queries: { queryType: "equality" }, }, { path: "patientRecord.billing", bsonType: "object", }, { path: "patientRecord.billAmount", bsonType: "int", queries: { queryType: "range", sparsity: 1, trimFactor: 4, min: 100, max: 2000, }, }, ], },};

For extended versions of these steps, see Create an Encryption Schema.

2
const clientEncryption = encryptedClient.getClientEncryption();
3

Important

Explicitly create your collection, rather than creating it implicitly with an insert operation. When you create a collection using createCollection(), MongoDB creates an index on the encrypted fields. Without this index, queries on encrypted fields may run slowly.

Create your encrypted collection by using the encryption helper method accessed through the ClientEncryption class. This method automatically generates data encryption keys for your encrypted fields and creates the encrypted collection:

await clientEncryption.createEncryptedCollection( encryptedDatabaseName, encryptedCollectionName, { provider: kmsProviderName, createCollectionOptions: collectionOpts, masterKey: customerMasterKeyCredentials, });

For additional information, see Enable Queryable Encryption when Creating a Collection.

4

Create a sample document that describes a patient's personal information. Use the encrypted client to insert it into the patients collection, as shown in the following example:

const patientDocument = { patientName: "Jon Doe", patientId: 12345678, patientRecord: { ssn: "987-65-4320", billing: { type: "Visa", number: "4111111111111111", }, billAmount: 1500, },}; const encryptedCollection = encryptedClient .getDB(encryptedDatabaseName) .getCollection(encryptedCollectionName); const insertResult = await encryptedCollection.insertOne(patientDocument);

After creating a Queryable Encryption-enabled collection, you can query the encrypted fields.

Select your language
Rate this page