From 89f95bbaf5110740a82dcf0db393db599fe2aeb1 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Wed, 20 Jan 2016 20:41:00 -0500 Subject: [PATCH] DOCS-6815: Add BI FAQ, and consolidate BI programs. --- conf.py | 1 + config/redirects.yaml | 21 +++ source/includes/toc-reference-landing.yaml | 4 - source/products/bi-connector.txt | 19 ++- source/products/components-bi-connector.txt | 30 ++++ source/products/faq-bi-connector.txt | 143 ++++++++++++++++++ .../business-intelligence-programs.txt | 28 ---- 7 files changed, 211 insertions(+), 35 deletions(-) create mode 100644 source/products/components-bi-connector.txt create mode 100644 source/products/faq-bi-connector.txt delete mode 100644 source/reference/business-intelligence-programs.txt diff --git a/conf.py b/conf.py index ad2d877c78e..f64c3fae43f 100644 --- a/conf.py +++ b/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' diff --git a/config/redirects.yaml b/config/redirects.yaml index a39bf77e81b..40215ed9b90 100644 --- a/config/redirects.yaml +++ b/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' diff --git a/source/includes/toc-reference-landing.yaml b/source/includes/toc-reference-landing.yaml index 7e75eca9564..5637a01bff9 100644 --- a/source/includes/toc-reference-landing.yaml +++ b/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. diff --git a/source/products/bi-connector.txt b/source/products/bi-connector.txt index aaad8be93bd..5a32e126c91 100644 --- a/source/products/bi-connector.txt +++ b/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 ` 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 + FAQ Release Notes diff --git a/source/products/components-bi-connector.txt b/source/products/components-bi-connector.txt new file mode 100644 index 00000000000..65e1f60f52f --- /dev/null +++ b/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 diff --git a/source/products/faq-bi-connector.txt b/source/products/faq-bi-connector.txt new file mode 100644 index 00000000000..9575aec1a3f --- /dev/null +++ b/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 ` information +imparted by :program:`mongobiuser`, and the schema defined by a +:ref:`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 `, +- The :ref:`aggregation pipeline ` from the + :ref:`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 ` file and +:ref:`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 ` 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 ` + +Is there any syntax validation tool for DRDL? +--------------------------------------------- + +:ref:`DRDL ` files use the `YAML `_ syntax. Any +YAML validator such as ``_ can help you +check your DRDL files. + +How does the |bi| process dates? +-------------------------------- + +The |bi| will correctly process :ref:`BSON 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 `, you must use the +``ssl=true`` option in the +`PyMongo connection string `_. + +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 ` for user authentication, +you must specify the :data:`authMechanism=PLAIN ` and +:data:`authSource=$external ` +:ref:`connection string ` 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. diff --git a/source/reference/business-intelligence-programs.txt b/source/reference/business-intelligence-programs.txt deleted file mode 100644 index 740b835218a..00000000000 --- a/source/reference/business-intelligence-programs.txt +++ /dev/null @@ -1,28 +0,0 @@ -======================================== -MongoDB Business Intelligence Components -======================================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. include:: /includes/fact-bi-enterprise.rst - -MongoDB provides a suite of tools for working with business intelligence -applications. - -:program:`mongobiuser` can modify users in the Business Intelligence Connector. -: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. - -.. toctree:: - :maxdepth: 1 - - /reference/program/mongodrdl - /reference/program/mongobischema - /reference/program/mongobiuser