Simba ODBC Driver with SQL Connector for Google …...Simba ODBC Driver with SQL Connector for Google BigQuery Installation and Configuration Guide May 12, 2015 Simba Technologies

Simba ODBC Driver with SQL Connector

for Google BigQuery

Installation and Configuration Guide

May 12, 2015

Simba Technologies Inc.

Simba ODBC Driver with SQL Connector for Google BigQuery Installation and Configuration Guide

Copyright ©2012-2015 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-2014 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.

OpenSSL

Copyright (c) 1998-2011 The OpenSSL Project. All rights reserved.

www.simba.com 2


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

www.simba.com 3


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.

Stringencoders License

Copyright 2005, 2006, 2007

Nick Galbreath -- nickg [at] modp [dot] com


Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

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.

Neither the name of the modp.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS 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 COPYRIGHT OWNER OR 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.

This is the standard "new" BSD license:

http://www.opensource.org/licenses/bsd-license.php

dtoa License

The author of this software is David M. Gay.

Copyright (c) 1991, 2000, 2001 by Lucent Technologies.

www.simba.com 4


Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

rapidjson

Copyright (c) 2011 Milo Yip

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.

libcurl

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2012, Daniel Stenberg, <[email protected]>.


Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

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

www.simba.com 5


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.

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

www.simba.com 6

http://www.simba.com/

mailto:[email protected]



Table of Contents Introduction ........................................................................................................................................................8

Windows Driver ..................................................................................................................................................8 System Requirements ................................................................................................................................8 Installing the Driver ...................................................................................................................................8 Creating a Data Source Name (DSN) ....................................................................................................9 Configuring Advanced Options ........................................................................................................... 11 Configuring Logging Options .............................................................................................................. 12

Linux Driver ...................................................................................................................................................... 14 System Requirements ............................................................................................................................. 14 Installing the Driver Using the RPM .................................................................................................. 14 Installing the Driver Using the Tarball Package ............................................................................ 15 Setting the LD_LIBRARY_PATH Environment Variable ............................................................... 16

Mac OS X Driver .............................................................................................................................................. 16 System Requirements ............................................................................................................................. 16 Installing the Driver ................................................................................................................................ 16

Configuring ODBC Connections for Linux and Mac OS X ............................................................... 17 Files ............................................................................................................................................................... 17 Sample Files ................................................................................................................................................ 18 Configuring the Environment .............................................................................................................. 18 Configuring the odbc.ini File ............................................................................................................... 19 Configuring the odbcinst.ini File ........................................................................................................ 20 Configuring the simba.bigqueryodbc.ini File ................................................................................. 21

Features ............................................................................................................................................................. 23 SQL Connector ........................................................................................................................................... 23 Data Types ................................................................................................................................................... 23 Nested and Repeated Records ............................................................................................................. 23 Authentication .......................................................................................................................................... 24 Catalog Support ........................................................................................................................................ 24 Large Result Set Support ....................................................................................................................... 24

Driver Configuration Options .................................................................................................................... 25

Contact Us ........................................................................................................................................................ 29

www.simba.com 7


Introduction The Simba ODBC Driver with SQL Connector for Google BigQuery enables Business Intelligence (BI), analytics, and reporting on data uploaded to Google Storage. The driver complies with the ODBC 3.80 data standard and adds important functionality such as Unicode, as well as 32- and 64-bit support for high-performance computing environments on all platforms.

ODBC is one 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 about the ODBC 3.80 specification, see the ODBC API Reference at http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

Windows Driver

System Requirements You install the Simba ODBC Driver with SQL Connector for Google BigQuery on client computers accessing data in BigQuery. 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® XP with SP3

o Windows® Vista

o Windows® 7 Professional

o Windows® Server 2008 R2

• 72 MB of available disk space

Important: To install the driver, you need Administrator privileges on the computer.

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 data in BigQuery:

• SimbaBigQueryODBC32.msi for 32-bit applications

• SimbaBigQueryODBC64.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

www.simba.com 8

http://www.simba.com/odbc.htm

http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf


To install the Simba ODBC Driver with SQL Connector for Google BigQuery:

1. Depending on the bitness of your client application, double-click to run SimbaBigQueryODBC32.msi or SimbaBigQueryODBC64.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 Change, 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 you selected in step 4.

Creating a Data Source Name (DSN) After installing the Simba ODBC Driver with SQL Connector for Google BigQuery, you need to create a Data Source Name (DSN).

To create a Data Source Name (DSN):

1. Click the Start button , then click All Programs, then click the Simba BigQuery ODBC Driver 1.1 program group corresponding to the bitness of the client application accessing data in BigQuery, and then click ODBC Administrator

2. In the ODBC Data Source Administrator, click the Drivers tab and verify that the Simba BigQuery ODBC Driver appears in the list of ODBC drivers that are installed on your system.

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 BigQuery ODBC Driver and then click Finish

6. Use the options in the Simba BigQuery ODBC Driver DSN Setup dialog box to configure your DSN:

a. In the Data Source Name field, type a name for your DSN.

b. Optionally, in the Description field, type relevant details about the DSN.

www.simba.com 9


c. To provide the DSN with the necessary credentials for accessing your BigQuery data, click the Sign In button and then do the following:

i. In the browser that opens, type your credentials for accessing your BigQuery data, and then click Sign in

ii. When prompted to allow BigQuery Client Tools to access your data in Google BigQuery, click Accept

iii. Copy the code that Google provides, and then paste the code in the Confirmation Code field in the Simba BigQuery ODBC Driver DSN Setup dialog box.

When you paste the confirmation code, the Refresh Token field populates automatically. The refresh token is used whenever the driver needs to access your BigQuery data.

d. Optionally, to connect to a proxy server, select the Use Proxy Server check box and then do the following:

i. In the Proxy Host field, type the IP address or hostname of the proxy server.

ii. In the Proxy Port field, type the number of the port on which the proxy server is listening.

iii. In the Proxy Username field, type the user name that you use to access the proxy server.

iv. In the Proxy Password field, type the password corresponding to the user name that you provided in step iii.

e. In the Catalog (Project) list, select the name of your BigQuery project.

Note: If you are not signed in to your Google account, then you are prompted to sign in.

f. In the Billed Project list, select the name of the project to bill for queries that are run using the DSN.

g. To configure advanced driver options, click Advanced Options. For more information, see “Configuring Advanced Options” on page 11.

h. To configure logging behavior for the driver, click Logging Options. For more information, see “Configuring Logging Options” on page 12.

7. To test the connection, click Test. Review the Test Result dialog box as needed, and then click OK

8. To save your settings and close the Simba BigQuery ODBC Driver DSN Setup dialog box, click OK

9. To close the ODBC Data Source Administrator, click OK

www.simba.com 10


Configuring Advanced Options You can configure advanced driver settings by using the following:

• Data Source Name

• Database connection string

For information about the configuration options available in the Simba ODBC Driver with SQL Connector for Google BigQuery, see “Driver Configuration Options” on page 25.

Using the Data Source Name

To set advanced options using the Simba BigQuery ODBC 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 the Configure button, and then click Advanced Options

3. In the Rows Fetched Per Block field, type the maximum number of rows to fetch for each data request.

4. In the Max Requests Per Second field, type the maximum number of requests that can be made per second.

Note: To allow an unlimited number of requests per second with no throttling, type 0

5. In the Default String Column Length field, type the maximum data length for STRING columns.

6. To disable the SQL Connector feature and allow the driver to execute BigQuery SQL directly, select the Use Native Query check box.

7. To enable the driver to retrieve metadata during the prepare stage of a query when working in Native Query mode, select the Enable SQLPrepare Metadata with Native Query check box.

Note: This option is available only if the Use Native Query check box is selected.

8. To allow query results that are larger than 128MB in size, select the Allow Large Result Sets check box and then do the following:

a. In the Dataset Name For Large Result Sets field, type the ID of the BigQuery dataset to use to store temporary tables.

Note: The dataset created from the default ID is hidden.

b. In the Temporary Table Expiration Time field, type the length of time (in milliseconds) for which a temporary table exists.

9. To save your settings and close the Advanced Options dialog box, click OK

10. To close the Simba BigQuery ODBC Driver DSN Setup dialog box, click OK

www.simba.com 11


Using a Database Connection String

Configuration options that are passed in using a connection string take precedence over configuration options that are set in the DSN.

The following is an example connection string that sets advanced options: DSN=Sample Simba BigQuery DSN; Catalog=public_data; MaxRequestsPerSecond=20; UseNativeQuery=0; AllowLargeResults=0; LargeResultsDataSetId=_bqodbc_temp_tables; LargeResultsTempTableExpirationTime=3600000

For more information about the configuration options available in Simba ODBC Driver with SQL Connector for Google BigQuery, see “Driver Configuration Options” on page 25.

Configuring Logging Options To help troubleshoot issues, you can enable logging. In addition to functionality provided in the Simba ODBC Driver with SQL Connector for Google BigQuery, 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. Table 1 lists the logging levels provided by the Simba ODBC Driver with SQL Connector for Google BigQuery, in order from least verbose to most verbose.

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 Google BigQuery Logging Levels

www.simba.com 12


To enable the logging functionality available in the Simba ODBC Driver with SQL Connector for Google BigQuery:

1. In the Simba BigQuery 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.

OR

Click Browse and select the folder where you want to save log files.

4. In the Max Number Files field, type the maximum number of log files to keep.

Note: After the maximum number of log files is reached, each time an additional file is created, the driver deletes the oldest log file.

5. In the Max File Size field, type the maximum size of each log file in megabytes (MB).

Note: After the maximum file size is reached, the driver creates a new file and continues logging.

6. Click OK

The Simba ODBC Driver with SQL Connector for Google BigQuery produces a log file named BigQueryODBC_driver.log at the location you specify using the Log Directory field.

To disable Simba ODBC Driver with SQL Connector for Google BigQuery logging:

1. In the Simba BigQuery 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

www.simba.com 13

http://support.microsoft.com/kb/274551


Linux Driver


• One of the following distributions (32- and 64-bit editions are supported):

o Red Hat® Enterprise Linux® (RHEL) 5.0 or 6.0

o CentOS 5.0 or 6.0

o SUSE Linux Enterprise Server (SLES) 11


• One of the following ODBC driver managers installed:

o iODBC 3.52.7 or above

o unixODBC 2.2.12 or above

Installing the Driver Using the RPM You can install the driver using RPMs. There are two versions of the driver for Linux:

• SimbaBigQueryODBC-32bit-Version-Release.LinuxDistro.i686.rpm for the 32-bit driver • SimbaBigQueryODBC-Version-Release.LinuxDistro.x86_64.rpm for the 64-bit driver

Version is the version number of the driver, and Release is the release number for this version of the driver. LinuxDistro is either el5 or el6. For SUSE, the LinuxDistro placeholder is empty.

The version of the driver that you select should match the bitness of the client application accessing your Google BigQuery 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.

Important: Ensure that you install the driver using the RPM corresponding to your Linux distribution.

The Simba ODBC Driver with SQL Connector for Google BigQuery driver files are installed in the following directories:

• /opt/simba/bigqueryodbc contains release notes, the Simba ODBC Driver with SQL Connector for Google BigQuery Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• /opt/simba/bigqueryodbc/ErrorMessages contains error message files required by the driver.

www.simba.com 14


• /opt/simba/bigqueryodbc/Setup contains configuration files named odbc.ini and odbcinst.ini

• /opt/simba/bigqueryodbc/Tools contains the Refresh Token configuration tool.

• /opt/simba/bigqueryodbc/lib/32 contains the 32-bit driver and the simba.bigqueryodbc.ini configuration file.

• /opt/simba/bigqueryodbc/lib/64 contains the 64-bit driver and the simba.bigqueryodbc.ini configuration file.


1. In Red Hat Enterprise Linux or CentOS, 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, 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: zypper install RPMFileName

2. If you received a license file via e-mail, then copy the license file into the /opt/simba/bigqueryodbc/lib/32 or /opt/simba/bigqueryodbc/lib/64 folder, depending on the version of the driver that you installed.

Note: To avoid security issues, you may need to save the license file on your local computer prior to copying the file into the folder.

Installing the Driver Using the Tarball Package Alternatively, the Simba ODBC Driver with SQL Connector for Google BigQuery is available for installation using a TAR.GZ tarball package. The tarball package includes the following, where INSTALL_DIR is your chosen installation directory:

• INSTALL_DIR/simba/bigqueryodbc/ contains release notes, the Simba ODBC Driver with SQL Connector for Google BigQuery Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• INSTALL_DIR/simba/bigqueryodbc/lib/32 contains the 32-bit driver and the simba.bigqueryodbc.ini configuration file.

• INSTALL_DIR/simba/bigqueryodbc/lib/64 contains the 64-bit driver and the simba.bigqueryodbc.ini configuration file.

• INSTALL_DIR/simba/bigqueryodbc/ErrorMessages contains error message files that are required by the driver.

www.simba.com 15


• INSTALL_DIR/simba/bigqueryodbc/Setup contains configuration files named odbc.ini and odbcinst.ini

• INSTALL_DIR/simba/bigqueryodbc/Tools contains the Refresh Token configuration tool.

Setting the LD_LIBRARY_PATH Environment Variable The LD_LIBRARY_PATH environment variable must include the paths to the 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 the Simba ODBC Driver with SQL Connector for Google BigQuery, see “Configuring ODBC Connections for Linux and Mac OS X” on page 17.

Mac OS X Driver


• Mac OS X version 10.6.8 or later


• iODBC 3.52.7 or above

The driver supports both 32- and 64-bit client applications.

Installing the Driver The Simba ODBC Driver with SQL Connector for Google BigQuery driver files are installed in the following directories:

• /opt/simba/bigqueryodbc contains release notes, the Simba ODBC Driver with SQL Connector for Google BigQuery Installation and Configuration Guide in PDF format, and a Readme.txt file that provides plain text installation and configuration instructions.

• /opt/simba/bigqueryodbc/ErrorMessages contains error message files required by the driver.

www.simba.com 16


• /opt/simba/bigqueryodbc/Setup contains configuration files named odbc.ini and odbcinst.ini

• /opt/simba/bigqueryodbc/Tools contains the Refresh Token configuration tool.

• /opt/simba/bigqueryodbc/lib/universal contains the driver and the simba.bigqueryodbc.ini configuration file.


1. Double-click SimbaBigQueryODBC.dmg to mount the disk image.

2. Double-click SimbaBigQueryODBC.pkg to run the installer.

3. In the installer, click Continue

4. On the Software License Agreement screen, click Continue, and when the prompt appears, click Agree if you agree to the terms of the License Agreement.

5. Optionally, to change the installation location, click Change Install Location, select the desired location, and then click Continue

6. To accept the installation location and begin the installation, click Install

7. When the installation completes, click Close

8. If you received a license file via e-mail, then copy the license file into the /opt/simba/bigqueryodbc/lib/universal folder.

Note: To avoid security issues, you may need to save the license file on your local computer prior to copying the file into the folder.

For information about creating ODBC connections using the Simba ODBC Driver with SQL Connector for Google BigQuery, see “Configuring ODBC Connections for Linux and Mac OS X” on page 17.

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 is used to define ODBC data sources, and it is required.

• .odbcinst.ini is used to define ODBC drivers, and it is optional.

Also, by default the Simba ODBC Driver with SQL Connector for Google BigQuery is configured using the simba.bigqueryodbc.ini file, which is located in one of the following directories depending on the version of the driver that you are using:

• /opt/simba/bigqueryodbc/lib/32 for the 32-bit driver on Linux

www.simba.com 17


• /opt/simba/bigqueryodbc/lib/64 for the 64-bit driver on Linux

• /opt/simba/bigqueryodbc/lib/universal for the driver on Mac OS X

The simba.bigqueryodbc.ini file is required.

Sample Files The driver installation contains the following sample configuration files in the Setup directory:

• odbc.ini

• odbcinst.ini

The names of the sample configuration files do not begin with a period (.) so that they will 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 (.).

If the configuration files do not already exist in the user’s home directory, then the sample configuration files can be copied to that directory and renamed. If the configuration files already exist in the user’s home directory, then the sample configuration files should be used as a guide for modifying the existing configuration files.

Configuring the Environment Optionally, you can use three environment variables—ODBCINI, ODBCSYSINI, and SIMBABIGQUERYINI—to specify different locations for the odbc.ini, odbcinst.ini, and simba.bigqueryodbc.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 SIMBABIGQUERYINI to point to your simba.bigqueryodbc.ini file.

For example, if your odbc.ini and simba.bigqueryodbc.ini files are located in/etc and your odbcinst.ini file is located in /usr/local/odbc, then set the environment variables as follows: export ODBCINI=/etc/odbc.ini export ODBCSYSINI=/usr/local/odbc export SIMBABIGQUERYINI=/etc/simba.bigqueryodbc.ini

The following search order is used to locate the simba.bigqueryodbc.ini file:

1. If the SIMBABIGQUERYINI environment variable is defined, then the driver searches for the file specified by the environment variable.

Important: SIMBABIGQUERYINI must contain the full path, including the filename.

2. The directory containing the driver’s binary is searched for a file named simba.bigqueryodbc.ini (not beginning with a period).

www.simba.com 18


3. The current working directory of the application is searched for a file named simba.bigqueryodbc.ini not beginning with a period.

4. The directory ~/ (that is, $HOME) is searched for a hidden file named .simba.bigqueryodbc.ini

5. The directory /etc is searched for a file named simba.bigqueryodbc.ini (not beginning with a period).

Configuring the odbc.ini File ODBC Data Source Names (DSNs) 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 of an odbc.ini configuration file for Linux: [ODBC Data Sources] Sample Simba BigQuery DSN 32=Simba BigQuery ODBC Driver 32-bit [Sample Simba BigQuery DSN 32] Driver=/opt/simba/bigqueryodbc/lib/32/libsimbabigqueryodbc32.so Catalog=public_data RefreshToken=Token

Token is the refresh token that you obtain from Google for authorizing access to BigQuery.

The following is an example of an odbc.ini configuration file for Mac OS X: [ODBC Data Sources] Sample Simba BigQuery DSN=Simba BigQuery ODBC Driver [Sample Simba BigQuery DSN] Driver=/opt/simba/bigqueryodbc/lib/universal/libsimbabigqueryodbc.dylib Catalog=public_data RefreshToken=Token

Token is the refresh token that you obtain from Google for authorizing access to BigQuery.

To create a Data Source Name (DSN):

1. Open the .odbc.ini configuration file in a text editor.

2. In the [ODBC Data Sources] section, add a new entry by typing the Data Source Name (DSN), then an equal sign (=), and then the driver name.

3. In the .odbc.ini file, add a new section with a name that matches the DSN you specified in step 2, and then add configuration options to the section. Specify configuration options as key-value pairs.

www.simba.com 19


4. Configure a refresh token to authorize your connection to BigQuery by doing the following:

a. Open a browser and go to the following website:

https://accounts.google.com/o/oauth2/auth?scope=https://www.googleapis.com/auth/bigquery&response_type=code&redirect_uri=urn:ietf:wg:oauth:2.0:oob&client_id=977385342095.apps.googleusercontent.com&hl=en&from_login=1&as=76356ac9e8ce640b&pli=1&authuser=0

b. Type your credentials for accessing your BigQuery data, and then click Sign in

c. When prompted to allow BigQuery Client Tools to access your data in Google BigQuery, click Accept, and then copy the code that Google provides.

d. To generate the refresh token, on your local computer, browse to the /opt/simba/bigqueryodbc/Tools directory and then run the get_refresh_token.sh shell script, passing in the code that you copied in step c.

e. Copy the refresh token from the output of the script. The refresh token is the text on the right side of the colon with no leading or trailing spaces.

f. In the odbc.ini file, set the RefreshToken key as follows, replacing Token by pasting the refresh token that you copied in step e: RefreshToken=Token

5. Save the .odbc.ini configuration file.

For information about the configuration options available in the Simba ODBC Driver with SQL Connector for Google BigQuery, see “Driver Configuration Options” on page 25.

Configuring the odbcinst.ini File 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 19.

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 of an odbcinst.ini file for Linux: [ODBC Drivers] Simba BigQuery ODBC Driver 32-bit=Installed Simba BigQuery ODBC Driver 64-bit=Installed [Simba BigQuery ODBC Driver 32-bit] Description=Simba BigQuery ODBC Driver (32-bit) Driver=/opt/simba/bigqueryodbc/lib/32/libsimbabigqueryodbc32.so [Simba BigQuery ODBC Driver 64-bit] Description=Simba BigQuery ODBC Driver (64-bit)

www.simba.com 20






Driver=/opt/simba/bigqueryodbc/lib/64/libsimbabigqueryodbc64.so

The following is an example of an odbcinst.ini file for Mac OS X: [ODBC Drivers] Simba BigQuery ODBC Driver=Installed [Simba BigQuery ODBC Driver] Description=Simba BigQuery ODBC Driver Driver=/opt/simba/bigqueryodbc/lib/universal/libsimbabigqueryodbc.dylib

To define a driver:

1. Open the .odbcinst.ini configuration file in a text editor.

2. In the [ODBC Drivers] section, add a new entry by typing the driver name and then typing =Installed

Note: Type a symbolic name that you want to use to refer to the driver in connection strings or DSNs.

3. In the .odbcinst.ini file, add a new section with a name that matches the driver name you typed in step 2, and then add configuration options to the section based on the sample odbcinst.ini file provided in the Setup directory. Specify configuration options as key-value pairs.

4. Save the .odbcinst.ini configuration file.

Configuring the simba.bigqueryodbc.ini File Driver settings are defined in the simba.bigqueryodbc.ini configuration file. The settings in this file apply to all connections that use the Simba ODBC Driver with SQL Connector for Google BigQuery.

You do not need to modify the settings in the simba.bigqueryodbc.ini file in order to use the driver and connect to your data source. However, to help troubleshoot issues, you can configure the simba.bigqueryodbc.ini file to enable logging in the driver.

Important: Only enable logging long enough to capture an issue. Logging decreases performance and can consume a large quantity of disk space.

Use the LogLevel key to set the amount of detail included in log files. Table 2 lists the logging levels provided by the Simba ODBC Driver with SQL Connector for Google BigQuery, in order from least verbose to most verbose.

LogLevel value Description

0 Disables all logging.

1 Logs very severe error events that will lead the driver to abort.

2 Logs error events that might still allow the driver to continue running.

www.simba.com 21


LogLevel value Description

3 Logs potentially harmful situations.

4 Logs general information that describes the progress of the driver.

5 Logs detailed information that is useful for debugging the driver.

6 Logs more detailed information than LogLevel=5

Table 2 Simba ODBC Driver with SQL Connector for Google BigQuery Logging Levels

To enable logging:

1. Open the simba.bigqueryodbc.ini configuration file in a text editor.

2. Set the LogLevel key to the desired level of information to include in log files. For example:

LogLevel=2

3. Set the LogPath key to the full path to the folder where you want to save log files. For example:

LogPath=/localhome/employee/Documents

4. Set the LogFileCount key to the maximum number of log files to keep.

Note: After the maximum number of log files is reached, each time an additional file is created, the driver deletes the oldest log file.

5. Set the LogFileSize key to the maximum size of each log file in megabytes (MB).

Note: After the maximum file size is reached, the driver creates a new file and continues logging.

6. Save the simba.bigqueryodbc.ini configuration file.

The Simba ODBC Driver with SQL Connector for Google BigQuery produces a log file named BigQueryODBC_driver.log at the location you specify using the LogPath key.

To disable logging:

1. Open the simba.bigqueryodbc.ini configuration file in a text editor.

2. Set the LogLevel key to 0

3. Save the simba.bigqueryodbc.ini configuration file.

www.simba.com 22


Features

SQL Connector The SQL Connector feature of the driver allows applications to use normal SQL queries against BigQuery, translating standard SQL-92 queries into equivalent BigQuery SQL calls. The SQL Connector allows standard queries that BI tools execute to run against your BigQuery instance.

Data Types The Simba ODBC Driver with SQL Connector for Google BigQuery supports many common data formats, converting between BigQuery data types and SQL data types.

Table 3 lists the supported data type mappings.

BigQuery Data Type SQL Data Type

Boolean SQL_BIT

Integer SQL_BIGINT

Float SQL_DOUBLE

String SQL_VARCHAR

Timestamp SQL_TYPE_TIMESTAMP

Table 3 Supported Data Types

Nested and Repeated Records The Simba ODBC Driver with SQL Connector for Google BigQuery fully supports nested and repeated records, with the nested fields being exposed as columns in period (.) notation. For example, consider the following record represented in JSON: {"address": [{"city": "Vancouver", "years": 5}, {"city": "Seattle", "years": 2}], "name": "Simba"}

The driver identifies the following columns for the record:

• address.city

• address.years

• name

To refer to the columns in a SQL query, you need to surround the column names with quotation marks (") because the column names contain the period (.) separator: SELECT "address.city", "address.years", name FROM Contacts

www.simba.com 23


Authentication The Sign In feature in the Simba BigQuery ODBC Driver DSN Setup dialog box uses the OAuth 2.0 protocol for authentication and authorization. The confirmation code that you receive is a temporary code that allows you to obtain a refresh token. The refresh token is transmitted with every API call that the driver makes.

For more information about OAuth 2.0, see Using OAuth 2.0 to Access Google APIs at https://developers.google.com/accounts/docs/OAuth2

Catalog Support The Simba ODBC Driver with SQL Connector for Google BigQuery supports both catalogs and schemas. Projects are mapped to catalogs. Table datasets are mapped to schemas. The mapping is intuitive, allowing the driver to work easily with various ODBC applications.

Large Result Set Support The Simba ODBC Driver with SQL Connector for Google BigQuery supports the allowLargeResults option in BigQuery job configurations to enable result sets greater than 128MB (compressed). If the Allow Large Result Sets driver option is enabled, then the driver creates temporary tables under a user-definable dataset ID to store large query results. Temporary tables exist for a user-definable interval of time (in milliseconds) before they are deleted.

For more information about large result sets and the limitations of enabling this option, see Queries at https://developers.google.com/bigquery/quota-policy and Returning large query results at https://developers.google.com/bigquery/querying-data

www.simba.com 24

https://developers.google.com/accounts/docs/OAuth2

https://developers.google.com/bigquery/quota-policy

https://developers.google.com/bigquery/querying-data


Driver Configuration Options Table 4 lists the configuration options available in the Simba ODBC Driver with SQL Connector for Google BigQuery alphabetically by field or button label.

When creating or configuring a connection from a Windows machine, the fields and buttons described in Table 4 are available in the Simba BigQuery ODBC Driver DSN Setup dialog box and the Advanced 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 4.

Note: You can pass in configuration options in your connection string or set them in your odbc.ini and simba.bigqueryodbc.ini files. Configuration options set in a simba.bigqueryodbc.ini file apply to all connections, whereas configuration options passed in using the connection string or set in an odbc.ini file are specific to a connection. Configuration options passed in using the connection string take precedence over configuration options set in odbc.ini. Configuration options set in odbc.ini take precedence over configuration options set in simba.bigqueryodbc.ini

Field or Button Label (Key Name)

Default Value Description

Allow Large Result Sets (AllowLargeResults)

Clear (0) When this option is enabled (1), the driver allows query results that are larger than 128MB in size. When this option is disabled (0), the driver returns an error when query results are larger than 128MB in size. (Optional)

Billed Project (ExecCatalog)

None The name of the project to bill for queries that are run using the DSN. (Required)

Catalog (Project) (Catalog)

None The name of your BigQuery project. (Required)

Confirmation Code (N/A)

None The code that you obtain from Google for generating a refresh token. (Required)

www.simba.com 25




Dataset Name For Large Result Sets (LargeResultDataSetId)

_odbc_temp_tables The ID of the BigQuery dataset to use to store temporary tables. Note: This option is available only when the Allow Large Result Sets option is enabled (the AllowLargeResults key is set to 1). The dataset created from the default ID is hidden. (Required if Allow Large Result Sets is enabled)

Default String Column Length (DefaultStringColumnLength)

65535 The maximum data length for STRING columns. (Optional)

Enable SQLPrepare Metadata with Native Query (UseNativeQueryMetadata)

Selected (1) When this option is enabled (1), the driver retrieves metadata during the prepare stage of a query when working in Native Query mode. When this option is disabled (0), the driver does not retrieve metadata during the prepare stage. Note: This option is available only when the Use Native Query option is enabled (the UseNativeQuery key is set to 1). (Optional)

Max Requests Per Second (MaxRequestsPerSecond)

5 The maximum number of requests that can be made per second. To allow an unlimited number of requests per second with no throttling, set the value to 0 (Optional)

Proxy Host (ProxyHost)

None The IP address or host name of the proxy server. If this key is not set for the Linux or Mac OS X driver, then support for connecting to proxy servers is disabled. (Optional)

www.simba.com 26




Proxy Password (ProxyPwd)

None The password corresponding to the user name provided in the Proxy Username field (the ProxyUid key). (Required if connecting to a proxy server)

Proxy Port (ProxyPort)

None The number of the port on which the proxy server is listening. (Required if connecting to a proxy server)

Proxy Username (ProxyUid)

None The user name that you use to access the proxy server. (Required if connecting to a proxy server)

Refresh Token (RefreshToken)

None The refresh token that you obtain from Google for authorizing access to BigQuery. When you configure a DSN with the Windows driver, the refresh token is generated automatically after you provide the confirmation code. When you configure a DSN with the Linux or Mac OS X versions of the driver, you must use the Refresh Token configuration tool to generate the token. For more information, see Configuring the odbc.ini File on page 19. (Required)

Rows Fetched Per Block (RowsFetchedPerBlock)

16384 The maximum number of rows that the driver can fetch for each data request. (Optional)

Temporary Table Expiration Time (LargeResultsTempTable ExpirationTime)

3600000 The length of time (in milliseconds) for which a temporary table exists. Note: This option is available only when the Allow Large Result Sets option is enabled (the AllowLargeResults key is set to 1). The default value is 1 hour in milliseconds. (Required if Allow Large Result Sets is enabled)

www.simba.com 27




Use Native Query (UseNativeQuery)

Clear (0) When this option is enabled (1), the driver does not transform the queries emitted by an application, so the native query is used. When this option is disabled (0), the driver transforms the queries emitted by an application and converts them into an equivalent form in BigQuery SQL. Note: If an application already emits BigQuery SQL, then enable this option to avoid the extra overhead of query transformation. (Optional)

Table 4 Driver Configuration Options

www.simba.com 28


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 29


http://www.simba.com/