Supported Operations for Queryable Encryption
On this page
- Operations Using
BinData
- Supported and Unsupported BSON Types
- CRUD
- Supported Read and Write Commands
- Supported Query Operators
- Unsupported Queries
- Supported Update Operators
- Replacement-style Updates
- Unsupported Insert Operations
- Unsupported Aggregation Stages
- Supported Aggregation Stages
$lookup
and$graphLookup
Behavior- Supported Aggregation Expressions
- Unsupported Field Types
This page documents the specific data types, commands, query operators, update operators, aggregation stages, and aggregation expressions supported for Queryable Encryption compatible drivers. It outlines the behavior for operations using automatic encryption, and operations using explicit encryption.
Note
Enterprise Feature
Automatic encryption is available in MongoDB Enterprise and MongoDB Atlas
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 integerlong
: 64-bit integerdouble
: 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()
anddb.collection.bulkWrite()
with more than one update or delete operation aren't supported.Queryable Encryption limits
db.collection.findAndModify()
arguments.fields
is not allowednew
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:
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:
The following commands do not require automatic encryption. Official drivers
configured for automatic encryption pass these commands directly to the
mongod
:
Issuing any other command through a compatible driver configured for automatic encryption returns an error.
[1] | While automatic encryption does not encrypt the getMore command, the response
to the command may contain encrypted field values.
|
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.
Important
Comparison Support
Comparison of an encrypted field to a plaintext value is supported.
{$expr: {$eq: ["$encrypted1", "plaintext_value"]}}
Comparison of one encrypted field to another encrypted field will fail.
{$expr: {$eq: ["$encrypted1", "$encrypted2"]}}
Fields configured for queryType: "equality"
support the following expressions:
Fields configured for queryType: "range"
support the following expressions:
Queries specifying any other query operator against an encrypted field return an error.
Unsupported Queries
Queries that compare an encrypted field to null
or a regular expression
always throw an error, even if using a supported query operator.
When using a MongoClient configured for Queryable Encryption, the following query operators throw an error, even if issued against an unencrypted field:
Supported Update Operators
Drivers configured for automatic encryption support the following update operators when issued against encrypted fields:
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 themongod
should generate the Timestamp. Since themongod
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 themongod
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:
Supported Aggregation Stages
Compatible drivers configured for automatic encryption support the following aggregation pipeline stages:
$group
on unencrypted fields$lookup
and$graphLookup
(For usage requirements, see$lookup
and$graphLookup
Behavior)
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.
$lookup
and $graphLookup
Behavior
Automatic encryption supports the $lookup
and
$graphLookup
only if the from
collection matches the
collection the aggregation runs against.
$lookup
and $graphLookup
stages that reference a different from
collection return an error.
Automatic encryption does not support "connectionless" aggregation metadata sources, which read metadata that doesn't pertain to a particular collection, such as:
Change Streams for watching a database or the whole cluster
Automatic encryption does not support the $planCacheStats
stage
as the result may contain sensitive information.
You cannot perform a $lookup
from a Queryable Encryption-enabled
MongoClient
on unencrypted collections.
Supported Aggregation Expressions
Compatible drivers configured for automatic encryption support the following expressions against any equality query type encrypted fields:
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:
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 to 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
Drivers configured for automatic encryption do not support any read or write operation that requires encrypting the following value types:
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