Read/Write Support with Automatic Field Level Encryption
On this page
Note
Enterprise Feature
The automatic feature of field level encryption is only available in MongoDB Enterprise 4.2 or later, and MongoDB Atlas 4.2 or later clusters.
New in version 4.2.
This page documents the specific commands, query operators, update operators, aggregation stages, and aggregation expressions supported by 4.2+ compatible drivers configured for automatic client-side field level encryption.
MongoDB stores client-side field level 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 4.2+ compatible drivers using automatic client-side field level encryption parse read/write operations for operators or expressions that do not support
BinData
values or that have abnormal behavior when issued againstBinData
values.Applications using explicit (manual) client-side field level encryption may use this page as guidance for issuing read/write operations against encrypted fields.
Supported Read and Write Commands
Official MongoDB 4.2+ compatible drivers support automatic client-side field level encryption with the following commands:
For any supported command, 4.2+ compatible drivers return an error if the command uses an unsupported operator, aggregation stage, or aggregation expression:
The following commands do not require automatic encryption. Official
MongoDB 4.2+ compatible drivers configured for automatic client-side
field level encryption pass these commands directly to the
mongod
:
isMaster
(deprecated)
Issuing any other command through a 4.2+ compatible driver configured for automatic client-side field level encryption returns an error.
[1] | While automatic client-side field level encryption does not encrypt
the getMore command, the response to the command may
contain encrypted field values. Applications configured with the
correct client-side field level encryption options
automatically decrypt those values.
Applications without the correct encryption options only see the
encrypted values. |
Supported Query Operators
Official 4.2+ compatible drivers configured for automatic client-side field level encryption allow the following query operators when issued against deterministically encrypted fields:
Queries that compare an encrypted field to null
or a regular
expression always throw an error even if using a supported query
operator. Queries issuing these operators against a randomly encrypted field throw 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 throw an error even if not issued against an encrypted field:
Supported Update Operators
Official 4.2+ compatible drivers configured for automatic client-side field level encryption allow the following update operators when issued against deterministically encrypted fields:
For update operations using the $rename
operator on encrypted
fields, ensure that the automatic JSON schema specifies 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 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 deterministically encrypted fields, the query filter must use only supported operators on those fields.
Unsupported Insert Operations
Official MongoDB 4.2+ compatible 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 themongod
should generate the Timestamp. Since themongod
cannot generated 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 themongod
autogenerates 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 Aggregation Stages
Official MongoDB 4.2+ compatible drivers configured for automatic client-side field level encryption support the following aggregation pipeline stages:
$group
(see$group
Behavior for usage requirements.)$lookup
and$graphLookup
(See$lookup
and$graphLookup
Behavior for usage requirements)
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.
$group
Behavior
$group
has the following behaviors specific to client-side
field level encryption:
$lookup
and $graphLookup
Behavior
Automatic client-side field level encryption supports the
$lookup
and $graphLookup
only if the
from
collection matches the collection on which the aggregation
runs against (i.e. self-lookup operations).
$lookup
and $graphLookup
stages that
reference a different from
collection return an error.
Supported Aggregation Expressions
Official 4.2+ compatible drivers configured for automatic client-side field level encryption allow aggregation stages using the following expressions against deterministically encrypted fields:
All other aggregation expressions return an error if issued against encrypted fields.
Aggregation stages with the following behavior throw an error even if using a supported aggregation expression:
Expressions | Rejected Behavior | Example | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
The expression specifies a field whose encryption properties
cannot be known until runtime and a subsequent aggregation
stage includes an expression referencing that field. |
| |||||||||||||||
The expression creates a new field that references an
encrypted field and operates on that new field in the same
expression. |
| |||||||||||||||
The expression references the prefix of an encrypted field
within the comparison expression. |
| |||||||||||||||
The result of the expression is compared an encrypted field. |
| |||||||||||||||
The expression binds a variable to an encrypted
field or attempts to rebind $$CURRENT . |
| |||||||||||||||
The first argument to the expression is an encrypted field, and
|
|
Unsupported Field Types
Official MongoDB 4.2+ compatible drivers configured for automatic client-side field level encryption do not support any read or write operation that requires encrypting the following value types:
Encryption does not adequately hide the type information for these values.
Automatic field level encryption also does not support read or write operations on a deterministically field where the operation compares the encrypted field to the following value types:
double
decimal128
bool
object
array
javascriptWithScope
(Deprecated)