Navigation
This version of the documentation is archived and no longer supported.

mongodrdl

On this page

Description

mongodrdl

Note

The MongoDB Connector for BI and associated utilities are only available with MongoDB Enterprise 3.2 and greater.

mongodrdl produces a schema based on contents of one or more mongod collections and writes them out into .drdl files understood by mongobischema.

Options

Core Options

--help

Returns information on the options and use of mongodrdl.

--version

Returns the mongodrdl release number.

--host <hostname><:port>, -h <hostname><:port>

Default: localhost:27017

Specifies a resolvable hostname for the mongod to which to connect. By default, the mongodrdl attempts to connect to a MongoDB instance running on the localhost on port number 27017.

To connect to a replica set, specify the replication.replSetName and a seed list of set members, as in the following:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>

You can always connect directly to a single MongoDB instance by specifying the host and port number directly.

--port <port>

Default: 27017

Specifies the TCP port on which the MongoDB instance listens for client connections.

--ssl

Enables connection to a mongod or mongos that has TLS/SSL support enabled.

--sslCAFile <filename>

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. Specify the file name of the .pem file using relative or absolute paths.

Warning

For SSL connections (--ssl) to mongod and mongos, if the mongodrdl runs without the --sslCAFile, mongodrdl will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.

--sslPEMKeyFile <filename>

Specifies the .pem file that contains both the TLS/SSL certificate and key. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --ssl option to connect to a mongod or mongos that has net.ssl.CAFile enabled without net.ssl.allowConnectionsWithoutCertificates.

--sslPEMKeyPassword <value>

Specifies the password to de-crypt the certificate-key file (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only if the certificate-key file is encrypted. In all cases, the mongodrdl 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 --sslPEMKeyPassword option, the mongodrdl will prompt for a passphrase. See TLS/SSL Certificate Passphrase.

--sslCRLFile <filename>

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

--sslAllowInvalidCertificates

Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the net.ssl.allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.

--sslAllowInvalidHostnames

Disables the validation of the hostnames in TLS/SSL certificates. Allows mongodrdl to connect to MongoDB instances if the hostname their certificates do not match the specified hostname.

--sslFIPSMode

Directs the mongodrdl to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

--db <database>, -d <database>

Specifies a database from which to generate a .drdl schema file.

--collection <collection>, -c <collection>

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.

--customFilterField <name>, -f <name>

Specifies the field name to add for a custom MongoDB filter. See Custom Filters for more details.

--out <path>, -o <path>

Default: Standard out.

Specifies the path where mongodrdl will write the schema file. To send the schema to standard output, specify “-” instead of a path.

--verbose <level>, -v <level>

Specifies that mongodrdl should provide more detailed log output. Include multiple times for more verbosity (e.g. -vvvvv), or specify a numeric value (e.g. --verbose=5).

--quiet

Hides all log output.

Authentication Options

--authenticationDatabase <dbname>

Specifies the database in which the user is created. See Authentication Database.

--authenticationMechanism <name>

Default: SCRAM-SHA-1

Specifies the authentication mechanism the mongodrdl instance uses to authenticate to the mongod or mongos.

Value Description
SCRAM-SHA-1 RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA1 hash function.
MONGODB-CR MongoDB challenge/response authentication.
MONGODB-X509 MongoDB TLS/SSL certificate authentication.
GSSAPI (Kerberos) External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.
PLAIN (LDAP SASL) External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.

Custom Filters

You can add a special field to your schema that allows you to pass a custom MongoDB $match query string to your MongoDB instance.

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 mongobischema.

This custom filter field allows you to pass a native MongoDB query string down to MongoDB as the first $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 Custom Filter.

Usage

Generate a Schema

Given documents of the following shape in the collection abc in the database test:

{
    "_id": ObjectId("....")
    "close": 7.45,
    "detail": { "a": 2, "b": 3 }
}

You can use mongodrdl to generate a schema based on this collection by running the following command:

mongodrdl -d test -c abc -o schema.drdl

The generated schema file schema.drdl will look similar to the following:

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

Custom Filter

To use this field, specify the --customFilterField flag with the name you want this field to have:

mongodrdl [ other options ] --customFilterField "_MONGOFILTER" -o schema.drdl

Your DRDL file schema.drdl will include the following field in every generated table:

- name: _MONGOFILTER
  mongotype: mongo.Filter
  sqltype: varchar

To add the special MongoDB query stage to your standard SQL, use the following SQL syntax:

SELECT <normal>
   FROM <tablename>
   WHERE <normal conditions> AND
       "_MONGOFILTER"='{ <json string that represents query to use> }'

SELECT name,age
  FROM users
  WHERE active='t' AND
    "_MONGOFILTER"='{"addr":{"$elemMatch":{"city":"Springfield","state":"CA"}}}'

The MongoDB Connector for BI will translate the above SQL into the following MongoDB aggregation expression:

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 JSON. All quotes inside the JSON must be double quotes.

←   mongobiuser mongobischema  →