Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

20 lines (18 sloc) 6.066 kb
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose Documents v3.3.1</title><link href="http://fonts.googleapis.com/css?family=Anonymous+Pro:400,700|Droid+Sans+Mono|Open+Sans:400,700|Linden+Hill|Quattrocento:400,700|News+Cycle:400,700|Antic+Slab|Cabin+Condensed:400,700" rel="stylesheet" type="text/css"><link href="/docs/css/default.css" rel="stylesheet" type="text/css"><link href="/docs/css/guide.css" rel="stylesheet" type="text/css"></head><body><a id="forkbanner" href="http://github.com/learnboost/mongoose"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" alt="Fork me on GitHub"></a><div id="links"><div id="header"><h1><a href="../index.html"><div class="mongoose">Mongoose</div></a></h1></div><ul><li class="home"><a href="../index.html">home</a></li><li class="faq"><a href="./faq.html">FAQ</a></li><li class="plugins"><a href="http://plugins.mongoosejs.com">plugins</a></li><li class="changelog"><a href="http://github.com/learnboost/mongoose/tree/master/History.md">change log</a></li><li class="support"><a href="../index.html#support">support</a></li><li class="fork"><a href="http://github.com/learnboost/mongoose">fork</a></li><li class="guide"><a href="./guide.html">guide</a><ul><li class="double"><a href="./guide.html">schemas</a><ul><li class="schematypes"><a href="./schematypes.html"><span>schema</span>types</a></li></ul></li><li><a href="./models.html">models</a></li><li class="double"><a href="./documents.html">documents</a><ul><li class="subdocs"><a href="./subdocs.html">sub docs</a></li></ul></li><li><a href="./queries.html">queries</a></li><li><a href="./validation.html">validation</a></li><li><a href="./middleware.html">middleware</a></li><li><a href="./populate.html">population</a></li><li><a href="./connections.html">connections</a></li><li><a href="./plugins.html">plugins</a></li><li><a href="https://github.com/LearnBoost/mongoose/blob/master/CONTRIBUTING.md">contributing</a></li><li><a href="./migration.html">migrating from 2.x</a></li></ul></li><li class="api"><a href="./api.html">API docs</a></li><li class="quickstart"><a href="./index.html">quick start</a></li><li class="contrib"><a href="http://github.com/learnboost/mongoose/contributors">contributors</a></li><li class="prior"><a href="./prior.html">prior releases</a></li></ul></div><div id="content"><div class="module"><h2>Documents</h2><p>Mongoose <a href="./api.html#document-js">documents</a> represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its <a href="./models.html">Model</a>.</p><h3>Retrieving</h3><p>There are many ways to retrieve documents from MongoDB. We won&#39;t cover that in this section. See the chapter on <a href="./queries.html">querying</a> for detail.</p><h3>Updating</h3><p>There are a number of ways to update documents. We&#39;ll first look at a traditional approach using <a href="./api.html#model_Model-findById">findById</a>:</p><pre><code class="javascript">Tank.findById(id, <span class="function"><span class="keyword">function</span> <span class="params">(err, tank)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
tank.size = <span class="string">'large'</span>;
tank.save(<span class="function"><span class="keyword">function</span> <span class="params">(err)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(tank);
});
});</code></pre><p>This approach involves first retreiving the document from Mongo, then issuing an update command (triggered by calling <code>save</code>). However, if we don&#39;t need the document returned in our application and merely want to update a property in the database directly, <a href="./api.html#model_Model-update">Model#update</a> is right for us:</p><pre><code class="javascript">Tank.update({ _id: id }, { $set: { size: <span class="string">'large'</span> }}, callback);</code></pre><p>If we do need the document returned in our application there is another, often <a href="./api.html#model_Model-findByIdAndUpdate">better</a>, option:</p><pre><code class="javascript">Tank.findByIdAndUpdate(id, { $set: { size: <span class="string">'large'</span> }}, <span class="function"><span class="keyword">function</span> <span class="params">(err, tank)</span> {</span>
<span class="keyword">if</span> (err) <span class="keyword">return</span> handleError(err);
res.send(tank);
});</code></pre><p>The <code>findAndUpdate/Remove</code> static methods all make a change to at most one document, and return it with just one call to the database. There <a href="./api.html#model_Model-findByIdAndRemove">are</a> <a href="./api.html#model_Model-findOneAndUpdate">several</a> <a href="./api.html#model_Model-findOneAndRemove">variations</a> on the <a href="http://www.mongodb.org/display/DOCS/findAndModify+Command">findAndModify</a> theme. Read the <a href="./api.html">API</a> docs for more detail.</p><h3>Validating</h3><p>Documents are validated before they are saved. Read the <a href="./api.html#document_Document-validate">api</a> docs or the <a href="./validation.html">validation</a> chapter for detail.</p><h3 id="next">Next Up</h3><p>Now that we&#39;ve covered <code>Documents</code>, let&#39;s take a look at <a href="/docs/subdocs.html">Sub-documents</a>.</p></div></div><script>document.body.className = 'load';</script><script>var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1122274-9']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();</script></body></html>
Jump to Line
Something went wrong with that request. Please try again.