<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Tutorial — MongoEngine 0.7.9 documentation</title> <link rel="stylesheet" href="_static/nature.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '0.7.9', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="MongoEngine 0.7.9 documentation" href="index.html" /> <link rel="next" title="User Guide" href="guide/index.html" /> <link rel="prev" title="MongoEngine User Documentation" href="index.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="guide/index.html" title="User Guide" accesskey="N">next</a> |</li> <li class="right" > <a href="index.html" title="MongoEngine User Documentation" accesskey="P">previous</a> |</li> <li><a href="index.html">MongoEngine 0.7.9 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="tutorial"> <h1>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h1> <p>This tutorial introduces <strong>MongoEngine</strong> by means of example — we will walk through how to create a simple <strong>Tumblelog</strong> application. A Tumblelog is a type of blog where posts are not constrained to being conventional text-based posts. As well as text-based entries, users may post images, links, videos, etc. For simplicity’s sake, we’ll stick to text, image and link entries in our application. As the purpose of this tutorial is to introduce MongoEngine, we’ll focus on the data-modelling side of the application, leaving out a user interface.</p> <div class="section" id="getting-started"> <h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2> <p>Before we start, make sure that a copy of MongoDB is running in an accessible location — running it locally will be easier, but if that is not an option then it may be run on a remote server.</p> <p>Before we can start using MongoEngine, we need to tell it how to connect to our instance of <strong class="program">mongod</strong>. For this we use the <a class="reference internal" href="apireference.html#mongoengine.connect" title="mongoengine.connect"><tt class="xref py py-func docutils literal"><span class="pre">connect()</span></tt></a> function. The only argument we need to provide is the name of the MongoDB database to use:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mongoengine</span> <span class="kn">import</span> <span class="o">*</span> <span class="n">connect</span><span class="p">(</span><span class="s">'tumblelog'</span><span class="p">)</span> </pre></div> </div> <p>For more information about connecting to MongoDB see <a class="reference internal" href="guide/connecting.html#guide-connecting"><em>Connecting to MongoDB</em></a>.</p> </div> <div class="section" id="defining-our-documents"> <h2>Defining our documents<a class="headerlink" href="#defining-our-documents" title="Permalink to this headline">¶</a></h2> <p>MongoDB is <em>schemaless</em>, which means that no schema is enforced by the database — we may add and remove fields however we want and MongoDB won’t complain. This makes life a lot easier in many regards, especially when there is a change to the data model. However, defining schemata for our documents can help to iron out bugs involving incorrect types or missing fields, and also allow us to define utility methods on our documents in the same way that traditional <abbr title="Object-Relational Mappers">ORMs</abbr> do.</p> <p>In our Tumblelog application we need to store several different types of information. We will need to have a collection of <strong>users</strong>, so that we may link posts to an individual. We also need to store our different types <strong>posts</strong> (text, image and link) in the database. To aid navigation of our Tumblelog, posts may have <strong>tags</strong> associated with them, so that the list of posts shown to the user may be limited to posts that have been assigned a specified tag. Finally, it would be nice if <strong>comments</strong> could be added to posts. We’ll start with <strong>users</strong>, as the others are slightly more involved.</p> <div class="section" id="users"> <h3>Users<a class="headerlink" href="#users" title="Permalink to this headline">¶</a></h3> <p>Just as if we were using a relational database with an ORM, we need to define which fields a <tt class="xref py py-class docutils literal"><span class="pre">User</span></tt> may have, and what their types will be:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Document</span><span class="p">):</span> <span class="n">email</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="n">first_name</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span> <span class="n">last_name</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span> </pre></div> </div> <p>This looks similar to how a the structure of a table would be defined in a regular ORM. The key difference is that this schema will never be passed on to MongoDB — this will only be enforced at the application level. Also, the User documents will be stored in a MongoDB <em>collection</em> rather than a table.</p> </div> <div class="section" id="posts-comments-and-tags"> <h3>Posts, Comments and Tags<a class="headerlink" href="#posts-comments-and-tags" title="Permalink to this headline">¶</a></h3> <p>Now we’ll think about how to store the rest of the information. If we were using a relational database, we would most likely have a table of <strong>posts</strong>, a table of <strong>comments</strong> and a table of <strong>tags</strong>. To associate the comments with individual posts, we would put a column in the comments table that contained a foreign key to the posts table. We’d also need a link table to provide the many-to-many relationship between posts and tags. Then we’d need to address the problem of storing the specialised post-types (text, image and link). There are several ways we can achieve this, but each of them have their problems — none of them stand out as particularly intuitive solutions.</p> <div class="section" id="posts"> <h4>Posts<a class="headerlink" href="#posts" title="Permalink to this headline">¶</a></h4> <p>But MongoDB <em>isn’t</em> a relational database, so we’re not going to do it that way. As it turns out, we can use MongoDB’s schemaless nature to provide us with a much nicer solution. We will store all of the posts in <em>one collection</em> — each post type will just have the fields it needs. If we later want to add video posts, we don’t have to modify the collection at all, we just <em>start using</em> the new fields we need to support video posts. This fits with the Object-Oriented principle of <em>inheritance</em> nicely. We can think of <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt> as a base class, and <tt class="xref py py-class docutils literal"><span class="pre">TextPost</span></tt>, <tt class="xref py py-class docutils literal"><span class="pre">ImagePost</span></tt> and <tt class="xref py py-class docutils literal"><span class="pre">LinkPost</span></tt> as subclasses of <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt>. In fact, MongoEngine supports this kind of modelling out of the box:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Post</span><span class="p">(</span><span class="n">Document</span><span class="p">):</span> <span class="n">title</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">120</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="n">author</span> <span class="o">=</span> <span class="n">ReferenceField</span><span class="p">(</span><span class="n">User</span><span class="p">)</span> <span class="k">class</span> <span class="nc">TextPost</span><span class="p">(</span><span class="n">Post</span><span class="p">):</span> <span class="n">content</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">()</span> <span class="k">class</span> <span class="nc">ImagePost</span><span class="p">(</span><span class="n">Post</span><span class="p">):</span> <span class="n">image_path</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">()</span> <span class="k">class</span> <span class="nc">LinkPost</span><span class="p">(</span><span class="n">Post</span><span class="p">):</span> <span class="n">link_url</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">()</span> </pre></div> </div> <p>We are storing a reference to the author of the posts using a <a class="reference internal" href="apireference.html#mongoengine.ReferenceField" title="mongoengine.ReferenceField"><tt class="xref py py-class docutils literal"><span class="pre">ReferenceField</span></tt></a> object. These are similar to foreign key fields in traditional ORMs, and are automatically translated into references when they are saved, and dereferenced when they are loaded.</p> </div> <div class="section" id="tags"> <h4>Tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h4> <p>Now that we have our Post models figured out, how will we attach tags to them? MongoDB allows us to store lists of items natively, so rather than having a link table, we can just store a list of tags in each post. So, for both efficiency and simplicity’s sake, we’ll store the tags as strings directly within the post, rather than storing references to tags in a separate collection. Especially as tags are generally very short (often even shorter than a document’s id), this denormalisation won’t impact very strongly on the size of our database. So let’s take a look that the code our modified <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt> class:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Post</span><span class="p">(</span><span class="n">Document</span><span class="p">):</span> <span class="n">title</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">120</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="n">author</span> <span class="o">=</span> <span class="n">ReferenceField</span><span class="p">(</span><span class="n">User</span><span class="p">)</span> <span class="n">tags</span> <span class="o">=</span> <span class="n">ListField</span><span class="p">(</span><span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">30</span><span class="p">))</span> </pre></div> </div> <p>The <a class="reference internal" href="apireference.html#mongoengine.ListField" title="mongoengine.ListField"><tt class="xref py py-class docutils literal"><span class="pre">ListField</span></tt></a> object that is used to define a Post’s tags takes a field object as its first argument — this means that you can have lists of any type of field (including lists). Note that we don’t need to modify the specialised post types as they all inherit from <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt>.</p> </div> <div class="section" id="comments"> <h4>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h4> <p>A comment is typically associated with <em>one</em> post. In a relational database, to display a post with its comments, we would have to retrieve the post from the database, then query the database again for the comments associated with the post. This works, but there is no real reason to be storing the comments separately from their associated posts, other than to work around the relational model. Using MongoDB we can store the comments as a list of <em>embedded documents</em> directly on a post document. An embedded document should be treated no differently that a regular document; it just doesn’t have its own collection in the database. Using MongoEngine, we can define the structure of embedded documents, along with utility methods, in exactly the same way we do with regular documents:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Comment</span><span class="p">(</span><span class="n">EmbeddedDocument</span><span class="p">):</span> <span class="n">content</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">()</span> <span class="n">name</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">120</span><span class="p">)</span> </pre></div> </div> <p>We can then store a list of comment documents in our post document:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Post</span><span class="p">(</span><span class="n">Document</span><span class="p">):</span> <span class="n">title</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">120</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="n">author</span> <span class="o">=</span> <span class="n">ReferenceField</span><span class="p">(</span><span class="n">User</span><span class="p">)</span> <span class="n">tags</span> <span class="o">=</span> <span class="n">ListField</span><span class="p">(</span><span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">30</span><span class="p">))</span> <span class="n">comments</span> <span class="o">=</span> <span class="n">ListField</span><span class="p">(</span><span class="n">EmbeddedDocumentField</span><span class="p">(</span><span class="n">Comment</span><span class="p">))</span> </pre></div> </div> </div> <div class="section" id="handling-deletions-of-references"> <h4>Handling deletions of references<a class="headerlink" href="#handling-deletions-of-references" title="Permalink to this headline">¶</a></h4> <p>The <a class="reference internal" href="apireference.html#mongoengine.ReferenceField" title="mongoengine.ReferenceField"><tt class="xref py py-class docutils literal"><span class="pre">ReferenceField</span></tt></a> object takes a keyword <cite>reverse_delete_rule</cite> for handling deletion rules if the reference is deleted. To delete all the posts if a user is deleted set the rule:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Post</span><span class="p">(</span><span class="n">Document</span><span class="p">):</span> <span class="n">title</span> <span class="o">=</span> <span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">120</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="n">author</span> <span class="o">=</span> <span class="n">ReferenceField</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">reverse_delete_rule</span><span class="o">=</span><span class="n">CASCADE</span><span class="p">)</span> <span class="n">tags</span> <span class="o">=</span> <span class="n">ListField</span><span class="p">(</span><span class="n">StringField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">30</span><span class="p">))</span> <span class="n">comments</span> <span class="o">=</span> <span class="n">ListField</span><span class="p">(</span><span class="n">EmbeddedDocumentField</span><span class="p">(</span><span class="n">Comment</span><span class="p">))</span> </pre></div> </div> <p>See <a class="reference internal" href="apireference.html#mongoengine.ReferenceField" title="mongoengine.ReferenceField"><tt class="xref py py-class docutils literal"><span class="pre">ReferenceField</span></tt></a> for more information.</p> <dl class="docutils"> <dt>..note::</dt> <dd>MapFields and DictFields currently don’t support automatic handling of deleted references</dd> </dl> </div> </div> </div> <div class="section" id="adding-data-to-our-tumblelog"> <h2>Adding data to our Tumblelog<a class="headerlink" href="#adding-data-to-our-tumblelog" title="Permalink to this headline">¶</a></h2> <p>Now that we’ve defined how our documents will be structured, let’s start adding some documents to the database. Firstly, we’ll need to create a <tt class="xref py py-class docutils literal"><span class="pre">User</span></tt> object:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">john</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">email</span><span class="o">=</span><span class="s">'jdoe@example.com'</span><span class="p">,</span> <span class="n">first_name</span><span class="o">=</span><span class="s">'John'</span><span class="p">,</span> <span class="n">last_name</span><span class="o">=</span><span class="s">'Doe'</span><span class="p">)</span> <span class="n">john</span><span class="o">.</span><span class="n">save</span><span class="p">()</span> </pre></div> </div> <p>Note that we could have also defined our user using attribute syntax:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">john</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">email</span><span class="o">=</span><span class="s">'jdoe@example.com'</span><span class="p">)</span> <span class="n">john</span><span class="o">.</span><span class="n">first_name</span> <span class="o">=</span> <span class="s">'John'</span> <span class="n">john</span><span class="o">.</span><span class="n">last_name</span> <span class="o">=</span> <span class="s">'Doe'</span> <span class="n">john</span><span class="o">.</span><span class="n">save</span><span class="p">()</span> </pre></div> </div> <p>Now that we’ve got our user in the database, let’s add a couple of posts:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">post1</span> <span class="o">=</span> <span class="n">TextPost</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">'Fun with MongoEngine'</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">john</span><span class="p">)</span> <span class="n">post1</span><span class="o">.</span><span class="n">content</span> <span class="o">=</span> <span class="s">'Took a look at MongoEngine today, looks pretty cool.'</span> <span class="n">post1</span><span class="o">.</span><span class="n">tags</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mongodb'</span><span class="p">,</span> <span class="s">'mongoengine'</span><span class="p">]</span> <span class="n">post1</span><span class="o">.</span><span class="n">save</span><span class="p">()</span> <span class="n">post2</span> <span class="o">=</span> <span class="n">LinkPost</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">'MongoEngine Documentation'</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">john</span><span class="p">)</span> <span class="n">post2</span><span class="o">.</span><span class="n">link_url</span> <span class="o">=</span> <span class="s">'http://tractiondigital.com/labs/mongoengine/docs'</span> <span class="n">post2</span><span class="o">.</span><span class="n">tags</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mongoengine'</span><span class="p">]</span> <span class="n">post2</span><span class="o">.</span><span class="n">save</span><span class="p">()</span> </pre></div> </div> <p>Note that if you change a field on a object that has already been saved, then call <tt class="xref py py-meth docutils literal"><span class="pre">save()</span></tt> again, the document will be updated.</p> </div> <div class="section" id="accessing-our-data"> <h2>Accessing our data<a class="headerlink" href="#accessing-our-data" title="Permalink to this headline">¶</a></h2> <p>So now we’ve got a couple of posts in our database, how do we display them? Each document class (i.e. any class that inherits either directly or indirectly from <a class="reference internal" href="apireference.html#mongoengine.Document" title="mongoengine.Document"><tt class="xref py py-class docutils literal"><span class="pre">Document</span></tt></a>) has an <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute, which is used to access the documents in the database collection associated with that class. So let’s see how we can get our posts’ titles:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">post</span> <span class="ow">in</span> <span class="n">Post</span><span class="o">.</span><span class="n">objects</span><span class="p">:</span> <span class="k">print</span> <span class="n">post</span><span class="o">.</span><span class="n">title</span> </pre></div> </div> <div class="section" id="retrieving-type-specific-information"> <h3>Retrieving type-specific information<a class="headerlink" href="#retrieving-type-specific-information" title="Permalink to this headline">¶</a></h3> <p>This will print the titles of our posts, one on each line. But What if we want to access the type-specific data (link_url, content, etc.)? One way is simply to use the <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute of a subclass of <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt>:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">post</span> <span class="ow">in</span> <span class="n">TextPost</span><span class="o">.</span><span class="n">objects</span><span class="p">:</span> <span class="k">print</span> <span class="n">post</span><span class="o">.</span><span class="n">content</span> </pre></div> </div> <p>Using TextPost’s <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute only returns documents that were created using <tt class="xref py py-class docutils literal"><span class="pre">TextPost</span></tt>. Actually, there is a more general rule here: the <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute of any subclass of <a class="reference internal" href="apireference.html#mongoengine.Document" title="mongoengine.Document"><tt class="xref py py-class docutils literal"><span class="pre">Document</span></tt></a> only looks for documents that were created using that subclass or one of its subclasses.</p> <p>So how would we display all of our posts, showing only the information that corresponds to each post’s specific type? There is a better way than just using each of the subclasses individually. When we used <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt>‘s <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute earlier, the objects being returned weren’t actually instances of <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt> — they were instances of the subclass of <tt class="xref py py-class docutils literal"><span class="pre">Post</span></tt> that matches the post’s type. Let’s look at how this works in practice:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">post</span> <span class="ow">in</span> <span class="n">Post</span><span class="o">.</span><span class="n">objects</span><span class="p">:</span> <span class="k">print</span> <span class="n">post</span><span class="o">.</span><span class="n">title</span> <span class="k">print</span> <span class="s">'='</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">post</span><span class="o">.</span><span class="n">title</span><span class="p">)</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">post</span><span class="p">,</span> <span class="n">TextPost</span><span class="p">):</span> <span class="k">print</span> <span class="n">post</span><span class="o">.</span><span class="n">content</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">post</span><span class="p">,</span> <span class="n">LinkPost</span><span class="p">):</span> <span class="k">print</span> <span class="s">'Link:'</span><span class="p">,</span> <span class="n">post</span><span class="o">.</span><span class="n">link_url</span> <span class="k">print</span> </pre></div> </div> <p>This would print the title of each post, followed by the content if it was a text post, and “Link: <url>” if it was a link post.</p> </div> <div class="section" id="searching-our-posts-by-tag"> <h3>Searching our posts by tag<a class="headerlink" href="#searching-our-posts-by-tag" title="Permalink to this headline">¶</a></h3> <p>The <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute of a <a class="reference internal" href="apireference.html#mongoengine.Document" title="mongoengine.Document"><tt class="xref py py-class docutils literal"><span class="pre">Document</span></tt></a> is actually a <a class="reference internal" href="apireference.html#mongoengine.queryset.QuerySet" title="mongoengine.queryset.QuerySet"><tt class="xref py py-class docutils literal"><span class="pre">QuerySet</span></tt></a> object. This lazily queries the database only when you need the data. It may also be filtered to narrow down your query. Let’s adjust our query so that only posts with the tag “mongodb” are returned:</p> <div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">post</span> <span class="ow">in</span> <span class="n">Post</span><span class="o">.</span><span class="n">objects</span><span class="p">(</span><span class="n">tags</span><span class="o">=</span><span class="s">'mongodb'</span><span class="p">):</span> <span class="k">print</span> <span class="n">post</span><span class="o">.</span><span class="n">title</span> </pre></div> </div> <p>There are also methods available on <a class="reference internal" href="apireference.html#mongoengine.queryset.QuerySet" title="mongoengine.queryset.QuerySet"><tt class="xref py py-class docutils literal"><span class="pre">QuerySet</span></tt></a> objects that allow different results to be returned, for example, calling <tt class="xref py py-meth docutils literal"><span class="pre">first()</span></tt> on the <tt class="xref py py-attr docutils literal"><span class="pre">objects</span></tt> attribute will return a single document, the first matched by the query you provide. Aggregation functions may also be used on <a class="reference internal" href="apireference.html#mongoengine.queryset.QuerySet" title="mongoengine.queryset.QuerySet"><tt class="xref py py-class docutils literal"><span class="pre">QuerySet</span></tt></a> objects:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">num_posts</span> <span class="o">=</span> <span class="n">Post</span><span class="o">.</span><span class="n">objects</span><span class="p">(</span><span class="n">tags</span><span class="o">=</span><span class="s">'mongodb'</span><span class="p">)</span><span class="o">.</span><span class="n">count</span><span class="p">()</span> <span class="k">print</span> <span class="s">'Found </span><span class="si">%d</span><span class="s"> posts with tag "mongodb"'</span> <span class="o">%</span> <span class="n">num_posts</span> </pre></div> </div> </div> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Tutorial</a><ul> <li><a class="reference internal" href="#getting-started">Getting started</a></li> <li><a class="reference internal" href="#defining-our-documents">Defining our documents</a><ul> <li><a class="reference internal" href="#users">Users</a></li> <li><a class="reference internal" href="#posts-comments-and-tags">Posts, Comments and Tags</a><ul> <li><a class="reference internal" href="#posts">Posts</a></li> <li><a class="reference internal" href="#tags">Tags</a></li> <li><a class="reference internal" href="#comments">Comments</a></li> <li><a class="reference internal" href="#handling-deletions-of-references">Handling deletions of references</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#adding-data-to-our-tumblelog">Adding data to our Tumblelog</a></li> <li><a class="reference internal" href="#accessing-our-data">Accessing our data</a><ul> <li><a class="reference internal" href="#retrieving-type-specific-information">Retrieving type-specific information</a></li> <li><a class="reference internal" href="#searching-our-posts-by-tag">Searching our posts by tag</a></li> </ul> </li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="index.html" title="previous chapter">MongoEngine User Documentation</a></p> <h4>Next topic</h4> <p class="topless"><a href="guide/index.html" title="next chapter">User Guide</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/tutorial.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="guide/index.html" title="User Guide" >next</a> |</li> <li class="right" > <a href="index.html" title="MongoEngine User Documentation" >previous</a> |</li> <li><a href="index.html">MongoEngine 0.7.9 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2009-2012, MongoEngine Authors. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. </div> </body> </html>