diff --git a/config/redirects.yaml b/config/redirects.yaml index 680933913d6..4ac3e8af678 100644 --- a/config/redirects.yaml +++ b/config/redirects.yaml @@ -867,6 +867,46 @@ code: 303 outputs: - 'before-v3.0' --- +from: '/reference/program/mongodrdl' +to: '/reference/program' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' + - 'manual' +--- +from: '/reference/program/mongobiuser' +to: '/reference/program' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' + - 'manual' +--- +from: '/reference/program/mongobischema' +to: '/reference/program' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' + - 'manual' +--- +from: '/reference/business-intelligence-programs' +to: '/reference' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' + - 'manual' +--- +from: '/additional-products/bi-connector' +to: '/' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' + - 'manual' +--- from: '/tutorial/deploy-config-servers' to: '/tutorial/deploy-shard-cluster' type: 'redirect' diff --git a/source/images/bi-connector.svg b/source/images/bi-connector.svg new file mode 100644 index 00000000000..c5d4b3a101c --- /dev/null +++ b/source/images/bi-connector.svg @@ -0,0 +1,508 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BusinessIntelligenceConnector + + + + + schema + + + Tableau + + + + + queries + + + + responses + + + + queries + + + + responses + + + MongoDB + + + + diff --git a/source/images/metadata.yaml b/source/images/metadata.yaml index b1c790674d9..0b9cfa594b9 100644 --- a/source/images/metadata.yaml +++ b/source/images/metadata.yaml @@ -812,6 +812,17 @@ output: dpi: 72 width: 500 --- +name: bi-connector +alt: "Diagram of the MongoDB Business Intelligence Connector." +output: + - type: print + tag: 'print' + dpi: 300 + width: 2100 + - type: web + dpi: 72 + width: 700 +--- name: redact-security-architecture alt: "Diagram of security architecture with middleware and redaction." output: diff --git a/source/includes/fact-bi-enterprise.rst b/source/includes/fact-bi-enterprise.rst new file mode 100644 index 00000000000..4a44aa39f5f --- /dev/null +++ b/source/includes/fact-bi-enterprise.rst @@ -0,0 +1,3 @@ +.. note:: + The MongoDB Business Intelligence Connector and associated utilities are only + available with MongoDB Enterprise. diff --git a/source/includes/fact-mongodrdl-example.rst b/source/includes/fact-mongodrdl-example.rst new file mode 100644 index 00000000000..f7b0f2b7429 --- /dev/null +++ b/source/includes/fact-mongodrdl-example.rst @@ -0,0 +1,41 @@ +Given documents of the following shape in the collection ``abc`` in the +database ``test``: + +.. code-block:: javascript + + { + "_id": ObjectId("....") + "close": 7.45, + "detail": { "a": 2, "b":3} + } + +You can use :program:`mongodrdl` to generate a schema based on this collection +by running the following command: + +.. code-block:: sh + + mongodrdl -d test -c abc -o schema.drdl + +The generated schema file ``schema.drdl`` will look similar to the following: + +.. code-block:: yaml + + schema: + - db: test + tables: + - table: abc + collection: abc + pipeline: [] + columns: + - name: _id + mongotype: float64 + sqltype: numeric + - name: close + mongotype: float64 + sqltype: numeric + - name: detail.a + mongotype: float64 + sqltype: numeric + - name: detail.b + mongotype: float64 + sqltype: numeric diff --git a/source/includes/options-mongobischema.yaml b/source/includes/options-mongobischema.yaml new file mode 100644 index 00000000000..d60192b5900 --- /dev/null +++ b/source/includes/options-mongobischema.yaml @@ -0,0 +1,48 @@ +# This file borrows content from other files, including +# /includes/options-shared.yaml, +# which uses {{program}} to refer to the tool. +# +program: mongobischema +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongobischema +name: host +aliases: -h +args: +default: | + localhost +directive: option +description: | + Specifies the resolvable hostname or socket path on which the Business + Intelligence Connector is listening. +optional: false +--- +program: mongobischema +name: port +inherit: + name: port + program: mongobiuser + file: options-mongobiuser.yaml +--- +program: mongobischema +name: password +aliases: -W +args: +directive: option +description: | + Specifies a password with which to authenticate with the Business + Intelligence Connector. If this option is not specified, {{program}} will + prompt for a password. +optional: true +--- +program: mongobischema +name: drop-all +directive: option +description: | + Drops all tables associated with the given user. +optional: true +... diff --git a/source/includes/options-mongobiuser.yaml b/source/includes/options-mongobiuser.yaml new file mode 100644 index 00000000000..9f8d2fddcac --- /dev/null +++ b/source/includes/options-mongobiuser.yaml @@ -0,0 +1,34 @@ +# This file borrows content from other files, including +# /includes/options-shared.yaml, +# which uses {{program}} to refer to the tool. +# +program: mongobiuser +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongobiuser +name: port +aliases: -p +args: +default: | + 27032 +directive: option +description: | + Specifies the TCP port on which the Business Intelligence Connector is + listening. +optional: false +--- +program: mongobiuser +name: password +aliases: -W +args: +directive: option +description: | + Specifies the password that the user being created must use to authenticate + with the Business Intelligence Connector. If this option is not specified, + {{program}} will prompt for a password. +optional: true +... diff --git a/source/includes/options-mongodrdl.yaml b/source/includes/options-mongodrdl.yaml new file mode 100644 index 00000000000..fec86e78f2b --- /dev/null +++ b/source/includes/options-mongodrdl.yaml @@ -0,0 +1,246 @@ +# This file borrows content from other files, including +# /includes/options-shared.yaml, +# which uses {{program}} to refer to the tool. +# +program: mongodrdl +name: username +inherit: + name: username + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: password +inherit: + name: password + program: _shared + file: options-shared.yaml +description: | + Specifies a password with which to authenticate to a MongoDB database + that uses authentication. Use in conjunction with the ``--username`` and + ``--authenticationDatabase`` options. +--- +program: mongodrdl +name: help +inherit: + name: help + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: version +inherit: + name: version + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: host +inherit: + name: host + program: _shared + file: options-shared.yaml +description: | + Specifies a resolvable hostname for the :program:`mongod` to which to + connect. By default, the {{program}} attempts to connect to a MongoDB + instance running on the localhost on port number ``27017``. + + To connect to a replica set, specify the + :setting:`~replication.replSetName` and a seed list of set members, as in + the following: + + .. code-block:: none + + /<:port>,<:port>,<...> + + You can always connect directly to a single MongoDB instance by + specifying the host and port number directly. +--- +program: mongodrdl +name: port +inherit: + name: port + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: authenticationDatabase +inherit: + name: authenticationDatabase + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: authenticationMechanism +inherit: + name: _authenticationMechanism + program: _shared + file: options-shared.yaml +--- +program: mongodrdl +name: db +aliases: -d +directive: option +args: +description: | + Specifies a database from which to generate a ``.drdl`` schema file. +optional: true +--- +program: mongodrdl +name: collection +aliases: -c +directive: option +args: +description: | + Specifies a collection from which to generate a ``.drdl`` schema file. + If you do not specify a collection, this option will use all collections in + the specified database or instance. +optional: true +--- +program: mongodrdl +name: customFilterField +aliases: -f +directive: option +args: +description: | + Specifies the field name to add for a custom MongoDB filter. See + :ref:`mongodrdl-custom-filters` for more details. +optional: true +--- +program: mongodrdl +name: out +aliases: -o +directive: option +args: +default: | + Standard out. +description: | + Specifies the path where :program:`mongodrdl` will write the schema file. To + send the schema to standard output, specify "``-``" instead of + a path. +optional: true +--- +# These SSL options cannot be inherited from the normal _shared because those +# include undesired information, unfortunately. +program: mongodrdl +name: ssl +args: null +directive: option +description: | + Enables connection to a :program:`mongod` or :program:`mongos` that has + TLS/SSL support enabled. +optional: true +--- +program: mongodrdl +name: sslCAFile +args: +directive: option +description: | + Specifies the :file:`.pem` file that contains the root certificate chain + from the Certificate Authority. Specify the file name of the + :file:`.pem` file using relative or absolute paths. + + .. warning:: + + For SSL connections (``--ssl``) to :program:`mongod` and + :program:`mongos`, if the {{program}} runs without the + {{role}}, {{program}} will not attempt + to validate the server certificates. This creates a vulnerability + to expired :program:`mongod` and :program:`mongos` certificates as + well as to foreign processes posing as valid :program:`mongod` or + :program:`mongos` instances. Ensure that you *always* specify the + CA file to validate the server certificates in cases where + intrusion is a possibility. + +optional: true +--- +program: mongodrdl +name: sslPEMKeyFile +args: +directive: option +description: | + Specifies the :file:`.pem` file that contains both the TLS/SSL certificate + and key. Specify the file name of the :file:`.pem` file using relative + or absolute paths. + + This option is required when using the :option:`--ssl` option to connect + to a :program:`mongod` or :program:`mongos` that has + :setting:`~net.ssl.CAFile` enabled *without* + :setting:`~net.ssl.allowConnectionsWithoutCertificates`. +optional: true +--- +program: mongodrdl +name: sslPEMKeyPassword +args: +directive: option +description: | + Specifies the password to de-crypt the certificate-key file (i.e. + :option:`--sslPEMKeyFile`). Use the {{role}} option only if the + certificate-key file is encrypted. In all cases, the {{program}} will + redact the password from all logging and reporting output. + + If the private key in the PEM file is encrypted and you do not specify + the {{role}} option, the {{program}} will prompt for a passphrase. See + :ref:`ssl-certificate-password`. +optional: true +--- +program: mongodrdl +name: sslCRLFile +args: +directive: option +description: | + Specifies the :file:`.pem` file that contains the Certificate Revocation + List. Specify the file name of the :file:`.pem` file using relative or + absolute paths. +optional: true +--- +program: mongodrdl +name: sslAllowInvalidCertificates +args: null +directive: option +description: | + Bypasses the validation checks for server certificates and allows + the use of invalid certificates. When using the + :setting:`~net.ssl.allowInvalidCertificates` setting, MongoDB logs as a + warning the use of the invalid certificate. +optional: true +--- +program: mongodrdl +name: sslAllowInvalidHostnames +args: null +directive: option +description: | + Disables the validation of the hostnames in TLS/SSL certificates. Allows + {{program}} to connect to MongoDB instances if the hostname their + certificates do not match the specified hostname. +optional: true +--- +program: mongodrdl +name: sslFIPSMode +args: null +directive: option +description: | + Directs the {{program}} to use the FIPS mode of the installed OpenSSL + library. Your system must have a FIPS compliant OpenSSL library to use + the {{role}} option. +optional: true +--- +program: mongodrdl +name: verbose +aliases: -v +args: +directive: option +description: | + Specifies that {{program}} should provide more detailed log output. Include + multiple times for more verbosity (e.g. ``-vvvvv``), or specify a numeric + value (e.g. ``--verbose=5``). +optional: true +--- +program: mongodrdl +name: quiet +args: null +directive: option +description: | + Hides all log output. +optional: true +... diff --git a/source/includes/options-shared.yaml b/source/includes/options-shared.yaml index 80e9448960f..3c7ab6fd487 100644 --- a/source/includes/options-shared.yaml +++ b/source/includes/options-shared.yaml @@ -282,14 +282,14 @@ description: | If you do not specify an argument for {{role}}, {{program}} returns an error. - + .. versionchanged:: 3.0.2 If you wish {{program}} to prompt the user for the password, pass the :option:`--username` option without {{role}} or specify an empty string as the {{role}} value, as in ``--password ""`` . - + optional: true --- program: _shared @@ -297,30 +297,18 @@ name: authenticationDatabase args: directive: option description: | - .. versionadded:: 2.4 - Specifies the database in which the user is created. See :ref:`user-authentication-database`. optional: true --- program: _shared -name: authenticationMechanism +name: _authenticationMechanism # This describes the authenticationMechanism option that is used by the # various client tools. args: default: SCRAM-SHA-1 directive: option description: | - .. versionadded:: 2.4 - - .. versionchanged:: 2.6 - Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication - mechanisms. - - .. versionchanged:: 3.0 - Added support for the ``SCRAM-SHA-1`` authentication mechanism. Changed - default mechanism to ``SCRAM-SHA-1``. - Specifies the authentication mechanism the {{program}} instance uses to authenticate to the :program:`mongod` or :program:`mongos`. @@ -369,6 +357,21 @@ description: | optional: true --- program: _shared +name: authenticationMechanism +inherit: + name: _authenticationMechanism + program: _shared + file: options-shared.yaml +pre: | + .. versionchanged:: 2.6 + Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication + mechanisms. + + .. versionchanged:: 3.0 + Added support for the ``SCRAM-SHA-1`` authentication mechanism. Changed + default mechanism to ``SCRAM-SHA-1``. +--- +program: _shared name: dbpath args: directive: option diff --git a/source/includes/steps-install-bi-connector.yaml b/source/includes/steps-install-bi-connector.yaml new file mode 100644 index 00000000000..bfd4312fb50 --- /dev/null +++ b/source/includes/steps-install-bi-connector.yaml @@ -0,0 +1,114 @@ +title: Install the Business Intelligence Connector. +stepnum: 1 +ref: install-bi-server +level: 4 +pre: | + Download the Business Intelligence Connector for your version of Red Hat + Enterprise Linux or CentOS from the + `MongoDB Download Center `_. + + You can check your operating system version with the following command: + + .. code-block:: sh + + cat /etc/redhat-release + + Extract the tarball you downloaded, and install the containing RPM packages: +action: + language: sh + code: | + sudo yum install *.rpm +--- +title: Create at least one Business Intelligence Connector user. +stepnum: 2 +ref: create-users +level: 4 +pre: | + Replace ``biuser`` in the following command with your desired Business + Intelligence username, and fill in the :ref:`connection string ` + that points to your MongoDB instance. +action: + language: sh + code: | + mongobiuser create biuser mongodb://your.mongodbhost.com:27017/db1 +post: | + :program:`mongobiuser` will prompt you to set a password for ``biuser`` by + default. +--- +title: Generate your schema definition file. +stepnum: 3 +ref: generate-schema +level: 4 +pre: | + Provide a MongoDB server hostname, replace ``dbname`` with the name of your + database, and optionally replace ``collname`` with the name of a collection. + If you do not specify a collection, :program:`mongodrdl` will generate a + schema from all collections in ``dbname``. +action: + language: sh + code: | + mongodrdl --host your.mongohost.com -d dbname [-c collname] -o schema.drdl +post: | + You can examine the generated ``schema.drdl`` file, and remove any fields or + tables that are not part of your intended schema. +--- +title: Load the generated schema into the Business Intelligence Connector. +stepnum: 4 +ref: load-schema +level: 4 +action: + language: sh + code: | + mongobischema import biuser schema.drdl +post: | + When prompted, you must provide the password you set with + ``mongobiuser create``. You can also provide the ``--password`` flag to + :program:`mongobischema` on the command line. +--- +title: Install business intelligence PostgreSQL drivers. +stepnum: 5 +level: 4 +ref: install-tableau-postgresql +content: | + On the Windows or OSX machine where you will be running your business + intelligence tool, install the appropriate PostgreSQL driver for that tool. + + If you are using Tableau for example, you can install the PostgreSQL driver + from their `drivers download page `_, + and follow the instructions there. +--- +title: Connect to the Business Intelligence Connector +stepnum: 6 +level: 4 +ref: connect-to-bi-server +content: | + Launch your business intelligence tool, and connect to the Business + Intelligence Connector using the following settings: + + .. list-table:: + :widths: 20 80 + + * - Host + + - The hostname of the server on which you installed the Business + Intelligence Connector in step 1. + + * - Port + + - ``27032`` by default. + + * - Username + + - The value you specified when creating your Business Intelligence + Connector user with :program:`mongobiuser` in step 2. + + * - Password + + - The value you specified when creating your Business Intelligence + Connector user with :program:`mongobiuser` in step 2. + + * - Database + + - The value you specified when creating your Business Intelligence + Connector user with :program:`mongobiuser` in step 2. +... diff --git a/source/includes/toc-reference-landing.yaml b/source/includes/toc-reference-landing.yaml index 5637a01bff9..7e75eca9564 100644 --- a/source/includes/toc-reference-landing.yaml +++ b/source/includes/toc-reference-landing.yaml @@ -14,6 +14,10 @@ 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.txt b/source/products.txt index b61bcd6ea60..f80a70de60e 100644 --- a/source/products.txt +++ b/source/products.txt @@ -22,6 +22,10 @@ analyze data in a MongoDB deployment. A sophisticated GUI that simplifies collection analysis with data visualization and an easy-to-use query builder. + :doc:`/products/bi-connector` + A specialized server that connects MongoDB to Business + Intelligence Tools like `Tableau `_. + .. class:: hidden .. toctree:: @@ -30,5 +34,6 @@ analyze data in a MongoDB deployment. /products/ops-manager /products/cloud-manager /products/compass + /products/bi-connector .. include:: /includes/replacement-mms.rst diff --git a/source/products/bi-connector.txt b/source/products/bi-connector.txt new file mode 100644 index 00000000000..28b80b83077 --- /dev/null +++ b/source/products/bi-connector.txt @@ -0,0 +1,356 @@ +.. _bi-connector: + +=============================== +Business Intelligence Connector +=============================== + +.. default-domain:: mongodb + +.. note:: + + The MongoDB Business Intelligence Connector is currently in beta and is + available for limited testing. Functionality and availability may change + before its official release. + +The MongoDB Business Intelligence Connector allows users to +visualize their MongoDB Enterprise data using existing relational business +intelligence tools such as `Tableau `_. + +These tools expect to connect to a data source and find data in tabular form +following a fixed schema. This presents a challenge when working with MongoDB's +:doc:`flexible schema ` and rich, multi-dimensional, documents. + +The Business Intelligence Connector acts as a layer in between a +:program:`mongod` instance and your reporting tool. Currently, it uses a +foreign data wrapper with `PostgreSQL `_ to provide a +relational :term:`SQL` view into your MongoDB data. + +.. include:: /images/bi-connector.rst + +Installation +------------ + +.. note:: + + The Business Intelligence Connector works only with MongoDB versions 3.2 and + greater. + +To set up the Business Intelligence Connector with a business intelligence tool +such as Tableau, follow the steps in this section. + +.. include:: /includes/steps/install-bi-connector.rst + +Schema Configuration +-------------------- + +Business Intelligence tools connect to a data source and, given a fixed +tabular schema, allow the user to visually explore their data. However, +because MongoDB uses a :doc:`flexible schema `, these tools +currently cannot use MongoDB as a native data source. + +To use MongoDB with a relational business intelligence tool such as Tableau, +you must define a relational mapping for your MongoDB data. + +The schema generation tool :program:`mongodrdl` will output such a schema in the +:ref:`Document Relational Definition Language ` (DRDL) format, but you +should verify that the schema it proposes matches your data requirements. +Examine both the table structure and field types to ensure that you will be +able to generate your desired reports. + +You may have to edit the schema definition files by hand to remove unneeded +fields; add fields that :program:`mongodrdl` did not discover within the subset +of documents that it sampled; and modify erroneous field types. + +You may edit DRDL files in the following ways: + +- Add :ref:`aggregation pipeline ` stages, +- Add fields, +- Remove fields, +- Remove tables, +- Rename tables, so long as the ``collection`` field remains the same. + +Note that you can *not* currently rename fields. + +.. _drdl: + +Document Relational Definition Language +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Document Relational Definition Language (``DRDL``) defines a relational +view of a MongoDB schema. + +:program:`mongodrdl` produces these files using one or more MongoDB collections +as a guideline, and :program:`mongobischema` imports them into the Business +Intelligence Connector. + +Using the `YAML `_ format, the file lists the databases, +tables, and columns to be "exported" for use in the Business Intelligence tools. + +File Format +``````````` +.. code-block:: yaml + + schema: + - db: + tables: + - table: + collection: + pipeline: + - + columns: + - name: + mongotype: + sqltype: + +Example +``````` + +.. include:: /includes/fact-mongodrdl-example.rst + +Field Types +~~~~~~~~~~~ + +The MongoDB Business Intelligence Connector will correctly map fields that +always contain the same data type into the relational model. Schema generation +will deal specially with the following cases: + +Dates + The connector will treat any field of type :bsontype:`data_date` as the + :term:`SQL` ``timestamp`` type. + +Timestamps + The connector will treat any field of type :bsontype:`data_timestamp` as a + ``varchar`` string type. + +Heterogeneous Fields + If a field can contain multiple types, :program:`mongodrdl` will pick the type + that appears most frequently. + + 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. + +Embedded Documents +~~~~~~~~~~~~~~~~~~ + +The Business Intelligence Connector will map embedded documents to simple fields +that have a ``.`` separator character, making them appear similar to the way you +would reference them using :ref:`dot notation ` in a +MongoDB query. + +While Tableau properly quotes identifiers, within "ad-hoc" +SQL expressions you must double-quote every identifier that contains ``.`` +characters or mixed-case characters. + +For example, consider the following document: + +.. code-block:: javascript + + { + "_id": 1, + "familyName": "Partridge", + "hometown" : "Hollywood Hills", + "address" : { "street": "123 Main Street", + "city" : "Hollywood", + "state" : "CA", + "zip" : "90210" }, + "members_since" : ISODate("2002-04-12T00:00:00Z") + } + +This will result in the following fields in the generated schema: + +.. list-table:: + + * - ``_id`` + + - ``numeric`` + + * - ``familyName`` + + - ``varchar`` + + * - ``hometown`` + + - ``varchar`` + + * - ``address.street`` + + - ``varchar`` + + * - ``address.city`` + + - ``varchar`` + + * - ``address.state`` + + - ``varchar`` + + * - ``address.zip`` + + - ``varchar`` + + * - ``members_since`` + + - ``timestamp`` + +Arrays +~~~~~~ + +The MongoDB Business Intelligence Connector exposes arrays to business +intelligence tools using two collections: one without the array, and the other +with the array "pre-joined" to its parent. + +For example, consider the following document in the collection ``families``: + +.. code-block:: javascript + + { + "_id": 1, + "familyName": "Partridge", + "hometown" : "Hollywood Hills", + "familyMembers" : [ + { + "firstname" : "Shirley", + "age" : 42, + "attributes" : [ + { "name" : "instrument", "value" : "singer" }, + { "name" : "role", "value" : "mom" } + ] + }, + { + "firstname" : "Keith", + "age" : 18, + "attributes" : [ + { "name" : "instrument", "value" : "guitar" }, + { "name" : "role", "value" : "son" } + ] + }, + { + "firstname" : "Laurie", + "age" : 16, + "attributes" : [ + { "name" : "instrument", "value" : "keyboard" }, + { "name" : "role", "value" : "sister" } + ] + }] + } + +This will result in the following three tables: + +``families`` + .. list-table:: + + * - ``_id`` + + - ``numeric`` + + * - ``familyName`` + + - ``varchar`` + + * - ``hometown`` + + - ``varchar`` + +``families_familyMembers`` + .. list-table:: + + * - ``_id`` + + - ``numeric`` + + * - ``familyMembers.age`` + + - ``numeric`` + + * - ``familyMembers.firstname`` + + - ``varchar`` + + * - ``familyMembers_idx`` + + - ``numeric`` + + * - ``familyName`` + + - ``varchar`` + + * - ``hometown`` + + - ``varchar`` + +``families_familyMembers_attributes`` + .. list-table:: + + * - ``_id`` + + - ``numeric`` + + * - ``familyMembers.age`` + + - ``numeric`` + + * - ``familyMembers.attributes.name`` + + - ``varchar`` + + * - ``familyMembers.attributes.value`` + + - ``varchar`` + + * - ``familyMembers.attributes_idx`` + + - ``numeric`` + + * - ``familyMembers.firstname`` + + - ``varchar`` + + * - ``familyMembers_idx`` + + - ``numeric`` + + * - ``familyName`` + + - ``varchar`` + + * - ``hometown`` + + - ``varchar`` + +Aggregation Pipelines +~~~~~~~~~~~~~~~~~~~~~ + +The Business Intelligence Connector can use +:ref:`aggregation pipelines ` as part of the schema to +transform documents from the collection into the proper form for the relational +tables. + +For example, consider a simple document in the collection ``simpleFamilies``: + +.. code-block:: javascript + + { + "_id": 1, + "familyName": "Partridge", + "familyMembers" : [ "Shirley", "Keith", "Laurie"] + } + + +:program:`mongodrdl` will generate a schema with the tables ``simpleFamilies`` +and ``simpleFamilies_familyMembers``. + +The table ``simpleFamilies_familyMembers`` enumerates each family members, and +has the following pipeline: + +.. code-block:: yaml + + pipeline: + - $unwind: + includeArrayIndex: familyMembers_idx + path: $familyMembers + +This pipeline uses :pipeline:`$unwind` to create a new record for each member of +``familyMembers``. The schema will track the array index in the field +``familyMembers_idx``. + +.. seealso:: :program:`mongodrdl`, :program:`mongobiuser`, :program:`mongobischema` diff --git a/source/reference/business-intelligence-programs.txt b/source/reference/business-intelligence-programs.txt new file mode 100644 index 00000000000..88a15490643 --- /dev/null +++ b/source/reference/business-intelligence-programs.txt @@ -0,0 +1,22 @@ +======================================== +MongoDB Business Intelligence Components +======================================== + +.. default-domain:: mongodb + +.. 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 diff --git a/source/reference/program/mongobischema.txt b/source/reference/program/mongobischema.txt new file mode 100644 index 00000000000..011d5f503fb --- /dev/null +++ b/source/reference/program/mongobischema.txt @@ -0,0 +1,117 @@ +================= +``mongobischema`` +================= + +.. default-domain:: mongodb + +.. only:: html + + .. meta:: + :description: The mongobischema command man page. + :keywords: mongobischema, mongodb, man page + +Description +----------- + +.. only:: (not man) + + .. binary:: mongobischema + +.. include:: /includes/fact-bi-enterprise.rst + +:program:`mongobischema` loads ``.drdl`` files generated by :program:`mongodrdl` +into the MongoDB Business Intelligence Connector. + +:program:`mongobischema` has several subcommands that perform different actions: + +.. list-table:: + :header-rows: 1 + + * - Command + - Arguments + - Description + + * - ``mongobischema drop`` + + - ``[drop-flags] [username] [tables...]`` + + - Drops a set of tables associated with the given user on the Business + Intelligence Connector. + + * - ``mongobischema import`` + + - ``[import-flags] [username] [files...]`` + + - Import a schema from set of ``.drdl`` files generated by + :program:`mongodrdl`. + + * - ``mongobischema list`` + + - ``[list-flags] [username]`` + + - List the tables associated with a given user on the Business Intelligence + Connector. + +Options +------- + +Core Options +~~~~~~~~~~~~ + +.. program:: mongobischema + +.. include:: /includes/option/option-mongobischema-help.rst + +.. include:: /includes/option/option-mongobischema-host.rst + +.. include:: /includes/option/option-mongobischema-port.rst + +.. include:: /includes/option/option-mongobischema-password.rst + +Drop Options +~~~~~~~~~~~~ + +.. include:: /includes/option/option-mongobischema-drop-all.rst + +Use +--- + +Drop +~~~~ + +To drop the tables ``familes`` and ``families_familymembers`` associated with +the user ``bradbi`` on the Business Intelligence Connector, you can run the following +command: + +.. code-block:: sh + + mongobischema drop bradbi families families_familymembers + +To drop **all** tables associated with the user ``bradbi``, you can run the +following: + +.. code-block:: sh + + mongobischema drop --all bradbi + +Import +~~~~~~ + +To associate a schema generated by :program:`mongodrdl` with the user ``bradbi`` +on the Business Intelligence Connector, you can run the following command: + +.. code-block:: sh + + mongobischema import bradbi ./schema.drdl + +List +~~~~ + +To list all tables associated with the user ``bradbi`` on the Business +Intelligence Connector, you can run the following command: + +.. code-block:: sh + + mongobischema list bradbi + +.. seealso:: :ref:`bi-connector` diff --git a/source/reference/program/mongobiuser.txt b/source/reference/program/mongobiuser.txt new file mode 100644 index 00000000000..a8a93958e93 --- /dev/null +++ b/source/reference/program/mongobiuser.txt @@ -0,0 +1,116 @@ +=============== +``mongobiuser`` +=============== + +.. default-domain:: mongodb + +.. only:: html + + .. meta:: + :description: The mongobiuser command man page. + :keywords: mongobiuser, mongodb, man page + +Description +----------- + +.. only:: (not man) + + .. binary:: mongobiuser + +.. include:: /includes/fact-bi-enterprise.rst + +:program:`mongobiuser` allows you to create, drop, and list users within a +MongoDB Business Intelligence Connector running on the same host. + +There must be at least one user created in order for Business Intelligence +Connector to function. + +:program:`mongobiuser` has several subcommands that perform different actions: + +.. list-table:: + :header-rows: 1 + + * - Command + - Arguments + - Description + + * - ``mongobiuser create`` + + - ``[create-flags] [username] [url]`` + + - Creates a new user in the Business Intelligence Connector and associate + them with the corresponding MongoDB :ref:`connection string `. + + If the MongoDB instance uses + :doc:`Transport Encryption `, you + must use the ``ssl=true`` option allowed in + `PyMongo connection strings `_. + + * - ``mongobiuser drop`` + + - ``[username]`` + + - Delete the given ``[username]`` and all data associated with them from + the Business Intelligence Connector. + + * - ``mongobiuser list`` + + - + + - List all users in the Business Intelligence Connector. + +Options +------- + +Core Options +~~~~~~~~~~~~ + +.. program:: mongobiuser + +.. include:: /includes/option/option-mongobiuser-help.rst + +.. include:: /includes/option/option-mongobiuser-port.rst + +Create Options +~~~~~~~~~~~~~~ + +.. include:: /includes/option/option-mongobiuser-password.rst + +Use +--- + +Create +~~~~~~ + +Suppose you have a three-member MongoDB :term:`replica set` requiring +:doc:`Transport Encryption ` and +:ref:`authentication ` with a user ``brad`` who has a +given ``password``. To associate a Business Intelligence Connector user +``bradbi`` with this replica set, you can run the following command: + +.. code-block:: sh + + mongobiuser create bradbi \ + 'mongodb://brad:password@localhost:27017,localhost:27018,localhost:27019/?readPreference=secondary&ssl=true' + +Drop +~~~~ + +To delete the user ``bradbi`` and all of their tables from the Business +Intelligence Connector, you can run the following command: + +.. code-block:: sh + + mongobiuser drop bradbi + +List +~~~~ + +To list all users associated with the Business Intelligence Connector, you can +run the following command: + +.. code-block:: sh + + mongobiuser list + +.. seealso:: :ref:`bi-connector` diff --git a/source/reference/program/mongodrdl.txt b/source/reference/program/mongodrdl.txt new file mode 100644 index 00000000000..c0589954040 --- /dev/null +++ b/source/reference/program/mongodrdl.txt @@ -0,0 +1,145 @@ +============= +``mongodrdl`` +============= + +.. default-domain:: mongodb + +.. only:: html + + .. meta:: + :description: The mongodrdl command man page. + :keywords: mongodrdl, mongodb, man page + +Description +----------- + +.. only:: (not man) + + .. binary:: mongodrdl + +.. include:: /includes/fact-bi-enterprise.rst + +:program:`mongodrdl` produces a schema based on contents of one or more +:program:`mongod` :term:`collections ` and writes them out into +``.drdl`` files understood by :program:`mongobischema`. + +Options +------- + +Core Options +~~~~~~~~~~~~ + +.. program:: mongodrdl + +.. include:: /includes/option/option-mongodrdl-help.rst + +.. include:: /includes/option/option-mongodrdl-version.rst + +.. include:: /includes/option/option-mongodrdl-host.rst + +.. include:: /includes/option/option-mongodrdl-port.rst + +.. include:: /includes/option/option-mongodrdl-username.rst + +.. include:: /includes/option/option-mongodrdl-password.rst + +.. include:: /includes/option/option-mongodrdl-db.rst + +.. include:: /includes/option/option-mongodrdl-collection.rst + +.. include:: /includes/option/option-mongodrdl-customFilterField.rst + +.. include:: /includes/option/option-mongodrdl-out.rst + +.. include:: /includes/option/option-mongodrdl-verbose.rst + +.. include:: /includes/option/option-mongodrdl-quiet.rst + +Authentication Options +~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/option/option-mongodrdl-authenticationDatabase.rst + +.. include:: /includes/option/option-mongodrdl-authenticationMechanism.rst + +.. _mongodrdl-custom-filters: + +Custom Filters +~~~~~~~~~~~~~~ + +You can add a special field to your schema that allows you to pass a custom +MongoDB :pipeline:`$match` query string to your MongoDB instance. + +:program:`mongodrdl` offers the ``--customFilterField`` flag you can use to +name such a custom filter field. Alternatively you can manually editing the DRDL +file before importing it with :program:`mongobischema`. + +This custom filter field allows you to pass a native MongoDB query string down +to MongoDB as the first :pipeline:`$match` stage of the aggregation pipeline, +before any additional filters pushed down from SQL. The MongoDB query must be +legal syntax, and can refer to any field in the collection, even if the fields +were not exposed in the relational schema. + +For an example, see :ref:`mongodrdl-custom-filters-example`. + +Use +--- + +Generate a Schema +~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-mongodrdl-example.rst + +.. _mongodrdl-custom-filters-example: + +Custom Filter +~~~~~~~~~~~~~ + +To use this field, specify the ``--customFilterField`` flag with the name you +want this field to have: + +.. code-block:: sh + + mongodrdl [ other options ] --customFilterField "_MONGOFILTER" -o schema.drdl + +Your DRDL file ``schema.drdl`` will include the following field in every generated table: + +.. code-block:: yaml + + - name: _MONGOFILTER + mongotype: mongo.Filter + sqltype: varchar + +To add the special MongoDB query stage to your standard SQL, use the following +SQL syntax: + +.. code-block:: sql + + SELECT + FROM + WHERE AND + "_MONGOFILTER"='{ }' + + SELECT name,age + FROM users + WHERE active='t' AND + "_MONGOFILTER"='{"addr":{"$elemMatch":{"city":"Springfield","state":"CA"}}}' + +The MongoDB Business Intelligence Connector will translate the above SQL +into the following MongoDB :ref:`aggregation ` +expression: + +.. code-block:: javascript + + db.users.aggregate([ + {$match:{"addr":{"$elemMatch":{"city":"Springfield","state":"CA"}}}, + {$match:{"active":true}}, + {$project:{"name":1, "age":1}} + ]); + +You can use this custom filter in any Business Intelligence tool by filtering +on your special field and providing the value to match as a single quoted string +representing valid :term:`JSON`. All quotes inside the JSON must be double +quotes. + +.. seealso:: :ref:`bi-connector`