This document provides an overview of Mongoose and how to get started using it with MongoDB. It explains how to connect to a MongoDB database, define a schema for documents, compile a model, create and save documents to the database, add methods to documents, and query the database. Key aspects covered include defining schemas with fields and validators, creating document instances from models, saving documents, adding methods to schemas to expose functionality on documents, and querying for all documents in a collection.
Workshop - Best of Both Worlds_ Combine KG and Vector search for enhanced R...
Mongoose getting started-Mongo Db with Node js
1. Mongoose
http://mongoosejs.com/docs/index.html
http://fredkschott.com/post/2014/06/require-and-the-module-system/
http://nodeguide.com/style.html
Mongoose#Schema()
The Mongoose Schema constructor
Example:
var mongoose = require('mongoose');
var Schema = mongoose.Schema;
var CatSchema = new Schema(..);
//other eg of declaring schema//
var Schema = mongoose.Schema
, ObjectId = Schema.ObjectId;
var UserSchema = new Schema({
email: String
, hash: String
});
Schema.reserved
Reserved document keys.
show code
Keys in this object are names that are rejected in schema declarations b/c they conflict with
mongoose functionality. Using these key name will throw an error.
on, emit, _events, db, get, set, init, isNew, errors, schema, options, modelName,
collection, _pres, _posts, toObject
2. NOTE: Use of these terms as method names is permitted, but play at your own risk, as they may be
existing mongoose document methods you are stomping on.
var schema = new Schema(..);
schema.methods.init = function () {} // potentially breaking
Models
Models are fancy constructors compiled from our Schema definitions. Instances of these models
representdocuments which can be saved and retreived from our database. All document creation
and retreival from the database is handled by these models.
Compiling your first model
var schema = new mongoose.Schema({ name: 'string', size: 'string' });
var Tank = mongoose.model('Tank', schema);
var Schema = mongoose.Schema
, ObjectId = Schema.ObjectId;
var UserSchema = new Schema({
email: String
, hash: String
});
var User = mongoose.model('User', UserSchema);
Constructing documents
Documents are instances of our model. Creating them and saving to the database is easy:
var Tank = mongoose.model('Tank', yourSchema);
var small = new Tank({ size: 'small' });
small.save(function (err) {
if (err) return handleError(err);
// saved!
3. })
// or
Tank.create({ size: 'small' }, function (err, small) {
if (err) return handleError(err);
// saved!
})
Note that no tanks will be created/removed until the connection your model uses is open. In this
case we are using mongoose.model() so let's open the default mongoose connection:
mongoose.connect('localhost', 'gettingstarted');
Querying
Finding documents is easy with Mongoose, which supports the rich query syntax of MongoDB.
Documents can be retreived using each models find, findById, findOne, or where static methods.
Tank.find({ size: 'small' }).where('createdDate').gt(oneYearAgo).exec(callback);
Removing
Models have a static remove method available for removing all documents matching conditions.
Tank.remove({ size: 'large' }, function (err) {
if (err) return handleError(err);
// removed!
});
Queries
Documents can be retrieved through several static helper methods of models.
Any model method which involves specifying query conditions can be executed two ways:
When a callback function:
4. is passed, the operation will be executed immediately with the results passed to the callback.
is not passed, an instance of Query is returned, which provides a
special QueryBuilder interface for you.
Let's take a look at what happens when passing a callback:
var Person = mongoose.model('Person', yourSchema);
// find each person with a last name matching 'Ghost', selecting the `name` and
`occupation` fields
Person.findOne({ 'name.last': 'Ghost' }, 'name occupation', function (err, person) {
if (err) return handleError(err);
console.log('%s %s is a %s.', person.name.first, person.name.last,
person.occupation) // Space Ghost is a talk show host.
})
Here we see that the query was executed immediately and the results passed to our callback. All
callbacks in Mongoose use the pattern: callback(error, result). If an error occurs executing the
query, the errorparameter will contain an error document, and result will be null. If the query is
successful, the errorparameter will be null, and the result will be populated with the results of the
query.
Anywhere a callback is passed to a query in Mongoose, the callback follows the
patterncallback(error, results). What results is depends on the operation: For findOne() it is
a potentially-null single document, find() a list of documents, count() the number of
documents, update() thenumber of documents affected, etc. The API docs for Models provide more
detail on what is passed to the callbacks.
Now let's look at what happens when no callback is passed:
// find each person with a last name matching 'Ghost'
var query = Person.findOne({ 'name.last': 'Ghost' });
// selecting the `name` and `occupation` fields
query.select('name occupation');
// execute the query at a later time
query.exec(function (err, person) {
if (err) return handleError(err);
5. console.log('%s %s is a %s.', person.name.first, person.name.last,
person.occupation) // Space Ghost is a talk show host.
})
An instance of Query was returned which allows us to build up our query. Taking this example
further:
Person
.find({ occupation: /host/ })
.where('name.last').equals('Ghost')
.where('age').gt(17).lt(66)
.where('likes').in(['vaporizing', 'talking'])
.limit(10)
.sort('-occupation')
.select('name occupation')
.exec(callback);
References to other documents
There are no joins in MongoDB but sometimes we still want references to documents in other
collections. This is where population comes in. Read more about how to include documents from
other collections in your query results here.
Streaming
Queries can be streamed from MongoDB to your application as well. Simply call the
query's stream method instead of exec to return an instance of QueryStream. Note: QueryStreams
are Node.js 0.8 style read streams not Node.js 0.10 style.
Population
There are no joins in MongoDB but sometimes we still want references to documents in other
collections. This is where population comes in.
Population is the process of automatically replacing the specified paths in the document with
document(s) from other collection(s). We may populate a single document, multiple documents,
plain object, multiple plain objects, or all objects returned from a query. Let's look at some examples.
var mongoose = require('mongoose')
6. , Schema = mongoose.Schema
var personSchema = Schema({
_id : Number,
name : String,
age : Number,
stories : [{ type: Schema.Types.ObjectId, ref: 'Story' }]
});
var storySchema = Schema({
_creator : { type: Number, ref: 'Person' },
title : String,
fans : [{ type: Number, ref: 'Person' }]
});
var Story = mongoose.model('Story', storySchema);
var Person = mongoose.model('Person', personSchema);
So far we've created two Models. Our Person model has it's stories field set to an array
of ObjectIds. The refoption is what tells Mongoose which model to use during population, in our
case the Story model. All _ids we store here must be document _ids from the Story model. We
also declared the Story _creator property as aNumber, the same type as the _id used in
the personSchema. It is important to match the type of _id to the type of ref.
Note: ObjectId, Number, String, and Buffer are valid for use as refs.
Saving refs
Saving refs to other documents works the same way you normally save properties, just assign
the _id value:
var aaron = new Person({ _id: 0, name: 'Aaron', age: 100 });
aaron.save(function (err) {
if (err) return handleError(err);
var story1 = new Story({
title: "Once upon a timex.",
_creator: aaron._id // assign the _id from the person
7. });
story1.save(function (err) {
if (err) return handleError(err);
// thats it!
});
})
Population
So far we haven't done anything much different. We've merely created a Person and a Story. Now
let's take a look at populating our story's _creator using the query builder:
Story
.findOne({ title: 'Once upon a timex.' })
.populate('_creator')
.exec(function (err, story) {
if (err) return handleError(err);
console.log('The creator is %s', story._creator.name);
// prints "The creator is Aaron"
})
Populated paths are no longer set to their original _id , their value is replaced with the mongoose
document returned from the database by performing a separate query before returning the results.
Arrays of refs work the same way. Just call the populate method on the query and an array of
documents will be returned in place of the original _ids.
Note: mongoose >= 3.6 exposes the original _ids used during population through
thedocument#populated() method.
Field selection
What if we only want a few specific fields returned for the populated documents? This can be
accomplished by passing the usual field name syntax as the second argument to the populate
method:
Story
.findOne({ title: /timex/i })
8. .populate('_creator', 'name') // only return the Persons name
.exec(function (err, story) {
if (err) return handleError(err);
console.log('The creator is %s', story._creator.name);
// prints "The creator is Aaron"
console.log('The creators age is %s', story._creator.age);
// prints "The creators age is null'
})
Populating multiple paths
What if we wanted to populate multiple paths at the same time?
Story
.find(...)
.populate('fans author') // space delimited path names
.exec()
In mongoose >= 3.6, we can pass a space delimited string of path names to populate. Before 3.6
you must execute the populate() method multiple times.
Story
.find(...)
.populate('fans')
.populate('author')
.exec()
Queryconditions and other options
What if we wanted to populate our fans array based on their age, select just their names, and return
at most, any 5 of them?
Story
.find(...)
.populate({
path: 'fans',
9. match: { age: { $gte: 21 }},
select: 'name -_id',
options: { limit: 5 }
})
.exec()
Refs to children
We may find however, if we use the aaron object, we are unable to get a list of the stories. This is
because nostory objects were ever 'pushed' onto aaron.stories.
There are two perspectives here. First, it's nice to have aaron know which stories are his.
aaron.stories.push(story1);
aaron.save(callback);
This allows us to perform a find and populate combo:
Person
.findOne({ name: 'Aaron' })
.populate('stories') // only works if we pushed refs to children
.exec(function (err, person) {
if (err) return handleError(err);
console.log(person);
})
It is debatable that we really want two sets of pointers as they may get out of sync. Instead we could
skip populating and directly find() the stories we are interested in.
Story
.find({ _creator: aaron._id })
.exec(function (err, stories) {
if (err) return handleError(err);
console.log('The stories are an array: ', stories);
})
10. Updating refs
Now that we have a story we realized that the _creator was incorrect. We can update refs the
same as any other property through Mongoose's internal casting:
var guille = new Person({ name: 'Guillermo' });
guille.save(function (err) {
if (err) return handleError(err);
story._creator = guille;
console.log(story._creator.name);
// prints "Guillermo" in mongoose >= 3.6
// see https://github.com/LearnBoost/mongoose/wiki/3.6-release-notes
story.save(function (err) {
if (err) return handleError(err);
Story
.findOne({ title: /timex/i })
.populate({ path: '_creator', select: 'name' })
.exec(function (err, story) {
if (err) return handleError(err);
console.log('The creator is %s', story._creator.name)
// prints "The creator is Guillermo"
})
})
})
The documents returned from query population become fully functional, removeable, saveable
documents unless the lean option is specified. Do not confuse them with sub docs. Take caution
when calling its remove method because you'll be removing it from the database, not just the array.
Populating an existing document
If we have an existing mongoose document and want to populate some of its paths, mongoose >=
3.6supports the document#populate() method.
11. Populating multiple existing documents
If we have one or many mongoose documents or even plain objects (like mapReduce output), we
may populate them using the Model.populate() method available in mongoose >= 3.6. This is
whatdocument#populate() and query#populate() use to populate documents.
Field selection difference fromv2 to v3
Field selection in v3 is slightly different than v2. Arrays of fields are no longer accepted. See
themigration guide and the example below for more detail.
// this works in v3
Story.findOne(..).populate('_creator', 'name age').exec(..);
// this doesn't
Story.findOne(..).populate('_creator', ['name', 'age']).exec(..);
SchemaTypes
SchemaTypes handle definition of path defaults, validation, getters, setters, field selection
defaults for queriesand other general characteristics for Strings and Numbers. Check out their
respective API documentation for more detail.
Following are all valid Schema Types.
String
Number
Date
Buffer
Boolean
Mixed
Objectid
Array
Example
var schema = new Schema({
name: String,
binary: Buffer,
13. m.save(callback);
Getting Started
First be sure you have MongoDB and Node.js installed.
Next install Mongoose from the command line using npm:
$ npm install mongoose
Now say we like fuzzy kittens and want to record every kitten we ever meet in MongoDB. The first
thing we need to do is include mongoose in our project and open a connection to the test database
on our locally running instance of MongoDB.
// getting-started.js
var mongoose = require('mongoose');
mongoose.connect('mongodb://localhost/test');
We have a pending connection to the test database running on localhost. We now need to get
notified if we connect successfully or if a connection error occurs:
var db = mongoose.connection;
db.on('error', console.error.bind(console, 'connection error:'));
db.once('open', function (callback) {
// yay!
});
Once our connection opens, our callback will be called. For brevity, let's assume that all following
code is within this callback.
With Mongoose, everything is derived from a Schema. Let's get a reference to it and define our
kittens.
var kittySchema = mongoose.Schema({
name: String
})
14. So far so good. We've got a schema with one property, name, which will be a String. The next step
is compiling our schema into a Model.
var Kitten = mongoose.model('Kitten', kittySchema)
A model is a class with which we construct documents. In this case, each document will be a kitten
with properties and behaviors as declared in our schema. Let's create a kitten document
representing the little guy we just met on the sidewalk outside:
var silence = new Kitten({ name: 'Silence' })
console.log(silence.name) // 'Silence'
Kittens can meow, so let's take a look at how to add "speak" functionality to our documents:
// NOTE: methods must be added to the schema before compiling it with
mongoose.model()
kittySchema.methods.speak = function () {
var greeting = this.name
? "Meow name is " + this.name
: "I don't have a name"
console.log(greeting);
}
var Kitten = mongoose.model('Kitten', kittySchema)
Functions added to the methods property of a schema get compiled into the Model prototype and
exposed on each document instance:
var fluffy = new Kitten({ name: 'fluffy' });
fluffy.speak() // "Meow name is fluffy"
We have talking kittens! But we still haven't saved anything to MongoDB. Each document can be
saved to the database by calling its save method. The first argument to the callback will be an error if
any occured.
fluffy.save(function (err, fluffy) {
if (err) return console.error(err);
fluffy.speak();
15. });
Say time goes by and we want to display all the kittens we've seen. We can access all of the kitten
documents through our Kitten model.
Kitten.find(function (err, kittens) {
if (err) return console.error(err);
console.log(kittens)
})
We just logged all of the kittens in our db to the console. If we want to filter our kittens by name,
Mongoose supports MongoDBs rich querying syntax.
Kitten.find({ name: /^Fluff/ }, callback)
This performs a search for all documents with a name property that begins with "Fluff" and returns
the results to the callback.