DOCSP-23294: Queryable Encryption _id Field Limitation (#1279)

Author: Chris Cho

source/core/queryable-encryption/fundamentals/encrypt-and-query.txt

@@ -22,12 +22,17 @@ In this guide, you can learn about the following {+qe+} topics:
 - Query types and which ones you can use on encrypted fields.
 - What to consider when deciding whether to enable queries on an encrypted field.
 
-Specify Fields for Encryption 
+Specify Fields for Encryption
 -----------------------------
 
-{+qe+} allows you to specify which fields you want to automatically 
+{+qe+} allows you to specify which fields you want to automatically
 encrypt in your MongoDB document.
 
+.. important::
+
+   You can specify any field in your document for encryption except the
+   ``_id`` field.
+
 To specify fields for encryption and querying, define a JSON
 schema that includes the following properties:
 
@@ -58,10 +63,10 @@ schema that includes the following properties:
 Example
 ~~~~~~~
 
-This example shows how to create a JSON schema that specifies which fields that 
+This example shows how to create a JSON schema that specifies which fields that
 the {+qe+} feature should automatically encrypt.
 
-Consider the following document that contains personally identifiable information 
+Consider the following document that contains personally identifiable information
 (PII), credit card information, and sensitive medical information:
 
 .. code-block:: json
@@ -84,8 +89,8 @@ Consider the following document that contains personally identifiable informatio
       }
    }
 
-To ensure the PII and sensitive medical information stays secure, create a JSON 
-schema that configures {+qe+} to automatically encrypt those fields. 
+To ensure the PII and sensitive medical information stays secure, create a JSON
+schema that configures {+qe+} to automatically encrypt those fields.
 The following sample JSON schema shows how you can specify which fields to encrypt:
 
 .. code-block:: javascript
@@ -115,24 +120,24 @@ The following sample JSON schema shows how you can specify which fields to encry
       ]
    }
 
-Note that the ``keyId`` field requires a unique {+dek-long+} (DEK) which {+qe+} 
-uses to encrypt the fields. For more information on DEKs, see 
+Note that the ``keyId`` field requires a unique {+dek-long+} (DEK) which {+qe+}
+uses to encrypt the fields. For more information on DEKs, see
 :ref:`qe-fundamentals-manage-keys`.
 
 Specify Queryable Encrypted Fields
 ----------------------------------
 
-Include the ``queries`` property on fields you want to make queryable in your JSON 
-schema. This enables an authorized client to issue read and write queries using 
-encrypted fields. You can omit the ``queries`` property unless you want to be able 
+Include the ``queries`` property on fields you want to make queryable in your JSON
+schema. This enables an authorized client to issue read and write queries using
+encrypted fields. You can omit the ``queries`` property unless you want to be able
 to query the field.
 
 
 Example
 ~~~~~~~
 
-The following code snippet shows how to add the ``queries`` property to the 
-JSON schema to make the ``patientId`` and ``patientInfo.ssn`` 
+The following code snippet shows how to add the ``queries`` property to the
+JSON schema to make the ``patientId`` and ``patientInfo.ssn``
 fields queryable..
 
 .. code-block:: javascript
@@ -172,8 +177,8 @@ Enable {+qe+}
 
 You can enable {+qe+} on fields you specify in a JSON schema in the following ways:
 
-- Pass the JSON schema, represented by the ``encryptedFieldsObject`` constant, 
-  to the client that the application uses to create the collection as shown in the 
+- Pass the JSON schema, represented by the ``encryptedFieldsObject`` constant,
+  to the client that the application uses to create the collection as shown in the
   following code snippet:
 
 
@@ -199,14 +204,14 @@ You can enable {+qe+} on fields you specify in a JSON schema in the following wa
 
 .. note::
 
-   It's important to enable {+qe+} before creating the collection. Enabling 
-   {+qe+} after creating the collection does not encrypt fields on documents 
+   It's important to enable {+qe+} before creating the collection. Enabling
+   {+qe+} after creating the collection does not encrypt fields on documents
    already in that collection.
 
-For more information on ``autoEncryption`` configuration options, see the 
+For more information on ``autoEncryption`` configuration options, see the
 section on :ref:`qe-reference-mongo-client`.
 
-- Pass the encrypted fields object to your call to create a new collection as 
+- Pass the encrypted fields object to your call to create a new collection as
   shown in the following code snippet:
 
 .. code-block:: javascript
@@ -216,29 +221,29 @@ section on :ref:`qe-reference-mongo-client`.
    });
 
 .. tip::
-   
-   For the highest level of security, specify the encrypted fields both when 
-   creating the collection, and when creating a client to access the collection. 
-   This ensures that if the server's security is compromised, the information 
+
+   For the highest level of security, specify the encrypted fields both when
+   creating the collection, and when creating a client to access the collection.
+   This ensures that if the server's security is compromised, the information
    is still encrypted through the client.
 
 .. important::
 
-   MongoDB recommends explicitly creating your collection when using {+qe+}, rather 
-   than implicitly creating the collection through an insert operation. When you 
-   create a collection using ``createCollection()``, the operation creates an index 
-   on the encrypted fields. Without an index, querying on encrypted fields could 
+   MongoDB recommends explicitly creating your collection when using {+qe+}, rather
+   than implicitly creating the collection through an insert operation. When you
+   create a collection using ``createCollection()``, the operation creates an index
+   on the encrypted fields. Without an index, querying on encrypted fields could
    run slowly.
 
 .. _qe-query-types:
 
 Query Types
 -----------
 
-{+qe+} allows you to specify on which fields you want to enable querying by passing 
+{+qe+} allows you to specify on which fields you want to enable querying by passing
 a query type to the ``queries`` option in your encrypted fields object.
 
-{+qe+} supports the ``equality`` query type. The ``equality`` query type allows 
+{+qe+} supports the ``equality`` query type. The ``equality`` query type allows
 you to query encrypted fields using the following expressions:
 
 - :manual:`$eq </reference/operator/query/eq/>`
@@ -252,13 +257,13 @@ you to query encrypted fields using the following expressions:
 - :manual:`$expr </reference/operator/query/expr/>`
 
 .. note::
-   Queries that compare an encrypted field to ``null`` or to a regular expression will 
+   Queries that compare an encrypted field to ``null`` or to a regular expression will
    result in an error, even when using a supported query operator.
 
 .. _qe-query-unsupported:
 
-{+qe+} using the ``equality`` query type doesn't support read or write operations 
-on a field when the operation compares the encrypted field to any of the following 
+{+qe+} using the ``equality`` query type doesn't support read or write operations
+on a field when the operation compares the encrypted field to any of the following
 :term:`BSON` types:
 
 - ``double``
@@ -271,13 +276,13 @@ on a field when the operation compares the encrypted field to any of the followi
 Considerations when Enabling Querying
 -------------------------------------
 
-When you use {+qe+}, you can choose whether to make an encrypted field queryable. 
-If you don't need to perform read operations, or write operations that require you 
-to read an encrypted field, you may decide not to enable querying on that field. 
+When you use {+qe+}, you can choose whether to make an encrypted field queryable.
+If you don't need to perform read operations, or write operations that require you
+to read an encrypted field, you may decide not to enable querying on that field.
 You can still retrieve the entire document by querying other fields that are queryable or not encrypted.
 
-When you make encrypted fields queryable, {+qe+} creates an index for each encrypted field, which 
-can make write operations on that field take longer. When a write operation updates 
+When you make encrypted fields queryable, {+qe+} creates an index for each encrypted field, which
+can make write operations on that field take longer. When a write operation updates
 an indexed field, MongoDB also updates the related index.
 
 When you enable querying on an encrypted field, your collection requires more storage space.

source/core/queryable-encryption/reference/limitations.txt

@@ -228,6 +228,12 @@ cannot introspect the index catalog to identify a given field as unique.
 Applications cannot rely on automatic encryption validation to prevent
 unique constraint violations on randomly-encrypted fields.
 
+The _id Field
+-------------
+
+You cannot instruct {+qe+} to encrypt the ``_id`` field because it relies on
+the value auto-generated by MongoDB.
+
 Read/Write Query Support
 ------------------------