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.