1MongoDB with MongoEngine
2========================
3
4Using a document database like MongoDB is a common alternative to
5relational SQL databases. This pattern shows how to use
6`MongoEngine`_, a document mapper library, to integrate with MongoDB.
7
8A running MongoDB server and `Flask-MongoEngine`_ are required. ::
9
10    pip install flask-mongoengine
11
12.. _MongoEngine: http://mongoengine.org
13.. _Flask-MongoEngine: https://flask-mongoengine.readthedocs.io
14
15
16Configuration
17-------------
18
19Basic setup can be done by defining ``MONGODB_SETTINGS`` on
20``app.config`` and creating a ``MongoEngine`` instance. ::
21
22    from flask import Flask
23    from flask_mongoengine import MongoEngine
24
25    app = Flask(__name__)
26    app.config['MONGODB_SETTINGS'] = {
27        "db": "myapp",
28    }
29    db = MongoEngine(app)
30
31
32Mapping Documents
33-----------------
34
35To declare a model that represents a Mongo document, create a class that
36inherits from ``Document`` and declare each of the fields. ::
37
38    import mongoengine as me
39
40    class Movie(me.Document):
41        title = me.StringField(required=True)
42        year = me.IntField()
43        rated = me.StringField()
44        director = me.StringField()
45        actors = me.ListField()
46
47If the document has nested fields, use ``EmbeddedDocument`` to
48defined the fields of the embedded document and
49``EmbeddedDocumentField`` to declare it on the parent document. ::
50
51    class Imdb(me.EmbeddedDocument):
52        imdb_id = me.StringField()
53        rating = me.DecimalField()
54        votes = me.IntField()
55
56    class Movie(me.Document):
57        ...
58        imdb = me.EmbeddedDocumentField(Imdb)
59
60
61Creating Data
62-------------
63
64Instantiate your document class with keyword arguments for the fields.
65You can also assign values to the field attributes after instantiation.
66Then call ``doc.save()``. ::
67
68    bttf = Movie(title="Back To The Future", year=1985)
69    bttf.actors = [
70        "Michael J. Fox",
71        "Christopher Lloyd"
72    ]
73    bttf.imdb = Imdb(imdb_id="tt0088763", rating=8.5)
74    bttf.save()
75
76
77Queries
78-------
79
80Use the class ``objects`` attribute to make queries. A keyword argument
81looks for an equal value on the field. ::
82
83    bttf = Movies.objects(title="Back To The Future").get_or_404()
84
85Query operators may be used by concatenating them with the field name
86using a double-underscore. ``objects``, and queries returned by
87calling it, are iterable. ::
88
89    some_theron_movie = Movie.objects(actors__in=["Charlize Theron"]).first()
90
91    for recents in Movie.objects(year__gte=2017):
92        print(recents.title)
93
94
95Documentation
96-------------
97
98There are many more ways to define and query documents with MongoEngine.
99For more information, check out the `official documentation
100<MongoEngine_>`_.
101
102Flask-MongoEngine adds helpful utilities on top of MongoEngine. Check
103out their `documentation <Flask-MongoEngine_>`_ as well.
104