Applications often store information that should not be visible to everyone who can access the database. Customer email addresses, financial details, personal identifiers, and other sensitive fields may require stronger protection than ordinary database access controls provide.
Encrypting an entire database helps protect data at rest, but it does not solve every problem. Applications still need to search records, filter results, and retrieve matching documents. If sensitive values must be decrypted on the server before every query, the protection offered by encryption becomes more limited.
MongoDB Queryable Encryption addresses this challenge by allowing applications to run supported queries against encrypted fields. The application encrypts sensitive values on the client side, while MongoDB stores and processes the encrypted representation.
This approach can reduce the exposure of sensitive data, but it requires careful configuration of encryption keys, client drivers, and query rules. Developers also need to understand which query operations are supported by their MongoDB version.
What Is MongoDB Queryable Encryption?
MongoDB Queryable Encryption is a feature that allows applications to query selected encrypted fields without sending their plaintext values to the database server.
Consider a customer collection containing personal information:
{
"customerId": 1042,
"name": "Amit Sharma",
"email": "[email protected]",
"accountNumber": "AC987654"
}
The application may need to search for a customer using an email address or account number. With ordinary server-side filtering, the database processes the actual value supplied in the query.
With Queryable Encryption, configured fields are encrypted by the client before the data reaches MongoDB. The database stores encrypted values and associated encryption metadata rather than the plaintext sensitive values.
An authorized application can submit a supported query against an encrypted field. The MongoDB driver and encryption components handle the necessary encryption operations, allowing the server to evaluate the query without receiving the original plaintext value.
The exact operations available depend on the MongoDB server release, driver version, and encryption configuration. Queryable Encryption has evolved over multiple releases, so developers should verify feature support before designing their data model around a particular query type.
How Queryable Encryption Works
Queryable Encryption involves several components working together.
1. The application identifies sensitive fields
Developers decide which fields require encryption and which operations the application needs to perform on them.
For example, an application might encrypt a customer's email address but leave the customer's display name unencrypted. The display name can be used for ordinary searches, while queries against the email address follow the configured encryption rules.
Encryption should be planned around actual application requirements. Encrypting every field without considering query patterns can make the data model unnecessarily difficult to maintain.
2. The client encrypts sensitive values
The application uses a compatible MongoDB driver and encryption configuration to encrypt selected values before sending them to the server.
The encryption keys are managed separately from the encrypted application data. Depending on the deployment, a key management service can protect the key-encryption key used to secure data encryption keys.
The server does not need access to the plaintext value or the keys required to decrypt it.
3. MongoDB stores encrypted data and metadata
MongoDB stores the encrypted fields along with the metadata required to support the configured queries.
The database can process supported queries using this encrypted representation. It does not need to decrypt the protected field into its original value to evaluate those queries.
4. The authorized client decrypts returned values
When a query returns a document containing encrypted fields, the client uses the appropriate keys to decrypt those fields.
A client without access to the necessary keys cannot simply read the original sensitive values from the stored ciphertext.
This separation is important: database access and permission to decrypt sensitive information are not necessarily the same thing.
Queryable Encryption vs. Other Security Options
Several MongoDB security features protect data, but they solve different problems.
Feature | Main purpose | Can query encrypted fields? | Where encryption happens |
|---|
Encryption at rest | Protect stored database files | Not by itself | Database storage layer |
TLS | Protect data moving across a network | Does not provide encrypted-field querying | Network connection |
Client-Side Field Level Encryption | Encrypt selected fields before they reach MongoDB | Query support depends on the configured encryption mode and supported operations | Client |
Queryable Encryption | Support queries against configured encrypted fields | Yes, for supported query types | Client, with server-side query processing over encrypted data |
Encryption at rest and TLS remain important even when Queryable Encryption is enabled. They protect different parts of the data lifecycle and should not be treated as interchangeable.
Queryable Encryption is particularly useful when an organization wants to reduce the database server's access to sensitive application values while retaining selected search capabilities.
Setting Up Queryable Encryption
A production implementation requires more than adding an encryption option to a connection string. Developers need to configure the key management service, key vault, encrypted collection, and client driver.
The following steps describe the general setup process.
Step 1: Configure key management
Queryable Encryption uses data encryption keys to protect sensitive values. These keys are protected using a key-encryption key, which can be managed by a supported key management service.
Depending on the environment, the key management service may be provided by a cloud provider or by a supported local key-management configuration.
The application needs permission to use the relevant key material, but database administrators should not automatically receive those same permissions.
Keep encryption keys separate from application data and source code.
Step 2: Create the key vault
MongoDB uses a key vault collection to store metadata about data encryption keys. A common configuration uses a collection named datakeys in a database named encryption.
For example, the key vault namespace could be:
encryption.datakeys
The actual namespace is configurable. The collection must be protected with suitable access controls, and the application must have the permissions required for the encryption operations it performs.
The key vault is not a replacement for the external key management service. It stores key documents, while the key-encryption key protects the underlying data encryption keys.
Step 3: Define the encrypted fields
Next, decide which fields require encryption and which query operations are necessary.
A customer collection might contain:
{
"customerId": 1042,
"name": "Amit Sharma",
"email": "[email protected]",
"accountNumber": "AC987654"
}
The application could configure email for supported equality queries while leaving name available for ordinary filtering.
The configuration must match the intended data model and the query capabilities of the deployed MongoDB version. Do not assume that every MongoDB query operator works against an encrypted field.
Step 4: Configure the MongoDB client
The application must use a compatible MongoDB driver and encryption components. Depending on the chosen driver and deployment, this can involve automatic encryption configuration, explicit encryption operations, or both.
The following JavaScript example illustrates the shape of a query in an application where the collection and client-side encryption settings have already been configured correctly:
const customers = db.collection("customers");
const customer = await customers.findOne({
email: "[email protected]"
});
if (customer) {
console.log("Customer found:", customer.customerId);
}
The query looks like an ordinary equality query because the configured driver and encryption setup handle the required processing.
This snippet is not a complete encryption setup. It assumes that db refers to a database obtained from a correctly configured MongoDB client, that the email field is configured for the required encrypted query, and that the necessary keys and encryption components are available.
Without that configuration, this code does not automatically make a plaintext query against an ordinary collection work as a Queryable Encryption query.
Step 5: Test the complete data flow
Before deploying the feature, verify that the application can:
Insert documents containing encrypted fields.
Query those fields using supported operations.
Read and decrypt returned values when authorized.
Access the required keys through the configured key management service.
Handle requests from clients that do not have decryption permissions.
Testing only successful queries is not enough. Security testing should also confirm that an unauthorized client cannot retrieve plaintext sensitive values.
Choosing the Right Query Patterns
Queryable Encryption should be designed around the queries the application actually needs.
Equality queries
Equality queries search for records matching a particular value. For example, an application may need to locate a customer using an exact email address.
This is a useful starting point for applications that need to find sensitive records without exposing their plaintext search values to MongoDB.
However, equality-query support must be verified against the current server and driver versions and the field's encryption configuration.
Range queries
Some applications need to find records within a range, such as transactions above a particular amount or records associated with values between two boundaries.
Range-query support is version-dependent and has specific configuration requirements. It should not be assumed that every numeric, date, or comparison query is supported on every encrypted field.
Before choosing this approach, verify the supported data types, operators, and server requirements for the intended deployment.
Unsupported query operations
Operations such as arbitrary regular expressions, unrestricted sorting, aggregation expressions, or complex combinations of query operators may not be supported on encrypted fields in the way they work on ordinary fields.
When an application requires a query that is not supported, consider whether the data model can be adjusted or whether the query should use a different, non-sensitive field. Avoid weakening encryption just to make an unsupported query work.
Managing Encryption Keys Safely
Encryption is only as strong as the controls around its keys.
Keep keys outside source control
Do not store key-encryption keys, cloud credentials, or production key material in application source files.
Use a supported key management service and an appropriate identity mechanism. Grant the application only the permissions it needs.
Plan for key rotation
Key rotation should be part of the operational design rather than an emergency procedure.
Document how new keys are created, how applications begin using them, and how existing encrypted data remains accessible. Rotation procedures depend on the encryption configuration and should be tested before they are needed in production.
Protect key vault backups
Backups of encrypted application data are not sufficient on their own. The key vault and the external key-management configuration are also important for recovery.
A backup strategy should preserve the ability to retrieve the required keys while keeping those keys protected. Test restoration in an isolated environment to confirm that encrypted records remain usable after recovery.
Avoid logging sensitive values
Do not write decrypted fields, encryption keys, or sensitive query parameters to application logs.
Use request identifiers and other non-sensitive diagnostic information to troubleshoot problems. Logs often have broader access and longer retention periods than the primary database.
Common Mistakes to Avoid
Mistake | Why it causes problems | Better approach |
|---|
Assuming encryption at rest provides field-level protection | Database access may still expose values through normal queries | Use an appropriate client-side encryption feature |
Using an incompatible driver or server version | Required encryption or query functionality may be unavailable | Verify compatibility before deployment |
Keeping keys in source control | Credentials can leak through repositories and build logs | Use a supported key management service |
Expecting every query operator to work | Encrypted queries have feature-specific limitations | Design and test supported query patterns |
Backing up documents but not key-management dependencies | Restored records may be impossible to decrypt | Test data and key recovery together |
Logging decrypted documents | Sensitive data can spread into monitoring systems | Redact fields and log non-sensitive identifiers |
Troubleshooting Queryable Encryption
Queries return no matching documents
First, verify that the document was inserted using the expected encryption configuration. Confirm the field name, data type, query operator, and exact value.
Also check whether the field supports the intended query operation in the deployed MongoDB version. A query that works against a plaintext field may not behave identically against an encrypted field.
The application cannot access encryption keys
Key access failures can result from missing cloud permissions, incorrect key identifiers, unavailable credentials, or a misconfigured key vault namespace.
Check the application's identity and key management configuration. Avoid granting broad permissions as a quick fix; determine which specific operation is failing and grant only the necessary access.
Encryption fails when connecting to MongoDB
Confirm that the server, driver, and required encryption components are compatible. Review the client encryption configuration and verify that the application can access the key vault and configured key management service.
For automatic encryption, check that the encrypted-field configuration matches the collection being accessed.
Restored data cannot be decrypted
A database restore may succeed while encryption dependencies remain unavailable.
Verify that the restored key vault documents correspond to the encrypted data and that the external key-encryption key is still accessible. Include this scenario in disaster recovery testing.
Advantages and Limitations
Queryable Encryption can reduce the exposure of sensitive fields to database administrators, infrastructure operators, and systems that can access database storage but do not possess the decryption keys.
It also allows applications to retain selected query capabilities without requiring the database server to receive plaintext field values.
There are trade-offs. Encryption adds configuration and operational complexity, and supported query types are more limited than the full range of operations available on ordinary fields. Key management, driver compatibility, monitoring, and recovery also require additional planning.
Queryable Encryption should therefore be introduced based on a clear security requirement, not simply because encryption is available.
Best Practices for Production Applications
Identify sensitive fields and required query patterns before configuring encryption.
Confirm supported operations for the exact MongoDB server and driver versions.
Store key-encryption keys in a suitable key management service.
Separate database permissions from permissions to use decryption keys.
Test inserts, queries, updates, backups, and restoration before production rollout.
Keep plaintext values and encryption material out of logs.
Document key rotation and recovery procedures.
Review security requirements regularly as the data model and application evolve.
Summary
MongoDB Queryable Encryption enables applications to query supported encrypted fields while keeping their plaintext values away from the database server. It can provide stronger protection for sensitive customer, financial, and business data without removing every useful search capability.
A successful implementation depends on more than enabling encryption. Developers must configure the key vault, protect encryption keys, select supported query patterns, and verify compatibility across the application stack.
The best starting point is a small collection with a clearly defined set of encrypted fields and queries. Test the complete encryption and recovery workflow before extending the design to production data.
Join the conversation! Your thoughts help the community grow.