Encrypted Fields and Enabled Queries

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 is decimal or double. Optional but highly recommended if it is int, long, or date. Defaults to the bsonType min and max values.

Specify minimum and maximum (inclusive) queryable values for a field when possible, as smaller bounds improve query efficiency. If querying values outside of these bounds, MongoDB returns an error.

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 is double or decimal. If unset, MongoDB uses the same maximum precision as the bsonType, either double or decimal.

Limits how many digits after the decimal point are taken into account when querying a double or decimal field. Additional digits are dropped, not rounded. For example, a precision of 1 treats 10.18 as 10.1 for queries. The encrypted value is still stored as 10.18.

Specify precision and limit it when possible. Every digit increases storage overhead and has a high impact on searchable range and index generation.

trimFactor

Query Type: Range queries only.

Type: Integer.

Optional. Defaults to 6.

The trimFactor controls the throughput of concurrent inserts and updates. A higher trimFactor increases the throughput of concurrent insert and updates at the cost of slowing down some range read operations. A lower trimFactor 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, or findAndModify 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 to 8, 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 of 8.

For more thorough information on contention factor and its cryptographic implications, see "Section 9: Guidelines" in MongoDB's Queryable Encryption Technical Paper.