forked from Automattic/mongoose
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocuments.html
More file actions
132 lines (120 loc) · 14.3 KB
/
documents.html
File metadata and controls
132 lines (120 loc) · 14.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
<!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 v5.1.8-pre: Documents</title><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="stylesheet" href="https://unpkg.com/[email protected]/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans"><link rel="stylesheet" href="/docs/css/github.css"><link rel="stylesheet" href="/docs/css/mongoose5.css"><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="manifest" href="images/favicon/manifest.json"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="images/favicon/ms-icon-144x144.png"><meta name="theme-color" content="#ffffff"></head><body><div id="layout"><div id="mobile-menu"><a id="menuLink" href="#menu" class="menu-link"><span></span></a><div id="mobile-logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png"><span class="logo-text">mongoose</span></a></div></div><div id="menu"><div class="pure-menu"><div id="logo-container" class="pure-menu-heading"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png"><span class="logo-text">mongoose</span></a></div><ul class="pure-menu-list"><li class="pure-menu-horizontal pure-menu-item pure-menu-has-children pure-menu-allow-hover version"><a href="#" class="pure-menu-link">Version 5.1.8-pre</a><ul class="pure-menu-children"><li class="pure-menu-item"><a href="/docs/4.x" class="pure-menu-link">Version 4.13.14</a></li><li class="pure-menu-item"><a href="/docs/3.8.x" class="pure-menu-link">Version 3.8.40</a></li></ul></li><li class="pure-menu-item"><a href="/docs/index.html" class="pure-menu-link">Quick Start</a></li><li class="pure-menu-item"><a href="/docs/guides.html" class="pure-menu-link">Guides</a></li><li class="pure-menu-item sub-item"><a href="/docs/guide.html" class="pure-menu-link">Schemas</a></li><li class="pure-menu-item sub-item"><a href="/docs/schematypes.html" class="pure-menu-link">SchemaTypes</a></li><li class="pure-menu-item sub-item"><a href="/docs/connections.html" class="pure-menu-link">Connections</a></li><li class="pure-menu-item sub-item"><a href="/docs/models.html" class="pure-menu-link">Models</a></li><li class="pure-menu-item sub-item"><a href="/docs/documents.html" class="pure-menu-link">Documents</a></li><li class="pure-menu-item sub-item"><a href="/docs/subdocs.html" class="pure-menu-link">Subdocuments</a></li><li class="pure-menu-item sub-item"><a href="/docs/queries.html" class="pure-menu-link">Queries</a></li><li class="pure-menu-item sub-item"><a href="/docs/validation.html" class="pure-menu-link">Validation</a></li><li class="pure-menu-item sub-item"><a href="/docs/middleware.html" class="pure-menu-link">Middleware</a></li><li class="pure-menu-item sub-item"><a href="/docs/populate.html" class="pure-menu-link">Populate</a></li><li class="pure-menu-item sub-item"><a href="/docs/discriminators.html" class="pure-menu-link">Discriminators</a></li><li class="pure-menu-item sub-item"><a href="/docs/plugins.html" class="pure-menu-link">Plugins</a></li><li class="pure-menu-item"><a href="/docs/api.html" class="pure-menu-link">API</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#mongoose_Mongoose" class="pure-menu-link">Mongoose</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Schema" class="pure-menu-link">Schema</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Connection" class="pure-menu-link">Connection</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Document" class="pure-menu-link">Document</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Model" class="pure-menu-link">Model</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Query" class="pure-menu-link">Query</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Aggregate" class="pure-menu-link">Aggregate</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Schematype" class="pure-menu-link">SchemaType</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Virtualtype" class="pure-menu-link">VirtualType</a></li><li class="pure-menu-item"><a href="/docs/compatibility.html" class="pure-menu-link">Version Compatibility</a></li><li class="pure-menu-item"><a href="/docs/faq.html" class="pure-menu-link">FAQ</a></li><li class="carbon-ad"><script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=mongoosejscom" id="_carbonads_js"></script></li></ul></div></div><div class="container"><div id="content"><h2 id="documents">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 id="retrieving">Retrieving</h3>
<p>There are many ways to retrieve documents from MongoDB. We won't cover that
in this section. See the chapter on <a href="./queries.html">querying</a> for detail.</p>
<h3 id="updating">Updating</h3>
<p>There are a number of ways to update documents. We'll first look at a
traditional approach using <a href="./api.html#model_Model.findById">findById</a>:</p>
<pre><code class="lang-javascript">Tank.findById(id, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, tank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> handleError(err);
tank.size = <span class="hljs-string">'large'</span>;
tank.save(<span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, updatedTank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> handleError(err);
res.send(updatedTank);
});
});
</code></pre>
<p>You can also use <a href="./api.html#document_Document-set"><code>.set()</code></a>
to modify documents. Under the hood, <code>tank.size = 'large';</code> becomes
<code>tank.set({ size: 'large' })</code>.</p>
<pre><code class="lang-javascript">Tank.findById(id, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, tank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> handleError(err);
tank.set({ size: <span class="hljs-string">'large'</span> });
tank.save(<span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, updatedTank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> handleError(err);
res.send(updatedTank);
});
});
</code></pre>
<p>This approach involves first retrieving the document from Mongo, then
issuing an update command (triggered by calling <code>save</code>). However, if we
don'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="lang-javascript">Tank.update({ _id: id }, { $set: { size: <span class="hljs-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="lang-javascript">Tank.findByIdAndUpdate(id, { $set: { size: <span class="hljs-string">'large'</span> }}, { <span class="hljs-keyword">new</span>: <span class="hljs-literal">true</span> }, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, tank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-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>
<p><em>Note that <code>findAndUpdate/Remove</code> do <em>not</em> execute any hooks or validation before making the change in the database. You can use the <a href="/docs/validation.html#update-validators"><code>runValidators</code> option</a> to access a limited subset of document validation. However, if you need hooks and full document validation, first query for the document and then <code>save()</code> it.</em></p>
<h3 id="validating">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="overwriting">Overwriting</h3>
<p>You can overwrite an entire document using <code>.set()</code>. This is handy if you
want to change what document is being saved in <a href="./middleware.html">middleware</a>.</p>
<pre><code class="lang-javascript">Tank.findById(id, <span class="hljs-function"><span class="hljs-keyword">function</span> (<span class="hljs-params">err, tank</span>) </span>{
<span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">return</span> handleError(err);
<span class="hljs-comment">// Now `otherTank` is a copy of `tank`</span>
otherTank.set(tank);
});
</code></pre>
<h3 id="next-up">Next Up</h3>
<p>Now that we've covered Documents, let's take a look at
<a href="/docs/subdocs.html">Subdocuments</a>.</p>
</div></div><script type="text/javascript">!function(name,path,ctx){
var latest,prev=name!=='Keen'&&window.Keen?window.Keen:false;ctx[name]=ctx[name]||{ready:function(fn){var h=document.getElementsByTagName('head')[0],s=document.createElement('script'),w=window,loaded;s.onload=s.onerror=s.onreadystatechange=function(){if((s.readyState&&!(/^c|loade/.test(s.readyState)))||loaded){return}s.onload=s.onreadystatechange=null;loaded=1;latest=w.Keen;if(prev){w.Keen=prev}else{try{delete w.Keen}catch(e){w.Keen=void 0}}ctx[name]=latest;ctx[name].ready(fn)};s.async=1;s.src=path;h.parentNode.insertBefore(s,h)}}
}('KeenAsync','https://d26b395fwzu5fz.cloudfront.net/keen-tracking-1.1.3.min.js',this);
KeenAsync.ready(function(){
// Configure a client instance
var client = new KeenAsync({
projectId: '59aad9cbc9e77c0001ce1b32',
writeKey: '4B38B0046086885E425D368BFAEAD8FD0D4F2DC2FA2F936FDE058D79508AEFAD9886BC020B96520823BB9C8241D9D9BCFDC0EF52E6033BD89D06E4B24FC13AE955896BF443406269A84DD009CEB5862DCEC944874DB2107FD648DA91ADC1E6DE'
});
client.recordEvent('pageView', {
host: window.location.host,
pathname: window.location.pathname,
hash: window.location.hash
});
});</script><script type="text/javascript">(function (window, document) {
var layout = document.getElementById('layout'),
menu = document.getElementById('menu'),
menuLink = document.getElementById('menuLink'),
content = document.getElementById('content');
function toggleClass(element, className) {
var classes = element.className.split(/\s+/),
length = classes.length,
i = 0;
for(; i < length; i++) {
if (classes[i] === className) {
classes.splice(i, 1);
break;
}
}
// The className is not found
if (length === classes.length) {
classes.push(className);
}
element.className = classes.join(' ');
}
function toggleAll(e) {
var active = 'active';
e.preventDefault();
toggleClass(layout, active);
toggleClass(menu, active);
toggleClass(menuLink, active);
}
menuLink.onclick = function (e) {
toggleAll(e);
};
content.onclick = function(e) {
if (menu.className.indexOf('active') !== -1) {
toggleAll(e);
}
};
}(this, this.document));</script></div></body></html>