Simba HBase ODBC Driver with SQL Connector User Guide · HBase currently does not support...

Simba HBase ODBC Driver with SQL Connector

User Guide

Last Revised: April 2, 2013

Simba Technologies Inc.

Simba HBase ODBC Driver with SQL Connector User Guide

www.simba.com i

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

Contact Us

Simba Technologies Inc. 938 West 8th Avenue Vancouver, BC Canada V5Z 1E5

www.simba.com

Telephone +1 (604) 633-0008 sales: extension 2, 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

mailto:[email protected]


www.simba.com ii

Table of Contents Introduction ........................................................................................................................................................1

Contact Us ...........................................................................................................................................................1

Windows Driver ..................................................................................................................................................2 System requirements .................................................................................................................................2 Installation .....................................................................................................................................................2 Configuration ...............................................................................................................................................5 Schema definition .......................................................................................................................................9

Features ............................................................................................................................................................. 10 SQL Connector ........................................................................................................................................... 10 Data Types ................................................................................................................................................... 10 Authentication .......................................................................................................................................... 11 Catalog Support ........................................................................................................................................ 11 Retrieving Multiple Versions of Data ................................................................................................ 11 Filtering for Data within a Time Range ............................................................................................ 13 Improvements when using the “KEY” Column ............................................................................... 13

Third Party Trademarks ................................................................................................................................ 14


www.simba.com 1

Introduction The Simba HBase ODBC Driver enables Business Intelligence (BI), analytics and reporting on data that is stored in HBase databases. It complies with the ODBC 3.52 data standard and adds important functionality such as Unicode and 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 3.52 specification, see the MSDN ODBC Programmer's Reference, available from the Microsoft web site at http://msdn.microsoft.com/en-us/library/ms714562(VS.85).aspx

Contact Us If you have difficulty using Simba HBase ODBC Driver with SQL Connector, please contact our support staff. We welcome your questions, comments, and feature requests. Please have a detailed summary of the client and server environment (OS version, patch-level, HBase distribution version, configuration etc.) ready, before you call or write to us. Supplying this information accelerates support.

By telephone:

Call (604) 633-0008 and press 3

Customer Support is available Monday – Friday, from 8 a.m. until 5 p.m. Pacific Time.

By fax or e-mail:

Fax (604) 633-0004

Send e-mail to [email protected]

On the Internet:

Visit us at www.simba.com.

Follow us on Twitter: @simbatech

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

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

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

mailto:[email protected]

http://www.simba.com/


www.simba.com 2

Windows Driver System requirements

• Windows® XP with SP3, Windows® Vista, Windows® 7 Professional or Windows® 2008 R2. Both 32-bit and 64-bit editions are supported.

• 25 MB of available disk space.

Installing the driver requires administrator privileges.

Installation There are two versions of the driver for Windows:

• SimbaHBaseODBC32.msi for 32-bit editions of Windows

• SimbaHBaseODBC64.msi for 64-bit editions of Windows

The version of the driver that you select should match the bitness of the application. For example, if the application is 64-bit then you should install the 64-bit driver. It is allowable to install both versions of the driver.

The following document explains how to use ODBC on 64-bit editions of Windows: http://www.simba.com/docs/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf.

To install the driver: 1. Double-click the appropriate MSI file.

The Simba HBase ODBC Driver Setup window opens.

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


www.simba.com 3

2. Click Next. The End-User License Agreement page is displayed.

3. Select the "I accept the terms in the License Agreement" checkbox and then, click Next. The Destination Folder page is displayed.


www.simba.com 4

4. Click Next. The Ready to install Simba HBase ODBC Driver page is displayed.

5. Click Install.

6. When the Windows User Account Control window appears, click Yes. When the installation is finished, the Completed the Simba HBase ODBC Driver Setup Wizard page is displayed.

7. Click Finish. The Simba HBase ODBC Driver installation is complete. The next step is to create a Data Source Name.


www.simba.com 5

Configuration

Create a Data Source Name (DSN) 1. Click the Start button .

2. Click All Programs.

3. Click the Simba HBase ODBC Connector 1.0 (64-bit) or the Simba HBase ODBC Connector 1.0 (32-bit) program group. If you installed both versions of the driver, you will see two program groups.

Because DSNs are bit-specific, select the version that matches the bitness of your application. For example, a DSN that is defined for the 32-bit driver will only be accessible from 32-bit applications.

4. Click 64-bit ODBC Driver Manager or 32-bit ODBC Driver Manager. The ODBC Data Source Administrator window opens.


www.simba.com 6

5. Click the Drivers tab and verify that the Simba HBase ODBC Driver is displayed in the list of ODBC drivers that are installed on your system.

6. Click the System DSN tab to create a system DSN or click the User DSN tab to create a user DSN. Note: A system DSN can be seen by all users that login to a workstation. A user DSN is specific to a user on the workstation. It can only be seen by the user who creates it.

7. Click Add. The Create New Data Source window opens.


www.simba.com 7

8. Select Simba HBase ODBC Driver and then click Finish. The Simba HBase ODBC Connector Setup window opens.

9. In the Data Source Name text box, type a name for your DSN.

10. Optionally, in the Description text box, enter a description.

11. In the Host text box, type the name or IP address of the host that your HBase instance is running on.

12. In the Port text box, type the port that your HBase instance is using.

13. Optionally, click Advanced Options. The advanced options are described in more detail in the section, Advanced options.

14. Optionally, click Schema Definition. Schema definition is described in more detail in the section, Schema definition.

15. Optionally, click Test to test connecting the driver with the current driver configuration. The Test Results window opens showing the result of the test.

16. Click OK to finish the configuration and close the Simba HBase ODBC Driver Setup window.

17. Click OK to close the ODBC Data Source Administrator window.


www.simba.com 8

Advanced options

The advanced configuration settings can be set any of the following ways:

• with the Simba HBase ODBC Driver Setup wizard

• with the database connection string

• with registry settings

The following advanced configuration settings are available:

Option Name Default Value

Description

Rows per fetch 65536 The number of rows fetched per request.

Default max column size

255 The default string column length to use. HBase does not provide the length for string columns in its column metadata. This option allows you to tune the length of String columns.

Schema definition row limit

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

Set advanced options using the Simba HBase ODBC Driver Setup wizard 1. Follow the steps described in the section Create a Data Source Name (DSN).

2. Click Advanced Options. The Advanced Options window opens.

3. Type new values in the text boxes and then click OK.

Set advanced options using the database connection string

An example of a connection string that sets advanced options is as follows:

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


www.simba.com 9

Note: Connection string settings override registry settings.

Schema definition 1. Follow the steps described in the section Create a Data Source Name (DSN).

2. Click Schema Definition. The Schema Definition window opens.

3. In the Table Name drop-down menu, select a table to work with.

4. The Columns pane displays the name and data type of the columns in the table. The data type is inferred from a sample of the rows that is taken from the table. To change the sample size, in the rows text box, type a number of rows and then click Sample.

5. To change the data type for a column, click on the data type for the column and select a new data type from the list. The Data Preview pane will be updated to reflect the change. If a sample data value cannot be represented with the selected data type, the Data Preview pane will display a conversion error message instead of the data value

6. The Data Preview pane displays a preview of the data that is contained in the table.

7. Click OK.

The schema data is stored in a collection called “SIMBA_METATABLE”, and if needed this collection can be copied to other HBase instances to copy the schema definitions to that instance. Note that removing this collection will also remove any schema definitions that have been saved.


www.simba.com 10

Features SQL Connector

To allow applications to use normal SQL queries against HBase, we have added the SQL Connector feature to translate 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 The following data types are supported:

o HB_ASCII o HB_BINARY o HB_BIT o HB_F32B o HB_F32L o HB_F64B o HB_F64L o HB_FILETIME o HB_SI8 o HB_SI16B o HB_SI16L o HB_SI32B o HB_SI32L o HB_SI64B o HB_SI64L o HB_SYSTEMTIME o HB_UI8 o HB_UI16B o HB_UI16L o HB_UI32B o HB_UI32L o HB_UI64B o HB_UI64L o HB_UT32B o HB_UT32L o HB_UT64B o HB_UT64L o HB_UTF8


www.simba.com 11

o HB_UTF16 o HB_UMT64B o HB_UMT64L o HB_UUT64B o HB_UUT64L

The following types are not yet supported:

o HB_GUID

Authentication HBase currently does not support authentication in the typical manner of a user login. There is no mechanism to pass in a user context (such as a user/password/token). Data security models are still under active development so this will change in the future. As a workaround, you will need to use the features available in your application to implement access control.

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

Retrieving Multiple Versions of Data The Simba HBase ODBC Driver allows for retrieving multiple versions of the same data. The driver provides a 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.

When this attribute is set with a value greater than 1, the driver will show 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, the older versions are set to NULL.


www.simba.com 12

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

{

"row" : {

"family1" : {

"val1" : {

15 : "val1Latest",

4 : "val1Oldest"

},

"val2" : {

15 : "val2Latest",

}

},

"family2" : {

"val3" : {

15 : "val3Latest"

1 : "val3Oldest"

}

}

}

}

Query the data through the Simba HBase ODBC Driver with the default HB_ATTR_MAX_VERSION value of one will return the following result set:

family1:val1 family1:val2 family2:val3

val1Latest val2Latest val3Latest

Setting HB_ATTR_MAX_VERSION to a value of three and repeating the query will return 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 columns will be named such that the current version of the data will be in the column without a “_#” suffix. Columns will then be added with a suffix of “_<distance to most recent version>”, so that the second most recent value will be 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.


www.simba.com 13

The following is an example of how to set HB_ATTR_MAX_VERSION via code:

SQLINTEGER value = 2;

SQLSetStmtAttr(stmt, HB_ATTR_MAX_VERSION, value, SQL_IS_INTEGER);

Alternatively, if HB_ATTR_MAX_VERSION is not defined, the following could be used:

SQLINTEGER value = 2;

SQLSetStmtAttr(stmt, 40000, value, SQL_IS_INTEGER);

Filtering for Data within a Time Range The Simba HBase ODBC Driver allows for filtering data that falls within a range of timestamps. The driver provides two SQLCHAR statement properties HB_ATTR_STARTTIME_STR, with an identifier of 40001, and HB_ATTR_ENDTIME_STR, with an identifier of 40002.

These attributes take in NUL-terminated strings which are convertible to 64-bit integers and represent the start and end timestamps to filter on (inclusive). The timestamps represent Unix time, or the number of milliseconds since January 1st, 1970 UTC. Data that falls outside of this range is not returned. These attributes can be set to NULL to indicate that there is no upper or lower bound on the data timestamp.

The default value for both properties is NULL to allow for all data to be returned.

An example value for one of the properties would be “1000”, which would represent one second after January 1st, 1970 UTC.

The following is an example of how to set either HM_ATTR_STARTTIME_STR or HM_ATTR_ENDTIME_STR via code:

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

Alternatively, if the property identifiers are not defined, the following could be used:

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

Improvements when using the “KEY” Column The Simba HBase ODBC Driver has enhancements when using the “KEY” column as a filter in queries. Performance is faster when filtering on this column.

Additionally, the driver supports suffix globbing when using the “KEY” column as a filter. This allows for use of wildcards in the filter. For example, using the filter “foo*” would return key values including “foo”, “foobar”, “foo1”, etc.


www.simba.com 14

Third Party Trademarks 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.

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


www.simba.com 15

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

Simba HBase ODBC Driver with SQL Connector User Guide · HBase currently does not support...

Documents

Transcript of Simba HBase ODBC Driver with SQL Connector User Guide · HBase currently does not support...