diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst index eff59845..186dd4a5 100644 --- a/docs/guide/defining-documents.rst +++ b/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 diff --git a/docs/guide/migration.rst b/docs/guide/migration.rst index ae4bb7c8..ed982efc 100644 --- a/docs/guide/migration.rst +++ b/docs/guide/migration.rst @@ -223,6 +223,47 @@ it is often useful for complex migrations of Document models. .. warning:: Be aware of this `flaw `_ 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 =============== diff --git a/mongoengine/document.py b/mongoengine/document.py index 5f05b485..72e2818a 100644 --- a/mongoengine/document.py +++ b/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 []