Encrypted Fields and Enabled Queries
On this page
When you use Queryable Encryption, you define encrypted fields at the collection level using an encryption schema. Encrypting a field and enabling queries increases storage requirements and impacts query performance. You can configure an encrypted field for either equality or range queries, but not both. Configure fields for the expected query type.
For instructions on creating an encryption schema and configuring querying, see Create an Encryption Schema.
Supported Query Types and Behavior
For a list of supported query operators and behavior with encrypted fields, see Supported Query Operators.
Client and Server Schema Validation
MongoDB supports using schema validation to enforce encryption of specific fields in a collection. Clients using automatic Queryable Encryption behave differently depending on the database connection configuration:
If the connection
encryptedFieldsMap
object contains a key for the specified collection, the client uses that object to perform automatic Queryable Encryption, rather than using the remote schema. At minimum, the local rules must encrypt all fields that the remote schema does.If the connection
encryptedFieldsMap
object doesn't contain a key for the specified collection, the client downloads the server-side remote schema for the collection and uses it instead.Important
Remote Schema Behavior
When using a remote schema:
The client trusts that the server has a valid schema
The client uses the remote schema to perform automatic Queryable Encryption only. The client does not enforce any other validation rules specified in the schema.
Considerations when Enabling Querying
You can make an encrypted field queryable. To change which fields are encrypted or queryable, rebuild the collection's encryption schema and re-create the collection.
If you don't need to query an encrypted field, you may not need to enable querying on that field. You can still retrieve the document by querying other fields that are queryable or unencrypted.
For every encrypted collection, MongoDB creates two metadata collections, increasing storage space. MongoDB creates an index for each encrypted field, which increases the duration of write operations on that field. When a write operation updates an indexed field, MongoDB updates the related index.
Configure Encrypted Fields for Optimal Search and Storage
MongoDB provides the following parameters to facilitate debugging and performance tuning:
min, max
Query Type: Range queries only.
Type: Must match the field's
bsonType
.Required if
bsonType
isdecimal
ordouble
. Optional but highly recommended if it isint
,long
, ordate
. Defaults to thebsonType
min and max values.Specify minimum and maximum (inclusive) queryable values for a field when possible, as this improves query efficiency. If querying values outside of these bounds, MongoDB returns an error.
Important
The sparsity, precision, trimFactor, and contention parameters are intended for advanced users only. The default values for these options are suitable for the majority of use cases, and should only be modified if your use case requires it.
sparsity
Query Type: Range queries only.
Type: Integer from
1
-4
.Optional. Defaults to
2
.Affects how thoroughly MongoDB indexes range values. Low sparsity (dense indexing) improves query performance, but stores more documents in the encrypted metadata collections for each insert or update operation, causing greater storage overhead. High sparsity does the opposite.
precision
Query Type: Range queries only.
Type: Integer.
Optional. Allowed only if
bsonType
isdouble
ordecimal
. If unset, MongoDB uses the same high precision as thebsonType
, eitherdouble
ordecimal
.Determines how many digits are taken into account when querying a
double
ordecimal
field. Every additional digit increases storage overhead, and has a high impact on searchable range and index generation. This parameter only affects queries. The encrypted value is still stored with full precision.
trimFactor
Query Type: Range queries only.
Type: Integer.
Optional. Defaults to
6
.A low
trimFactor
causes MongoDB to store more documents in the metadata collections for eachinsert
orupdate
operation. It improvesinsert
andupdate
times at the cost of slowing down some range operations . A hightrimFactor
does the opposite.
contention
Query Type: Equality and range queries.
Type: Integer.
Optional. Defaults to
8
.Concurrent write operations, such as inserting the same field/value pair into multiple documents in close succession, can cause contention: conflicts that delay operations.
With Queryable Encryption, MongoDB tracks the occurrences of each field/value pair in an encrypted collection using an internal counter. The contention factor partitions this counter, similar to an array. This minimizes issues with incrementing the counter when using
insert
,update
, orfindAndModify
to add or modify an encrypted field with the same field/value pair in close succession.contention = 0
creates an array with one element at index 0.contention = 4
creates an array with 5 elements at indexes 0-4. MongoDB increments a random array element during insert.When unset,
contention
defaults to8
, which provides high performance for most workloads. Higher contention improves the performance of insert and update operations on low cardinality fields, but decreases find performance.You can optionally include
contention
on queryable fields to change the value from its default of8
. Before you modify contention, consider the following points:Consider increasing
contention
above the default value of8
only if the field has frequent concurrent write operations. Since highcontention
values sacrifice find performance in favor of insert and update operations, the benefit of a high contention factor for a rarely updated field is unlikely to outweigh the drawback.Consider decreasing
contention
if a field is often queried, but rarely written. In this case, find performance is preferable to write and update performance.You can calculate contention factor for a field by using a formula where:
ω
is the number of concurrent write operations on the field in a short time, such as 30ms. If unknown, you can use the server's number of virtual cores.valinserts
is the number of unique field/value pairs inserted since last performing metadata compaction.ω
∗ isω/valinserts
rounded up to the nearest integer. For a workload of 100 operations with 1000 recent values,100/1000 = 0.1
, which rounds up to1
.
A reasonable contention factor,
cf
, is the result of the following formula, rounded up to the nearest positive integer:(ω
∗· (ω
∗− 1)) / 0.2
For example, if there are 100 concurrent write operations on a field in 30ms, then
ω = 100
. If there are 50 recent unique values for that field, thenω
∗= 100/50 = 2
. This results incf = (2·1)/0.2 = 10
.Warning
Don't set the contention factor based on properties of the data itself, such as the frequency of field/value pairs (cardinality). Only set the contention factor based on your workload.
Consider a case where
ω = 100
andvalinserts = 1000
, resulting inω
∗= 100/1000 = 0.1 ≈ 1
andcf = (1·0)/0.2 = 0 ≈ 1
. 20 of the values appear very frequently, so you setcontention = 3
instead. An attacker with access to multiple database snapshots can infer that the high setting indicates frequent field/value pairs. In this case, leavingcontention
unset so that it defaults to8
would prevent the attacker from having that information.For thorough information on contention factor and its cryptographic implications, see "Section 9: Guidelines" in MongoDB's Queryable Encryption Technical Paper.