publishing: SQL comparison charts

Author: Sam Kleinman

source/contents.txt

@@ -18,4 +18,3 @@ MongoDB Manual Contents
    use-cases
    faq
    reference
-   sql

source/index.txt

@@ -43,13 +43,20 @@ MongoDB...
 
    - **For Developers**
 
-     The task when building an application with MongoDB, is selecting
-     a programming :doc:`language and driver
+     The first task when building an application with MongoDB, is
+     selecting a programming :doc:`language and driver
      <applications/drivers>`. Most of the drivers have their own
      tutorials; however, for all drivers you may want to understand a
      few core MongoDB concepts. The wiki's :wiki:`developer docs
      <Developer+Zone>` outlines these topics.
 
+     If you're familiar with database systems that use SQL, consider
+     the following documents, which compare common MongoDB conventions and
+     operations with their SQL equivalents: 
+     
+     - :doc:`/reference/sql-comparison`
+     - :doc:`/reference/sql-aggregation-comparison`
+
      Of the developer docs, those covering CRUD (create, read, update,
      and delete) are particularly helpful:
 

source/reference.txt

@@ -7,15 +7,8 @@ Reference
 MongoDB Interface
 -----------------
 
-.. see:: The following interface overview pages:
-   :doc:`/reference/operators` for an overview of all query, update,
-   and projection operators; :doc:`/reference/meta-query-operators`
-   for all special "meta" query operators;
-   :doc:`/reference/aggregation` for all :doc:`aggregation
-   </aggregation>` operators; :doc:`/reference/commands` for an
-   overview of all :term:`database commands <database command>`; and
-   the :doc:`/reference/javascript` for all :program:`mongo` shell
-   methods and helpers
+Reference
+~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
@@ -24,6 +17,30 @@ MongoDB Interface
    reference/command
    reference/method
 
+MongoDB and SQL Interface Comparisons
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following documents provide mappings between MongoDB
+concepts and statements and SQL concepts and statements.
+
+.. toctree::
+   :maxdepth: 1
+   
+   reference/sql-comparison
+   reference/sql-aggregation-comparison
+
+Overviews
+~~~~~~~~~
+
+For this reference material in another form, consider the following
+interface overview pages: 
+
+- :doc:`/reference/operators` for an overview of all query, update, and projection operators;
+- :doc:`/reference/meta-query-operators` for all special "meta" query operators; 
+- :doc:`/reference/aggregation` for all :doc:`aggregation </aggregation>` operators; 
+- :doc:`/reference/commands` for an overview of all :term:`database commands <database command>`; and 
+- :doc:`/reference/javascript` for all :program:`mongo` shell methods and helpers.
+
 .. _man-pages:
 
 Architecture and Components

source/reference/sql-aggregation-comparison.txt

@@ -1,21 +1,21 @@
-.. default-domain:: mongodb
-
+==========================================
 SQL to Aggregation Framework Mapping Chart
-------------------------------------------
+==========================================
+
+.. default-domain:: mongodb
 
-With its :doc:`aggregation framework </applications/aggregation>`,
-MongoDB provides analogous functionality to common SQL aggregation
-functions.
+The :doc:`aggregation framework </applications/aggregation>` allows
+MongoDB to provide native aggregation capabilities that corresponds to
+many common data aggregation operations in SQL.
 
-The following table presents a quick reference of the various SQL
-aggregation terms, functions, and concepts and the corresponding
-MongoDB :ref:`aggregation operators
-<aggregation-pipeline-operator-reference>`:
+The following table provides an overview of common SQL aggregation
+terms, functions, and concepts and the corresponding MongoDB
+:ref:`aggregation operators <aggregation-pipeline-operator-reference>`:
 
 .. include:: /includes/table-sql-to-agg-terms.rst
 
 Examples
-~~~~~~~~
+--------
 
 The following table presents a quick reference of SQL aggregation
 statements and the corresponding MongoDB statements. The examples in
@@ -39,8 +39,9 @@ the table assume the following conditions:
                 { sku: "yyy", qty: 25, price: 1 } ]
      }
 
-- In the MongoDB statements, the fields of the :term:`documents
-  <document>` in the collection ``orders`` are prefixed with ``$`` when
-  they appear as operands to the aggregation operators.
+- The MongoDB statements prefix, the names of the fields from the
+  :term:`documents <document>` in the collection ``orders`` with a
+  ``$`` character when they appear as operands to the aggregation
+  operations.
 
 .. include:: /includes/table-sql-to-agg-examples.rst

source/reference/sql-comparison.txt

@@ -1,18 +1,19 @@
-.. default-domain:: mongodb
+============================
+SQL to MongoDB Mapping Chart
+============================
 
-SQL to Mongo Mapping Chart
---------------------------
+.. default-domain:: mongodb
 
 Executables
-~~~~~~~~~~~
+-----------
 
 The following table presents a quick reference to the MySQL/Oracle
 executables and the corresponding MongoDB executables.
 
 .. include:: /includes/table-sql-to-mongo-executables.rst
 
 Terminology/Concepts
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 The following table presents a quick reference of the various SQL
 terminology and concepts and the corresponding MongoDB terminology and
@@ -21,7 +22,7 @@ concepts.
 .. include:: /includes/table-sql-to-mongo-terms.rst
 
 Examples
-~~~~~~~~
+--------
 
 The following table presents a quick reference of the various SQL
 statements and the corresponding MongoDB statements. The examples in
@@ -42,7 +43,7 @@ the table assume the following conditions:
      }
 
 Create and Alter Table
-``````````````````````
+~~~~~~~~~~~~~~~~~~~~~~
 
 The following table presents a quick reference of the various SQL
 statements related to table-level actions and the corresponding MongoDB
@@ -51,7 +52,7 @@ statements.
 .. include:: /includes/table-sql-to-mongo-schema-examples.rst
 
 Insert into Table
-`````````````````
+~~~~~~~~~~~~~~~~~
 
 The following table presents a quick reference of the various SQL
 statements related to inserting records into tables and the
@@ -60,7 +61,7 @@ corresponding MongoDB statements.
 .. include:: /includes/table-sql-to-mongo-insert-examples.rst
 
 Select from Table
-`````````````````
+~~~~~~~~~~~~~~~~~
 
 The following table presents a quick reference of the various SQL
 statements related to reading records from tables and the corresponding
@@ -69,7 +70,7 @@ MongoDB statements.
 .. include:: /includes/table-sql-to-mongo-select-examples.rst
 
 Update Records in Table
-```````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The following table presents a quick reference of the various SQL
 statements related to updating existing records in tables and the
@@ -78,7 +79,7 @@ corresponding MongoDB statements.
 .. include:: /includes/table-sql-to-mongo-update-examples.rst
 
 Delete Records from Table
-`````````````````````````
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following table presents a quick reference of the various SQL
 statements related to deleting records from tables and the