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

@@ -11,11 +11,12 @@ Model Your Data
 .. meta::
    :keywords: ruby framework, odm, model, class, query
 
-.. .. toctree::
-..    :caption: Data Modeling
-..    
-..    Documents </data-modeling/documents>
+.. toctree::
+   :caption: Data Modeling
+
+   Documents </data-modeling/documents>
 
 In this section, you can learn how to model data in {+odm+}.
 
-.. - :ref:``: Learn how to ...
+- :ref:`mongoid-modeling-documents`: Learn about the ``Document``
+  module.

source/data-modeling/documents.txt

@@ -0,0 +1,93 @@
+.. _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 representation of a MongoDB
+document. 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>`__.
+
+MongoDB Representation
+----------------------
+
+The representation of a ``Document`` in MongoDB is a BSON object that is
+similar to a {+language+} hash or JSON object. You can store instances
+of your models directly in a collection in the database, or you can
+embed them in other classes that use the ``Document`` module.
+
+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.