Supported Operations for Queryable Encryption

Operations Using BinData

MongoDB stores Queryable Encryption encrypted fields as a BinData blob. Read and write operations issued against the encrypted BinData value may have unexpected or incorrect behavior as compared to issuing that same operation against the decrypted value. Certain operations have strict BSON type support where issuing them against a BinData value returns an error.

Official drivers compatible with Queryable Encryption parse read and write operations for operators or expressions that don't support BinData values.

Supported and Unsupported BSON Types

Queryable Encryption supports equality queries against all BSON types except for the following:

• double

• decimal128

• object

• array

Queryable Encryption supports range queries against the following BSON types:

• int: 32-bit integer

• long: 64-bit integer

• double: Double (IEEE 754 Binary64)

• decimal: Decimal (IEEE 754 Decimal128)

• date: UTC DateTime (Int64)

CRUD

• Queryable Encryption doesn't support multi-document update or delete operations. db.collection.updateMany() and db.collection.bulkWrite() with more than one update or delete operation aren't supported.

• Queryable Encryption limits db.collection.findAndModify() arguments.

  • fields is not allowed

  • new must be false

• When performing an upsert operation, any encrypted fields in the filter are excluded from the insert.

Supported Read and Write Commands

Queryable Encryption compatible drivers support automatic encryption with the following commands:

• aggregate

• count

• delete

• explain

• find

• findAndModify

• insert

• update

For any supported command, the 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:

• Supported Query Operators

• Supported Update Operators

• Supported Aggregation Stages

• Supported Aggregation Expressions

The following commands do not require automatic encryption. Official drivers configured for automatic 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 compatible driver configured for automatic encryption returns an error.

Supported Query Operators

Drivers configured for automatic encryption support a limited set of query operators when issued against an encrypted queryable field.

Querying non-encrypted fields or encrypted fields with a supported query type returns encrypted data that is then decrypted at the client.

Queryable Encryption currently supports none, equality, and range query types. If the query type is unspecified, it defaults to none. If the query type is none, the field is encrypted and clients can't query it.

{$expr: {$eq: ["$encrypted1", "plaintext_value"]}}

{$expr: {$eq: ["$encrypted1", "$encrypted2"]}}

Fields configured for queryType: "equality" support the following expressions:

• $eq

• $ne

• $in

• $nin

• $and

• $or

• $not

• $nor

• $expr

• $exists

Fields configured for queryType: "range" support the following expressions:

• $lt

• $lte

• $gt

• $gte

• $and

• $exists

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

Supported Update Operators

Drivers configured for automatic encryption support the following update operators when issued against encrypted fields:

• $set

• $unset

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

Update operations with the following behavior throw 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 encrypted fields, the query filter must use only supported operators on those fields.

Replacement-style Updates

Replacement-style updates are supported, however, if the replacement document contains a Timestamp(0,0) inside a top-level encrypted field, Queryable Encryption will error. The (0,0) value indicates that the mongod should generate the Timestamp. mongod cannot generate encrypted fields.

Unsupported Insert Operations

Compatible drivers configured for automatic 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. Since the mongod cannot generate encrypted fields, the resulting timestamp would be unencrypted.

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

Unsupported Aggregation Stages

Automatic encryption will not support aggregation stages that read from or write to additional collections. These stages are:

• $out

• $merge

Supported Aggregation Stages

Compatible drivers configured for automatic encryption support the following aggregation pipeline stages:

• $addFields

• $bucket

• $bucketAuto

• $collStats

• $count

• $geoNear

• $group on unencrypted fields

• $indexStats

• $limit

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

• $match

• $project

• $redact

• $replaceRoot

• $sample

• $skip

• $sort

• $sortByCount

• $unwind

Aggregation 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.

Supported Aggregation Expressions

Compatible drivers configured for automatic encryption support the following expressions against any equality query type encrypted fields:

• $cond

• $eq

• $ifNull

• $in

• $let

• $literal

• $ne

• $switch

All other aggregation expressions return an error if issued against encrypted fields.

Aggregation stages with the following behavior return an error, even if using a supported aggregation expression:

$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 encryption do not support any read or write operation that requires encrypting the following value types:

• MaxKey

• MinKey

• null

• undefined

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

Queryable Encryption does not support automatic encryption on fields within an array of documents.

Queryable Encryption does not support read or write operations on an encrypted field where the operation compares the encrypted field to the following value types:

• array

• decimal128

• double

• object