Merge pull request #2561 from bagerard/improve_index_doc

improve index doc

docs/guide/defining-documents.rst

@@ -628,8 +628,8 @@ point. To create a geospatial index you must prefix the field with the
             ],
         }
 
-Time To Live indexes
---------------------
+Time To Live (TTL) indexes
+--------------------------
 
 A special index type that allows you to automatically expire data from a
 collection after a given period. See the official

docs/guide/migration.rst

@@ -223,6 +223,47 @@ it is often useful for complex migrations of Document models.
 
 .. warning:: Be aware of this `flaw <https://groups.google.com/g/mongodb-user/c/AFC1ia7MHzk>`_ if you modify documents while iterating
 
+Example 4: Index removal
+========================
+
+If you remove an index from your Document class, or remove an indexed Field from your Document class,
+you'll need to manually drop the corresponding index. MongoEngine will not do that for you.
+
+The way to deal with this case is to identify the name of the index to drop with `index_information()`, and then drop
+it with `drop_index()`
+
+Let's for instance assume that you start with the following Document class
+
+.. code-block:: python
+
+    class User(Document):
+        name = StringField(index=True)
+
+        meta = {"indexes": ["name"]}
+
+    User(name="John Doe").save()
+
+As soon as you start interacting with the Document collection (when `.save()` is called in this case),
+it would create the following indexes:
+
+.. code-block:: python
+
+    print(User._get_collection().index_information())
+    # {
+    #  '_id_': {'key': [('_id', 1)], 'v': 2},
+    #  'name_1': {'background': False, 'key': [('name', 1)], 'v': 2},
+    # }
+
+Thus: '_id' which is the default index and 'name_1' which is our custom index.
+If you would remove the 'name' field or its index, you would have to call:
+
+.. code-block:: python
+
+    User._get_collection().drop_index('name_1')
+
+.. note:: When adding new fields or new indexes, MongoEngine will take care of creating them
+    (unless `auto_create_index` is disabled) ::
+
 Recommendations
 ===============
 

mongoengine/document.py

@@ -875,6 +875,10 @@ class Document(BaseDocument, metaclass=TopLevelDocumentMetaclass):
 
         Global defaults can be set in the meta - see :doc:`guide/defining-documents`
 
+        By default, this will get called automatically upon first interaction with the
+        Document collection (query, save, etc) so unless you disabled `auto_create_index`, you
+        shouldn't have to call this manually.
+
         .. note:: You can disable automatic index creation by setting
                   `auto_create_index` to False in the documents meta data
         """
@@ -924,8 +928,10 @@ class Document(BaseDocument, metaclass=TopLevelDocumentMetaclass):
 
     @classmethod
     def list_indexes(cls):
-        """Lists all of the indexes that should be created for given
-        collection. It includes all the indexes from super- and sub-classes.
+        """Lists all indexes that should be created for the Document collection.
+        It includes all the indexes from super- and sub-classes.
+
+        Note that it will only return the indexes' fields, not the indexes' options
         """
         if cls._meta.get("abstract"):
             return []