Supported Operations for Automatic Encryption

Supported Read and Write Commands

Drivers using automatic Client-Side Field Level Encryption support the following commands:

• aggregate

• count

• delete

• distinct

• explain

• find

• findAndModify

• insert

• update

For any supported command, drivers return an error if the command uses an unsupported operator, aggregation stage, or aggregation expression. For a complete list of the supported operators, stages, and expressions, see the following sections of this page:

• Supported Query Operators

• Supported Update Operators

• Supported Aggregation Stages

• Supported Aggregation Expressions

The following commands do not require automatic encryption. Drivers configured for automatic Client-Side Field Level Encryption pass these commands directly to the mongod:

• getMore [1]

• authenticate

• hello

• logout

• abortTransaction

• commitTransaction

• endSessions

• startSession

• create

• createIndexes

• drop

• dropDatabase

• dropIndexes

• killCursors

• listCollections

• listDatabases

• listIndexes

• renameCollection

• ping

Issuing any other command through a driver configured for automatic Client-Side Field Level Encryption returns an error.

Supported Query Operators

Drivers configured for automatic Client-Side Field Level Encryption allow the following query operators when issued against deterministically encrypted fields:

• $eq

• $ne

• $in

• $nin

• $and

• $or

• $not

• $nor

Queries that compare an encrypted field to null or a regular expression always return an error even when using a supported query operator. Queries issuing these operators against a randomly encrypted field return an error.

The $exists operator has normal behavior when issued against both deterministically and randomly encrypted fields.

Queries specifying any other query operator against an encrypted field return an error.

The following query operators return an error even if not issued against an encrypted field:

• $text

• $where

• $jsonSchema

Unsupported Insert Operations

Drivers configured for automatic Client-Side Field Level Encryption do not support insert commands with the following behavior:

• Inserting a document with Timestamp(0,0) associated to an encrypted field. The (0,0) value indicates that the mongod should generate the Timestamp. When the mongod cannot generated encrypted fields, the resulting timestamp is unencrypted.

• Inserting a document without an encrypted _id if the configured automatic schema specifies an encrypted _id field. When the mongod automatically generates an unencrypted ObjectId, omitting _id from documents results in documents that do not conform to the automatic encryption rules.

• Inserting a document with an array associated to a deterministically encrypted field. Automatic Client-Side Field Level Encryption does not support deterministically encrypting arrays.

Supported Update Operators

Drivers configured for automatic Client-Side Field Level Encryption allow the following update operators when issued against deterministically encrypted fields:

• $set

• $unset

• $rename

When you use the $rename operator on encrypted fields, the automatic JSON schema must specify the same encryption metadata for the source and target field names.

Updates specifying any other update operator against an encrypted field return an error.

Update operations with the following behavior return an error even if using a supported operator:

• The update operation produces an array inside of an encrypted path.

• The update operation uses aggregation expression syntax.

For update operations specifying a query filter on deterministically encrypted fields, the query filter must use only supported operators on those fields.

Supported Aggregation Stages

Drivers configured for automatic Client-Side Field Level Encryption support the following aggregation pipeline stages:

• $addFields

• $bucket

• $bucketAuto

• $collStats

• $count

• $geoNear

• $group (For usage requirements, see $group Behavior)

• $indexStats

• $limit

• $lookup and $graphLookup (For usage requirements, see $lookup and $graphLookup Behavior)

• $match

• $project

• $redact

• $replaceRoot

• $sample

• $skip

• $sort

• $sortByCount

• $unwind

Pipelines operating on collections configured for automatic encryption that specify any other stage return an error.

For each supported pipeline stage, MongoDB tracks fields that must be encrypted as they pass through the supported pipelines and marks them for encryption.

Each supported stage must specify only supported query operators and aggregation expressions.

$addFields : {
  "valueWithUnknownEncryption" : {
    $cond : {
      if : { "$encryptedField" : "value" },
      then : "$encryptedField",
      else: "unencryptedValue"
    }
  }
},
{
  $match : {
    "valueWithUnknownEncryption" : "someNewValue"
  }
}

{
  $eq : [
    {"newField" : "$encryptedField"},
    {"newField" : "value"
  ]
}

{ $eq : [ "$prefixOfEncryptedField" , "value"] }

{
  $eq : [
      "$encryptedField" ,
      { $ne : [ "field", "value" ] }
  ]
}

{
  $let: {
    "vars" : {
      "newVariable" : "$encryptedField"
    }
  }
}

{
  $in : [
    "$encryptedField" ,
    "$otherEncryptedField"
  ]
}

Unsupported Field Types

Drivers configured for automatic Client-Side Field Level Encryption (CSFLE) do not support any read or write operation that requires encrypting the following value types:

• MaxKey

• MinKey

• null

• undefined

Encryption does not adequately hide the type information for these values.

Automatic CSFLE also does not support read or write operations on a deterministically encrypted field where the operation compares the encrypted field to the following value types:

• array

• bool

• decimal128

• double

• object

• javascriptWithScope (Deprecated in MongoDB 4.4)