Docs Menu
Docs Home
/
MongoDB Manual
/
Security
/
Encryption
/
In-Use Encryption
/
Queryable Encryption
/
Fundamentals

Create an Encryption Schema

On this page

  • About this Task
  • Steps
  • Create a JSON encryption schema document
  • Specify encryption parameters for each field you want to encrypt:
  • Example

About this Task

To make encrypted fields queryable, create an encryption schema. This schema defines which fields are queryable, and which query types are permitted. For more information, see Encrypted Fields and Queries.

Steps

1

Create a JSON encryption schema document

Include an encryptedFieldsObject with a nested fields array:

const encryptedFieldsObject = {
   fields: []
}
2

Specify encryption parameters for each field you want to encrypt:

  1. Add the path and bsonType strings to the fields array:

    const encryptedFieldsObject = {
       fields: [
          {
             path: "myDocumentField",
             bsonType: "int"
          }
       ]
    }

    Important

    You can specify any field for encryption except the _id field.

  2. If you are using explicit encryption, add a keyId field with the DEK

    {
       path: "myDocumentField",
       bsonType: "int",
       keyId: "<unique data encryption key>"
    }

    Tip

    With Automatic Encryption, MongoDB creates encryption keys for each field. You configure AutoEncryptionSettings on the client, then use the createEncryptedCollection helper method to create your collections.

  3. If you want a field to be queryable, add the queries property and list allowed queryTypes

    Queryable Encryption currently supports equality queries only.

    {
       path: "myDocumentField",
       bsonType: "int",
       queries: { queryType: "equality" }
    }

  4. (Optional) Include the contention property on queryable fields to favor either find performance, or write and update performance

    {
       path: "myDocumentField",
       bsonType: "int",
       queries: { queryType: "equality",
                  contention: "0"}
    }

    For more information, see Contention.

Example

This example shows how to create an encryption schema for hospital data.

Consider the following document that contains personally identifiable information (PII), credit card information, and sensitive medical information:

{
   "firstName": "Jon",
   "lastName": "Snow",
   "patientId": 12345187,
   "address": "123 Cherry Ave",
   "medications": [
      "Adderall",
      "Lipitor"
   ],
   "patientInfo": {
      "ssn": "921-12-1234",
      "billing": {
            "type": "visa",
            "number": "1234-1234-1234-1234"
      }
   }
}

To ensure the PII and sensitive medical information stays secure, this encryption schema adds the relevant fields:

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int"
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string"
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      }
   ]
}

Adding the queries property makes the patientId and patientInfo.ssn fields queryable. This example enables equality queries:

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int",
         queries: { queryType: "equality" }
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string",
         queries: { queryType: "equality" }
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      },
   ]
}

The example below sets contention to 0 for the low cardinality Social Security Number (SSN) and patient ID fields, since these are unique identifiers that shouldn't repeat in the data set.

const encryptedFieldsObject = {
   fields: [
      {
         path: "patientId",
         bsonType: "int",
         queries: { queryType: "equality",
                    contention: "0"}
      },
      {
         path: "patientInfo.ssn",
         bsonType: "string",
         queries: { queryType: "equality",
                    contention: "0"}
      },
      {
         path: "medications",
         bsonType: "array"
      },
      {
         path: "patientInfo.billing",
         bsonType: "object"
      }
   ]
}
← Encrypted Fields and Queries
Enabling Queryable Encryption when Creating Collections →

On this page