SimbaAmazonDynamoDBODBC DriverwithSQLConnector ... · Introduction TheSimbaAmazonDynamoDBODBCDriverwithSQLConnectorenablesBusiness Intelligence(BI),analytics,andreportingondatathatisstoredinDynamoDBdatabases

Simba Amazon DynamoDB ODBCDriver with SQL Connector

Installation and ConfigurationGuide

Simba Technologies Inc.

September 23, 2015

Copyright © 2015 Simba Technologies Inc. All Rights Reserved.

Information in this document is subject to change without notice. Companies, names anddata used in examples herein are fictitious unless otherwise noted. No part of thispublication, or the software it describes, may be reproduced, transmitted, transcribed,stored in a retrieval system, decompiled, disassembled, reverse-engineered, or translatedinto any language in any form by any means for any purpose without the express writtenpermission of Simba Technologies Inc.

Trademarks

Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLibare registered trademarks of Simba Technologies Inc. All other trademarks and/orservicemarks are the property of their respective owners.

Amazon DynamoDB, Amazon, and DynamoDB are trademarks or registered trademarksof Amazon Web Services, Inc. or its subsidiaries in the Canada, United States and/orother countries. All other trademarks are trademarks of their respective owners.

Contact Us

Simba Technologies Inc.938 West 8th AvenueVancouver, BC CanadaV5Z 1E5

Tel: +1 (604) 633-0008

Fax: +1 (604) 633-0004

www.simba.com

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 thissoftware and associated documentation files (the "Software"), to deal in the Softwarewithout 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 theSoftware is furnished to do so, provided that the above copyright notice(s) and thispermission notice appear in all copies of the Software and that both the above copyrightnotice(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 OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

www.simba.com 2

Simba Amazon DynamoDB ODBC Driverwith SQL Connector Installation and Configuration Guide

http://www.simba.com/

NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THECOPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FORANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, ORANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA ORPROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHERTORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE ORPERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used inadvertising or otherwise to promote the sale, use or other dealings in this Software withoutprior written authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of theirrespective owners.

OpenSSL

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

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

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

2. Redistributions in binary form must reproduce the above copyright notice, this list ofconditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution.

3. All advertising materials mentioning features or use of this software must display thefollowing acknowledgment:

"This product includes software developed by the OpenSSL Project for use in theOpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorseor promote products derived from this software without prior written permission. Forwritten 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 OpenSSLProject.

6. Redistributions of any form whatsoever must retain the following acknowledgment:

"This product includes software developed by the OpenSSL Project for use in theOpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT "AS IS" AND ANYEXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITSCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED

www.simba.com 3


http://www.openssl.org/

http://www.openssl.org/

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ONANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, ORTORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OFTHE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCHDAMAGE.

Original SSLeay License

Copyright (C) 1995-1998 Eric Young ([email protected])


This package is an SSL implementation written by Eric Young ([email protected]). Theimplementation was written so as to conform with Netscapes SSL.

This library is free for commercial and non-commercial use as long as the followingconditions are aheared to. The following conditions apply to all code found in thisdistribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSLdocumentation included with this distribution is covered by the same copyright termsexcept that the holder is Tim Hudson ([email protected]).

Copyright remains Eric Young's, and as such any Copyright notices in the code are not tobe removed. If this package is used in a product, Eric Young should be given attribution asthe author of the parts of the library used. This can be in the form of a textual message atprogram startup or in documentation (online or textual) provided with the package.


1. Redistributions of source code must retain the copyright notice, this list of conditionsand the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list ofconditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution.

3. All advertising materials mentioning features or use of this software must display thefollowing acknowledgement:

"This product includes cryptographic software written by Eric Young([email protected])"

The word 'cryptographic' can be left out if the rouines from the library being used arenot cryptographic related :-).

4. If you include any Windows specific code (or a derivative thereof) from the appsdirectory (application code) you must include an acknowledgement:

"This product includes software written by Tim Hudson ([email protected])"

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS ORIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

www.simba.com 4


WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR ORCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITEDTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ONANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, ORTORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OFTHE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCHDAMAGE.

The licence and distribution terms for any publically available version or derivative of thiscode cannot be changed. i.e. this code cannot simply be copied and put under anotherdistribution licence [including the GNU Public Licence.]

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 thissoftware and associated documentation files (the "Software"), to deal in the Softwarewithout 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 towhom 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 orsubstantial 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 OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ANDNOINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHTHOLDERS 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 OTHERDEALINGS IN THE SOFTWARE.

Stringencoders License

Copyright 2005, 2006, 2007

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



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

www.simba.com 5


Redistributions in binary form must reproduce the above copyright notice, this list ofconditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution.

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

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ANDCONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORSBE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, ORCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENTOF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OFLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDINGNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, 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.

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

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS ORIMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENTMAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THEMERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULARPURPOSE.

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization obtaining acopy of the software and accompanying documentation covered by this license (the"Software") to use, reproduce, display, distribute, execute, and transmit the Software, andto prepare derivative works of the Software, and to permit third-parties to whom theSoftware is furnished to do so, all subject to the following:

www.simba.com 6


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

The copyright notices in the Software and this entire statement, including the abovelicense grant, this restriction and the following disclaimer, must be included in all copies ofthe Software, in whole or in part, and all derivative works of the Software, unless suchcopies or derivative works are solely in the form of machine-executable object codegenerated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONEDISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHERLIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUTOF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHERDEALINGS IN THE SOFTWARE.

zlib License

Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler

This software is provided 'as-is', without any express or implied warranty. In no event willthe authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, includingcommercial applications, and to alter it and redistribute it freely, subject to the followingrestrictions:

1. The origin of this software must not be misrepresented; you must not claim that youwrote the original software. If you use this software in a product, an acknowledgmentin the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not bemisrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Jean-loup Gailly Mark Adler

[email protected] [email protected]

rapidjson

Copyright (C) 2015 THL A29 Limited, a Tencent company, and Milo Yip. All rightsreserved.

If you have downloaded a copy of the RapidJSON binary from Tencent, please note thatthe RapidJSON binary is licensed under the MIT License.

If you have downloaded a copy of the RapidJSON source code from Tencent, please notethat RapidJSON source code is licensed under the MIT License, except for the third-partycomponents listed below which are subject to different license terms. Your integration of

www.simba.com 7


mailto:[email protected]


RapidJSON into your own projects may require compliance with the MIT License, as wellas the other licenses applicable to the third-party components included within RapidJSON.

A copy of the MIT License is included in this file.

Other dependencies and licenses:

Open Source Software Licensed Under the BSD License:

The msinttypes r29

Copyright (c) 2006-2013 Alexander Chemeris


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

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

l Redistributions in binary form must reproduce the above copyrightnotice, this list of conditions and the following disclaimer in the doc-umentation and/or other materials provided with the distribution.

l Neither the name of copyright holder nor the names of its contributorsmay be used to endorse or promote products derived from this softwarewithout specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS ANDCONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIEDWARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THEREGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT,INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OFSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, ORPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ONANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICTLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IFADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Open Source Software Licensed Under the JSON License:

json.org

Copyright (c) 2002 JSON.org

All Rights Reserved.

www.simba.com 8


JSON_checker

Copyright (c) 2002 JSON.org

All Rights Reserved.

Terms of the JSON License:

Permission is hereby granted, free of charge, to any person obtaining a copy ofthis software and associated documentation files (the "Software"), to deal inthe Software without restriction, including without limitation the rights to use,copy, modify, merge, publish, distribute, sublicense, and/or sell copies of theSoftware, 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 allcopies or substantial portions of the Software.

The Software shall be used for Good, not Evil.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANYKIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THEWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OFCONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR INCONNECTION WITH THE SOFTWARE OR THE USE OR OTHERDEALINGS IN THE SOFTWARE.

Terms of the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy ofthis software and associated documentation files (the "Software"), to deal inthe Software without restriction, including without limitation the rights to use,copy, modify, merge, publish, distribute, sublicense, and/or sell copies of theSoftware, 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 allcopies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANYKIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THEWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OFCONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN

www.simba.com 9


CONNECTION WITH THE SOFTWARE OR THE USE OR OTHERDEALINGS IN THE SOFTWARE.

libcurl

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1996 - 2015, Daniel Stenberg, [email protected].


Permission to use, copy, modify, and distribute this software for any purpose with orwithout fee is hereby granted, provided that the above copyright notice and this permissionnotice 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 OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE ANDNONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OROTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OROTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWAREOR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used inadvertising or otherwise to promote the sale, use or other dealings in this Software withoutprior written authorization of the copyright holder.

www.simba.com 10



About This Guide

Purpose

The Simba Amazon DynamoDB ODBC Driver with SQL Connector Installation andConfiguration Guide explains how to install and configure the Simba Amazon DynamoDBODBC Driver with SQL Connector on all supported platforms. The guide also providesdetails related to features of the driver.

Audience

The guide is intended for end users of the Simba Amazon DynamoDB ODBC Driver withSQL Connector, as well as administrators and developers integrating the driver.

Knowledge Prerequisites

To use the Simba Amazon DynamoDB ODBC Driver with SQL Connector, the followingknowledge is helpful:

l Familiarity with the platform on which you are using the Simba Amazon DynamoDBODBC Driver with SQL Connector

l Ability to use the data source to which the Simba Amazon DynamoDB ODBC Driverwith SQL Connector is connecting

l An understanding of the role of ODBC technologies and driver managers in con-necting to a data source

l Experience creating and configuring ODBC connectionsl Exposure to SQL

Document Conventions

Italics are used when referring to book and document titles.

Bold is used in procedures for graphical user interface elements that a user clicks and textthat a user types.

Monospace font indicates commands, source code or contents of text files.

Underline is not used.

The pencil icon indicates a short note appended to a paragraph.

The star icon indicates an important comment related to the preceding paragraph.

The thumbs up icon indicates a practical tip or suggestion.

www.simba.com 11


Table of Contents

Introduction 14

Windows Driver 15System Requirements 15Installing the Driver 15Verifying the Version Number 16Creating a Data Source Name 16Configuring Authentication 18Configuring Advanced Options 19Defining a Schema 20Configuring Logging Options 25

Linux Driver 27System Requirements 27Installing the Driver Using the RPM 27Installing the Driver Using the Tarball Package 28Verifying the Version Number 29Setting the LD_LIBRARY_PATH Environment Variable 29

Mac OS X Driver 31System Requirements 31Installing the Driver 31Verifying the Version Number 32Setting the DYLD_LIBRARY_PATH Environment Variable 32

Configuring ODBC Connections for Non-Windows Platforms 33Configuration Files 33Sample Configuration Files 34Configuring the Environment 34Configuring the odbc.ini File 35Configuring the odbcinst.ini File 36Configuring the simba.dynamodbodbc.ini File 37Configuring Authentication 38Defining a Schema 39Configuring Logging Options 41

Features 43SQL Interface 43

www.simba.com 12


C++ Interface 43Data Types 43Schema Definition 43Virtual Tables 44Write-back 47Parallel Scan 49

Contact Us 51

Appendix A Using a Connection String 52DSN Connection String Example 52DSN-less Connection String Examples 52

Appendix B Driver Configuration Options 54Configuration Options Appearing in the User Interface 54Configuration Options Having Only Key Names 61

Appendix C Data Type Mapping and Conversion Rules 63

www.simba.com 13


Introduction

The Simba Amazon DynamoDB ODBC Driver with SQL Connector enables BusinessIntelligence (BI), analytics, and reporting on data that is stored in DynamoDB databaseson AWS or DynamoDB Local. The driver complies with the ODBC 3.80 data standard andadds important functionality such as Unicode, as well as 32- and 64-bit support for high-performance computing environments on all platforms.

ODBC is one of the most established and widely supported APIs for connecting to andworking with databases. At the heart of the technology is the ODBC driver, which connectsan application to the database. For more information about ODBC, seehttp://www.simba.com/resources/data-access-standards-library. For completeinformation about the ODBC specification, see the ODBC API Reference athttp://msdn.microsoft.com/en-us/library/windows/desktop/ms714562(v=vs.85).aspx.

The Simba Amazon DynamoDB ODBC Driver with SQL Connector is available forMicrosoft® Windows®, Linux, and Mac OS X platforms.

The Installation and Configuration Guide is suitable for users who are looking to accessdata residing within DynamoDB from their desktop environment. Application developersmay also find the information helpful. Refer to your application for details on connecting viaODBC.

www.simba.com 14


http://www.simba.com/resources/data-access-standards-library

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

Windows Driver

System Requirements

You install the Simba Amazon DynamoDB ODBC Driver with SQL Connector on clientcomputers accessing data in DynamoDB. Each computer where you install the driver mustmeet the following minimum system requirements:

l One of the following operating systems:o Windows 7 SP1, 8, or 8.1o Windows Server 2008 R2 SP1, 2012, or 2012 R2

l 250 MB of available disk space

To install the driver, you must have Administrator privileges on the computer.

Installing the Driver

On 64-bit Windows operating systems, you can execute 32- and 64-bit applicationstransparently. You must use the version of the driver matching the bitness of the clientapplication accessing data in DynamoDB:

l SimbaDynamoDBODBC32.msi for 32-bit applicationsl SimbaDynamoDBODBC64.msi for 64-bit applications

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

For an explanation of how to use ODBC on 64-bit editions of Windows, seehttp://www.simba.com/wp-content/uploads/2010/10/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf

To install the Simba Amazon DynamoDB ODBC Driver with SQL Connector:1. Depending on the bitness of your client application, double-click to run

SimbaDynamoDBODBC32.msi or SimbaDynamoDBODBC64.msi2. Click Next3. Select the check box to accept the terms of the License Agreement if you agree, and

then click Next4. To change the installation location, click Change, then browse to the desired folder,

and then click OK. To accept the installation location, click Next5. Click Install6. When the installation completes, click Finish7. 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.To avoid security issues, you may need to save the license file on your localcomputer prior to copying the file into the \lib subfolder.

www.simba.com 15


http://www.simba.com/wp-content/uploads/2010/10/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf

http://www.simba.com/wp-content/uploads/2010/10/HOW-TO-32-bit-vs-64-bit-ODBC-Data-Source-Administrator.pdf

Verifying the Version Number

If you need to verify the version of the Simba Amazon DynamoDB ODBC Driver with SQLConnector that is installed on your Windows machine, you can find the version number inthe ODBC Data Source Administrator.

To verify the version number:1. If you are using Windows 7 or earlier, click the Start button , then click All

Programs, then click the Simba DynamoDB ODBC Driver 0.9 program groupcorresponding to the bitness of the client application accessing data in DynamoDB,and then click ODBC Administrator

OR

If you are using Windows 8 or later, on the Start screen, type ODBC administrator,and then click the ODBC Administrator search result corresponding to the bitnessof the client application accessing data in DynamoDB.

2. In the ODBC Data Source Administrator, click the Drivers tab and then find theSimba DynamoDB ODBC Driver in the list of ODBC drivers that are installed on yoursystem. The version number is displayed in the Version column.

Creating a Data Source Name

Typically, after installing the Simba Amazon DynamoDB ODBC Driver with SQLConnector, you need to create a Data Source Name (DSN).

Alternatively, for information about DSN-less connections, see DSN-less ConnectionString Examples on page 52.

To create a Data Source Name:1. If you are using Windows 7 or earlier, click the Start button , then click All

Programs, then click the Simba DynamoDB ODBC Driver 0.9 program groupcorresponding to the bitness of the client application accessing data in DynamoDB,and then click ODBC Administrator

OR

If you are using Windows 8 or later, on the Start screen, type ODBC administrator,and then click the ODBC Administrator search result corresponding to the bitnessof the client application accessing data in DynamoDB.

2. In the ODBC Data Source Administrator, click the Drivers tab, and then scroll downas needed to confirm that the Simba DynamoDB ODBC Driver appears in thealphabetical 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 theUser DSN tab.

ORTo create a DSN that all users who log into Windows can use, click the System DSNtab.

www.simba.com 16


4. Click Add5. In the Create New Data Source dialog box, select Simba DynamoDB ODBC

Driver and then click Finish6. Use the options in the Simba Amazon DynamoDB 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.c) If you are connecting to the DynamoDB service on AWS, then do the

following:i. In the Host field, type or select the URL (the endpoint) for the

DynamoDB service.

After you specify the URL, the Region field in the Authenticationarea is automatically set to an appropriate value.

ii. Ensure that the DynamoDB Local check box is cleared, and then con-figure the options in the Authentication area. For more information, seeConfiguring Authentication on page 18.

OR

If you are connecting to a server on DynamoDB Local, then do the following:i. In the Host field, type the IP address of the server.ii. Select the DynamoDB Local check box.iii. In the Port field, type the number of the port used by the server.

The default port number used by DynamoDB Local is 8000.iv. Specify the database file that you want to connect to by typing the appro-

priate values in the Region field and the Access Key field, and then typean arbitrary value in the Secret Key field.

For information about how the Region, Access Key, and SecretKey values are used in connections to DynamoDB Local, seeDynamoDB Local for Desktop Development in the AWS OfficialBlog located at https://aws.amazon.com/blogs/aws/dynamodb-local-for-desktop-development/

d) To configure advanced driver options, click Advanced Options. For moreinformation, see Configuring Advanced Options on page 19.

e) To define the schema that the driver uses when connecting to the database,click Schema Definition. For more information, see Defining a Schema onpage 20.

f) To configure logging behavior for the driver, click Logging Options. For moreinformation, see Configuring Logging Options on page 25.

7. To test the connection, click Test. Review the results as needed, and then click OK

www.simba.com 17


https://aws.amazon.com/blogs/aws/dynamodb-local-for-desktop-development/


If the connection fails, then confirm that the settings in the Simba AmazonDynamoDB ODBC Driver DSN Setup dialog box are correct. Contact yourDynamoDB server administrator as needed.

8. To save your settings and close the Simba Amazon DynamoDB ODBC Driver DSNSetup dialog box, click OK

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

Configuring Authentication

Connections to DynamoDB require authentication. You must configure the Simba AmazonDynamoDB ODBC Driver with SQL Connector to provide your credentials andauthenticate the connection to the database.

You can authenticate your connection by using one of the following forms of credentials:l Access keys (access key and secret key)l Credentials filel Temporary security credentials (access key, secret key, and session token)

Using Access Keys

You can provide an access key and a secret key in order to authenticate your connection.

To configure authentication using access keys:1. To access authentication options, open the ODBC Data Source Administrator where

you created the DSN, then select the DSN, and then click Configure2. In the Authentication area, ensure that the Region field is set to the AWS region to

which you want to connect.3. Select IAM Credentials4. In the Access Key field, type your access key ID for connecting to the DynamoDB

service.5. In the Secret Key field, type the secret access key corresponding to your access key

ID.6. To save your settings and close the dialog box, click OK

Using a Credentials File

You can provide AWS credentials by using a special credentials file that contains theaccess keys and secret keys of multiple users.

For information about the format of a credentials file, see the section AWSCredentials File Format in the AWS documentation available athttp://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/credentials.html# credentials-file-format

www.simba.com 18


http://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/credentials.html#


To configure authentication using a credentials file:1. To access authentication options, open the ODBC Data Source Administrator where


which you want to connect.3. Select Credential File4. In the File Path field, specify the full path and name of the AWS credentials file that

you want to use. You can manually type the path in the field, or click Browse andthen browse to select the file.

5. In the Profile Name field, type the name of the profile to use from the AWScredentials file.

6. To save your settings and close the dialog box, click OK

Using Temporary Security Credentials

Temporary credentials consist of an access key, a secret key, and a session token, whichare all valid for 1 hour only. Contact your DynamoDB server administrator to request a setof temporary credentials.

To configure authentication using temporary security credentials:1. To access authentication options, open the ODBC Data Source Administrator where


which you want to connect.3. Select IAM Credentials4. In the Access Key field, type your access key ID for connecting to the DynamoDB

service.5. In the Secret Key field, type the secret access key corresponding to your access key

ID.6. Select the Temporary Session Token check box, and then copy and paste your

session token into the field.7. To save your settings and close the dialog box, click OK

Configuring Advanced Options

You can configure advanced options to modify the behavior of the driver.

To configure advanced options:1. To access advanced options, open the ODBC Data Source Administrator where you

created the DSN, then select the DSN, then click Configure, and then clickAdvanced Options

www.simba.com 19


2. In the Number of Retries field, type the maximum number of times that the drivershould retransmit a request to the DynamoDB database if the request fails from arecoverable error.

Each retransmission consumes throughput, even if it fails. For more informationabout provisioned throughput and how it is used, see Provisioned Throughputin Amazon DynamoDB in the Amazon DynamoDB documentation located athttp://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ProvisionedThroughputIntro.html

3. In the Limit Throughput Consumption field, type the percentage of the totalprovisioned read units that the driver is allowed to consume. For information aboutspecifying an appropriate value, see Limit Throughput Consumption on page 57.

4. To prevent INSERT statements from overwriting existing primary keys, select theEnable overwrite protection check box.

In DynamoDB, the default response to an INSERT statement includesoverwriting primary keys.

Overwrite protection is not supported for virtual tables.5. Use the options in the Active Metadata Location area to specify the file or table

containing the schema that you want the driver to use:l To configure the driver to use a schema stored in a JSON file, select Localfile, then click Browse, and then select the JSON file containing the schema.

l To configure the driver to use a schema stored in a DynamoDB table, selectDatabase and then do the following:

i. In the Database field, type the name of the table. You can specify thename of an existing table to use, or the name of a new table to createand use.

ii. In the Read Throughput Units and Write Throughput Units fields, typethe number of read units and write units (respectively) to allocate to thetable. For more information, see Read Throughput Units on page 59 andWrite Throughput Units on page 61.

You must specify values for Read Throughput Units and WriteThroughput Units, even if you are using an existing table.However, specifying a different number of read or write units foran existing table does not update the table. These values areset when the table is created.

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

Defining a Schema

The Simba Amazon DynamoDB ODBC Driver with SQL Connector can sample data froma database and then generate the schema that is needed for ODBC applications. Theschema can be stored in a local file or in a table in the database. Typically, you would storethe schema in the database so that all users who connect to the database can use thesame schema.

www.simba.com 20


http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ProvisionedThroughputIntro.html


You can also manually edit a schema. To do this, use the driver to generate the initialschema and store it in a local file, and then use the Schema Editor to modify the schema inthe file.

Creating a Schema

If you are working with a DynamoDB database that does not already have the schemaneeded for ODBC applications, use the options in the Schema Definition dialog box tocreate a schema and import it into the database.

To create a schema:1. Open the ODBC Data Source Administrator where you created the DSN, then select

the DSN, then click Configure, and then click Advanced Options2. Use the options in the Active Metadata Location area to configure a table for storing

the schema:a) Select Database and then type the name of the table that you want to use to

store the schema. You can specify the name of an existing table in thedatabase, or the name of a new table to be created.

b) In the Read Throughput Units and Write Throughput Units fields, type thenumber of read units and write units (respectively) to allocate to the table. Formore information, see Read Throughput Units on page 59 and WriteThroughput Units on page 61.

You must specify values for Read Throughput Units and WriteThroughput Units, even if you are using an existing table. However,specifying a different number of read or write units for an existingtable does not update the table. These values are set when the tableis created.

c) To save your settings and close the Advanced Options dialog box, click OK3. In the Simba Amazon DynamoDB ODBC Driver DSN Setup dialog box, click

Schema DefinitionThe options in the Schema Definition dialog box are disabled by default.These options become available after you set a JSON file to use as theexternal schema file. All actions to export, edit, or update the schema usethe JSON file that you set.

4. To specify the JSON file that you want to use to locally store the schema, click theBrowse button beside the External Schema File field. In the Save As dialog box,browse to select an existing JSON file or type the name of a new JSON file that youwant to create, and then click Save

5. To generate a schema based on a sampling of all the tables in the database and thenexport the schema to the JSON file, click Generate All. In the confirmation dialogbox, click Yes

ORTo generate a schema based on a sampling of specific tables in the data source andthen export the schema to the JSON file, type a comma-separated or semicolon-

www.simba.com 21


separated list of the tables that you want the driver to sample, and then click SampleSelect Tables. In the confirmation dialog box, click Yes

When you generate and export the schema, it replaces all existing content inthe JSON file.

After the sampling process, the driver returns a message indicating whether theschema was successfully created and whether any tables could not be sampled. Thedriver may fail to sample certain tables due to the following reasons:

l The provisioned throughput configured for the table does not support the read-ing speed required by the driver. During sampling, the driver reads tables at arate of 100 items per second.

l The table contains a secondary index that has mixed data types in one of thekeys.

l An error has occurred in the server.6. To modify the schema, click Edit Schema File. Using the Schema Editor that

opens, modify the schema as needed, and then save your changes. For moreinformation about using the Schema Editor, see the Schema Editor User Guide.

It is recommended that you test your modified schema before importing itinto the database for others to use. To test your schema, set the Local fileadvanced property to the full path and name of the JSON file containingyour modified schema and then connect to the database. You can theninspect the results of your schema definition and verify if your queries run asintended.

7. To import the schema into the database, in the Schema Definition dialog box, clickUpload Metadata

When you import the schema, it replaces all the existing content in the tableyou specified in step 2.

8. To close the Schema Definition dialog box, click OK

Editing a Schema

You can modify an existing schema stored in a DynamoDB database or in a JSON file.

To edit a schema saved in a database:1. Open the ODBC Data Source Administrator where you created the DSN, then select

the DSN, then click Configure, and then click Advanced Options2. Use the options in the Active Metadata Location area to specify the table containing

the schema that you want to export for editing:a) Select Database and then type the name of the table containing the schema

that you want to export for editing.b) Specify values in the Read Throughput Units and Write Throughput Units

fields.

www.simba.com 22


You must specify values for Read Throughput Units and WriteThroughput Units. However, specifying a different number of read orwrite units for an existing table does not update the table. Thesevalues are set when the table is created.

c) To save your settings and close the Advanced Options dialog box, click OK3. In the Simba Amazon DynamoDB ODBC Driver DSN Setup dialog box, click

Schema DefinitionThe options in the Schema Definition dialog box are disabled by default.These options become available after you set a JSON file to use as theexternal schema file. All actions to export, edit, or update the schema usethe JSON file that you set.

4. To specify the JSON file that you want to use to locally store the schema, click theBrowse button beside the External Schema File field. In the Save As dialog box,browse to select an existing JSON file or type the name of a new JSON file that youwant to create, and then click Save

5. To export the schema from the database to the JSON file, click Export Existing. Inthe confirmation dialog box, click OK

When you export the schema, it replaces all existing content in the JSONfile.

6. To modify the schema, click Edit Schema File. Using the Schema Editor thatopens, modify the schema as needed, and then save your changes. For moreinformation about using the Schema Editor, see the Schema Editor User Guide.

It is recommended that you test your modified schema before importing itinto the database for others to use. To test your schema, set the Local fileadvanced property to the full path and name of the JSON file containingyour modified schema and then connect to the database. You can theninspect the results of your schema definition and verify if your queries run asintended.

7. To import the modified schema into the database, in the Schema Definition dialogbox, click Upload Metadata

When you import the schema, it replaces all the existing content in the tablespecified in the Advanced Options dialog box.

8. To close the Schema Definition dialog box, click OK

To edit a schema saved in a JSON file:1. Open the ODBC Data Source Administrator where you created the DSN, then select

the DSN, then click Configure, and then click Schema DefinitionThe options in the Schema Definition dialog box are disabled by default.These options become available after you set a JSON file to use as theexternal schema file. All actions to export, edit, or update the schema usethe JSON file that you set.

2. To select the JSON file containing the schema that you want to edit, click theBrowse button beside the External Schema File field, select the file, and then clickSave

www.simba.com 23


3. To modify the schema, click Edit Schema File. Using the Schema Editor thatopens, modify the schema as needed, and then save your changes. For moreinformation about using the Schema Editor, see the Schema Editor User Guide.

Using an Existing Schema

You can configure the driver to use a schema saved in the database or in a local JSON file.

To use an existing schema:1. Open the ODBC Data Source Administrator where you created the DSN, then select

the DSN, then click Configure, and then click Advanced Options2. To use a schema stored in a file, select Local file and then specify the full name and

path of the JSON file containing the schema.OR

To use a schema stored in a database table, do the following:a) In the Active Metadata Location area, select Database and type the name of

the table containing the schema that you want to use.b) Specify values in the Read Throughput Units and Write Throughput Units

fields.You must specify values for Read Throughput Units and WriteThroughput Units. However, specifying a different number of read orwrite units for an existing table does not update the table. Thesevalues are set when the table is created.

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

Deleting a Schema

You can delete the schema from the database.

This operation cannot be undone. It is recommended that you back up the schemaby exporting it to a local JSON file before deleting it from the database.

To delete a schema:1. Open the ODBC Data Source Administrator where you created the DSN, then select

the DSN, then click Configure, and then click Advanced Options2. In the Active Metadata Location area, select Database and then type the name of

the table containing the schema that you want to delete.3. Specify values in the Read Throughput Units and Write Throughput Units fields.

You must specify values for Read Throughput Units and Write ThroughputUnits. However, specifying a different number of read or write units for anexisting table does not update the table. These values are set when thetable is created.

4. To save your settings and close the Advanced Options dialog box, click OK5. Click Schema Definition

www.simba.com 24


6. To delete the schema in the table you specified in step 2, click Clear ExistingMetadata

Configuring Logging Options

To help troubleshoot issues, you can enable logging. In addition to functionality provided inthe Simba Amazon DynamoDB ODBC Driver with SQL Connector, the ODBC DataSource Administrator provides tracing functionality.

Only enable logging or tracing long enough to capture an issue. Logging or tracingdecreases 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 thelogging levels provided by the Simba Amazon DynamoDB ODBC Driver with SQLConnector, 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 continuerunning.

WARNING Logs potentially harmful situations.

INFO Logs general information that describes the progress of thedriver.

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

TRACE Logs more detailed information than the DEBUG level.

Table 1. Simba Amazon DynamoDB ODBC Driver with SQL Connector Logging Levels

To enable the logging functionality available in the Simba Amazon DynamoDBODBC Driver with SQL Connector:

1. To access logging options, open the ODBC Data Source Administrator where youcreated the DSN, then select the DSN, then click Configure, and then clickLogging Options

2. In the Log Level list, select the desired level of information to include in log files.3. In the Log Path field, specify the full path to the folder where you want to save log

files.4. If requested by Technical Support, type the name of the component for which to log

messages in the Log Namespace field. Otherwise, do not type a value in the field.5. Click OK

www.simba.com 25


6. Restart your ODBC application to ensure that the new settings take effect.

The Simba Amazon DynamoDB ODBC Driver with SQL Connector produces a log filenamed DynamoDBODBC_driver.log at the location you specify using the Log Path field.

To disable Simba Amazon DynamoDB ODBC Driver with SQL Connector logging:1. To access logging options, open the ODBC Data Source Administrator where you

created the DSN, then select the DSN, then click Configure, and then clickLogging Options

2. In the Log Level list, select LOG_OFF3. 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 filename 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 TracingNow

For more information about tracing using the ODBC Data Source Administrator, see thearticle How to Generate an ODBC Trace with ODBC Data Source Administrator athttp://support.microsoft.com/kb/274551

www.simba.com 26


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

Linux Driver

System Requirements


l One of the following distributions:o Red Hat® Enterprise Linux® (RHEL) 5, 6, or 7o CentOS 5, 6, or 7o SUSE Linux Enterprise Server (SLES) 11 or 12o Ubuntu 12.04 or 14.04o Debian 7

l 150 MB of available disk spacel One of the following ODBC driver managers installed:

o iODBC 3.52.7 or latero unixODBC 2.3.0 or later

Installing the Driver Using the RPM

There are two versions of the driver for Linux:l SimbaDynamoDBODBC-32bit-Version-Release.i686.rpm for the 32-bit driverl SimbaDynamoDBODBC-64bit-Version-Release.x86_64.rpm for the 64-bit driver

Version is the version number of the driver, and Release is the release number for thisversion of the driver.

The bitness of the driver that you select should match the bitness of the client applicationaccessing your data. For example, if the client application is 64-bit, then you should installthe 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 thedriver.

The Simba Amazon DynamoDB ODBC Driver with SQL Connector driver files areinstalled in the following directories:

l /opt/simba/dynamodbodbc contains release notes, the Simba AmazonDynamoDB ODBC Driver with SQL Connector Installation and Configuration Guidein PDF format, and a Readme.txt file that provides plain text installation andconfiguration instructions.

l /opt/simba/dynamodbodbc/ErrorMessages contains error message files requiredby the driver.

www.simba.com 27


l /opt/simba/dynamodbodbc/Setup contains sample configuration files namedodbc.ini and odbcinst.ini

l /opt/simba/dynamodbodbc/lib/32 contains the 32-bit shared libraries and thesimba.dynamodbodbc.ini configuration file.

l /opt/simba/dynamodbodbc/lib/64 contains the 64-bit shared libraries and thesimba.dynamodbodbc.ini configuration file.

l /opt/simba/dynamodbodbc/Tools/SchemaEditor contains the Schema EditorJava application.

To install the Simba Amazon DynamoDB ODBC Driver with SQL Connector: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 atthe command line, where RPMFileName is the file name of the RPM packagecontaining the version of the driver that you want to install:yum --nogpgcheck localinstall RPMFileName

ORIn SUSE Linux Enterprise Server, log in as the root user, then navigate to the foldercontaining the driver RPM packages to install, and then type the following at thecommand line, where RPMFileName is the file name of the RPM package containingthe 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/dynamodbodbc/lib/32 or /opt/simba/dynamodbodbc/lib/64 folder,depending on the version of the driver that you installed.

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

Installing the Driver Using the Tarball Package

Alternatively, the Simba Amazon DynamoDB ODBC Driver with SQL Connector isavailable for installation using a TAR.GZ tarball package. The tarball package contains thefollowing:

l simba/dynamodbodbc contains the release notes, the Simba Amazon DynamoDBODBC Driver with SQL Connector Installation and Configuration Guide in PDFformat, and a Readme.txt file that provides plain text installation and configurationinstructions.

l simba/dynamodbodbc/ErrorMessages contains error message files required bythe driver.

l simba/dynamodbodbc/lib/32 contains the 32-bit driver and thesimba.dynamodbodbc.ini configuration file.

l simba/dynamodbodbc/lib/64 contains the 64-bit driver and thesimba.dynamodbodbc.ini configuration file.

www.simba.com 28


l simba/dynamodbodbc/Setup contains sample configuration files named odbc.iniand odbcinst.ini

l simba/dynamodbodbc/Tools/SchemaEditor contains the Schema Editor Javaapplication.

To install the Simba Amazon DynamoDB ODBC Driver with SQL Connector:1. Log in as the root user, then navigate to the folder containing the tarball package,

and then run the tar command to extract the package and install the driver.For example:tar --directory=/opt -zxvf TarballName

TarballName is the name of the tarball package containing the driver you want toinstall.

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



If you need to verify the version of the Simba Amazon DynamoDB ODBC Driver with SQLConnector that is installed on your Linux machine, you can query the version numberthrough the command-line interface if the driver was installed using an RPM file.

To verify the version number:At the command prompt, run the following command:yum list | grep SimbaDynamoDBODBC

ORRun the following command:rpm -qa | grep SimbaDynamoDBODBC

The command returns information about the Simba Amazon DynamoDB ODBC Driverwith SQL Connector that is installed on your machine, including the version number.

Setting the LD_LIBRARY_PATH Environment Variable

The LD_LIBRARY_PATH environment variable must include the paths to the installedODBC driver manager libraries.

For example, if ODBC driver manager libraries are installed in /usr/local/lib, then setLD_LIBRARY_PATH as follows:export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

www.simba.com 29


For information about how to set environment variables permanently, refer to your Linuxshell documentation.

For information about creating ODBC connections using the Simba Amazon DynamoDBODBC Driver with SQL Connector, see Configuring ODBC Connections for Non-WindowsPlatforms on page 33.

www.simba.com 30


Mac OS X Driver

System Requirements


l Mac OS X version 10.9 or 10.10l 150 MB of available disk spacel iODBC 3.52.7 or later

Installing the Driver

The Simba Amazon DynamoDB ODBC Driver with SQL Connector driver files areinstalled in the following directories:

l /opt/simba/dynamodbodbc contains release notes, the Simba AmazonDynamoDB ODBC Driver with SQL Connector Installation and Configuration Guidein PDF format, and a Readme.txt file that provides plain text installation andconfiguration instructions.

l /opt/simba/dynamodbodbc/ErrorMessages contains error message files requiredby the driver.

l /opt/simba/dynamodbodbc/Setup contains sample configuration files namedodbc.ini and odbcinst.ini

l /opt/simba/dynamodbodbc/lib/universal contains the driver binaries.l /opt/simba/dynamodbodbc/Tools/Schema Editor contains the Schema Editor

Java application.

To install the Simba Amazon DynamoDB ODBC Driver with SQL Connector:1. Double-click SimbaDynamoDBODBC.dmg to mount the disk image.2. Double-click SimbaDynamoDBODBC.pkg to run the installer.3. In the installer, click Continue4. 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, then

select the desired location, and then click Continue6. To accept the installation location and begin the installation, click Install7. When the installation completes, click Close8. If you received a license file via e-mail, then copy the license file into the

/opt/simba/dynamodbodbc/lib/universal folder.

www.simba.com 31




If you need to verify the version of the Simba Amazon DynamoDB ODBC Driver with SQLConnector that is installed on your Mac OS X machine, you can query the version numberthrough the Terminal.

To verify the version number:At the Terminal, run the following command:pkgutil --info simba.dynamodbodbc

The command returns information about the Simba Amazon DynamoDB ODBC Driverwith SQL Connector that is installed on your machine, including the version number.

Setting the DYLD_LIBRARY_PATH Environment Variable

The DYLD_LIBRARY_PATH environment variable must include the paths to the installedODBC driver manager libraries.

For example, if ODBC driver manager libraries are installed in /usr/local/lib, then setDYLD_LIBRARY_PATH as follows:export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/usr/local/lib

For information about how to set environment variables permanently, refer to your Mac OSX shell documentation.

For information about creating ODBC connections using the Simba Amazon DynamoDBODBC Driver with SQL Connector, see Configuring ODBC Connections for Non-Windows Platforms on page 33.

www.simba.com 32


Configuring ODBC Connections for Non-WindowsPlatforms

The following sections describe how to configure ODBC connections when using theSimba Amazon DynamoDB ODBC Driver with SQL Connector with non-Windowsplatforms:

l Configuration Files on page 33l Sample Configuration Files on page 34l Configuring the Environment on page 34l Configuring the odbc.ini File on page 35l Configuring the odbcinst.ini File on page 36l Configuring the simba.dynamodbodbc.ini File on page 37l Configuring Authentication on page 38l Defining a Schema on page 39l Configuring Logging Options on page 41

Configuration Files

ODBC driver managers use configuration files to define and configure ODBC data sourcesand drivers. By default, the following configuration files residing in the user’s homedirectory are used:

l .odbc.ini is used to define ODBC data sources, and it is required for DSNs.l .odbcinst.ini is used to define ODBC drivers, and it is optional.

Also, by default the Simba Amazon DynamoDB ODBC Driver with SQL Connector isconfigured using the simba.dynamodbodbc.ini file, which is located in one of the followingdirectories depending on the version of the driver that you are using:

l /opt/simba/dynamodbodbc/lib/32 for the 32-bit driver on Linuxl /opt/simba/dynamodbodbc/lib/64 for the 64-bit driver on Linuxl /opt/simba/dynamodbodbc/lib/universal for the driver on Mac OS X

The simba.dynamodbodbc.ini file is required.

The simba.dynamodbodbc.ini file in the /lib subfolder provides default settings formost configuration options available in the Simba Amazon DynamoDB ODBCDriver with SQL Connector.

You can set driver configuration options in your odbc.ini and simba.dynamodbodbc.inifiles. Configuration options set in a simba.dynamodbodbc.ini file apply to all connections,whereas configuration options set in an odbc.ini file are specific to a connection.Configuration options set in odbc.ini take precedence over configuration options set insimba.dynamodbodbc.ini. For information about the configuration options available for

www.simba.com 33


controlling the behavior of DSNs that are using the Simba Amazon DynamoDB ODBCDriver with SQL Connector, see Driver Configuration Options on page 54.

Sample Configuration Files

The driver installation contains the following sample configuration files in the Setupdirectory:

l odbc.inil odbcinst.ini

These sample configuration files provide preset values for settings related to the SimbaAmazon DynamoDB ODBC Driver with SQL Connector.

The names of the sample configuration files do not begin with a period (.) so that they willappear in directory listings by default. A file name beginning with a period (.) is hidden. Forodbc.ini and odbcinst.ini, if the default location is used, then the file names must begin witha period (.).

If the configuration files do not exist in the home directory, then you can copy the sampleconfiguration files to the home directory, and then rename the files. If the configurationfiles already exist in the home directory, then use the sample configuration files as a guideto modify the existing configuration files.

Configuring the Environment

Optionally, you can use three environment variables—ODBCINI, ODBCSYSINI, andSIMBADYNAMODBINI—to specify different locations for the odbc.ini, odbcinst.ini, andsimba.dynamodbodbc.ini configuration files by doing the following:

l Set ODBCINI to point to your odbc.ini file.l Set ODBCSYSINI to point to the directory containing the odbcinst.ini file.l Set SIMBADYNAMODBINI to point to your simba.dynamodbodbc.ini file.

For example, if your odbc.ini and simba.dynamodbodbc.ini files are located in /etc and yourodbcinst.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 SIMBADYNAMODBINI=/etc/simba.dynamodbodbc.ini

The following search order is used to locate the simba.dynamodbodbc.ini file:1. If the SIMBADYNAMODBINI environment variable is defined, then the driver

searches for the file specified by the environment variable.SIMBADYNAMODBINI must specify the full path, including the file name.

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

www.simba.com 34


3. The current working directory of the application is searched for a file namedsimba.dynamodbodbc.ini (not beginning with a period).

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

5. The directory /etc is searched for a file named simba.dynamodbodbc.ini (notbeginning with a period).

Configuring the odbc.ini File

ODBC Data Source Names (DSNs) are defined in the odbc.ini configuration file. The file isdivided into several sections:

l [ODBC] is optional and used to control global ODBC configuration, such as ODBCtracing.

l [ODBC Data Sources] is required, listing DSNs and associating DSNs with adriver.

l A section having the same name as the data source specified in the [ODBC DataSources] 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 DynamoDB DSN 32=Simba DynamoDB ODBC Driver 32-bit

[Sample Simba DynamoDB DSN 32]

Driver=/opt/simba/dynamodbodbc/lib/32/libsimbadynamodbodbc32.so

Host=dynamodb.Region.amazonaws.com;

Port=8000;

Region is the AWS region to use for your connection.

The following is an example of an odbc.ini configuration file for Mac OS X:[ODBC Data Sources]

Sample Simba DynamoDB DSN=Simba DynamoDB ODBC Driver

[Sample Simba DynamoDB DSN]

Driver=/opt/simba/dynamodbodbc/lib/universal/libsimbadynamodbodbc.dylib

Host=dynamodb.Region.amazonaws.com;

Port=8000;

Region is the AWS region to use for your connection.

www.simba.com 35


To create a Data Source Name: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. Specifyconfiguration options as key-value pairs.

4. If you are connecting to the DynamoDB service on AWS instead of a server onDynamoDB Local, then configure authentication. For more information, seeConfiguring Authentication on page 38.

5. Save the odbc.ini configuration file.

For information about the configuration options available for controlling the behavior ofDSNs that are using the Simba Amazon DynamoDB ODBC Driver with SQL Connector,see Appendix B Driver Configuration Options on page 54.

Configuring the odbcinst.ini File

ODBC drivers are defined in the odbcinst.ini configuration file. The configuration file isoptional because drivers can be specified directly in the odbc.ini configuration file, asdescribed in Configuring the odbc.ini File on page 35.

The odbcinst.ini file is divided into the following sections:l [ODBC Drivers] lists the names of all the installed ODBC drivers.l 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 configuration file for Linux:[ODBC Drivers]

Simba DynamoDB ODBC Driver 32-bit=Installed

Simba DynamoDB ODBC Driver 64-bit=Installed

[Simba DynamoDB ODBC Driver 32-bit]

Description=Simba DynamoDB ODBC Driver (32-bit)


[Simba DynamoDB ODBC Driver 64-bit]

Description=Simba DynamoDB ODBC Driver (64-bit)


The following is an example of an odbcinst.ini configuration file for Mac OS X:[ODBC Drivers]

www.simba.com 36


Simba DynamoDB ODBC Driver=Installed

[Simba DynamoDB ODBC Driver]

Description=Simba DynamoDB ODBC Driver

Driver=/opt/simba/dynamodbodbc/lib/universal/libsimbadynamodbodbc.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 =InstalledType a symbolic name that you want to use to refer to the driver inconnection strings or DSNs.

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

4. Save the odbcinst.ini configuration file.

Configuring the simba.dynamodbodbc.ini File

The simba.dynamodbodbc.ini file contains configuration settings for the Simba AmazonDynamoDB ODBC Driver with SQL Connector. Settings that you define in thesimba.dynamodbodbc.ini file apply to all connections that use the driver.

To configure the Simba Amazon DynamoDB ODBC Driver with SQL Connector towork with your ODBC driver manager:

1. Open the simba.dynamodbodbc.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 usesUTF-32, andunixODBC uses UTF-16. To determine the correct setting to use, refer to yourODBC driver manager documentation.

3. Edit the ODBCInstLib setting. The value is the name of the ODBCInst shared libraryfor the ODBC driver manager you use. To determine the correct library to specify,refer to your ODBC driver manager documentation.The configuration file defaults to the shared library for iODBC. In Linux, the sharedlibrary name for iODBC is libiodbcinst.so. In Mac OS X, the shared library name foriODBC is libiodbcinst.dylib.

You can specify an absolute or relative filename for the library. If you intendto use the relative filename, then the path to the library must be included inthe library path environment variable. In Linux, the library path environmentvariable is named LD_LIBRARY_PATH. In Mac OS X, the library pathenvironment variable is named DYLD_LIBRARY_PATH.

www.simba.com 37


4. Optionally, configure logging by editing the LogLevel and LogPath settings. For moreinformation, see Configuring Logging Options on page 41.

5. Save the simba.dynamodbodbc.ini configuration file.

Configuring Authentication

Connections to DynamoDB require authentication. You must configure the Simba AmazonDynamoDB ODBC Driver with SQL Connector to provide your credentials andauthenticate the connection to the database.

You can authenticate your connection by using one of the following forms of credentials:l Access keys (access key and secret key)l Credentials filel Temporary security credentials (access key, secret key, and session token)

Configure authentication settings in the driver by defining connection attributes in aconnection string or in a DSN (in the odbc.ini file).

Using Access Keys

You can provide an access key and a secret key in order to authenticate your connection.

To configure authentication using access keys:1. Set the Region attribute to the AWS region to which you want to connect.2. Set the AuthMechanism attribute to 03. Set the AccessKey attribute to your access key ID for connecting to the DynamoDB

service.4. Set the SecretKey attribute to the secret access key corresponding to your access

key ID.

Using a Credentials File

You can provide AWS credentials by using a special credentials file that contains theaccess keys and secret keys of multiple users.

For information about the format of a credentials file, see the section AWSCredentials File Format in the AWS documentation available athttp://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/credentials.html# credentials-file-format

To configure authentication using a credentials file:1. Set the Region attribute to the AWS region to which you want to connect.2. Set the AuthMechanism attribute to 13. Set the CredentialFile attribute to the full path and name of the AWS credentials file

that you want to use.

www.simba.com 38




4. Set the ProfileName attribute to the name of the profile to use from the AWScredentials file.

Using Temporary Security Credentials

Temporary credentials consist of an access key, a secret key, and a session token, whichare all valid for 1 hour only. Contact your DynamoDB server administrator to request a setof temporary credentials.

To configure authentication using temporary security credentials:1. Set the Region attribute to the AWS region to which you want to connect.2. Set the AuthMechanism attribute to 03. Set the AccessKey attribute to your access key ID for connecting to the DynamoDB

service.4. Set the SecretKey attribute to the secret access key corresponding to your access

key ID.5. Set the TempCredentials attribute to 16. Set the SessionToken attribute to your session token for accessing the DynamoDB

service.

Defining a Schema

The Simba Amazon DynamoDB ODBC Driver with SQL Connector can sample data froma database and then generate the schema that is needed for ODBC applications. Whenusing a non-Windows version of the driver to create or edit a schema, you must store theschema in a local file instead of a database table.

You can also manually edit a schema. To do this, use the driver to generate the initialschema and store it in a local file, and then use the Schema Editor to modify the schema inthe file.

Creating a Schema

If you are working with a DynamoDB database that does not already have the schemaneeded for ODBC applications, use the connection properties provided by the driver tocreate a schema.

To create a schema:1. Set the GenerateSchema property to 12. Optionally, if you want the driver to sample specific tables instead of all the tables in

the database, then set the SamplingTables property to a comma-separated orsemicolon-separated list of tables for sampling.

3. Set the LocalMetadataFile property to the full path and name of a JSON file that youwant to use to locally store the schema.

4. Connect to the DynamoDB database.

www.simba.com 39


When you connect to the database using the settings defined in steps 1 to 3,the driver samples the data, generates a schema, and stores the schema inthe specified JSON file.

If the LogLevel option is set to 5 or 6, then the driver log includes a messageindicating whether any tables could not be sampled. The driver may fail tosample certain tables due to the following reasons:

l The provisioned throughput configured for the table does not supportthe reading speed required by the driver. During sampling, the driverreads tables at a rate of 100 items per second.

l The table contains a secondary index that has mixed data types in oneof the keys.

l An error has occurred in the server.

5. Open the JSON file in the Schema Editor, then modify the schema as needed, andthen save your changes. For more information about using the Schema Editor, seethe Schema Editor User Guide.

You can now use the schema defined in the JSON file when connecting to the database.For more information, see Using an Existing Schema on page 40.

Editing a Schema

You can modify an existing schema stored in a JSON file.

To edit a schema saved in a JSON file:Open the JSON file in the Schema Editor, modify the schema as needed, and thensave your changes. For more information about using the Schema Editor, see theSchema Editor User Guide.

Using an Existing Schema

You can configure the driver to use a schema saved in the database or in a local JSON file.

To use an existing schema:To use a schema stored in a local file, set the LocalMetadataFile property to the fullpath and name of the JSON file containing the schema that you want to use, andthen connect to the database.

OR

To use a schema stored in a database table, do the following:a) Set the MetadataDatabaseTable property to the name of the table containing

the schema that you want to use.b) Specify values for the MetadataReadUnits and MetadataWriteUnits

properties.

www.simba.com 40


You must specify values for MetadataReadUnits andMetadataWriteUnits. However, specifying a different number of reador write units for an existing table does not update the table. Thesevalues are set when the table is created.

c) Connect to the database.

Configuring Logging Options

To help troubleshoot issues, you can enable logging in the driver.

Only enable logging long enough to capture an issue. Logging decreasesperformance 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 thelogging levels provided by the Simba Amazon DynamoDB ODBC Driver with SQLConnector, 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 continuerunning.

3 Logs potentially harmful situations.

4 Logs general information that describes the progress of thedriver.

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

6 Logs more detailed information than LogLevel=5

Table 2. Simba Amazon DynamoDB ODBC Driver with SQL Connector Logging Levels

To enable logging:1. Open the simba.dynamodbodbc.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. Forexample:LogPath=/localhome/employee/Documents

4. Save the simba.dynamodbodbc.ini configuration file.

www.simba.com 41


5. Restart your ODBC application to ensure that the new settings take effect.

The Simba Amazon DynamoDB ODBC Driver with SQL Connector produces a log filenamed DynamoDBODBC_driver.log at the location you specify using the LogPath key.

To disable logging:1. Open the simba.dynamodbodbc.ini configuration file in a text editor.2. Set the LogLevel key to 03. Save the simba.dynamodbodbc.ini configuration file.

www.simba.com 42


Features

More information is provided on the following features of the Simba Amazon DynamoDBODBC Driver with SQL Connector:

l SQL Interface on page 43l C++ Interface on page 43l Data Types on page 43l Schema Definition on page 43l Virtual Tables on page 44l Write-back on page 47l Parallel Scan on page 49

SQL Interface

The Simba Amazon DynamoDB ODBC Driver with SQL Connector provides a SQLinterface that enables ODBC applications to work with data that is stored in DynamoDBdatabases. DynamoDB uses a unique POST-based JSON web API and provides SDKsthat enable Java, .NET, or PHP to interact with the API; without the SQL interfaceprovided by the driver, DynamoDB can only be accessed by applications that nativelysupport the API or SDKs.

C++ Interface

The Simba Amazon DynamoDB ODBC Driver with SQL Connector provides a C++interface that enables C++ based applications to work with data that is stored inDynamoDB databases. AWS does not natively support C++ APIs. To access DynamoDBdatabases using C++ applications, you must connect through the driver.

Data Types

To support complex DynamoDB data types such as lists, maps, and sets, the driverconverts the data into virtual tables. For more information, see Virtual Tables on page 44.

Schema Definition

DynamoDB is able to store "denormalized" data that does not follow the rules of datatyping and structure that apply to relational databases. DynamoDB tables do not have aschema, and schemas are defined for each row instead. As a result, columns are notsubject to data typing and may contain cells that are of varying data types. Becausetraditional ODBC toolsets may not support some of these data structures, the data needsto be mapped to a relational form. To achieve this, the Simba Amazon DynamoDB ODBCDriver with SQL Connector generates a database schema that maps the DynamoDB datato an ODBC-compatible format.

www.simba.com 43


To generate the database schema that is needed for ODBC applications, the driversamples the tables in the database, assigns a DynamoDB data type to each column, andthen maps each DynamoDB data type to the SQL data type that is best able to representthe greatest number of items in the table.

During the sampling process, the driver defines a SQL data type and a DynamoDB datatype for each column, but does not change the data types of the individual cells in thedatabase. As a result, columns may contain mixed data types. During read operations,values are converted to match the SQL data type of the column so that the driver can workwith all the data in the column consistently.

In addition to the automatic schema generation done by the driver, you can also manuallyedit the schema by using the Schema Editor. The Schema Editor is a Java application thatruns on Windows, Linux, and Mac OS X. It is installed as part of the Simba AmazonDynamoDB ODBC Driver with SQL Connector. For more information about using theSchema Editor, see the Schema Editor User Guide.

For detailed information about generating or manually defining a schema when using theWindows driver, see Defining a Schema on page 20. For information about generating ormanually defining a schema when using the Linux or Mac OS X driver, see Defining aSchema on page 39.

Virtual Tables

One advantage of the DynamoDB design is the ability to store data that is denormalizedinto a fewer number of tables. However, the ODBC interface does not natively supportaccessing denormalized data types such as lists, maps, and sets. By expanding the datacontained within lists, maps, and sets into virtual tables, the Simba Amazon DynamoDBODBC Driver with SQL Connector allows users to directly interact with the data but leavethe storage of the data in its denormalized form in DynamoDB.

If any columns are mapped to a denormalized data type during schema generation, thenthe driver creates the following tables and saves them as part of the schema:

l A "base" table, which contains the same data as the real table except for the columnsthat are mapped to a denormalized data type.

l A virtual table for each column of denormalized data, expanding the first level of nes-ted data.

Data that is nested deeper than one level in the list or map is returned as a JSONstring. For information about the data type changes that may occur when thedriver reads or writes DynamoDB data, see Data Type Mapping and ConversionRules on page 63.

Virtual tables refer to the data in the real table, enabling the driver to access thedenormalized data. By querying the virtual tables, you can access the contents of lists,maps, and sets via ODBC. When you write or modify data in a virtual table, the data in thereal table in the DynamoDB database is updated.

www.simba.com 44


The base table and virtual tables appear as additional tables in the list of tables that exist inthe database. The base table uses the same name as the real table that it represents. Thevirtual tables that represent lists, maps, and sets are named using the name of the realtable, a separator (#vt_), and the name of the column.

For example, consider the example DynamoDB table named ExampleTable shown inTable 3.

Hash Range List Map StringSet

0 1 [ { “N” : “1” }, { “N” :“2” }, { “N” : “3”}]

{{Name: {S: JohnDoe}}, {Age: {N:60}}, {Address: {S:221B Main St.}}}

{ “A”, “B”, “C” }

3 3 [ { “N” : “100” }, { “N”: “101” }, { “N” :“102”}, { “N” : “105”}]

{{Name: {S: JaneDoe}}, {Age: {N:35}}}

{ “D”, “E” }

Table 3. ExampleTable

The driver would generate multiple virtual tables to represent this single table. Table 4shows the base table.

Hash Range

0 1

3 3

Table 4. ExampleTable

The base table contains all of the data of the original table, but the data from the lists,maps, and sets have been omitted and will be expanded in the other virtual tables.

Table 5, Table 6, and Table 7 show the virtual tables that represent the data from the List,Map, and StringSet columns.

Hash Range List#index List#value

0 1 0 1

0 1 1 2

0 1 2 3

Table 5. ExampleTable#vt_List

www.simba.com 45


Hash Range List#index List#value

3 3 0 100

3 3 1 101

3 3 2 102

3 3 3 105

Hash Range Map#Name Map#Age Map#Address

0 1 John Doe 60 221B Main St.

3 3 Jane Doe 35

Table 6. ExampleTable#vt_Map

Hash Range StringSet#value

0 1 A

0 1 B

0 1 C

3 3 D

3 3 E

Table 7. ExampleTable#vt_StringSet

The Hash and Range columns in the virtual tables reference the Hash and Range columnsin the real table, and indicate which real table row the virtual table row corresponds to.

In virtual tables representing lists, columns with names that end with #index indicate theposition of the data within the original list. Values in #index columns are of type Integer. Invirtual tables representing lists or sets, columns with names that end with #value containthe expanded data from the list or set.

In virtual tables representing maps, the driver creates a column for each distinct key thatwas detected during sampling. Any map keys that are not detected during sampling will notappear in the virtual table and will not be available for read or write operations.

The data in the virtual tables can be selected, inserted, and updated as if they were normaltables, and the driver will handle the storage details within DynamoDB. For example, to

www.simba.com 46


append F to StringSet in ExampleTable, where Hash = 3 and Range = 3, use the followingquery:INSERT INTO "ExampleTable#vt_StringSet" (Hash, Range,"StringSet#value") VALUES (3, 3, 'F')

However, some operations are not supported for certain types of data. For moreinformation, see Write-back on page 47.

Write-back

The Simba Amazon DynamoDB ODBC Driver with SQL Connector supports DataManipulation Language (DML) statements such as INSERT, UPDATE, and DELETE. Thedriver does not support SQL subqueries, ODBC transactions, or ODBC batch operations.

Writing data to the DynamoDB database may change the typing of the data. If theexisting data is of a type that is different from the column data type defined in theschema, then the existing data will be replaced by new data that is of the columndata type.

When the driver samples the data and generates the schema, the driver defines a SQLdata type and a DynamoDB data type for each column, but does not change the data typesof the individual cells in the database. As a result, columns may contain mixed data types.The Simba Amazon DynamoDB ODBC Driver with SQL Connector supports DMLstatements on mixed data types. When you execute a write operation, the driver will firstattempt to complete the operation using the column data type that was defined duringsampling. If the operation fails, then the driver will convert the cells to match the data typeof the column and then attempt the operation again.

The way that the driver handles each DML statement is described in more detail below.

DynamoDB data sources are eventually consistent, so changes in the databasemay not appear until some time after the DML statement is executed.

INSERT

By default, the driver does not execute INSERT statements atomically. If an INSERTstatement affects multiple rows and an error occurs in one of them, then the driver returnsan error, and none of the subsequent rows are inserted.

Each row in DynamoDB has a unique ID known as the “primary key”. The primary key maybe a hash value, or a hash value and a range value. When inserting a new row in any tableother than a virtual table representing a list, it is mandatory to specify the primary key.Normally, inserting a row that has the same primary key as a row in the table will overwritethe existing row. If you enable overwrite protection, then the driver will not execute anyINSERT statements that would overwrite an existing row in the table.

Hash and range attributes are exposed as valid columns. For example, consider Table 8.

www.simba.com 47


Hash Range sample_column

0 1 A

3 4 B

Table 8. Before INSERT Example

To insert a row, issue a command such as the following:INSERT INTO sample_table_1(Hash, Range, sample_column)VALUES(5,6,'C')

Table 9 shows the table after the insertion.

Hash Range sample_column

0 1 A

3 4 B

5 6 C

Table 9. After INSERT Example

When inserting a row into a virtual table that represents a map, all the columns for whichno data types are specified will be omitted from the row. For example, if the table schemais MAP(KeyColumn, Key1, Key2) and you execute the command INSERT INTOMAP(KeyColumn, Key1) VALUES ("k1", 1) then Key2 is omitted and thefollowing map value is inserted into the table: {"Key1":{"N":1}}

UPDATE

When an UPDATE statement affects multiple rows, the driver executes the statement asmultiple separate statements. If an error occurs in one of the updates, then the driverreturns an error, and none of the subsequent updates are completed. However, any rowsthat were updated successfully before the error occurred will remain updated.

You cannot use UPDATE statements to change sets or primary keys (the Hashand Range columns) in DynamoDB.

DELETE

The driver does not execute DELETE statements atomically. If a DELETE statementaffects multiple rows and an error occurs in one of them, then that row is not deleted, butany other rows that can be deleted successfully are deleted.

www.simba.com 48


When you delete a row from a real or base table, the driver also deletes values in therelated rows in the virtual tables. However, because the driver cannot delete primary keys,the rows in the virtual tables cannot be completely deleted.

If you delete all the rows from a table but the table still exists in the schema, then the tableis valid and can still be accessed.

Supported Data Types for DML

DML statements cannot be used directly on the following:l Listsl Mapsl String setsl Number setsl Binary setsl Indexes

To modify a list, map, or set, execute DML statements on the virtual table that correspondsto it. For more information, see Virtual Tables on page 44. UPDATE statements cannot beused on virtual tables that represent sets

The CREATE, ALTER, and DROP statements are not supported for tables.

The data provided in DML statements should match the existing column data types. Forexample, a String value cannot be inserted or set in a column that is defined as a Numbercolumn in the schema.

Parallel Scan

The Simba Amazon DynamoDB ODBC Driver with SQL Connector supports parallelscans, which allow the driver to improve performance by dividing a scan operation acrossmultiple threads. You can specify the number of threads that the driver uses to scan a tableby accessing the table properties through the Schema Editor and modifying the value ofthe numberOfThreads property.

Before configuring parallel scans, consider the following factors:l Parallel scans consume more provisioned throughput units than single-threaded

scans.l Parallel scans are only effective for improving the performance of scan operations on

large tables. The overhead associated with running multiple threads often outweighthe performance gain of using parallel scan, so the default number of threads usedfor each table is 1.

l The relationship between the number of threads used and the performance level ofscan operations is not linear; continuing to increase the number of threads useddoes not guarantee an equal increase in performance.

www.simba.com 49


Parallel scan is most effective when used on tables with high provisioned throughputvalues. Because each thread can only consume a certain amount of throughput, tableswith large amounts of provisioned throughput can support more threads. If some of theprovisioned throughput of a table appears to be unused, consider increasing the number ofthreads.

www.simba.com 50


Contact Us

If you have difficulty using the driver, please contact our Technical Support staff. Wewelcome your questions, comments, and feature requests.

Technical Support is available Monday to Friday from 8 a.m. to 6 p.m. Pacific Time.

To help us assist you, prior to contacting Technical Support please prepare adetailed summary of the client and server environment including operating systemversion, patch level, and configuration.

You can contact Technical Support via:l E-mail—[email protected] Web site—www.simba.coml Telephone—(604) 633-0008 Extension 3l Fax—(604) 633-0004

You can also follow us on Twitter @SimbaTech

www.simba.com 51


mailto:[email protected]?subject=Technical Support

http://www.simba.com/

Appendix A Using a Connection String

For some applications, you may need to use a connection string to connect to your datasource. For detailed information about how to use a connection string in an ODBCapplication, refer to the documentation for the application that you are using.

The following connection strings are examples showing the minimum set of connectionattributes that you must specify in order to successfully connect to the data source.Depending on the configuration of the data source and the type of connection you areworking with, you may need to specify additional connection attributes. For detailedinformation about all the attributes that you can use in the connection string, see DriverConfiguration Options on page 54.

DSN Connection String Example

The following is an example of a connection string for a connection that uses a DSN:DSN=DataSourceName;

DataSourceName is the DSN that you are using for the connection.

You can set additional configuration options by appending key-value pairs to theconnection string. Configuration options that are passed in using a connection string takeprecedence over configuration options that are set in the DSN.

For information about creating a DSN on a Windows computer, see Creating a DataSource Name on page 16. For information about creating a DSN on a non-Windowscomputer, see Configuring the odbc.ini File on page 35.

DSN-less Connection String Examples

Some applications provide support for connecting to a data source using a driver without aDSN. To connect to a data source without using a DSN, use a connection string instead.

The placeholders in the examples are defined as follows, in alphabetical order:l Name is the name of the profile to use from the AWS credentials file.l Path is the full path and name of your AWS credentials file.l PortNumber is the number of the port that the server on DynamoDB Local uses to

listen for client connections.l Region is the AWS region to use for your connection.l Server is the IP address of the server on DynamoDB Local.l YourAccessKey is the access key ID that you use to access the DynamoDB service

on AWS.l YourSecretKey is the secret access key corresponding to your access key ID.

www.simba.com 52


l YourSessionToken is the session token to use when connecting to DynamoDB usingtemporary security credentials.

Connecting to the DynamoDB Service on AWS Using Access Keys

The following is an example of a DSN-less connection string that connects to theDynamoDB service using an access key and a secret key:Driver=Simba DynamoDB ODBC Driver;Host=dynamodb.Region.amazonaws.com;Region=us-west-2;AuthMechanism=0;AccessKey=YourAccessKey;SecretKey=YourSecretKey;

Connecting to the DynamoDB Service on AWS Using a Credentials File

The following is an example of a DSN-less connection string that connects to theDynamoDB service using an AWS credentials file:Driver=Simba DynamoDB ODBC Driver;Host=dynamodb.Region.amazonaws.com;Region=us-west-2;AuthMechanism=1;CredentialFile=Path;ProfileName=Name;

Connecting to the DynamoDB Service on AWS Using Temporary SecurityCredentials

The following is an example of a DSN-less connection string that connects to theDynamoDB service using temporary security credentials:Driver=Simba DynamoDB ODBC Driver;Host=dynamodb.Region.amazonaws.com;Region=us-west-2;AuthMechanism=0;AccessKey=YourAccessKey;SecretKey=YourSecretKey;TempCredentials=1;SessionToken=YourSessionToken;

Temporary credentials consist of an access key, a secret key, and a session token,which are all valid for 1 hour only. Contact your DynamoDB server administrator torequest a set of temporary credentials.

Connecting to a Server on DynamoDB Local

The following is an example of a DSN-less connection string that connects to a server onDynamoDB Local:Driver=Simba DynamoDB ODBC Driver;DynamoDBLocal=1;Host=Server;Port=PortNumber;Region=Region;AccessKey=YourAccessKey;SecretKey=YourSecretKey;

For information about how the Region, AccessKey, and SecretKey values areused in connections to DynamoDB Local, see DynamoDB Local for DesktopDevelopment in the AWS Official Blog located athttps://aws.amazon.com/blogs/aws/dynamodblocal-for-desktop-development/

www.simba.com 53


https://aws.amazon.com/blogs/aws/dynamodblocal-for-desktop-development/

Appendix B Driver Configuration Options

Appendix B Driver Configuration Options on page 54 lists the configuration optionsavailable in the Simba Amazon DynamoDB ODBC Driver with SQL Connectoralphabetically by field or button label. Options having only key names—not appearing inthe user interface of the driver—are listed alphabetically by key name.

When creating or configuring a connection from a Windows computer, the fields andbuttons described below are available in the following dialog boxes:

l Simba Amazon DynamoDB ODBC Driver DSN Setupl Advanced Optionsl Schema Definition

When using a connection string or configuring a connection from a Linux or Mac OS Xcomputer, use the key names provided below.

You can pass in configuration options in your connection string, or set them in yourodbc.ini and simba.dynamodbodbc.ini files if you are using a non-Windows versionof the driver. Configuration options set in a simba.dynamodbodbc.ini file apply toall connections, whereas configuration options passed in in the connection stringor set in an odbc.ini file are specific to a connection. Configuration options passedin using the connection string take precedence over configuration options set inodbc.ini. Configuration options set in odbc.ini take precedence over configurationoptions set in simba.dynamodbodbc.ini

Configuration Options Appearing in the User Interface

The following configuration options are accessible via the Windows user interface for theSimba Amazon DynamoDB ODBC Driver with SQL Connector, or via the key name whenusing a connection string or configuring a connection from a Linux or Mac OS X computer:

l Access Key on page 55l Authentication on page 55l Database on page 55l DynamoDB Local on page 56l Enable Overwrite Protection on

page 56l File Path on page 56l Host on page 57l Limit Throughput Consumption on

page 57l Local File on page 57

l Port on page 58l Profile Name on page 58l Read Throughput Units on page 59l Region on page 59l Sampling Select Tables on page 59l Secret Key on page 60l Temporary Session Token (check

box) on page 60l Temporary Session Token (field) on

page 61l Write Throughput Units on page 61

www.simba.com 54


l Number of Retries on page 58

Access Key

Key Name Default Value Required

AccessKey None Yes, if you are not using acredentials file(AuthMechanism is set to0).

Description

The access key ID that you use to access the DynamoDB database.

For information about how the Access Key value is used in connections toDynamoDB Local, see DynamoDB Local for Desktop Development in the AWSOfficial Blog located at https://aws.amazon.com/blogs/aws/dynamodb-local-for-desktop-development/

Authentication


AuthMechanism IAM Credentials (0) Yes

Description

When this option is set to IAM Credentials (0), the driver authenticates connections toDynamoDB by using an access key and a secret key.

When this option is set to Credential File (1), the driver authenticates connections toDynamoDB by using a profile from a credentials file.

Database


MetadataDatabaseTable None Yes, if Local File (theLocalMetadataFile key) isnot set.

Description

The name of the database table that stores the metadata.

www.simba.com 55




DynamoDB Local


DynamoDBLocal Clear (0) Optional

Description

When this option is enabled (1), the driver connects to a DynamoDB Local server.

When this option is disabled (0), the driver connects to the DynamoDB service on AWS.

Enable Overwrite Protection


OverwriteProtectionEnabled Clear (0) Optional

Description

When this option is enabled (1), the driver prevents INSERT statements from overwritingexisting primary keys.

When this option is disabled (0), INSERT statements can overwrite existing primary keys.

In DynamoDB, the default response to an INSERT statement includes overwritingthe primary keys.

Overwrite protection is not supported for virtual tables.

File Path


CredentialFile None Yes, if you are using acredentials file(AuthMechanism is set to1).

Description

The full path and name of the AWS credentials file.

For information about the format of a credentials file, see the section AWS Credentials FileFormat in the AWS documentation available athttp://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/credentials.html#credentials-file-format

www.simba.com 56




Host


Host None Yes

Description

If you are connecting to AWS, then specify the URL (the endpoint) for the DynamoDBservice on AWS. For example, dynamodb.Region.amazonaws.com, where Region isthe AWS region to use for your connection.

For a list of available AWS regions, see the Regions and Endpoints article in theAWS documentation available athttp://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region

If you are connecting to DynamoDB Local, then specify the IP address of the server.

Limit Throughput Consumption


ThroughputLimit 75 No

Description

The percentage of the total provisioned read units that the driver is allowed to consume.By default, the driver is allowed to consume up to 75% of the provisioned throughput.

Ensure that you use a value that is appropriate for the number of client applications thatwill be using a specific table concurrently. For example, if you set this value to 100, thenone client will use all of the provisioned throughput units, preventing any other clients fromusing the table until more throughput becomes available.

To throttle the amount of throughput used, the driver starts by estimating the number ofitems per second that it can request from a table, and then multiplies that number of itemsby the Limit Throughput Consumption value. The resulting number of items is themaximum number of items per second that the driver will request from the table.

Local File


LocalMetadataFile None Yes, if Database (theMetadataDatabaseTablekey) is not set.

www.simba.com 57


http://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region

Description

The path and name of the JSON file that stores the metadata.

Number of Retries


RetryLimit 0 Optional

Description

The maximum number of times that the driver should retransmit a request to theDynamoDB database if the request fails from a recoverable error.

Each retransmission consumes throughput, even if it fails. For more informationabout provisioned throughput and how it is used, see Provisioned Throughput inAmazon DynamoDB in the Amazon DynamoDB documentation located athttp://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ProvisionedThroughputIntro.html

Port


Port None Yes, if connecting toDynamoDB Local.

Description

The number of the port used by the DynamoDB Local database to listen for clientconnections.

The default port number used by DynamoDB Local is 8000.

Profile Name


ProfileName None Yes, if you are using acredentials file(AuthMechanism is set to1).

Description

The name of the profile to use from the AWS credentials file.

www.simba.com 58




Read Throughput Units


MetadataReadUnits 5 Yes, if Database (theMetadataDatabaseTablekey) is set.

Description

The number of read units allocated to a metadata table when it is created. 1 read unit isequal to 4kb per second.

It is recommended that you allocate at least 5 read units, with an additional 0.5 units foreach additional client using the table concurrently.

Changing this value does not update an existing table. The value is used onlywhen the table is created.

Region


Region None Yes

Description

The AWS region to which you want to connect.

For a list of available AWS regions, see the Regions and Endpoints article in theAWS documentation available athttp://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region

For information about how the Region value is used in connections to DynamoDBLocal, see DynamoDB Local for Desktop Development in the AWS Official Bloglocated at https://aws.amazon.com/blogs/aws/dynamodb-local-for-desktop-development/

Sampling Select Tables


SamplingTables None No

www.simba.com 59


http://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region



Description

A comma-separated or semicolon-separated list of tables that the driver will sample whengenerating a schema.

If this option is not set, then the driver will sample all the tables in the database.

Secret Key


SecretKey None Yes, if you are not using acredentials file(AuthMechanism is set to0).

Description

The secret access key corresponding to the access key ID that you provided in the AccessKey field (the AccessKey key).

For information about how the Secret Key value is used in connections toDynamoDB Local, see DynamoDB Local for Desktop Development in the AWSOfficial Blog located at https://aws.amazon.com/blogs/aws/dynamodb-local-for-desktop-development/

Temporary Session Token (check box)


TempCredentials Clear (0) Yes, if you are usingtemporary securitycredentials.

Description

When this option is enabled (1), the driver authenticates connections to DynamoDB byusing a set of temporary security credentials. Temporary credentials consist of an accesskey, a secret key, and a session token, which are all valid for 1 hour only.

When this option disabled (0), the driver does not use temporary credentials.

Contact your DynamoDB server administrator to request a set of temporarycredentials.

www.simba.com 60




Temporary Session Token (field)


SessionToken None Yes, if you are usingtemporary securitycredentials.

Description

The session token to use when connecting to DynamoDB using temporary securitycredentials, which are valid for 1 hour only.

Contact your DynamoDB server administrator to request a set of temporarycredentials.

Write Throughput Units


MetadataWriteUnits 1 Yes, if Database (theMetadataDatabaseTablekey) is set.

Description

The number of write units allocated to a metadata table when it is created. 1 write unit isequal to 1kb per second.

It is recommended that you allocate 1 write unit for every 20 database tables sampled tocreate the metadata table.

Changing this value does not update an existing table. The value is used onlywhen the table is created.

Once the metadata table is created, the driver will no longer attempt to write to it,so you can use the AWS console to reduce the number of write units to 1 (theminimum value possible).

Configuration Options Having Only Key Names

The GenerateSchema option is used to support schema definition in non-Windowsversions of the driver. You can set this option in a connection string or in an odbc.iniconfiguration file.

www.simba.com 61


GenerateSchema

Default Value Required

0 No

Description

When this option is enabled (1), the driver generates the database schema that is neededfor ODBC applications and then stores the schema in the JSON file specified in theLocalMetadataFile key.

If the SamplingTables key is also set, then the driver generates the schema based on asampling of the specified tables only.

When this option is disabled (0), the driver does not generate schemas.

To avoid unintentionally generating the schema again and overwriting an existingschema that you want to keep, set the GenerateSchema property to 0 or remove itfrom your connection string or odbc.ini configuration file after you have generatedthe necessary schema.

www.simba.com 62


Appendix C Data Type Mapping and ConversionRules

To support schema generation, read operations, and write operations for DynamoDBdatabases, the Simba Amazon DynamoDB ODBC Driver with SQL Connector must definemappings between DynamoDB data types and SQL data types so that the data can beconverted between the mapped types and the driver can work with all the data in eachcolumn consistently.

The following sections explain how the Simba Amazon DynamoDB ODBC Driver with SQLConnector maps and converts data types so that DynamoDB data is compatible with SQLqueries and the ODBC interface. Consider these guidelines when reading and writing dataor manually editing schemas.

Mapping Mixed DynamoDB Data Types to One DynamoDBData Type

As part of the schema generation process, the driver samples the data in the database andthen assigns a DynamoDB data type to each column. Table 10 shows the DynamoDB datatype that the driver will use to represent any two given data types. For example, if a columncontains boolean values and string set values, then the driver will assign the string set datatype to that column.

NULL Boolean(BOOL)

Number(N)

Binary(B)

String(S)

NumberSet (NS)

BinarySet (BS)

StringSet (SS)

List(L)

Map(M)

Boolean(BOOL)

BOOL BOOL N S S NS SS SS L S

Number(N)

N N N S S NS S SS L S

Binary(B)

B S S B S SS BS SS L S

String(S)

S S S S S SS SS SS L S

NumberSet (NS)

NS NS NS SS SS NS SS SS L S

BinarySet (BS)

SS SS SS BS SS SS BS SS L S

String SS SS SS SS SS SS SS SS L S

Table 10. Mapping Mixed DynamoDB Types to One DynamoDB Type

www.simba.com 63


NULL Boolean(BOOL)

Number(N)

Binary(B)

String(S)

NumberSet (NS)

BinarySet (BS)

StringSet (SS)

List(L)

Map(M)

Set (SS)

List(L)

L L L L L L L L L L

Map(M)

M S S S S S S S L M

For information about how lists, maps, and sets are represented in the ODBC interface,see Virtual Tables on page 44.

Mapping DynamoDB Data Types to SQL Data Types

To support read operations, the DynamoDB data types in the database are mapped to theSQL data types that will be exposed through the driver. Table 11 shows the supported datatype conversions. The top row lists the DynamoDB data types, and the leftmost columnlists the SQL data types. The colored cells containing superscript numbers indicate thatadditional information is available below the table.

String Number Binary Boolean Null StringSet

NumberSet

BinarySet List Map

BOOLEAN X1 X2 X X

BIT X1 X2 X X

TINYINT X3 X3 X5 X

SMALLINT X3 X3 X5 X

INTEGER X3 X3 X5 X

BIGINT X3 X3 X5 X

FLOAT X3 X3 X5 X

REAL X3 X3 X5 X

DOUBLE X3 X3 X5 X

NUMERIC X3 X3 X5 X

Table 11. Mapping DynamoDB Types (top row) to SQL Types (leftmost column)

www.simba.com 64


String Number Binary Boolean Null StringSet

NumberSet

BinarySet List Map

DECIMAL X3 X3 X5 X

CHAR X X X X6 X X7 X7 X7 X7 X7

VARCHAR X X X X6 X X7 X7 X7 X7 X7

LONGVARCHAR X X X X6 X X7 X7 X7 X7 X7

DATE X3 X

TIME X3 X

TIMESTAMP X3 X

BINARY X4 X X

VARBINARY X4 X X

LONGVARBINARY X4 X X

1 : If the String value is true (regardless of letter case), it is returned as True. If the valueis any other non-null value, it is returned as False.

2 : If the Number value is 1, it is returned as True. If it is any other non-null value, it isreturned as False.

3 : The driver will try to convert the value to the SQL type. If the conversion fails, the driverreturns an error.

The valid format for Date data is yyyy-[m]m-[d]d

The valid format for Time data is hh:mm:ss[.f…]

The valid format for Timestamp data is yyyy-[m]m-[d]d hh:mm:ss[.f...]

4 : The driver returns the base64-decoded value.

5 : If the Boolean value is True, it is returned as 1. If the Boolean value is False, it isreturned as 0.

6 : If the Boolean value is True, it is returned as "1". If the Boolean value is False, it isreturned as "0".

7 : The driver returns the data as a JSON string. The following are two examples:{"1":{"B":"MDA0MQ=="},"A":{"S":"a"},"B":{"N":"1"}}

["MDA0MQ==","MTIzNA==","QUJDRA=="]

www.simba.com 65


Special Considerations for Virtual Tables

Because the data type can change from row to row in DynamoDB, some specialconversion rules apply to DynamoDB cells that are represented in virtual tables.

Set Virtual Tablesl Set Values: When the cell contains a set value, the value is converted to the

SQL type of the #value column, as defined in the schema.l Scalar Values: When the cell contains a scalar value, the value is converted to the

SQL type of the #value column, as defined in the schema.l List or Map Values: When the cell contains a list or map value, the value cannot be

represented as a SQL data type. All the columns except the one containing theprimary key will return as data errors. The returned error is different from the typicalSQL conversion error.

List Virtual Tablesl Set Values: When the cell contains a set value, the value is converted to the

SQL type of the #value column, as defined in the schema. The #index column valueis incremented for each set value, starting from 0.

l Scalar Values: When the cell contains a scalar value, the value is converted to theSQL type of the #value column, as defined in the schema. The #index column valueis 0.

l Map Values: When the cell contains a map value, the value cannot be representedas a SQL data type. All the columns except the one containing the primary key willreturn as data errors. The returned error is different from the typical SQL conversionerror.

Map Virtual Tables

Set, Scalar, or List Values: When the cell contains a set, scalar, or list value, the valuecannot be represented as a SQL data type. All the columns except the one containing theprimary key will return as data errors. The returned error is different from the typicalSQL conversion error.

Mapping One DynamoDB Data Type to Another

During a write operation, the driver inserts the new data as the DynamoDB data type ofthe column, as defined in the schema. If the existing value is of a type that is different fromthe column data type defined in the schema, then the driver will do one of the following,depending on what is supported:

l The driver may convert the existing value to the column data type and then write thenew value.

l Alternatively, the driver will simply replace the existing value with the new value.

www.simba.com 66


Table 12 shows the supported conversions from one DynamoDB data type to another. Foreach cell, refer to the note below the table with the corresponding color or letter foradditional information.

NULL Boolean Number Binary String NumberSet

BinarySet

StringSet List Map

NULL S Y Y Y Y Y Y Y Y Y

Boolean Y S Y Y Y Y Y Y Y Y

Number Y Y S Y Y Y Y Y Y Y

Binary Y Y Y S Y Y Y Y Y Y

String Y Y Y Y S Y Y Y Y Y

NumberSet

Y C C N C S N C N N

BinarySet

Y N N C C N S C N N

StringSet

Y C C C C C C S N N

List Y C C C C C C C S N

Map Y N N N N N N N N S

Table 12. Conversion Support from a DynamoDB Cell Data Type to a DynamoDB ColumnData Type

N : The type conversion is not supported. The driver will not perform the UPDATE orINSERT operation.

Y : The driver replaces the existing value with the value from the UPDATE or INSERToperation.

C : The driver converts the existing value to the column data type defined in the schema,and then executes the UPDATE or INSERT operation on the converted value.

S : The data types are the same. The driver executes the UPDATE or INSERT operationon the value without converting it.

www.simba.com 67
