ODBC Data Wrapper Reference

ODBC HeavyConnect and import is currently a beta feature.
This topic provides setup and configuration details and information about supported data types when using ODBC HeavyConnect or import. This reference also describes ODBC data wrapper assumptions and supported mappings of HeavyDB column types to ODBC column types, and provides RDMS-specific notes.
ODBC Driver Installation
To HeavyConnect to or import from an external RDMS using the ODBC data wrapper, make sure that an appropriate ODBC driver is installed for the RDMS you want to access. RDMS vendors websites usually provide ODBC driver download and configuration instructions, and in certain cases, ODBC drivers are managed by third-party vendors that provide these instructions.
ODBC Configuration Files
Two key configuration files need to be set up when using ODBC HeavyConnect or import: odbcinst.ini and odbc.ini.
The odbcinst.ini file specifies a list of installed drivers, along with required configuration for those drivers (the path to the driver binary). The following example is an odbcinst.ini configuration file for an instance with installed drivers for PostGreSQL, Redshift, and Snowflake:
[ODBC Drivers]
PostgreSQL=Installed
Redshift=Installed
Snowflake=Installed
​
[PostgreSQL]
Description=PostgreSQL ODBC driver
Driver=/usr/lib/x86_64-linux-gnu/odbc/psqlodbca.so
​
[Redshift]
Description=Redshift ODBC driver
Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so
​
[Snowflake]
Description=Snowflake ODBC Driver
Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so
Use an intuitive name for the drivers, such as the official name of the RDMS, so that users can easily know the driver names to use in connection strings.
The odbc.ini file contains configuration for database-specific connections. Each connection configuration is identified by a data source name (DSN). The following example is an odbc.ini file with configuration for the default postgres database on a local instance of PostgreSQL running on port 5432:
[ODBC Data Sources]
default_postgres_db=default_postgres_db
​
[default_postgres_db]
Description=Local default PostgreSQL database
Driver=PostgreSQL
Database=postgres
Servername=localhost
Port=5432
Locate odbcinst.ini and odbc.ini in the /etc/ directory, or in the home directory for cases where the server process is started under a specific user account.
Working with HEAVY.AI Docker Images
For docker deployments of HEAVY.AI, ODBC driver installations can be managed in a Dockerfile that uses the HEAVY.AI Docker image as a base. For example, you can create a docker image with installed PostGreSQL, Redshift, and Snowflake ODBC drivers using a Dockerfile with the following content.
Always consult the license and terms and conditions of the ODBC drivers you install. The examples here are provided for illustrative purposes only.
FROM heavyai/heavyai-ee-cuda
​
# Install PostGreSQL ODBC driver.
# The Snowflake ODBC driver depends on unixodbc.
RUN apt-get update && apt-get install -y odbc-postgresql unixodbc
​
# Install Redshift ODBC driver.
RUN wget https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.deb
RUN dpkg -i ./AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.deb
RUN rm ./AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.deb
​
# Install Snowflake ODBC driver.
RUN wget https://sfc-repo.snowflakecomputing.com/odbc/linux/latest/snowflake-odbc-2.25.2.x86_64.deb
RUN dpkg -i ./snowflake-odbc-2.25.2.x86_64.deb
RUN rm ./snowflake-odbc-2.25.2.x86_64.deb
You can then build a new image with installed ODBC drivers using the Dockerfile. 
The odbcinst.ini and odbc.ini configuration files should be bound to /etc/odbcinst.ini and /etc/odbc.ini, respectively, when running the container.
ODBC Data Wrapper Assumptions
The remote database management system supports the MIN, MAX, and LENGTH SQL functions. These functions are used internally for optimizations and validations.
The combination of the query specified in the foreign table’s SQL_SELECT option and the SQL_ORDER_BY option is guaranteed to return a result set in the same order every time the query is executed.
Queries for geo columns are always returned as WKT strings. This implies that either geo columns are stored as text columns containing WKT strings, geo columns are cast to text (for example, using a function like ST_AsText) in the SQL_SELECT query, or the remote database management system, by default, projects geo columns as WKT strings.
HeavyDB to ODBC Data Type Mapping
Numeric and Boolean Types
HeavyDB (Down) \ ODBC (Right)
SQL_BIGINT
SQL_INTEGER
SQL_SMALLINT
SQL_TINYINT
SQL_DOUBLE
SQL_FLOAT
SQL_REAL
SQL_DECIMAL
SQL_NUMERIC
SQL_BIT
BIGINT
Yes (unsigned is coercible)
Yes (if unsigned)
No
No
No
No
No
Coercible
No
No
BIGINT ENCODING FIXED (32) / INTEGER
Coercible
Yes
Yes (if unsigned)
No
No
No
No
Coercible
No
No
BIGINT ENCODING FIXED (16) / INTEGER ENCODING FIXED (16) / SMALLINT
Coercible
Coercible
Yes
Yes (if unsigned)
No
No
No
Coercible
No
No
BIGINT ENCODING FIXED (8) / INTEGER ENCODING FIXED (8) / SMALLINT ENCODING FIXED (8) / TINYINT
Coercible
Coercible
Coercible
Yes
No
No
No
Coercible
No
No
BOOLEAN
No
No
No
No
No
No
No
No
No
Yes
DECIMAL (Precision, Scale)
No
No
No
No
No
No
No
Yes (if precision and scale are within OmniSci’s range)
Yes (if precision and scale are within OmniSci’s range)
No
DOUBLE
No
No
No
No
Yes
Coercible
No
No
No
No
FLOAT
No
No
No
No
Coercible
Coercible
Yes
No
No
No
*[1] PostgreSQL requires setting the option BoolsAsChar=false to represent boolean columns as SQL_BIT.
Date and Time Types
HeavyDB (Down) \ ODBC (Right)
SQL_TYPE_DATE
SQL_TYPE_TIMESTAMP
SQL_TYPE_TIME
SQL_TYPE_UTCDATETIME
SQL_TYPE_UTCTIME
DATE / DATE ENCODING DAYS (32)
Coercible
No
No
No
No
DATE ENCODING DAYS (16)
Coercible
No
No
No
No
TIME
No
No
Yes
No
No
TIME ENCODING FIXED (32)
No
No
Yes
No
No
TIMESTAMP (0)
No
Coercible
No
No
No
TIMESTAMP (3)
No
Coercible
No
No
No
TIMESTAMP (6)
No
Coercible
No
No
No
TIMESTAMP (9)
No
Coercible
No
No
No
TIMESTAMP ENCODING FIXED (32)
No
Coercible
No
No
No
Geo and String Types
HeavyDB (Down) \ ODBC (Right)
SQL_CHAR
SQL_VARCHAR
SQL_LONGVARCHAR
SQL_WCHAR
SQL_WVARCHAR
SQL_WLONGVARCHAR
TEXT ENCODING DICT
Yes
Yes
Yes
Yes
Yes
Yes
TEXT ENCODING (16)
Yes
Yes
Yes
Yes
Yes
Yes
TEXT ENCODING (8)
Yes
Yes
Yes
Yes
Yes
Yes
TEXT ENCODING NONE
Yes
Yes
Yes
Yes
Yes
Yes
LINESTRING
No
Yes
Yes
No
No
No
MULTIPOLYGON
No
Yes
Yes
No
No
No
POINT
No
Yes
Yes
No
No
No
POLYGON
No
Yes
Yes
No
No
No
Array Type
Array data types currently are not supported.
See https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/sql-data-types for more details about ODBC data types, and consult the specific RDMS ODBC driver documentation for  details about how the RDMS data types map to the ODBC data types.
RDMS-Specific Notes
PostgreSQL
The official PostgreSQL ODBC driver can be downloaded from https://odbc.postgresql.org/​
Accessing BOOLEAN data in PostgreSQL requires the BoolsAsChar=false option to be added to the connection string or DSN configuration.

HeavyConnect - Previous

Parquet Data Wrapper Reference

Last modified 1mo ago

Export as PDF

Copy link

Outline

ODBC Driver Installation

ODBC Configuration Files

Working with HEAVY.AI Docker Images

ODBC Data Wrapper Assumptions

HeavyDB to ODBC Data Type Mapping

RDMS-Specific Notes