fixup! Create index usage documentation

art049 · Sep 7, 2022 · bc01068 · bc01068
1 parent eeb0596
commit bc01068
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 1 deletion.
diff --git a/docs/examples_src/modeling/async/index_creation.py b/docs/examples_src/modeling/async/index_creation.py
@@ -0,0 +1,6 @@
+# ... Continuation of the previous snippet ...
+
+from odmantic import AIOEngine
+
+engine = AIOEngine()
+await engine.configure_database([Product])
diff --git a/docs/examples_src/modeling/compound_index.py b/docs/examples_src/modeling/compound_index.py
@@ -0,0 +1,14 @@
+from odmantic import Field, Index, Model
+
+
+class Product(Model):
+    name: str
+    stock: int
+    category: str
+    sku: str = Field(unique=True)
+
+    class Config:
+        @staticmethod
+        def indexes():
+            yield Index(Product.name, Product.stock, name="name_stock_index")
+            yield Index(Product.name, Product.category, unique=True)
diff --git a/docs/examples_src/modeling/custom_text_index.py b/docs/examples_src/modeling/custom_text_index.py
@@ -0,0 +1,15 @@
+import pymongo
+
+from odmantic import Model
+
+
+class Post(Model):
+    title: str
+    content: str
+
+    class Config:
+        @staticmethod
+        def indexes():
+            yield pymongo.IndexModel(
+                [(+Post.title, pymongo.TEXT), (+Post.content, pymongo.TEXT)]
+            )
diff --git a/docs/examples_src/modeling/sync/index_creation.py b/docs/examples_src/modeling/sync/index_creation.py
@@ -0,0 +1,6 @@
+# ... Continuation of the previous snippet ...
+
+from odmantic import SyncEngine
+
+engine = SyncEngine()
+engine.configure_database([Product])
diff --git a/docs/modeling.md b/docs/modeling.md
@@ -38,6 +38,65 @@ option in the `Config` class.
 
 ### Indexes
 
+#### Index definition
+
+There are two ways to create indexes on a model in ODMantic. The first one is to use the
+Field descriptors as explained in [Indexed fields](fields.md#indexed-fields) or
+[Unique fields](fields.md#unique-fields). However, this way doesn't allow a great
+flexibility on index definition.
+
+That's why you can also use the `Config.indexes` generator to specify advanced indexes
+(compound indexes, custom names). This static function defined in the `Config` class
+should yield [odmantic.Index][odmantic.index.Index].
+
+
+For example:
+
+```python hl_lines="8 11-14" linenums="1"
+--8<-- "modeling/compound_index.py"
+```
+
+This snippet creates 3 indexes on the `Product` model:
+
+- A unique index on the `sku` field defined with
+  [the field descriptor](fields.md#unique-fields), enforcing uniqueness of the `sku`
+  field.
+
+- A compound index on the `name` and `stock` fields, making sure the following query
+  will be efficient (i.e. avoid a full collection scan):
+
+    ```python
+    engine.find(Product, Product.name == "banana", Product.stock > 5)
+    ```
+
+- A unique index on the `name` and `category` fields, making sure each category has
+  unique product name.
+
+#### Index creation
+
+In order to create and enable the indexes in the database, you need to call the
+`engine.configure_database` method
+(either [AIOEngine.configure_database][odmantic.engine.AIOEngine.configure_database] or
+[SyncEngine.configure_database][odmantic.engine.SyncEngine.configure_database]).
+
+{{ async_sync_snippet("modeling", "index_creation.py", hl_lines="6") }}
+
+This method can also take a `#!python update_existing_indexes=True` parameter to update existing
+indexes when the index definition changes. If not enabled, an exception will be thrown
+when a conflicting index update happens.
+
+#### Advanced indexes
+
+In some cases, you might need a greater flexibility on the index definition (Geo2D,
+Hashed, Text indexes for example), the
+`Config.indexes` generator can also yield [pymongo.IndexModel](https://pymongo.readthedocs.io/en/stable/api/pymongo/operations.html?highlight=indexmodel#pymongo.operations.IndexModel){:target=blank_}
+objects.
+
+For example, defining a [text index](https://www.mongodb.com/docs/manual/core/index-text/){:target=blank_} :
+
+```python hl_lines="11-15" linenums="1"
+--8<-- "modeling/custom_text_index.py"
+```
 
 
 ### Custom model validators
@@ -80,7 +139,7 @@ in the model body.
 
       Default: `#!python False`
 
-`#!python indexes: Callable[[],Iterable[Index]]`
+`#!python indexes: Callable[[],Iterable[Union[Index, pymongo.IndexModel]]]`
  :    Define additional indexes for the model. See [Indexes](modeling.md#indexes) for
       more details.