An Introduction to Mongoose Arrays
Mongoose's Array class extends vanilla JavaScript arrays with additional Mongoose functionality. For example, suppose you have a blog post schema with an array of tags.
const blogPostSchema = Schema({ title: String, tags: [String] });When you create a new BlogPost document, the tags property is an instance of the vanilla JavaScript array class. But it also has some special properties.
const blogPostSchema = Schema({ title: String, tags: [String] }, { versionKey: false }); const BlogPost = mongoose.model('BlogPost', blogPostSchema); const doc = new BlogPost({ title: 'Intro to JavaScript', tags: ['programming'] }); Array.isArray(doc.tags); // true doc.tags.isMongooseArray; // trueFor example, Mongoose intercepts push() calls on the tags array, and is smart enough to update the document using $push when you save() the document.
mongoose.set('debug', true); doc.tags.push('web development'); // Because of 'debug' mode, will print: // Mongoose: blogposts.updateOne({ _id: ObjectId(...) }, { '$push': { tags: { '$each': [ 'web development' ] } } }, { session: null }) await doc.save();Document Arrays
The tags example is an array of primitives. Mongoose also supports arrays of subdocuments. Here's how you can define an array of members, each with a firstName and lastName property.
const groupSchema = Schema({ name: String, members: [{ firstName: String, lastName: String }] });doc.members is an instance of a vanilla JavaScript array, so it has all the usual functions, like slice() and filter(). But it also has some Mongoose-specific functionality baked in.
const groupSchema = Schema({ name: String, members: [{ firstName: String, lastName: String }] }); const Group = mongoose.model('Group', groupSchema); const doc = new Group({ title: 'Jedi Order', members: [{ firstName: 'Luke', lastName: 'Skywalker' }] }); Array.isArray(doc.members); // true doc.members.isMongooseArray; // true doc.members.isMongooseDocumentArray; // trueFor example, if you set the 0th member's firstName, Mongoose will translate that to a set on member.0.firstName when you call save().
const groupSchema = Schema({ name: String, members: [{ firstName: String, lastName: String }] }, { versionKey: false }); const Group = mongoose.model('Group', groupSchema); const doc = new Group({ title: 'Jedi Order', members: [{ firstName: 'Luke', lastName: 'Skywalker' }] }); await doc.save(); mongoose.set('debug', true); doc.members[0].firstName = 'Anakin'; // Prints: // Mongoose: groups.updateOne({ _id: ObjectId("...") }, // { '$set': { 'members.0.firstName': 'Anakin' } }, { session: null }) await doc.save();Caveat With Setting Array Indexes
Mongoose has a known issue with setting array indexes directly. For example, if you set doc.tags[0], Mongoose change tracking won't pick up that change.
const blogPostSchema = Schema({ title: String, tags: [String] }, { versionKey: false }); const BlogPost = mongoose.model('BlogPost', blogPostSchema); const doc = new BlogPost({ title: 'Intro to JavaScript', tags: ['programming'] }); await doc.save(); // This change won't end up in the database! doc.tags[0] = 'JavaScript'; await doc.save(); const fromDb = await BlogPost.findOne({ _id: doc._id }); fromDb.tags; // ['programming']To work around this caveat, you need to inform Mongoose's change tracking of the change, either using the markModified() method or by explicitly calling MongooseArray#set() on the array element as shown below.
// This change works. `set()` is a special method on Mongoose // arrays that triggers change tracking. doc.tags.set(0, 'JavaScript'); await doc.save(); const fromDb = await BlogPost.findOne({ _id: doc._id }); fromDb.tags; // ['JavaScript']