"Embedded document" or "subdocument"?

Hi there,

What does MongoDB call the following child value in the following examples:

  1. { child: { _id: ObjectId, name: 'Ricky' }}
  2. { child: { name: 'Ricky' }}

Mongoose calls these a “subdocument” and “nested path” respectively

MongoDB calls these both a “subdocument” and “embedded document”

Is there anyone that can advise on the naming convention used? Thanks

I like to use object and keep document for entities of a collection.

Why object?

  1. It is a BSON type : https://www.mongodb.com/docs/manual/reference/bson-types/
  2. It is the result of {$type:"$child"} : https://www.mongodb.com/docs/manual/reference/operator/aggregation/type/
  3. If you look in Compass, it is marked as Object
  4. The term object is used in $jsonSchema. It is used there because of item 1 above.
  5. It is the O in JSON and BSON

So collection.findOne({}) gives you a document. And document.child gives you an object.

And if not confusing enough, in Java,

  1. Document inherits from the Object class,
  2. the equivalent of collection.findOne() gives you a Document
  3. the equivalent of document.child gives you a Document

And in JS

> document = collection.findOne( { _id : 0 })
< { _id: 0, child: { age: 1 } }
> typeof document
< 'object'
> child = document.child
< { age: 1 }
> typeof child
< 'object'
> collection.aggregate( [
  { "$match" : { "_id" : 0 } } ,
  { $set : { "type_of_child:" : { "$type" : "$child"}}}
] )
{ _id: 0, child: { age: 1 }, 'type_of_child:': 'object' }

Welcome to the MongoDB Community @Ricky0 !

`“Embedded document” and “subdocument” are used interchangeably, and you’ll also see references like “embedded subdocument” and “nested document”. Preferred naming conventions also depend on context (for example, language drivers or ODMs can be influenced by the author or phrases that are more idiomatic for a language community).

As @steevej illustrated, many object-oriented programming languages use Object as a primitive type that is extended with additional properties, and have class definitions as a template for creation of objects. Structured data without an associated class will be typed as an Object; data with a class will ultimately inherit from Object or an equivalent primitive class.

The document nomenclature comes from data modelling and thinking about the shape and relationship of data. Embedded documents represent relationships (1:1 or 1:many) that are candidates for normalisation if you are designing a data model optimised for storage efficiency (or tabular data limitations) rather than application efficiency. Optimal MongoDB data models will support how data is commonly used by your application, which includes choices like appropriately modelling relationships with linking versus embedding.

I don’t have a strong preference for using “embedded document” vs “subdocument”, but I do think of these as referring to the shape of data as compared to “objects” which may include additional functional hooks and attributes.

For example, Mongoose follows an Object-Document Mapper (ODM) pattern where your code interacts with Mongoose objects that represent MongoDB documents (the data actually stored in your MongoDB deployment). Mongoose objects have associated middleware functions and virtual properties that are not part of the database representation. Mongoose also has some specific schema treatment for Subdocuments versus Nested Paths: both are stored identically in MongoDB so this a Mongoose-specific difference.


1 Like