1. No category

Simba ODBC Driver with
SQL Connector
for
MongoDB
Installation and Configuration
Guide
Version 1.7
October 24, 2014
Simba Technologies Inc.
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Copyright ©2012-2014 Simba Technologies Inc. All Rights Reserved.
Information in this document is subject to change without notice. Companies, names and data
used in examples herein are fictitious unless otherwise noted. No part of this publication, or the
software it describes, may be reproduced, transmitted, transcribed, stored in a retrieval system,
decompiled, disassembled, reverse-engineered, or translated into any language in any form by
any means for any purpose without the express written permission of Simba Technologies Inc.
Trademarks
Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered
trademarks of Simba Technologies Inc. All other trademarks and/or servicemarks are the property
of their respective owners.
ICU License - ICU 1.8.1 and later
COPYRIGHT AND PERMISSION NOTICE
Copyright (c) 1995-2010 International Business Machines Corporation and others
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so,
provided that the above copyright notice(s) and this permission notice appear in all copies of the
Software and that both the above copyright notice(s) and this permission notice appear in
supporting documentation.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL
THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR
ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
OR PERFORMANCE OF THIS SOFTWARE.
Except as contained in this notice, the name of a copyright holder shall not be used in advertising
or otherwise to promote the sale, use or other dealings in this Software without prior written
authorization of the copyright holder.
All trademarks and registered trademarks mentioned herein are the property of their respective
owners.
w w w. si mb a. co m
2
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
OpenSSL
Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions
and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials
provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the
following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit. (http://www.openssl.org/)"
4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote
products derived from this software without prior written permission. For written permission,
please contact [email protected].
5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear
in their names without prior written permission of the OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit (http://www.openssl.org/)"
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
Expat
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the ""Software""), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
w w w. si mb a. co m
3
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NOINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Lua
Copyright © 1994–2014 Lua.org, PUC-Rio.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
LuaJIT
LuaJIT is Copyright © 2005-2014 Mike Pall
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to
do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
w w w. si mb a. co m
4
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Contact Us
Simba Technologies Inc.
938 West 8th Avenue
Vancouver, BC Canada
V5Z 1E5
www.simba.com
Telephone: +1 (604) 633-0008
Information and Product Sales: Extension 2
Technical Support: Extension 3
Fax: +1 (604) 633-0004
Information and Product Sales: [email protected]
Technical Support: [email protected]
Follow us on Twitter: @SimbaTech
Printed in Canada
w w w. si mb a. co m
5
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Table of Contents
Introduction ........................................................................................................................................................7
Windows Driver..................................................................................................................................................7
System Requirements ................................................................................................................................7
Installing the Driver ...................................................................................................................................8
Creating a Data Source Name ................................................................................................................8
Configuring Options................................................................................................................................ 10
Logging ........................................................................................................................................................ 12
Defining a Schema for the Driver to Use ........................................................................................ 13
Using Virtual Tables ................................................................................................................................. 15
Linux Driver ...................................................................................................................................................... 16
System Requirements ............................................................................................................................. 16
Installing the Driver Using the RPM .................................................................................................. 17
Installing the Driver Using the Tarball Package ............................................................................ 18
Setting the LD_LIBRARY_PATH Environment Variable ............................................................... 18
Mac OS X Driver .............................................................................................................................................. 19
System Requirements ............................................................................................................................. 19
Installation.................................................................................................................................................. 19
Configuring ODBC Connections for Linux and Mac OS X ............................................................... 20
Files ............................................................................................................................................................... 20
Sample Files ................................................................................................................................................ 20
Configuring the Environment.............................................................................................................. 21
Configuring the odbc.ini File ............................................................................................................... 21
Configuring the odbcinst.ini File ........................................................................................................ 22
Configuring the simba.mongodbodbc.ini File ................................................................................ 23
Features ............................................................................................................................................................. 24
SQL Connector........................................................................................................................................... 24
Schema Definition ................................................................................................................................... 24
Data Types................................................................................................................................................... 25
Authentication .......................................................................................................................................... 27
Catalog Support........................................................................................................................................ 27
Virtual Tables ............................................................................................................................................. 28
Write-back .................................................................................................................................................. 30
Contact Us ........................................................................................................................................................ 32
Appendix: Driver Configuration Options ............................................................................................... 33
w w w. si mb a. co m
6
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Introduction
The Simba ODBC Driver with SQL Connector for MongoDB enables Business Intelligence (BI),
analytics, and reporting on data that is stored in MongoDB databases. The driver complies with
the ODBC 3.80 data standard and adds important functionality such as Unicode, as well as 32and 64-bit support for high-performance computing environments on all platforms.
ODBC is one of the most established and widely supported APIs for connecting to and working
with databases. At the heart of the technology is the ODBC driver, which connects an application
to the database. For more information about ODBC, see http://www.simba.com/odbc.htm. For
complete information on the ODBC specification, see the ODBC API Reference at
http://msdn.microsoft.com/en-us/library/windows/desktop/ms714562(v=vs.85).aspx
Simba ODBC Driver with SQL Connector for MongoDB is available for the Microsoft® Windows®,
Linux, and Mac OS X operating systems.
Note: For details on installing and setting up a MongoDB data source, and details on configuring
Microsoft Excel and Tableau as client applications to connect to MongoDB data sources using the
Simba ODBC Driver with SQL Connector for MongoDB, see the Simba ODBC Driver with SQL
Connector for MongoDB Quick Start Guide.
Windows Driver
System Requirements
You install Simba ODBC Driver with SQL Connector for MongoDB on client computers accessing
MongoDB databases. Each computer where you install the driver must meet the following
minimum system requirements:
•
One of the following operating systems (32- and 64-bit editions are supported):
o Windows® Vista
o Windows® 7 Professional
o Windows® 8
o Windows® 8.1
o Windows® Server 2008 R2
•
100 MB of available disk space
Important: To install the driver, you need Administrator privileges on the computer.
Simba ODBC Driver with SQL Connector for MongoDB Version 1.7 supports MongoDB versions
2.2.1 to 2.6
www.simba.com
7
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Installing the Driver
On 64-bit Windows operating systems, you can execute 32- and 64-bit applications
transparently. You must use the version of the driver matching the bitness of the client
application accessing MongoDB databases:
•
SimbaMongoDBODBC32.msi for 32-bit applications
•
SimbaMongoDBODBC64.msi for 64-bit applications
You can install both versions of the driver on the same computer.
Note: For an explanation of how to use ODBC on 64-bit editions of Windows, see
http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf
To install Simba ODBC Driver with SQL Connector for MongoDB:
1. Depending on the bitness of your client application, double-click to run
SimbaMongoDBODBC32.msi or SimbaMongoDBODBC64.msi
2. Click Next
3. Select the check box to accept the terms of the License Agreement if you agree, and then
click Next
4. To change the installation location, click the Change button, then browse to the desired
folder, and then click OK. To accept the installation location, click Next
5. Click Install
6. When the installation completes, click Finish
7. If you received a license file via e-mail, then copy the license file into the \lib subfolder in
the installation folder that you selected in step 4.
Note: To avoid security issues, you may need to save the license file on your local
computer prior to copying the file into the \lib subfolder.
Creating a Data Source Name
After installing Simba ODBC Driver with SQL Connector for MongoDB, you need to create a Data
Source Name (DSN).
To create a Data Source Name:
1. Click the Start button , then click All Programs, then click the Simba MongoDB ODBC
Driver 1.7 program group corresponding to the bitness of the client application accessing
MongoDB databases, and then click ODBC Administrator
2. In the ODBC Administrator, click the Drivers tab, and then scroll down as needed to
confirm that Simba MongoDB ODBC Driver appears in the alphabetical list of driver
names.
www.simba.com
8
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
3. To create a DSN that only the user currently logged into Windows can use, click the User
DSN tab.
OR
To create a DSN that all users who log into Windows can use, click the System DSN tab.
4. Click Add
5. In the Create New Data Source dialog box, select Simba MongoDB ODBC Driver, and then
click Finish
6. In the Simba MongoDB ODBC Driver DSN Setup dialog box, in the Data source name field,
type a name for the data source.
7. In the Description field, type relevant details about the DSN.
8. In the Host field, type the name or IP address of the host where the MongoDB instance
runs.
9. In the Port field, type the number of the port that the MongoDB instance uses.
Note: The default port for MongoDB is 27017.
10. In the Database field, type the name of the MongoDB database to which the client
application needs to connect.
11. In the Username field, type the appropriate login credential for the DSN to provide when
accessing the MongoDB database.
12. In the Additional servers field, type a comma-separated list of additional servers that you
need to use when connecting to a sharded cluster or a replica set. You can indicate the
port on which a server is listening by appending a colon (:) and the port number to the
server name or IP address.
13. If you are connecting to a replica set in your MongoDB implementation, then select the
Connect to a replica set check box and then type the name of the replica set in the
Replica set name field.
Note: Ensure that the names of the secondary servers in the replica set are listed in the
Additional servers field, as described in step 12.
14. To configure advanced driver options, click Advanced Options. For details, see Configuring
Options on page 10.
15. To configure logging behavior for the driver, click Logging Options. For details, see
Logging on page 12.
16. If you need to customize the schema that Simba ODBC Driver with SQL Connector for
MongoDB detects for a MongoDB database, then click Schema Definition. For details, see
Defining a Schema for the Driver to Use on page 13.
17. To test the connection, click Test. If you are prompted for authentication, then type your
user name and password for accessing the MongoDB instance, and then click OK. The Test
Results dialog box appears, displaying a message informing you if the connection
succeeded or failed. Click OK to close the Test Results dialog box.
www.simba.com
9
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Note: To troubleshoot a connection, confirm that the values and settings in the Simba
MongoDB ODBC Driver DSN Setup dialog box are correct. Contact your MongoDB
administrator for assistance as needed.
18. To save your settings and close the Simba MongoDB ODBC Driver DSN Setup dialog box,
click OK
19. To close the ODBC Data Source Administrator, click OK
Configuring Options
You can configure options using the following:
•
Data Source Name
•
Database connection string
For information about the configuration options available in Simba ODBC Driver with SQL
Connector for MongoDB, see Appendix: Driver Configuration Options on page 33.
Using the Data Source Name
To set advanced options using the Simba MongoDB Driver DSN Setup dialog box:
1. In the ODBC Data Source Administrator where you created the DSN, select the DSN tab
where the Data Source Name appears, and then select the Data Source Name.
2. Click Configure, and then click Advanced Options
3. In the Documents fetched per block field, type the maximum number of documents
(rows) that a query returns at a time.
4. In the Nested column separator field, type a character or string to use to separate the
names of nested columns.
5. In the Read preference list, select the appropriate option to specify how the driver routes
read operations to the members of a replica set.
6. In the Sampling strategy list, select the appropriate option to specify the location in the
table to sample rows from when detecting schema.
7. In the Documents to sample field, type the number of documents to sample when
detecting schema for a table.
Note: If you set the value to 0, then the driver scans all documents.
8. In the String Column Lengths area, do the following:
a. In the Standard field, select or type the default length for String columns.
b. In the Container field, select or type the default length for containers (arrays and
objects) in MongoDB.
c. In the DocumentAsJSON field, select or type the default column length for
documentAsJSON fields.
www.simba.com
10
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
9. Select or clear the Use SQL_WVARCHAR for string data types check box as needed. When
this check box is selected, the driver maps the MongoDB String data type to
SQL_WVARCHAR instead of SQL_VARCHAR.
10. To configure the driver to report a special column named documentAsJSON that retrieves
or stores documents as JSON-formatted strings, select Enable reading/writing as JSON
document
11. To configure the driver to display documents and arrays as columns in JSON format in the
real table, select Show container columns when generating metadata
Note: This option does not affect virtual tables.
12. If you purchased the write-enabled Simba ODBC Driver with SQL Connector for MongoDB,
then select or clear check boxes in the Write Configuration area as needed:
a. To configure the driver to check for reported failures after each INSERT or UPDATE
operation, select Check GetLastError on writes
b. To configure the driver so that UPDATE statements update all rows that match the
filters instead of the first matching row only, select Enable updating multiple rows
c. To configure the driver so that INSERT operations do not write null values to table
columns, select Omit default NULL columns on insert. If you clear this check box,
then the INSERT operations write explicitly provided null values to columns, but
not default null values.
d. To configure the driver to truncate any document that is greater than 16MB in
size, select Truncate documents larger than 16MB. If you clear this check box, then
the driver rejects any document that is greater than 16MB in size.
e. To configure the driver to validate BSON objects before INSERT or UPDATE
operations, select Validate BSON before writes
13. In the Metadata Source area, select Database or Local file. If you select Local file, then
click the Browse button, then select the Schema Database Definition (SDD) file from
which to load metadata, and then click OK
14. To save your settings and close the Advanced Options dialog box, click OK
15. To close the Simba MongoDB ODBC Driver DSN Setup dialog box, click OK
Using a DSN-less Connection
Some applications provide support for connecting to a data source using a driver without a DSN.
To connect to a data source without using a DSN, use a connection string instead.
The following is an example of a connection string that contains only the minimum required
attributes:
Driver=Simba MongoDB ODBC Driver;
Host=192.168.100.100;
Port=27017;
Database=MyDatabase
www.simba.com
11
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
The following is an example connection string that sets some advanced options:
Driver=Simba MongoDB ODBC Driver;
Host=192.168.100.100;
Port=27017;
Database=MyDatabase;
UID=MyUsername;
PWD=MyPassword;
RowsFetchedPerBlock=4096;
DefaultStringColumnLength=255;
DefaultContainerColumnLength=511;
UseSqlWVarchar=0;
CacheMetadata=1;
VirtualTableDetection=1
Logging
To help troubleshoot issues, you can enable logging. In addition to functionality provided in the
Simba ODBC Driver with SQL Connector for MongoDB, the ODBC Data Source Administrator
provides tracing functionality.
Important: Only enable logging long enough to capture an issue. Logging decreases performance
and can consume a large quantity of disk space.
The driver allows you to set the amount of detail included in log files. In order from highest to
lowest level, Table 1 lists logging levels provided by the Simba ODBC Driver with SQL Connector
for MongoDB.
Logging Level
Description
OFF
Disables all logging.
FATAL
Logs very severe error events that will lead the driver to abort.
ERROR
Logs error events that might still allow the driver to continue
running.
WARNING
Logs potentially harmful situations.
INFO
Logs general information that describes the progress of the
driver.
DEBUG
Logs detailed information that is useful for debugging the driver.
TRACE
Logs more detailed information than the DEBUG level.
Table 1 Simba ODBC Driver with SQL Connector for MongoDB Logging Levels
www.simba.com
12
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
To enable logging functionality available in the Simba ODBC Driver with SQL Connector for
MongoDB:
1. In the Simba MongoDB ODBC Driver DSN Setup dialog box, click Logging Options
2. In the Log level list, select the desired level of information to include in log files.
3. In the Log directory field, type the full path to the folder where you want to save log
files.
4. Click OK
The Simba ODBC Driver with SQL Connector for MongoDB produces a log file named
MongoDBODBC_driver.log at the location you specify using the Log directory field.
To disable Simba ODBC Driver with SQL Connector for MongoDB logging:
1. In the Simba MongoDB ODBC Driver DSN Setup dialog box, click Logging Options
2. In the Log level list, select LOG_OFF
3. Click OK
To start tracing using the ODBC Data Source Administrator:
1. In the ODBC Data Source Administrator, click the Tracing tab.
2. In the Log File Path area, click Browse. In the Select ODBC Log File dialog box, browse to
the location where you want to save the log file, then type a descriptive file name in the
File name field, and then click Save
3. On the Tracing tab, click Start Tracing Now
To stop ODBC Data Source Administrator tracing:
 On the Tracing tab in the ODBC Data Source Administrator, click Stop Tracing Now
For more information about tracing using the ODBC Data Source Administrator, see the article
How to Generate an ODBC Trace with ODBC Data Source Administrator at
http://support.microsoft.com/kb/274551
Defining a Schema for the Driver to Use
This section explains how to customize the schema that the driver uses when connecting to a
MongoDB instance. For information about how the Simba ODBC Driver with SQL Connector for
MongoDB uses a schema, see Schema Definition on page 24.
Note: The driver will automatically generate the schema if you do not manually define it. When
you select data from a table for the first time, the driver generates the schema for that table.
In the Schema Definition dialog box, you must first select or set a Schema Database Definition
(SDD) file. All actions to export, edit, or update metadata that you complete in the Schema
Definition dialog box use the SDD file that you set.
www.simba.com
13
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
You can export metadata for all tables, missing tables, or tables that you select.
To define a schema that the Simba ODBC Driver with SQL Connector for MongoDB uses when
connecting to a MongoDB instance:
1. In the ODBC Data Source Administrator where you created the DSN, select the DSN tab
where the Data Source Name appears, and then select the Data Source Name.
2. Click the Configure button, and then click the Schema Definition button.
3. In the Schema Definition dialog box, click the Browse button next to the External schema
file field. In the Save As dialog box, browse to select the existing SDD file that you want
to use, and then click Save
OR
In the Save As dialog box, type the name of a new SDD file that you want to create in the
File name field, and then click Save
4. To export metadata to the SDD file that you set, do one of the following:
•
If the desired metadata has already been generated, then click Export Existing to
export the metadata. In the confirmation dialog box, click OK
•
To generate and export metadata for all the tables in the database, click Export All
Tables. In the confirmation dialog box, click OK
•
To generate and export metadata for tables in the database that are currently not
included in the schema, click Export Missing Tables. In the confirmation dialog
box, click OK
•
To generate and export metadata for a specific table, use the options in the Export
One Table area:
a. In the Database source table list, select the table for which you want to
generate and export metadata.
b. Optionally, in the JSON filter field, type an appropriate JSON filter to apply
to data in the selected table prior to generating metadata.
c. Click Export Table. In the confirmation dialog box, click OK
d. Repeat steps a to c as needed to include all desired metadata in the SDD
file that you set.
Note: The value you type in the JSON filter field is the MongoDB equivalent of a
WHERE clause in SQL. For example, the SQL statement SELECT * FROM at_1 WHERE
_id = “T123” returns the row having the value T123 in the _id field from the table
named at_1. In the Schema Definition dialog box, selecting at_1 from the Table
Name list and then typing {_id: “T123”} in the JSON Filter field returns the same
result. For more information, see the “db.collection.find()” section of the MongoDB
Manual at
http://docs.mongodb.org/manual/reference/method/db.collection.find/#db.collecti
on.find. The JSON filter is the argument for the “criteria” parameter.
www.simba.com
14
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
5. To edit metadata in the SDD file that you set, click Edit Schema File. Using the Simba
Schema Editor that opens, edit the schema as needed, and then save your edits.
Note: The Simba Schema Editor is installed with the Simba ODBC Driver with SQL
Connector for MongoDB. You can find the Simba Schema Editor application in the
/Tools/Schema Editor subfolder in the Simba ODBC Driver with SQL Connector for
MongoDB installation folder. The Simba Schema Editor is a Java application. For details on
using the Simba Schema Editor, see the Simba Schema Editor User Guide.
6. To update the schema that the driver uses to connect to your MongoDB instance with the
metadata in the SDD file that you set, in the Update area of the Schema Definition dialog
box, click Update Metadata.
Note: The Current metadata source field displays the metadata source that you set using
the Advanced Options dialog box. For information about how to set the metadata source,
see Configuring Options on page 10.
7. Repeat steps 5 and 6 until your queries perform as needed.
8. If you want to delete all the metadata that the driver has generated for the MongoDB
instance, click Clear Existing Metadata
9. To configure options related to virtual tables, click Virtual Table Options. For details, see
Using Virtual Tables on page 15.
Important: By default, the Simba ODBC Driver with SQL Connector for MongoDB enables
virtual table creation. If possible, configure options related to virtual tables as needed
prior to connecting to your MongoDB data source using the Simba ODBC Driver with SQL
Connector for MongoDB for the first time. Connecting to the data source generates a
schema for the data source. If you configure options for virtual tables after connecting to
the data source, then you need to export and then import the schema for changes to take
effect.
10. In the Schema Definition dialog box, click OK
Using Virtual Tables
For a discussion and example showing how the Simba ODBC Driver with SQL Connector for
MongoDB implements virtual tables, see Virtual Tables on page 28.
For information about the configuration options available in Simba ODBC Driver with SQL
Connector for MongoDB, including settings related to virtual tables, see Appendix: Driver
Configuration Options on page 33.
To set Simba ODBC Driver with SQL Connector for MongoDB options related to using virtual
tables:
1. In the ODBC Data Source Administrator where you created the DSN, select the DSN tab
where the Data Source Name appears, and then select the Data Source Name.
2. Click Configure, then click Schema Definition, and then click Virtual Table Options.
www.simba.com
15
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
3. To enable the generation of metadata for virtual tables, select the Enable virtual table
detection check box.
4. In the Virtual main table name suffix field, type a suffix for naming the main virtual
table.
5. In the Virtual key column separator field, type a separator for generated column names in
a virtual table.
6. In the Virtual table name separator field, type a separator for naming a virtual table built
from an array column.
7. In the Virtual table index column suffix field, type a suffix for naming generated columns
in a virtual table that indicate the position/index of an element into an array.
8. To configure the driver to hide the real table when virtual tables have been created, select
Hide real table if virtual tables created
9. To show the array count column in the main virtual table, select the Show array counts in
virtual main table check box, and then in the Virtual table array count prefix field, type a
prefix for naming the array count column.
10. To save your settings and close the Virtual Table Options dialog box, click OK
Linux Driver
System Requirements
Each computer where you install the driver must meet the following minimum system
requirements:
•
One of the following operating systems (32- and 64-bit editions are supported):
o Red Hat® Enterprise Linux® (RHEL) 5.x
o CentOS 5.x
o CentOS 6.x
o SUSE Linux Enterprise Server (SLES) 11
•
300 MB of available disk space
•
An installed ODBC driver manager:
•
iODBC 3.52.7 or above
OR
•
unixODBC 2.2.12 or above
Simba ODBC Driver with SQL Connector for MongoDB Version 1.7 supports MongoDB 2.2.1 to 2.6
www.simba.com
16
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Installing the Driver Using the RPM
You can install the driver using RPMs. There are two versions of the driver for Linux:
•
•
SimbaMongoDBODBC-32bit-Version-Release.rpm—32-bit driver
SimbaMongoDBODBC-Version-Release.rpm—64-bit driver
The bitness of the driver that you select should match the bitness of the client application
accessing your MongoDB-based data. For example, if the client application is 64-bit, then you
should install the 64-bit driver. Note that 64-bit editions of Linux support both 32- and 64-bit
applications. Verify the bitness of your intended application and install the appropriate version of
the driver.
Simba ODBC Driver with SQL Connector for MongoDB driver files are installed in the following
directories:
•
/opt/simba/mongodbodbc/ contains release notes, the Simba ODBC Driver with SQL
Connector for MongoDB Installation and Configuration Guide in PDF format and a
Readme.txt file that provides plain text installation and configuration instructions.
•
/opt/simba/mongodbodbc/lib/32 contains the 32-bit Simba ODBC Driver with SQL
Connector for MongoDB for Linux, as well as the simba.mongodbodbc.ini configuration
file.
•
/opt/simba/mongodbodbc/lib/64 contains the 64-bit Simba ODBC Driver with SQL
Connector for MongoDB for Linux, as well as the simba.mongodbodbc.ini configuration
file.
•
/opt/simba/mongodbodbc/ErrorMessages contains error message files required by the
Simba ODBC Driver with SQL Connector for MongoDB.
•
/opt/simba/mongodbodbc/Setup contains sample configuration files named odbc.ini and
odbcinst.ini
•
/opt/simba/mongodbodbc/Tools/Schema Editor contains the Simba Schema Editor Java
application.
To install Simba ODBC Driver with SQL Connector for MongoDB:
1. In Red Hat Enterprise Linux 5.0 or CentOS 5.0, log in as the root user, then navigate to the
folder containing the driver RPM packages to install, and then type the following at the
command line, where RPMFileName is the file name of the RPM package containing the
version of the driver that you want to install:
yum --nogpgcheck localinstall RPMFileName
OR
In SUSE Linux Enterprise Server 11, log in as the root user, then navigate to the folder
containing the driver RPM packages to install, and then type the following at the
command line, where RPMFileName is the file name of the RPM package containing the
version of the driver that you want to install:
www.simba.com
17
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
zypper install RPMFileName
2. If you received a license file via e-mail, then copy the license file into the /opt/simba/
mongodbodbc /lib/32 or /opt/simba/mongodbodbc /lib/64 folder, depending on the
version of the driver that you installed.
Installing the Driver Using the Tarball Package
Alternatively, the Simba ODBC Driver with SQL Connector for MongoDB is available for
installation using a TAR.GZ tarball package. The tarball package includes:
•
[INSTALL_DIR]/simba/mongodbodbc/ contains release notes, the Simba ODBC Driver with
SQL Connector for MongoDB Installation and Configuration Guide in PDF format and a
Readme.txt file that provides plain text installation and configuration instructions.
•
[INSTALL_DIR]/simba/mongodbodbc/lib/32 contains the 32-bit Simba ODBC Driver with
SQL Connector for MongoDB for Linux, as well as the simba.mongodbodbc.ini
configuration file.
•
[INSTALL_DIR]/simba/mongodbodbc/lib/64 contains the 64-bit Simba ODBC Driver with
SQL Connector for MongoDB for Linux, as well as the simba.mongodbodbc.ini
configuration file.
•
[INSTALL_DIR]/simba/mongodbodbc/ErrorMessages contains error message files required
by the Simba ODBC Driver with SQL Connector for MongoDB.
•
[INSTALL_DIR]/simba/mongodbodbc/Setup contains sample configuration files named
odbc.ini and odbcinst.ini
•
[INSTALL_DIR]/simba/mongodbodbc/Tools/Schema Editor contains the Simba Schema
Editor Java application.
Setting the LD_LIBRARY_PATH Environment Variable
The LD_LIBRARY_PATH environment variable must include the paths to installed ODBC driver
manager libraries.
For example, if ODBC driver manager libraries are installed in /usr/local/lib, then set
LD_LIBRARY_PATH as follows:
export LD_LIBRARY_PATH=/usr/local/lib
For information about how to set environment variables permanently, refer to your Linux shell
documentation.
For information about creating ODBC connections using Simba ODBC Driver with SQL Connector
for MongoDB, see Configuring ODBC Connections for Linux and Mac OS X on page 20.
www.simba.com
18
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Mac OS X Driver
System Requirements
Each computer where you install the driver must meet the following minimum system
requirements:
•
Mac OS X version 10.6.8 or later
•
100 MB of available disk space
•
iODBC 3.52.7 or above
Simba ODBC Driver with SQL Connector for MongoDB Version 1.7 supports MongoDB 2.2.1 to 2.6
Installation
Simba ODBC Driver with SQL Connector for MongoDB driver files are installed in the following
directories:
•
/opt/simba/mongodbodbc/ErrorMessages contains error message files required by the
Simba ODBC Driver with SQL Connector for MongoDB.
•
/opt/simba/mongodbodbc/Setup contains sample configuration files named odbc.ini and
odbcinst.ini
•
/opt/simba/mongodbodbc/Tools/Schema Editor contains the Simba Schema Editor Java
application.
•
/opt/simba/mongodbodbc/lib/universal contains the Simba ODBC Driver with SQL
Connector for MongoDB for Mac OS X, as well as the simba.mongodbodbc.ini
configuration file.
To install Simba ODBC Driver with SQL Connector for MongoDB:
1. Double-click to mount the SimbaMongoDBODBC.dmg disk image.
2. Double-click SimbaMongoDBODBC.pkg to run the installer.
3. Follow the instructions in the installer to complete the installation process.
4. When the installation completes, click Close
5. If you received a license file via e-mail, then copy the license file into the
/opt/simba/mongodbodbc/lib/universal folder.
www.simba.com
19
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Setting the DYLD_LIBRARY_PATH Environment Variable
The DYLD_LIBRARY_PATH environment variable must include the paths to installed ODBC driver
manager libraries.
For example, if ODBC driver manager libraries are installed in /usr/local/lib, then set
DYLD_LIBRARY_PATH as follows:
export DYLD_LIBRARY_PATH=/usr/local/lib
For information about how to set environment variables permanently, refer to your Mac OS X
shell documentation.
For information about creating ODBC connections using Simba ODBC Driver with SQL Connector
for MongoDB, see Configuring ODBC Connections for Linux and Mac OS X on page 20.
Configuring ODBC Connections for Linux and Mac OS X
Files
ODBC driver managers use configuration files to define and configure ODBC data sources and
drivers. By default, the following configuration files residing in the user’s home directory are
used:
•
.odbc.ini – The file used to define ODBC data sources (required)
•
.odbcinst.ini – The file used to define ODBC drivers (optional)
Also, by default the Simba ODBC Driver with SQL Connector for MongoDB is configured using the
simba.mongodbodbc.ini file in the subfolder in the /lib folder containing the binaries for the
driver that you are using. The simba.mongodbodbc.ini file is required.
Note: The simba.mongodbodbc.ini file in the /lib subfolder provides default settings for most
configuration options available in the Simba ODBC Driver with SQL Connector for MongoDB.
Sample Files
The driver installation contains the following sample configuration files in the Setup directory:
•
odbc.ini
•
odbcinst.ini
The sample configuration files in the Setup directory provide preset values for settings related to
the Simba ODBC Driver with SQL Connector for MongoDB.
The names of the sample configuration files do not begin with a period (.) in order to appear in
directory listings by default. A filename beginning with a period (.) is hidden. For odbc.ini and
odbcinst.ini, if the default location is used, then the filenames must begin with a period (.).
www.simba.com
20
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
If configuration files do not exist in the user’s home directory, then you can copy the sample
configuration files to the home directory, and then rename the files. If the configuration files
already exist in the home directory, then use the sample configuration files as a guide to modify
the existing configuration files.
Configuring the Environment
Optionally, you can use three environment variables—ODBCINI, ODBCSYSINI, and
SIMBAMONGODBINI—to specify different locations for the odbc.ini, odbcinst.ini and
simba.mongodbodbc.ini configuration files by doing the following:
•
Set ODBCINI to point to your odbc.ini file.
•
Set ODBCSYSINI to point to the directory containing the odbcinst.ini file.
•
Set SIMBAMONGODBINI to point to your simba.mongodbodbc.ini file.
For example, if your odbc.ini and simba.mongodbodbc.ini files are located in the folder /etc and
your odbcinst.ini file is located in the folder /usr/local/odbc, then set the environment variables
as follows:
export ODBCINI=/etc/odbc.ini
export ODBCSYSINI=/usr/local/odbc
export SIMBAMONGODBINI=/etc/simba.mongodbodbc.ini
The following search order is used to locate the simba.mongodbodbc.ini file:
1. If the SIMBAMONGODBINI environment variable is defined, then the driver searches for
the file specified by the environment variable.
Important: SIMBAMONGODBINI must contain the full path, including the filename.
2. The directory containing the driver’s binary is searched for a file named
simba.mongodbodbc.ini (not beginning with a period).
3. The current working directory of the application is searched for a file named
simba.mongodbodbc.ini (not beginning with a period).
4. The directory ~/ (that is, $HOME) is searched for a hidden file named
.simba.mongodbodbc.ini
5. The directory /etc is searched for a file named simba.mongodbodbc.ini (not beginning
with a period).
Configuring the odbc.ini File
Note: For an example odbc.ini file providing preset values for settings related to the Simba ODBC
Driver with SQL Connector for MongoDB, see the Setup directory in the folder where you
installed the driver.
www.simba.com
21
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
ODBC Data Sources are defined in the odbc.ini configuration file. The file is divided into several
sections:
•
[ODBC] is optional and used to control global ODBC configuration, such as ODBC tracing.
•
[ODBC Data Sources] is required, listing DSNs and associating DSNs with a driver.
•
A section having the same name as the data source specified in the [ODBC Data Sources]
section is required to configure the data source.
The following is an example odbc.ini configuration file for Linux:
[ODBC Data Sources]
Sample Simba MongoDB DSN 32=Simba MongoDB ODBC Driver 32-bit
[Sample Simba MongoDB DSN 32]
Driver=/opt/simba/mongodbodbc/lib/32/libsimbamongodbodbc32.so
HOST=MyMongoDBServer
PORT=10000
The following is an example odbc.ini configuration file for Mac OS X:
[ODBC Data Sources]
Sample Simba MongoDB DSN=Simba MongoDB ODBC Driver
[Sample Simba MongoDB DSN]
Driver=/opt/simba/mongodbodbc/lib/universal/libsimbamongodbodbc.dylib
HOST=MyMongoDBServer
PORT=10000
To create a data source:
1. Open the .odbc.ini configuration file in a text editor.
2. Add a new entry to the [ODBC Data Sources] section. Type the data source name (DSN)
and the driver name.
3. To set configuration options, add a new section having a name matching the data source
name (DSN) you specified in step 2. Specify configuration options as key-value pairs.
4. If you are connecting to a MongoDB database that uses authentication, then set the
following key:
UID=MyUsername
MyUsername is your login credential for accessing the MongoDB database.
5. Save the .odbc.ini configuration file.
For information about the configuration options available in Simba ODBC Driver with SQL
Connector for MongoDB, see Appendix: Driver Configuration Options on page 33.
Configuring the odbcinst.ini File
Note: For an example odbc.ini file providing preset values for settings related to the Simba ODBC
Driver with SQL Connector for MongoDB, see the Setup directory in the folder where you
installed the driver.
www.simba.com
22
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
ODBC Drivers are defined in the odbcinst.ini configuration file. The configuration file is optional
because drivers can be specified directly in the odbc.ini configuration file, as described in
Configuring the odbc.ini File on page 21.
The odbcinst.ini file is divided into the following sections:
•
[ODBC Drivers] lists the names of all the installed ODBC drivers.
•
A section having the same name as the driver name specified in the [ODBC Drivers]
section lists driver attributes and values.
The following is an example odbcinst.ini file for Linux:
[ODBC Drivers]
Simba MongoDB ODBC Driver 32-bit=Installed
Simba MongoDB ODBC Driver 64-bit=Installed
[Simba MongoDB ODBC Driver 32-bit]
Description=Simba MongoDB ODBC Driver (32-bit)
Driver=/opt/simba/mongodbodbc/lib/32/libsimbamongodbodbc32.so
[Simba MongoDB ODBC Driver 64-bit]
Description=Simba MongoDB ODBC Driver (64-bit)
Driver=/opt/simba/mongodbodbc/lib/64/libsimbamongodbodbc64.so
The following is an example odbcinst.ini file for Mac OS X:
[ODBC Drivers]
Simba MongoDB ODBC Driver=Installed
[Simba MongoDB ODBC Driver]
Description=Simba MongoDB ODBC Driver
Driver=/opt/simba/mongodbodbc/lib/universal/libsimbamongodbodbc.dylib
To define a driver:
1. Open the .odbcinst.ini configuration file in a text editor.
2. Add a new entry to the [ODBC Drivers] section. Type the driver name, and then type
=Installed
Note: Assign the driver name as the value of the Driver attribute in the data source
definition instead of the driver shared library name.
3. In .odbcinst.ini, add a new section having a name matching the driver name you typed in
step 2, and then add configuration options to the section based on the sample
odbcinst.ini file provided with Simba ODBC Driver with SQL Connector for MongoDB in
the Setup directory. Specify configuration options as key-value pairs.
4. Save the .odbcinst.ini configuration file.
Configuring the simba.mongodbodbc.ini File
To configure Simba ODBC Driver with SQL Connector for MongoDB to work with your ODBC
driver manager:
1. Open the simba.mongodbodbc.ini configuration file in a text editor.
www.simba.com
23
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
2. Edit the DriverManagerEncoding setting. The value is usually UTF-16 or UTF-32,
depending on the ODBC driver manager you use. iODBC uses UTF-32, and unixODBC uses
UTF-16. Consult your ODBC Driver Manager documentation for the correct setting to use.
3. Edit the ODBCInstLib setting. The value is the name of the ODBCInst shared library for the
ODBC driver manager you use. The configuration file defaults to the shared library for
iODBC. In Linux, the shared library name for iODBC is libiodbcinst.so. In Mac OS X, the
shared library name for iODBC is libiodbcinst.dylib.
Note: Consult your ODBC driver manager documentation for the correct library to specify.
You can specify an absolute or relative filename for the library. If you intend to use the
relative filename, then the path to the library must be included in the library path
environment variable. In Linux, the library path environment variable is named
LD_LIBRARY_PATH. In Mac OS X, the library path environment variable is named
DYLD_LIBRARY_PATH.
4. Save the simba.mongodbodbc.ini configuration file.
Features
SQL Connector
The SQL Connector feature of the driver allows applications to use normal SQL queries against
MongoDB, translating standard SQL-92 queries into equivalent MongoDB API calls. This allows
standard queries that BI tools execute to run against your MongoDB instance.
Schema Definition
Simba ODBC Driver with SQL Connector for MongoDB dynamically detects the database schema—
also referred to as metadata—needed for ODBC in the process of connecting to a MongoDB
database. You can also edit the schema that the driver uses manually using the Simba Schema
Editor.
The Simba Schema Editor is a Java application that runs on Windows, Linux, and Mac OS X. The
Simba Schema Editor is included when you install the Simba ODBC Driver with SQL Connector for
MongoDB. For more details on using the Simba Schema Editor, see the Simba Schema Editor User
Guide.
To define a schema manually:
1. Export the schema from the driver.
2. Edit the schema using the Simba Schema Editor application.
3. Import the edited schema into the driver.
4. Repeat steps 2 to 3 until your queries perform as needed.
For information about exporting and importing the schema when using the Windows driver, see
Defining a Schema for the Driver to Use on page 13. For information about exporting and
www.simba.com
24
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
importing the schema when using the Linux or Mac OS X driver, see Appendix: Driver
Configuration Options on page 33.
Data Types
The following data types are supported:
•
Array (see below for more information)
•
MaxKey
•
BinData
•
MinKey
•
Boolean
•
NumberDouble
•
Code
•
NumberInt
•
CodeWScope
•
NumberLong
•
Date
•
Object (see below for more information)
•
DBRef (deprecated)
•
RegEx
•
jstOID
•
String
•
JSTypeMax
•
Symbol
•
Timestamp
Embedded Documents
Embedded documents in MongoDB are represented as nested columns in the Simba ODBC Driver
with SQL Connector for MongoDB. For example, consider the following JSON document:
{"contact": {"address": {"street": "1-123 Broadway", "city":
"Vancouver"}}, "phone": "+12345678"}
The driver identifies the following columns in the document:
Column
MongoDB Data Type
Data
contact.address.street
String
1-123 Broadway
contact.address.city
String
Vancouver
phone
String
+12345678
The identified columns will act in the same way as any other column when being mapped to SQL
data types or when generalizing data types.
If there are different fields within a document, then only the most general fields are identified as
columns. Consider the following two documents:
{"contact": {"address": {"street": "1-123 Broadway", "city":
"Vancouver"}}, "phone": "+12345678"}
{"contact": {"address": "22 Cambie, Vancouver"}, "phone": "+87654321"}
www.simba.com
25
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
In the second document, contact.address is not an embedded document, so the driver considers
contact.address as a String instead of an embedded document. Respectively, the driver identifies
the following columns for each document:
Column
MongoDB Data Type
Data
contact.address
String
{street: “1-123 Broadway”, city: “Vancouver”}
22 Cambie, Vancouver
phone
String
+12345678
+87654321
In a SQL query, when a column name contains the separator character, you need to enclose the
column name in quotes (“). For example:
SELECT "contact.address", "phone" FROM Contacts
Arrays
The ODBC interface does not natively support collection-based data types, so the Simba ODBC
Driver with SQL Connector for MongoDB implements two options for accessing and interacting
with collection-based data. Depending on preference, arrays in MongoDB can be represented as
either virtual tables or nested columns. By default, arrays are represented as virtual tables. The
driver uses the nested column representation when Virtual Table Detection is disabled in the
configuration.
Arrays as Virtual Tables
The Simba ODBC Driver with SQL Connector for MongoDB can represent arrays in MongoDB using
virtual tables. For more information, see Virtual Tables on page 28 and Using Virtual Tables on
page 15.
Arrays as Nested Columns
Arrays in MongoDB can also be represented as nested columns in the Simba ODBC Driver with
SQL Connector for MongoDB. Consider the following JSON document using an array:
{"values": ["hello", 1, {"v1": {"v2": "this is an embedded
document"}}]}
The driver identifies the following columns:
Column
MongoDB Data Type
Data
values.0
String
Hello
values.1
Double
1.0
values.2.v1.v2
String
this is an embedded document
www.simba.com
26
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
The column names include the index of the item in the array that the column represents, starting
with an index of 0. In other words, the first element of the array uses a suffix of .0, the second
element uses .1, and so on.
If different rows in the sample have the same field with different data types, then a precedence
order is used to determine the type. The generated type will be the first one from the following
list that appears in the sample data:
1. Array
2. Object
3. Binary
4. String
5. NumberDouble
6. NumberLong
7. NumberInt
Data types having no direct mapping from Mongo to ODBC are represented as type VARCHAR in
ODBC. The detected MongoDB type is used during INSERT and UPDATE operations.
Columns mapped to SQL data types or generalized act in the same way as any other column.
For example, the following field named f is generalized to type Array:
{f : {g1 : 1}}
{f : [1, 2, 3]}
In a SQL query, when a column name contains the separator character you need to enclose the
column name in quotes (“). For example:
SELECT "values.0", "values.1", "values.2.v1.v2" FROM Contacts
Authentication
Simba ODBC Driver with SQL Connector for MongoDB leverages authentication built into
MongoDB. Built-in authentication requires users to supply a user name and password.
For information about using authentication when the driver is installed on the Windows
operating system, see Creating a Data Source Name on page 8. For information about Linux and
Mac OS X installations, see Configuring the odbc.ini File on page 21.
Catalog Support
Simba ODBC Driver with SQL Connector for MongoDB supports catalogs by using the name of the
MongoDB database as the catalog, allowing the driver to work easily with various ODBC
applications.
www.simba.com
27
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
Virtual Tables
One advantage of the MongoDB design is the ability to create schemas with data that is
denormalized into a fewer number of tables. By taking advantage of arrays, transactions can be
simplified. However the ODBC interface does not natively support accessing this type of data in
an intuitive manner. By expanding the data contained within an array into virtual tables, the
Simba ODBC Driver with SQL Connector for MongoDB allows users to directly interact with their
data but leave the storage of the data in its denormalized form in MongoDB.
When creation of virtual tables is enabled in the driver, the first time that a table having cells
containing embedded arrays is queried the driver creates a virtual table for each embedded array
found in the real table, up to four levels deep for reading and up to two levels deep for writing.
Virtual tables appear as additional tables in a list showing tables that exist in the database. Once
created, virtual tables are persistent within the schema that the driver creates and is using for the
connection.
Virtual tables link to data in the real table. When you write to your MongoDB database using a
virtual table, data in the real table is updated. When the Simba ODBC Driver with SQL Connector
for MongoDB creates virtual tables, a virtual main table is created containing data matching the
real table, but replacing data embedded in the real table with links from other virtual tables that
reference the data embedded in the real table, using unique MongoDB IDs. In virtual tables that
the driver creates, the names of primary and foreign key fields end with the suffix _id. By
querying the virtual tables, you can access the contents of embedded arrays via ODBC.
The virtual main table is named using the convention RealTableName VirtualTableNameSeparator
VirtualMainTableNameSuffix where RealTableName is the name of the corresponding real table,
VirtualTableNameSeparator is _vt_ by default, and VirtualMainTableNameSuffix is main by
default. Other virtual tables are named using the convention RealTableName
VirtualTableNameSeparator ArrayName where RealTableName is the name of the real table
containing the embedded data, VirtualTableNameSeparator is _vt_ by default, and ArrayName is
the shortest unique version of the embedded data array name.
You can change the Virtual Table Name Separator and Virtual Main Table Name Suffix.
Important: If possible, configure options related to virtual tables as needed prior to connecting to
your MongoDB data source using the Simba ODBC Driver with SQL Connector for MongoDB for
the first time. Connecting to the data source generates a schema for the data source. If you
configure options for virtual tables after connecting to the data source, then you need to export
and then import the schema for changes to take effect. For information about exporting and
importing a schema in Windows, see Defining a Schema for the Driver to Use on page 13. For
information about exporting and importing a schema in Linux or Mac OS X, see Appendix: Driver
Configuration Options on page 33.
www.simba.com
28
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
For example, consider the following table in MongoDB, CustomerTable:
_id
1111
Customer
Name
ABC
Invoices
Service
Level
[{invoice_id=123,item=toaster,
price=456,discount=0.2},
Silver
{invoice_id=124,item=oven,
price=1235,discount=0.2}]
2222 XYZ
Contacts
Oggs
[{type=primary,name="John [1,2]
Johnson"},
{type=invoicing,name="Jill
Jilliamson"}]
[{invoice_id=135,item=denial,
price=12543,discount=0.0}]
Lead
[{type=primary,name="Jane
Doe"}]
[8,9]
This table has two columns that have an array of Objects in each cell (Invoices, Contacts) and one
column that has an array of Scalar types (Oggs). If Virtual Table Detection is enabled, then
multiple virtual tables would be generated for this single Source table. The first table is the main
virtual table:
CustomerTable_vt_main
_id
1111
Customer
Name
Number of
Invoices
Service Level
Number of
Contacts
Number of Oggs
ABC
2
Silver
2
2
2222 XYZ
1
Lead
1
2
This virtual table contains all of the data of the original table, but the data from the arrays has
been left out and will be expanded in the other virtual tables. The cells that originally contained
the array data have been replaced with counts of the number of elements in the array (Number
of Invoices, Number of Contacts, Number of Oggs). By default, the columns containing counts are
hidden and do not appear in ODBC.
Now, have a closer look at the expanded virtual tables representing the original arrays:
CustomerTable_vt_Invoices
CustomerTable._id
Invoices_index
invoice_id
item
price
discount
1111
1
123
toaster
456
0.2
1111
2
124
oven
1235
0.2
2222
1
135
denial
12543
0.0
www.simba.com
29
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
CustomerTable_vt_Contacts
CustomerTable._id
Invoices_index
type
name
1111
1
primary
John Johnson
1111
2
invoicing
Jill Jilliamson
2222
1
primary
Jane Doe
CustomerTable_vt_Oggs
CustomerTable._id
Oggs_index
Oggs.value
1111
1
1
1111
2
2
2222
1
8
2222
2
9
Each of these tables contain a reference back to the original primary key column corresponding
to the row of the original array (CustomerTable._id), an indication of the position of the data
within the original array (Invoices_index, Contacts_index, Oggs_index), and the expanded data
for each element within the array (for Invoices: (invoice_id, item, price, discount), for Contacts:
(type, name), for Oggs: (Oggs.value)).
The data within each of these virtual tables can be selected, inserted and updated as if they were
normal tables, and the driver will take care of the storage details within MongoDB. You can also
explicitly append data to the end of an array by inserting a row of data with the index column
set to -1. For example, to append 3 to the Oggs array in the CustomerTable where _id = 1111, you
would submit a query to:
INSERT INTO CustomerTable_vt_Oggs (CustomerTable._id, Oggs_index,
Oggs.value) VALUES (1111, -1, 3)
Write-back
The write-enabled version of the Simba ODBC Driver with SQL Connector for MongoDB supports
Data Manipulation Language (DML) statements such as INSERT, UPDATE, and DELETE. These
statements expose standard SQL-92 behavior. The driver does not execute the DML statements
atomically, as MongoDB does not have transaction support. However, MongoDB guarantees
atomic update on a single row and so does the driver. If an UPDATE/DELETE statement affects
multiple rows and an error occurs in one of them, then the driver returns an error, but the rows
that are already updated will remain so. Which means, for an UPDATE/DELETE statement, some
rows may be updated successfully and the driver may return an error for the rest. Some special
cases with DML statements are described in more detail below.
www.simba.com
30
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Important: The read-only version of the driver does not support the use of DML statements such
as INSERT, UPDATE, and DELETE.
INSERT
Each row in MongoDB needs to have a unique ID represented by the “_id” column. If not provided
during insertion, MongoDB auto-generates a unique ID for each row. The “_id” field is exposed as
a valid column in MongoDB ODBC Driver and can be auto-generated when issuing INSERT
statements through the driver. For example, consider the following table:
_id
sample_column
"517024D6CC79814E3FEBD352"
1
"5170ED77E49CC93A918DE316"
2
To insert a document with auto-generated value for “_id” (data type: jstOID), issue the following
command:
INSERT INTO sample_table_1(sample_column) VALUES(3)
After the insertion, the table would look like as below:
_id
sample_column
"517024D6CC79814E3FEBD352"
1
"5170ED77E49CC93A918DE316"
2
"51710FFCE49CC93A918DE322"
3
The value for the “_id” column can also be inserted using the INSERT statements, as in the
following examples:
INSERT INTO sample_table_2(_id, sample_column) VALUES(1,1)
INSERT INTO sample_table_2 VALUES(1,1)
UPDATE
When updating rows, special care needs to be taken to avoid duplicate values for the “_id”
column. As mentioned before, “_id” needs to be unique across all rows. When an UPDATE
statement tries to set a value for the “_id” column and matches multiple rows, only one of the
rows is updated with the new values, and the driver return an error for the remaining rows.
UPDATE is not executed atomically.
DELETE
Currently, the driver considers a table valid as long as the table contains some data. If a table is
completely empty, then the driver is not able to access the table. Consider the following example:
DELETE FROM sample_table_3
www.simba.com
31
Simba ODBC Driver with SQL Connector for MongoDB
Installation and Configuration Guide
The command removes all data from sample_table_3. Therefore, sample_table_3 is invalid. Any
users attempting to access the table receive an error.
A table exists until the metadata is removed. Continuing the example, the following command
removes the table metadata:
DROP TABLE sample_table_3
Supported Data Types for DML
All supported data types are supported for DML statements.
CREATE TABLE cannot create virtual tables, arrays, or nested objects. In general, it is
recommended to create tables by inserting a row using the mongo shell and then generating the
schema from the row.
Also, the data provided in DML statements should match the existing column data types. For
example, a String value cannot be inserted/set in a column that has NumberInt as its data type.
Contact Us
If you have difficulty using the driver, please contact our Technical Support staff. We welcome
your questions, comments, and feature requests.
Technical Support is available Monday to Friday from 8 a.m. to 5 p.m. Pacific Time.
Important: To help us assist you, prior to contacting Technical Support please prepare a detailed
summary of the client and server environment including operating system version, patch level
and configuration.
You can contact Technical Support via:
•
E-mail: [email protected]
•
Web site: www.simba.com
•
Telephone: (604) 633-0008 Extension 3
•
Fax: (604) 633-0004
You can also follow us on Twitter @SimbaTech
www.simba.com
32
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Appendix: Driver Configuration Options
You can configure options using the following:
•
Data Source Name
•
Database connection string
Table 2 lists the configuration options available in Simba ODBC Driver with SQL Connector for
MongoDB alphabetically by field or button label. Options that do not appear in the user interface
of the driver are listed alphabetically by key name at the end of the table.
When creating or configuring a DSN connection from a Windows machine, the fields and buttons
described in Table 2 are available in the following dialog boxes:
•
The Simba MongoDB ODBC Driver DSN Setup dialog box
•
The Advanced Options dialog box
•
The Schema Definition dialog box
•
The Virtual Table Options dialog box
When using a connection string or configuring a connection from a Linux or Mac OS X machine,
use the key names provided in Table 2.
Field or Button Label
(Key Name)
Additional servers
(SecondaryServers)
Check GetLastError on writes
(CheckGetLastError)
www.simba.com
Default
Value
Description
A comma-separated list of additional
servers that you need to use when
connecting to a sharded cluster or a
replica set. You can indicate the port on
which a server is listening by appending
a colon (:) and the port number to the
server name or IP address.
Selected (1) When this option is enabled (1), the
driver calls the MongoDB
CheckGetLastError() function after each
INSERT or UPDATE operation to check
for reported failures.
Calling CheckGetLastError() typically
takes four times longer than the INSERT
or UPDATE operation, but it is necessary
if fault tolerance is important.
33
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Description
Connect to a replica set
(UseReplicaSet)
0
When this option is enabled (1), the
driver is able to access replica sets in
your MongoDB implementation.
When this option is disabled (0), the
driver does not access replica sets.
Container
(DefaultContainerColumnLength)
511
The default column length for containers
(arrays and objects) in MongoDB.
DocumentAsJSON
(DefaultJSONColumnLength)
1023
The default column length for
documentAsJSON fields.
See also the Enable reading/writing as
JSON document driver configuration
option.
Documents fetched per block
(RowsFetchedPerBlock)
4096
The maximum number of documents
(rows) that a query returns at a time.
Documents to sample
(SchemaDetectSampleSize)
100
The number of documents to sample
when detecting schema for a table.
If you set the value to 0, then the driver
scans all documents.
Enable reading/writing as JSON
document
(UseJSONColumn)
Clear (0)
When this option is enabled (1), the
driver reports a special column named
documentAsJSON that retrieves or stores
whole documents as JSON-formatted
strings.
Note: Only enable this option as needed.
The process of converting documents
into JSON strings decreases the
performance of the driver.
See also the DocumentAsJSON driver
configuration option.
Enable updating multiple rows
(UpdateMultipleRows)
Selected (1) When this option is enabled (1), UPDATE
statements update all rows that match
the filters.
When this option is disabled (0), UPDATE
statements update the first matching
row only.
www.simba.com
34
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Enable virtual table detection
(VirtualTableDetection)
Default
Value
Description
Selected (1) When this option is enabled (1), the
driver generates metadata for virtual
tables.
When this option is disabled (0), the
driver does not generate metadata for
virtual tables.
Export All Tables
(ExportSchemaMapTo)
The full path to a Schema Database
Definition (SDD) file that you want to
export metadata to.
Important: Including the key in a
connection string exports the metadata
to the specified file. After exporting the
metadata, remove the key from the
connection string.
Hide real table if virtual tables created
(VTHideRealTables)
Selected (1) When this option is enabled (1), if virtual
tables have been created, then the real
table is hidden.
When this option is disabled (0), both
types of tables are displayed.
Local file
(LocalMetadataFile)
Clear
The path to a local SDD file from which
to load metadata. The metadata in the
file must be in a predefined JSON
format.
If you do not provide a value, then the
driver loads metadata from the
collection in the database named
Mersenne_Collection_Metadata
Nested column separator
(NestedColumnSeparator)
__ (two
underscore
characters)
The character or string to use to separate
the names of nested columns (for
embedded documents and arrays).
Note: It is assumed that the separator is
not used in column names. By default,
MongoDB uses a period (.) as the
separator.
www.simba.com
35
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Description
Omit default NULL columns on insert
(OmitColumns)
Selected (1) When this option is enabled (1), no null
values (whether explicitly provided or
not) are written to the columns of a
table.
When this option is disabled (0),
explicitly provided null values are
written to columns as specified, but no
default null value is inserted.
Note: This option affects INSERT
operations only.
Read preference
(ReadPreference)
primary
Replica set name
(ReplicaSetName)
Sampling strategy
(SchemaDetectSampleStrategy)
www.simba.com
Specify how the driver routes read
operations to the members of a replica
set. The following values are possible:
• primary
• primaryPreferred
• secondary
• secondaryPreferred
• nearest
For more information, see “Replication”
in the MongoDB Manual at
http://docs.mongodb.org/manual/replicat
ion/
The name of the replica set for the driver
to access.
Note: This option is available only if the
Connect to a replica set option is
enabled (the UseReplicaSet key is set to
1).
End
The location in the table to sample rows
from when detecting schema. The
following values are possible:
• Start
• End
• Random
36
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Description
Show array counts in virtual main table
(VTMainTableShowArrayCounts)
Clear (0)
When this option is enabled (1), the
array count column appears in the main
virtual table.
When this option is disabled (0), the
column does not appear.
Show container columns when
generating metadata
(SchemaDetectShowContainerColumns)
Clear (0)
When this option is enabled (1),
documents and arrays appear as columns
in JSON format in the real table.
When this option is disabled (0),
documents and arrays do not appear as
columns in the real table.
Note: This option does not affect virtual
tables.
Standard
(DefaultStringColumnLength)
255
The default column length for String
columns. MongoDB does not provide the
length for String columns in its column
metadata. The option allows you to tune
the length of String columns.
Truncate documents larger than 16MB
(TruncateDocument)
Clear (0)
When this option is enabled (1), the
driver truncates any document that is
greater than 16MB in size.
When this option is disabled (0), the
driver rejects any document that is
greater than 16MB in size.
Update Metadata
(ImportSchemaMapFrom)
Use SQL_WVARCHAR for string data
types
(UseSqlWVarchar)
www.simba.com
The full path to a Schema Database
Definition (SDD) file from which to
import metadata.
Important: Including the key in a
connection string imports the specified
SDD file. After importing the desired
SDD file, remove the key from the
connection string.
Clear (0)
When this option is enabled (1), the
MongoDB String type is mapped to
SQL_WVARCHAR instead of
SQL_VARCHAR.
When this option is (0), the String type is
mapped to SQL_VARCHAR.
37
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Username
(UID)
Description
The login credential to use when
accessing the MongoDB database.
Validate BSON before writes
(ValidateBsonBeforeWrite)
Selected (1) By default, MongoDB does not validate
BSON objects before INSERT or UPDATE
operations, which can result in a
corrupted database. When this option is
enabled (1), the driver validates all
content prior to passing the content to
the database server.
When this option is disabled (0), the
driver does not validate BSON objects.
Virtual key column separator
(VTKeyColumnSeparator)
. (a period
character)
The separator for generated column
names in a virtual table.
The name of a key column in a virtual
table uses the following format:
OriginalTable<VTKeyColumnSeparator>_i
d
For example, OriginalTable._id
Virtual main table name suffix
(VTMainTableNameSuffix)
main
The suffix for naming the main virtual
table.
The name of a virtual main table uses
the following format:
OriginalTable<VTTableNameSeparator><
VTMainTableNameSuffix>
For example, OriginalTable_vt_main
Virtual table array count prefix
(VTArrayCountPrefix)
Number of
The prefix for naming a generated array
count column in a virtual table.
The name of an array count column in a
virtual table uses the following format:
<VTArrayCountPrefix>ArrayColumnName
For example, Number of
ArrayColumnName
www.simba.com
38
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Description
Virtual table index column suffix
(VTIndexColSuffix)
index
The suffix for naming generated columns
in a virtual table that indicate the
position/index of an element into an
array.
The name of an array index column
name uses the following format:
ArrayColumnName<VTTableNameSeparat
or><VTIndexColSuffix>
For example,
ArrayColumnName_vt_index
Virtual table name separator
(VTTableNameSeparator)
_vt_
The separator for naming a virtual table
built from an array column.
The name of a virtual table uses the
following format:
OriginalTable<VTTableNameSeparator>
ArrayColumnName
For example,
OriginalTable_vt_ArrayColumnName
N/A
(ArrayColumnMax)
5
The number of array columns to
generate when detecting schema for a
table.
www.simba.com
39
Installation and Configuration Guide
Simba ODBC Driver with SQL Connector for MongoDB
Field or Button Label
(Key Name)
Default
Value
Description
N/A
(CacheMetadata)
1
Simba ODBC Driver with SQL Connector
for MongoDB dynamically detects the
database schema as needed in the
process of connecting to a MongoDB
database. By default, the driver stores
the metadata for reuse. When you
disable metadata caching by setting the
CacheMetadata key to 0, the driver
regenerates the metadata every time the
driver accesses the database.
If you disable metadata caching, then
the driver continues to save schema
definitions that you set using the
Schema Definition dialog box. For
information about using the Schema
Definition dialog box, see Defining a
Schema for the Driver to Use on page
13.
Important: Caching metadata is useful
when defining the schema for your
MongoDB database. After the schema is
defined, disable metadata caching in
your production environment.
N/A
(DefaultBinaryColumnLength)
32767
The default column length for Binary
columns.
N/A
(VTInsertUpdateSafeMode)
0
VTInsertUpdateSafeMode is no longer
used.
Table 2 Advanced Configuration Options
www.simba.com
40