DOCSP-45358: documents

snooty.toml

@@ -10,7 +10,8 @@ toc_landing_pages = [
     "/quick-start-rails",
     "/quick-start-sinatra",
     "/interact-data",
-    "/interact-data/specify-query"
+    "/interact-data/specify-query",
+    "/data-modeling"
     ]
 
 [constants]

source/data-modeling.txt

@@ -14,9 +14,13 @@ Model Your Data
 .. toctree::
    :caption: Data Modeling
 
+   Documents </data-modeling/documents>
    Inheritance </data-modeling/inheritance>
 
 In this section, you can learn how to model data in {+odm+}.
 
+- :ref:`mongoid-modeling-documents`: Learn about the ``Document``
+  module.
+
 - :ref:`mongoid-modeling-inheritance`: Learn how to implement
   inheritance in your model classes.

source/data-modeling/documents.txt

@@ -0,0 +1,95 @@
+.. _mongoid-modeling-documents:
+
+=========
+Documents
+=========
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: ruby framework, odm, code example, bson
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about the ``Mongoid::Document`` module in
+{+odm+}. The ``Document`` module is a {+language+} implementation of a
+MongoDB document, which stores data in field-and-value pairs. To learn
+more about the terminology, structure, and limitations of
+MongoDB documents, see :manual:`Documents </core/document/>` in the
+{+server-manual+}.
+
+You must include the ``Mongoid::Document`` module in any class that you
+want to persist to MongoDB. By including the ``Document`` module in your
+model class, you can use its methods on instances of your model class.
+
+The following code demonstrates how to include the ``Document`` module
+in a sample ``Person`` model class:
+
+.. code-block:: ruby
+   :emphasize-lines: 2
+
+   class Person
+       include Mongoid::Document
+
+       field :name, type: String
+   end
+
+You can find more information about the ``Document`` module in the `API
+documentation <{+api-root+}/Document.html>`__.
+
+Work with Documents
+-------------------
+
+You can store instances of your models directly in a collection, or you
+can embed them in other classes that use the ``Document`` module.
+When you save a ``Document`` instance to MongoDB, it is converted
+to a BSON object that is similar to a {+language+} hash or JSON
+object.
+
+The following code creates an instance of the ``Person`` model defined
+in the preceding section:
+
+.. code-block:: ruby
+
+   Person.create(name: 'Meena Kumar')
+
+The document appears in MongoDB as follows:
+
+.. code-block:: json
+   :copyable: false
+
+   {
+     "_id": {
+       "$oid": "673b6dce61700598c24a72b0"
+     },
+     "name": "Meena Kumar"
+   }
+
+.. note:: _id Field
+
+   When you persist an instance of a model to the database, MongoDB
+   automatically adds an ``_id`` field that has a unique value even if you
+   do not explicitly define this field in your model.
+
+   To learn more about this field, see the :manual:`ObjectId reference
+   </reference/bson-types/#objectid>` in the {+server-manual+}.
+
+Additional Information
+----------------------
+
+To learn how to access and change your MongoDB data, see the
+:ref:`mongoid-interact-data` guides.
+
+To learn more about how to model your data by using {+odm+} models,
+see the :ref:`mongoid-data-modeling` guides.
+
+.. TODO Add link to field types guide.