@@ -12,14 +12,8 @@ Encrypted Collection Management
1212 :depth: 2
1313 :class: singlecol
1414
15- It is important that you understand the performance and storage costs of field level encryption. Each encrypted field:
16-
17- - Adds adds writes to insert, update, and delete operations.
18- - Requires additional storage, because MongoDB maintains an encrypted field index.
19-
20- This section lists the writes per operation and explains how to compact
21- encrypted collection indexes so that you can minimize write and storage
22- costs.
15+ In this guide, you can learn how to manage your encrypted collections,
16+ and the storage and write costs of {+qe+}.
2317
2418Overview
2519--------
@@ -30,9 +24,9 @@ fields.
3024
3125With {+qe+}, a given plaintext value always encrypts to a different
3226ciphertext, while still remaining queryable. To enable
33- this functionality, {+qe+} uses three data structures:
27+ this functionality, {+qe+} uses four data structures:
3428
35- - Two metadata collections
29+ - Three metadata collections
3630- A field in every document in the encrypted collection called ``__safeContent__``
3731
3832.. important::
@@ -43,10 +37,11 @@ this functionality, {+qe+} uses three data structures:
4337Metadata Collections
4438--------------------
4539
46- When you create an encrypted collection, MongoDB creates two
40+ When you create an encrypted collection using {+qe+} , MongoDB creates three
4741metadata collections:
4842
4943- ``enxcol_.<collectionName>.esc``, referred to as ``ESC``
44+ - ``enxcol_.<collectionName>.ecc``, referred to as ``ECC``
5045- ``enxcol_.<collectionName>.ecoc``, referred to as ``ECOC``
5146
5247.. example::
@@ -55,25 +50,29 @@ metadata collections:
5550 following metadata collections:
5651
5752 - ``enxcol_.patients.esc``
53+ - ``enxcol_.patients.ecc``
5854 - ``enxcol_.patients.ecoc``
5955
6056
61- When you insert documents with a queryable encrypted field ,
57+ When you insert documents with encrypted fields that you wish to query on ,
6258MongoDB updates the metadata collections to maintain an index
63- that enables querying. The field becomes an "indexed field". This
64- comes at a cost in storage and write speed for every such field .
59+ that enables you to query. MongoDB refers to this as "indexed field". This
60+ comes at a cost in storage and write speed.
6561
6662Storage Costs
6763-------------
6864
6965Storage and write costs increase based on the number of indexed fields
7066per document.
7167
72- .. important::
68+ .. important:: Technical Preview
7369
74- Expect a {+qe+} collection to have 2-3 times the storage requirements
75- of the documents, to account for metadata collections. For example, a
76- 1 GB collection may have a storage requirement of 2-3 GB.
70+ MongoDB's guidance during the technical preview is to expect two to
71+ three times the storage requirement for a {+qe+} collection and
72+ associated metadata collections. For example, a 1 GB collection may
73+ have a storage requirement of 2-3 GB for associated metadata collections.
74+
75+ This guidance will be tuned in a future release.
7776
7877Write Costs
7978-----------
@@ -98,10 +97,11 @@ metadata collections.
9897Update Operations
9998~~~~~~~~~~~~~~~~~
10099
101- When updating a document, each indexed field requires three writes to
100+ When updating a document, each indexed field requires four writes to
102101metadata collections.
103102
104103- One write to ``ESC``
104+ - One write to ``ECC``
105105- Two writes to ``ECOC``
106106
107107
@@ -110,44 +110,45 @@ metadata collections.
110110 Updating a document with two indexed fields requires:
111111
112112 - One write to the encrypted collection.
113- - Six writes to the metadata collections.
113+ - Eight writes to the metadata collections.
114114
115115
116116Delete Operations
117117~~~~~~~~~~~~~~~~~
118118
119- When deleting a document, each indexed field requires one write to the
119+ When deleting a document, each indexed field requires two writes to the
120120metadata collections.
121121
122+ - One write to ``ECC``
122123- One write to ``ECOC``
123124
124125
125126.. example::
126127
127128 Deleting a document with two indexed fields requires:
128129
129- - One write to the encrypted collection.
130- - Two writes to the metadata collections.
130+ - One write into the encrypted collection.
131+ - Four writes to the metadata collections.
131132
132133
133134.. _qe-index-compaction:
134135
135136Index Compaction
136137----------------
137138
138- As you insert, update, and delete documents, the metadata collections
139- change and grow. Index compaction prunes the metadata collections and
140- reduces their size.
139+ .. important:: Technical Preview
141140
142- .. important::
141+ You are required to run index compaction during the technical preview.
142+ MongoDB plans to automatically run index compaction in a future release.
143143
144- You must manually run index compaction. Compaction only works on
145- clients configured for {+qe+}.
144+ As you insert, update, and delete documents, the metadata collections
145+ change and grow. Index compaction is a process that prunes the metadata
146+ collections and reduces their size.
146147
147- Run index compaction when the size of ``ECOC`` exceeds 1 GB.
148+ You should run index compaction when the size of ``ECOC`` exceeds 1 GB.
148149
149150You can check the size of your collections using :binary:`~bin.mongosh`
150- and issuing the :method:` db.collection.totalSize()` command.
151+ and issuing the `` db.collection.totalSize()` ` command.
151152
152153.. example::
153154
@@ -165,6 +166,10 @@ and issuing the :method:`db.collection.totalSize()` command.
165166
166167 1407960328
167168
169+ .. important::
170+
171+ You must configure your client for {+qe+} to run index compaction.
172+
168173To run index compaction, use :binary:`~bin.mongosh` and run the
169174``db.collection.compactStructuredEncryptionData()`` command to reduce
170175the size of the metadata collections.
0 commit comments