DOCS-6815: Add BI FAQ, and consolidate BI programs.

conf.py

@@ -61,6 +61,7 @@ def has(self, *args):
     '.. |year| replace:: {0}'.format(datetime.date.today().year),
     '.. |hardlink| replace:: {0}/{1}'.format(conf.project.url, conf.git.branches.current),
     '.. |branch| replace:: ``{0}``'.format(conf.git.branches.current),
+    '.. |bi| replace:: MongoDB Connector for BI',
 ])
 
 pygments_style = 'sphinx'

config/redirects.yaml

@@ -902,6 +902,13 @@ code: 303
 outputs:
  - 'before-v3.0'
 ---
+from: '/reference/business-intelligence-programs'
+to: '/products/bi-connector'
+type: 'redirect'
+code: 303
+outputs:
+ - 'after-v3.0'
+---
 from: '/products/bi-connector'
 to: '/'
 type: 'redirect'
@@ -1042,6 +1049,20 @@ code: 303
 outputs:
   - 'before-v3.0'
 ---
+from : '/products/faq-bi-connector'
+to: '/'
+type: 'redirect'
+code: 303
+outputs:
+  - 'before-v3.0'
+---
+from : '/products/components-bi-connector'
+to: '/'
+type: 'redirect'
+code: 303
+outputs:
+  - 'before-v3.0'
+---
 from : '/reference/command/geoWalk'
 to: '/reference/command/nav-geospatial/'
 type: 'redirect'

source/includes/toc-reference-landing.yaml

@@ -14,10 +14,6 @@ file: /reference/program
 description: |
   Documentation of :program:`mongod` and :program:`mongos` and all other tools distributed with MongoDB.
 ---
-file: /reference/business-intelligence-programs
-description: |
-  Documentation of the utilities that accompany the MongoDB Business Intelligence Connector.
----
 file: /reference/configuration-options
 description: |
   Full documentation of the configuration file and available run-time operations.

source/products/bi-connector.txt

@@ -12,6 +12,8 @@ MongoDB Connector for BI
    :depth: 1
    :class: singlecol
 
+.. include:: /includes/fact-bi-enterprise.rst
+
 The MongoDB Connector for BI (Business Intelligence)
 allows users to visualize their MongoDB Enterprise data using existing
 relational business intelligence tools such as Tableau.
@@ -141,13 +143,22 @@ Geospatial
 
   See :ref:`bi-geospatial` for an example.
 
+.. _drdl-heterogeneous:
+
 Heterogeneous Fields
   If a field can contain multiple types, :program:`mongodrdl` will pick the type
-  that appears most frequently.
+  that appears most frequently. If a value does not match the type specified in
+  the :ref:`DRDL <drdl>` schema, the |bi| will report an error. However, in the
+  case where schema specifies a string, the |bi| can convert the value into a
+  string.
 
   If a field can contain either a string or an array of strings, the generated
   schema will always specify that the field contains an array of strings.
 
+  .. seealso::
+
+     :ref:`bi-skip-incompatible-types`
+
 Embedded Documents
 ~~~~~~~~~~~~~~~~~~
 
@@ -336,6 +347,8 @@ This will result in the following three tables:
 
        - ``varchar``
 
+.. _bi-pipeline:
+
 Aggregation Pipelines
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -422,11 +435,11 @@ For example, given the following collection:
          sqlname: pos.coordinates
          sqltype: numeric[]
 
-.. seealso:: :program:`mongodrdl`, :program:`mongobiuser`, :program:`mongobischema`
-
 .. class:: hidden
 
    .. toctree::
       :titlesonly:
 
+      Components </products/components-bi-connector>
+      FAQ </products/faq-bi-connector>
       Release Notes </products/release-notes/bi-connector>

source/products/components-bi-connector.txt

@@ -0,0 +1,30 @@
+===================================
+MongoDB Connector for BI Components
+===================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/fact-bi-enterprise.rst
+
+The |bi| provides a suite of configuration tools.
+
+- :program:`mongobiuser` can modify users in |bi|.
+- :program:`mongodrdl` generates database schema information for use with the
+  :ref:`bi-connector`.
+- :program:`mongobischema` will load the resulting files
+  into the Business Intelligence Connector.
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /reference/program/mongobiuser
+      /reference/program/mongodrdl
+      /reference/program/mongobischema

source/products/faq-bi-connector.txt

@@ -0,0 +1,143 @@
+=================================
+FAQ: The MongoDB Connector for BI
+=================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Does the |bi| store any data?
+-----------------------------
+
+No. The |bi| is an interface into your MongoDB database. It stores only user
+information and :ref:`MongoDB connection string <mongodb-uri>` information
+imparted by :program:`mongobiuser`, and the schema defined by a
+:ref:`DRDL <drdl>` file.
+
+In what order does query processing happen?
+-------------------------------------------
+
+.. versionchanged:: 1.1.1
+
+   The |bi| now processes ``ORDER BY`` clauses.
+
+The |bi| will process a query in the following order:
+
+- The :pipeline:`$match` stage from a
+  :ref:`custom filter <mongodrdl-custom-filters>`,
+- The :ref:`aggregation pipeline <bi-pipeline>` from the
+  :ref:`DRDL <drdl>` file,
+- Any :pipeline:`$match` stages from the ``WHERE`` clause,
+- Any :pipeline:`$sort` stages from the ``ORDER BY`` clause,
+- The :pipeline:`$project` stage from the ``SELECT`` clause.
+
+What SQL statements get pushed down to MongoDB?
+-----------------------------------------------
+
+.. versionchanged:: 1.1.1
+
+   The |bi| now pushes ``ORDER BY`` clauses down to MongoDB.
+
+The |bi| will push ``SELECT`` projection terms, ``WHERE`` conditions including
+the ``IN`` operator, and the ``ORDER BY`` clause down to MongoDB.
+
+You can push ``JOIN``, ``GROUP BY``, and other clauses down to MongoDB
+using the ``pipeline`` field of your :ref:`DRDL <drdl>` file and
+:ref:`custom filters <mongodrdl-custom-filters>`.
+
+.. _bi-skip-incompatible-types:
+
+How do I skip data incompatible with my DRDL type definition?
+-------------------------------------------------------------
+
+If documents in a collection contain different data types for a field, you may
+wish to filter for a specific data type. To accomplish this, you can include a
+:pipeline:`$match` stage at the beginning of the pipeline in your
+:ref:`DRDL <drdl>` table definition.
+
+For example, to match only documents containing a number in the ``grade`` field,
+use the following pipeline stage:
+
+.. code-block:: javascript
+
+   "$match": { "grade": { "$type": "number" } }
+
+If you are :pipeline:`unwinding <$unwind>` an array field that contains
+different data types, then to filter the array for a specific data type, put
+the :pipeline:`$match` stage after the :pipeline:`$unwind`.
+
+.. seealso::
+
+   :ref:`Heterogeneous data types <drdl-heterogeneous>`
+
+Is there any syntax validation tool for DRDL?
+---------------------------------------------
+
+:ref:`DRDL <drdl>` files use the `YAML <http://yaml.org/>`_ syntax. Any
+YAML validator such as `<https://yaml-online-parser.appspot.com/>`_ can help you
+check your DRDL files.
+
+How does the |bi| process dates?
+--------------------------------
+
+The |bi| will correctly process :ref:`BSON date <document-bson-type-date>` data
+by mapping it to the :term:`SQL` ``datetime`` type. For example:
+
+.. code-block:: javascript
+
+   db.data.save({ date: new Date() })
+
+However, if you store date data as a string, |bi| will treat it as a string
+rather than as a date. For example, |bi| will treat the following as a string:
+
+.. code-block:: javascript
+
+   db.data.save({ date: '32-FEB-2015' })
+
+How do I use TLS with the |bi|?
+-------------------------------
+
+If the MongoDB instance you are connecting to uses
+:doc:`SSL/TLS </core/security-transport-encryption>`, you must use the
+``ssl=true`` option in the
+`PyMongo connection string <https://api.mongodb.org/python/current/examples/tls.html>`_.
+
+For example, when using :program:`mongobiuser`:
+
+.. code-block:: sh
+
+   mongobiuser create bradbi \
+               'mongodb://brad:password@localhost:27017/?ssl=true'
+
+To specify a TLS CA root certificate, use the ``ssl_ca_certs`` option. To
+specify a client certificate, use the ``ssl_certfile`` option. For example:
+
+.. code-block:: sh
+
+   mongobiuser create bradbi \
+               'mongodb://localhost:17017/?ssl=true&ssl_ca_certs=/certs/ca.pem&ssl_certfile=/certs/mongodb_client.pem'
+
+How do I use LDAP authentication with the |bi|?
+-----------------------------------------------
+
+If you are connecting to a MongoDB instance that uses
+:doc:`LDAP </tutorial/configure-ldap-sasl-openldap>` for user authentication,
+you must specify the :data:`authMechanism=PLAIN <uri.authMechanism>` and
+:data:`authSource=$external <uri.authSource>`
+:ref:`connection string <mongodb-uri>` options. For example:
+
+
+.. code-block:: sh
+
+   mongobiuser create bradbi \
+               'mongodb://USERNAME:PASSWORD@localhost:27017/?authMechanism=PLAIN&authSource=$external'
+
+.. important::
+
+   You must surround your connection string in single quotes, as in the example.
+   This prevents your shell from trying to expand ``$external`` with an empty
+   string.