mongoose/docs/models.html at 5.2 · JavaScriptBach/mongoose

History

158 lines (141 loc) · 19 KB

Raw

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

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

<!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: Models</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"></a><div id="mobile-logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png">mongoose</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">mongoose</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>Models</h2><a href="./api.html#model-js">Models</a> are fancy constructors compiled from

<code>Schema</code> definitions. An instance of a model is called a

<a href="./documents.html">document</a>. Models are responsible for creating and

reading documents from the underlying MongoDB database.

<ul><li><a href="#compiling">Compiling your first model</a></li><li><a href="#constructing-documents">Constructing Documents</a></li><li><a href="#querying">Querying</a></li><li><a href="#deleting">Deleting</a></li><li><a href="#updating">Updating</a></li><li><a href="#change-streams">Change Streams</a></li></ul><h3 id="compiling">Compiling your first model</h3><pre><code class="lang-javascript">var schema = new mongoose.Schema({ name: 'string', size: 'string' });

var Tank = mongoose.model('Tank', schema);

</code></pre>

The first argument is the singular name of the collection your model is for. Mongoose automatically looks for the plural version of your model name.

Thus, for the example above, the model Tank is for the tanks collection in the database.

The <code>.model()</code> function makes a copy of <code>schema</code>. Make sure that you've added everything you want to <code>schema</code> before calling <code>.model()</code>!

<h3 id="constructing-documents">Constructing Documents</h3>An instance of a model is called a <a href="./documents.html">document</a>. Creating

them and saving to the database is easy.

<pre><code class="lang-javascript">var Tank = mongoose.model('Tank', yourSchema);

var small = new Tank({ size: 'small' });

small.save(function (err) {

if (err) return handleError(err);

// saved!

});

// or

Tank.create({ size: 'small' }, function (err, small) {

if (err) return handleError(err);

// saved!

});

// or, for inserting large batches of documents

Tank.insertMany([{ size: 'small' }], function(err) {

});

</code></pre>

Note that no tanks will be created/removed until the connection your model

uses is open. Every model has an associated connection. When you use

<code>mongoose.model()</code>, your model will use the default mongoose connection.

<pre><code class="lang-javascript">mongoose.connect('localhost', 'gettingstarted');

</code></pre>

If you create a custom connection, use that connection's <code>model()</code> function

instead.

<pre><code class="lang-javascript">var connection = mongoose.createConnection('mongodb://localhost:27017/test');

var Tank = connection.model('Tank', yourSchema);

</code></pre>

<h3 id="querying">Querying</h3>Finding documents is easy with Mongoose, which supports the <a href="http://www.mongodb.org/display/DOCS/Advanced+Queries">rich</a> query syntax of MongoDB. Documents can be retreived using each <code>models</code> <a href="./api.html#model_Model.find">find</a>, <a href="./api.html#model_Model.findById">findById</a>, <a href="./api.html#model_Model.findOne">findOne</a>, or <a href="./api.html#model_Model.where">where</a> static methods.

<pre><code class="lang-javascript">Tank.find({ size: 'small' }).where('createdDate').gt(oneYearAgo).exec(callback);

</code></pre>

See the chapter on <a href="./queries.html">queries</a> for more details on how to use the <a href="./api.html#query-js">Query</a> api.

<h3 id="deleting">Deleting</h3>Models have static <code>deleteOne()</code> and <code>deleteMany()</code> functions

for removing all documents matching the given <code>filter</code>.

<pre><code class="lang-javascript">Tank.deleteOne({ size: 'large' }, function (err) {

if (err) return handleError(err);

// deleted at most one tank document

});

</code></pre>

<h3 id="updating">Updating</h3>Each <code>model</code> has its own <code>update</code> method for modifying documents in the

database without returning them to your application. See the

<a href="./api.html#model_Model.updateOne">API</a> docs for more detail.

<pre><code class="lang-javascript">Tank.updateOne({ size: 'large' }, { name: 'T-90' }, function(err, res) {

// Updated at most one doc, `res.modifiedCount` contains the number

// of docs that MongoDB updated

});

</code></pre>

_If you want to update a single document in the db and return it to your

application, use <a href="./api.html#model_Model.findOneAndUpdate">findOneAndUpdate</a>

instead._

<h3 id="change-streams">Change Streams</h3>New in MongoDB 3.6.0 and Mongoose 5.0.0

<a href="https://docs.mongodb.com/manual/changeStreams/">Change streams</a> provide

a way for you to listen to all inserts and updates going through your

MongoDB database. Note that change streams do not work unless you're

connected to a <a href="https://docs.mongodb.com/manual/replication/">MongoDB replica set</a>.

<pre><code class="lang-javascript">async function run() {

// Create a new mongoose model

const personSchema = new mongoose.Schema({

name: String

});

const Person = mongoose.model('Person', personSchema, 'Person');

// Create a change stream. The 'change' event gets emitted when there's a

// change in the database

Person.watch().

on('change', data => console.log(new Date(), data));

// Insert a doc, will trigger the change stream handler above

console.log(new Date(), 'Inserting doc');

await Person.create({ name: 'Axl Rose' });

}

</code></pre>

The output from the above <a href="http://thecodebarbarian.com/80-20-guide-to-async-await-in-node.js.html">async function</a> will look like what you see below.

<pre><code>2018-05-11T15:05:35.467Z 'Inserting doc'

2018-05-11T15:05:35.487Z 'Inserted doc'

operationType: 'insert',

fullDocument: { _id: 5af5b13fe526027666c6bf83, name: 'Axl Rose', __v: 0 },

ns: { db: 'test', coll: 'Person' },

documentKey: { _id: 5af5b13fe526027666c6bf83 } }

</code></pre>You can read more about <a href="http://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-36-change-streams.html#change-streams-in-mongoose">change streams in mongoose in this blog post</a>.

<h3>Yet more</h3>The <a href="./api.html#model_Model">API docs</a> cover many additional methods available like <a href="./api.html#model_Model.count">count</a>, <a href="./api.html#model_Model.mapReduce">mapReduce</a>, <a href="./api.html#model_Model.aggregate">aggregate</a>, and <a href="./api.html#model_Model.findOneAndRemove">more</a>.

<h3 id="next">Next Up</h3>Now that we've covered <code>Models</code>, let's take a look at <a href="/docs/documents.html">Documents</a>.

</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>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

models.html

Latest commit

History

models.html

File metadata and controls