Simba ODBC Driver with SQL Connector for HBase ... · Simba ODBC Driver with SQL Connector for HBase Installation and Configuration Guide 5 . PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

Simba ODBC Driver with SQL Connector

for HBase

Installation and Configuration Guide

September 12, 2014

Simba Technologies Inc.

Simba ODBC Driver with SQL Connector for HBase Installation and Configuration Guide

www. s imba .com 2

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.

OpenSSL

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


www. s imba .com 3

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.

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


www. s imba .com 4

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.

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.

Protocol Buffers

Copyright 2008, Google Inc.


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


www. s imba .com 5

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.

Code generated by the Protocol Buffer compiler is owned by the owner of the input file used when generating it. This code is not standalone and requires a support library to be linked with it. This support library is itself covered by the above license.

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

http://www.simba.com/

mailto:[email protected]



www. s imba .com 6

Table of Contents Introduction ........................................................................................................................................................7

Windows Driver ..................................................................................................................................................7 System Requirements ................................................................................................................................7 Installing the Driver ...................................................................................................................................7 Creating a Data Source Name ................................................................................................................8 Configuring Logging Options .................................................................................................................9 Configuring Advanced Options ........................................................................................................... 10 Defining the Schema .............................................................................................................................. 11

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

Mac OS X Driver .............................................................................................................................................. 14 System Requirements ............................................................................................................................. 14 Installing the Driver ................................................................................................................................ 15

Configuring ODBC Connections for Linux and Mac OS X ............................................................... 15 Files ............................................................................................................................................................... 15 Sample Files ................................................................................................................................................ 16 Configuring the Environment .............................................................................................................. 16 Configuring the odbc.ini File ............................................................................................................... 17 Configuring the odbcinst.ini File ........................................................................................................ 18 Configuring the simba.hbaseodbc.ini File ....................................................................................... 19

Features ............................................................................................................................................................. 19 SQL Connector ........................................................................................................................................... 19 Data Types ................................................................................................................................................... 19 Authentication .......................................................................................................................................... 21 Catalog Support ........................................................................................................................................ 22 Retrieving Multiple Versions of Data ................................................................................................ 22 Filtering for Data within a Time Range ............................................................................................ 23 Improvements when using the KEY Column .................................................................................. 24

Contact Us ........................................................................................................................................................ 25


www. s imba .com 7

Introduction The Simba ODBC Driver with SQL Connector for HBase enables Business Intelligence (BI), analytics, and reporting on data that is stored in HBase databases. The driver complies with the ODBC 3.52 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 on the ODBC specification, see the ODBC API Reference at http://msdn.microsoft.com/en-us/library/windows/desktop/ms714562(v=vs.85).aspx

Windows Driver System Requirements

You install Simba ODBC Driver with SQL Connector for HBase on client computers accessing data in HBase 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):

• Windows® XP with SP3

• Windows® Vista

• Windows® 7 Professional

• Windows® Server 2008 R2

• 25 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 HBase databases:

• SimbaHBaseODBC32.msi for 32-bit applications

• SimbaHBaseODBC64.msi for 64-bit applications

You can install both versions of the driver on the same computer.

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

http://msdn.microsoft.com/en-us/library/windows/desktop/ms714562(v=vs.85).aspx


www. s imba .com 8

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 HBase:

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

Creating a Data Source Name After installing Simba ODBC Driver with SQL Connector for HBase, 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 HBase ODBC Driver 1.0 program group corresponding to the bitness of the client application accessing data in HBase databases, and then click ODBC Administrator

2. In the ODBC Data Source Administrator, click the Drivers tab, and then scroll down as needed to confirm that Simba HBase ODBC Driver appears in the alphabetical list of driver names.

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 the Add button.

5. In the Create New Data Source dialog box, select Simba HBase ODBC Driver, and then click Finish

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

a. In the Data Source Name field, type a name for the data source.

b. In the Description field, type relevant details about the DSN.

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


www. s imba .com 9

c. In the Host field, type the name or IP address of the host where the HBase instance runs.

d. In the Port field, type the number of the port that the HBase instance uses.

e. To configure logging options, click the Logging Options button. For details, see Configuring Logging Options on page 9.

f. To configure advanced driver options, click the Advanced Options button. For details, see Configuring Advanced Options on page 10.

g. If you need to customize the schema that Simba ODBC Driver with SQL Connector for HBase detects for an HBase database, then click the Schema Definition button. For details, Defining the Schema on page 11.

7. To confirm that the DSN connects to your HBase database, click the Test button. Review the Test Results dialog box as needed, and then click OK

8. In the Simba HBase ODBC Driver DSN Setup dialog box, click OK

9. In the ODBC Data Source Administrator dialog box, click OK

Configuring Logging Options Simba ODBC Driver with SQL Connector for HBase provides logging options so you can troubleshoot the driver.

Important: Enabling logging slows driver performance and uses disk space. Enable logging only when troubleshooting the driver. Logging settings that you configure affect all DSNs using the driver. Logging settings for the 32-bit driver do not affect the 64-bit driver, and logging settings for the 64-bit driver do not affect the 32-bit driver.

Table 1 lists the available configuration settings for logging.

Name Default Value Description

Log Level LOG_OFF Controls the level of logging. The following values are possible, in order from least verbose to most verbose:

• LOG_FATAL

• LOG_ERROR

• LOG_WARNING

• LOG_INFO

• LOG_DEBUG

• LOG_TRACE

Log Path The directory where log files are created.


www. s imba .com 10

Name Default Value Description

Log Namespace The base namespace prefix filter used to reduce the log entries. For example, a value of “Simba” would allow “Simba::SQLEngine” but not “HBase::SQLEngine”.

Table 1 Logging Configuration Settings

To enable logging:

1. In the ODBC Data Source Administrator where you created a DSN using the driver you want to troubleshoot, click 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 Logging Options button.

3. In the Log Level list, select the appropriate level of logging.

4. In the Log Path field, type the absolute path to the folder in which to save log files.

Important: Ensure that this folder already exists.

5. In the Log Namespace field, type an appropriate filter for log entries.

6. Click OK

7. In the Simba HBase ODBC Driver DSN Setup dialog box, click OK.

8. In the ODBC Data Source Administrator, click OK.

Configuring Advanced Options Table 2 lists the advanced configuration settings available in Simba ODBC Driver with SQL Connector for HBase.

Name (Key)

Default Value Description

Maximum Rows Per Fetch (MaxFetchRows)

4096 The largest number of rows that a query returns per request.

Schema Definition Row Limit (Sdrl)

1024 The number of rows inspected when attempting to infer the columns and data types in a table.

Table 2 Advanced Configuration Options


www. s imba .com 11

You can configure advanced configuration settings by using the following:

• Data Source Name

• Database connection string

Using the Data Source Name

To set advanced options using the Simba HBase ODBC Driver Setup dialog box:

1. In the ODBC Data Source Administrator where you created the DSN, click 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 Advanced Options button.

3. In the Max Rows Per Fetch field, type an appropriate value.

4. In the Schema Definition Row Limit field, type an appropriate value.

5. Click OK

6. In the Simba HBase ODBC Driver DSN Setup dialog box, click OK

Using a Database Connection String

The following is an example connection string that sets advanced options:

DSN=Sample Simba HBase DSN; Host=192.168.100.100; Port=27017; MaxFetchRows=65536; Sdrl=128

Defining the Schema Simba ODBC Driver with SQL Connector for HBase dynamically detects the database schema as needed in the process of connecting to an HBase database. You can also edit the schema that the driver uses to connect to the database manually.

To define manually the schema to use when Simba ODBC Driver with SQL Connector for HBase connects to the database:


2. Click the Configure button, and then click the Schema Definition button.

3. In the Schema Definition dialog box, in the Table Name list, select the table for which you want to edit the schema.

4. To change the number of rows in the table that the driver samples to detect columns and corresponding data types, type a number in the Rows field, and then click the Sample button. In the confirmation dialog, click OK


www. s imba .com 12

5. To change the data type for a column, in the Columns area, click the Type field for the column, and then select the appropriate data type. The Data Preview pane updates to reflect your change.

6. Repeat steps 3 to 5 as needed to define the schema.

7. When you are finished defining the schema, click OK, and then click Yes when prompted to write metadata to the database.

OR

To discard changes, click the Cancel button, and then click OK when prompted to discard changes.

Schema data is stored in a collection called SIMBA_METATABLE. As needed, you can copy the collection to other HBase instances to duplicate the schema definition.

Note: Deleting the SIMBA_METATABLE collection deletes the schema definition you defined.

Linux Driver System Requirements

Each computer where you install the driver must meet the following minimum system requirements:

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

• Red Hat® Enterprise Linux® (RHEL) 5.0/6.0

• CentOS 5.0/6.0

• SUSE Linux Enterprise Server (SLES) 11

• 45 MB of available disk space.

• An installed ODBC driver manager:

• iODBC 3.52.7 or above

OR

• unixODBC 2.2.12 or above

Installing the Driver Using the RPM There are two versions of the driver for Linux:

• SimbaHBaseODBC-Version-Release.Platform.i686.rpm for 32-bit • SimbaHBaseODBC-Version-Release.Platform.x86_64.rpm for 64-bit


www. s imba .com 13

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

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

• /opt/simba/hbaseodbc/ErrorMessages—Error messages files directory

• /opt/simba/hbaseodbc/Setup—Sample configuration files directory

• /opt/simba/hbaseodbc/lib/32—32-bit shared libraries directory

• /opt/simba/hbaseodbc/lib/64—64-bit shared libraries directory


1. In Red Hat Enterprise Linux 5.0/6.0 or CentOS 5.0/6.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:

zypper install RPMFileName

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

Installing the Driver Using the Tarball Package Alternatively, the Simba ODBC Driver with SQL Connector for HBase is available for installation using a TAR.GZ tarball package. The tarball package includes the following:

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

• [INSTALL_DIR]/simba/hbaseodbc/lib/32 contains the 32-bit Simba ODBC Driver with SQL Connector for HBase for Linux.


www. s imba .com 14

• [INSTALL_DIR]/simba/hbaseodbc/lib/64 contains the 64-bit Simba ODBC Driver with SQL Connector for HBase for Linux.

• [INSTALL_DIR]/simba/hbaseodbc/ErrorMessages contains error message files that are required by the Simba ODBC Driver with SQL Connector for HBase.

• [INSTALL_DIR]/simba/hbaseodbc/Setup contains configuration files named odbc.ini, odbcinst.ini, and simba.hbaseodbc.ini

Setting the LD_LIBRARY_PATH Environment Variable The LD_LIBRARY_PATH environment variable must include the paths to the following:

• Installed ODBC driver manager libraries

• Installed Simba ODBC Driver with SQL Connector for HBase shared libraries

Important: While you can have both 32- and 64-bit versions of the driver installed at the same time on the same computer, do not include the paths to both 32- and 64-bit shared libraries in LD_LIBRARY PATH at the same time. Only include the path to the shared libraries corresponding to the driver matching the bitness of the client application used.

For example, if you are using a 64-bit client application and ODBC driver manager libraries are installed in /usr/local/lib, then set LD_LIBRARY_PATH as follows, where InstallDir is /opt if you installed the driver using the RPM or your installation directory if you installed the driver using the tarball:

export LD_LIBRARY_PATH=/usr/local/lib:InstallDir/simba/hbaseodbc/ lib/64

Refer to your Linux shell documentation for details on how to set environment variables permanently.

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


www. s imba .com 15

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

• /opt/simba/hbaseodbc/ErrorMessages—Error messages files directory

• /opt/simba/hbaseodbc/Setup—Sample configuration files directory

• /opt/simba/hbaseodbc/lib/universal—Binaries directory


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

2. Double-click SimbaHBaseODBC.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/hbaseodbc/lib/universal folder.

Setting the DYLD_LIBRARY_PATH Environment Variable The DYLD_LIBRARY_PATH environment variable must include the paths to the following:

• Installed ODBC driver manager libraries

• Installed Simba ODBC Driver with SQL Connector for HBase shared 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:/opt/simba/hbaseodbc/lib/ universal

Refer to your Mac OS X shell documentation for details on how to set environment variables permanently.

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)


www. s imba .com 16

• .simba.hbaseodbc.ini—The file used to configure Simba ODBC Driver with SQL Connector for HBase (required)

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

• odbc.ini

• odbcinst.ini

• simba.hbaseodbc.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 (.). For simba.hbaseodbc.ini, the filename must begin with a period (.) and must reside in the user’s home directory.

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 The odbc.ini, odbcinst.ini, and simba.hbaseodbc.ini configuration files reside in the user’s home directory by default, but you can use three environment variables—ODBCINI, ODBCSYSINI, and SIMBAINI—to specify different locations for the 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 SIMBAINI to point to your simba.hbaseodbc.ini file.

For example, if your odbc.ini and simba.hbaseodbc.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 SIMBAINI=/etc/simba.hbaseodbc.ini

The search order for the simba.hbaseodbc.ini file is as follows:

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

Important: SIMBAINI must specify the full path, including the filename.

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

3. The directory ~/ (i.e. $HOME) is searched for a hidden file named .simba.hbaseodbc.ini


www. s imba .com 17

4. The directory /etc is searched for a file named simba.hbaseodbc.ini not beginning with a period.

Configuring the odbc.ini File

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.

Here is an example odbc.ini configuration file for Linux:

[ODBC Data Sources]

Sample Simba HBase DSN 32=Simba HBase ODBC Driver 32-bit

[Sample Simba HBase DSN 32]

Driver=/opt/simba/hbaseodbc/lib/32/libsimbahbaseodbc32.so

HOST=MyHBaseServer

PORT=10000

Here is an example odbc.ini configuration file for Mac OS X:

[ODBC Data Sources]

Sample Simba HBase DSN=Simba HBase ODBC Driver

[Sample Simba HBase DSN]

Driver=/opt/simba/hbaseodbc/lib/universal/libsimbahbaseodbc.dylib

HOST=MyHBaseServer

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. Save the .odbc.ini configuration file.


www. s imba .com 18

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

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.

Here is an example odbcinst.ini file for Linux:

[ODBC Drivers]

Simba HBase ODBC Driver 32-bit=Installed

Simba HBase ODBC Driver 64-bit=Installed

[Simba HBase ODBC Driver 32-bit]

Description=Simba HBase ODBC Driver (32-bit)


[Simba HBase ODBC Driver 64-bit]

Description=Simba HBase ODBC Driver (64-bit)


Here is an example odbcinst.ini file for Mac OS X:

[ODBC Drivers]

Simba HBase ODBC Driver=Installed

[Simba HBase ODBC Driver]

Description=Simba HBase ODBC Driver

Driver=/opt/simba/hbaseodbc/lib/universal/libsimbahbaseodbc.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 HBase in the Setup directory. Specify configuration options as key-value pairs.

4. Save the .odbcinst.ini configuration file.


www. s imba .com 19

Configuring the simba.hbaseodbc.ini File To configure Simba ODBC Driver with SQL Connector for HBase to work with your ODBC driver manager:

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

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.hbaseodbc.ini configuration file.

Features SQL Connector

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

Data Types HBase stores data in raw binary streams. Therefore, data can be stored in a variety of formats. Simba ODBC Driver with SQL Connector for HBase supports many common data formats, converting the raw binary data into ODBC SQL types based on the data type selected for each column.

Table 3 lists supported data type mappings.

Simba HBase Type SQL Type Description

HB_ASCII SQL_VARCHAR Text encoded in ASCII

HB_BINARY SQL_VARBINARY Raw binary data

HB_BIT SQL_BIT 1 byte zero (false)/one (true)


www. s imba .com 20


HB_F32B SQL_REAL IEEE-754 single-precision 4 bytes big endian

HB_F32L SQL_REAL IEEE-754 single-precision 4 bytes little endian

HB_F64B SQL_DOUBLE IEEE-754 double-precision 8 bytes big endian

HB_F64L SQL_DOUBLE IEEE-754 double-precision 8 bytes little endian

HB_FILETIME SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of 100ns since 1601-01-01 00:00:00 little endian (Windows FILETIME equivalent)

HB_SI8 SQL_TINYINT 8-bit/1 byte signed integer

HB_SI16B SQL_SMALLINT 16-bit/2 bytes signed integer big endian

HB_SI16L SQL_SMALLINT 16-bit/2 bytes signed integer little endian

HB_SI32B SQL_INTEGER 32-bit/4 bytes signed integer big endian

HB_SI32L SQL_INTEGER 32-bit/4 bytes signed integer little endian

HB_SI64B SQL_BIGINT 64-bit/8 bytes signed integer big endian

HB_SI64L SQL_BIGINT 64-bit/8 bytes signed integer little endian

HB_SYSTEMTIME SQL_TYPE_TIMESTAMP

Serialized Windows SYSTEMTIME structure

HB_UI8 SQL_TINYINT 8-bit/1 byte unsigned integer

HB_UI16B SQL_SMALLINT 16-bit/2 bytes unsigned integer big endian

HB_UI16L SQL_SMALLINT 16-bit/2 bytes unsigned integer little endian

HB_UI32B SQL_INTEGER 32-bit/4 bytes unsigned integer big endian

HB_UI32L SQL_INTEGER 32-bit/4 bytes unsigned integer little endian

HB_UI64B SQL_BIGINT 64-bit/8 bytes unsigned integer big endian

HB_UI64L SQL_BIGINT 64-bit/8 bytes unsigned integer little endian

HB_UT32B SQL_TYPE_TIMESTAMP

32-bit/4 bytes signed integer number of seconds since 1970-01-01 00:00:00 big endian (valid to 2038)

HB_UT32L SQL_TYPE_TIMESTAMP

32-bit/4 bytes signed integer number of seconds since 1970-01-01 00:00:00 little endian (valid to 2038)

HB_UT64B SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of seconds since 1970-01-01 00:00:00 big endian

HB_UT64L SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of seconds since 1970-01-01 00:00:00 little endian


www. s imba .com 21


HB_UTF8 SQL_WVARCHAR Text encoded as UTF-8

HB_UTF16 SQL_WVARCHAR Text encoded as UTF-16

HB_UMT64B SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of milliseconds since 1970-01-01 00:00:00 big endian

HB_UMT64L SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of milliseconds since 1970-01-01 00:00:00 little endian

HB_UUT64B SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of microseconds since 1970-01-01 00:00:00 big endian

HB_UUT64L SQL_TYPE_TIMESTAMP

64-bit/8 bytes signed integer number of microseconds since 1970-01-01 00:00:00 little endian

Table 3 Supported Data Types

Note: The HB_GUID data type is not yet supported.

Authentication If your HBase deployment supports HTTPS, then Simba ODBC Driver with SQL Connector for HBase provides HTTPS basic authentication.

To configure basic authentication in Windows:


2. Click the Configure button.

3. In the Simba Hbase ODBC Driver DSN Setup dialog box, in the Authentication Type list, select Basic Authentication

4. In the User and Password fields, type the user’s credentials.

5. Click OK

6. In the ODBC Data Source Administrator, click OK.

To configure basic authentication in Linux or Mac OS X:

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


www. s imba .com 22

2. Set the AUTHTYPE parameter to 1

3. Type in the username for the UID parameter.

4. Type in the password for the PWD parameter.

5. Save and close the file.

Here is an example of the .odbc.ini configuration file:

AUTHTYPE=1 UID=HBaseUserID PWD=HBasePassword

Catalog Support Simba ODBC Driver with SQL Connector for HBase does not support schemas and catalogs, as there is no logical mapping yet. A default catalog named “HBASE” is provided in order to make it easy for the driver to work with various ODBC applications.

Retrieving Multiple Versions of Data Simba ODBC Driver with SQL Connector for HBase allows you to retrieve multiple versions of the same data. The driver provides the SQLINTEGER statement attribute HB_ATTR_MAX_VERSION, with an identifier of 40000, to specify the number of versions of each column to retrieve. The default number of versions to return is one, which means that every new statement created will only return a single version unless HB_ATTR_MAX_VERSION is set.

If HB_ATTR_MAX_VERSION is set with a value greater than 1, then the driver shows extra columns for each version available up to the requested HB_ATTR_MAX_VERSION value. If there are fewer versions of the data than what is requested for a row, then the older versions are set to NULL.

As an example, consider the following raw data in JSON format using arbitrary integer timestamps:

{"row": {"family1": {"val1": {4: "val1Oldest", 15: "val1Latest"}, "val2": {15: "val2Latest"}}, "family2": {"val3": {1: "val3Oldest", 15: "val3Latest"}}}}

Querying the data using Simba ODBC Driver with SQL Connector for HBase with the default HB_ATTR_MAX_VERSION value of 1 returns the following result set:

family1:val1 family1:val2 family2:val3

val1Latest val2Latest val3Latest


www. s imba .com 23

Setting HB_ATTR_MAX_VERSION to a value of 3 and repeating the query returns the following result set:

family1:val1 family1:val1_1 family1:val2 family1:val2_1 family2:val3 family2:val3_1

val1Latest val1Oldest val2Latest <null> val3Latest val3Oldest

The name of the column having the current version of the data has no “_#” suffix. Columns are named with the suffix “_<distance to most recent version>” so that the second most recent value is in the “_1” column, the third most recent in the “_2” column, and so on. If there is no value for the version of a column, then a null value is returned.

Setting a Driver Attribute

The following example shows how to set the HB_ATTR_MAX_VERSION attribute using the SQLSetStmtAttr function included in the ODBC API, where stmt is an SQL statement handle and value is the number of versions of each column to retrieve:

SQLINTEGER value = 2;

SQLSetStmtAttr(stmt, HB_ATTR_MAX_VERSION, value, SQL_IS_INTEGER);

Alternatively, for example if HB_ATTR_MAX_VERSION is not defined, then you can use the identifier of the attribute instead of the name:

SQLINTEGER value = 2;

SQLSetStmtAttr(stmt, 40000, value, SQL_IS_INTEGER);

For more details, see the section “SQLSetStmtAttr Function” in the ODBC API Reference at http://msdn.microsoft.com/en-us/library/ms712631(v=vs.85).aspx

Filtering for Data within a Time Range Simba ODBC Driver with SQL Connector for HBase allows you to filter data that falls within a range of timestamps. The driver provides two SQLCHAR statement properties: one named HB_ATTR_STARTTIME_STR having an identifier of 40001, and the other named HB_ATTR_ENDTIME_STR having an identifier of 40002.

The attributes take in NUL-terminated strings that are convertible to 64-bit integers representing the start and end timestamps, inclusive, on which to filter. The timestamps represent UNIX time—the number of milliseconds since January 1st, 1970 UTC. Data that falls outside the specified range is not returned. Setting the attributes to NULL specifies no upper or lower bound on the data timestamp.

The default value for both properties is NULL.

For example, using a value of 1000 specifies one second after January 1st, 1970 UTC.

The following ODBC statement sets the end timestamp of the range to return to two seconds after January 1st, 1970 UTC, where stmt is an SQL statement handle:

SQLSetStmtAttr(stmt, HB_ATTR_ENDTIME_STR, "2000", SQL_IS_INTEGER);

http://msdn.microsoft.com/en-us/library/ms712631(v=vs.85).aspx


www. s imba .com 24

Alternatively, you can use the identifier for the attribute:

SQLSetStmtAttr(stmt, 40002, "2000", SQL_IS_INTEGER);

Improvements when using the KEY Column Simba ODBC Driver with SQL Connector for HBase has enhancements when using the KEY column as a filter in queries. Performance is faster when filtering on the KEY column.

The driver also supports suffix globbing when using the KEY column as a filter, allowing you to use wildcards in the filter. For example, using the filter “foo*” would return key values including “foo”, “foobar” and “foo1”.


www. s imba .com 25

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, HBase distribution version and system 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


http://www.simba.com/

Documents

Simba ODBC Driver with SQL Connector for HBase ... · Simba ODBC Driver with SQL Connector for HBase Installation and Configuration Guide 5 . PROFITS; OR BUSINESS INTERRUPTION) HOWEVER