Merge pull request #413 from JuliaMongo/DOCSP-29384

(DOCSP)-29384 Clarify the need to name the custom schema when loading it into drdl

Author: JuliaMongo

source/includes/fact-name-your-schema.rst

@@ -0,0 +1,11 @@
+.. important::
+
+   If you upload a custom schema, you must store it with its specified
+   name, using :commandoption:`name-schema <name-schema>`, and then specify
+   this name to the :binary:`~bin.mongosqld` with
+   :option:`--schemaName <mongosqld --schemaName>`.
+   If you don't store the schema's name when you upload it, the schema
+   name defaults to ``defaultSchema``. If the schema's name doesn't exist,
+   this results in an error from :binary:`~bin.mongosqld` similar to the
+   following: MongoDB schema not yet available.
+   Error initializing schema: no schema found for name.

source/includes/options/commandoption-mongodrdl-name-schema.rst

@@ -17,10 +17,10 @@
         - *Required.* Specifies the database where the schema information
           is stored.
 
-      * - ``--name``
+      * - :option:`--name <mongodrdl --name>`
         - *Required.* The new name of the schema.
 
-      * - ``--schema``
+      * - :option:`--schema <mongodrdl --schema>`
         - *Required* The string representation of the
           :ref:`ObjectId <document-bson-type-object-id>` of the schema.
 

source/includes/options/commandoption-mongodrdl-upload.rst

@@ -35,14 +35,21 @@
       :copyable: false
    
       5d793f3f6a26a3ce66c304ea
+
+   The next step is to store the schema under a name you provide, using
+   the :commandoption:`name-schema <name-schema>` command:
+
+   .. code-block:: sh
    
-   To use the newly uploaded schema, restart :binary:`~bin.mongosqld`
-   with the schema database specified by the
-   :option:`--schemaSource <mongosqld --schemaSource>` option and
-   the :option:`--schemaMode <mongosqld --schemaMode>` set to ``custom``:
+      mongodrdl name-schema --name movies --schemaSource schemas --schema 5d793f3f6a26a3ce66c304ea
+   
+   To use the newly uploaded schema that received a specified name,
+   restart :binary:`~bin.mongosqld` with the schema database specified by the
+   :option:`--schemaSource <mongosqld --schemaSource>` option, with the
+   schema's name specified with :option:`--schemaName <mongosqld --schemaName>`:
 
    .. code-block:: sh
    
-      mongosqld --schemaMode custom --schemaSource <schema-db>
+      mongosqld --schemaSource <schema-db> --schemaName movies
    
-
+   .. include:: /includes/fact-name-your-schema.rst

source/includes/options/option-mongodrdl-name.rst

@@ -0,0 +1,9 @@
+.. option:: --name <db-name>
+
+   
+   .. versionadded:: 2.11
+   
+   Specifies the schema name.
+   
+   .. include:: /includes/fact-name-your-schema.rst
+   

source/includes/options/option-mongodrdl-schema.rst

@@ -0,0 +1,7 @@
+.. option:: --schema <db-id>
+
+   .. versionadded:: 2.11
+   
+   *Required*. Specifies the string representation of the
+   :ref:`ObjectId <document-bson-type-object-id>` of the schema.
+

source/includes/options/option-mongosqld-schemaName.rst

@@ -8,7 +8,7 @@
    the :option:`--schemaSource <mongosqld --schemaSource>` database.
    Specifying schema names allows you to store multiple schemas in
    the :option:`--schemaSource <mongosqld --schemaSource>` database.
-   The behavior depends on on the value of
+   The behavior depends on the value of
    :option:`--schemaMode <mongosqld --schemaMode>`:
 
    .. list-table::
@@ -28,8 +28,8 @@
           <mongosqld --schemaSource>` database after the |bi-short|
           samples the schema on startup.
 
-   If not specified, defaults to ``defaultSchema``.
-   
+   .. include:: /includes/fact-name-your-schema.rst
+
    .. include:: /includes/sampling-ref-chart-link.rst
 
 

source/launch.txt

@@ -24,13 +24,23 @@ databases. You have several options for creating a schema and
 launching :binary:`~bin.mongosqld`. This guide will help you choose
 the best option for your needs.
 
-By default, :binary:`~bin.mongosqld` generates a :doc:`data schema
-</schema-configuration>` and holds it in memory. Alternatively, if
-you prefer to create a schema file and edit it manually, use the
-:binary:`~bin.mongodrdl` program to create a ``.drdl`` schema
-file and use the :option:`--schema <mongosqld --schema>` option
-when starting :binary:`~bin.mongosqld`. For more information on schema
-generation and data sampling, see :doc:`schema-configuration`.
+By default, :binary:`~bin.mongosqld` generates a default :doc:`data schema
+</schema-configuration>` and stores it in memory. Alternatively, if you prefer
+to create a custom schema and edit it manually, use one of these two methods:
+
+- Use the :binary:`~bin.mongodrdl` program to create a custom ``.drdl`` schema
+  file and then start :binary:`~bin.mongosqld` with the
+  :option:`--schema <mongodrdl --schema>` option to point to this file.
+
+- If you previously uploaded a custom schema with the :commandoption:`upload`
+  command, you must use the :commandoption:`name-schema <name-schema>`
+  command to store the schema internally under the provided custom name.
+  Then you can start :binary:`~bin.mongosqld` with
+  :option:`--schemaSource <mongosqld --schema>`,
+  :option:`--schemaMode <mongosqld --schema>`, and
+  :option:`--schemaName <mongosqld --schemaName>` options.
+
+To learn more about creating a schema and data sampling, see :doc:`schema-configuration`.
 
 Prerequisites
 -------------

source/reference/mongodrdl.txt

@@ -131,6 +131,10 @@ Core Options
 
 .. include:: /includes/options/option-mongodrdl-preJoined.rst
 
+.. include:: /includes/options/option-mongodrdl-schema.rst
+
+.. include:: /includes/options/option-mongodrdl-name.rst
+
 .. include:: /includes/options/option-mongodrdl-schemaSource.rst
 
 TLS/SSL Options

source/schema-configuration.txt

@@ -26,7 +26,7 @@ The default sampling mode which :binary:`~bin.mongosqld` uses to
 analyze your collections and derive a static schema. In this mode,
 :binary:`~bin.mongosqld` derives the schema on startup and holds the
 schema in memory.
-   
+
 :ref:`bi-persistent-schema`
 ---------------------------------------------------------
 
@@ -71,11 +71,11 @@ table along with other collection data.
 :ref:`type-conflict-resolution`
 -------------------------------
 
-Relational databases do not allow dynamically typed columns so when
+Relational databases don't allow dynamically typed columns. When
 the |bi-short| samples data from MongoDB to generate a schema, type
-conversion conflicts may occur. See this page for more information
-on how the |bi-short| resolves these conflicts and displays data
-when conflicts are present.
+conversion conflicts may occur. To learn more about how the |bi-short|
+resolves these conflicts and displays data when conflicts are present,
+see the following sections.
 
 
 .. toctree::

source/schema/cached-sampling.txt

@@ -29,7 +29,7 @@ of the schema which it then caches in memory.
 
 .. include:: /includes/fact-sampleRefresh.rst
 
-If the schema which :binary:`~bin.mongosqld` creates does not meet your
+If the schema which :binary:`~bin.mongosqld` creates doesn't meet your
 BI workload needs, you can manually generate a :ref:`schema file
 <schema-with-drdl-file>` file and edit it as necessary.
 

source/schema/load-schema-from-drdl.txt

@@ -21,7 +21,7 @@ requirements.
 You can manually edit the schema definition files to perform the
 following actions:
 
-- Add fields that :binary:`~bin.mongodrdl` did not discover within
+- Add fields that :binary:`~bin.mongodrdl` didn't discover within
   the subset of documents that it sampled
 - Remove fields
 - Remove tables
@@ -32,11 +32,44 @@ following actions:
 
 .. include:: /includes/fact-geospatial-views.rst
 
-When you're done editing your ``.drdl`` file, you can either:
+When you're done editing your ``.drdl`` file, you can follow the steps in
+one of the following options:
 
-- Use :binary:`~bin.mongodrdl` to :commandoption:`upload` the schema
-  to your MongoDB deployment.
+- Option 1. Upload the schema, give it a name, and start :binary:`~bin.mongosqld`,
+  specifying both the schema's name, source, and mode, as in the following steps:
 
-- Run :binary:`~bin.mongosqld` with the
-  :option:`--schema <mongosqld --schema>` option to specify the
-  ``.drdl`` when launching ``mongosqld``.
+  1. Use :binary:`~bin.mongodrdl` to :commandoption:`upload` the schema
+     to your MongoDB deployment, similar to the following example:
+
+     .. code-block:: sh
+   
+      mongodrdl upload --host <hostName> --schemaSource schemas --drdl ./movies.drdl
+
+     The string representation of the :ref:`ObjectId <document-bson-type-object-id>`
+     of the uploaded schema is returned:
+
+     .. code-block:: sh
+        :copyable: false
+   
+        5d793f3f6a26a3ce66c304ea
+
+  2. Name your schema, using the :commandoption:`name-schema <name-schema>`
+     command, similar to the following example:
+
+     .. code-block:: sh
+   
+        mongodrdl name-schema --name movies --schemaSource schemas --schema 5d793f3f6a26a3ce66c304ea
+
+  3. Start :binary:`~bin.mongosqld` with a named schema, using
+     :option:`--schemaSource <mongosqld --schema>`,
+     :option:`--schemaMode <mongosqld --schema>`,
+     and :option:`--schemaName <mongosqld --schemaName>` options,
+     similar to the following example:
+
+     .. code-block::
+
+        mongosqld --schemaMode custom --schemaSource schemas --schemaName movies
+
+- Option 2. Start :binary:`~bin.mongosqld` with the
+  :option:`--schema <mongosqld --schema>` option to specify the path to the
+  ``.drdl`` schema file.