Connecting to HP Vertica

Transcription

1 HP Vertica Analytic Database Software Version: 7.1.x Document Release Date: 12/9/2015

2 Legal Notices Warranty The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice. Restricted Rights Legend Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR and , Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Copyright Notice Copyright Hewlett-Packard Development Company, L.P. Trademark Notices Adobe is a trademark of Adobe Systems Incorporated. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. UNIX is a registered trademark of The Open Group. HP Vertica Analytic Database Page 2 of 401

3 Contents Contents 3 Using vsql 19 General Notes 19 Installing the vsql Client 22 How to Install vsql on Unix-Based systems: 22 Installing vsql on Windows: 22 vsql Notes for Windows Users 22 Connecting From the Administration Tools 23 Connecting from the Command Line 25 Command-Line Options 26 General Options 26 Connection Options 28 Output Formatting 29 Input and Output Options 30 -c Command --command Command 31 -f Filename --file Filename 31 -F Separator --field-separator Separator 32 -h Hostname --host Hostname 33 Notes: 33 -v Assignment --set Assignment --variable Assignment 33 Connecting From a Non-Cluster Host 34 Meta-Commands 35 \! [ COMMAND ] 35 \? 35 \a 37 \b 37 \c (or \connect) [ Dbname [ Username ] ] 37 \C [ STRING ] 37 \cd [ DIR ] 37 HP Vertica Analytic Database Page 3 of 401

4 Contents The \d [ PATTERN ] Meta-Commands 37 \d [ PATTERN ] 38 \df [ PATTERN ] 42 \dj [ PATTERN ] 43 \dn [ PATTERN ] 44 \dp [ PATTERN ] 44 \ds [ PATTERN ] 45 \ds [ PATTERN ] 45 \dt [ PATTERN ] 46 \dt [ PATTERN ] 46 \dtv [ PATTERN ] 47 \du [ PATTERN ] 47 \dv [ PATTERN ] 48 \e \edit [ FILE ] 48 \echo [ STRING ] 49 \f [ String ] 49 \g 49 \H 49 \h \help 49 \i FILE 51 \l 51 Locale 51 Viewing the Current Locale Setting 51 Overriding the Default Local for a Session 51 \o 52 \p 52 \password [ USER ] 53 \pset NAME [ VALUE ] 53 \q 55 \qecho [ STRING ] 55 \r 55 HP Vertica Analytic Database (7.1.x) Page 4 of 401

5 Contents \s [ FILE ] 55 \set [ NAME [ VALUE [... ] ] ] 55 Using Backquotes to Read System Variables 56 \t 57 \T [ STRING ] 57 \timing 57 \unset [ NAME ] 57 \w [ FILE ] 57 \x 57 \z 58 Variables 59 SQL Interpolation 59 AUTOCOMMIT 60 Notes 60 DBNAME 61 ECHO 61 ECHO_HIDDEN 61 ENCODING 61 HISTCONTROL 61 HISTSIZE 61 HOST 62 IGNOREEOF 62 ON_ERROR_STOP 62 PORT 62 PROMPT1 PROMPT2 PROMPT3 62 QUIET 62 SINGLELINE 63 SINGLESTEP 63 USER 63 VERBOSITY 63 VSQL_HOME 63 HP Vertica Analytic Database (7.1.x) Page 5 of 401

6 Contents VSQL_SSLMODE 63 Prompting 64 Command Line Editing 65 Notes 65 vsql Environment Variables 66 Locales 67 To Change Settings on Linux 67 To Change Settings on Windows Using PuTTy 67 Notes 67 Files 68 Exporting Data Using vsql 68 Copying Data Using vsql 70 Monitoring Progress (optional) 71 Output Formatting Examples 71 Client Libraries 75 Client Driver Standards 75 Client Driver and Server Version Compatibility 76 Version 4.1 to 5.1 Client Driver Transition 76 HP Vertica ODBC/JDBC Client Installers 76 ODBC/JDBC Multiple Version Installations 76 HP Vertica ADO.NET Client Installers 77 Installing the Client Drivers 78 Client Driver Standards 78 Driver Prerequisites 78 ODBC Prerequisites 78 Operating System 78 ODBC Driver Manager 78 UTF-8, UTF-16 and UTF-32 Support 78 ADO.NET Prerequisites 79 Operating System 79 Memory 79 HP Vertica Analytic Database (7.1.x) Page 6 of 401

7 Contents.NET Framework 79 Python Prerequisites 79 Python Driver 80 Supported Operating Systems 80 Perl Prerequisites 80 Perl Drivers 80 Supported Client Systems 80 PHP Prerequisites 80 PHP Modules 81 Supported Client Systems 81 Installing the Client Drivers 81 Installing Driver Managers Linux and Other UNIX-like Platforms 82 Installing ODBC Drivers on Linux, Solaris, AIX, and HP-UX 82 Installation Procedure 83 Post Driver Installation Configuration 83 Installing the Client RPM on Red Hat and SUSE 84 Installing JDBC Driver on Linux, Solaris, AIX, and HPUX 85 Installing ODBC/JDBC Client Drivers and vsql Client on Windows 85 To Download the Windows client-drivers: 86 To Install the Windows Client-Drivers and vsql client: 86 To Silent-Install the Windows Client-Drivers and vsql client: 86 After You install: 87 Modifying the Java CLASSPATH 87 Linux, Solaris, AIX, HP-UX, and OS X 87 Windows 88 Specifying the Library Directory in the Java Command 88 Installing the JDBC Driver on Macintosh OS X 88 Downloading the JDBC Driver 88 Ensuring Java Can Find the JDBC Driver 89 Installing the ODBC Driver on Mac OS X 89 Before You Download the Driver 89 HP Vertica Analytic Database (7.1.x) Page 7 of 401

8 Contents Download the Driver 90 Install the Mac OS X ODBC Client-Driver 90 Silently Install the Mac OS X ODBC Client-Driver 91 Uninstall the Mac OS X ODBC Client-Driver 91 Using Legacy Drivers 91 Creating an ODBC Data Source Name (DSN) 93 Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX 93 odbc.ini File Structure 93 Configuring the odbc.ini file: 94 Using an odbcinst.ini File 96 Configuring Additional ODBC Settings 97 Testing a DSN Using Isql 97 Creating an ODBC DSN for Windows Clients 97 Setting Up a DSN 97 To set up a DSN 98 Setting up a 32-Bit DSN on 64-Bit Versions of Microsoft Windows 102 Testing a DSN Using Excel Creating an ODBC DSN for Macintosh OS X Clients 110 Setting Up a DSN 110 Testing a DSN Using iodbctest 112 Data Source Name (DSN) Connection Parameters 113 Required Connection Parameters 113 Optional Parameters 114 Advanced Settings 114 Identification 117 Encryption 118 Third-Party Compatibility 119 Kerberos Connection Parameters 119 Setting DSN Connection Parameters 120 Upgrading the Client Drivers 121 Additional Linux ODBC Driver Configuration Settings 122 HP Vertica Analytic Database (7.1.x) Page 8 of 401

9 Contents Location of the Additional Driver Settings 122 Creating a vertica.ini File 122 Required Settings 123 Setting the VERTICAINI Environment Variable 123 Example vertica.ini File 123 Additional Parameter Settings 124 Logging Settings 124 ODBC-specific Settings 125 ADO.NET-specific Settings 126 Programming ODBC Client Applications 127 ODBC Architecture 127 ODBC Feature Support 128 Updating ODBC Client Code From Previous Driver Versions 128 DSN Parameter Changes 128 Removed DSN Parameters 128 Changed DSN Parameters 129 New DSN Parameter 129 New DSN Parameter Alias 130 Function Changes 130 Removed Functions 131 Interval and TimeStamp Changes 131 New Additional Driver Information 132 -specific ODBC Header File 132 Connecting to 133 Notes 136 Enabling Native Connection Load Balancing in ODBC 136 ODBC Connection Failover 138 Choosing a Failover Method 139 Using DNS Failover 139 Using the Backup Host List 140 Prompting Windows Users for Missing Connection Parameters 142 HP Vertica Analytic Database (7.1.x) Page 9 of 401

10 Contents Prompting Windows Users for Passwords 143 No Password Entry vs. Empty Passwords 145 Setting the Locale for ODBC Sessions 146 AUTOCOMMIT and ODBC Transactions 149 Retrieving Data Through ODBC 152 Loading Data Through ODBC 155 Using a Single Row Insert 155 Using Prepared Statements 156 Using Batch Inserts 159 Batch Insert Steps 160 Tracking Load Status (ODBC) 164 Finding the Number of Accepted Rows 164 Finding the Accepted and Rejected Rows 165 Error Handling During Batch Loads 169 Loading Batches in Parallel 170 Using the COPY Statement 170 Streaming Data From the Client Using COPY LOCAL 173 Using LONG VARCHAR and LONG VARBINARY Data Types with ODBC 176 Programming JDBC Client Applications 177 JDBC Feature Support 177 Multiple SQL Statement Support 177 Multiple Batch Conversion to COPY Statements 178 Multiple JDBC Version Support 178 Updating Application Code From Previous Driver Versions 178 Updating Client Code From 4.1 or Earlier JDBC Driver Versions 179 Driver Package and Interface Name Changes 179 Interface Name Changes 179 Removed Classes 179 Converting From PGConnection to VerticaConnection 180 Property Setters and Getters 180 Deprecated Methods 180 HP Vertica Analytic Database (7.1.x) Page 10 of 401

11 Contents Savepoint Support 182 Updatable Result Set Changes 182 Converting From PGStatement to VerticaStatement 182 Deprecated Methods 182 Bulk Loading Method Changes 183 Connection Property Setters and Getters 183 Multiple Statement Support 184 Connection Property Changes 184 New Connection Properties 184 Renamed Properties 185 Removed Connection Properties 185 New Features in the Version JDBC Driver 186 JNDI Service Registration 186 Exception Class Improvements 186 Wrapper Interface Support 187 Additional DatabaseMetaData Methods 187 Improved Connection Pooling 187 Native Connection Load Balancing Support 187 Connection Failover Support 188 Creating and Configuring a Connection 189 Importing SQL Packages 189 Opening the Connection 189 JDBC Connection Properties 192 Connection Properties 192 General Properties 194 Logging Properties 196 Kerberos Connection Parameters 197 Routable Connection API Connection Parameters 198 Setting and Getting Connection Property Values 198 Setting Properties When Connecting 199 Getting and Setting Properties After Connecting 200 HP Vertica Analytic Database (7.1.x) Page 11 of 401

12 Contents Setting the Locale for JDBC Sessions 201 Notes: 202 Changing the Transaction Isolation Level 202 Using a Pooling Data Source 204 Enabling Native Connection Load Balancing in JDBC 204 JDBC Connection Failover 206 Choosing a Failover Method 206 Using DNS Failover 207 Using the Backup Host List 207 JDBC Data Types 209 Numeric Data Alias Conversion 209 Using Intervals with JDBC 211 Using Intervals in Batch Inserts 212 Reading Interval Values 213 Executing Queries Through JDBC 215 Executing DDL (Data Definition Language) Queries 215 Executing Queries That Return Result Sets 216 Executing DML (Data Manipulation Language) Queries Using executeupdate 216 Loading Data Through JDBC 217 Using a Single Row Insert 217 Using LONG VARCHAR and LONG VARBINARY Data Types with JDBC 217 Batch Inserts Using JDBC Prepared Statements 220 Streaming Batch Inserts 222 Notes 223 Loading Batches Directly into ROS 223 Error Handling During Batch Loads 224 Identifying Accepted and Rejected Rows (JDBC) 224 Rolling Back Batch Loads on the Server 227 Bulk Loading Using the COPY Statement 229 Streaming Data Via JDBC 230 Using VerticaCopyStream 231 HP Vertica Analytic Database (7.1.x) Page 12 of 401

13 Contents Getting Rejected Rows 232 Using COPY LOCAL with JDBC 235 Handling Errors 237 Vertica Analytic Database SQLState Mapping to Java Exception Classes 237 Error Handling Example 240 Routing JDBC Queries Directly to a Single Node 241 Creating Tables and Projections for use with the Routable Query API 243 Creating a Connection for Routable Queries 245 Defining the Query for Routable Queries using the VerticaRoutableExecutor Class 247 Defining the Query for Routable Queries Using the VGet Class 251 Routable Query Performance and Troubleshooting 254 Programming ADO.NET Applications 257 Updating ADO.NET Client Code From Previous Driver Versions 257 Auto Commit Change 257 Performance Improvements 257 Namespace Change 257 Connection Properties 257 Result Buffering 258 Logging Changes 258 Data Type Changes 258 Multiple Commands Now Supported 259 Setting the Locale for ADO.NET Sessions 259 Connecting to the Database 259 Using SSL: Installing Certificates on Windows 260 Import the Server and Client Certificates into the Windows Key store: 260 Import the Public Certificate of Your CA: 260 Enable SSL in Your ADO.NET Applications 260 Opening and Closing the Database Connection (ADO.NET) 261 To Manually Create a Connection string: 261 To Use the VerticaConnectionStringBuilder Class to Create a Connection String and Open a connection: 262 HP Vertica Analytic Database (7.1.x) Page 13 of 401

14 Contents To Close the connection: 263 Example Usage: 263 ADO.NET Connection Properties 263 Enabling Native Connection Load Balancing in ADO.NET 268 ADO.NET Connection Failover 270 Choosing a Failover Method 270 Using DNS Failover 271 Using the Backup Host List 271 Configuring Log Properties (ADO.Net) 272 VerticaLogProperties 272 Setting Log Properties 272 SetLogPath 273 SetLogNamespace 273 SetLogLevel 274 Getting Log Properties 274 Setting and Getting Log Properties Example 275 Querying the Database Using ADO.NET 277 Inserting Data (ADO.NET) 277 To Insert a Single Row of data: 277 Example Usage: 278 Using Parameters 278 Using Parameters 278 Creating and Rolling Back Transactions 279 Creating Transactions 279 To Create a Transaction in HP Vertica Using the ADO.NET driver: 280 Rolling Back Transactions 280 Commit and Rollback Example 281 Setting the Transaction Isolation Level 282 Reading Data (ADO.Net) 284 To Read Data From the Database Using VerticaDataReader: 284 Loading Data Through ADO.Net 286 HP Vertica Analytic Database (7.1.x) Page 14 of 401

15 Contents Using the HP Vertica Data Adapter 286 Batching Updates 287 Reading Data From HP Vertica Using the Data adapter: 287 Reading Data From HP Vertica into a Data set and Changing data: 288 Using Batch Inserts and Prepared Statements 290 Example Batch Insert Using Parameters and Transactions 291 Loading Batches Directly into ROS 293 Streaming Data Via ADO.NET 293 Streaming From the Client Via VerticaCopyStream 294 Using Copy with ADO.NET 296 Handling Messages (ADO.NET) 298 To Use the VerticaInfoMessageEventHander class: 299 Getting Table Metadata (ADO.Net) 300 ADO.NET Data Types 302 Programming Python Client Applications 305 Python on Linux 305 Python on Windows 305 Python and Unicode 306 The Python Driver Module (pyodbc) 306 Configuring the ODBC Run-Time Environment on Linux 306 Querying the Database Using Python 307 Programming Perl Client Applications 309 Perl Client Prerequisites 309 Supported Perl Versions 310 Perl on Linux 310 Perl on Windows 310 The Perl Driver Modules (DBI and DBD::ODBC) 310 Installing Missing Perl Modules 312 Connecting to Using Perl 312 Setting ODBC Connection Parameters in Perl 313 Setting Perl DBI Connection Attributes 314 HP Vertica Analytic Database (7.1.x) Page 15 of 401

16 Contents Connecting From Perl Without a DSN 315 Executing Statements Using Perl 316 Batch Loading Data Using Perl 317 Using COPY LOCAL to Load Data in Perl 319 Querying Using Perl 321 Binding Variables to Column Values 322 Preparing, Querying, and Returning a Single Row 323 Conversions Between Perl and Data Types 324 Perl Unicode Support 326 Programming PHP Client Applications 329 PHP on Linux 329 PHP on Windows 329 The PHP ODBC Drivers 329 Setup 329 Example odbc.ini 329 Example odbcinst.ini 330 Verify the HP Vertica UnixODBC or iodbc Library 330 Test Your ODBC Connection 330 PHP Unicode Support 331 Querying the Database Using PHP 331 Management API 333 curl 335 VerticaAPIKey 337 GET / 338 GET api 340 GET backups 348 POST backups/:config_script_base 350 GET backups/:config_script_base/:archive_id 351 POST restore/:archive_id 352 GETdatabases 353 POST databases 355 HP Vertica Analytic Database (7.1.x) Page 16 of 401

17 Contents GET databases/:database_name 357 PUT databases/:database_name 359 DELETE databases/:database_name 361 GET databases/:database_name/configuration 362 PUT databases/:database_name/configuration 365 GET databases/:database_name/hosts 367 POST databases/:database_name/hosts 369 DELETE databases/:database_name/hosts/:host_id 370 POST databases/:database_name/hosts/:host_id/process 371 DELETE databases/:database_name/hosts/:host_id/process 372 POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new 373 GET databases/:database_name/license 374 GET databases/:database_name/licenses 376 GET databases/:database_name/nodes 378 GET databases/:database_name/nodes/:node_id 379 POST databases/:database_name/process 380 GET databases/:database_name/process 381 DELETE databases/:database_name/process 382 POST databases/:database_name/rebalance/process 383 POST databases/:database_name/wla/process 384 GET hosts 385 GET hosts/:hostid 388 GET jobs 390 GET jobs/:id 392 POST licenses 393 GET licenses 394 GET nodes 395 GET nodes/:nodeid 396 GET webhooks 397 POST webhooks/subscribe 399 DELETE webhooks/:subscriber_id 400 HP Vertica Analytic Database (7.1.x) Page 17 of 401

18 Contents We appreciate your feedback! 401 HP Vertica Analytic Database (7.1.x) Page 18 of 401

19 Using vsql Using vsql vsql is a character-based, interactive, front-end utility that lets you type SQL statements and see the results. It also provides a number of meta-commands and various shell-like features that facilitate writing scripts and automating a variety of tasks. If you are using the vsql client installed on the server, then you can connect from the: Administration Tools Linux command line You can also install the vsql client for other supported platforms. A man page is available for vsql. If you are running as the dbadmin user, simply type: man vsql. If you are running as a different user, type: man -M /opt/vertica/man vsql. General Notes SQL statements can be spread over several lines for clarity. vsql can handles input and output in UTF-8 encoding. Note that the terminal emulator running vsql must be set up to display the UTF-8 characters correctly. Follow the documentation of your terminal emulator. The following example shows the settings in PuTTy from the Change Settings > Window > Translation option: HP Vertica Analytic Database (7.1.x) Page 19 of 401

20 Using vsql See also Best Practices for Working with Locales. Cancel SQL statements by typing Ctrl+C. Traverse command history by typing Ctrl+R. When you disconnect a user session, any transactions in progress are automatically rolled back. To view wide result sets, use the Linux less utility to truncate long lines. a. Before connecting to the database, specify that you want to use less for query output: $ export PAGER=less b. Connect to the database. c. Query a wide table: => select * from wide_table; HP Vertica Analytic Database (7.1.x) Page 20 of 401

21 Using vsql d. At the less prompt, type: -S If a shell running vsql fails (crashes or freezes), the vsql processes continue to run even if you stop the database. In that case, log in as root on the machine on which the shell was running and manually kill the vsql process. For example: # ps -ef grep vertica fred :02 pts/1 00:00:00 /opt/vertica/bin/vsql -p h test01_site01 quick_start_single # kill HP Vertica Analytic Database (7.1.x) Page 21 of 401

22 Using vsql Installing the vsql Client The vsql client is installed as part of the HP Vertica server rpm, but it is also available as a download for other Unix-based systems such as HP-UX, AIX, and Mac OSX. How to Install vsql on Unix-Based systems: 1. Use a web browser to log in to the myvertica portal. 2. Click the Download tab, scroll down to the CLIENT PACKAGES section and download the appropriate vsql client from the HP Vertica downloads page. Note that there are both 32-bit and 64-bit versions for most platforms. 3. Extract the tarball. The tarball is organized to extract into /opt/vertica if you extract it at the root (/) of the drive. 4. Optionally add the directory where the vsql client resides to your path. 5. Verify mode on the vsql file is executable. For example: chmod ugo+x vsql_version 6. Set your shell locale to a locale supported by vsql. For example, in your.profile, add, export LANG=en_US.UTF-8 Installing vsql on Windows: vsql on Windows is installed as part of the Windows Client Driver package. To install vsql on windows see the instructions for installing the Windows Client Driver package. See vsql Notes for Windows Users for details on using vsql in a windows console. vsql Notes for Windows Users Font Set the console font to "Lucida Console", because the raster font does not work well with the ANSI code page. Console Encoding vsql is built as a "console application." The Windows console windows use a different encoding than the rest of the system, so take care when you use 8-bit characters within vsql. If vsql detects a problematic console code page, it warns you at startup. To change the console code page, two things are necessary: HP Vertica Analytic Database (7.1.x) Page 22 of 401

23 Using vsql Set the code page by entering cmd.exe /c chcp is a code page that is appropriate for European languages; replace it with your preferred locale code page. Running Under Cygwin Verify that your cygwin.bat file does not include the "tty" flag. If the "tty" flag is included in your cywgin.bat file, then banners and prompts are not displayed in vsql. For example, change: set CYGWIN=binmode tty ntsec to: set CYGWIN=binmode ntsec Additionally, when running under Cygwin, vsql uses Cygwin shell conventions as opposed to Windows console conventions. Tab Completion Tab completion is a function of the shell, not vsql. Because of this, tab completion does not work the same way in Windows vsql as it does on Linux versions of vsql. On Windows, instead of using tab-completion. Press F7 to pop-up a history window of commands, or press F8 after typing a few letters of a command to cycle through commands in the history buffer starting with the same letters. Connecting From the Administration Tools You can use the Administration Tools to connect to a database using vsql on any node in the cluster. 1. Log in as the database administrator user; for example, dbadmin. Note: HP Vertica does not allow users with root privileges to connect to a database for security reasons. 2. Run the Administration Tools. /opt/vertica/bin/admintools 3. On the Main Menu, select Connect to Database. HP Vertica Analytic Database (7.1.x) Page 23 of 401

24 Using vsql 4. Supply the database password if asked: Password: When you create a new user with the CREATE USER command, you can configure the password or leave it empty. You cannot bypass the password if the user was created with a password configured. You can change a user's password using the ALTER USER command. 5. The Administration Tools connect to the database and transfer control to vsql. Welcome to vsql, the Vertica Analytic Database interactive terminal. Type: \h or \? for help with vsql commands \g or terminate with semicolon to execute query \q to quit => Note: See Meta-Commands for the various commands you can run while connected to the database through the Administration Tools. HP Vertica Analytic Database (7.1.x) Page 24 of 401

25 Using vsql Connecting from the Command Line You can connect to a database using vsql from the command line on multiple client platforms. Syntax /opt/vertica/bin/vsql [-h host] [ option...] [ dbname [ username ] ] Parameters host option dbname username Not required if you are connecting to a local server. You can provide an IPv4 or IPv6 IP address or a host name. One or more of the vsql Command-Line Options The name of the target database. A database username. Usage Considerations If the database is password protected, you must specify the -w or --password command line option. For HP Vertica servers that have both IPv4 and IPv6 addressed and you have provided a host name instead of an IP address, you can prefer to use an IPv4 address with the -4 option and to use the IPv6 adddress with the -6 option if the DNS is configured to provide both IPv4 and IPv6 addresses. The default values for both dbname and username is your Linux user name. If the connection cannot be made for any reason,vsql returns an error and terminates. This situation can occur if, for example, you have insufficient privileges, server is not running on the targeted host, etc.), vsql returns the following informational messages: 0 To the shell if it finished normally 1 If a fatal error occurs(such as out of memory or file not found) 2 If the connection to the server went bad and the session was not interactive HP Vertica Analytic Database (7.1.x) Page 25 of 401

26 Using vsql 3 If an error occurred in a script and the variable ON_ERROR_STOP was set Unrecognized words in the command line might be interpreted as database or user names. Examples The following example shows how you can capture any error messages by edirecting vsql output into an output file called retail_queries.out: $ vsql --echo-all < retail_queries.sql > retail_queries.out 2>&1 Command-Line Options This section contains the command-line options for vsql. General Options Option Description -c command --command command Runs one command and exits. This command is useful in shell scripts. -d dbname --dbname dbname Specifies the name of the database to which you want to connect. Using this command is equivalent to specifying dbname as the first nonoption argument on the command line. HP Vertica Analytic Database (7.1.x) Page 26 of 401

27 Using vsql -f filename --file filename Uses the file filename as the source of commands instead of reading commands interactively. After the file is processed, vsql terminates. Using this command is in many ways equivalent to the internal command \i. --help Displays help about vsql command line arguments and exits. -l --list Returns all available databases, then exits. Other nonconnection options are ignored. This command is similar to the internal command \list. HP Vertica Analytic Database (7.1.x) Page 27 of 401

28 Using vsql -v assignment --set assignment --variable assignment Performs a variable assignment, like the \set internal command. -V --version Prints the vsql version and exits. -X --no-vsqlrc Prevents the start-up file from being read (the system-wide vsqlrc file or the user's ~/.vsqlrc file). Connection Options Option Description -4 When resolving hostnames in dual stack environments, prefer IPv4 addresses. -6 When resolving hostnames in dual stack environments, prefer IPv6 addresses. -B SERVER:PORT,SERVER:PORT,... Sets connection backup server/port. Use commaseparate multiple hosts (default: not set). If using an IPv6 address, enclose the address in brackets ([, ]) and place the port outside of the brackets. For example \B [2620:0:a13:8a4:9d9f:e0e3:1181:7f51]:5433 -C --enable-connection-load-balance Enables connection load balancing (default: not enabled). Note: You can only use load balancing with one address family in dual stack environments. For example, if you've configured load balancing for IPv6 addresses, then when an IPv4 client connects and requests load balancing the server does not allow it. -h hostname --host hostname Specifies the host name of the machine on which the server is running. HP Vertica Analytic Database (7.1.x) Page 28 of 401

29 Using vsql -k KRB SERVICE Provides the service name portion of the Kerberos principal (default: vertica). Using -k is equivalent to using the drivers' KerberosServiceName connection string. -K KRB HOST Provides the instance or host name portion of the Kerberos principal. -K is equivalent to the drivers' KerberosHostName connection string. -m --sslmode Specifies the policy for making SSL connections to the server. Options are require, prefer, allow, and disable. You can also set the VSQL_SSLMODE variable to achieve the same effect. If the variable is set, the command-line option overrides it. -p port --port port Specifies the TCP port or the local socket file extension on which the server is listening for connections. Defaults to port U username --username username Connects to the database as the user username instead of the default. -w password Specifies the password for a database user. Note: Using this command-line option displays the database password in plain text. Use it with care, particularly if you are connecting as the database administrator, to avoid exposing sensitive information. -W --password Forces vsql to prompt for a password before connecting to a database. The password is not displayed on the screen. This option remains set for the entire session, even if you change the database connection with the meta-command \connect. Output Formatting Option Description -A --no-align Switches to unaligned output mode. (The default output mode is aligned.) -b Beep on command completion. -F separator --field-separator separator Specifies the field separator for unaligned output (default: " ") (-P fieldsep=). (See -A --noalign.) Using this command is equivalent to \pset fieldsep or \f. HP Vertica Analytic Database (7.1.x) Page 29 of 401

30 Using vsql -H --html Turns on HTML tabular output. Using this command is equivalent to using the \pset format html or the \H command. -P assignment --pset assignment Lets you specify printing options in the style of \pset on the command line. You must separate the name and value with an equals (=) sign instead of a space. Thus, to set the output format to LaTeX, you could write -P format=latex. -R separator --record-separator separator Uses separator as the record separator. Using this command is equivalent to using the \pset recordsep command. -t --tuples-only Disables printing of column names, result row count footers, and so on. This is equivalent to the \t command. -T table_options --table-attr table_options Allows you to specify options to be placed within the HTML table tag. See \pset for details. -x --extended Enables extended table formatting mode. This is equivalent to the command \x. Input and Output Options Option Description -a --echo-call Prints all input lines to standard output as they are read. This approach is more useful for script processing than interactive mode. It is the same as setting the variable ECHO to all. -e --echo-queries Copies all SQL commands sent to the server to standard output. Using this command is equivalent to setting the variable ECHO to queries. -E Displays queries generated by internal commands. -n Disables command line editing. -o filename --output filename Writes all query output into file filename. Using this command is equivalent to using the command \o. -q --quiet Specifies that vsql do its work quietly (without informational output, such as welcome messages). This command is useful with the -c option. Within vsql you can also set the QUIET variable to achieve the same effect. HP Vertica Analytic Database (7.1.x) Page 30 of 401

31 Using vsql -s --single-step Runs in single-step mode for debugging scripts. Forces vsql to prompt before each statement is sent to the database and allows you to cancel execution. -S --single-line Runs in single-line mode where a newline terminates a SQL command, as if you are using a semicolon. Note: This mode is provided only by customer request. Hewlett-Packard recommends that you not use single-line mode in cases where you mix SQL and meta-commands on a line. In single-line mode, the order of execution might be unclear to the inexperienced user. -c Command --command Command -c command --command command runs one command and exits. This is useful in shell scripts. Use either: A command string that can be completely parsed by the server that does not contain features specific to vsql A single meta-command You cannot mix SQL and vsql meta-commands. You can, however, pipe the string into vsql as shown: echo "\\timing\\\\select * from t"../linux64/bin/vsql Timing is on. i c v (0 rows) Note: If you use double quotes (") with echo, you must double the backslashes (\). -f Filename --file Filename -f filename --file filename uses the file filename as the source of commands instead of reading commands interactively. After the file is processed, vsql terminates. Using this command is in many ways equivalent to the internal command \i. If filename is a hyphen (-), the standard input is read. Using this option is subtly different from writing vsql < filename. In general, both do what you expect, but using -f enables some additional features such as error messages with line numbers. In some cases, using this option may also reduce start-up overhead. Conversely, the variant using HP Vertica Analytic Database (7.1.x) Page 31 of 401

32 Using vsql the shell's input redirection should always yield exactly the same output that you would have gotten had you entered everything manually. Using f filename to Read Data Piped into vsql To read data piped into vsql from a data file: 1. Create a named pipe. For example, to create a named pipe called pipe1: mkfifo pipe1 Next, create a data file. The data file in this example is called data_file Then, create a command file that: Selects the table into which you want to copy data Copies the data from the pipe file (pipe1) Removes the pipe file. The command file in the following example is called command_line. 2. From the command line, run a command that pipes the data file (data_file) into the appropriate table through vsql. The following example pipes the data file into public.shipping_dimension in the VMart database: cat data_file > pipe1 vsql -f 'command_line' Example data_file: 110 EXPRESS SEA FEDEX111 EXPRESS HAND CARRY MSC 112 OVERNIGHT COURIER USPS Example command_line file: SELECT * FROM public.shipping_dimension;\set dir `pwd`/ \set file '''':dir'pipe1''' COPY public.shipping_dimension FROM :file delimiter ' '; SELECT * FROM public.shipping_dimension; --Remove the pipe1 \! rm pipe1 -F Separator --field-separator Separator -F separator --field-separator separator specifies the field separator for unaligned output (default: " ") (-P fieldsep=). (See -A --no-align.) This is equivalent to \pset fieldsep or \f. To set the field separator value to a control character, use your shell's control character escape notation. In Bash, you specify a control character in an argument using a dollar sign ($) followed by a string contained in single quotes. This string can contain C-string escapes (such as \t for tab), or a backslash (\) followed by an octal value for the character you want to use. HP Vertica Analytic Database (7.1.x) Page 32 of 401

33 Using vsql The following example demonstrates setting the separator character to tab (\t), vertical tab (\v) and the octal value of vertical tab (\013). $ vsql -At -c "SELECT * FROM testtable;" A B $ vsql -F $'\t' -At -c "SELECT * FROM testtable;" A B $ vsql -F $'\v' -At -c "SELECT * FROM testtable;" A B $ vsql -F $'\013' -At -c "SELECT * FROM testtable;" A B h Hostname --host Hostname -h hostname --host hostname specifies the host name of the machine on which the server is running. Notes: If you are using client authentication with a Kerberos connection method of either gss or krb5, you are required to specify -h hostname. If you are using client authentication with a "local" connection type specified, and you want to match the client authentication entry, do not use -h hostname. -v Assignment --set Assignment --variable Assignment -v assignment --set assignment --variable assignment performs a variable assignment, like the \set internal command. Note: You must separate name and value, if any, by an equals sign (=) on the command line. HP Vertica Analytic Database (7.1.x) Page 33 of 401

34 Using vsql To unset a variable, omit the equal sign. To set a variable without a value, use the equals sign but omit the value. Make these assignments at a very early stage of start-up, so that variables reserved for internal purposes can get overwritten later. Connecting From a Non-Cluster Host You can use the HP Vertica vsql executable image on a non-cluster Linux host to connect to an HP Vertica database. On Red Hat bit and SUSE 10/11 64-bit, you can install the client driver RPM, which includes the vsql executable. See Installing the Client RPM on Red Hat and SUSE for details. If the non-cluster host is running the same version of Linux as the cluster, copy the image file to the remote system. For example: $ scp host01:/opt/vertica/bin/vsql.$./vsql If the non-cluster host is running a different version of Linux than your cluster hosts, and that operating system is not Red Hat version 5 64-bit or SUSE 10/11 64-bit, you must install the HP Vertica server RPM in order to get vsql. Download the appropriate rpm package from the Download tab of the myvertica portal then log into the non-cluster host as root and install the rpm package using the command: # rpm -Uvh filename Notes In the above command, filename is the package you downloaded. Note that you do not have to run the install_hp Vertica script on the non-cluster host in order to use vsql. Use the same Command-Line Options that you would on a cluster host. You cannot run vsql on a Cygwin bash shell (Windows). Use ssh to connect to a cluster host, then run vsql. HP Vertica Analytic Database (7.1.x) Page 34 of 401

35 Using vsql Meta-Commands Anything you enter in vsql that begins with an unquoted backslash is a vsql meta-command that is processed by vsql itself. These commands help make vsql more useful for administration or scripting. Meta-commands are more commonly called slash or backslash commands. The format of a vsql command is the backslash, followed immediately by a command verb, then any arguments. The arguments are separated from the command verb and each other by any number of whitespace characters. To include whitespace into an argument you can quote it with a single quote. To include a single quote into such an argument, precede it by a backslash. Anything contained in single quotes is furthermore subject to C-like substitutions for \n (new line), \t (tab), \digits, \0digits, and \0xdigits (the character with the given decimal, octal, or hexadecimal code). If an unquoted argument begins with a colon (:), it is taken as a vsql variable and the value of the variable is used as the argument instead. Arguments that are enclosed in backquotes (`) are taken as a command line that is passed to the shell. The output of the command (with any trailing newline removed) is taken as the argument value. The above escape sequences also apply in backquotes. Some commands take a SQL identifier (such as a table name) as argument. These arguments follow the syntax rules of SQL: Unquoted letters are forced to lowercase, while double quotes (") protect letters from case conversion and allow incorporation of whitespace into the identifier. Within double quotes, paired double quotes reduce to a single double quote in the resulting name. For example, FOO"BAR"BAZ is interpreted as foobarbaz, and "A weird"" name" becomes A weird" name. Parsing for arguments stops when another unquoted backslash occurs. This is taken as the beginning of a new meta-command. The special sequence \\ (two backslashes) marks the end of arguments and continues parsing SQL commands, if any. That way SQL and vsql commands can be freely mixed on a line. But in any case, the arguments of a meta-command cannot continue beyond the end of the line. \! [ COMMAND ] \? \! [ COMMAND ] executes a command in a Linux shell (passing arguments as entered) or starts an interactive shell. \? displays help information about the meta-commands. Works the same as \h. => \? General \c[onnect] [DBNAME - [USER]] connect to new database (currently "VMart") \cd [DIR] change the current working directory HP Vertica Analytic Database (7.1.x) Page 35 of 401

36 Using vsql \q quit vsql \set [NAME [VALUE]] set internal variable, or list all if no parameters \timing toggle timing of commands (currently off) \unset NAME unset (delete) internal variable \! [COMMAND] execute command in shell or start interactive shell \password [USER] change user's password Query Buffer \e [FILE] edit the query buffer (or file) with external editor \g send query buffer to server \g FILE send query buffer to server and results to file \g COMMAND send query buffer to server and pipe results to command \p show the contents of the query buffer \r reset (clear) the query buffer \s [FILE] display history or save it to file \w FILE write query buffer to file Input/Output \echo [STRING] write string to standard output \i FILE execute commands from file \o FILE send all query results to file \o COMMAND pipe all query results to command \o close query-results file or pipe \qecho [STRING] write string to query output stream (see \o) Informational \d [PATTERN] describe tables (list tables if no argument is supplied) \df [PATTERN] list functions \dj [PATTERN] list projections \dn [PATTERN] list schemas \dp [PATTERN] list table access privileges \ds [PATTERN] list sequences \ds [PATTERN] list system tables \dt [PATTERN] list tables \dtv [PATTERN] list tables and views \dt [PATTERN] list data types \du [PATTERN] list users \dv [PATTERN] list views \l list all databases \z [PATTERN] list table access privileges (same as \dp) Formatting \a toggle between unaligned and aligned output mode \b toggle beep on command completion \C [STRING] set table title, or unset if none \f [STRING] show or set field separator for unaligned query output \H toggle HTML output mode (currently off) \pset NAME [VALUE] set table output option (NAME := format border expanded fieldsep footer null recordsep tuples_only title tableattr pager) \t show only rows (currently off) \T [STRING] set HTML <table> tag attributes, or unset if none \x toggle expanded output (currently off) HP Vertica Analytic Database (7.1.x) Page 36 of 401

37 Using vsql \a \b \a toggles output format alignment. This command is kept for backwards compatibility. See \pset for a more general solution. \a is similar to the command line option -A --no-align, which only disables alignment. \b toggles beep on command completion. \c (or \connect) [ Dbname [ Username ] ] \c (or \connect) [ dbname [ username ] ] establishes a connection to a new database and/or under a user name. The previous connection is closed. If dbname is - the current database name is assumed. If username is omitted the current user name is assumed. As a special rule, \connect without any arguments connects to the default database as the default user (as you would have gotten by starting vsql without any arguments). If the connection attempt fails (wrong user name, access denied, or other error messages), the previous connection is kept if and only if vsql is in interactive mode. When executing a noninteractive script, processing immediately stops with an error. This is a distinction that avoids typos and prevents scripts from accidentally acting on the wrong database. \C [ STRING ] \C [ STRING ] sets the title of any tables being printed as the result of a query or unsets any such title. This command is equivalent to \pset title title. (The name of this command derives from "caption," as it was previously only used to set the caption in an HTML table.) \cd [ DIR ] \cd [ DIR ] changes the current working directory to directory. Without argument, changes to the current user's home directory. To print your current working directory, use \! pwd. For example: => \!pwd /home/dbadmin The \d [ PATTERN ] Meta-Commands This section describes the various \d meta-commands. HP Vertica Analytic Database (7.1.x) Page 37 of 401

38 Using vsql All \d meta-commands take an optional pattern (asterisk [ * ] or question mark [? ]) and return only the records that match that pattern. The? argument is useful if you can't remember if a table name uses an underscore or a dash: => \dn v?internal List of schemas Name Owner v_internal dbadmin (1 row) The output from the \d metacommands places double quotes around non-alphanumeric table names and table names that are keywords, such as in the following example. => CREATE TABLE my_keywords.precision(x numeric (4,2)); CREATE TABLE => \d List of tables Schema Name Kind Owner my_keywords "precision" table dbadmin Double quotes are optional when you use a \d command with pattern matching. \d [ PATTERN ] The \d meta-command lists all tables in the database and returns their schema, table name, kind (e.g., table), and owner. If you use \d [ PATTERN ] and provide the schema name or table name (or wildcard or? characters) as the pattern argument, the result shows more detailed information about the tables: Schema name Table name Column name Column data type Data type size Default column value Whether the column accepts null values or has a NOT NULL constraint Whether there is a primary key or foreign key constraint To view information about system tables, you must include the V_MONITOR or V_CATALOG as the pattern argument; for example: HP Vertica Analytic Database (7.1.x) Page 38 of 401

39 Using vsql \d v_catalog.types -- information on the types table in v_catalog schema \d v_catalog.* -- information on all table columns in v_catalog schema The following output is the result of all tables in the vmart schema, which is in the PUBLIC schema. VMart=> \d List of tables Schema Name Kind Owner online_sales call_center_dimension table dbadmin online_sales online_page_dimension table dbadmin online_sales online_sales_fact table dbadmin public customer_dimension table dbadmin public date_dimension table dbadmin public employee_dimension table dbadmin public inventory_fact table dbadmin public product_dimension table dbadmin public promotion_dimension table dbadmin public shipping_dimension table dbadmin public vendor_dimension table dbadmin public warehouse_dimension table dbadmin store store_dimension table dbadmin store store_orders_fact table dbadmin store store_sales_fact table dbadmin (15 rows) This example returns information on the inventory_fact table in the VMart database: VMart=> \x Expanded display is on. VMart=> \d inventory_fact List of Fields by Tables -[ RECORD 1 ] Schema public Table inventory_fact Column date_key Type int Size 8 Default Not Null t Primary Key f Foreign Key public.date_dimension(date_key) -[ RECORD 2 ] Schema public Table inventory_fact Column product_key Type int Size 8 Default Not Null t Primary Key f Foreign Key public.product_dimension(product_key) -[ RECORD 3 ] Schema public HP Vertica Analytic Database (7.1.x) Page 39 of 401

40 Using vsql Table inventory_fact Column product_version Type int Size 8 Default Not Null t Primary Key f Foreign Key public.product_dimension(product_version) -[ RECORD 4 ] Schema public Table inventory_fact Column warehouse_key Type int Size 8 Default Not Null t Primary Key f Foreign Key public.warehouse_dimension(warehouse_key) -[ RECORD 5 ] Schema public Table inventory_fact Column qty_in_stock Type int Size 8 Default Not Null f Primary Key f Foreign Key Use the question mark [? ] argument to replace a single character. For example, the? argument replaces the last character in the user-created SubQ1 and SubQ2 tables, so the command returns information about both: => \d SubQ? List of Fields by Tables Schema Table Column Type Size Default Not Null Primary Key Foreign Key public SubQ1 a int 8 f f public SubQ1 b int 8 f f public SubQ1 c int 8 f f public SubQ2 x int 8 f f public SubQ2 y int 8 f f public SubQ2 z int 8 f f (6 rows) If you run the \d command and provide both the schema and table name, output includes columns for tables that match the pattern VMart=> \x Expanded display is on. VMart=> \d v_catalog.types List of Fields by Tables -[ RECORD 1 ] HP Vertica Analytic Database (7.1.x) Page 40 of 401

41 Using vsql Schema v_catalog Table types Column column_size Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 2 ] Schema v_catalog Table types Column creation_parameters Type varchar(128) Size 128 Default Not Null f Primary Key f Foreign Key -[ RECORD 3 ] Schema v_catalog Table types Column epoch Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 4 ] Schema v_catalog Table types Column interval_mask Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 5 ] Schema v_catalog Table types Column max_scale Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 6 ] Schema v_catalog Table types Column min_scale Type int Size 8 Default Not Null f Primary Key f HP Vertica Analytic Database (7.1.x) Page 41 of 401

42 Using vsql Foreign Key -[ RECORD 7 ] Schema v_catalog Table types Column odbc_subtype Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 8 ] Schema v_catalog Table types Column odbc_type Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 9 ] Schema v_catalog Table types Column type_id Type int Size 8 Default Not Null f Primary Key f Foreign Key -[ RECORD 10 ] Schema v_catalog Table types Column type_name Type varchar(128) Size 128 Default Not Null f Primary Key f Foreign Key To view all tables in a schema, use the wildcard character. The following command would return all system tables in the V_CATALOG schema: => \d v_catalog.* \df [ PATTERN ] The \df [ PATTERN ] meta-command returns all function names, the function return data type, and the function argument data type. Also returns the procedure names and arguments for all procedures that are available to the user. HP Vertica Analytic Database (7.1.x) Page 42 of 401

43 Using vsql vmartdb=> \df List of functions procedure_name procedure_return_type procedure_argument_types abs Float Float abs Integer Integer abs Interval Interval abs Interval Interval abs Numeric Numeric acos Float Float... width_bucket Integer Float, Float, Float, Integer width_bucket Integer Interval, Interval, Interval, Integer width_bucket Integer Interval, Interval, Interval, Integer width_bucket Integer Timestamp, Timestamp, Timestamp, Integer... The following example uses the wildcard character to search for all functions that begin with as: vmartdb=> \df as* List of functions procedure_name procedure_return_type procedure_argument_types ascii Integer Varchar asin Float Float (2 rows) \dj [ PATTERN ] The \dj [ PATTERN ] meta-command returns all projections showing the schema, projection name, owner, and node. The returned rows include superprojections, live aggregate projections, Top-K projections, and projections with expressions: vmartdb=> \dj List of projections Schema Name Owner Node public product_dimension_node0001 dbadmin v_wmartdb_node0001 public product_dimension_node0002 dbadmin v_wmartdb_node0002 public product_dimension_node0003 dbadmin v_wmartdb_node0003 online_sales call_center_dimension_node0001 dbadmin v_wmartdb_node0001 online_sales call_center_dimension_node0002 dbadmin v_wmartdb_node0002 online_sales call_center_dimension_node0003 dbadmin v_wmartdb_node If you supply a projection name as an argument, the system returns fewer records: vmartdb=> \dj call_center_dimension_n* List of projections Schema Name Owner Node online_sales call_center_dimension_node0001 dbadmin v_wmartdb_node0001 HP Vertica Analytic Database (7.1.x) Page 43 of 401

44 Using vsql online_sales call_center_dimension_node0002 dbadmin v_wmartdb_node0002 online_sales call_center_dimension_node0003 dbadmin v_wmartdb_node0003 (3 rows) \dn [ PATTERN ] The \dn [ PATTERN ] meta-command returns the schema names and schema owner. vmartdb=> \dn List of schemas Name Owner v_internal dbadmin v_catalog dbadmin v_monitor dbadmin public dbadmin store dbadmin online_sales dbadmin (6 rows) The following command returns all schemas that begin with the letter v: => \dn v* List of schemas Name Owner v_internal dbadmin v_catalog dbadmin v_monitor dbadmin (3 rows) \dp [ PATTERN ] The \dp [ PATTERN ] meta-command returns the grantee, grantor, privileges, schema, and name for all table access privileges in each schema: vmartdb=> \dp Access privileges for database "vmartdb" Grantee Grantor Privileges Schema Name dbadmin USAGE public dbadmin USAGE v_internal dbadmin USAGE v_catalog dbadmin USAGE v_monitor (4 rows) Note: \dp is the same as \z. HP Vertica Analytic Database (7.1.x) Page 44 of 401

45 Using vsql \ds [ PATTERN ] The \ds [ PATTERN ] meta-command (lowercase s) returns a list of sequences and their parameters. The following series of commands creates a sequence called my_seq and uses the vsql command to display its parameters: => CREATE SEQUENCE my_seq MAXVALUE 5000 START 150; CREATE SEQUENCE => \ds List of Sequences Schema Sequence CurrentValue IncrementBy Minimum Maximum AllowCycle public my_seq f (1 row) Note: You can return additional information about sequences by issuing SELECT * FROM SEQUENCES, as described in the SQL Reference Manual. \ds [ PATTERN ] The \ds [ PATTERN ] meta-command (uppercase S) returns all system table (monitoring API) names from the V_CATALOG and V_MONITOR schemas. Tip: You can get identical results running this query: SELECT * FROM system_tables; If you specify a schema name, you can view results for tables in that schema only; however, you must use the wildcard character. For example: => \ds v_catalog.* You can also run the \ds command with a table argument to return information for that table only: vmartdb=> \ds columns List of tables Schema Name Kind Description Comment v_catalog columns system Table column information (1 row) If you provide the schema name with the table name, the output returns information about the table: vmartdb=> \ds v_catalog.types List of tables Schema Name Kind Description Comment HP Vertica Analytic Database (7.1.x) Page 45 of 401

46 Using vsql v_catalog types system Information about supported data types (1 row) \dt [ PATTERN ] The \dt [ PATTERN ] meta-command (lowercase t) is identical to \d and returns all tables in the database unless a table name is specified in which case the command lists only the schema, name, kind and owner for the specified table (or tables if wildcards used). vmartdb=> \dt inventory_fact List of tables Schema Name Kind Owner public inventory_fact table dbadmin (1 row) The following command returns all table names that begin with "st": vmartdb=> \dt st* List of tables Schema Name Kind Owner store store_dimension table dbadmin store store_orders_fact table dbadmin store store_sales_fact table dbadmin (3 rows) \dt [ PATTERN ] The \dt [ PATTERN ] meta-command (uppercase T) lists all supported data types. vmartdb=> \dt List of data types type_name Binary Boolean Char Date Float Integer Interval Day Interval Day to Hour Interval Day to Minute Interval Day to Second Interval Hour HP Vertica Analytic Database (7.1.x) Page 46 of 401

47 Using vsql Interval Hour to Minute Interval Hour to Second Interval Minute Interval Minute to Second Interval Month Interval Second Interval Year Interval Year to Month Numeric Time TimeTz Timestamp TimestampTz Varbinary Varchar (26 rows) \dtv [ PATTERN ] The \dtv [ PATTERN ] meta-command lists all tables and views, returning the schema, table or view name, kind (table of view), and owner. vmartdb=> \dtv List of tables Schema Name Kind Owner online_sales call_center_dimension table release online_sales online_page_dimension table release online_sales online_sales_fact table release public customer_dimension table release public date_dimension table release public employee_dimension table release public inventory_fact table release public product_dimension table release public promotion_dimension table release public shipping_dimension table release public vendor_dimension table release public warehouse_dimension table release store store_dimension table release store store_orders_fact table release store store_sales_fact table release (15 rows) \du [ PATTERN ] The \du [ PATTERN ] meta-command returns all database users and attributes, such as if user is a superuser. vmartdb=> \du List of users User name Is Superuser HP Vertica Analytic Database (7.1.x) Page 47 of 401

48 Using vsql dbadmin (1 row) t \dv [ PATTERN ] The \dv [ PATTERN ] meta-command returns the schema name, view name, and view owner. The following example defines a view using the SEQUENCES system table: vmartdb=> CREATE VIEW my_seqview AS (SELECT * FROM sequences); CREATE VIEW vmartdb=> \dv List of views Schema Name Owner public my_seqview dbadmin (1 row) If a view name is provided as an argument, the result shows the schema, view name, and the following for all columns within the view's result set: schema name, view name, column name, column data type, and data type size. vmartdb=> \dv my_seqview List of View Fields Schema View Column Type Size public my_seqview sequence_schema varchar(128) 128 public my_seqview sequence_name varchar(128) 128 public my_seqview owner_name varchar(128) 128 public my_seqview identity_table_name varchar(128) 128 public my_seqview session_cache_count int 8 public my_seqview allow_cycle boolean 1 public my_seqview output_ordered boolean 1 public my_seqview increment_by int 8 public my_seqview minimum int 8 public my_seqview maximum int 8 public my_seqview current_value int 8 public my_seqview sequence_schema_id int 8 public my_seqview sequence_id int 8 public my_seqview owner_id int 8 public my_seqview identity_table_id int 8 (15 rows) \e \edit [ FILE ] \e \edit [ FILE ] edits the query buffer (or specified file) with an external editor. When the editor exits, its content is copied back to the query buffer. If no argument is given, the current query buffer is copied to a temporary file which is then edited in the same fashion. The new query buffer is then re-parsed according to the normal rules of vsql, where the whole buffer up to the first semicolon is treated as a single line. (Thus you cannot make scripts this way. Use \i HP Vertica Analytic Database (7.1.x) Page 48 of 401

49 Using vsql for that.) If there is no semicolon, vsql waits for one to be entered (it does not execute the query buffer). Tip: vsql searches the environment variables VSQL_EDITOR, EDITOR, and VISUAL (in that order) for an editor to use. If all of them are unset, vi is used on Linux systems, notepad.exe on Windows systems. \echo [ STRING ] \echo [ STRING ] writes the string to standard output. Tip: If you use the \o command to redirect your query output you might want to use \qecho instead of this command. \f [ String ] \g \f [ string ] sets the field separator for unaligned query output. The default is the vertical bar ( ). See also \pset for a generic way of setting output options. The \g meta-command sends the query in the input buffer (see \p ) to the server. With no arguments, it displays the results in the standard way. \g FILE sends the query input buffer to the server, and writes the results to FILE. \g COMMAND sends the query buffer to the server, and pipes the results to a shell COMMAND. See Also \H \o \H toggles HTML query output format. This command is for compatibility and convenience, but see \pset about setting other output options. \h \help \h \help displays help information about the meta-commands. Works the same as \?. => \h General \c[onnect] [DBNAME - [USER]] connect to new database (currently "VMart") HP Vertica Analytic Database (7.1.x) Page 49 of 401

50 Using vsql \cd [DIR] change the current working directory \q quit vsql \set [NAME [VALUE]] set internal variable, or list all if no parameters \timing toggle timing of commands (currently off) \unset NAME unset (delete) internal variable \! [COMMAND] execute command in shell or start interactive shell \password [USER] change user's password Query Buffer \e [FILE] edit the query buffer (or file) with external editor \g send query buffer to server \g FILE send query buffer to server and results to file \g COMMAND send query buffer to server and pipe results to command \p show the contents of the query buffer \r reset (clear) the query buffer \s [FILE] display history or save it to file \w FILE write query buffer to file Input/Output \echo [STRING] write string to standard output \i FILE execute commands from file \o FILE send all query results to file \o COMMAND pipe all query results to command \o close query-results file or pipe \qecho [STRING] write string to query output stream (see \o) Informational \d [PATTERN] describe tables (list tables if no argument is supplied) \df [PATTERN] list functions \dj [PATTERN] list projections \dn [PATTERN] list schemas \dp [PATTERN] list table access privileges \ds [PATTERN] list sequences \ds [PATTERN] list system tables \dt [PATTERN] list tables \dtv [PATTERN] list tables and views \dt [PATTERN] list data types \du [PATTERN] list users \dv [PATTERN] list views \l list all databases \z [PATTERN] list table access privileges (same as \dp) Formatting \a toggle between unaligned and aligned output mode \b toggle beep on command completion \C [STRING] set table title, or unset if none \f [STRING] show or set field separator for unaligned query output \H toggle HTML output mode (currently off) \pset NAME [VALUE] set table output option (NAME := format border expanded fieldsep footer null recordsep tuples_only title tableattr pager) \t show only rows (currently off) \T [STRING] set HTML <table> tag attributes, or unset if none \x toggle expanded output (currently off) HP Vertica Analytic Database (7.1.x) Page 50 of 401

51 Using vsql \i FILE \i filename command reads input from the file filename and executes it as though it had been typed on the keyboard. Note: To see the lines on the screen as they are read, set the variable ECHO to all. \l \l provides a list of databases and their owners. vmartdb=> \l List of databases name user_name vmartdb dbadmin (1 row) Locale The vsql \locale command displays the current locale setting or lets you set a new locale for the session. This command does not alter the default locale for all database sessions. To change the default for all sessions, set the DefaultSessionLocale configuration parameter. Viewing the Current Locale Setting To view the current locale setting, use the vsql command \locale, as follows: => \locale en_us@collation=binary Overriding the Default Local for a Session To override the default local for a specific session, use the vsql command \locale <ICU-localeidentifier>. The session locale setting applies to any subsequent commands issued in the session. For example: \locale en_gbinfo: INFO 2567: Canonical locale: 'en_gbinfo:' Standard collation: 'LEN' English (GBINFO:) HP Vertica Analytic Database (7.1.x) Page 51 of 401

52 Using vsql Notes \o The server locale settings impact only the collation behavior for server-side query processing. The client application is responsible for ensuring that the correct locale is set in order to display the characters correctly. Below are the best practices recommended by HP to ensure predictable results: The locale setting in the terminal emulator for vsql (POSIX) should be set to be equivalent to session locale setting on server side (ICU) so data is collated correctly on the server and displayed correctly on the client. The vsql locale should be set using the POSIX LANG environment variable in terminal emulator. Refer to the documentation of your terminal emulator for how to set locale. Server session locale should be set using the set as described in Specify the Default Locale for the Database. Note that all input data for vsql should be in UTF-8 and all output data is encoded in UTF-8. Non UTF-8 encodings and associated locale values are not supported. The \o meta-command is used to control where vsql directs its query output. The output can be written to a file, piped to a shell command, or sent to the standard output. \o FILE sends all subsequent query output to FILE. \o COMMAND pipes all subsequent query output to a shell COMMAND. \o with no argument closes any open file or pipe, and switches back to normal query result output. Notes Query results includes all tables, command responses, and notices obtained from the database server. To intersperse text output with query results, use \qecho. See Also \p \g \p prints the current query buffer to the standard output. For example: HP Vertica Analytic Database (7.1.x) Page 52 of 401

53 Using vsql => \p CREATE VIEW my_seqview AS (SELECT * FROM sequences); \password [ USER ] \password starts the password change process. Users can only change their own passwords. The command prompts the user for the old password, a new password, and then the new password again to confirm. A superuser can change the password of another user by supplying the username. A superuser is not prompted for the old password, either when changing his or her own password, or when changing another user's password. Note: If you want to cancel the password change process, press ENTER until you return the to vsql prompt. \pset NAME [ VALUE ] \pset NAME [ VALUE ] sets options affecting the output of query result tables. NAME describes which option to set, as illustrated in the following table. The parameters of VALUE depend thereon. It is an error to call \pset without arguments. Adjustable printing options are: format Sets the output format to one of unaligned, aligned, html, or latex. Unique abbreviations are allowed. (That would mean one letter is enough.) "Unaligned" writes all columns of a row on a line, separated by the currently active field separator. This is intended to create output that might be intended to be read in by other programs (tab- separated, comma-separated). "Aligned" mode is the standard, human-readable, nicely formatted text output that is default. The "HTML" and "LaTeX" modes put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! (This might not be so dramatic in HTML, but in LaTeX you must have a complete document wrapper.) border The second argument must be a number. In general, the higher the number the more borders and lines the tables have, but this depends on the particular format. In HTML mode, this translates directly into the border=... attribute, in the others only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense. HP Vertica Analytic Database (7.1.x) Page 53 of 401

54 Using vsql expanded Toggles between regular and expanded format. When expanded format is enabled, all output has two columns with the column name on the left and the data on the right. This mode is useful if the data wouldn't fit on the screen in the normal "horizontal" mode. Expanded mode is supported by all four output formats. \x is the same as \pset expanded. fieldsep footer null recordsep tuples_only (or t) title [ text ] tableattr (or T)[ text ] pager Specifies the field separator to be used in unaligned output mode. That way one can create, for example, tab- or comma-separated output, which other programs might prefer. To set a tab as field separator, type \pset fieldsep '\t'. The default field separator is ' ' (a vertical bar). Toggles the display of the default footer (x rows). The second argument is a string that is printed whenever a column is null. The default is not to print anything, which can easily be mistaken for, say, an empty string. Thus, one might choose to write \pset null '(null)'. Specifies the record (line) separator to use in unaligned output mode. The default is a newline character. Toggles between tuples only and full display. Full display might show extra information such as column headers, titles, and various footers. In tuples only mode, only actual table data is shown. Sets the table title for any subsequently printed tables. This can be used to give your output descriptive tags. If no argument is given, the title is unset. Allows you to specify any attributes to be placed inside the HTML table tag. This could for example be cellpadding or bgcolor. Note that you probably don't want to specify border here, as that is already taken care of by \pset border. Controls use of a pager for query and vsql help output. If the environment variable PAGER is set, the output is piped to the specified program. Otherwise a platform-dependent default (such as more) is used. When the pager is off, the pager is not used. When the pager is on, the pager is used only when appropriate; that is, the output is to a terminal and does not fit on the screen. (vsql does not do a perfect job of estimating when to use the pager.) \pset pager turns the pager on and off. Pager can also be set to always, which causes the pager to be always used. See illustrations on how these different formats look in the Examples section. HP Vertica Analytic Database (7.1.x) Page 54 of 401

55 Using vsql Tip: There are various shortcut commands for \pset. See \a, \C, \H, \t, \T, and \ x. \q \q quits the vsql program. \qecho [ STRING ] \r \qecho [ STRING ] is identical to \echo except that the output is written to the query output stream, as set by \o. \r resets (clears) the query buffer. For example, run the \p meta-command to see what is in the query buffer: => \p CREATE VIEW my_seqview AS (SELECT * FROM sequences); Now reset the query buffer: => \r Query buffer reset (cleared). If you reissue the command to see what's in the query buffer, you can see it is now empty: => \p Query buffer is empty. \s [ FILE ] \s [ FILE ] prints or saves the command line history to filename. If a filename is not specified, \s writes the history to the standard output. This option is only available if vsql is configured to use the GNU Readline library. \set [ NAME [ VALUE [... ] ] ] \set [ name [ value [... ] ] ] sets the internal variable name to value or, if more than one value is given, to the concatenation of all of values. If no second argument is given, the variable is set with no value. If no argument is provided, \set lists all internal variables; for example: HP Vertica Analytic Database (7.1.x) Page 55 of 401

56 Using vsql => \set VERSION = 'Vertica Analytic Database v ' AUTOCOMMIT = 'off' VERBOSITY = 'default' PROMPT1 = '%/%R%# ' PROMPT2 = '%/%R%# ' PROMPT3 = '>> ' ROWS_AT_A_TIME = '1000' DBNAME = 'VMartDB' USER = 'dbadmin' HOST = '<host_ip_address>' PORT = '5433' LOCALE = 'en_us@collation=binary' HISTSIZE = '500' Notes Valid variable names are case sensitive and can contain characters, digits, and underscores. vsql treats several variables as special, which are described in Variables. The \set parameter ROWS_AT_A_TIME defaults to It retrieves results as blocks of rows of that size. The column formatting for the first block is used for all blocks, so in later blocks some entries could overflow. See \timing for examples. When formatting results, HP Vertica buffers ROWS_AT_A_TIME rows in memory to calculate the maximum column widths. It is possible that rows after this initial fetch are not properly aligned if any of the field values are longer than those see in the first ROWS_AT_A_TIME rows. ROWS_AT_A_TIME can be \unset to guarantee perfect alignment, but this requires rebuffering the entire result set in memory and may cause vsql to fail if the result set is too big. To unset a variable, use the \unset command. Using Backquotes to Read System Variables In vsql, the contents of backquotes are passed to the system shell to be interpreted (the same behavior as many UNIX shells). This is particularly useful in setting internal vsql variables, since you may want to access UNIX system variables (such as HOME or TMPDIR) rather than hardcode values. For example, if you want to set an internal variable to the full path for a file in your UNIX user directory, you could use backquotes to get the content of the system HOME variable, which is the full path to your user directory: => \set inputfile `echo $HOME`/myinput.txt=> \echo :inputfile /home/dbadmin/myinput.txt The contents of the backquotes are replaced with the results of running the contents in a system shell interpreter. In this case, the echo $HOME command returns the contents of the HOME system variable. HP Vertica Analytic Database (7.1.x) Page 56 of 401

57 Using vsql \t \t toggles the display of output column name headings and row count footer. This command is equivalent to \pset tuples_only and is provided for convenience. \T [ STRING ] \T [ STRING ] specifies attributes to be placed within the table tag in HTML tabular output mode. This command is equivalent to \pset tableattr table_options. \timing \timing toggles the timing of commands (currently off). The meta-command displays how long each SQL statement takes, in milliseconds, and reports both the time required to fetch the first block of rows from the server and the total until the last block is formatted. Example => \o /dev/null=> SELECT * FROM fact LIMIT ; Time: First fetch (1000 rows): ms. All rows formatted: ms Note that the database retrieved the first 1000 rows in 22 ms and completed retrieving and formatting all rows in 235 ms. See Also \set [ NAME [ VALUE [... ] ] ] \unset [ NAME ] \unset [ NAME ] unsets (deletes) the internal variable name that was set using the \set metacommand. \w [ FILE ] \x \w [ FILE ] outputs the current query buffer to the file filename. \x toggles extended table formatting mode. Is equivalent to \pset expanded. Note: There is no space between the backslash and the x. HP Vertica Analytic Database (7.1.x) Page 57 of 401

58 Using vsql \z \z lists table access privileges (grantee, grantor, privilege, and name) for all table access privileges in each schema. Is the same as \dp. HP Vertica Analytic Database (7.1.x) Page 58 of 401

59 Using vsql Variables vsql provides variable substitution features similar to common Linux command shells. Variables are simply name/value pairs, where the value can be any string of any length. To set variables, use the vsql meta-command \set : => \set fact dim sets the variable fact to the value dim. To retrieve the content of the variable, precede the name with a colon and use it as the argument of any slash command: => \echo :fact dim Note: The arguments of \set are subject to the same substitution rules as with other commands. For example, \set dim :fact is a valid way to copy a variable. If you call \set without a second argument, the variable is set, with an empty string as value. To unset (or delete) a variable, use the command \unset. vsql's internal variable names can consist of letters, numbers, and underscores in any order and any number. Some of these variables are treated specially by vsql. They indicate certain option settings that can be changed at run time by altering the value of the variable or represent some state of the application. Although you can use these variables for any other purpose, this is not recommended. By convention, all specially treated variables consist of all upper-case letters (and possibly numbers and underscores). To ensure maximum compatibility in the future, avoid using such variable names for your own purposes. SQL Interpolation An additional useful feature of vsql variables is that you can substitute ("interpolate") them into regular SQL statements. The syntax for this is again to prepend the variable name with a colon (:). => \set fact 'my_table' => SELECT * FROM :fact; would then query the table my_table. The value of the variable is copied literally (except for backquoted strings, see below), so it can even contain unbalanced quotes or backslash commands. Make sure that it makes sense where you put it. Variable interpolation is not performed into quoted SQL entities. Note: The one exception to variable values being copied literally is strings in backquotes (``). The contents of backquoted strings are passed to a system shell, and replaced with the shell's output. See the set metacommand topic for details. HP Vertica Analytic Database (7.1.x) Page 59 of 401

60 Using vsql AUTOCOMMIT When AUTOCOMMIT is set 'on', each SQL command is automatically committed upon successful completion; for example: \ set AUTOCOMMIT on To postpone COMMIT in this mode, set the value as off. \set AUTOCOMMIT off If AUTOCOMMIT is empty or defined as off, SQL commands are not committed unless you explicitly issue COMMIT. Notes AUTOCOMMIT is off by default. AUTOCOMMIT must be in uppercase, but the values, on or off, are case insensitive. In autocommit-off mode, you must explicitly abandon any failed transaction by entering ABORT or ROLLBACK. If you exit the session without committing, your work is rolled back. Validation on vsql variables is done when they are run, not when they are set. The COPY statement, by default, commits on completion, so it does not matter which AUTOCOMMIT mode you use, unless you issue COPY NO COMMIT. Please note that DDL statements are autocommitted. To tell if AUTOCOMMIT is on or off, issue the set command: $ \set... AUTOCOMMIT = 'off'... AUTOCOMMIT is off if a SELECT * FROM LOCKS shows locks from the statement you just ran. $ \set AUTOCOMMIT off $ \set... AUTOCOMMIT = 'off'... SELECT COUNT(*) FROM customer_dimension; count HP Vertica Analytic Database (7.1.x) Page 60 of 401

61 Using vsql (1 row) SELECT node_names, object_name, lock_mode, lock_scope FROM LOCKS; node_names object_name lock_mode lock_scope site01 Table:customer_dimension S TRANSACTION (1 row) DBNAME The name of the database to which you are currently connected. DBNAME is set every time you connect to a database (including program startup), but it can be unset. ECHO If set to all, all lines entered from the keyboard or from a script are written to the standard output before they are parsed or run. To select this behavior on program start-up, use the switch -a. If set to queries, vsql merely prints all queries as they are sent to the server. The switch for this is -e. ECHO_HIDDEN When this variable is set and a backslash command queries the database, the query is first shown. This way you can study the HP Vertica internals and provide similar functionality in your own programs. (To select this behavior on program start-up, use the switch -E.) If you set the variable to the value noexec, the queries are just shown but are not actually sent to the server and run. ENCODING The current client character set encoding. HISTCONTROL If this variable is set to ignorespace, lines that begin with a space are not entered into the history list. If set to a value of ignoredups, lines matching the previous history line are not entered. A value of ignoreboth combines the two options. If unset, or if set to any other value than those previously mentioned, all lines read in interactive mode are saved on the history list. Source: Bash. HISTSIZE The number of commands to store in the command history. The default value is 500. HP Vertica Analytic Database (7.1.x) Page 61 of 401

62 Using vsql Source: Bash. HOST The database server host you are currently connected to. This is set every time you connect to a database (including program startup), but can be unset. IGNOREEOF If unset, sending an EOF character (usually Control+D) to an interactive session of vsql terminates the application. If set to a numeric value, that many EOF characters are ignored before the application terminates. If the variable is set but has no numeric value, the default is 10. Source: Bash. ON_ERROR_STOP By default, if a script command results in an error, for example, because of a malformed command or invalid data format, processing continues. If you set ON_ERROR_STOP to on in a script and an error occurs during processing, the script terminates immediately. If you set ON_ERROR_STOP to on in a script, run the script from Linux using vsql -f <filename>, and an error occurs, vsql returns an error code 3 to Linux to indicate that the error occurred in a script. To enable ON_ERROR_STOP: => \set ON_ERROR_STOP on To disable ON_ERROR_STOP: => \set ON_ERROR_STOP off PORT The database server port to which you are currently connected. This is set every time you connect to a database (including program start-up), but can be unset. PROMPT1 PROMPT2 PROMPT3 These specify what the prompts vsql issues look like. See Prompting for details. QUIET This variable is equivalent to the command line option -q. It is probably not too useful in interactive mode. HP Vertica Analytic Database (7.1.x) Page 62 of 401

63 Using vsql SINGLELINE This variable is equivalent to the command line option -S. SINGLESTEP This variable is equivalent to the command line option -s. USER The database user you are currently connected as. This is set every time you connect to a database (including program startup), but can be unset. VERBOSITY This variable can be set to the values default, verbose, or terse to control the verbosity of error reports. VSQL_HOME By default, the vsql program reads configuration files from the user's home directory. In cases where this is not desirable, the configuration file location can be overridden by setting the VSQL_ HOME environment variable in a way that does not require modifying a shared resource. In the following example, vsql reads configuration information out of /tmp/jsmith rather than out of ~. # Make an alternate configuration file in /tmp/jsmith mkdir -p /tmp/jsmith echo "\\echo Using VSQLRC in tmp/jsmith" > /tmp/jsmith/.vsqlrc # Note that nothing is echoed when invoked normally vsql # Note that the.vsqlrc is read and the following is # displayed before the vsql prompt # # Using VSQLRC in tmp/jsmith VSQL_HOME=/tmp/jsmith vsql VSQL_SSLMODE VSQL_SSLMODE specifies how (or whether) clients (like admintools) use SSL when connecting to servers. The default value is prefer, meaning to use SSL if the server offers it. Legal values are require, prefer, allow, and disable. This variable is equivalent to the command-line -m option (or --sslmode). HP Vertica Analytic Database (7.1.x) Page 63 of 401

64 Using vsql Prompting The prompts vsql issues can be customized to your preference. The three variables PROMPT1, PROMPT2, and PROMPT3 contain strings and special escape sequences that describe the appearance of the prompt. Prompt 1 is the normal prompt that is issued when vsql requests a new command. Prompt 2 is issued when more input is expected during command input because the command was not terminated with a semicolon or a quote was not closed. Prompt 3 is issued when you run a SQL COPY command and you are expected to type in the row values on the terminal. The value of the selected prompt variable is printed literally, except where a percent sign (%) is encountered. Depending on the next character, certain other text is substituted instead. Defined substitutions are: %M The full host name (with domain name) of the database server, or [local] if the connection is over a socket, or [local:/dir/name], if the socket is not at the compiled in default location. %m The host name of the database server, truncated at the first dot, or [local]. %> The port number at which the database server is listening. %n The database session user name. %/ The name of the current database. %~ Like %/, but the output is ~ (tilde) if the database is your default database. %# If the session user is a database superuser, then a #, otherwise a >. (The expansion of this value might change during a database session as the result of the command SET SESSION AUTHORIZATION.) %R In prompt 1 normally =, but ^ if in single-line mode, and! if the session is disconnected from the database (which can happen if \connect fails). In prompt 2 the sequence is replaced by -, *, a single quote, a double quote, or a dollar sign, depending on whether vsql expects more input because the command wasn't terminated yet, because you are inside a /*... */ comment, or because you are inside a quoted or dollar-escaped string. In prompt 3 the sequence doesn't produce anything. %x Transaction status: an empty string when not in a transaction block, or * when in a transaction block, or! when in a failed transaction block, or? when the transaction state is indeterminate (for example, because there is no connection). %digits %:name: The character with the indicated numeric code is substituted. If digits starts with 0x the rest of the characters are interpreted as hexadecimal; otherwise if the first digit is 0 the digits are interpreted as octal; otherwise the digits are read as a decimal number. The value of the vsql variable name. See the section Variables for details. HP Vertica Analytic Database (7.1.x) Page 64 of 401

65 Using vsql %`command` The output of command, similar to ordinary "back- tick" substitution. %[... %] Prompts may contain terminal control characters which, for example, change the color, background, or style of the prompt text, or change the title of the terminal window. In order for the line editing features of Readline to work properly, these nonprinting control characters must be designated as invisible by surrounding them with %[ and %]. Multiple pairs of these may occur within the prompt. The following example results in a boldfaced (1;) yellow-on-black (33;40) prompt on VT100- compatible, color-capable terminals: testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%#%[%033[0m%] ' To insert a percent sign into your prompt, write %%. The default prompts are '%/%R%# ' for prompts 1 and 2, and '>> ' for prompt 3. Note: See the specification for terminal control sequences (applicable to gnometerminal and xterm). Command Line Editing vsql supports the tecla library for convenient line editing and retrieval. The command history is automatically saved when vsql exits and is reloaded when vsql starts up. Tab-completion is also supported, although the completion logic makes no claim to be a SQL parser. If for some reason you do not like the tab completion, you can turn it off by putting this in a file named.teclarc in your home directory: bind ^I Read the tecla documentation for further details. Notes The vsql implementation of the tecla library deviates from the tecla documentation as follows: Recalling Previously Typed Lines Under pure tecla, all new lines are appended to a list of historical input lines maintained within the GetLine resource object. In vsql, only different, non-empty lines are appended to the list of historical input lines. History Files tecla has no standard name for the history file. In vsql, the file name is called ~/.vsql_hist. International Character Sets (Meta keys and locales) HP Vertica Analytic Database (7.1.x) Page 65 of 401

66 Using vsql In vsql, 8-bit meta characters are no longer supported. Make sure that meta characters send an escape by setting their EightBitInput X resource to False. You can do this in one of the following ways: Edit the ~/.Xdefaults file by adding the following line: XTerm*EightBitInput: False Start an xterm with an -xrm '*EightBitInput: False' command-line argument. Key Bindings: The following key bindings are specific to vsql: Insert switches between insert mode (the default) and overwrite mode. Delete deletes the character to the right of the cursor. Home moves the cursor to the front of the line. End moves the cursor to the end of the line. ^R Performs a history backwards search. vsql Environment Variables The following environment variables can be set to automatically use the defined properties each time you start vsql: PAGER - If the query results do not fit on the screen, they are piped through this command. Typical values are more or less. The default is platform-dependent. The use of the pager can be disabled by using the \pset command. VSQL_DATABASE - Database to connect to. For example, VMart. VSQL_HOST - Host name or IP address of the HP Vertica node. VSQL_PORT - Port to use for the connection. VSQL_USER - Username to use for the connection. VSQL_PASSWORD - Password to use for the connection. VSQL_EDITOR, EDITOR and VISUAL - Editor used by the \e command. The variables are examined in the order listed; the first that is set is used. SHELL - Command run by the \! command. HP Vertica Analytic Database (7.1.x) Page 66 of 401

67 Using vsql TMPDIR - Directory for storing temporary files. The default is platform-dependant. On Unix-like systems the default is /tmp. Locales The default terminal emulator under Linux is gnome-terminal, although xterm can also be used. HP recommends that you use gnome-terminal with vsql in UTF-8 mode, which is its default. To Change Settings on Linux 1. From the tabs at the top of the vsql screen, select Terminal. 2. Click Set Character Encoding. 3. Select Unicode (UTF-8). Note: This works well for standard keyboards. xterm has a similar UTF-8 option. To Change Settings on Windows Using PuTTy 1. Right click the vsql screen title bar and select Change Settings. 2. Click Window and click Translation. 3. Select UTF-8 in the drop-down menu on the right. Notes vsql has no way of knowing how you have set your terminal emulator options. The tecla library is prepared to do POSIX-type translations from a local encoding to UTF-8 on interactive input, using the POSIX LANG, etc., environment variables. This could be useful to international users who have a non-utf-8 keyboard. See the tecla documentation for details. HP recommends the following (or whatever other.utf-8 locale setting you find appropriate): export LANG=en_US.UTF-8 The vsql \locale command invokes and tracks the server SET LOCALE TO command, described in the SQL Reference Manual. vsql itself currently does nothing with this locale setting, but rather treats its input (from files or from tecla), all its output, and all its interactions with the server as UTF-8. vsql ignores the POSIX locale variables, except for any "automatic" uses in printf, and so on. HP Vertica Analytic Database (7.1.x) Page 67 of 401

68 Using vsql Files Before starting up, vsql attempts to read and execute commands from the system-wide vsqlrc file and the user's ~/.vsqlrc file. The command-line history is stored in the file ~/.vsql_history. Tip: If you want to save your old history file, open another terminal window and save a copy to a different file name. Exporting Data Using vsql You can use vsql for simple data-export tasks by changing its output format options so the output is suitable for importing into other systems (tab-delimited or comma-separated files, for example). These options can be set either from within an interactive vsql session, or through command-line arguments to the vsql command (making the export process suitable for automation through scripting). After you have set vsql's options so it outputs the data in a format your target system can read, you run a query and capture the result in a text file. The following table lists the meta-commands and command-line options that are useful for changing the format of vsql's output. Description Metacommand Command-line Option Disable padding used to align output. \a -A or --no-align Show only tuples, disabling column headings and row counts. \t -t or --tuples-only Set the field separator character. \pset fieldsep -F or --field-separator Send output to a file. \o -o or --output Specify a SQL statement to execute. N/A -c or --command The following example demonstrates disabling padding and column headers in the output, and setting a field separator to dump a table to a tab-separated text file within an interactive session. => SELECT * FROM my_table; a b c a one 1 b two 2 c three 3 d four 4 e five 5 (5 rows) => \a Output format is unaligned. HP Vertica Analytic Database (7.1.x) Page 68 of 401

69 Using vsql => \t Showing only tuples. => \pset fieldsep '\t' Field separator is " ". => \o dumpfile.txt => select * from my_table; => \o => \! cat dumpfile.txt a one 1 b two 2 c three 3 d four 4 e five 5 Note: You could encounter issues with empty strings being converted to NULLs or the reverse using this technique. You can prevent any confusion by explicitly setting null values to output a unique string such as NULLNULLNULL (for example, \pset null 'NULLNULLNULL'). Then, on the import end, convert the unique string back to a null value. For example, if you are copying the file back into an HP Vertica database, you would give the argument NULL 'NULLNULLNULL' to the COPY statement. When logged into one of the database nodes, you can create the same output file directly from the command line by passing the right parameters to vsql: $ vsql -U username -F $'\t' -At -o dumpfile.txt -c "SELECT * FROM my_table;" Password: $ cat dumpfile.txt a one 1 b two 2 c three 3 d four 4 e five 5 If you want to convert null values to a unique string as mentioned earlier, you can add the argument -P null='nullnullnull' (or whatever unique string you choose). By adding the -w vsql command-line option to the example command line, you could use the command within a batch script to automate the data export. However, the script would contain the database password as plain text. If you take this approach, you should prevent unauthorized access to the batch script, and also have the script use a database user account that has limited access. To set the field separator value to a control character, use your shell's control character escape notation. In Bash, you specify a control character in an argument using a dollar sign ($) followed by a string contained in single quotes. This string can contain C-string escapes (such as \t for tab), or a backslash (\) followed by an octal value for the character you want to use. The following example demonstrates setting the separator character to tab (\t), vertical tab (\v) and the octal value of vertical tab (\013). $ vsql -At -c "SELECT * FROM testtable;" HP Vertica Analytic Database (7.1.x) Page 69 of 401

70 Using vsql A B $ vsql -F $'\t' -At -c "SELECT * FROM testtable;" A B $ vsql -F $'\v' -At -c "SELECT * FROM testtable;" A B $ vsql -F $'\013' -At -c "SELECT * FROM testtable;" A B Copying Data Using vsql You can use vsql to copy data between two HP Vertica databases. This technique is similar to the technique explained in Exporting Data Using vsql, except instead of having vsql save data to a file for export, you pipe one vsql's output to the input of another vsql command that runs a COPY statement from STDIN. This technique can also work for other databases or applications that accept data from an input stream. Note: The following technique only works for individual tables. To copy an entire database to another cluster, see Copying a Database to Another Cluster in the Administrator's Guide. The easiest way to copy using vsql is to log in to a node of the target database, then issue a vsql command that connects to the source HP Vertica database to dump the data you want. For example, the following command copies the store.store_sales_fact table from the vmart database on node testdb01 to the vmart database on the node you are logged into: vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT * from store.store_sales_ fact" \ vsql -U username -w passwd -d vmart -c "COPY store.store_sales_fact FROM STDIN DELIMITER ' ';" Note: The above example copies the data only, not the table design. The target table for the data copy must already exist in the target database. You can export the design of the table using EXPORT_OBJECTS or EXPORT_CATALOG. HP Vertica Analytic Database (7.1.x) Page 70 of 401

71 Using vsql If you are using the Bash shell, you can escape special delimiter characters. For example, DELIMITER E'\t' specifies tab. Shells other than Bash may have other string-literal syntax. Monitoring Progress (optional) You may want some way of monitoring progress when copying large amounts of data between HP Vertica databases. One way of monitoring the progress of the copy operation is to use a utility such as Pipe Viewer that pipes its input directly to its output while displaying the amount and speed of data it passes along. Pipe Viewer can even display a progress bar if you give it the total number of bytes or lines you expect to be processed. You can get the number of lines to be processed by running a separate vsql command that executes a SELECT COUNT query. Note: Pipe Viewer isn't a standard Linux or Solaris command, so you will need to download and install it yourself. See the Pipe Viewer page for download packages and instructions. HP does not support Pipe Viewer. Install and use it at your own risk. The following command demonstrates how you can use Pipe Viewer to monitor the progress of the copy shown in the prior example. The command is complicated by the need to get the number of rows that will be copied, which is done using a separate vsql command within a Bash backquote string, which executes the string's contents and inserts the output of the command into the command line. This vsql command just counts the number of rows in the store.store_sales_fact table. vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT * from store.store_sales_ fact" \ pv -lpetr -s `vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT COUNT (*) FROM store.store_sales_fact;"` \ vsql -U username -w passwd -d vmart -c "COPY store.store_sales_fact FROM STDIN DELIMITER ' ';" While running, the above command displays a progress bar that looks like this: 0:00:39 [12.6M/s] [=============================> ] 50% ETA 00:00:40 Output Formatting Examples The first example shows how to spread a command over several lines of input. Notice the changing prompt: => CREATE TABLE my_table ( -> first integer not null default 0, -> second char(10)); CREATE TABLE Assume you have filled the table with data and want to take a look at it: HP Vertica Analytic Database (7.1.x) Page 71 of 401

72 Using vsql testdb=> SELECT * FROM my_table; first second one 2 two 3 three 4 four (4 rows) You can display tables in different ways by using the \pset command: testdb=> \pset border 2 Border style is 2. testdb=> SELECT * FROM my_table; first second one 2 two 3 three 4 four (4 rows) => \pset border 0 Border style is 0. => SELECT * FROM my_table; first second one 2 two 3 three 4 four (4 rows) => \pset border 1 Border style is 1. => \pset format unaligned Output format is unaligned. => \pset fieldsep ',' Field separator is ",". => \pset tuples_only Showing only tuples. => SELECT second, first FROM my_table; one,1 two,2 three,3 four,4 Alternatively, use the short commands: => \a \t \ x Output format is aligned. Tuples only is off. Expanded display is on. => SELECT * FROM my_table; first 1 second one HP Vertica Analytic Database (7.1.x) Page 72 of 401

73 Using vsql first 2 second two first 3 second three first 4 second four HP Vertica Analytic Database (7.1.x) Page 73 of 401

74 Using vsql HP Vertica Analytic Database (7.1.x) Page 74 of 401

75 Client Libraries The HP Vertica client driver libraries provide interfaces for connecting your client applications (or third-party applications such as Cognos and MicroStrategy) to your HP Vertica database. The drivers simplify exchanging data for loading, report generation, and other common database tasks. There are three separate client drivers: Open Database Connectivity (ODBC) the most commonly-used interface for third-party applications and clients written in C, Python, PHP, Perl, and most other languages. Java Database Connectivity (JDBC) used by clients written in the Java programming language. ActiveX Data Objects for.net (ADO.NET) used by clients developed using Microsoft's.NET Framework and written in C#, Visual Basic.NET, and other.net languages. Client Driver Standards The HP Vertica client drivers are compatible with the following driver standards: The ODBC driver complies with version of the ODBC standard. HP Vertica's JDBC driver is a type 4 driver that complies with the JDBC 3.0 standard. It is compiled using JDK version 1.5, and is compatible with client applications compiled using JDK versions 1.5 and 1.6. ADO.NET drivers conform to.net framework 3.0 specifications. The drivers do not support some of the optional features in the standards. See ODBC Feature Support and JDBC Feature Support and Using ADO.NET for details. HP Vertica Analytic Database Page 75 of 401

76 Client Driver and Server Version Compatibility Usually, each version of the HP Vertica server is compatible with the previous version of the client drivers. This compatibility lets you upgrade your HP Vertica server without having to immediately upgrade your client software. However, some new features of the new server version may not be available through the old drivers. The following table summarizes the compatibility of each recent version of the client drivers with the HP Vertica server versions. Client Driver Version 6.1.x 7.0.x 7.1.x Compatible Server Versions 6.1.x, 7.0.x, 7.1.x 7.0.x, 7.1.x 7.1.x Version 4.1 to 5.1 Client Driver Transition The client driver libraries were completely rewritten for HP Vertica 5.1 to improve standards compatibility and support more platforms. As a result, some of the classes, functions, properties, and other elements of the driver APIs have been renamed or deprecated in favor of standard ones. See Updating ODBC Client Code From Previous Driver Versions, Updating ADO.NET Client Code From Previous Driver Versions, and Updating Client Code From 4.1 or Earlier JDBC Driver Versions for details on updating your pre-5.1 client code to work with the new client libraries. HP Vertica ODBC/JDBC Client Installers The ODBC/JDBC client drivers are a separate installation from the ADO.NET drivers. (ADO.NET support is not available in Community Edition.) As noted in the compatibility table, the 6.x ODBC/JDBC client drivers do not support access to a non HP Vertica 6.x database and above. For example, you cannot use the new 6.x ODBC/JDBC client drivers to access an HP Vertica 5.x database. If you plan on having a mixed HP Vertica environment supporting both 5.x and 6.x HP Vertica database, consider keeping the 5.x drivers installed. ODBC/JDBC Multiple Version Installations The following ODBC/JDBC drivers are supported on a single machine: 4.x and 5.x ODBC/JDBC drivers can be installed on the same machine. 4.x and 6.x ODBC/JDBC drivers can be installed on the same machine. It is not possible to have both 5.x and 6.x ODBC drivers on a single machine. If you install the 6.x version, it automatically overlays the existing 5.x installation, and any DSN defined against a 5.x HP Vertica database is not supported. HP Vertica Analytic Database Page 76 of 401

77 Client Libraries HP Vertica ADO.NET Client Installers Prior to version 6.x, ADO.Net drivers must be uninstalled prior to installing a later version of the driver. The 6.x ADO.Net drivers require the HP Vertica database to be or above. The ADO.NET 6.x driver only supports access to an HP Vertica 6.x server. The ADO.NET 4.x plug-in does not work with an HP Vertica 6.x server. If you plan on also using the ODBC bridge and you need to access both HP Vertica 5.x and 6.x databases, consider keeping the 5.x versions of the ODBC/JDBC drivers for the reasons stated previously. HP Vertica Analytic Database (7.1.x) Page 77 of 401

78 Client Libraries Installing the Client Drivers You must install the HP Vertica client drivers to access HP Vertica from your client application. The drivers create and maintain connections to the database and provide APIs that your applications use to access your data. The client drivers support connections using JDBC, ODBC, and ADO.NET. Client Driver Standards The client drivers support the following standards: ODBC drivers conform to ODBC specifications. JDBC drivers conform to JDK 5 specifications. ADO.NET drivers conform to.net framework 3.0 specifications. The remainder of this section explain the requirements for the HP Vertica client drivers, and the procedure for downloading, installing, and configuring them. Driver Prerequisites The following topics explain the system requirements for the client drivers. You need to ensure that your client system meets these requirements before installing and using the client drivers. ODBC Prerequisites There are several requirements your client systems must meet before you can install the HP Vertica ODBC drivers. Operating System The HP Vertica ODBC driver requires a supported platform. The list of currently-supported platforms can be found at HP Vertica Client Drivers. ODBC Driver Manager The HP Vertica ODBC driver requires that the client system have a supported driver manager. See the myvertica portal for a list of supported driver managers. UTF-8, UTF-16 and UTF-32 Support The HP Vertica ODBC driver is a universal driver that supports UTF-8, UTF-16, and UTF-32 encoding. The default setting depends on the client platform. (see Additional Linux ODBC Driver Configuration Settings for more information). HP Vertica Analytic Database (7.1.x) Page 78 of 401

79 Client Libraries When using the driver with the DataDirect Connect driver manager, DataDirect Connect adapts to the ODBC driver's text encoding settings. You should configure the ODBC driver to use the encoding method that your application requires. This allows strings to be passed between the driver and the application without intermediate conversion. See Also Installing the Client Drivers Programming ODBC Client Applications Creating an ODBC Data Source Name (DSN) ADO.NET Prerequisites The HP Vertica driver for ADO.NET requires the following software and hardware components: Operating System The HP Vertica ADO.NET driver requires a supported Windows operating system. The list of supported platforms can be found in the Supported Platforms document at Memory HP Vertica suggests a minimum of 512MB of RAM..NET Framework The requirements for the.net framework for ADO.NET in HP Vertica can be found in the Supported Platforms document at See Also Programming ADO.NET Applications Python Prerequisites Python is a free, agile, object-oriented, cross-platform programming language designed to emphasize rapid development and code readability. Python has been released under several different open source licenses. HP Vertica's ODBC driver is tested with multiple versions of Python. See Perl and Python Requirements for details. HP Vertica Analytic Database (7.1.x) Page 79 of 401

80 Client Libraries Python Driver HP Vertica requires the pyodbc driver module. See your system's Python documentation for installation and configuration information. Supported Operating Systems The HP Vertica ODBC driver requires one of the operating systems listed in ODBC Prerequisites. For usage and examples, see Programming Python Client Applications. Perl Prerequisites Perl is a free, stable, open source, cross-platform programming language licensed under its Artistic License, or the GNU General Public License (GPL). Your Perl scripts access HP Vertica through its ODBC driver, using the Perl Database Interface (DBI) module with the ODBC Database Driver (DBD::ODBC). The HP Vertica ODBC driver is known to be compatible with these versions of Perl: Later Perl versions may also work. Perl Drivers The following Perl driver modules have been tested with the HP Vertica ODBC driver: The DBI driver module, version The DBD::ODBC driver module, version 1.22 Other versions may also work. Supported Client Systems The HP Vertica ODBC driver requires one of the operating systems and driver managers listed in ODBC Prerequisites. PHP Prerequisites PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded into HTML. PHP is licensed under the PHP License, an opensource BSD-style license certified by the Open Source Initiative. HP Vertica Analytic Database (7.1.x) Page 80 of 401

81 Client Libraries PHP Modules The following PHP modules are required: php php-odbc php-pdo UnixODBC (if you are using the Unix ODBC driver) libiodbc (if you are using the iodbc driver) Supported Client Systems The HP Vertica ODBC driver requires one of the operating systems and driver managers listed in ODBC Prerequisites. Installing the Client Drivers How you install client drivers depends on the client's operating system: For Linux and UNIX clients, you must first install a Linux driver manager. After you have installed the driver manager, there are two different ways to install the client drivers: On Red Hat Enterprise Linux 5, 64-bit and SUSE Linux Enterprise Server 10/11 64-bit, you can use the HP Vertica client RPM package to install the ODBC and JDBC drivers as well as the vsql client. On other Linux platforms and UNIX-like platforms you can download the ODBC and JDBC drivers and install them individually. Note: The ODBC and JDBC client drivers are installed by the server.rpm files. If you have installed HP Vertica Analytics Platform on your Linux system for development or testing purposes, you do not need to download and install the client drivers on it you just need to configure the drivers. To use ODBC, you need to create a DSN (see Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX). To use JDBC, you need to add the JDBC client driver to the Java CLASSPATH (see Modifying the Java CLASSPATH). On Windows clients, download the 32-bit or 64-bit client installer. The installer provides the ODBC and and JDBC drivers. There is an additional Windows installer for the ADO.NET client driver. 32-bit and 64-bit versions of the installer are available. ADO.NET is only available for the Enterprise edition of HP Vertica. The remainder of this section describes how to install client drivers on different operating systems. HP Vertica Analytic Database (7.1.x) Page 81 of 401

82 Client Libraries Installing Driver Managers Linux and Other UNIX-like Platforms If your client platform does not already have an ODBC driver manager, you need to install one before you can use the HP Vertica ODBC client driver. The driver manager provides an interface between your client operating system and the ODBC drivers. See Supported Platforms for a list of driver managers that are supported on each of the client platforms. Driver managers can be downloaded from your operating system specific repository and from the links below. HP Vertica does not provide instructions for installing and configuring these third party binaries. For download and configuration information, see the respective websites for the driver managers for installation and configuration information: UnixODBC: iodbc: Installing ODBC Drivers on Linux, Solaris, AIX, and HP- UX Note: For additional details about supported platforms, see Supported Platforms. Read Driver Prerequisites before you proceed. For Red Hat Enterprise Linux and SUSE Linux Enterprise Server, you can download and install a client RPM that installs both the ODBC and JDBC driver as well as the vsql client. See Installing the Client RPM on Red Hat and SUSE. Note: The ODBC and JDBC client drivers are installed by the server.rpm files. If you have installed HP Vertica Analytics Platform on your Linux system for development or testing purposes, you do not need to download and install the client drivers on it you just need to configure the drivers. To use ODBC, you need to create a DSN (see Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX). To use JDBC, you need to add the JDBC client driver to the Java CLASSPATH (see Modifying the Java CLASSPATH). The ODBC driver installation packages are broken down by client platform on the myvertica portal. The package's filename is named based on its operating system and architecture (for example, vertica_7.1..xx_odbc_x86_64_linux.tar.gz) HP Vertica Analytic Database (7.1.x) Page 82 of 401

83 Client Libraries Installation Procedure 1. Open a Web browser and log in to myvertica portal. 2. Click the Download tab and locate and download the driver package that corresponds to your client system. 3. If you did not directly download to the client system, transfer the downloaded file to it. 4. Log in to the client system as root. 5. If the directory /opt/vertica/ does not exist, create it: # mkdir -p /opt/vertica/ 6. Copy the downloaded file to the /opt/vertica/ directory. For example: # cp vertica_7.1..xx_odbc_x86_64_linux.tar.gz /opt/vertica/ 7. Change to the /opt/vertica/ directory: # cd /opt/vertica/ 8. Uncompress the file you downloaded. For example: $ tar vzxf vertica_7.1..xx_odbc_x86_64_linux.tar.gz Two folders are created: one for the include file, and one for the library files. The path of the library file depends on the processor architecture: lib for 32-bit libraries, and lib64 for 64-bit libraries. So, a 64-bit driver client download creates the directories: /opt/vertica/include, which contains the header file /opt/vertica/lib64, which contains the library file Post Driver Installation Configuration You must configure the ODBC driver before you can use it. There are two required configuration files: The odbc.ini configuration file defines the Data Source Names (DSNs) that tell the ODBC how to access your HP Vertica databases. See Creating an ODBC Data Source Name for instructions to create this file. HP Vertica Analytic Database (7.1.x) Page 83 of 401

84 Client Libraries The vertica.ini configuration file defines some HP Vertica-specific settings required by the drivers. See Additional Linux ODBC Driver Configuration Settings for instructions to create this file. Note: If you are upgrading your ODBC driver, you must either update your DSNs to point to the newly-installed driver or create new DSNs. If your odbc.ini file references drivers defined in an odbcinst.ini file, you just need to update the odbcinst.ini file. See Creating an ODBC Data Source Name (DSN) for details. Installing the Client RPM on Red Hat and SUSE For Red Hat Enterprise Linux and SUSE Linux Enterprise Server, you can download and install a client driver RPM that installs both the ODBC and JDBC driver libraries and the vsql client. To install the client driver RPM package: 1. Open a Web browser and log in to the myvertica portal. 2. Click the Download tab and download the client RPM file that matches your client platform's architecture. Note: The 64-bit client driver RPM installs both the 64-bit and 32-bit ODBC driver libraries, so you do not need to install both on your 64-bit client system. 3. If you did not directly download the RPM on the client system, transfer the file to the client. 4. Log in to the client system as root. 5. Install the RPM package you downloaded: # rpm -Uvh package_name.rpm Note: You receive one or more conflict error messages if there are existing HP Vertica client driver files on your system. This can happen if you are trying to install the client driver package on a system that has the server package installed, since the server package also includes the client drivers. In this case, you don't need to install the client drivers, and can instead use the drivers installed by the server package. If the conflict arises from an old driver installation or from a server installation for an older version, you can use the rpm command's --force switch to force it to overwrite the existing files with the files in the client driver package. Once you have installed the client package, you need to create a DSN (see Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX) and set some additional configuration parameters (see Additional Linux ODBC Driver Configuration Settings) to use ODBC. To use JDBC, you need to modify your class path (see Modifying the Java CLASSPATH) before you can use JDBC. HP Vertica Analytic Database (7.1.x) Page 84 of 401

85 Client Libraries You may also want to add the vsql client to your PATH environment variable so that you do not need to enter its full path to run it. You add it to your path by adding the following to the.profile file in your home directory or the global /etc/profile file: export PATH=$PATH:/opt/vertica/bin Installing JDBC Driver on Linux, Solaris, AIX, and HPUX Note: The ODBC and JDBC client drivers are installed by the server.rpm files. If you have installed HP Vertica Analytics Platform on your Linux system for development or testing purposes, you do not need to download and install the client drivers on it you just need to configure the drivers. To use ODBC, you need to create a DSN (see Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX). To use JDBC, you need to add the JDBC client driver to the Java CLASSPATH (see Modifying the Java CLASSPATH). Note: For additional details about supported platforms, see Supported Platforms. The JDBC driver is available for download from myvertica portal. There is a single.jar file that works on all platforms and architectures. To download and install the file: 1. Open a Web browser and log in to myvertica portal. 2. Click the Download tab and locate and download the JDBC driver. 3. You need to copy the.jar file you downloaded file to a directory in your Java CLASSPATH on every client system with which you want to access HP Vertica. You can either: Copy the.jar file to its own directory (such as /opt/vertica/java/lib) and then add that directory to your CLASSPATH (recommended). See Modifying the Java CLASSPATH for details. Copy the.jar file to directory that is already in your CLASSPATH (for example, a directory where you have placed other.jar files on which your application depends). Note: In the directory where you copied the.jar file, you should create a symbolic link named vertica_jdk_5.jar to the.jar file. You can reference this symbolic link anywhere you need to use the name of the JDBC library without having to worry any future upgrade invalidating the file name. This symbolic link is automatically created on server installs. On clients, you need to create and manually maintain this symbolic link yourself if you installed the driver manually. The Installing the Client RPM on Red Hat and SUSE create this link when they install the JDBC library. Installing ODBC/JDBC Client Drivers and vsql Client on Windows This topic details how to download and install the HP Vertica ODBC/JDBC client drivers and vsql client for Windows systems. The installer can be run as a regular windows installer or silently. The HP Vertica Analytic Database (7.1.x) Page 85 of 401

86 Client Libraries Windows client drivers (ODBC, JDBC, etc.) are all installed using a single installer. There are 32-bit and 64-bit installers available. The 32-bit installer provides a 32-bit driver. The 64-bit installer provides both 32-bit and 64-bit drivers. Read Driver Prerequisites before you proceed. Note: Note: If you are uninstalling a previous release of the HP Vertica ODBC/JDBC drivers, delete any DSNs associated with those drivers before you uninstall. Windows requires that the driver files be present when a DSN is removed. If you uninstall the driver first, then the DSN cannot be removed. For releases after 5.1 you do not need to uninstall the drivers, as the installation program upgrades the existing 5.1+ drivers in place. To Download the Windows client-drivers: 1. Open a Web browser and log in to myvertica portal. 2. Click the Download tab and select the ODBC/JDBC Windows installer that you want to install (32-bit or 64-bit) and follow the on-screen prompts to download the installer. To Install the Windows Client-Drivers and vsql client: 1. As a Windows Administrator, double-click the installer to start the install process. 2. The introduction screen appears. Click Next to begin the installation. 3. Read the license agreement and check the appropriate radio box. Click Next to continue. 4. Optionally change the installation directory and click Next. The default directory is C:\Program Files (x86)\vertica Systems\. 5. Select the components to install and click Next. By default all components are selected. 6. Click Install to install the options you selected. 7. Click Finish. To Silent-Install the Windows Client-Drivers and vsql client: 1. As a Windows Administrator, open a command-line session and change directory to the folder that contains the installer. 2. Run the command vertica_client_drivers_[version].exe /S /v/qn 3. The drivers are silently installed in C:\Program Files\Vertica Systems\. If you install the 32-bit drivers on a 64-bit system, then those drivers are installed to C:\Program Files (x86)\vertica Systems\. The driver appears in the list of installed programs and is now available in the ODBC control panel. HP Vertica Analytic Database (7.1.x) Page 86 of 401

87 Client Libraries After You install: The client drivers are available in the ODBC and JDBC folders of the installation directory. There is no shortcut for the vsql client. vsql is added to the windows PATH environment variable. Start a command window and type vsql -? at the command prompt to start vsql and show the help list. See vsql Notes for Windows Users for important details about using vsql in a Windows console. You must perform an additional step for some of the client drivers before you use them: For ODBC, create a new Data Source Name (DSN). For JDBC, Modifying the Java CLASSPATH. Modifying the Java CLASSPATH The CLASSPATH environment variable contains the list of directories where the Java run time looks for library class files. For your Java client code to access HP Vertica, you need to add the directory where the HP Vertica JDBC.jar file is located. Note: In your CLASSPATH, use the symbolic link vertica-jdbc-x.x.x.jar (where x.x.x is a version number) that points to the JDBC library.jar file, rather than the.jar file itself. Using the symbolic link ensures that any updates to the JDBC library.jar file (which will use a different filename) will not invalidate your CLASSPATH setting, since the symbolic link's filename will remain the same. You just need to update the symbolic link to point at the new.jar file. Linux, Solaris, AIX, HP-UX, and OS X If you are using the Bash shell, use the export command to define the CLASSPATH variable: # export CLASSPATH=/opt/vertica/java/lib/vertica-jdbc-x.x.x.jar If environment variable CLASSPATH is already defined, use the following command to prevent it from being overwritten: # export CLASSPATH=$CLASSPATH:/opt/vertica/java/lib/vertica-jdbc-x.x.x.jar If you are using a shell other than Bash, consult its documentation to learn how to set environment variables. You need to either set the CLASSPATH environment variable for every login session, or insert the command to set the variable into one of your startup scripts (such as ~/.profile or /etc/profile). HP Vertica Analytic Database (7.1.x) Page 87 of 401

88 Client Libraries Windows Provide the class paths to the.jar,.zip, or.class files. C:> SET CLASSPATH=classpath1;classpath2... For example: C:> SET CLASSPATH=C:\java\MyClasses\vertica-jdbc-x.x.x.jar As with the Linux/UNIX settings, this setting only lasts for the current session. To set the CLASSPATH permanently, set an environment variable: 1. On the Windows Control Panel, click System. 2. Click Advanced or Advanced Systems Settings. 3. Click Environment Variables. 4. Under User variables, click New. 5. In the Variable name box, type CLASSPATH. 6. In the Variable value box, type the path to the HP Vertica JDBC.jar file on your system (for example, C:\Program Files (x86)\vertica\jdbc\vertica-jdbc-x.x.x.jar) Specifying the Library Directory in the Java Command There is an alternative way to tell the Java run time where to find the HP Vertica JDBC driver other than changing the CLASSPATH environment variable: explicitly add the directory containing the.jar file to the java command line using either the -cp or -classpath argument. For example, on Linux, start your client application using: # java -classpath /opt/vertica/java/lib/vertica-jdbc-x.x.x.jar myapplication.class Your Java IDE may also let you add directories to your CLASSPATH, or let you import the HP Vertica JDBC driver into your project. See your IDE documentation for details. Installing the JDBC Driver on Macintosh OS X To install the HP Vertica JDBC driver on your Macintosh OS X client system, download the crossplatform JDBC driver.jar file to your system and ensure OS X's Java installation can find it. Downloading the JDBC Driver To download the HP Vertica JDBC driver on Macintosh OS X: HP Vertica Analytic Database (7.1.x) Page 88 of 401

89 Client Libraries 1. On your Macintosh client system, open a browser and log into the myvertica portal. 2. Navigate to the Downloads page, scroll to the Client Software download section, and click the download link for the JDBC driver. 3. Accept the license agreement and wait for the download to complete. Ensuring Java Can Find the JDBC Driver In order for your Java client application to use the HP Vertica JDBC driver, the Java interpreter needs to be able to find its library file. Choose one of these methods to tell the Java interpreter where to look for the library: Copy the JDBC.jar file you downloaded to either the system-wide Java Extensions folder (/Library/Java/Extensions) or your user Java Extensions folder (/Users/username/Library/Java/Extensions). Add the directory containing the JDBC.jar file to the CLASSPATH environment variable (see Modifying the Java CLASSPATH). Specify the directory containing the JDBC.jar using the -cp argument in the Java command line you use to start your Java command line. Installing the ODBC Driver on Mac OS X You can obtain the HP Vertica ODBC driver for Mac OS X as a.pkg file through the myvertica portal. You can run the installer as a regular Mac OS X installer or silently. This driver is compatible with both 32-bit and 64-bit applications. The installer is designed to be used with the standard iodbc Driver Manager included in Mac OS X. While Mac OS X ships with the iodbc Driver Manager already installed, you may choose to download the most recent version of the driver at the iodbc.org website. By default, the installer installs the driver in the following location: /Library/Vertica/ODBC/lib/libverticaodbc.dylib. The installer also automatically registers a driver named "Vertica" with the iodbc Driver Manager. To use the unixodbc Driver Manager instead of Apple's iodbc Driver Manager, see the unixodbc.org website. Before You Download the Driver If you installed a previous version of the HP Vertica ODBC driver for Mac OS X, your system may already have a registered driver named "Vertica." In this case, If you must remove or rename the older version of the driver before installing the HP Vertica ODBC driver.pkg. To have multiple versions of the driver installed on your system at the same time, you must rename the currently installed version of the driver to something other than "Vertica." You can do so using the Apple ODBC Administrator Tool. HP Vertica Analytic Database (7.1.x) Page 89 of 401

90 Client Libraries To rename the driver: 1. Using your web browser, download and install the Apple ODBC Administrator Tool. 2. Locate and open the ODBC Administrator Tool after installation: a. Navigate to Finder > Applications > Utilities. b. Open the ODBC Administrator Tool. 3. Click the Drivers tab, and then select the driver named "Vertica." 4. Click the Configure button. A dialog box opens. a. In Description, enter a new name for the driver, and then click OK. The dialog box closes. b. On the ODBC Administrator page, click Apply. 5. Exit the ODBC Administrator Tool. Download the Driver Follow these steps to download the HP Vertica ODBC driver for Mac OS X: 1. On your Mac OS X client system, open a browser, and log in to the myvertica portal. 2. Install the HP Vertica ODBC driver for Mac OS X: a. Navigate to the Downloads tab, and scroll to the Client Software section. b. Click the download link for the Mac OS X ODBC installer. 3. Accept the license agreement, and wait for the download to complete. Install the Mac OS X ODBC Client-Driver As a Mac OS X Administrator, double-click the installer to start the installation. Follow the prompts as the wizard guides you through each step of the process. Note: After installing the ODBC driver, you must create a DSN to be able to connect to your HP Vertica database. For the procedure, see Creating an ODBC DSN for Macintosh OS X Clients. HP Vertica Analytic Database (7.1.x) Page 90 of 401

91 Client Libraries Silently Install the Mac OS X ODBC Client-Driver 1. Log into the client Mac in one of two ways: As an administrator account, if you are installing the driver for system-wide use As the user who needs to use the HP Vertica ODBC driver 2. Open a terminal window. In the Finder, click Applications > Utilities > Terminal. 3. Install the.pkg file containing the ODBC driver using the command: sudo installer -pkg ~/Downloads/vertica-odbc7.1.pkg -target / In the preceding.pkg command, change the path to that of the downloaded file, if: You downloaded the driver.pkg file to a directory other than your Downloads directory. You downloaded the driver using another user account. Note: After installing the ODBC driver, you must create a DSN to be able to connect to your HP Vertica database. For the procedure, see Creating an ODBC DSN for Macintosh OS X Clients. Uninstall the Mac OS X ODBC Client-Driver Uninstalling the Mac OS X ODBC Client-Driver does not remove any existing DSNs associated with the driver. To uninstall: 1. Open a terminal window. 2. Enter the command: sudo /Library/Vertica/ODBC/bin/Uninstall Using Legacy Drivers The HP Vertica server supports connections from the previous version of the client drivers. For example, the HP Vertica version 5.1 server works with the 4.1 client drivers, since they were the drivers distributed with the previous version of the server. This backwards compatibility lets you upgrade your HP Vertica database first, then later upgrade your clients. If you have not yet updated your code to work with the new version of the HP Vertica client drivers, you can continue to use the older drivers until you do. If you need to install your client application on HP Vertica Analytic Database (7.1.x) Page 91 of 401

92 Client Libraries a new client system, you can download and install the older drivers. See myvertica portal to download the installers; find installation documentation at For detailed information on which the compatibility of different versions of the HP Vertica server and HP Vertica client, see Client Driver and Server Version Compatibility. Note: The support for a previous version of the drivers is usually eliminated in the next release of HP Vertica. For example, the HP Vertica version 5.1 server does not support the version 4.0 drivers. You should update your client application to work with the new client drivers as soon as possible. HP Vertica Analytic Database (7.1.x) Page 92 of 401

93 Client Libraries Creating an ODBC Data Source Name (DSN) A Data Source Name (DSN) is the logical name that is used by Open Database Connectivity (ODBC) to refer to the driver and other information that is required to access data from a data source. Whether you are developing your own ODBC client code or you are using a third-party tool that needs to access HP Vertica using ODBC, you need to configure and test a DSN. The method you use depends upon the client operating system you are using. Creating an ODBC DSN for Linux, Solaris, AIX, and HP- UX You define DSN on Linux, Solaris, and other UNIX-like platforms in a text file. Your client's driver manager reads this file to determine how to connect to your HP Vertica database. The driver manager usually looks for the DSN definitions in two places: /etc/odbc.ini ~/.odbc.ini (a file named.odbc.ini in the user's home directory) The structure of these files is the same, only their location differs. If both files are present, the ~/.odbc.ini file usually overrides the system-wide /etc/odbc.ini file. Note: See your ODBC driver manager's documentation for details on where these files should be located and any other requirements. odbc.ini File Structure The odbc.ini is a text file that contains two types of lines: Section definitions, which are text strings enclosed in square brackets. Parameter definitions, which contain a parameter name, an equals sign (=), and then the parameter's value. The first section of the file is always named [ODBC Data Sources], and contains a list of all the DSNs that the odbc.ini file defines. The parameters in this section are the names of the DSNs, which appear as section definitions later in the file. The value is a text description of the DSN and has no function. For example, an odbc.ini file that defines a single DSN named HP VerticaDSN could have this ODBC Data Sources section: [ODBC Data Sources] HPVerticaDSN = "vmartdb" Appearing after the ODBC data sources section are sections that define each DSN. The name of a DSN section must match one of the names defined in the ODBC Data Sources section. HP Vertica Analytic Database (7.1.x) Page 93 of 401

94 Client Libraries Configuring the odbc.ini file: To create or edit the DSN definition file: 1. Using the text editor of your choice, open odbc.ini or ~/.odbc.ini. 2. Create an ODBC Data Sources section and define a parameter: Whose name is the name of the DSN you want to create Whose value is a description of the DSN For example, to create a DSN named VMart, you would enter: [ODBC Data Sources] VMart = "VMart database on HP Vertica" 3. Create a section whose name matches the DSN name you defined in step 2. In this section, you add parameters that define the DSN's settings. The most commonly-defined parameters are: Description Additional information about the data source. Driver The location and designation of the HP Vertica ODBC driver, or the name of a driver defined in the odbcinst.ini file (see below). For future compatibility, use the name of the symbolic link in the library directory, rather than the library file: o o (/opt/vertica/lib, on 32-bit clients /opt/vertica/lib64, on 64-bit clients For example, the symbolic link for the 64-bit ODBC driver library is: /opt/vertica/lib64/libverticaodbc.so The symbolic link always points to the most up-to-date version of the HP Vertica client ODBC library. Use this link so that you do not need to update all of your DSNs when you update your client drivers. Database The name of the database running on the server. This example uses vmartdb for the vmartdb. ServerName The name of the server where HP Vertica is installed. Use localhost if HP Vertica is installed on the same machine. You can provide an IPv4 address, IPv6 address, or hostname. HP Vertica Analytic Database (7.1.x) Page 94 of 401

95 Client Libraries In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6. UID Either the database superuser (same name as database administrator account) or a user that the superuser has created and granted privileges. This example uses the user name dbadmin. PWD The password for the specified user name. This example leaves the password field blank. Port The port number on which HP Vertica listens for ODBC connections. For example, ConnSettings Can contain SQL commands separated by a semicolon. These commands can be run immediately after connecting to the server. SSLKeyFile The file path and name of the client's private key. This file can reside anywhere on the system. SSLCertFile The file path and name of the client's public certificate. This file can reside anywhere on the system. Locale The default locale used for the session. By default, the locale for the database is: en_us@collation=binary (English as in the United States of America). Specify the locale as an ICU Locale. See the ICU User Guide ( for a complete list of parameters that can be used to specify a locale. PreferredAddressFamily: The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name. Valid values are: o o o ipv4 Connect to the server using IPv4. ipv6 Connect to the server using IPv6. none Use the IP address provided by the DNS server. For example: [VMart] Description = Vmart Database Driver = /opt/vertica/lib64/libverticaodbc.so Database = vmartdb Servername = host01 UID = dbadmin PWD = Port = 5433 ConnSettings = HP Vertica Analytic Database (7.1.x) Page 95 of 401

96 Client Libraries SSLKeyFile = /home/dbadmin/client.key SSLCertFile = /home/dbadmin/client.crt Locale = en_gb See Data Source Name (DSN) Connection Parameters for a complete list of parameters including HP Vertica-specific ones. Using an odbcinst.ini File Instead of giving the path of the ODBC driver library in your DSN definitions, you can use the name of a driver defined in the odbcinst.ini file. This method is useful method if you have many DSNs and often need to update them to point to new driver libraries. It also allows you to set some additional ODBC parameters, such as the threading model. Just as in the odbc.ini file, odbcinst.ini has sections. Each section defines an ODBC driver that can be referenced in the odbc.ini files. In a section, you can define the following parameters: Description Additional information about the data source. Driver The location and designation of the HP Vertica ODBC driver, such as /opt/vertica/lib64/libverticaodbc.so For example: [HPVertica] Description = HP Vertica ODBC Driver Driver = /opt/vertica/lib64/libverticaodbc.so Then, in your odbc.ini file, use the name of the section you created in the odbcinst.ini file that describes the driver you want to use. For example: [VMart] Description = HP Vertica Vmart database Driver = HPVertica If you are using the unixodbc driver manager, you should also add an ODBC section to override its standard threading settings. By default, unixodbc serializes all SQL calls through ODBC, which prevents multiple parallel loads. To change this default behavior, add the following to your odbcinst.ini file: [ODBC] Threading = 1 HP Vertica Analytic Database (7.1.x) Page 96 of 401

97 Client Libraries Configuring Additional ODBC Settings On Linux and UNIX systems, you need to configure some additional driver settings before you can use your DSN. See Additional Linux ODBC Driver Configuration Settings for details. Testing a DSN Using Isql The unixodbc driver manager includes a utility named isql, which is a simple ODBC commandline client. It lets you to connect to a DSN to send commands and receive results, similarly to vsql. To use isql to test a DSN connection: 1. Run the following command: $ isql v DSNnameSQL> Where DSNname is the name of the DSN you created. A connection message and a SQL prompt display. If they do not, you could have a configuration problem or you could be using the wrong user name or password. 2. Try a simple SQL statement. For example: SQL> SELECT table_name FROM tables; The isql tool returns the results of your SQL statement. Note: If you have not set the ErrorMessagesPath in the additional driver configuration settings, any errors during testing will trigger a missing error message file ("The error message NoSQLGetPrivateProfileString could not be found in the en-us locale"). See Additional Linux ODBC Driver Configuration Settings for more information. Creating an ODBC DSN for Windows Clients To create a DSN for Microsoft Windows clients, you must perform the following tasks: Setting Up a DSN Testing the DSN Using Excel 2007 Setting Up a DSN A Data Source Name (DSN) is the ODBC logical name for the drive and other information the database needs to access data. The name is used by Internet Information Services (IIS) for a connection to an ODBC data source. HP Vertica Analytic Database (7.1.x) Page 97 of 401

98 Client Libraries This section describes how to use the HP Vertica ODBC Driver to set up an ODBC DSN. This topic assumes that the driver is already installed, as described in Installing Client Drivers on Windows. To set up a DSN 1. Open the ODBC Administrator. For example, you could navigate to Start > Control Panel > Administrative Tools > Data Sources (ODBC). Note: The method you use to open the ODBC Administrator depends on your version of Windows. Differences between Windows versions and Start Menu customizations could require you to take a different action to open the ODBC Administrator. 2. Decide if you want all users on your client system to be able to access to the DSN for the HP Vertica database. If you want all users to have access, then click the System DSN tab. Otherwise, click the User DSN tab to create a DSN that is only usable by your Windows user account. 3. Click Add to create a new DSN to connect to the HP Vertica database. HP Vertica Analytic Database (7.1.x) Page 98 of 401

99 Client Libraries 4. Scroll through the list of drivers in the Create a New Data Source dialog box to locate the HP Vertica driver. Select the driver, and then click Finish. Note: If you have installed more than one version of the HP Vertica client drivers on your Windows client system, you may see multiple versions of the driver in this list. Choose the version that you know is compatible with your client application and Vertica Analytic Database server. If you are unsure, use the latest version of the driver. The HP Vertica ODBC DSN configuration dialog box appears. 5. Click the More >>> button to view a description of the field you are editing and the connection string defined by the DSN. HP Vertica Analytic Database (7.1.x) Page 99 of 401

100 Client Libraries 6. Enter the information for your DSN. The following fields are required: DSN Name The name for the DSN. Clients use this name to identify the DSN to which they want to connect. The DSN name must satisfy the following requirements: o Its maximum length is 32 characters. o It is composed of ASCII characters except for the following: [ ], ;? * \ o It contains no spaces. Server The host name or IP address of the HP Vertica server to which you want to connect. Use localhost, if HP Vertica is installed on the same machine. You can provide an IPv4 address, IPv6 address, or hostname. In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6. The PreferredAddressFamily option is available on the Client Settings tab. HP Vertica Analytic Database (7.1.x) Page 100 of 401

101 Client Libraries Backup Servers A comma-separated list of host names or IP addresses used to connect to if the server specified by the Server field is down. Optional. Database The name of the HP Vertica database. User Name The name of the user account to use when connecting to the database. If the application does not supply its own user name when connecting to the DSN, this account name is used to log into the database.. The rest of the fields are optional. See DSN Parameters for detailed information about the DSN parameters you can define. 7. If you want to test your connection: a. Enter at least a valid DSN name, Server name, Database, and either User name or select Windows authentication. b. If you have not selected Windows authentication, you can enter a password in the Password box. Alternately, you can select Password prompt to have the driver prompt you for a password when connecting. c. Click Test Connection. 8. When you have finished editing and testing the DSN, click OK. The HP Vertica ODBC DSN configuration window closes, and your new DSN is listed in the ODBC Data Source Administrator window. HP Vertica Analytic Database (7.1.x) Page 101 of 401

102 Client Libraries 9. Click OK to close the ODBC Data Source Administrator. After creating the DSN, you can test it using Microsoft Excel Setting up a 32-Bit DSN on 64-Bit Versions of Microsoft Windows On 64-bit versions of Windows, the default ODBC Data Source Administrator creates and edits DSNs that are associated with the 64-bit HP Vertica ODBC library. Attempting to use these 64-bit DSNs with a 32-bit client application results in an architecture mismatch error. Instead, you must create a specific 32-bit DSN for 32-bit clients by running the 32- bit ODBC Administrator usually located at: c:\windows\syswow64\odbcad32.exe This administrator window edits a set of DSNs that are associated with the 32-bit ODBC library. You can then use your 32-bit client applications with the DSNs you create with this version of the ODBC administrator. Testing a DSN Using Excel 2007 You can use Microsoft Excel 2007 to verify that an application can connect to an ODBC data source or other ODBC application. HP Vertica Analytic Database (7.1.x) Page 102 of 401

103 Client Libraries 1. Open Microsoft Excel, and select Data > Get External Data > From Other Sources > From Microsoft Query. 2. When the Choose Data Source dialog box opens: a. Select New Data Source, and click OK. b. Enter the name of the data source. HP Vertica Analytic Database (7.1.x) Page 103 of 401

104 Client Libraries c. Select the Vertica driver. HP Vertica Analytic Database (7.1.x) Page 104 of 401

105 Client Libraries d. Click Connect. HP Vertica Analytic Database (7.1.x) Page 105 of 401

106 Client Libraries 3. When the HP Vertica Connection Dialog box opens, enter the connection information for the DSN, and click OK. HP Vertica Analytic Database (7.1.x) Page 106 of 401

107 Client Libraries 4. Click OK on the Create New Data Source dialog box to return to the Choose Data Source dialog box. 5. Select VMart_Schema*, and verify that the Use the Query Wizard check box is deselected. Click OK. 6. When the Add Tables dialog box opens, click Close. HP Vertica Analytic Database (7.1.x) Page 107 of 401

108 Client Libraries 7. When the Microsoft Query window opens, click the SQL button. 8. In the SQL window, write any simple query to test your connection. For example: SELECT DISTINCT calendar_year FROM date_dimension; 9. If you see the caution, "SQL Query can't be represented graphically. Continue anyway?" click OK. The data values 2003, 2004, 2005, 2006, 2007 indicate that you successfully connected to and ran a query through ODBC. HP Vertica Analytic Database (7.1.x) Page 108 of 401

109 Client Libraries 10. Select File > Return Data to Microsoft Office Excel. 11. In the Import Data dialog box, click OK. HP Vertica Analytic Database (7.1.x) Page 109 of 401

110 Client Libraries The data is now available for use in an Excel worksheet. Creating an ODBC DSN for Macintosh OS X Clients You can use the HP Vertica ODBC Driver to set up an ODBC DSN. This procedure assumes that the driver is already installed, as described in Installing the ODBC Driver on Macintosh OS X. Setting Up a DSN 1. Using your web browser, download and install the Apple ODBC Administrator Tool. 2. Locate and open the ODBC Administrator Tool after installation: a. Navigate to Finder > Applications > Utilities. b. Open the ODBC Administrator Tool. 3. Click the Drivers tab, and verify that the HP Vertica driver is installed. HP Vertica Analytic Database (7.1.x) Page 110 of 401

111 Client Libraries 4. Specify if you want all users on your client system to be able to access the DSN for the HP Vertica database: If you want all users to have access, then click the System DSN tab. Otherwise, click the User DSN tab to create a DSN that is only usable by your Macintosh user account. 5. Click Add... to create a new DSN to connect to the HP Vertica database. 6. Scroll through the list of drivers in the Choose A Driver dialog box to locate the HP Vertica driver. Select the driver, and then click OK. A dialog box opens that requests DSN parameter information. 7. In the dialog box, enter the Data Source Name (DSN) and an optional Description. To do so, click Add to insert keywords (parameters) and values that define the settings needed to connect to your database. Then, click OK. The following figure shows the minimum parameters that are required to configure a DSN so that it connects to the database: HP Vertica Analytic Database (7.1.x) Page 111 of 401

112 Client Libraries 8. In the ODBC Administrator dialog box, click Apply. See Data Source Name (DSN) Connection Parameters for a complete list of parameters including those specific to HP Vertica. After configuring the ODBC Administrator Tool, you may need to configure additional driver settings before you can use your DSN, depending on your environment. See Additional ODBC Driver Configuration Settings for details. Note: If you want to test your connection, use the iodbctest utility. For the procedure, see Testing a DSN Using iodbctest. Testing a DSN Using iodbctest The standard iodbc Driver Manager on OS X includes a utility named iodbctest that lets you test a DSN to verify that it is correctly configured. You pass this command a connection string in the same format that you would use to open an ODBC database connection. After configuring your DSN connection, you can run a query to verify that the connection works. For example: # iodbctest "DSN=VerticaDSN;UID=dbadmin;PWD=password" iodbc Demonstration program This program shows an interactive SQL processor Driver Manager: Driver: (verticaodbcw.so) SQL> SELECT table_name FROM tables; table_name HP Vertica Analytic Database (7.1.x) Page 112 of 401

113 Client Libraries customer_dimension product_dimension promotion_dimension date_dimension vendor_dimension employee_dimension shipping_dimension warehouse_dimension inventory_fact store_dimension store_sales_fact store_orders_fact online_page_dimension call_center_dimension online_sales_fact numbers result set 1 returned 16 rows. Data Source Name (DSN) Connection Parameters The following tables list the connection parameters you can set in the DSNs for use with HP Vertica's ODBC driver. Required Connection Parameters These connection parameters are the minimum required to create a functioning DSN. NOTE: If you use a host name (Servername) whose DNS entry resolves to multiple IP addresses, the client attempts to connect to the first IP address returned by the DNS. If a connection cannot be made to the first address, the client attempts to connect to the second, then the third, continuing until it either connects successfully or runs out of addresses. Parameters Description Default Value Driver The file path and name of the driver used. none Database The name of the database running on the server. none Servername The host name or IP address of any active node in an HP Vertica cluster. You can provide an IPv4 address, IPv6 address, or hostname. In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6. You can also use the aliases "server" and "host" for this parameter. none UID The database username. none HP Vertica Analytic Database (7.1.x) Page 113 of 401

114 Client Libraries Optional Parameters These are basic parameters that are optional. Parameters Description Default Value Port PWD The port number on which HP Vertica listens for ODBC connections. The password for the specified user name. You may insert an empty string to leave this parameter blank none (login only succeeds if the user does not have a password set) PreferredAddressFamily The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name. Valid values are: ipv4 Connect to the server using IPv4. ipv6 Connect to the server using IPv6. none Use the IP address provided by the DNS server. none Advanced Settings Parameters Description Default AutoCommit BackupServerNode A Boolean value that controls whether the driver automatically commits transactions after executing a DML statement. A string containing the host name or IP address that client libraries can try to connect to if the host specified in ServerName is unreachable. Connection attempts continue until successful or until the list of server nodes is exhausted. Valid values: Comma-separated list of servers optionally followed by a colon and port number. true none HP Vertica Analytic Database (7.1.x) Page 114 of 401

115 Client Libraries Parameters Description Default ConnectionLoadBalance ConnSettings DirectBatchInsert A Boolean value that indicates whether the connection can be redirected to a host in the database other than the ServerNode. This affects the connection only if the load balancing. is set to something other than "none". When the node differs from the node the client is connected to, the client disconnects and reconnects to the targeted node. See About Native Connection Load Balancing in the Administration Guide. A string containing SQL commands that the driver should execute immediately after connecting to the server. You can use this parameter to configure the connection, such as setting a schema search path. Reserved symbol: In the connection string ';' is a reserved symbol. To set multiple parameters as part of ConnSettings parameters, use '%3B' for ','. Also use '+' for spaces. A Boolean value that controls where data inserted through the connection is stored. When set to true, HP Vertica directly inserts data into ROS containers. Otherwise, it stores data using AUTO mode. When you load data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. false none false HP Vertica Analytic Database (7.1.x) Page 115 of 401

116 Client Libraries Parameters Description Default DriverStringConversions Locale PromptOnNoPassword ReadOnly ResultBufferSize Controls whether the ODBC driver performs type conversions on strings sent between the ODBC driver and the database. Possible values are: NONE No conversion in either direction. this results in the highest performance. INPUT Strings sent from the client to the server are converted, but strings sent from the server to the client are not. OUTPUT Strings sent by the server to the client are converted, but strings sent from the client to the server are not. BOTH Strings are converted in both directions. The locale used for the session. Specify the locale as an ICU Locale. See: The ICU User Guide ( for a complete list of paerameters that can be used to specify a locale. [Windows only0 Controls whether users are prompted to enter a password, if none is supplied by the connection string or DSN used to connect to HP Vertica. See Prompting Windows Users for Passwords. A true or false value that controls whether the connection can read data only from HP Vertica. Size of memory buffer for the large result sets in streaming mode. OUTPUT en_ US@collation=binary (English as in the United States of America) false false (128KB) Note: This parameter was previously called MaxMemoryCache HP Vertica Analytic Database (7.1.x) Page 116 of 401

117 Client Libraries Parameters Description Default TransactionIsolation Sets the transaction isolation for the connection. Valid values are: Read Committed Serializable Server Default See Changing Transaction Isolation Levels in the Administrator's Guide for an explanation of transaction isolation. Server Default Identification Parameters Description Default Standard/HP Vertica Description Description for the DSN entry. none Standard Required? No Insert an empty string to leave the description empty. Label / SessionLabel Sets a label for the connection on the server. This value appears in the session_id column of the V_ MONITOR.SESSIONS system table. none HP Vertica Note: Label and SessionLabel are synonyms and can be used interchangeably. HP Vertica Analytic Database (7.1.x) Page 117 of 401

118 Client Libraries Encryption Parameters Description Default Standard/HP Vertica SSLMode Controls whether the connection to the database uses SSL encryption. Valid values follow. For descriptions of these values, refer to Configuring SSL for ODBC Clients. prefer HP Vertica require prefer Prefers that the server use SSL. If the server does not offer an encrypted channel, the client requests one. The first connection attempt to the database tries to use SSL. If that attempt fails, a second connection is attempted over a clear channel. allow Makes a connection to the server whether the server uses SSL or not. The first connection attempt to the database is attempted over a clear channel. If that fails, a second connection is attempted over SSL. disable Never connects to the server using SSL. Typically, you use this setting for troubleshooting. SSLCertFile The absolute path of the client's public certificate file. This file can reside anywhere on the system. none HP Vertica SSLKeyFile The absolute path to the client's private key file. This file can reside anywhere on the system. none HP Vertica HP Vertica Analytic Database (7.1.x) Page 118 of 401

119 Client Libraries Third-Party Compatibility Parameters Description Default Standard/HP Vertica ColumnsAsChar Specifies how character column types are reported when the driver is in Unicode mode. When set to false, the ODBC driver reports the data type of character columns as WCHAR. If you set ColumnsAsChar to true, the driver identifies character column as CHAR. false HP Vertica You typically use this setting for compatibility with some third-party clients, such as Informatica. ThreePartNaming A Boolean value that controls how catalog names are interpreted by the driver. When this value is false, the driver reports that catalog names are not supported. When catalog names are not supported, they cannot be used as a filter in database metadata API calls, and the driver returns NULL as the catalog name in all driver metadata results. false (UNIX) true (Windows) HP Vertica When this value is true, catalog names can be used as a filter in database metadata API calls and the driver will return the database name as the catalog name in metadata results. Some third-party applications assume a certain catalog behavior and do not work properly with the defaults. Enable this option if your client software expects to be able to get the catalog name from the database metadata and use it as part of a three-part name reference. Kerberos Connection Parameters Use the following parameters for client authentication using Kerberos. Parameters Description Default Standard/HP Vertica KerberosServiceName Provides the service name portion of the HP Vertica Kerberos principal; for example: vertica/[email protected] vertica HP Vertica HP Vertica Analytic Database (7.1.x) Page 119 of 401

120 Client Libraries Parameters Description Default Standard/HP Vertica KerberosHostname Provides the instance or host name portion of the HP Vertica Kerberos principal; for example: Value specified in the servername connection string parameter HP Vertica See Also Additional Linux ODBC Driver Configuration Settings Setting DSN Connection Parameters The parameters in the following tables are common for all user and system DSN entries. The examples provided are for Windows clients. To edit DSN parameters: On UNIX and Linux client platforms, you can edit the odbc.ini file. (See Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX.) The location of this file is specific to the driver manager. On Windows client platforms, you can edit some DSN parameters using the HP Vertica ODBC client driver interface. See Creating an ODBC DSN for Windows Clients. You can also edit the DSN parameters directly by opening the DSN entry in the Windows registry (for example, at HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\DSNname). Directly editing the registry can be risky, so you should only use this method for parameters that cannot be set through the ODBC driver's user interface, or via your client code. You can set parameters in the connection string when opening a connection using the SQLDriverConnect() function: sqlret = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=DSNName;Locale=en_GB", SQL_NTS, szdns, 1024,&nSize, SQL_DRIVER_NOPROMPT); Note: In the connection string ';' is a reserved symbol. If you need to set multiple parameters as part of ConnSettings parameter use '%3B' in place of ';'. Also use '+' instead of spaces. For example: sqlret = SQLDriverConnect(sql_hDBC, 0, (SQLCHAR*)"DSN=HP VerticaSQL;ConnSettings=set+search_path+to+a,b,c%3Bset+locale=ch;SSLMode=prefer", SQL_ NTS, szdns, 1024,&nSize, SQL_DRIVER_NOPROMPT); HP Vertica Analytic Database (7.1.x) Page 120 of 401

121 Client Libraries Your client code can retrieve DSN parameter values after a connection has been made to HP Vertica using the SQLGetConnectAttr() and SQLGetStmtAttr() API calls. Some parameters can be set and using SQLSetConnectAttr() and SQLSetStmtAttr(). For details of the list of HP Vertica-specific parameters see HP Vertica-specific ODBC Header File. Upgrading the Client Drivers The HP Vertica client driver are usually updated for each new release of the HP Vertica server. The client driver installation packages include the version number of the corresponding HP Vertica server release. Usually, the drivers are forward-compatible with the next release, so your client applications are still be able to connect using the older drivers after you upgrade to the next version of HP Vertica Analytics Platform server. See Client Driver and Server Version Compatibility for details on which client driver versions work withe each version of HP Vertica server. You should upgrade your clients as soon as possible after upgrading your server, to take advantage of new features and to maintain maximum compatibility with the server. To upgrade your drivers, follow the same procedure you used to install them in the first place. The new installation will overwrite the old. See the specific instructions for installing the drivers on your client platform for any special instructions regarding upgrades. Note: Installing new ODBC drivers does not alter existing DSN settings. You may need to change the driver settings in either the DSN or in the odbcinst.ini file, if your client system uses one. See Creating an ODBC Data Source Name for details. HP Vertica Analytic Database (7.1.x) Page 121 of 401

122 Client Libraries Additional Linux ODBC Driver Configuration Settings On Linux and UNIX platforms you need to provide some additional settings to configure the HP Vertica ODBC client driver in addition to the DSN settings. These settings control the following: The text encoding used by the driver manager (for example, UTF-8 or UTF-16). The location of the directory containing the HP Vertica ODBC driver's error message files. Whether and how the ODBC driver logs messages. Note: Most of the additional driver configuration settings are automatically set on Windows platforms. The Windows ODBC driver's DSN Configuration dialog lets you control whether the ODBC driver logs messages. On Linux/UNIX systems, you must supply the additional configuration settings before the ODBC drivers can function properly. The topics in this section describe these settings in greater detail. Location of the Additional Driver Settings Where the additional driver settings are stored depends on your client platform: On Linux and UNIX platforms, the settings are contained in a text file named vertica.ini (although you can choose a different filename). You tell the HP Vertica ODBC driver where to find this file using an environment variable named VERTICAINI. On Windows platforms, the additional settings are set using the ODBC Data Source Configuration window. The values for the settings are stored in the Windows registry under the path HKEY_LOCAL_MACHINE\SOFTWARE\Vertica\Driver. Creating a vertica.ini File There is no standard location for the vertica.ini file you can store the file anywhere that it is convenient for you on your client system. One possible location is in the /etc directory if you have multiple users on your client system that need to access it, or have a vertica.ini file in each user's home directory so users can alter their own settings. Wherever you store it, be sure users have read access to the file. The format of the vertica.ini file is similar to the odbc.ini file, with a section followed by parameter definitions. Unlike the odbc.ini file, vertica.ini contains a single section named Driver: [Driver] HP Vertica Analytic Database (7.1.x) Page 122 of 401

123 Client Libraries Following the section definition, you add setting definitions, one per line. A setting definition consists of the setting name, followed by an equal sign (=), followed by the value. The value does not need quotes. For example, to set the ODBCInstLib setting, you add a line like this: ODBCInstLib=/usr/lib64/libodbcinst.so See Additional Parameter Settings for a list of the additional settings. Required Settings You must configure two settings in order for the ODBC driver to work correctly: ErrorMessagesPath ODBCInstLib (unless the driver manager's installation library is in a directory listed in the LD_ LIBRARY_PATH or LIB_PATH environment variables). Also, if your driver manager does not use UTF-8 encoding, you need to set DriverManagerEncoding to the proper encoding. Setting the VERTICAINI Environment Variable You must set an environment variable named VERTICAINI to the absolute path of the vertica.ini file. The HP Vertica ODBC driver uses this variable to find the settings. Where you set this variable depends on whether users on your client system need to have separate vertica.ini files. If you want to have a single, system-wide vertica.ini file, you can add a command to set VERTICAINI in /etc/profile or some other system-wide environment file. For example: export VERTICAINI=/etc/vertica.ini If users need individual vertica.ini files, set VERTICAINI in their ~/.profile or similar configuration file. For example: export VERTICAINI=~/.vertica.ini On Macintosh OS X client systems, you can set the VERTICAINI environment variable in each user's ~/.MacOSX/environment.plist file. See the Environment Variables entry in the Apple's Developer's Library for more information. Example vertica.ini File The following example vertica.ini file configures the ODBC driver to: use the 64-bit UnixODBC driver manager. get its error messages from the standard HP Vertica 64-bit ODBC driver installation directory. log all warnings and more severe messages to log files stored in the temporary directory. HP Vertica Analytic Database (7.1.x) Page 123 of 401

124 Client Libraries [Driver] DriverManagerEncoding=UTF-16 ODBCInstLib=/usr/lib64/libodbcinst.so ErrorMessagesPath=/opt/vertica/lib64 LogLevel=4 LogPath=/tmp Additional Parameter Settings The following parameters can be set for the HP Vertica client drivers. Logging Settings These parameters control how messages between the client and server are logged. None of these settings are required. If they are not set, then the client library does not log any messages. They apply to both ADO.NET and ODBC. LogLevel The severity of messages that are logged between the client and the server. The valid values are: 0 No logging 1 Fatal errors 2 Errors 3 Warnings 4 Info 5 Debug 6 Trace (all messages) The value you specify for this setting sets the minimum severity for a message to be logged. For example, setting LogLevel to 3 means that the client driver logs all warnings, errors, and fatal errors. LogPath The absolute path of a directory to store log files. For example: /var/log/verticaodbc LogNamespace Limits logging to messages generated by certain objects in the client driver. Note: These settings are also available for the HP Vertica JDBC driver through connection properties. See Connection Properties for details. HP Vertica Analytic Database (7.1.x) Page 124 of 401

125 Client Libraries ODBC-specific Settings The following settings are used only by the HP Vertica ODBC client driver. DriverManagerEncoding The UTF encoding standard that the driver manager uses. This setting needs to match the encoding the driver manager expects. The available values for this setting are: UTF-8 UTF-16 (usually used by unixodbc) UTF-32 (usually used by iodbc) See the documentation for your driver manager to find the correct value for this setting. Note: While both UTF-16 and UTF-8 are valid settings for DataDirect, Vertica recommends that you set the DataDirect driver manager encoding to UTF-16. If you do not set this parameter, the ODBC driver defaults to the value shown in the following table. If your driver manager uses a different encoding, you must set this value for the ODBC driver to be able to work. Client Platform AIX 32-bit AIX 64-bit HPUX 32-bit HPUX 64-bit Linux x86 32-bit Linux x86 64-bit Linux Itanium 64-bit OS X Solaris x86 32-bit Solaris x86 64-bit Solaris SPARC 32-bit Solaris SPARC 64-bit Windows 32-bit Default Encoding UTF-16 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-32 UTF-16 HP Vertica Analytic Database (7.1.x) Page 125 of 401

126 Client Libraries Client Platform Windows 64-bit Default Encoding UTF-16 ErrorMessagesPath The absolute path to the parent directory that contains the HP Vertica client driver's localized error message files. These files are usually stored in the same directory as the HP Vertica ODBC driver files. Note: This setting is required. If you do not set it, then any error the ODBC driver encounters will result in an error message about a missing ODBCMessages.xml file. ODBCInstLib The absolute path to the file containing the ODBC installer library (ODBCInst). This setting is required if the directory containing this library is not set in the LD_LIBRARY_ PATH or LIB_PATH environment variables. The library files for the major driver manager are: UnixODBC: libodbcinst.so iodbc: libiodbcinst.so (libiodbcinst.2.dylib on OS X) DataDirect: libodbcinst.so Note: On AIX platforms, you need give the path to the library archive, followed by the name of the library enclosed in parenthesis. For example: ODBCInstLib=/usr/lib64/libodbcinst.a(libodbcinst.so.1) ADO.NET-specific Settings This setting applies only to the ADO.NET client driver: C#PreloadLogging Tells the HP Vertica ADO.NET driver to begin logging as soon as possible, before the driver has fully loaded itself. Normally, logging only starts after the driver has fully loaded. Valid values for this setting are: 0 Do not start logging before the driver has loaded. 1 Start logging as soon as possible. HP Vertica Analytic Database (7.1.x) Page 126 of 401

127 Client Libraries Programming ODBC Client Applications HP Vertica provides an Open Database Connectivity (ODBC) driver that allows applications to connect to the HP Vertica database. This driver can be used by custom-written client applications that use the ODBC API to interact with HP Vertica. ODBC is also used by many third-party applications to connect to HP Vertica, including business intelligence applications and extract, transform, and load (ETL) applications. This section details the process for configuring the HP Vertica ODBC driver. It also explains how to use the ODBC API to connect to HP Vertica in your own client applications. This section assumes that you have already installed the ODBC libraries on your client system. If you have not, see Client Driver Install Procedures. ODBC Architecture The ODBC architecture has four layers: Client Application Is an application that opens a data source through a Data Source Name (DSN). It then sends requests to the data source, and receives the results of those requests. Requests are made in the form of calls to ODBC functions. Driver Manager Is a library on the client system that acts as an intermediary between a client application and one or more drivers. The driver manager: Resolves the DSN provided by the client application. Loads the driver required to access the specific database defined within the DSN. Processes ODBC function calls from the client or passing them to the driver. Retrieves results from the driver. Unloads drivers when they are no longer needed. On Windows and Mac client systems, the driver manager is provided by the operating system. On Linux and UNIX systems, you usually need to install a driver manager. See ODBC Prerequisites for a list of driver managers that can be used with HP Vertica on your client platform. Driver HP Vertica Analytic Database (7.1.x) Page 127 of 401

128 Client Libraries A library on the client system that provides access to a specific database. It translates requests into the format expected by the database, and translates results back into the format required by the client application. Database The database processes requests initiated at the client application and returns results. ODBC Feature Support The ODBC driver for HP Vertica supports the most of the features defined in the Microsoft ODBC 3.5 specifications. The following features are not supported: Updatable result sets Backwards scrolling cursors Cursor attributes More than one open statement per connection. For example you cannot execute a new statement while another statement has a result set open. If you need to execute multiple statements at once, open multiple database connections. Keysets Bookmarks The HP Vertica ODBC driver accurately reports its capabilities. If you need to determine whether it complies with a specific feature, you should query the driver's capabilities directly using the SQLGetInfo() function. Updating ODBC Client Code From Previous Driver Versions In HP Vertica Version 5.1, the client drivers were rewritten to improve standards compliance and reliability. As a result, some HP Vertica-specific features and past incompatibilities have been eliminated. You must update any client code written for versions of the HP Vertica ODBC driver earlier than 5.1 to work with the newer drivers. The following topics give you an overview of the necessary code changes. DSN Parameter Changes A number of HP Vertica-specific DSN parameters have been eliminated or changed. Removed DSN Parameters The following parameters are no longer available in the 5.1 ODBC driver. HP Vertica Analytic Database (7.1.x) Page 128 of 401

129 Client Libraries Parameter BatchInsertEnforceLength BinaryDataTransfer BoolAsChar Debug LRSPath and LRSStreaming SupressWarnings WideCharSizeIn and WideCharSizeOut Description Batch inserts behave the same way all other inserts behave. If a piece of data is too wide for its column, the row will be rejected. To avoid having rows rejected, either truncate the data yourself or use the COPY statement directly, which defaults to truncating data. All data is now transferred using NATIVE VARCHAR. Boolean columns can no longer be bound to SQL_CHAR values. Use SQL_BIT values instead. Use the LogLevel parameter instead. The ODBC driver now always streams data. It does not cache data on the local disk. Removed to prevent clients from ignoring warnings. These options are now set using the DriverManagerEncoding option in the vertica.ini file. Changed DSN Parameters The following DSN parameter have changed since the previous version of the ODBC driver. Parameter MaxMemoryCache Description This parameteris now named ResultBufferSize to make its name consistent across all HP Vertica client drivers. New DSN Parameter The following DSN parameters are new in the version 5.1 ODBC driver. Parameter DriverStringConversions ThreePartNaming Description Determines whether strings sent between the server and the ODBC client are converted. Controls whether the database metadata uses the database name as the catalog name. This parameter is only used for backwards compatibility with some client software that expects a non-null catalog name. HP Vertica Analytic Database (7.1.x) Page 129 of 401

130 Client Libraries New DSN Parameter Alias Parameter Password SessionLabel UserName Description An alias for PWD. This is a new alias for the existing Label parameter that lets you assign a label to an ODBC connection. An alias for UID. Function Changes The following functions have changed their behavior in the version 5.1 drivers. SQLGetInfo() now returns the file name of the ODBC library file when queried for the SQL_ DRIVER_NAME. Previous versions would return the brand name of the driver, which is not part of the ODBC specifications. In previous versions of the ODBC driver, passing the SQLGetInfo function SQL_PARAM_ ARRAY_SELECTS returned SQL_PAS_BATCH, indicating that the driver returns a batch for each set of parameters in a SELECT statement. This return value was incorrect. The driver now correctly returns SQL_PAS_NO_SELECT, which indicates that the driver does not support SELECT queries using arrays of parameters. For better compatibility with the ODBC standards, the time data type in the ODBC driver no longer contain fractions of a second. In the new driver, functions that convert time values to strings (for example, a SQLBindCol() call to bind a SQL_TYPE_TIME to a SQL_C_CHAR value) no longer add fractional second values to the string. Earlier versions of the driver would return the fractions of a second that the HP Vertica database stores. SQLBindParameter() now requires that its column-size argument for variable-width columns (such as SQL_CHAR, SQL_VARCHAR, SQL_VARBINARY) be non-zero as specified in the ODBC standards. The implementation of this function in previous versions of the driver allowed a non-standard zero value to indicate the column width was a default width value. The driver is now more strict about converting from character data types to numerical data types. In previous drivers, any portion of the character string that could not be converted to a numeric value was ignored. The new driver returns an error if any portion of the string cannot be converted. For example, asking the previous driver to insert the character string "3 days" to an integer column resulted in the value 3 being stored in the column. Now, the driver returns an error when attempting to store this character value in an integer column. Functions that return result sets containing catalog metadata now return SQL_WVARCHAR columns instead of SQL_VARCHAR columns. This is standard behavior for ODBC 3.52 drivers that are Unicode capable. HP Vertica Analytic Database (7.1.x) Page 130 of 401

131 Client Libraries Removed Functions The LCOPY function has been removed from the version 5.1 driver. You should instead use the LOCAL option of the COPY SQL statement to copy data from the client system to the server. See Streaming Data From the Client Using COPY LOCAL. Interval and TimeStamp Changes When you call the SQLBindParameter() function to bind a SQL_C_INTERVAL value (for example, SQL_INTERVAL_STRUCT) to an INTERVAL column after calling SQLPrepare(), the interval leading precision is now reset to the default value of 2. Earlier versions of the driver did not reset the leading precision as called for in the ODBC standards. If you want your interval value to have a greater leading precision, your client application can take either of the following steps: Call SQLBindParamter() to bind the value to the INTERVAL column before calling SQLPrepare (). The interval precision is not reset unless you call SQLBindParameter() after you have called SQLPrepare(). Reset the leading precision by using the SQLSetDescField() function to set SQL_DESC_ DATETIME_INTERVAL_PRECISION to whatever value you want. SQLDescribeCol() now returns a new width for interval data types. For example, when passed SQL_INTERVAL_SECOND, the previous driver would return 21 bytes. The new driver returns 16. In general, the new drivers are more strict regarding interval values, and throw errors when the old drivers silently truncated values. If your application throws an exception when dealing with an interval, your first debugging step is to make sure the values you are inserting are the correct width and type. Note: The units interval style is not supported. Do not use the SET INTERVALSTYLE statement to change the interval style in your client applications. SQLBindParameter() is more strict about the number of digits you supply in fractions of a second in a timestamp. For example, the following call generates an error: SQL_TIMESTAMP_STRUCT ts;ts.fraction = ; //represents the fraction SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_TIMESTAMP, SQL_TYPE_TIMESTAMP, 0, 6, (SQLPOINTER)&ts, 0, NULL); SQLExecute(hstmt); The error occurs because the fractional value represents more than six digits. Instead you would need to change the SQLBindParameter call to allow 9 digits in the fraction: SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_TIMESTAMP, SQL_TYPE_TIMESTAMP, 0, 9, (SQLPOINTER)&ts, 0, NULL); HP Vertica Analytic Database (7.1.x) Page 131 of 401

132 Client Libraries Note that the fraction will be truncated to , since timestamps do not have nanosecond precision. But you still need to allow for all of the fractional digits to be inserted into the timestamp. New Additional Driver Information The new HP Vertica version 5.1 ODBC driver has some additional configuration settings not covered by the standard ODBC.INI file. use a configuration file named vertica.ini on Linux, AIX, Solaris, and HP-UX. It controls several features of the ODBC driver. For more information, see Additional Linux ODBC Driver Configuration Settings. -specific ODBC Header File The HP Vertica ODBC driver provides a C header file named verticaodbc.h that defines several useful constants that you can use in your applications. These constants let you access and alter HP Vertica-specific settings. This file's location depends on your client operating system: /opt/vertica/include on Linux and UNIX systems. C:\Program Files (x86)\vertica\odbc\include on Windows systems. The constants defined in this file are listed below. Parameter Description Associated Function SQL_ATTR_VERTICA_RESULT_BUFFER_ SIZE Sets the size of the buffer used when retrieving results from the server. SQLSetConnectAttr() SQLGetConnectAttr() HP Vertica Analytic Database (7.1.x) Page 132 of 401

133 Client Libraries Parameter Description Associated Function SQL_ATTR_VERTICA_DIRECT_BATCH_ INSERT SQL_ATTR_VERTICA_LOCALE Determines whether a batch is inserted directly into the ROS (1) or using AUTO mode (0). By default batches are inserted using AUTO. When you load data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. Changes the locale from en_ US@collation=bina ry to the ICU locale specified. See Setting the Locale for ODBC Sessions for an example of using this parameter. SQLSetConnectAttr() SQLSetStmtAttr () SQLGetConnectAttr() SQLGetStmtAttr() SQLSetConnectAttr() SQLGetConnectAttr() Connecting to The first step in any ODBC application is to connect to the database. When you create the connection to a data source using ODBC, you use the name of the DSN that contains the details of the driver to use, the database host, and other basic information about connecting to the data source. There are 4 steps your application needs to take to connect to a database: 1. Call SQLAllocHandle() to allocate a handle for the ODBC environment. This handle is used to create connection objects and to set application-wide settings. HP Vertica Analytic Database (7.1.x) Page 133 of 401

134 Client Libraries 2. Use the environment handle to set the version of ODBC that your application wants to use. This ensures that the data source knows which API your application will use to interact with it. 3. Allocate a database connection handle by calling SQLAllocHandle(). This handle represents a connection to a specific data source. 4. Use the SQLConnect() or SQLDriverConnect() functions to open the connection to the database. Note: If you specify a locale either in the connection string or in the DSN, the call to the connection function returns SQL_SUCCESS_WITH_INFO on a successful connection, with messages about the state of the locale. When creating the connection to the database, use SQLConnect() when the only options you need to set at connection time is the username and password. Use SQLDriverConnect() when you want to change connection options, such as the locale. The following example demonstrates connecting to a database using a DSN named ExampleDB. After it creates the connection successfully, this example simply closes it. // Demonstrate connecting to Vertica using ODBC. // Standard i/o library #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // SQL include files that define data types and ODBC API // functions #include <sql.h> #include <sqlext.h> #include <sqltypes.h> int main() SQLRETURN ret; // Stores return value from ODBC API calls SQLHENV hdlenv; // Handle for the SQL environment object // Allocate an a SQL environment object ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Set the ODBC version we are going to use to // 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC 3.\n"); exit(exit_failure); else HP Vertica Analytic Database (7.1.x) Page 134 of 401

135 Client Libraries printf("set application version to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not allocate database handle.\n"); exit(exit_failure); else printf("allocated Database handle.\n"); // Connect to the database using // SQL Connect printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "ExampleUser"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // We're connected. You can do real // work here // When done, free all of the handles to close them // in an orderly fashion. printf("disconnecting and freeing handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting from database. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); Running the above code prints the following: Allocated an environment handle. Set application version to ODBC 3. Allocated Database handle. Connecting to database. Connected to database. Disconnecting and freeing handles. See Setting the Locale for ODBC Sessions for an example of using SQLDriverConnect to connect to the database. HP Vertica Analytic Database (7.1.x) Page 135 of 401

136 Client Libraries Notes If you use the DataDirect driver manager, you should always use the SQL_DRIVER_ NOPROMPT value for the SQLDriverConnect function's DriverCompletion parameter (the final parameter in the function call) when connecting to HP Vertica. HP Vertica's ODBC driver on Linux and UNIX platforms does not contain a UI, and therefore cannot prompt users for a password. On Windows client platforms, the ODBC driver can prompt users for connection information. See Prompting Windows Users for Missing Connection Parameters for more information. If your database does not comply with your HP Vertica license agreement, your application receives a warning message in the return value of the SQLConnect() function. Always have your application examine this return value to see if it is SQL_SUCCESS_WITH_INFO. If it is, have your application extract and display the message to the user. Enabling Native Connection Load Balancing in ODBC Native connection load balancing helps spread the overhead caused by client connections on the hosts in the HP Vertica database. Both the server and the client must enable native connection load balancing in order for it to have an effect. If both have enabled it, then when the client initially connects to a host in the database, the host picks a host to handle the client connection from a list of the currently up hosts in the database, and informs the client which host it has chosen. If the initially-contacted host did not choose itself to handle the connection, the client disconnects, then opens a second connection to the host selected by the first host. The connection process to this second host proceeds as usual if SSL is enabled, then SSL negotiations begin, otherwise the client begins the authentication process. See About Native Connection Load Balancing in the Administrator's Guide for details. To enable native load balancing on your client, set the ConnectionLoadBalance connection parameter to true either in the DSN entry or in the connection string. The following example demonstrates connecting to the database several times with native connection load balancing enabled, and fetching the name of the node handling the connection from the V_ MONITOR.CURRENT_SESSION system table. // Demonstrate enabling native load connection balancing. // Standard i/o library #include <stdlib.h> #include <iostream> #include <assert.h> // Only needed for Windows clients // #include <windows.h> // SQL include files that define data types and ODBC API // functions #include <sql.h> #include <sqlext.h> #include <sqltypes.h> using namespace std; HP Vertica Analytic Database (7.1.x) Page 136 of 401

137 Client Libraries int main() SQLRETURN ret; // Stores return value from ODBC API calls SQLHENV hdlenv; // Handle for the SQL environment object // Allocate an a SQL environment object ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); assert(sql_succeeded(ret)); // Set the ODBC version we are going to use to // 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); assert(sql_succeeded(ret)); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); assert(sql_succeeded(ret)); // Connect four times. If load balancing is on, client should // connect to different nodes. for (int x=1; x <= 4; x++) // Connect to the database using SQLDriverConnect. Set // ConnectionLoadBalance to 1 (true) to enable load // balancing. cout << endl << "Connection attempt #" << x << "... "; const char *connstr = "DSN=VMart;ConnectionLoadBalance=1;" "UID=ExampleUser;PWD=password123"; ret = SQLDriverConnect(hdlDbc, NULL, (SQLCHAR*)connStr, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT ); if(!sql_succeeded(ret)) cout << "failed. Exiting." << endl; exit(exit_failure); else cout << "succeeded" << endl; // We're connected. Query the v_monitor.current_session table to // find the name of the node we've connected to. // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); assert(sql_succeeded(ret)); ret = SQLExecDirect( hdlstmt, (SQLCHAR*)"SELECT node_name FROM " "V_MONITOR.CURRENT_SESSION;", SQL_NTS ); if(sql_succeeded(ret)) // Bind varible to column in result set. SQLTCHAR node_name[256]; ret = SQLBindCol(hdlStmt, 1, SQL_C_TCHAR, (SQLPOINTER)node_name, sizeof(node_name), NULL); while(sql_succeeded(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT,1))) // Print the bound variables, which now contain the values from the // fetched row. HP Vertica Analytic Database (7.1.x) Page 137 of 401

138 Client Libraries cout << "Connected to node " << node_name << endl; // Free statement handle SQLFreeHandle(SQL_HANDLE_STMT,hdlStmt); cout << "Disconnecting." << endl; ret = SQLDisconnect( hdldbc ); assert(sql_succeeded(ret)); // When done, free all of the handles to close them // in an orderly fashion. cout << endl << "Freeing handles..." << endl; SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); cout << "Done!" << endl; exit(exit_success); Running the above example produces output similar to the following: Connection attempt #1... succeeded Connected to node v_vmart_node0001 Disconnecting. Connection attempt #2... succeeded Connected to node v_vmart_node0002 Disconnecting. Connection attempt #3... succeeded Connected to node v_vmart_node0003 Disconnecting. Connection attempt #4... succeeded Connected to node v_vmart_node0001 Disconnecting. Freeing handles... Done! ODBC Connection Failover If a client application attempts to connect to a host in the Vertica Analytic Database cluster that is down, the connection attempt fails when using the default connection configuration. This failure usually returns an error to the user. The user must either wait until the host recovers and retry the connection or manually edit the connection settings to choose another host. Due to Vertica Analytic Database's distributed architecture, you usually do not care which database host handles a client application's connection. You can use the client driver's connection failover feature to prevent the user from getting connection errors when the host specified in the connection settings is unreachable. It gives you two ways to let the client driver automatically attempt to connect to a different host if the one specified in the connection parameters is unreachable: HP Vertica Analytic Database (7.1.x) Page 138 of 401

139 Client Libraries Configure your DNS server to return multiple IP addresses for a host name. When you use this host name in the connection settings, the client attempts to connect to the first IP address from the DNS lookup. If the host at that IP address is unreachable, the client tries to connect to the second IP, and so on until it either manages to connect to a host or it runs out of IP addresses. Supply a list of backup hosts for the client driver to try if the primary host you specify in the connection parameters is unreachable. For both methods, the process of failover is transparent to the client application (other than specifying the list of backup hosts, if you choose to use the list method of failover). If the primary host is unreachable, the client driver automatically tries to connect to other hosts. Failover only applies to the initial establishment of the client connection. If the connection breaks, the driver does not automatically try to reconnect to another host in the database. Choosing a Failover Method You usually choose to use one of the two failover methods. However, they do work together. If your DNS server returns multiple IP addresses and you supply a list of backup hosts, the client first tries all of the IPs returned by the DNS server, then the hosts in the backup list. Note: If a host name in the backup host list resolves to multiple IP addresses, the client does not try all of them. It just tries the first IP address in the list. The DNS method of failover centralizes the configuration client failover. As you add new nodes to your Vertica Analytic Database cluster, you can choose to add them to the failover list by editing the DNS server settings. All client systems that use the DNS server to connect to Vertica Analytic Database automatically use connection failover without having to change any settings. However, this method does require administrative access to the DNS server that all clients use to connect to the Vertica Analytic Database cluster. This may not be possible in your organization. Using the backup server list is easier than editing the DNS server settings. However, it decentralizes the failover feature. You may need to update the application settings on each client system if you make changes to your Vertica Analytic Database cluster. Using DNS Failover To use DNS failover, you need to change your DNS server's settings to map a single host name to multiple IP addresses of hosts in your Vertica Analytic Database cluster. You then have all client applications use this host name to connect to Vertica Analytic Database. You can choose to have your DNS server return as many IP addresses for the host name as you want. In smaller clusters, you may choose to have it return the IP addresses of all of the hosts in your cluster. However, for larger clusters, you should consider choosing a subset of the hosts to return. Otherwise there can be a long delay as the client driver tries unsuccessfully to connect to each host in a database that is down. HP Vertica Analytic Database (7.1.x) Page 139 of 401

140 Client Libraries Using the Backup Host List To enable backup list-based connection failover, your client application has to specify at least one IP address or host name of a host in the BackupServerNode parameter. The host name or IP can optionally be followed by a colon and a port number. If not supplied, the driver defaults to the standard HP Vertica port number (5433). To list multiple hosts, separate them by a comma. The following example demonstrates setting the BackupServerNode connection parameter to specify additional hosts for the connection attempt. The connection string intentionally has a nonexistent node, so that the initial connection fails. The client driver has to resort to trying the backup hosts to establish a connection to HP Vertica. // Demonstrate using connection failover. // Standard i/o library #include <stdlib.h> #include <iostream> #include <assert.h> // Only needed for Windows clients // #include <windows.h> // SQL include files that define data types and ODBC API // functions #include <sql.h> #include <sqlext.h> #include <sqltypes.h> using namespace std; int main() SQLRETURN ret; // Stores return value from ODBC API calls SQLHENV hdlenv; // Handle for the SQL environment object // Allocate an a SQL environment object ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); assert(sql_succeeded(ret)); // Set the ODBC version we are going to use to // 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); assert(sql_succeeded(ret)); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); assert(sql_succeeded(ret)); /* DSN for this connection specifies a bad node, and good backup nodes: [VMartBadNode] Description=VMart Vertica Database Driver=/opt/vertica/lib64/libverticaodbc.so Database=VMart Servername=badnode.example.com BackupServerNode=node02.example.com,node03.example.com */ HP Vertica Analytic Database (7.1.x) Page 140 of 401

141 Client Libraries // Connect to the database using SQLConnect cout << "Connecting to database." << endl; const char *dsnname = "VMartBadNode"; // Name of the DSN const char* userid = "ExampleUser"; // Username const char* passwd = "password123"; // password ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) cout << "Could not connect to database." << endl; exit(exit_failure); else cout << "Connected to database." << endl; // We're connected. Query the v_monitor.current_session table to // find the name of the node we've connected to. // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); assert(sql_succeeded(ret)); ret = SQLExecDirect( hdlstmt, (SQLCHAR*)"SELECT node_name FROM " "v_monitor.current_session;", SQL_NTS ); if(sql_succeeded(ret)) // Bind varible to column in result set. SQLTCHAR node_name[256]; ret = SQLBindCol(hdlStmt, 1, SQL_C_TCHAR, (SQLPOINTER)node_name, sizeof(node_name), NULL); while(sql_succeeded(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT,1))) // Print the bound variables, which now contain the values from the // fetched row. cout << "Connected to node " << node_name << endl; cout << "Disconnecting." << endl; ret = SQLDisconnect( hdldbc ); assert(sql_succeeded(ret)); // When done, free all of the handles to close them // in an orderly fashion. cout << endl << "Freeing handles..." << endl; SQLFreeHandle(SQL_HANDLE_STMT,hdlStmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); cout << "Done!" << endl; exit(exit_success); When run, the example's output on the system console is similar to the following: HP Vertica Analytic Database (7.1.x) Page 141 of 401

142 Client Libraries Connecting to database. Connected to database. Connected to node v_vmart_node0002 Disconnecting. Freeing handles... Done! Notice that the connection was made to the first node in the backup list (node 2). Note: When native connection load balancing is enabled, the additional servers specified in the BackupServerNode connection parameter are only used for the initial connection to an HP Vertica host. If host redirects the client to another host in the database cluster to handle its connection request, the second connection does not use the backup node list. This is rarely an issue, since native connection load balancing is aware of which nodes are currently up in the database. See Enabling Native Connection Load Balancing in ODBC Prompting Windows Users for Missing Connection Parameters The HP Vertica Windows ODBC driver can prompt the user for connection information if required information is missing. The driver displays the HP Vertica Connection Dialog if the client application calls SQLDriverConnect to connect to HP Vertica and either of the following is true: the DriverCompletion parameter is set to SQL_DRIVER_PROMPT. the DriverCompletion parameter is set to SQL_DRIVER_COMPLETE or SQL_DRIVER_ COMPLETE_REQUIRED and the connection string or DSN being used to connect is missing the server, database, or port information. If either of the above conditions are true, the driver displays an HP Vertica Connection Dialog to the user to prompt for connection information. HP Vertica Analytic Database (7.1.x) Page 142 of 401

143 Client Libraries Any parameters supplied in the connection string or DSN filled in on the dialog. Note: Your connection string at least needs to specify Vertica as the driver, otherwise Windows will not know to use the Vertica ODBC driver to try to open the connection. The required fields on the connection dialog are Database, UID, Server, and Port. Once these are filled in, the form enables the OK button. If the user clicks Cancel on the dialog, the SQLDriverConnect function call returns SQL_NO_ DATA immediately, without attempting to connect to HP Vertica. If the user supplies incomplete or incorrect information for the connection, the connection function returns SQL_ERROR after the connection attempt fails. Note: If the DriverCompletion parameter of the SQLDriverConnect function call is SQL_ DRIVER_NOPROMPT, the ODBC driver immediately returns a SQL_ERROR indicating that it cannot connect because not enough information has been supplied and the driver is not allowed to prompt the user for the missing information. Prompting Windows Users for Passwords If the connection string or DSN supplied to the SQLDriverConnect function that client applications call to connect to HP Vertica lacks any of the required connection properties needed to connect, the HP Vertica's Windows ODBC driver opens a dialog box to prompt the user to enter the missing information (see Prompting Windows Users for Missing Connection Parameters). The user's password is not normally considered a required connection property, since HP Vertica user accounts may not have a password. If the password property is missing, the ODBC driver still tries to connect to HP Vertica without supplying a password. You can use the PromptOnNoPassword DSN parameter to force ODBC driver to treat the password as a required connection property. This parameter is useful if you do not want to store passwords in DSN entries. Passwords saved in DSN entries are insecure, since they are stored as clear text in the Windows registry and therefore visible to other users on the same system. There are two other factors which also decide whether the ODBC driver displays the HP Vertica Connection Dialog. These are (in order of priority): The SQLDriverConnect function call's DriverCompletion parameter. Whether the DSN or connection string contain a password The following table shows how the PromptOnNoPassword DSN parameter, the DriverCompletion parameter of the SQLDriverConnect function, and whether the DSN or connection string contains a password interact to control whether the HP Vertica Connection dialog appears. HP Vertica Analytic Database (7.1.x) Page 143 of 401

144 Client Libraries PromptOnNoPassword Setting DriverCompletion Value DSN or Connection String Contains Password? HP Vertica Connection Dialog Displays? Notes any value any value any value SQL_DRIVER_ PROMPT SQL_DRIVER_ NOPROMPT SQL_DRIVER_ COMPLETE any case Yes This DriverCompletion value forces the dialog to always appear, even if all required connection properties are supplied. any case No This DriverCompletion value always prevents the dialog from appearing. Yes No Connection dialog displays if another required connection property is missing. true SQL_DRIVER_ COMPLETE No Yes false (default) SQL_DRIVER_ COMPLETE No No Connection dialog displays if another required connection property is missing. The following example code demonstrates using the PromptOnNoPassword DSN parameter along with a system DSN. wstring connectstring = L"DSN=VerticaDSN;PromptOnNoPassword=1;"; retcode = SQLDriverConnect( hdbc, 0, (SQLWCHAR*)connectString.c_str(), connectstring.length(), OutConnStr, 255, HP Vertica Analytic Database (7.1.x) Page 144 of 401

145 Client Libraries &OutConnStrLen, SQL_DRIVER_COMPLETE ); No Password Entry vs. Empty Passwords There is a difference between not having a password property in the connection string or DSN and having an empty password. The PromptOnNoPassword DSN parameter only has an effect if the connection string or DSN does not have a PWD property (which holds the user's password). If it does, even if it is empty, PromptOnNoPassword will not prompt the Windows ODBC driver to display the HP Vertica Connection Dialog. This difference can cause confusion if you are using a DSN to provide the properties for your connection. Once you enter a password for a DSN connection in the Windows ODBC Manager and save it, Windows adds a PWD property to the DSN definition in the registry. If you later delete the password, the PWD property remains in the DSN definition value is just set to an empty string. The PWD property is created even if you just use the Test button on the ODBC Manager dialog to test the DSN and later clear it before saving the DSN. Once the password has been set, the only way to remove the PWD property from the DSN definition is to delete it using the Windows Registry Editor: 1. On the Windows Start menu, click Run. 2. In the Run dialog, type regedit, then click OK. 3. In the Registry Editor window, click Edit > Find (or press Ctrl+F). 4. In the Find window, enter the name of the DSN whose PWD property you want to delete and click OK. HP Vertica Analytic Database (7.1.x) Page 145 of 401

146 Client Libraries 5. If find operation did not locate a folder under the ODBC.INI folder, click Edit > Find Next (or press F3) until the folder matching your DSN's name is highlighted. 6. Select the PWD entry and press Delete. 7. Click Yes to confirm deleting the value. The DSN now does not have a PWD property and can trigger the connection dialog to appear when used along with PromptOnNoPassword=true and DriverConnect=SQL_DRIVER_COMPLETE. Setting the Locale for ODBC Sessions HP Vertica provides three ways to set the locale for an ODBC session: Specify the locale for all connections made using the DSN: On Linux and other UNIX-like platforms: Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX On Windows platforms, set the locale in the ODBC DSN configuration editor's Locale field on the Server Settings tab. See Creating an ODBC DSN for Windows Clients for detailed information. Set the Locale connection parameter in the connection string in SQLDriverConnect() function. For example: HP Vertica Analytic Database (7.1.x) Page 146 of 401

147 Client Libraries SQLDriverConnect(conn, NULL, (SQLCHAR*)"DSN=Vertica;Locale=en_GB", SQL_NTS, szconnout, sizeof(szconnout), &iavailable, SQL_DRIVER_NOPROMPT) Use the SQLSetConnectAttr() method with the SQL_ATTR_VERTICA_LOCALE constant and specify the ICU string as the attribute value. See the example below. Notes Having the client system use a non-unicode locale (such as setting LANG=C on Linux platforms) and using a Unicode locale for the connection to HP Vertica can result in errors such as "(10170) String data right truncation on data from data source." If data received from HP Vertica isn't in UTF-8 format. The driver allocates string memory based on the system's locale setting, and non-utf-8 data can trigger an overrun. You can avoid these errors by always using a Unicode locale on the client system. If you specify a locale either in the connection string or in the DSN, the call to the connection function returns SQL_SUCCESS_WITH_INFO on a successful connection, with messages about the state of the locale. ODBC applications can be in either ANSI or Unicode mode: If Unicode, the encoding used by ODBC is UCS-2. If ANSI, the data must be in single-byte ASCII, which is compatible with UTF-8 on the database server. The ODBC driver converts UCS-2 to UTF-8 when passing to the HP Vertica server and converts data sent by the HP Vertica server from UTF-8 to UCS-2. If the end-user application is not already in UCS-2, the application is responsible for converting the input data to UCS-2, or unexpected results could occur. For example: On non-ucs-2 data passed to ODBC APIs, when it is interpreted as UCS-2, it could result in an invalid UCS-2 symbol being passed to the APIs, resulting in errors. Or the symbol provided in the alternate encoding could be a valid UCS-2 symbol; in this case, incorrect data is inserted into the database. ODBC applications should set the correct server session locale using SQLSetConnectAttr (if different from database-wide setting) in order to set the proper collation and string functions behavior on server. The following example code demonstrates setting the locale using both the connection string and through the SQLSetConnectAttr() function. // Standard i/o library #include <stdio.h> #include <stdlib.h> HP Vertica Analytic Database (7.1.x) Page 147 of 401

148 Client Libraries // Only needed for Windows clients // #include <windows.h> // SQL include files that define data types and ODBC API // functions #include <sql.h> #include <sqlext.h> #include <sqltypes.h> // Vertica-specific definitions. This include file is located as // /opt/vertica/include on database hosts. #include <verticaodbc.h> int main() SQLRETURN ret; // Stores return value from ODBC API calls SQLHENV hdlenv; // Handle for the SQL environment object // Allocate an a SQL environment object ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Set the ODBC version we are going to use to 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC 3.\n"); exit(exit_failure); else printf("set application version to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not allocate database handle.\n"); exit(exit_failure); else printf("allocated Database handle.\n"); // Connect to the database using SQLDriverConnect printf("connecting to database.\n"); // Set the locale to English in Great Britain. const char *connstr = "DSN=ExampleDB;locale=en_GB;" "UID=dbadmin;PWD=password123"; ret = SQLDriverConnect(hdlDbc, NULL, (SQLCHAR*)connStr, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT ); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Get the Locale char locale[256]; SQLGetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, locale, sizeof(locale), 0); printf("locale is set to: %s\n", locale); HP Vertica Analytic Database (7.1.x) Page 148 of 401

149 Client Libraries // Set the locale to a new value const char* newlocale = "en_gb"; SQLSetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, (SQLCHAR*)newLocale, SQL_NTS); // Get the Locale again SQLGetConnectAttr(hdlDbc, SQL_ATTR_VERTICA_LOCALE, locale, sizeof(locale), 0); printf("locale is now set to: %s\n", locale); // When done, free all of the handles to close them // in an orderly fashion. printf("disconnecting and freeing handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting from database. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); AUTOCOMMIT and ODBC Transactions The AUTOCOMMIT connection attribute controls whether INSERT, ALTER, COPY and other data-manipulation statements are automatically committed after they complete. By default, AUTOCOMMIT is enabled all statements are committed after they execute. This is often not the best setting to use, since it is less efficient. Also, you often want to control whether a set of statements are committed as a whole, rather than have each individual statement committed. For example, you may only want to commit a series of inserts if all of the inserts succeed. With AUTOCOMMIT disabled, you can roll back the transaction if one of the statements fail. If AUTOCOMMIT is on, the results of statements are committed immediately after they are executed. You cannot roll back a statement executed in AUTOCOMMIT mode. For example, when AUTOCOMMIT is on, the following single INSERT statement is automatically committed: ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500," "'Smith, Sam', ' ');", SQL_NTS); If AUTOCOMMIT is off, you need to manually commit the transaction after executing a statement. For example: ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500," "'Smith, Sam', ' ');", SQL_NTS); // Other inserts and data manipulations // Commit the statements(s) ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); The inserted row is only committed when you call SQLEndTran(). You can roll back the INSERT and other statements at any point before committing the transaction. HP Vertica Analytic Database (7.1.x) Page 149 of 401

150 Client Libraries Note: Prepared statements cache the AUTOCOMMIT setting when you create them using SQLPrepare(). Later changing the connection's AUTOCOMMIT setting has no effect on the AUTOCOMMIT settings of previously created prepared statements. See Using Prepared Statements for details. The following example demonstrates turning off AUTOCOMMIT, executing an insert, then manually committing the transaction. // Some standard headers #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> int main() // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Tell ODBC that the application uses ODBC 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not allocate database handle.\n"); exit(exit_failure); else printf("allocated Database handle.\n"); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) HP Vertica Analytic Database (7.1.x) Page 150 of 401

151 Client Libraries printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Get the AUTOCOMMIT state SQLINTEGER autocommitstate; SQLGetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, &autocommitstate, 0, NULL); printf("autocommit is set to: %d\n", autocommitstate); // Disable AUTOCOMMIT printf("disabling autocommit.\n"); ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF, SQL_NTS); if(!sql_succeeded(ret)) printf("could not disable autocommit.\n"); exit(exit_failure); // Get the AUTOCOMMIT state again SQLGetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, &autocommitstate, 0, NULL); printf("autocommit is set to: %d\n", autocommitstate); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); // Create a table to hold the data SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers " "(CustID int, CustName varchar(100), Phone_Number char(15));", SQL_NTS); // Insert a single row. ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"INSERT INTO customers VALUES(500," "'Smith, Sam', ' ');", SQL_NTS); if(!sql_succeeded(ret)) printf("could not perform single insert.\n"); else printf("performed single insert.\n"); // Need to commit the transaction before closing, since autocommit is // disabled. Otherwise SQLDisconnect returns an error. printf("committing transaction.\n"); ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); if(!sql_succeeded(ret)) printf("error committing transaction.\n"); exit(exit_failure); // Clean up printf("free handles.\n"); HP Vertica Analytic Database (7.1.x) Page 151 of 401

152 Client Libraries ret = SQLDisconnect(hdlDbc); if(!sql_succeeded(ret)) printf("error disconnecting from database. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); Running the above code results in the following output: Allocated an environment handle. Set application to ODBC 3. Allocated Database handle. Connecting to database. Connected to database. Autocommit is set to: 1 Disabling autocommit. Autocommit is set to: 0 Performed single insert. Committing transaction. Free handles. Note: You can also disable AUTOCOMMIT in the ODBC connection string. See Setting DSN Connection Parameters for more information. Retrieving Data Through ODBC To retrieve data through ODBC, you execute a query that returns a result set (SELECT, for example), then retrieve the results using one of two methods: Use the SQLFetch() function to retrieve a row of the result set, then access column values in the row by calling SQLGetData(). Use the SQLBindColumn() function to bind a variable or array to a column in the result set, then call SQLExtendedFetch() or SQLFetchScroll() to read a row of the result set and insert its values into the variable or array. In both methods you loop through the result set until you either reach the end (signaled by the SQL_ NO_DATA return status) or encounter an error. Note: HP Vertica supports one cursor per connection. Attempting to use more than one cursor per connection will result in an error. For example, you receive an error if you execute a statement while another statement has a result set open. The following code example demonstrates retrieving data from HP Vertica by: HP Vertica Analytic Database (7.1.x) Page 152 of 401

153 Client Libraries 1. Connecting to the database. 2. Executing a SELECT statement that returns the IDs and names of all tables. 3. Binds two variables to the two columns in the result set. 4. Loops through the result set, printing the ids and name values. // Demonstrate running a query and getting results by querying the tables // system table for a list of all tables in the current schema. // Some standard headers #include <stdlib.h> #include <sstream> #include <iostream> #include <assert.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> // Use std namespace to make output easier using namespace std; // Helper function to print SQL error messages. template <typename HandleT> void reporterror(int handletypeenum, HandleT hdl) // Get the status records. SQLSMALLINT i, MsgLen; SQLRETURN ret2; SQLCHAR SqlState[6], Msg[SQL_MAX_MESSAGE_LENGTH]; SQLINTEGER NativeError; i = 1; cout << endl; while ((ret2 = SQLGetDiagRec(handleTypeEnum, hdl, i, SqlState, &NativeError, Msg, sizeof(msg), &MsgLen))!= SQL_NO_DATA) cout << "error record #" << i++ << endl; cout << "sqlstate: " << SqlState << endl; cout << "detailed msg: " << Msg << endl; cout << "native error code: " << NativeError << endl; int main() // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); assert(sql_succeeded(ret)); // Tell ODBC that the application uses ODBC 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); assert(sql_succeeded(ret)); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); assert(sql_succeeded(ret)); // Connect to the database HP Vertica Analytic Database (7.1.x) Page 153 of 401

154 Client Libraries cout << "Connecting to database." << endl; const char* dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) cout << "Could not connect to database" << endl; reporterror<sqlhdbc>(sql_handle_dbc, hdldbc); exit(exit_failure); else cout << "Connected to database." << endl; // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); assert(sql_succeeded(ret)); // Execute a query to get the names and IDs of all tables in the schema // search p[ath (usually public). ret = SQLExecDirect( hdlstmt, (SQLCHAR*)"SELECT table_id, table_name " "FROM tables ORDER BY table_name", SQL_NTS ); if(!sql_succeeded(ret)) // Report error an go no further if statement failed. cout << "Error executing statement." << endl; reporterror<sqlhdbc>(sql_handle_stmt, hdlstmt); exit(exit_failure); else // Query succeeded, so bind two variables to the two colums in the // result set, cout << "Fetching results..." << endl; SQLBIGINT table_id; // Holds the ID of the table. SQLTCHAR table_name[256]; // buffer to hold name of table ret = SQLBindCol(hdlStmt, 1, SQL_C_SBIGINT, (SQLPOINTER)&table_id, sizeof(table_id), NULL); ret = SQLBindCol(hdlStmt, 2, SQL_C_TCHAR, (SQLPOINTER)table_name, sizeof(table_name), NULL); // Loop through the results, while( SQL_SUCCEEDED(ret = SQLFetchScroll(hdlStmt, SQL_FETCH_NEXT,1))) // Print the bound variables, which now contain the values from the // fetched row. cout << table_id << " " << table_name << endl; // See if loop exited for reasons other than running out of data if (ret!= SQL_NO_DATA) // Exited for a reason other than no more data... report the error. reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); HP Vertica Analytic Database (7.1.x) Page 154 of 401

155 Client Libraries // Clean up by shutting down the connection cout << "Free handles." << endl; ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) cout << "Error disconnecting. Transaction still open?" << endl; exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); Running the example code in the vmart database produces output similar to this: Connecting to database. Connected to database. Fetching results call_center_dimension customer_dimension customers date_dimension employee_dimension inventory_fact online_page_dimension online_sales_fact product_dimension promotion_dimension shipping_dimension store_dimension store_orders_fact store_sales_fact t vendor_dimension warehouse_dimension Free handles. Loading Data Through ODBC A primary task for many client applications is loading data into the HP Vertica database. There are several different ways to insert data using ODBC, which are covered by the topics in this section. Using a Single Row Insert The easiest way to load data into HP Vertica is to run an INSERT SQL statement using the SQLExecuteDirect function. However this method is limited to inserting a single row of data. ret = SQLExecDirect(hstmt, (SQLTCHAR*)"INSERT into Customers values" "(1,'abcda','efgh','1')", SQL_NTS); HP Vertica Analytic Database (7.1.x) Page 155 of 401

156 Client Libraries Using Prepared Statements HP Vertica supports using server-side prepared statements with both ODBC and JDBC. Prepared statements let you define a statement once, and then run it many times with different parameters. The statement you want to execute contains placeholders instead of parameters. When you execute the statement, you supply values for each placeholder. Placeholders are represented by question marks (?) as in the following example query: SELECT * FROM public.inventory_fact WHERE product_key =? Server-side prepared statements are useful for: Optimizing queries. HP Vertica only needs to parse the statement once. Preventing SQL injection attacks. A SQL injection attack occurs when user input is either incorrectly filtered for string literal escape characters embedded in SQL statements or user input is not strongly typed and thereby unexpectedly run. Since a prepared statement is parsed separately from the input data, there is no chance the data can be accidentally executed by the database. Binding direct variables to return columns. By pointing to data structures, the code doesn't have to perform extra transformations. The following example demonstrates a using a prepared statement for a single insert. // Some standard headers #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> // Some constants for the size of the data to be inserted. #define CUST_NAME_LEN 50 #define PHONE_NUM_LEN 15 #define NUM_ENTRIES 4 int main() // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Tell ODBC that the application uses ODBC 3. HP Vertica Analytic Database (7.1.x) Page 156 of 401

157 Client Libraries ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Disable AUTOCOMMIT printf("disabling autocommit.\n"); ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF, SQL_NTS); if(!sql_succeeded(ret)) printf("could not disable autocommit.\n"); exit(exit_failure); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers " "(CustID int, CustName varchar(100), Phone_Number char(15));", SQL_NTS); // Set up a bunch of variables to be bound to the statement // parameters. // Create the prepared statement. This will insert data into the // table we created above. printf("creating prepared statement\n"); ret = SQLPrepare (hdlstmt, (SQLTCHAR*)"INSERT INTO customers (CustID, " "CustName, Phone_Number) VALUES(?,?,?)", SQL_NTS) ; if(!sql_succeeded(ret)) printf("could not create prepared statement\n"); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); HP Vertica Analytic Database (7.1.x) Page 157 of 401

158 Client Libraries exit(exit_failure); else printf("created prepared statement.\n"); SQLINTEGER custid = 1234; SQLCHAR custname[100] = "Fein, Fredrick"; SQLVARCHAR phonenum[15] = " "; SQLLEN strfieldlen = SQL_NTS; SQLLEN custidlen = 0; // Bind the data arrays to the parameters in the prepared SQL // statement ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER, 0, 0, &custid, 0, &custidlen); if(!sql_succeeded(ret)) printf("could not bind custid array\n"); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_failure); else printf("bound custid to prepared statement\n"); // Bind CustNames SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0, (SQLPOINTER)custName, 0, &strfieldlen); if(!sql_succeeded(ret)) printf("could not bind custnames\n"); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_failure); else printf("bound custname to prepared statement\n"); // Bind phonenums SQLBindParameter(hdlStmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 15, 0, (SQLPOINTER)phoneNum, 0, &strfieldlen); if(!sql_succeeded(ret)) printf("could not bind phonenums\n"); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_failure); else printf("bound phonenum to prepared statement\n"); // Execute the prepared statement. printf("running prepared statement..."); ret = SQLExecute(hdlStmt); if(!sql_succeeded(ret)) printf("not successful!\n"); else printf("successful.\n"); // Done with batches, commit the transaction printf("committing transaction\n"); ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); HP Vertica Analytic Database (7.1.x) Page 158 of 401

159 Client Libraries if(!sql_succeeded(ret)) printf("could not commit transaction\n"); else printf("committed transaction\n"); // Clean up printf("free handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); Using Batch Inserts You use batch inserts to insert chunks of data into the database. By breaking the data into batches, you can monitor the progress of the load by receiving information about any rejected rows after each batch is loaded. To perform a batch load through ODBC, you typically use a prepared statement with the parameters bound to arrays that contain the data to be loaded. For each batch, you load a new set of data into the arrays then execute the prepared statement. When you perform a batch load, HP Vertica uses a COPY statement to load the data. Each additional batch you load uses the same COPY statement. The statement remains open until you end the transaction, close the cursor for the statement, or execute a non-insert statement. Using a single COPY statement for multiple batches improves batch loading efficiency by: reducing the overhead of inserting individual batches combining individual batches into larger ROS containers Note: If the database connection has AUTOCOMMIT enabled, then the transaction is automatically committed after each batch insert statement which closes the COPY statement. Leaving AUTOCOMMIT enabled makes your batch load much less efficient, and can cause added overhead in your database as all of the smaller loads are consolidated. Even though HP Vertica uses a single COPY statement to insert multiple batches within a transaction, you can locate which (if any) rows were rejected due to invalid row formats or data type issues after each batch is loaded. See Tracking Load Status (ODBC) for details. Note: While you can find rejected rows during the batch load transaction, other types of errors (such as running out of disk space or a node shutdown that makes the database unsafe) are only reported when the COPY statement ends. HP Vertica Analytic Database (7.1.x) Page 159 of 401

160 Client Libraries Since the batch loads share a COPY statement, errors in one batch can cause earlier batches in the same transaction to be rolled back. Batch Insert Steps The steps your application needs to take in order to perform an ODBC Batch Insert are: 1. Connect to the database. 2. Disable autocommit for the connection. 3. Create a prepared statement that inserts the data you want to load. 4. Bind the parameters of the prepared statement to arrays that will contain the data you want to load. 5. Populate the arrays with the data for your batches. 6. Execute the prepared statement. 7. Optionally, check the results of the batch load to find rejected rows. 8. Repeat the previous three steps until all of the data you want to load is loaded. 9. Commit the transaction. 10. Optionally, check the results of the entire batch transaction. The following example code demonstrates a simplified version of the above steps. // Some standard headers #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> int main() // Number of data rows to insert const int NUM_ENTRIES = 4; // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); HP Vertica Analytic Database (7.1.x) Page 160 of 401

161 Client Libraries // Tell ODBC that the application uses ODBC 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not allocate database handle.\n"); exit(exit_failure); else printf("allocated Database handle.\n"); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Disable AUTOCOMMIT printf("disabling autocommit.\n"); ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF, SQL_NTS); if(!sql_succeeded(ret)) printf("could not disable autocommit.\n"); exit(exit_failure); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); // Create a table to hold the data SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers " "(CustID int, CustName varchar(100), Phone_Number char(15));", SQL_NTS); // Create the prepared statement. This will insert data into the // table we created above. printf("creating prepared statement\n"); HP Vertica Analytic Database (7.1.x) Page 161 of 401

162 Client Libraries ret = SQLPrepare (hdlstmt, (SQLTCHAR*)"INSERT INTO customers (CustID, " "CustName, Phone_Number) VALUES(?,?,?)", SQL_NTS) ; if(!sql_succeeded(ret)) printf("could not create prepared statement\n"); exit(exit_failure); else printf("created prepared statement.\n"); // This is the data to be inserted into the database. SQLCHAR custnames[][50] = "Allen, Anna", "Brown, Bill", "Chu, Cindy", "Dodd, Don" ; SQLINTEGER custids[] = 100, 101, 102, 103; SQLCHAR phonenums[][15] = " ", " ", " ", " "; // Bind the data arrays to the parameters in the prepared SQL // statement. First is the custid. ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER, 0, 0, (SQLPOINTER)custIDs, sizeof(sqlinteger), NULL); if(!sql_succeeded(ret)) printf("could not bind custid array\n"); exit(exit_failure); else printf("bound CustIDs array to prepared statement\n"); // Bind CustNames ret = SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0, (SQLPOINTER)custNames, 50, NULL); if(!sql_succeeded(ret)) printf("could not bind custnames\n"); exit(exit_failure); else printf("bound CustNames array to prepared statement\n"); // Bind phonenums ret = SQLBindParameter(hdlStmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 15, 0, (SQLPOINTER)phoneNums, 15, NULL); if(!sql_succeeded(ret)) printf("could not bind phonenums\n"); exit(exit_failure); else printf("bound phonenums array to prepared statement\n"); // Tell the ODBC driver how many rows we have in the // array. ret = SQLSetStmtAttr( hdlstmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER)NUM_ENTRIES, 0 ); if(!sql_succeeded(ret)) printf("could not bind set parameter size\n"); exit(exit_failure); else printf("bound phonenums array to prepared statement\n"); // Add multiple batches to the database. This just adds the same // batch of data four times for simplicity's sake. Each call adds // the 4 rows into the database. for (int batchloop=1; batchloop<=5; batchloop++) // Execute the prepared statement, loading all of the data HP Vertica Analytic Database (7.1.x) Page 162 of 401

163 Client Libraries // in the arrays. printf("adding Batch #%d...", batchloop); ret = SQLExecute(hdlStmt); if(!sql_succeeded(ret)) printf("not successful!\n"); else printf("successful.\n"); // Done with batches, commit the transaction printf("committing transaction\n"); ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); if(!sql_succeeded(ret)) printf("could not commit transaction\n"); else printf("committed transaction\n"); // Clean up printf("free handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); The result of running the above code is shown below. Allocated an environment handle. Set application to ODBC 3. Allocated Database handle. Connecting to database. Connected to database. Creating prepared statement Created prepared statement. Bound CustIDs array to prepared statement Bound CustNames array to prepared statement Bound phonenums array to prepared statement Adding Batch #1...successful. Adding Batch #2...successful. Adding Batch #3...successful. Adding Batch #4...successful. Adding Batch #5...successful. Committing transaction Committed transaction Free handles. The resulting table looks like this: => SELECT * FROM customers; HP Vertica Analytic Database (7.1.x) Page 163 of 401

164 Client Libraries CustID CustName Phone_Number Allen, Anna Brown, Bill Chu, Cindy Dodd, Don Allen, Anna Brown, Bill Chu, Cindy Dodd, Don Allen, Anna Brown, Bill Chu, Cindy Dodd, Don Allen, Anna Brown, Bill Chu, Cindy Dodd, Don Allen, Anna Brown, Bill Chu, Cindy Dodd, Don (20 rows) Note: An input parameter bound with the SQL_C_NUMERIC data type uses the default numeric precision (37) and the default scale (0) instead of the precision and scale set by the SQL_NUMERIC_STRUCT input value. This behavior adheres to the ODBC standard. If you do not want to use the default precision and scale, use SQLSetDescField() or SQLSetDescRec () to change them in the statement's attributes. Tracking Load Status (ODBC) After loading a batch of data, your client application can get the number of rows that were processed and find out whether each row was accepted or rejected. Finding the Number of Accepted Rows To get the number of rows processed by a batch, you add an attribute named SQL_ATTR_ PARAMS_PROCESSED_PTR to the statement object that points to a variable to receive the number rows: SQLULEN rowsprocessed; SQLSetStmtAttr(hdlStmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &rowsprocessed, 0); When your application calls SQLExecute() to insert the batch, the HP Vertica ODBC driver saves the number of rows that it processed (which is not necessarily the number of rows that were successfully inserted) in the variable you specified in the SQL_ATTR_PARAMS_PROCESSED_ PTR statement attribute. HP Vertica Analytic Database (7.1.x) Page 164 of 401

165 Client Libraries Finding the Accepted and Rejected Rows Your application can also set a statement attribute named SQL_ATTR_PARAM_STATUS_PTR that points to an array where the ODBC driver can store the result of inserting each row: SQLUSMALLINT rowresults[ NUM_ENTRIES ]; SQLSetStmtAttr(hdlStmt, SQL_ATTR_PARAM_STATUS_PTR, rowresults, 0); This array must be at least as large as the number of rows being inserted in each batch. When your application calls SQLExecute to insert a batch, the ODBC driver populates the array with values indicating whether each row was successfully inserted (SQL_PARAM_SUCCESS or SQL_ PARAM_SUCCESS_WITH_INFO) or encountered an error (SQL_PARAM_ERROR). The following example expands on the example shown in Using Batch Inserts to include reporting the number of rows processed and the status of each row inserted. // Some standard headers #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> // Helper function to print SQL error messages. template <typename HandleT> void reporterror(int handletypeenum, HandleT hdl) // Get the status records. SQLSMALLINT i, MsgLen; SQLRETURN ret2; SQLCHAR SqlState[6], Msg[SQL_MAX_MESSAGE_LENGTH]; SQLINTEGER NativeError; i = 1; printf("\n"); while ((ret2 = SQLGetDiagRec(handleTypeEnum, hdl, i, SqlState, &NativeError, Msg, sizeof(msg), &MsgLen))!= SQL_NO_DATA) printf("error record %d\n", i); printf("sqlstate: %s\n", SqlState); printf("detailed msg: %s\n", Msg); printf("native error code: %d\n\n", NativeError); i++; int main() // Number of data rows to insert const int NUM_ENTRIES = 4; SQLRETURN ret; SQLHENV hdlenv; HP Vertica Analytic Database (7.1.x) Page 165 of 401

166 Client Libraries ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not allocate database handle.\n"); exit(exit_failure); else printf("allocated Database handle.\n"); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); reporterror<sqlhdbc>(sql_handle_dbc, hdldbc); exit(exit_failure); else printf("connected to database.\n"); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); // Create a table into which we can store data printf("creating table.\n"); ret = SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers " "(CustID int, CustName varchar(50), Phone_Number char(15));", SQL_NTS); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); else printf("created table.\n"); // Create the prepared statement. This will insert data into the // table we created above. printf("creating prepared statement\n"); ret = SQLPrepare (hdlstmt, (SQLTCHAR*)"INSERT INTO customers (CustID, " HP Vertica Analytic Database (7.1.x) Page 166 of 401

167 Client Libraries "CustName, Phone_Number) VALUES(?,?,?)", SQL_NTS) ; if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); else printf("created prepared statement.\n"); // This is the data to be inserted into the database. char custnames[][50] = "Allen, Anna", "Brown, Bill", "Chu, Cindy", "Dodd, Don" ; SQLINTEGER custids[] = 100, 101, 102, 103; char phonenums[][15] = " ", " ", " ", " "; // Bind the data arrays to the parameters in the prepared SQL // statement ret = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_LONG, SQL_INTEGER, 0, 0, (SQLPOINTER)custIDs, sizeof(sqlinteger), NULL); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); else printf("bound CustIDs array to prepared statement\n"); // Bind CustNames SQLBindParameter(hdlStmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0, (SQLPOINTER)custNames, 50, NULL); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); else printf("bound CustNames array to prepared statement\n"); // Bind phonenums SQLBindParameter(hdlStmt, 3, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 15, 0, (SQLPOINTER)phoneNums, 15, NULL); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); else printf("bound phonenums array to prepared statement\n"); // Set up a variable to recieve number of parameters processed. SQLULEN rowsprocessed; // Set a statement attribute to point to the variable SQLSetStmtAttr(hdlStmt, SQL_ATTR_PARAMS_PROCESSED_PTR, &rowsprocessed, 0); // Set up an array to hold the result of each row insert SQLUSMALLINT rowresults[ NUM_ENTRIES ]; // Set a statement attribute to point to the array SQLSetStmtAttr(hdlStmt, SQL_ATTR_PARAM_STATUS_PTR, rowresults, 0); // Tell the ODBC driver how many rows we have in the // array. SQLSetStmtAttr(hdlStmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER)NUM_ENTRIES, 0); // Add multiple batches to the database. This just adds the same // batch of data over and over again for simplicity's sake. for (int batchloop=1; batchloop<=5; batchloop++) // Execute the prepared statement, loading all of the data // in the arrays. printf("adding Batch #%d...", batchloop); HP Vertica Analytic Database (7.1.x) Page 167 of 401

168 Client Libraries ret = SQLExecute(hdlStmt); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); exit(exit_failure); // Number of rows processed is in rowsprocessed printf("params processed: %d\n", rowsprocessed); printf("results of inserting each row:\n"); int i; for (i = 0; i<num_entries; i++) SQLUSMALLINT result = rowresults[i]; switch(rowresults[i]) case SQL_PARAM_SUCCESS: case SQL_PARAM_SUCCESS_WITH_INFO: printf(" Row %d inserted successsfully\n", i+1); break; case SQL_PARAM_ERROR: printf(" Row %d was not inserted due to an error.", i+1); break; default: printf(" Row %d had some issue with it: %d\n", i+1, result); // Done with batches, commit the transaction printf("commit Transaction\n"); ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); if(!sql_succeeded(ret)) reporterror<sqlhdbc>( SQL_HANDLE_STMT, hdlstmt ); // Clean up printf("free handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); Running the example code produces the following output: Allocated an environment handle.set application to ODBC 3. Allocated Database handle. Connecting to database. Connected to database. Creating table. Created table. Creating prepared statement Created prepared statement. Bound CustIDs array to prepared statement HP Vertica Analytic Database (7.1.x) Page 168 of 401

169 Client Libraries Bound CustNames array to prepared statement Bound phonenums array to prepared statement Adding Batch #1...Params processed: 4 Results of inserting each row: Row 1 inserted successfully Row 2 inserted successfully Row 3 inserted successfully Row 4 inserted successfully Adding Batch #2...Params processed: 4 Results of inserting each row: Row 1 inserted successfully Row 2 inserted successfully Row 3 inserted successfully Row 4 inserted successfully Adding Batch #3...Params processed: 4 Results of inserting each row: Row 1 inserted successfully Row 2 inserted successfully Row 3 inserted successfully Row 4 inserted successfully Adding Batch #4...Params processed: 4 Results of inserting each row: Row 1 inserted successfully Row 2 inserted successfully Row 3 inserted successfully Row 4 inserted successfully Adding Batch #5...Params processed: 4 Results of inserting each row: Row 1 inserted successfully Row 2 inserted successfully Row 3 inserted successfully Row 4 inserted successfully Commit Transaction Free handles. Error Handling During Batch Loads When loading individual batches, you can find information on how many rows were accepted and what rows were rejected (see Tracking Load Status (ODBC) for details). Other errors, such as disk space errors, do not occur while inserting individual batches. This behavior is caused by having a single COPY statement perform the loading of multiple consecutive batches. Using the single COPY statement makes the batch load process perform much faster. It is only when the COPY statement closes that the batched data is committed and HP Vertica reports other types of errors. Your bulk loading application should check for errors when the COPY statement closes. Normally, you force the COPY statement to close by calling the SQLEndTran() function to end the transaction. You can also force the COPY statement to close by closing the cursor using the SQLCloseCursor() function, or by setting the database connection's AutoCommit property to true before inserting the last batch in the load. Note: The COPY statement also closes if you execute any non-insert statement. However having to deal with errors from the COPY statement in what might be an otherwise-unrelated HP Vertica Analytic Database (7.1.x) Page 169 of 401

170 Client Libraries query is not intuitive, and can lead to confusion and a harder to maintain application. You should explicitly end the COPY statement at the end of your batch load and handle any errors at that time. Loading Batches in Parallel To load batches in parallel, you need to establish a thread for each parallel batch you want to load. Then for each thread, set the batch size, prepare the insert, and execute the batch insert. The following code samples illustrate this. #define THREAD_COUNT 10#define ROWS_PER_THREAD #define BATCH_SIZE void *BatchInsert(void *arg) SQLRETURN rc = SQL_SUCCESS; int i, j; SQLINTEGER *intvalarray = NULL; SQLINTEGER lrows=batch_size; // connect to db, allocate statement, set auto-commit off skipped intvalarray = (SQLINTEGER*) malloc(sizeof(*intvalarray) * BATCH_SIZE); rc = SQLSetStmtAttr( hstmt, SQL_ATTR_PARAMSET_SIZE, (SQLPOINTER)lRows, 0 ); // prepare insert rc = SQLPrepare (hstmt, (SQLTCHAR*)"insert into mt_test values(?)", SQL_NTS) ; rc = SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER, 0, 0, (SQLPOINTER)intValArray, sizeof(*intvalarray), NULL); for (i = 0; i < ROWS_PER_THREAD; i) for (j = 0; j < BATCH_SIZE; j++) intvalarray[j] = (SQLINTEGER) ++i; rc = SQLExecute(hStmt); rc = SQLEndTran (SQL_HANDLE_DBC, hdbc, SQL_COMMIT); int runmt(int argc, char **argv) pthread_t t[thread_count]; void *trc; for (int i=0;i<thread_count;++i) pthread_create(&t[i], NULL, BatchInsert, argv[0]); for (int i=0;i<thread_count;++i) pthread_join(t[i], &trc); free(trc); return 0; Using the COPY Statement The COPY statement lets you bulk load data from a file on stored on a database node into the HP Vertica database. This method is the most efficient way to load data into HP Vertica because the file resides on the database server. One drawback is that only a database superuser can use COPY, since it requires privilege in order to access the filesystem of the database node. HP Vertica Analytic Database (7.1.x) Page 170 of 401

171 Client Libraries One drawback of using COPY instead of performing batch loads is that you can only get results of the load (the number of accepted and rejected rows) when the COPY statement has finished. With batch loads, you can monitor the progress as batches are inserted. The ability to monitor the progress of a load can be a useful feature if you want to stop loading if a large portion of the data is being rejected. A primary concern when bulk loading data using COPY is deciding whether the data should be loaded directly into ROS using the DIRECT option, or by using the AUTO method (loading into WOS until it fills, then loading into ROS). You should load directly into the ROS when your transaction will load a large (more than 100MB of data or so) amount of data. Note: The exceptions/rejections files are created on the client machine when the exceptions and rejected data modifiers are specified on the COPY command. Specify a local path and filename for these modifiers when executing a COPY query from the driver. The following example loads data into the WOS (Write Optimized Store) until it fills, then stores additional data directly in ROS (Read Optimized Store). ret=sqlexecdirect(hdlstmt, (SQLCHAR*)"COPY customers " "FROM '/data/customers.txt' AUTO",SQL_NTS); The following example loads data into the ROS (Read Optimized Store. ret=sqlexecdirect(hdlstmt, (SQLCHAR*)"COPY customers " "FROM '/data/customers.txt' DIRECT",SQL_NTS); See the COPY statement in the SQL Reference Manual for more information about its syntax and use. The following example demonstrates using the COPY command. // Some standard headers #include <stdio.h> #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> // Helper function to determine if an ODBC function call returned // successfully. bool notsuccess(sqlreturn ret) return (ret!= SQL_SUCCESS && ret!= SQL_SUCCESS_WITH_INFO); int main() // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(notsuccess(ret)) HP Vertica Analytic Database (7.1.x) Page 171 of 401

172 Client Libraries printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Tell ODBC that the application uses ODBC 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(notsuccess(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; // Note: User MUST be a database superuser to be able to access files on the // filesystem of the node. const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(notsuccess(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Disable AUTOCOMMIT printf("disabling autocommit.\n"); ret = SQLSetConnectAttr(hdlDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_OFF, SQL_NTS); if(notsuccess(ret)) printf("could not disable autocommit.\n"); exit(exit_failure); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); // Create table to hold the data SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers" "(Last_Name char(50) NOT NULL, First_Name char(50), char(50), " "Phone_Number char(15));", SQL_NTS); // Run the copy command to load data into ROS. ret=sqlexecdirect(hdlstmt, (SQLCHAR*)"COPY customers " "FROM '/data/customers.txt' DIRECT", HP Vertica Analytic Database (7.1.x) Page 172 of 401

173 Client Libraries SQL_NTS); if(notsuccess(ret)) printf("data was not successfully loaded.\n"); exit(exit_failure); else // Get number of rows added. SQLLEN numrows; ret=sqlrowcount(hdlstmt, &numrows); printf("successfully inserted %d rows.\n", numrows); // Done with batches, commit the transaction printf("committing transaction\n"); ret = SQLEndTran(SQL_HANDLE_DBC, hdldbc, SQL_COMMIT); if(notsuccess(ret)) printf("could not commit transaction\n"); else printf("committed transaction\n"); // Clean up printf("free handles.\n"); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); The example prints the following when run: Allocated an environment handle. Set application to ODBC 3. Connecting to database. Connected to database. Disabling autocommit. Successfully inserted rows. Committing transaction Committed transaction Free handles. Streaming Data From the Client Using COPY LOCAL The LOCAL option of the SQL COPY statement lets you stream data from a file on a client system to your HP Vertica database. This statement works through the ODBC driver, making the task of transferring data files from the client to the server much easier. The LOCAL option of COPY works transparently through the ODBC driver. Just have your client application execute a statement containing a COPY LOCAL statement, and the ODBC driver will read and stream the data file from the client to the server. For example: // Some standard headers #include <stdio.h> HP Vertica Analytic Database (7.1.x) Page 173 of 401

174 Client Libraries #include <stdlib.h> // Only needed for Windows clients // #include <windows.h> // Standard ODBC headers #include <sql.h> #include <sqltypes.h> #include <sqlext.h> int main() // Set up the ODBC environment SQLRETURN ret; SQLHENV hdlenv; ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hdlenv); if(!sql_succeeded(ret)) printf("could not allocate a handle.\n"); exit(exit_failure); else printf("allocated an environment handle.\n"); // Tell ODBC that the application uses ODBC 3. ret = SQLSetEnvAttr(hdlEnv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_UINTEGER); if(!sql_succeeded(ret)) printf("could not set application version to ODBC3.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Allocate a database handle. SQLHDBC hdldbc; ret = SQLAllocHandle(SQL_HANDLE_DBC, hdlenv, &hdldbc); if(!sql_succeeded(ret)) printf("could not aalocate a database handle.\n"); exit(exit_failure); else printf("set application to ODBC 3.\n"); // Connect to the database printf("connecting to database.\n"); const char *dsnname = "ExampleDB"; const char* userid = "dbadmin"; const char* passwd = "password123"; ret = SQLConnect(hdlDbc, (SQLCHAR*)dsnName, SQL_NTS,(SQLCHAR*)userID,SQL_NTS, (SQLCHAR*)passwd, SQL_NTS); if(!sql_succeeded(ret)) printf("could not connect to database.\n"); exit(exit_failure); else printf("connected to database.\n"); // Set up a statement handle SQLHSTMT hdlstmt; SQLAllocHandle(SQL_HANDLE_STMT, hdldbc, &hdlstmt); // Create table to hold the data HP Vertica Analytic Database (7.1.x) Page 174 of 401

175 Client Libraries SQLExecDirect(hdlStmt, (SQLCHAR*)"DROP TABLE IF EXISTS customers", SQL_NTS); SQLExecDirect(hdlStmt, (SQLCHAR*)"CREATE TABLE customers" "(Last_Name char(50) NOT NULL, First_Name char(50), char(50), " "Phone_Number char(15));", SQL_NTS); // Run the copy command to load data into ROS. ret=sqlexecdirect(hdlstmt, (SQLCHAR*)"COPY customers " "FROM LOCAL '/home/dbadmin/customers.txt' DIRECT", SQL_NTS); if(!sql_succeeded(ret)) printf("data was not successfully loaded.\n"); exit(exit_failure); else // Get number of rows added. SQLLEN numrows; ret=sqlrowcount(hdlstmt, &numrows); printf("successfully inserted %d rows.\n", numrows); // COPY commits automatically, unless it is told not to, so // there is no need to commit the transaction. // Clean up printf("free handles.\n"); ret = SQLDisconnect( hdldbc ); if(!sql_succeeded(ret)) printf("error disconnecting. Transaction still open?\n"); exit(exit_failure); SQLFreeHandle(SQL_HANDLE_STMT, hdlstmt); SQLFreeHandle(SQL_HANDLE_DBC, hdldbc); SQLFreeHandle(SQL_HANDLE_ENV, hdlenv); exit(exit_success); This example is essentially the same as the example shown in Using the COPY Statement, except it uses the COPY statement's LOCAL option to load data from the client system rather than from the filesystem of the database node. Note: On Windows clients, the path you supply for the COPY LOCAL file is limited to 216 characters due to limitations in the Windows API. See Also COPY LOCAL HP Vertica Analytic Database (7.1.x) Page 175 of 401

176 Client Libraries Using LONG VARCHAR and LONG VARBINARY Data Types with ODBC The ODBC drivers support the LONG VARCHAR and LONG VARBINARY data types similarly to VARCHAR and VARBINARY data types. When binding input or output parameters to a LONG VARCHAR or LONG VARBINARY column in a query, use the SQL_LONGVARCHAR and SQL_ LONGVARBINARY constants to set the column's data type. For example, to bind an input parameter to a LONG VARCHAR column, you would use a statement that looks like this: rc = SQLBindParameter(hdlStmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_LONGVARCHAR, 80000, 0, (SQLPOINTER)myLongString, sizeof(mylongstring), NULL); Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG VARCHAR values. HP Vertica cannot load encoded values larger than 32MB, even if the decoded value is less than 32 MB in size. For example, HP Vertica returns an error if you attempt to load a 32MB LONG VARBINARY value encoded in octal format, since the octal encoding quadruples the size of the value (each byte is converted into a backslash followed by three digits). HP Vertica Analytic Database (7.1.x) Page 176 of 401

177 Programming JDBC Client Applications The HP Vertica JDBC driver provides you with a standard JDBC API. If you have accessed other databases using JDBC, you should find accessing HP Vertica familiar. This section explains how to use the JDBC to connect your Java application to HP Vertica. You must first install the JDBC client driver on all client systems that will be accessing the HP Vertica database. For installation instructions, see Installing the HP Vertica Client Drivers. For more information about JDBC: Vertica Analytic Database JDBC Driver JavaDoc (HP Vertica extensions) An Introduction to JDBC, Part 1 JDBC Feature Support The HP Vertica JDBC driver complies with the JDBC 4.0 standards (although it does not implement all of the optional features in them). Your application can use the DatabaseMetaData class to determine if the driver supports a particular feature it wants to use. In addition, the driver implements the Wrapper interface, which lets your client code discover HP Vertica-specific extensions to the JDBC standard classes, such as VerticaConnection and VerticaStatement classes. Some important facts to keep in mind when using the HP Vertica JDBC driver: Cursors are forward only and are not scrollable. Result sets cannot be updated. A connection supports executing a single statement at any time. If you want to execute multiple statements simultaneously, you must open multiple connections. Because HP Vertica does not have stored procedures, CallableStatement is not supported. The DatabaseMetaData.getProcedures() and.getprocedurecolumns() methods return information about SQL functions (including User Defined Functions) instead of stored procedures. Multiple SQL Statement Support The HP Vertica JDBC driver can execute strings containing multiple statements. For example: stmt.executeupdate("create TABLE t(a INT);INSERT INTO t VALUES(10);"); Only the Statement interface supports executing strings containing multiple SQL statements. You cannot use multiple statement strings with PreparedStatement. COPY statements that copy a file from a host file system work in a multiple statement string. However, client COPY statements (COPY FROM STDIN) do not work. HP Vertica Analytic Database (7.1.x) Page 177 of 401

178 Multiple Batch Conversion to COPY Statements The HP Vertica JDBC driver converts all batch inserts into HP Vertica COPY statements. If you turn off your JDBC connection's AutoCommit property, the JDBC driver uses a single COPY statement to load data from sequential batch inserts which can improve load performance by reducing overhead. See Batch Inserts Using JDBC Prepared Statements for details. Multiple JDBC Version Support The HP Vertica JDBC driver implements both JDBC 3.0 and JDBC 4.0 compliant interfaces. The interface that the driver returns to your application depends on the JVM version on which it is running. If your application is running on a 5.0 JVM, the driver supplies your application with JDBC 3.0 classes. If your application is running on a 6.0 or later JVM, the driver supplies it with JDBC 4.0 classes. Updating Application Code From Previous Driver Versions If you have a client application that was written using a previous version of the HP Vertica JDBC driver, you may need to alter its code to work with newer driver versions, or you may want to change your application to take advantage of new driver features. The topics in this section explain the changes that have been made to the JDBC driver from previous driver versions. HP Vertica Analytic Database (7.1.x) Page 178 of 401

179 Updating Client Code From 4.1 or Earlier JDBC Driver Versions The HP Vertica version 5.1 client drivers were rewritten to improve standards compliance and reliability. As a result, some HP Vertica-specific features and past incompatibilities were eliminated. If you client code worked with a pre-5.1 version of the HP Vertica JDBC driver, you must update it to work with the new driver versions. The following topics explain these updates. Driver Package and Interface Name Changes The name of the HP Vertica client driver package has changed. Previously, the HP Vertica JDBC driver classes were located in com.vertica. They are now in com.vertica.jdbc. Loading the 4.1 Driver Class.forName("com.vertica.Driver"); Loading the 5.1 Driver Class.forName("com.vertica.jdbc.Driver"); Note: The HP Vertica version 7.0 JDBC driver introduces JDBC 4.0 compatibility which includes the JNDI service registration that eliminates the need to manually load the JDBC driver. See New Features in the Version JDBC Driver for details. Interface Name Changes The following table lists the interfaces in the HP Vertica JDBC client library whose names have changed. 4.1 Interface Name 5.1 Interface Name PGConnection PGStatement VerticaConnection VerticaStatement Normally, you reference these interfaces only when casting a Connection or Statement object to access HP Vertica-specific methods or properties. Many of the HP Vertica-specific methods and properties have been removed from the version 5.1 client drivers in favor of JDBC-standard methods and properties. You should not need to cast to these interfaces as often when using the new client drivers. See Converting From PGConnection to VerticaConnection and Converting From PGStatement to VerticaStatement for more information. Removed Classes The HP Vertica version 5.1 JDBC driver has removed several legacy classes. Previously, many HP Vertica-specific methods would throw a PSQLException when encountering an error. This class has been removed. Instead, all methods now throw a standard SQLException. HP Vertica Analytic Database (7.1.x) Page 179 of 401

180 Note: Note: The HP Vertica version 7.0 JDBC driver introduces a set of SQLException subclasses that more specifically describe error situations. See New Features in the Version JDBC Driver for more information. The PGInterval class has been replaced with a pair of HP Vertica interval classes: VerticaDayTimeInterval (which represents all ten types of day/time intervals) and VerticaYearMonthInterval (which represents all three types of year/month intervals). See Using Intervals with JDBC for details. The PGMoney class has been removed from the driver. Converting From PGConnection to VerticaConnection The VerticaConnection interface replaces the PGConnection interface in the version 5.1 JDBC driver. The PGConnection interface contained HP Vertica-specific extensions to the standard JDBC Connection interface. VerticaConnection does not implement some of PGConnection's methods to make it more compliant with the JDBC standards. Property Setters and Getters The PGConnection interface had several specific setters and getters for some connection properties. These have been removed from VerticaConnection and replaced with properties, as described in the following table: 4.1 Methods 5.1 Property Name Description getbatchdirectinsert()setbatchdirectinsert() DirectBatchInsert Controls whether data is inserted directly into ROS, or into WOS. getmaxlrsmemory()setmaxlrsmemory() ResultBufferSize Controls the size of the memory buffer the client uses when retrieving a result set stream. Instead of these non-standard methods, use the VerticaConnection.getProperty() and VerticaConnection.setProperty() methods to access these properties, or set them when creating the database connection. See Connection Properties and Setting and Getting Connection Property Values for more information. Deprecated Methods The following methods of the PGConnection class were deprecated in the version 4.1 drivers, and are not implemented by VerticaConnection: HP Vertica Analytic Database (7.1.x) Page 180 of 401

181 Removed Methods Reason getbatchinsertenforcelength()setbatchinsertenforcelength() In the HP Vertica version 5.1 drivers, batch inserts always enforce column-width limitations. This makes batch inserts consistent with non-batch inserts, which always enforce width limitations. If you do not want to batch load errors to occur due to data being too wide for the column, you can either: Truncate the data to the column's width before attempting to insert it Use the VerticaCopyStream class to execute a COPY FROM STDIN statement, without an ENFORCELENGTH parameter. getbinarybatchinsert()setbinarybatchinsert() getlocale()setlocale() getstreaminglrs()setstreaminglrs() The new JDBC driver now uses a single batch insert protocol rather than having separate binary and text modes to insert data. These methods are not implemented by VerticaConnection. Instead, you set the connection's locale using the SET LOCALE SQL statement. See Setting the Locale for JDBC Sessions for details. The new JDBC driver always uses streaming result sets rather than optionally caching the results on the client. HP Vertica Analytic Database (7.1.x) Page 181 of 401

182 Removed Methods getencoding()setencoding() getfastpathapi() getlargeobjectapi() getmanagedbatchinsert() setmanagedbatchinsert() getobject() getpgtype() getpreparethreshold() setpreparethreshold() getsqltype() getuse35copyformat() setuse35copyformat() getuse35copyparameters() setuser35copyparameters() adddatatype() Reason All of these methods were previously deprecated and have been removed from the version 5.1 JDBC driver. Savepoint Support The version 5.1 JDBC driver implements the Savepoint interface, allowing you to use savepoints to segment your transactions and later roll back a portion of the transaction. Updatable Result Set Changes The createstatement() method in the 4.1 and earlier JDBC drivers accepted the ResultSet.CONCUR_UPDATABLE flag to create an updatable result set. However, the driver's support of this feature was limited. The 5.1 JDBC driver does not support updatable result sets. The createstatement() method now accepts just ResultSet.TYPE_FORWARD_ONLY and ResultSet.CONCUR_READ_ONLY flags. It throws an exception if you pass it other flags. Converting From PGStatement to VerticaStatement The VerticaStatement interface contains the HP Vertica-specific extensions of the standard JDBC Statement interface. In previous versions of the HP Vertica JDBC driver, this interface was named PGStatement. In addition to the name change, a some methods have been removed from this interface. Deprecated Methods VerticaStatement does not implement the following PGStatement methods because they are obsolete: executecopyin() executecopyout() finishload() getlastoid() HP Vertica Analytic Database (7.1.x) Page 182 of 401

183 Bulk Loading Method Changes VerticaStatement does not implement the following PGStatement bulk loading methods: addstreamtocopyin() startcopyin() finishcopyin() Instead, the new VerticaCopyStream class implements a stream copying feature. See Streaming Data Via JDBC. Connection Property Setters and Getters In previous versions of the drivers, many of the connection property setters and getters on the PGConnection interface were also implemented in the PGStatement interface. These methods allowed you to change some of the connection parameters for the statement, letting you override their settings on the PGConnection object used to create the statement. VerticaStatement does not implement these setters and getters helping to prevent potential confusion and difficult-to-debug issues caused by having different statements on the same connection having their own connection properties. VerticaStatement objects cache two properties independently: DirectBatchInsert and ResultBufferSize. Once a VerticaStatement object is instantiated, it stores the values of these properties that were set on the VerticaConnection object you used to create them. The object retains these values even if you later change the property on the VerticaConnection object. For example, in the following code: // Set the DirectBatchInsert property ((VerticaConnection) conn).setproperty("directbatchinsert", true ); // Create a statement object Statement stmta = conn.createstatement(); // Change the direct batch insert setting and create another // statement. ((VerticaConnection) conn).setproperty("directbatchinsert", false ); Statement stmtb = conn.createstatement(); The stmta object has its DirectBatchInsert property set to true, since that was the property's value on the VerticaConnection used to instantiate it. Since this property is specific to the statement, stmta's DirectBatchInsert property remains unchanged when the connection's DirectBatchInsert property changes to false later. Note: The VerticaStatement interface does not cache any of the other connection properties. If you change another property (such as Locale) on a VerticaConnection object, the change affects all of the VerticaStatement objects instantiated using that connection object. HP Vertica Analytic Database (7.1.x) Page 183 of 401

184 Multiple Statement Support The previous JDBC driver's implementation of the Statement interface did not support executing SQL strings containing multiple statements. The new driver's implementation does support multiple statements. For example: stmt.executeupdate("create TABLE t(a INT);INSERT INTO t VALUES(10);"); Only the Statement interface supports executing strings containing multiple SQL statements. You cannot use multiple statement strings with PreparedStatement. COPY statements that copy a file from a host file system work in a multiple statement string. However, client COPY statements (COPY FROM STDIN) do not work. Connection Property Changes JDBC connection properties let you control the behavior of your application's connection to the database. The HP Vertica version 5.1 JDBC driver has removed some old properties, renamed several others, and added some new properties. New Connection Properties The following properties have been added to the HP Vertica version 5.1 JDBC driver. Property ConnSettings LogLevel LogNameSpace LogPath TransactionIsolation ThreePartNaming Description Contains SQL commands to be executed when the database connection is established. Sets the types of messages that the client writes to a log file. Limits the messages written to the log to only those generated by classes in the given namespace. Sets the path where the log file is written. Previously could only be accessed using a getter and setter method on the PGConnection object. It can now be set using the same methods as other connection properties. Controls whether the database metadata uses the database name as the catalog name. This property is only used for backwards compatibility with some client software. See Connection Properties for more information about these new properties. HP Vertica Analytic Database (7.1.x) Page 184 of 401

185 Renamed Properties Several properties have been renamed to make connection properties more consistent across the different client libraries: 4.1 Property Name 5.1 Name Description defaultautocommit Autocommit Sets whether statements automatically commit themselves. SessionLabel Label Identifies the connection on the server. maxlrsmemory ResultBufferSize Sets the buffer size the driver uses when retrieving a result set from the server. In addition, the default value has been changed from 8MB to 8KB. Removed Connection Properties The following table lists the connection properties have been removed from the HP Vertica version 5.1 JDBC driver: Parameter batchinsertenforcelength batchinsertrecordterminator binarybatchinsert BinaryDataTransfer KeepAlive Locale Description Controlled whether inserting data that is too wide for its column would cause an error. Removed to make batch inserts consistent with other types of data inserts. Attempting to insert data that is too wide for a column always results in an error. Set the record terminator for a batch insert. This property was deprecated and was only available for backwards compatibility. Controlled whether batched data inserts were transmitted as binary data or converted to string. Removed because the driver now uses NATIVE VARCHAR transfer for all data types. Controlled whether data was transmitted between the server and the client in binary format. Removed because the driver now uses NATIVE VARCHAR to transfer data Caused the network connection to send keepalive packets to ensure the connection remained open during idle periods. The new JDBC driver always sends keepalive packets. Set the locale for the connection. Instead of a property, use a query to set the locale. You can include a SQL statement in the ConnSettings property to set the locale as soon as the JDBC driver connects to the database. See Setting the Locale for JDBC Sessions. HP Vertica Analytic Database (7.1.x) Page 185 of 401

186 Parameter preparethreshold streaminglrs Description Controlled how many times a statement would be executed before the server would automatically convert it to a server-side prepared statement. Removed since this functionality was deprecated. Controlled whether results were streamed to the client as it requested data, or if all data in a result set was sent to the client, which cached it in a local file. Removed since the new driver always uses streaming mode. New Features in the Version JDBC Driver The HP Vertica Version 7.0 JDBC driver introduces JDBC 4.0 compatibility. This driver is completely backwards compatible with the earlier driver versions, so you do not need to change the code of your Java client application or even recompile it. You may wish to update you client application to take advantage of some of the features offered by the new driver, which are explained below. JNDI Service Registration In prior versions of the HP Vertica JDBC driver, your client application needed to load the JDBC driver by calling Class.forName("com.vertica.jdbc.Driver") before using it. The new driver implements JNDI service registration, so the JVM automatically finds and loads the JDBC driver when your application tries to use it. Therefore, your application no longer needs to call Class.forName before using the JDBC driver. There is no harm in having you application still call Class.forName so you do not need to remove this call if it is already there. Note: If you want your application to remain compatible with the JDBC 3.0 driver so it can run in a Java 5 JVM, you should still have it call Class.forName to load the driver. You can remove the call if your application will only be run on Java 6 or later JVMs which use the JDBC 4.0 driver. Exception Class Improvements In the JDBC 3.0 standard, most errors were signaled by throwing a single exception class (SQLException). This single class makes it difficult for a client application to analyze errors. JDBC 4.0 introduces a hierarchy of subclasses of SQLException which provide more specific information to your application about the type of error that has occurred. With these new classes, your client application can better respond to errors, potentially resolving them itself. For example, exception subclasses that inherit from the SQLTransientException subclass of SQLException (such as SQLTransientConnectionException) are thrown by the driver when it encounters an error that may be caused by a temporary condition (such as a timeout or a network issue that might resolve itself). Your client application could catch this exception and automatically retry the operation instead of immediately reporting a failure to the user. HP Vertica Analytic Database (7.1.x) Page 186 of 401

187 The SQLException class and its subclasses now make iterating over multiple exceptions easier by implementing the Iterator interface. See Handling Errors for details about using these new SQLException subclasses. Wrapper Interface Support The JDBC 4.0 standard introduces the Wrapper interface, which lets client applications discover vendor-specific extensions to the JDBC standards. Your client application can use this interface to find Vertica-specific extensions to standard JDBC classes such as VerticaConnection (an extension to the standard Connection class) and VerticaPreparedStatement (an extension to the PreparedStatement class) which implement the Wrapper interface. Additional DatabaseMetaData Methods Past versions of the JDBC standard contained the DatabaseMetaData interface which let client applications determine which features the JDBC driver and database implemented. JDBC 4.0 extends this interface with new methods that the HP Vertica JDBC driver implements. Among these new methods are getfunctions() and getfunctioncolumns() which let your client application find which User Defined Functions (UDFs) are defined in the HP Vertica catalog, and determine their input and output values. See Developing and Using User Defined Functions for more information about UDFs. Improved Connection Pooling The HP Vertica Version 7.0 JDBC driver implements the improvements in connection pooling defined in the JDBC 4.0 standard. These improvements include: new methods to determine if a connection is still valid. new methods to report information about the client back to the server. new callback methods to alert client applications to the expiration of a connection or statement. Normally, your client application will not use this API directly. Instead, you use an application framework that handles connection pooling for you. See Using a Pooling Data Source for more information. Native Connection Load Balancing Support The HP Vertica Version 7.0 server, client libraries, and vsql client support native connection load balancing, which helps spread the resources used by client connections across all of the hosts in the database. See "About Native Connection Load Balancing" on page 1 in the Administrator's Guide for details. To support this feature, the JDBC driver has a new connection parameter named ConnectionLoadBalance to enable load balancing on the client side of the connection. See Enabling Native Connection Load Balancing in JDBC for more information. HP Vertica Analytic Database (7.1.x) Page 187 of 401

188 Connection Failover Support The JDBC driver now supports two forms of connection failover: DNS based and parameter based. This feature lets the JDBC driver automaitcally attempt to one or more backup hosts if ithe primary host does not respond to its connection request. See JDBC Connection Failover for more information. HP Vertica Analytic Database (7.1.x) Page 188 of 401

189 Creating and Configuring a Connection Before your Java application can interact with HP Vertica, it must create a connection. Connecting to HP Vertica using JDBC is similar to connecting to most other databases. Importing SQL Packages Before creating a connection, you must import the Java SQL packages. A simple way to do so is to import the entire package using a wildcard: import java.sql.*; You may also want to import the Properties class. You can use an instance of this class to pass connection properties when instantiating a connection, rather than encoding everything within the connection string: import java.util.properties; If your application needs to run in a Java 5 JVM, it uses the older JDBC 3.0-compliant driver. This driver requires that you to manually load the HP Vertica JDBC driver using the Class.forName() method: // Only required for old JDBC 3.0 driver try Class.forName("com.vertica.jdbc.Driver"); catch (ClassNotFoundException e) // Could not find the driver class. Likely an issue // with finding the.jar file. System.err.println("Could not find the JDBC driver class."); e.printstacktrace(); return; // Exit. Cannot do anything further. Your application may run in a Java 6 or later JVM. If so, then the JVM automatically loads the HP Vertica JDBC 4.0-compatible driver without requiring the call to Class.forName. However, making this call does not adversely affect the process.thus, if you want your application to be compatible with both Java 5 and Java 6 (or later) JVMs, it can still call Class.forName. Opening the Connection With SQL packages imported, you are ready to create your connection by calling the DriverManager.getConnection() method. You supply this method with at least the following information: The IP address or host name of a node in the database cluster: You can provide an IPv4 address, IPv6 address, or hostname. HP Vertica Analytic Database (7.1.x) Page 189 of 401

190 In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6. Port number for the database Name of the database Username of a database user account Password of the user (if the user has a password) The first three parameters are always supplied as part of the connection string, a URL that tells the JDBC driver where to find the database. The format of the connection string is: "jdbc:vertica://verticahost:portnumber/databasename" The first portion of the connection string selects the HP Vertica JDBC driver, followed by the location of the database. You can provide the last two parameters, username and password, to thejdbc driver, in one of three ways: As part of the connection string. The parameters are encoded similarly to URL parameters: "jdbc:vertica://verticahost:portnumber/databasename?user=username&password=password" As separate parameters to DriverManager.getConnection(): Connection conn = DriverManager.getConnection( "jdbc:vertica://verticahost:portnumber/databasename", "username", "password"); In a Properties object: Properties myprop = new Properties(); myprop.put("user", "username"); myprop.put("password", "password"); Connection conn = DriverManager.getConnection( "jdbc:vertica://verticahost:portnumber/databasename", myprop); Of these three methods, the Properties object is the most flexible because it makes passing additional connection properties to the getconnection() method easy. See Connection Properties and Setting and Getting Connection Property Values for more information about the additional connection properties. If there is any problem establishing a connection to the database, the getconnection() method throws a SQLException on one of its subclasses.. To prevent an exception, enclose the method within a try-catch block, as shown in the following complete example of establishing a connection. HP Vertica Analytic Database (7.1.x) Page 190 of 401

191 import java.sql.*; import java.util.properties; public class VerySimpleVerticaJDBCExample public static void main(string[] args) /* * If your client needs to run under a Java 5 JVM, It will use the older * JDBC 3.0-compliant driver, which requires you manually load the * driver using Class.forname */ /* * try Class.forName("com.vertica.jdbc.Driver"); catch * (ClassNotFoundException e) // Could not find the driver class. * Likely an issue // with finding the.jar file. * System.err.println("Could not find the JDBC driver class."); * e.printstacktrace(); return; // Bail out. We cannot do anything * further. */ Properties myprop = new Properties(); myprop.put("user", "dbadmin"); myprop.put("password", "vertica"); myprop.put("logintimeout", "35"); myprop.put("binarybatchinsert", "true"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://docd04.verticacorp.com:5433/vmart", myprop); System.out.println("Connected!"); conn.close(); catch (SQLTransientConnectionException connexception) // There was a potentially temporary network error // Could automatically retry a number of times here, but // instead just report error and exit. System.out.print("Network connection issue: "); System.out.print(connException.getMessage()); System.out.println(" Try again later!"); return; catch (SQLInvalidAuthorizationSpecException authexception) // Either the username or password was wrong System.out.print("Could not log into database: "); System.out.print(authException.getMessage()); System.out.println(" Check the login credentials and try again."); return; catch (SQLException e) // Catch-all for other exceptions e.printstacktrace(); Usage Considerations When you disconnect a user session, any uncommitted transactions are automatically rolled back. If your database is not compliant with your HP Vertica license terms, HP Vertica issues a SQLWarning when you establish the connection to the database. You can retrieve this warning HP Vertica Analytic Database (7.1.x) Page 191 of 401

192 using the Connection.getWarnings() method. See Managing Your License Key in the Administrator's Guide for more information about complying with your license terms. JDBC Connection Properties You use connection properties to configure the connection between your JDBC client application and your HP Vertica database. The properties provide the basic information about the connections, such as the server name and port number to use to connect to your database. They also let you tune the performance of your connection and enable logging. You can set a connection property in any of three ways: Include the property name and value as part of the connection string you pass to the DriverManager.getConnection() method. Set the properties in a Properties object, and then pass it to the DriverManager.getConnection()method. Use the VerticaConnection.setProperty() method. With this approach, you can change only those connection properties that remain changeable after the connection has been established. In addition, some of the standard JDBC connection properties have getters and setters on the Connection interface (such as Connection.setAutocommit()). The following tables list the properties supported by the HP Vertica JDBC driver, and explain which are required in order for the connection to be established. Connection Properties The properties in the following table can only be set before you open the connection to the database. Two of them are required for every connection. Property ConnSettings Description A string containing SQL statements that the JDBC driver automatically runs after it connects to the database. You can use this property to set the locale or schema search path, or perform other configuration that the connection requires. Required?: No Default Value: none HP Vertica Analytic Database (7.1.x) Page 192 of 401

193 Property Label Description Sets a label for the connection on the server. This value appears in the client_label column of the V_MONITOR.SESSIONS system table. Required?: No Default Value: jdbc-driver_version-random_number LoginTimeout The number of seconds HP Vertica waits for a connection to be established to the database before throwing a SQLException. Required?: No Default Value: 0 (no TCP timeout) SSL When set to true, use SSL to encrypt the connection to the server. HP Vertica must be configured to handle SSL connections before you can establish an SSL-encrypted connection to it. See Implementing SSL in the Administrator's Guide. Required?: No Default Value: false Password The password to use to log into the database. Required?: Yes Default Value: none User The database user name to use to connect to the database. Required?: Yes Default Value: none ConnectionLoadBalance A Boolean value indicating whether the client is willing to have its connection redirected to another host in the HP Vertica database. This setting has an effect only if the server has also enabled connection load balancing. See About Native Connection Load Balancing in the Administrator's Guide for more information about native connection load balancing. Required?: No Default Value: false HP Vertica Analytic Database (7.1.x) Page 193 of 401

194 Property BackupServerNode Description A string containing the host name or IP address of one or more hosts in the database. If the connection to the host specified in the connection string times out, the client attempts to connect to any host named in this string.the host name or IP address can also include a colon followed by the port number for the database. If no port number is specified, the client uses the standard port number (5433). Separate multiple host name or IP address entries with commas. Required?: No Default Value: none PreferredAddressFamily The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name. Valid values are: ipv4 Connect to the server using IPv4. ipv6 Connect to the server using IPv6. none Use the IP address provided by the DNS server. Required?: No Default Value: none General Properties The following properties can be set after the connection is established. None of these properties are required. Property AutoCommit Description Controls whether the connection automatically commits transactions. Set this parameter to false to prevent the connection from automatically committing its transactions. You often want to do this when you are bulk loading multiple batches of data and you want the ability to roll back all of the loads if an error occurs. Previous Property NameNote: This property was called defaultautocommit in previous versions of the HP Vertica JDBC driver. Set After Connection: Connection.setAutoCommit() Default Value: true HP Vertica Analytic Database (7.1.x) Page 194 of 401

195 Property DirectBatchInsert Description Determines whether a batch insert stored data directly into ROS (true) or using AUTO mode (false). When you load data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. Set After Connection: VerticaConnection.setProperty() Default Value: false ReadOnly When set to true, makes the data connection read-only. Any queries attempting to update the database using a read-only connection cause a SQLException. Set After Connection: Connection.setReadOnly() Default Value: false ResultBufferSize Sets the size of the buffer the HP Vertica JDBC driver uses to temporarily store result sets. Note: This property was named maxlrsmemory in previous versions of the HP Vertica JDBC driver. Set After Connection: VerticaConnection.setProperty() Default Value: 8912 (8KB) SearchPath Sets the schema search path for the connection. This value is a string containing a comma-separated list of schema names. See Setting Search Paths in the Administrator's Guide for more information on the schema search path. Set After Connection: VerticaConnection.setProperty() Default Value: "$user", public, v_catalog, v_monitor, v_internal ThreePartNaming A Boolean value that controls how DatabaseMetaData reports the catalog name. When set to true, the database name is returned as the catalog name in the database metadata. When set to false, NULL is returned as the catalog name. Enable this option if your client software is set up to get the catalog name from the database metadata for use in a three-part name reference. Set After Connection: VerticaConnection.setProperty() Default Value: true HP Vertica Analytic Database (7.1.x) Page 195 of 401

196 Property TransactionIsolation Description Sets the isolation level of the transactions that use the connection. See Changing the Transaction Isolation Level for details. Note: In previous versions of the HP Vertica JDBC driver, this property was only available using a getter and setter on the PGConnection object. You can now set it in the same way as other connection properties. Set After Connection: Connection.setTransactionIsolation() Default Value: TRANSACTION_READ_COMMITTED Logging Properties The properties that control client logging must be set before the connection is opened. None of these properties are required, and none can be changed after the Connection object has been instantiated. Property LogLevel Description Sets the type of information logged by the JDBC driver. The value is set to one of the following values: "DEBUG" "ERROR" "TRACE" "WARNING" "INFO" "OFF" Default Value: "OFF" HP Vertica Analytic Database (7.1.x) Page 196 of 401

197 Property LogNameSpace Description Restricts logging to just messages generated by a specific packages. Valid values are: com.vertica All messages generated by the JDBC driver com.vertica.jdbc All messages generated by the top-level JDBC API com.vertica.jdbc.kv A ll messages generated by the JDBC KV API) com.vertica.jdbc.core Connection and statement settings com.vertica.jdbc.io Client/server protocol messages com.vertica.jdbc.util Miscellaneous utilities com.vertica.jdbc.dataengine Query execution and result set iteration com.vertica.dataengine Query execution and result set iteration Default Value: none LogPath Sets the path where the log file is written. Default Value: The current working directory Kerberos Connection Parameters Use the following parameters to set the service and host name principals for client authentication using Kerberos. Parameters JAASConfigName Description Provides the name of the JAAS configuration that contains the JAAS Krb5LoginModule and its settings Default Value: verticajdbc KerberosServiceName Provides the service name portion of the HP Vertica Kerberos principal, for example: vertica/[email protected] Default Value: vertica KerberosHostname Provides the instance or host name portion of thehp Vertica Kerberos principal, for example: vertica/[email protected] Default Value: Value specified in the servername connection string property HP Vertica Analytic Database (7.1.x) Page 197 of 401

198 Routable Connection API Connection Parameters Use the following parameters to set properties to enable and configure the connection for Routable Connection lookups. Parameters EnableRoutableQueries Description Enables Routable Connection lookup. See Routing JDBC Queries Directly to a Single Node Default Value: false FailOnMultiNodePlans If the query plan requires more than one node, then the query fails. Only applicable when EnableRoutableQueries = true. Default Value: true MetadataCacheLifetime The time in seconds to keep projection metadata. Only applicable when EnableRoutableQueries = true. Default Value: MaxPooledConnections Cluster-wide maximum number of connections to keep in the VerticaRoutableConnection s internal pool. Only applicable when EnableRoutableQueries = true. Default Value: 20 MaxPooledConnections PerNode Per-node maximum number of connections to keep in the VerticaRoutableConnection s internal pool. Only applicable when EnableRoutableQueries = true. Default Value: 5 Note: You can also use VerticaConnection.setProperty() method to set properties that have standard JDBC Connection setters, such as AutoCommit. For information about manipulating these attributes, see Setting and Getting Connection Property Values. Setting and Getting Connection Property Values You can set a connection property in any of three ways: HP Vertica Analytic Database (7.1.x) Page 198 of 401

199 Include the property name and value as part of the connection string you pass to the DriverManager.getConnection() method. Set the properties in a Properties object, and then pass it to the DriverManager.getConnection()method. Use the VerticaConnection.setProperty() method. With this approach, you can change only those connection properties that remain changeable after the connection has been established. In addition, some of the standard JDBC connection properties have getters and setters on the Connection interface (such as Connection.setAutocommit()). Setting Properties When Connecting There are two ways you can set connection properties when creating a connection to HP Vertica: In the connection string, using the same URL parameter format that you can use to set the username and password. The following example sets the SSL connection parameter to true: "jdbc:vertica://verticahost:5433/db?user=username&password=password&ssl=true" Setting a host name using the setproperty() method overrides the host name set in a connection string as seen above. If this occurs, Vertica may not be able to connect to a host. For example, using the connection string above, the following overrides the VerticaHost name: Properties props = new Properties(); props.setproperty("datasource", datasourceurl); props.setproperty("database", database); props.setproperty("user", user); props.setproperty("password", password); ps.setproperty("jdbcdriver", jdbcdriver); props.setproperty("hostname", "NonVertica_host"); However, if a new connection or override connection is needed, you may enter a valid host name in the hostname properties object. The NonVertica_host hostname overrides VerticaHost name in the connection string. To avoid this issue comment out the props.setproperty("hostname", "NonVertica_host"); line: //props.setproperty("hostname", "NonVertica_host"); In a Properties object that you pass to the getconnection() call. You will need to import the java.util.properties class in order to instantiate a Properties object. Then you use the put () method to add the property name and value to the object: HP Vertica Analytic Database (7.1.x) Page 199 of 401

200 Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); myprop.put("logintimeout", "35"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:/exampledb", myprop); catch (SQLException e) e.printstacktrace(); Note: The data type of all of the values you set in the Properties object are strings, even if the property value's data type is integer or Boolean. Getting and Setting Properties After Connecting The VerticaConnection.getProperty() method lets you get the value of some connection properties. You can use VerticaConnection.setProperty() method to change the value for properties that can be set after the database connection has been established. Since these methods are HP Vertica-specific, you must cast your Connection object to the VerticaConnection interface to be able to use them. To cast to VerticaConnection, you must either import it into your client application or use a fully-qualified reference (com.vertica.jdbc.verticaconnection). The following example demonstrates getting and setting the value of the DirectBatchInsert property. import java.sql.*; import java.util.properties; import com.vertica.jdbc.*; public class SetConnectionProperties public static void main(string[] args) // Note: If your application needs to run under Java 5, you need to // load the JDBC driver using Class.forName() here. Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); // Set DirectBatchInsert to true initially myprop.put("directbatchinsert", "true"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // Show state of the DirectBatchInsert property. This was set at the // time the connection was created. System.out.println("DirectBatchInsert state: " + ((VerticaConnection) conn).getproperty( "DirectBatchInsert")); // Change it and show it again ((VerticaConnection) conn).setproperty("directbatchinsert", false); HP Vertica Analytic Database (7.1.x) Page 200 of 401

201 System.out.println("DirectBatchInsert state is now: " + ((VerticaConnection) conn).getproperty( "DirectBatchInsert")); conn.close(); catch (SQLException e) e.printstacktrace(); When run, the example prints the following on the standard output: DirectBatchInsert state: true DirectBatchInsert state is now: false Setting the Locale for JDBC Sessions You set the locale for a connection while opening it by including a SET LOCALE statement in the ConnSettings property, or by executing a SET LOCALE statement at any time after opening the connection. Changing the locale of a Connection object affects all of the Statement objects you instantiated using it. You can get the locale by executing a SHOW LOCALE query. The following example demonstrates setting the locale using ConnSettings and executing a statement, as well as getting the locale: import java.sql.*; import java.util.properties; public class GetAndSetLocale public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); // Set Locale to true en_gb on connection. After the connection // is established, the JDBC driver runs the statements in the // ConnSettings property. myprop.put("connsettings", "SET LOCALE TO en_gb"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // Execute a query to get the locale. The results should // show "en_gb" as the locale, since it was set by the // conn settings property. Statement stmt = conn.createstatement(); ResultSet rs = null; rs = stmt.executequery("show LOCALE"); System.out.print("Query reports that Locale is set to: "); while (rs.next()) System.out.println(rs.getString(2).trim()); HP Vertica Analytic Database (7.1.x) Page 201 of 401

202 // Now execute a query to set locale. stmt.execute("set LOCALE TO en_us"); // Run query again to get locale. rs = stmt.executequery("show LOCALE"); System.out.print("Query now reports that Locale is set to: "); while (rs.next()) System.out.println(rs.getString(2).trim()); // Clean up conn.close(); catch (SQLException e) e.printstacktrace(); Running the above example displays the following on the system console: Query reports that Locale is set to: en_gb (LEN) Query now reports that Locale is set to: en_us (LEN) Notes: JDBC applications use a UTF-16 character set encoding and are responsible for converting any non-utf-16 encoded data to UTF-16. Failing to convert the data can result in errors or the data being stored incorrectly. The JDBC driver converts UTF-16 data to UTF-8 when passing to the HP Vertica server and converts data sent by HP Vertica server from UTF-8 to UTF-16. Changing the Transaction Isolation Level Changing the transaction isolation level lets you choose how transactions prevent interference from other transactions. By default, the JDBC driver matches the transaction isolation level of the HP Vertica server. The HP Vertica default transaction isolation level is READ_COMMITTED, which means any changes made by a transaction cannot be read by any other transaction until after they are committed. This prevents a transaction from reading data inserted by another transaction that is later rolled back. HP Vertica also supports the SERIALIZABLE transaction isolation level. This level locks tables to prevent queries from having the results of their WHERE clauses changed by other transactions. Locking tables can have a performance impact, since only one transaction is able to access the table at a time. A transaction retains its isolation level until it completes, even if the session's transaction isolation level changes mid-transaction. HP Vertica internal processes (such as the Tuple Mover and HP Vertica Analytic Database (7.1.x) Page 202 of 401

203 refresh operations) and DDL operations are always run at SERIALIZABLE isolation level to ensure consistency. You can change the transaction isolation level connection property after the connection has been established using the Connection object's setter (settransactionisolation()) and getter (gettransactionisolation()). The value for transaction isolation property is an integer. The Connection interface defines constants to help you set the value in a more intuitive manner: Constant Value Connection.TRANSACTION_READ_COMMITTED 2 Connection.TRANSACTION_SERIALIZABLE 8 Note: The Connection interface also defines several other transaction isolation constants (READ_UNCOMMITTED and REPEATABLE_READ). Since HP Vertica does not support these isolation levels, they are converted to READ_COMMITTED and SERIALIZABLE, respectively. The following example demonstrates setting the transaction isolation level to SERIALIZABLE. import java.sql.*; import java.util.properties; public class SetTransactionIsolation public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // Get default transaction isolation System.out.println("Transaction Isolation Level: " + conn.gettransactionisolation()); // Set transaction isolation to SERIALIZABLE conn.settransactionisolation(connection.transaction_serializable); // Get the transaction isolation again System.out.println("Transaction Isolation Level: " + conn.gettransactionisolation()); conn.close(); catch (SQLException e) e.printstacktrace(); Running the example results in the following being printed out to the console: Transaction Isolation Level: 2Transaction Isolation Level: 8 HP Vertica Analytic Database (7.1.x) Page 203 of 401

204 Using a Pooling Data Source A pooling data source uses a collection of persistent connections in order to reduce the overhead of repeatedly opening network connections between the client and server. Opening a new connection for each request is costly for both the server and the client than keeping a small pool of connections open constantly, ready to be used by new requests. When a request comes in, one of the preexisting connections in the pool is assigned to it. Only if there are no free connections in the pool is a new connection created. Once the request is complete, the connection returns to the pool and waits to service another request. The HP Vertica JDBC driver supports connection pooling as defined in the JDBC 4.0 standard. If you are using a J2EE-based application server in conjunction with HP Vertica, it should already have a built-in data pooling feature. All that is required is that the application server work with the PooledConnection interface implemented by HP Vertica's JDBC driver. An application server's pooling feature is usually well-tuned for the works loads that the server is designed to handle. See your application server's documentation for details on how to work with pooled connections. Normally, using pooled connections should be transparent in your code you will just open connections and the application server will worry about the details of pooling them. If you are not using an application server, or your application server does not offer connection pooling that is compatible with HP Vertica, you can use a third-party pooling library, such as the open-source c3p0 or DBCP libraries, to implement connection pooling. Note: The Vertica Analytic Database client driver's native connection load balancing feature works with third-party connection pooling supplied by application servers and third-party pooling libraries. See Enabling Native Connection Load Balancing in JDBC for more information. Enabling Native Connection Load Balancing in JDBC Native connection load balancing helps spread the overhead caused by client connections on the hosts in the HP Vertica database. Both the server and the client must enable native connection load balancing in order for it to have an effect. If both have enabled it, then when the client initially connects to a host in the database, the host picks a host to handle the client connection from a list of the currently up hosts in the database, and informs the client which host it has chosen. If the initially-contacted host did not choose itself to handle the connection, the client disconnects, then opens a second connection to the host selected by the first host. The connection process to this second host proceeds as usual if SSL is enabled, then SSL negotiations begin, otherwise the client begins the authentication process. See About Native Connection Load Balancing in the Administrator's Guide for details. To enable native load balancing on your client, set the ConnectionLoadBalance connection parameter to true. The following example demonstrates connecting to the database several times with native connection load balancing enabled, and fetching the name of the node handling the connection from the V_MONITOR.CURRENT_SESSION system table. import java.sql.*; HP Vertica Analytic Database (7.1.x) Page 204 of 401

205 import java.util.properties; import com.vertica.jdbc.datasource; public class ConnectionLoadBalancingExample public static void main(string[] args) /* * If your client needs to run under a Java 5 JVM, It will use the older * JDBC 3.0-compliant driver, which requires you manually load the * driver using Class.forname */ the Properties myprop = new Properties(); myprop.put("user", "dbadmin"); myprop.put("password", "vertica"); // Enable connection load balancing on this client. Only works if it is set on // server as well. myprop.put("connectionloadbalance", 1); Connection conn; // Connect 4 times. See if we connect to a different node each time. for (int x=1; x <= 4; x++) try System.out.print("Connect attempt #" + x + "..."); conn = DriverManager.getConnection( "jdbc:vertica://docd03.verticacorp.com:5433/vmart", myprop); Statement stmt = conn.createstatement(); // Query system to table to see what node we are connected to. Assume a single row // in response set. ResultSet rs = stmt.executequery("select node_name FROM v_ monitor.current_session;"); rs.next(); System.out.println("Connected to node " + rs.getstring(1).trim()); conn.close(); catch (SQLException e) // Catch-all for other exceptions System.out.println("Error!"); e.printstacktrace(); Running the above example produces the following output: Connect attempt #1...Connected to node v_vmart_node0001 Status of load balance policy on server: roundrobin Connect attempt #2...Connected to node v_vmart_node0002 Connect attempt #3...Connected to node v_vmart_node0003 Connect attempt #4...Connected to node v_vmart_node0001 HP Vertica Analytic Database (7.1.x) Page 205 of 401

206 JDBC Connection Failover If a client application attempts to connect to a host in the Vertica Analytic Database cluster that is down, the connection attempt fails when using the default connection configuration. This failure usually returns an error to the user. The user must either wait until the host recovers and retry the connection or manually edit the connection settings to choose another host. Due to Vertica Analytic Database's distributed architecture, you usually do not care which database host handles a client application's connection. You can use the client driver's connection failover feature to prevent the user from getting connection errors when the host specified in the connection settings is unreachable. It gives you two ways to let the client driver automatically attempt to connect to a different host if the one specified in the connection parameters is unreachable: Configure your DNS server to return multiple IP addresses for a host name. When you use this host name in the connection settings, the client attempts to connect to the first IP address from the DNS lookup. If the host at that IP address is unreachable, the client tries to connect to the second IP, and so on until it either manages to connect to a host or it runs out of IP addresses. Supply a list of backup hosts for the client driver to try if the primary host you specify in the connection parameters is unreachable. For both methods, the process of failover is transparent to the client application (other than specifying the list of backup hosts, if you choose to use the list method of failover). If the primary host is unreachable, the client driver automatically tries to connect to other hosts. Failover only applies to the initial establishment of the client connection. If the connection breaks, the driver does not automatically try to reconnect to another host in the database. Choosing a Failover Method You usually choose to use one of the two failover methods. However, they do work together. If your DNS server returns multiple IP addresses and you supply a list of backup hosts, the client first tries all of the IPs returned by the DNS server, then the hosts in the backup list. Note: If a host name in the backup host list resolves to multiple IP addresses, the client does not try all of them. It just tries the first IP address in the list. The DNS method of failover centralizes the configuration client failover. As you add new nodes to your Vertica Analytic Database cluster, you can choose to add them to the failover list by editing the DNS server settings. All client systems that use the DNS server to connect to Vertica Analytic Database automatically use connection failover without having to change any settings. However, this method does require administrative access to the DNS server that all clients use to connect to the Vertica Analytic Database cluster. This may not be possible in your organization. Using the backup server list is easier than editing the DNS server settings. However, it decentralizes the failover feature. You may need to update the application settings on each client system if you make changes to your Vertica Analytic Database cluster. HP Vertica Analytic Database (7.1.x) Page 206 of 401

207 Using DNS Failover To use DNS failover, you need to change your DNS server's settings to map a single host name to multiple IP addresses of hosts in your Vertica Analytic Database cluster. You then have all client applications use this host name to connect to Vertica Analytic Database. You can choose to have your DNS server return as many IP addresses for the host name as you want. In smaller clusters, you may choose to have it return the IP addresses of all of the hosts in your cluster. However, for larger clusters, you should consider choosing a subset of the hosts to return. Otherwise there can be a long delay as the client driver tries unsuccessfully to connect to each host in a database that is down. Using the Backup Host List To enable backup list-based connection failover, your client application has to specify at least one IP address or host name of a host in the BackupServerNode parameter. The host name or IP can optionally be followed by a colon and a port number. If not supplied, the driver defaults to the standard HP Vertica port number (5433). To list multiple hosts, separate them by a comma. The following example demonstrates setting the BackupServerNode connection parameter to specify additional hosts for the connection attempt. The connection string intentionally has a nonexistent node, so that the initial connection fails. The client driver has to resort to trying the backup hosts to establish a connection to HP Vertica. import java.sql.*; import java.util.properties; public class ConnectionFailoverExample public static void main(string[] args) // Assume using JDBC 4.0 driver on JVM 6+. No driver loading needed. Properties myprop = new Properties(); myprop.put("user", "dbadmin"); myprop.put("password", "vertica"); // Set two backup hosts to be used if connecting to the first host // fails. All of these hosts will be tried in order until the connection // succeeds or all of the connections fail. myprop.put("backupservernode", "VerticaHost02,VerticaHost03"); Connection conn; try // The connection string is set to try to connect to a known // bnad host (in this case, a host that never existed). conn = DriverManager.getConnection( "jdbc:vertica://badverticahost:5433/vmart", myprop); System.out.println("Connected!"); // Query system to table to see what node we are connected to. // Assume a single row in response set. Statement stmt = conn.createstatement(); ResultSet rs = stmt.executequery( "SELECT node_name FROM v_monitor.current_session;"); rs.next(); System.out.println("Connected to node " + rs.getstring(1).trim()); HP Vertica Analytic Database (7.1.x) Page 207 of 401

208 // Done with connection. conn.close(); catch (SQLException e) // Catch-all for other exceptions e.printstacktrace(); When run, the example outputs output similar to the following on the system console: Connected! Connected to node v_vmart_node0002 Notice that the connection was made to the first node in the backup list (node 2). Notes When native connection load balancing is enabled, the additional servers specified in the BackupServerNode connection parameter are only used for the initial connection to an HP Vertica host. If host redirects the client to another host in the database cluster to handle its connection request, the second connection does not use the backup node list. This is rarely an issue, since native connection load balancing is aware of which nodes are currently up in the database. See Enabling Native Connection Load Balancing in JDBC for more information. HP Vertica Analytic Database (7.1.x) Page 208 of 401

209 JDBC Data Types The JDBC driver transparently converts most HP Vertica data types to the appropriate Java data type. In a few cases, an HP Vertica data type cannot be directly translated to a Java data type; these exceptions are explained in this section. Numeric Data Alias Conversion The HP Vertica server supports data type aliases for integer, float and numeric types. The JDBC driver reports these as its basic data types (BIGINT, DOUBLE PRECISION, and NUMERIC), as follows: HP Vertica Server Types and Aliases INTEGER HP Vertica JDBC Type BIGINT INT INT8 BIGINT SMALLINT TINYINT DOUBLE PRECISION DOUBLE PRECISION FLOAT5 FLOAT8 REAL DECIMAL NUMERIC NUMERIC NUMBER MONEY If a client application retrieves the values into smaller data types, HP Vertica JDBC driver does not check for overflows. The following example demonstrates the results of this overflow. import java.sql.*; import java.util.properties; public class JDBCDataTypes public static void main(string[] args) // If running under a Java 5 JVM, use you need to load the JDBC driver // using Class.forname here Properties myprop = new Properties(); HP Vertica Analytic Database (7.1.x) Page 209 of 401

210 myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/vmart", myprop); Statement statement = conn.createstatement(); // Create a table that will hold a row of different types of // numeric data. statement.executeupdate( "DROP TABLE IF EXISTS test_all_types cascade"); statement.executeupdate("create TABLE test_all_types (" + "c0 INTEGER, c1 TINYINT, c2 DECIMAL, " + "c3 MONEY, c4 DOUBLE PRECISION, c5 REAL)"); // Add a row of values to it. statement.executeupdate("insert INTO test_all_types VALUES(" + " , 444, , " + " , , " + " )"); // Query the new table to get the row back as a result set. ResultSet rs = statement.executequery("select * FROM test_all_types"); // Get the metadata about the row, including its data type. ResultSetMetaData md = rs.getmetadata(); // Loop should only run once... while (rs.next()) // Print out the data type used to defined the column, followed // by the values retrieved using several different retrieval // methods. String[] verttypes = new String[] "INTEGER", "TINYINT", "DECIMAL", "MONEY", "DOUBLE PRECISION", "REAL"; for (int x=1; x<7; x++) System.out.println("\n\nColumn " + x + " (" + verttypes[x-1] + ")"); System.out.println("\tgetColumnType()\t\t" + md.getcolumntype(x)); System.out.println("\tgetColumnTypeName()\t" + md.getcolumntypename(x)); System.out.println("\tgetShort()\t\t" + rs.getshort(x)); System.out.println("\tgetLong()\t\t" + rs.getlong(x)); System.out.println("\tgetInt()\t\t" + rs.getint(x)); System.out.println("\tgetByte()\t\t" + rs.getbyte(x)); rs.close(); statement.executeupdate("drop table test_all_types cascade"); statement.close(); catch (SQLException e) e.printstacktrace(); The above example prints the following on the console when run: HP Vertica Analytic Database (7.1.x) Page 210 of 401

211 Column 1 (INTEGER) getcolumntype() -5 getcolumntypename() BIGINT getshort() 455 getlong() getint() getbyte() -57 Column 2 (TINYINT) getcolumntype() -5 getcolumntypename() BIGINT getshort() 444 getlong() 444 getint() 444 getbyte() -68 Column 3 (DECIMAL) getcolumntype() 2 getcolumntypename() NUMERIC getshort() -1 getlong() getint() getbyte() -1 Column 4 (MONEY) getcolumntype() 2 getcolumntypename() NUMERIC getshort() getlong() getint() getbyte() 113 Column 5 (DOUBLE PRECISION) getcolumntype() 8 getcolumntypename() DOUBLE PRECISION getshort() -1 getlong() getint() getbyte() -1 Column 6 (REAL) getcolumntype() 8 getcolumntypename() DOUBLE PRECISION getshort() 8466 getlong() getint() getbyte() 18 Using Intervals with JDBC The JDBC standard does not contain a data type for intervals (the duration between two points in time). To handle HP Vertica's INTERVAL data type, you must use JDBC's database-specific object type. When reading an interval value from a result set, use the ResultSet.getObject() method to retrieve the value, and then cast it to one of the HP Vertica interval classes: VerticaDayTimeInterval (which represents all ten types of day/time intervals) or VerticaYearMonthInterval (which represents all three types of year/month intervals). HP Vertica Analytic Database (7.1.x) Page 211 of 401

212 Note: The units interval style is not supported. Do not use the SET INTERVALSTYLE statement to change the interval style in your client applications. Using Intervals in Batch Inserts When inserting batches into tables that contain interval data, you must create instances of the VerticaDayTimeInterval or VerticaYearMonthInterval classes to hold the data you want to insert. You set values either when calling the class's constructor, or afterwards using setters. You then insert your interval values using the PreparedStatement.setObject() method. You can also use the.setstring() method, passing it a string in "DD HH:MM:SS" or "YY-MM" format. The following example demonstrates inserting data into a table containing a day/time interval and a year/month interval: import java.sql.*; import java.util.properties; // Need to import the Vertica JDBC classes to be able to instantiate // the interval classes. import com.vertica.jdbc.*; public class IntervalDemo public static void main(string[] args) // If running under a Java 5 JVM, use you need to load the JDBC driver // using Class.forname here Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/vmart", myprop); // Create table for interval values Statement stmt = conn.createstatement(); stmt.execute("drop TABLE IF EXISTS interval_demo"); stmt.executeupdate("create TABLE interval_demo(" + "DayInt INTERVAL DAY TO SECOND, " + "MonthInt INTERVAL YEAR TO MONTH)"); // Insert data into interval columns using // VerticaDayTimeInterval and VerticaYearMonthInterval // classes. PreparedStatement pstmt = conn.preparestatement( "INSERT INTO interval_demo VALUES(?,?)"); // Create instances of the Vertica classes that represent // intervals. VerticaDayTimeInterval dayint = new VerticaDayTimeInterval(10, 0, 5, 40, 0, 0, false); VerticaYearMonthInterval monthint = new VerticaYearMonthInterval( 10, 6, false); // These objects can also be manipulated using setters. dayint.sethour(7); // Add the interval values to the batch ((VerticaPreparedStatement) pstmt).setobject(1, dayint); ((VerticaPreparedStatement) pstmt).setobject(2, monthint); pstmt.addbatch(); HP Vertica Analytic Database (7.1.x) Page 212 of 401

213 // Set another row from strings. // Set day interval in "days HH:MM:SS" format pstmt.setstring(1, "10 10:10:10"); // Set year to month value in "MM-YY" format pstmt.setstring(2, "12-09"); pstmt.addbatch(); // Execute the batch to insert the values. try pstmt.executebatch(); catch (SQLException e) System.out.println("Error message: " + e.getmessage()); Reading Interval Values You read an interval value from a result set using the ResultSet.getObject() method, and cast the object to the appropriate HP Vertica object class: VerticaDayTimeInterval for day/time intervals or VerticaYearMonthInterval for year/month intervals. This is easy to do if you know that the column contains an interval, and you know what type of interval it is. If your application cannot assume the structure of the data in the result set it reads in, you can test whether a column contains a database-specific object type, and if so, determine whether the object belongs to either the VerticaDayTimeInterval or VerticaYearMonthInterval classes. // Retrieve the interval values inserted by previous demo. // Query the table to get the row back as a result set. ResultSet rs = stmt.executequery("select * FROM interval_demo"); // If you do not know the types of data contained in the result set, // you can read its metadata to determine the type, and use // additional information to determine the interval type. ResultSetMetaData md = rs.getmetadata(); while (rs.next()) for (int x = 1; x <= md.getcolumncount(); x++) // Get data type from metadata int coldatatype = md.getcolumntype(x); // You can get the type in a string: System.out.println("Column " + x + " is a " + md.getcolumntypename(x)); // Normally, you'd have a switch statement here to // handle all sorts of column types, but this example is // simplified to just handle database-specific types if (coldatatype == Types.OTHER) // Column contains a database-specific type. Determine // what type of interval it is. Assuming it is an // interval... Object columnval = rs.getobject(x); if (columnval instanceof VerticaDayTimeInterval) // We know it is a date time interval VerticaDayTimeInterval interval = (VerticaDayTimeInterval) columnval; // You can use the getters to access the interval's // data System.out.print("Column " + x + "'s value is "); System.out.print(interval.getDay() + " Days "); HP Vertica Analytic Database (7.1.x) Page 213 of 401

214 System.out.print(interval.getHour() + " Hours "); System.out.println(interval.getMinute() + " Minutes"); else if (columnval instanceof VerticaYearMonthInterval) VerticaYearMonthInterval interval = (VerticaYearMonthInterval) columnval; System.out.print("Column " + x + "'s value is "); System.out.print(interval.getYear() + " Years "); System.out.println(interval.getMonth() + " Months"); else System.out.println("Not an interval."); catch (SQLException e) e.printstacktrace(); The example prints the following to the console: Column 1 is a INTERVAL DAY TO SECOND Column 1's value is 10 Days 7 Hours 5 Minutes Column 2 is a INTERVAL YEAR TO MONTH Column 2's value is 10 Years 6 Months Column 1 is a INTERVAL DAY TO SECOND Column 1's value is 10 Days 10 Hours 10 Minutes Column 2 is a INTERVAL YEAR TO MONTH Column 2's value is 12 Years 9 Months Another option is to use database metadata to find columns that contain intervals. // Determine the interval data types by examining the database // metadata. DatabaseMetaData dbmd = conn.getmetadata(); ResultSet dbmeta = dbmd.getcolumns(null, null, "interval_demo", null); int colcount = 0; while (dbmeta.next()) // Get the metadata type for a column. int javatype = dbmeta.getint("data_type"); System.out.println("Column " + ++colcount + " Type name is " + dbmeta.getstring("type_name")); if(javatype == Types.OTHER) // The SQL_DATETIME_SUB column in the metadata tells you // Specifically which subtype of interval you have. // The VerticaDayTimeInterval.isDayTimeInterval() // methods tells you if that value is a day time. // int intervaltype = dbmeta.getint("sql_datetime_sub"); if(verticadaytimeinterval.isdaytimeinterval(intervaltype)) HP Vertica Analytic Database (7.1.x) Page 214 of 401

215 // Now you know it is one of the 10 day/time interval types. // When you select this column you can cast to // VerticaDayTimeInterval. // You can get more specific by checking intervaltype // against each of the 10 constants directly, but // they all are represented by the same object. System.out.println("column " + colcount + " is a " + "VerticaDayTimeInterval intervaltype = " + intervaltype); else if(verticayearmonthinterval.isyearmonthinterval( intervaltype)) //now you know it is one of the 3 year/month intervals, //and you can select the column and cast to // VerticaYearMonthInterval System.out.println("column " + colcount + " is a " + "VerticaDayTimeInterval intervaltype = " + intervaltype); else System.out.println("Not an interval type."); Executing Queries Through JDBC To run a query through JDBC: 1. Connect with the HP Vertica database. See Creating and Configuring a Connection. 2. Run the query. The method you use to run the query depends on the type of query you want to run: a DDL query that does not return a result set. a DDL query that returns a result set. a DML query Executing DDL (Data Definition Language) Queries To run DDL queries, such as CREATE TABLE and COPY, use the Statement.execute() method. You get an instance of this class by calling the createstatement method of your connection object. The following example creates an instance of the Statement class and uses it to execute a CREATE TABLE and a COPY query: Statement stmt = conn.createstatement(); stmt.execute("create TABLE address_book (Last_Name char(50) default ''," + "First_Name char(50), char(50),phone_number char(50))"); HP Vertica Analytic Database (7.1.x) Page 215 of 401

216 stmt.execute("copy address_book FROM 'address.dat' DELIMITER ',' NULL 'null'"); Executing Queries That Return Result Sets Use the Statement class's executequery method to execute queries that return a result set, such as SELECT. To get the data from the result set, use methods such as getint, getstring, and getdouble to access column values depending upon the data types of columns in the result set. Use ResultSet.next to advance to the next row of the data set. ResultSet rs = null; rs = stmt.executequery("select First_Name, Last_Name FROM address_book"); int x = 1; while(rs.next()) System.out.println(x + ". " + rs.getstring(1).trim() + " " + rs.getstring(2).trim()); x++; Note: The HP Vertica JDBC driver does not support scrollable cursors. You can only read forwards through the result set. Executing DML (Data Manipulation Language) Queries Using executeupdate Use the executeupdate method for DML SQL queries that change data in the database, such as INSERT, UPDATE and DELETE which do not return a result set. stmt.executeupdate("insert INTO address_book " + "VALUES ('Ben-Shachar', 'Tamar', '[email protected]'," + "' ')"); stmt.executeupdate("insert INTO address_book (First_Name, ) " + "VALUES ('Pete','[email protected]')"); Note: The HP Vertica JDBC driver's Statement class supports executing multiple statements in the SQL string you pass to the execute method. The PreparedStatement class does not support using multiple statements in a single execution. HP Vertica Analytic Database (7.1.x) Page 216 of 401

217 Loading Data Through JDBC You can use any of the following methods to load data via the JDBC interface: Executing a SQL INSERT statement to insert a single row directly. Batch loading data using a prepared statement. Bulk loading data from files or streams using COPY. When loading data into HP Vertica, you need to decide whether to write data to the Write Optimized Store (WOS) or the Read Optimized Store (ROS). By default, most data loading methods insert data into the WOS until it fills up, then insert any additional data directly into ROS containers (called AUTO mode). This is the best method to use when frequently loading small amounts of data (often referred to as trickle-loading). When performing less frequent large data loads (any loads over 100MB of data at once), you should change this behavior to insert data directly into the ROS. The following sections explain in detail how you load data using JDBC. Using a Single Row Insert The simplest way to insert data into a table is to use the SQL INSERT statement. You can use this statement by instantiating a member of the Statement class, and use its executeupdate() method to run your SQL statement. The following code fragment demonstrates how you can create a Statement object and use it to insert data into a table named address_book: Statement stmt = conn.createstatement(); stmt.executeupdate("insert INTO address_book " + "VALUES ('Smith', 'John', '[email protected]', " + "' ')"); This method has a few drawbacks: you need convert your data to string and escape any special characters in your data. A better way to insert data is to use prepared statements. See Batch Inserts Using JDBC Prepared Statements. Using LONG VARCHAR and LONG VARBINARY Data Types with JDBC Using LONG VARCHAR and LONG VARBINARY data types in a JDBC client application is similar to using VARCHAR and VARBINARY data types. The JDBC driver transparently handles the conversion (for example, between a Java String object and a LONG VARCHAR). The following example code demonstrates inserting and retrieving a LONG VARCHAR string. It uses the JDBC Types class to determine the data type of the string returned by HP Vertica, although it does not actually need to know whether the database column is a LONG VARCHAR or just a VARCHAR in order to retrieve the value. HP Vertica Analytic Database (7.1.x) Page 217 of 401

218 import java.sql.*; import java.util.properties; public class LongVarcharExample public static void main(string[] args) try Class.forName("com.vertica.jdbc.Driver"); catch (ClassNotFoundException e) System.err.println("Could not find the JDBC driver class."); e.printstacktrace(); return; Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // establish connection and make a table for the data. Statement stmt = conn.createstatement(); // How long we want the example string to be. This is // larger than can fit into a traditional VARCHAR (which is limited // to int length = ; // Create a table with a LONG VARCHAR column that can store // the string we want to insert. stmt.execute("drop TABLE IF EXISTS longtable CASCADE"); stmt.execute("create TABLE longtable (text LONG VARCHAR(" + length + "))"); // Build a long string by appending an integer to a string builder // until we hit the size limit. Will result in a string // containing StringBuilder sb = new StringBuilder(length); for (int i = 0; i < length; i++) sb.append(i % 10); String value = sb.tostring(); System.out.println("String value is " + value.length() + " characters long."); // Create the prepared statement PreparedStatement pstmt = conn.preparestatement( "INSERT INTO longtable (text)" + " VALUES(?)"); try // Insert LONG VARCHAR value System.out.println("Inserting LONG VARCHAR value"); pstmt.setstring(1, value); pstmt.addbatch(); pstmt.executebatch(); // Query the table we created to get the value back. ResultSet rs = null; HP Vertica Analytic Database (7.1.x) Page 218 of 401

219 rs = stmt.executequery("select * FROM longtable"); // Get metadata about the result set. ResultSetMetaData rsmd = rs.getmetadata(); // Print the type of the first column. Should be // LONG VARCHAR. Also check it against the Types class, to // recognize it programmatically. System.out.println("Column #1 data type is: " + rsmd.getcolumntypename(1)); if (rsmd.getcolumntype(1) == Types.LONGVARCHAR) System.out.println("It is a LONG VARCHAR"); else System.out.println("It is NOT a LONG VARCHAR"); // Print out the string length of the returned value. while (rs.next()) // Use the same getstring method to get the value that you // use to get the value of a VARCHAR. System.out.println("Returned string length: " + rs.getstring(1).length()); catch (SQLException e) System.out.println("Error message: " + e.getmessage()); return; // Exit if there was an error // Cleanup conn.close(); catch (SQLException e) e.printstacktrace(); Note: Do not use inefficient encoding formats for LONG VARBINARY and LONG VARCHAR values. HP Vertica cannot load encoded values larger than 32MB, even if the decoded value is less than 32 MB in size. For example, HP Vertica returns an error if you attempt to load a 32MB LONG VARBINARY value encoded in octal format, since the octal encoding quadruples the size of the value (each byte is converted into a backslash followed by three digits). HP Vertica Analytic Database (7.1.x) Page 219 of 401

220 Batch Inserts Using JDBC Prepared Statements You can load batches of data into HP Vertica using prepared INSERT statements server-side statements that you set up once, and then call repeatedly. You instantiate a member of the PreparedStatement class with a SQL statement that contains question mark placeholders for data. For example: PreparedStatement pstmt = conn.preparestatement( "INSERT INTO customers(last, first, id) VALUES(?,?,?)"); You then set the parameters using data-type-specific methods on the PreparedStatement object, such as setstring() and setint(). Once your parameters are set, call the addbatch() method to add the row to the batch. When you have a complete batch of data ready, call the executebatch() method to execute the insert batch. Behind the scenes, the batch insert is converted into a COPY statement. When the connection's AutoCommit parameter is disabled, HP Vertica keeps the COPY statement open and uses it to load subsequent batches until the transaction is committed, the cursor is closed, or your application executes anything else (or executes any statement using another Statement or PreparedStatement object). Using a single COPY statement for multiple batch inserts makes loading data more efficient. If you are loading multiple batches, you should disable the AutoCommit property of the database to take advantage of this increased efficiency. When performing batch inserts, experiment with various batch and row sizes to determine the settings that provide the best performance. The following example demonstrates using a prepared statement to batch insert data. import java.sql.*; import java.util.properties; public class BatchInsertExample public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); //Set streamingbatchinsert to True to enable streaming mode for batch inserts. //myprop.put("streamingbatchinsert", "True"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // establish connection and make a table for the data. Statement stmt = conn.createstatement(); // Set AutoCommit to false to allow Vertica to reuse the same // COPY statement conn.setautocommit(false); HP Vertica Analytic Database (7.1.x) Page 220 of 401

221 // Drop table and recreate. stmt.execute("drop TABLE IF EXISTS customers CASCADE"); stmt.execute("create TABLE customers (CustID int, Last_Name" + " char(50), First_Name char(50), char(50), " + "Phone_Number char(12))"); // Some dummy data to insert. String[] firstnames = new String[] "Anna", "Bill", "Cindy", "Don", "Eric" ; String[] lastnames = new String[] "Allen", "Brown", "Chu", "Dodd", "Estavez" ; String[] s = new String[] "[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]" ; String[] phonenumbers = new String[] " ", " ", " ", " ", " " ; // Create the prepared statement PreparedStatement pstmt = conn.preparestatement( "INSERT INTO customers (CustID, Last_Name, " + "First_Name, , Phone_Number)" + " VALUES(?,?,?,?,?)"); // Add rows to a batch in a loop. Each iteration adds a // new row. for (int i = 0; i < firstnames.length; i++) // Add each parameter to the row. pstmt.setint(1, i + 1); pstmt.setstring(2, lastnames[i]); pstmt.setstring(3, firstnames[i]); pstmt.setstring(4, s[i]); pstmt.setstring(5, phonenumbers[i]); // Add row to the batch. pstmt.addbatch(); try // Batch is ready, execute it to insert the data pstmt.executebatch(); catch (SQLException e) System.out.println("Error message: " + e.getmessage()); return; // Exit if there was an error // Commit the transaction to close the COPY command conn.commit(); // Print the resulting table. ResultSet rs = null; rs = stmt.executequery("select CustID, First_Name, " + "Last_Name FROM customers ORDER BY CustID"); while (rs.next()) System.out.println(rs.getInt(1) + " - " + rs.getstring(2).trim() + " " + rs.getstring(3).trim()); // Cleanup conn.close(); HP Vertica Analytic Database (7.1.x) Page 221 of 401

222 catch (SQLException e) e.printstacktrace(); The result of running the example code is: 1 - Anna Allen 2 - Bill Brown 3 - Cindy Chu 4 - Don Dodd 5 - Eric Estavez Streaming Batch Inserts By default, HP Vertica performs batch inserts by caching each row and inserting the cache when the user calls the executebatch() method. HP Vertica also supports streaming batch inserts. A streaming batch insert adds a row to the database each time the user calls addbatch(). Streaming batch inserts improve database performance by allowing parallel processing and reducing memory demands. Note: Once you begin a streaming batch insert, you cannot make other JDBC calls that require client-server communication until you have executed the batch or closed or rolled back the connection. To enable streaming batch inserts, set the streamingbatchinsert property to True. The preceding code sample includes a line enabling streamingbatchinsert mode. Remove the // comment marks to enable this line and activate streaming batch inserts. The following table explains the various batch insert methods and how their behavior differs between default batch insert mode and streaming batch insert mode. Method addbatch() executebatch() clearbatch() Default Batch Insert Behavior Adds a row to the row cache. Adds the contents of the row cache to the database in a single action. Clears the row cache without inserting any rows. Streaming Batch Insert Behavior Inserts a row into the database. Sends an end-of-batch message to the server and returns an array of integers indicating the success or failure of each addbatch() attempt. Not supported. Triggers an exception if used when streaming batch inserts are enabled. HP Vertica Analytic Database (7.1.x) Page 222 of 401

223 Notes Using the PreparedStatement.setFloat() method can cause rounding errors. If precision is important, use the.setdouble() method instead. The PreparedStatement object caches the connection's AutoCommit property when the statement is prepared. Later changes to the AutoCommit property have no effect on the prepared statement. Loading Batches Directly into ROS When loading large batches of data (more than 100MB or so), you should load the data directly into ROS containers. Inserting directly into ROS is more efficient for large loads than AUTO mode, since it avoids overflowing the WOS and spilling the remainder of the batch to ROS. Otherwise, the Tuple Mover has to perform a moveout on the data in the WOS, while subsequent data is directly written into ROS containers causing your data to be segmented across storage containers. When you load data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. To directly load batches into ROS, set the directbatchinsert connection property to true. See Setting and Getting Connection Property Values for an explanation of how to set connection properties. When this property is set to true, all batch inserts bypass the WOS and load directly into a ROS container. If all of batches being inserted using a connection should be inserted into the ROS, you should set the DirectBatchInsert connection property to true in the Properties object you use to create the connection: Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); // Enable directbatchinsert for this connection myprop.put("directbatchinsert", "true"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop);... If you will be using the connection for inserting both large and small batches (or you do not know the size batches you will be inserting when you create the Connection object), you can set the DirectBatchInsert property after the connection has been established using the VerticaConnection.setProperty method: ((VerticaConnection)conn).setProperty("DirectBatchInsert", true); See Setting and Getting Connection Property Values for a full example of setting DirectBatchInsert. HP Vertica Analytic Database (7.1.x) Page 223 of 401

224 Error Handling During Batch Loads When loading individual batches, you can find how many rows were accepted and what rows were rejected (see Identifying Accepted and Rejected Rows for details). If you have disabled the AutoCommit connection setting, other errors (such as disk space errors, for example) do not occur while inserting individual batches. This behavior is caused by having a single SQL COPY statement perform the loading of multiple consecutive batches (which makes the load process more efficient). It is only when the COPY statement closes that the batched data is committed and HP Vertica reports other types of errors. Therefore, your bulk loading application should be prepared to check for errors when the COPY statement closes. You can trigger the COPY statement to close by: ending the batch load transaction by calling Connection.commit() closing the statement using Statement.close() setting the connection's AutoCommit property to true before inserting the last batch in the load Note: The COPY statement also closes if you execute any non-insert statement or execute any statement using a different Statement or PreparedStatement object. Ending the COPY statement using either of these methods can lead to confusion and a harder-to-maintain application, since you would need to handle batch load errors in a non-batch load statement. You should explicitly end the COPY statement at the end of your batch load and handle any errors at that time. Identifying Accepted and Rejected Rows (JDBC) The return value of PreparedStatement.executeBatch is an integer array containing the success or failure status of inserting each row. A value 1 means the row was accepted and a value of -3 means that the row was rejected. In the case where an exception occurred during the batch execution, you can also get the array using BatchUpdateException.getUpdateCounts(). The following example extends the example shown in Batch Inserts Using JDBC Prepared Statements to retrieve this array and display the results the batch load. import java.sql.*; import java.util.arrays; import java.util.properties; public class BatchInsertErrorHandlingExample public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; // establish connection and make a table for the data. try HP Vertica Analytic Database (7.1.x) Page 224 of 401

225 conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // Disable auto commit conn.setautocommit(false); // Create a statement Statement stmt = conn.createstatement(); // Drop table and recreate. stmt.execute("drop TABLE IF EXISTS customers CASCADE"); stmt.execute("create TABLE customers (CustID int, Last_Name" + " char(50), First_Name char(50), char(50), " + "Phone_Number char(12))"); // Some dummy data to insert. The one row won't insert because // the phone number is too long for the phone column. String[] firstnames = new String[] "Anna", "Bill", "Cindy", "Don", "Eric" ; String[] lastnames = new String[] "Allen", "Brown", "Chu", "Dodd", "Estavez" ; String[] s = new String[] "[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]" ; String[] phonenumbers = new String[] " ", " ", " ", " ", " " ; // Create the prepared statement PreparedStatement pstmt = conn.preparestatement( "INSERT INTO customers (CustID, Last_Name, " + "First_Name, , Phone_Number)" + " VALUES(?,?,?,?,?)"); // Add rows to a batch in a loop. Each iteration adds a // new row. for (int i = 0; i < firstnames.length; i++) // Add each parameter to the row. pstmt.setint(1, i + 1); pstmt.setstring(2, lastnames[i]); pstmt.setstring(3, firstnames[i]); pstmt.setstring(4, s[i]); pstmt.setstring(5, phonenumbers[i]); // Add row to the batch. pstmt.addbatch(); // Integer array to hold the results of inserting // the batch. Will contain an entry for each row, // indicating success or failure. int[] batchresults = null; try // Batch is ready, execute it to insert the data batchresults = pstmt.executebatch(); catch (BatchUpdateException e) // We expect an exception here, since one of the HP Vertica Analytic Database (7.1.x) Page 225 of 401

226 // inserted phone numbers is too wide for its column. All of the // rest of the rows will be inserted. System.out.println("Error message: " + e.getmessage()); // Batch results isn't set due to exception, but you // can get it from the exception object. // // In your own code, you shouldn't assume the a batch // exception occurred, since exceptions can be thrown // by the server for a variety of reasons. batchresults = e.getupdatecounts(); // You should also be prepared to catch SQLExceptions in your own // application code, to handle dropped connections and other general // problems. // Commit the transaction conn.commit(); // Print the array holding the results of the batch insertions. System.out.println("Return value from inserting batch: " + Arrays.toString(batchResults)); // Print the resulting table. ResultSet rs = null; rs = stmt.executequery("select CustID, First_Name, " + "Last_Name FROM customers ORDER BY CustID"); while (rs.next()) System.out.println(rs.getInt(1) + " - " + rs.getstring(2).trim() + " " + rs.getstring(3).trim()); // Cleanup conn.close(); catch (SQLException e) e.printstacktrace(); Running the above example produces the following output on the console: Error message: [Vertica][VJDBC](100172) One or more rows were rejected by the server.return value from inserting batch: [1, 1, -3, 1, 1] 1 - Anna Allen 2 - Bill Brown 4 - Don Dodd 5 - Eric Estavez Notice that the third row failed to insert because its phone number is too long for the Phone_Number column. All of the rest of the rows in the batch (including those after the error) were correctly inserted. Note: It is more efficient for you to ensure that the data you are inserting is the correct data HP Vertica Analytic Database (7.1.x) Page 226 of 401

227 type and width for the table column you are inserting it into than to handle exceptions after the fact. Rolling Back Batch Loads on the Server Batch loads always insert all of their data, even if one or more rows is rejected. Only the rows that caused errors in a batch are not loaded. When the database connection's AutoCommit property is true, batches automatically commit their transactions when they complete, so once the batch finishes loading, the data is committed. In some cases, you may want all of the data in a batch to be successfully inserted none of the data should be committed if an error occurs. The best way to accomplish this is to turn off the database connection's AutoCommit property to prevent batches from automatically committing themselves. Then, if a batch encounters an error, you can roll back the transaction after catching the BatchUpdateException caused by the insertion error. The following example demonstrates performing a rollback if any error occurs when loading a batch. import java.sql.*; import java.util.arrays; import java.util.properties; public class RollbackBatchOnError public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); // Disable auto-commit. This will allow you to roll back a // a batch load if there is an error. conn.setautocommit(false); // establish connection and make a table for the data. Statement stmt = conn.createstatement(); // Drop table and recreate. stmt.execute("drop TABLE IF EXISTS customers CASCADE"); stmt.execute("create TABLE customers (CustID int, Last_Name" + " char(50), First_Name char(50), char(50), " + "Phone_Number char(12))"); // Some dummy data to insert. The one row won't insert because // the phone number is too long for the phone column. String[] firstnames = new String[] "Anna", "Bill", "Cindy", "Don", "Eric" ; String[] lastnames = new String[] "Allen", "Brown", "Chu", "Dodd", "Estavez" ; String[] s = new String[] "[email protected]", "[email protected]", "[email protected]", "[email protected]", "[email protected]" ; String[] phonenumbers = new String[] " ", " ", " ", " ", HP Vertica Analytic Database (7.1.x) Page 227 of 401

228 " " ; // Create the prepared statement PreparedStatement pstmt = conn.preparestatement( "INSERT INTO customers (CustID, Last_Name, " + "First_Name, , Phone_Number) "+ "VALUES(?,?,?,?,?)"); // Add rows to a batch in a loop. Each iteration adds a // new row. for (int i = 0; i < firstnames.length; i++) // Add each parameter to the row. pstmt.setint(1, i + 1); pstmt.setstring(2, lastnames[i]); pstmt.setstring(3, firstnames[i]); pstmt.setstring(4, s[i]); pstmt.setstring(5, phonenumbers[i]); // Add row to the batch. pstmt.addbatch(); // Integer array to hold the results of inserting // the batch. Will contain an entry for each row, // indicating success or failure. int[] batchresults = null; try // Batch is ready, execute it to insert the data batchresults = pstmt.executebatch(); // If we reach here, we inserted the batch without errors. // Commit it. System.out.println("Batch insert successful. Committing."); conn.commit(); catch (BatchUpdateException e) System.out.println("Error message: " + e.getmessage()); // Batch results isn't set due to exception, but you // can get it from the exception object. batchresults = e.getupdatecounts(); // Roll back the batch transaction. System.out.println("Rolling back batch insertion"); conn.rollback(); catch (SQLException e) // General SQL errors, such as connection issues, throw // SQLExceptions. Your application should do something more // than just print a stack trace, e.printstacktrace(); System.out.println("Return value from inserting batch: " + Arrays.toString(batchResults)); System.out.println("Customers table contains:"); // Print the resulting table. ResultSet rs = null; rs = stmt.executequery("select CustID, First_Name, " + "Last_Name FROM customers ORDER BY CustID"); while (rs.next()) System.out.println(rs.getInt(1) + " - " + rs.getstring(2).trim() + " " + rs.getstring(3).trim()); HP Vertica Analytic Database (7.1.x) Page 228 of 401

229 // Cleanup conn.close(); catch (SQLException e) e.printstacktrace(); Running the above example prints the following on the system console: Error message: [Vertica][VJDBC](100172) One or more rows were rejected by the server.rolling back batch insertion Return value from inserting batch: [1, 1, -3, 1, 1] Customers table contains: The return values indicate whether each rows was successfully inserted. The value 1 means the row inserted without any issues, and a -3 indicates the row failed to insert. The customers table is empty since the batch insert was rolled back due to the error caused by the third column. Bulk Loading Using the COPY Statement One of the fastest ways to load large amounts of data into HP Vertica at once (bulk loading) is to use the COPY statement. This statement loads data from a file stored on an HP Vertica host (or in a data stream) into a table in the database. You can pass the COPY statement parameters that define the format of the data in the file, how the data is to be transformed as it is loaded, how to handle errors, and how the data should be loaded. See the COPY documentation in the SQL Reference Manual for details. One parameter that is particularly important is the DIRECT option, which tells COPY to load the data directly into ROS rather than going through the WOS. You should use this option when you are loading large files (over 100MB) into the database. Without this option, your load may fill the WOS and overflow into ROS, requiring the Tuple Mover to perform a Moveout on the data in the WOS. It is more efficient to directly load into ROS and avoid forcing a moveout. Only a superuser can use the COPY statement to copy a file stored on a host, so you must connect to the database using a superuser account. If you want to have a non-superuser user bulkload data, you can use COPY to load from a stream on the host (such as STDIN) rather than a file or stream data from the client (see Streaming Data Via JDBC). You can also perform a standard batch insert using a prepared statement, which uses the COPY statement in the background to load the data. The following example demonstrates using the COPY statement through the JDBC to load a file name customers.txt into a new database table. This file must be stored on the database host to which your application connects (in this example, a host named VerticaHost). Since the customers.txt file used in the example is very large, this example uses the DIRECT option to bypass WOS and load directly into ROS. HP Vertica Analytic Database (7.1.x) Page 229 of 401

230 import java.sql.*; import java.util.properties; import com.vertica.jdbc.*; public class COPYFromFile public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "ExampleAdmin"); // Must be superuser myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb",myprop); // Disable AutoCommit conn.setautocommit(false); Statement stmt = conn.createstatement(); // Create a table to hold data. stmt.execute("drop TABLE IF EXISTS customers;"); stmt.execute("create TABLE IF NOT EXISTS customers (Last_Name char(50) " + "NOT NULL, First_Name char(50), char(50), " + "Phone_Number char(15))"); // Use the COPY command to load data. Load directly into ROS, since // this load could be over 100MB. Use ENFORCELENGTH to reject // strings too wide for their columns. boolean result = stmt.execute("copy customers FROM " + " '/data/customers.txt' DIRECT ENFORCELENGTH"); // Determine if execution returned a count value, or a full result // set. if (result) System.out.println("Got result set"); else // Count will usually return the count of rows inserted. System.out.println("Got count"); int rowcount = stmt.getupdatecount(); System.out.println("Number of accepted rows = " + rowcount); // Commit the data load conn.commit(); catch (SQLException e) System.out.print("Error: "); System.out.println(e.toString()); The example prints the following out to the system console when run (assuming that the customers.txt file contained two million valid rows): Number of accepted rows = Streaming Data Via JDBC There are two options to stream data from a file on the client to your HP Vertica database: HP Vertica Analytic Database (7.1.x) Page 230 of 401

231 Use the VerticaCopyStream class to stream data in an object-oriented manner Execute a COPY LOCAL SQL statement to stream the data The topics in this section explain how to use these options. Using VerticaCopyStream The VerticaCopyStream class lets you stream data from the client system to an HP Vertica database. It lets you use the SQL COPY statement directly without having to copy the data to a host in the database cluster first. Using the COPY command to load data from the host requires superuser privileges to be able to access the host's filesystem. The COPY statement used to load data from a stream does not require superuser privileges so your client can connect using any user account that has INSERT privileges on the table that will receive the data. To copy streams into the database: 1. Disable the database connections AutoCommit connection parameter. 2. Instantiate a VerticaCopyStreamObject, passing it at least the database connection objects and a string containing a COPY statement to load the data. This statement must copy data from the STDIN into your table. You can use whatever parameters are appropriate for your data load. Note: The VerticaCopyStreamObject constructor optionally takes a single InputStream object, or a List of InputStream objects. This option lets you pre-populate the list of streams to be copied into the database. 3. Call VerticaCopyStreamObject.start() to start the COPY statement and begin streaming the data in any streams you have already added to the VerticaCopyStreamObject. 4. Call VerticaCopyStreamObject.addStream() to add additional streams to the list of streams to send to the database. You can then call VerticaCopyStreamObject.execute() to stream them to the server. 5. Optionally, call VerticaCopyStreamObject.getRejects() to get a list of rejected rows from the last.execute() call. The list of rejects is reset by each call to.execute() or.finish(). Note: If you used either the REJECTED DATA or EXCEPTIONS options in the COPY statement you passed to VerticaCopyStreamObject the object in step 2,.getRejects() returns an empty list. You can only use one method of tracking the rejected rows at a time. 6. When you are finished adding streams, call VerticaCopyStreamObject.finish() to send any remaining streams to the database and close the COPY statement. 7. Call Connection.commit() to commit the loaded data. HP Vertica Analytic Database (7.1.x) Page 231 of 401

232 Getting Rejected Rows The VerticaCopyStreamObject.getRejects() method returns a List containing the row numbers of rows that were rejected after the previous.execute() method call. Each call to.execute() clears the list of rejected rows, so you need to call.getrejects() after each call to.execute(). Since.start() and.finish() also call.execute() to send any pending streams to the server, you should also call.getrejects() after these methods as well. The following example demonstrates loading the content of five text files stored on the client system into a table. import java.io.file; import java.io.fileinputstream; import java.sql.connection; import java.sql.drivermanager; import java.sql.statement; import java.util.iterator; import java.util.list; import java.util.properties; import com.vertica.jdbc.verticaconnection; import com.vertica.jdbc.verticacopystream; public class CopyMultipleStreamsExample public static void main(string[] args) // Note: If running on Java 5, you need to call Class.forName // to manually load the JDBC driver. // Set up the properties of the connection Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); // Must be superuser myprop.put("password", "password123"); // When performing bulk loads, you should always disable the // connection's AutoCommit property to ensure the loads happen as // efficiently as possible by reusing the same COPY command and // transaction. myprop.put("autocommit", "false"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb", myprop); Statement stmt = conn.createstatement(); // Create a table to receive the data stmt.execute("drop TABLE IF EXISTS customers"); stmt.execute("create TABLE customers (Last_Name char(50), " + "First_Name char(50), char(50), " + "Phone_Number char(15))"); // Prepare the query to insert from a stream. This query must use // the COPY statement to load data from STDIN. Unlike copying from // a file on the host, you do not need superuser privileges to // copy a stream. All your user account needs is INSERT privileges // on the target table. String copyquery = "COPY customers FROM STDIN " + "DELIMITER ' ' DIRECT ENFORCELENGTH"; // Create an instance of the stream class. Pass in the HP Vertica Analytic Database (7.1.x) Page 232 of 401

233 // connection and the query string. VerticaCopyStream stream = new VerticaCopyStream( (VerticaConnection) conn, copyquery); // Keep running count of the number of rejects int totalrejects = 0; // start() starts the stream process, and opens the COPY command. stream.start(); // If you added streams to VerticaCopyStream before calling start(), // You should check for rejects here (see below). The start() method // calls execute() to send any pre-queued streams to the server // once the COPY statement has been created. // Simple for loop to load 5 text files named customers-1.txt to // customers-5.txt for (int loadnum = 1; loadnum <= 5; loadnum++) // Prepare the input file stream. Read from a local file. String filename = "C:\\Data\\customers-" + loadnum + ".txt"; System.out.println("\n\nLoading file: " + filename); File inputfile = new File(filename); FileInputStream inputstream = new FileInputStream(inputFile); // Add stream to the VerticaCopyStream stream.addstream(inputstream); // call execute() to load the newly added stream. You could // add many streams and call execute once to load them all. // Which method you choose depends mainly on whether you want // the ability to check the number of rejections as the load // progresses so you can stop if the number of rejects gets too // high. Also, high numbers of InputStreams could create a // resource issue on your client system. stream.execute(); // Show any rejects from this execution of the stream load // getrejects() returns a List containing the // row numbers of rejected rows. List<Long> rejects = stream.getrejects(); // The size of the list gives you the number of rejected rows. int numrejects = rejects.size(); totalrejects += numrejects; System.out.println("Number of rows rejected in load #" + loadnum + ": " + numrejects); // List all of the rows that were rejected. Iterator<Long> rejit = rejects.iterator(); long linecount = 0; while (rejit.hasnext()) System.out.print("Rejected row #" + ++linecount); System.out.println(" is row " + rejit.next()); // Finish closes the COPY command. It returns the number of // rows inserted. long results = stream.finish(); HP Vertica Analytic Database (7.1.x) Page 233 of 401

234 System.out.println("Finish returned " + results); // If you added any streams that hadn't been executed(), // you should also check for rejects here, since finish() // calls execute() to // You can also get the number of rows inserted using // getrowcount(). System.out.println("Number of rows accepted: " + stream.getrowcount()); System.out.println("Total number of rows rejected: " + totalrejects); // Commit the loaded data conn.commit(); catch (Exception e) e.printstacktrace(); Running the above example on some sample data results in the following output: Loading file: C:\Data\customers-1.txtNumber of rows rejected in load #1: 3 Rejected row #1 is row 3 Rejected row #2 is row 7 Rejected row #3 is row 51 Loading file: C:\Data\customers-2.txt Number of rows rejected in load #2: 5Rejected row #1 is row 4143 Rejected row #2 is row 6132 Rejected row #3 is row 9998 Rejected row #4 is row Rejected row #5 is row Loading file: C:\Data\customers-3.txt Number of rows rejected in load #3: 9 Rejected row #1 is row Rejected row #2 is row Rejected row #3 is row Rejected row #4 is row Rejected row #5 is row Rejected row #6 is row Rejected row #7 is row Rejected row #8 is row Rejected row #9 is row Loading file: C:\Data\customers-4.txt Number of rows rejected in load #4: 8 Rejected row #1 is row Rejected row #2 is row Rejected row #3 is row Rejected row #4 is row Rejected row #5 is row Rejected row #6 is row Rejected row #7 is row Rejected row #8 is row Loading file: C:\Data\customers-5.txt Number of rows rejected in load #5: 1 HP Vertica Analytic Database (7.1.x) Page 234 of 401

235 Rejected row #1 is row Finish returned Number of rows accepted: Total number of rows rejected: 26 Note: The above example shows a simple load process that targets one node in the HP Vertica cluster. It is more efficient to simultaneously load multiple streams to multiple database nodes. Doing so greatly improves performance because it spreads the processing for the load across the cluster. Using COPY LOCAL with JDBC To use COPY LOCAL with JDBC, just execute a COPY LOCAL statement with the path to the source file on the client system. This method is simpler than using the VerticaCopyStream class. However, you may prefer using VerticaCopyStream if you have many files to copy to the database or if your data comes from a source other than a file (streamed over a network connection, for example). The following example code demonstrates using COPY LOCAL to copy a file from the client to the database. It is the same as the code shown in Bulk Loading Using the COPY Statement, except for the use of the LOCAL option in the COPY statement, and the path to the data file is on the client system, rather than on the server. Note: The exceptions/rejections files are created on the client machine when the exceptions and rejected data modifiers are specified on the copy local command. Specify a local path and filename for these modifiers when executing a COPY LOCAL query from the driver. import java.sql.*; import java.util.properties; public class COPYLocal public static void main(string[] args) // Note: If using Java 5, you must call Class.forName to load the // JDBC driver. Properties myprop = new Properties(); myprop.put("user", "ExampleUser"); // Do not need to superuser myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/exampledb",myprop); // Disable AutoCommit conn.setautocommit(false); Statement stmt = conn.createstatement(); // Create a table to hold data. stmt.execute("drop TABLE IF EXISTS customers;"); stmt.execute("create TABLE IF NOT EXISTS customers (Last_Name char(50) " + "NOT NULL, First_Name char(50), char(50), " + "Phone_Number char(15))"); HP Vertica Analytic Database (7.1.x) Page 235 of 401

236 // Use the COPY command to load data. Load directly into ROS, since // this load could be over 100MB. Use ENFORCELENGTH to reject // strings too wide for their columns. boolean result = stmt.execute("copy customers FROM LOCAL " + " 'C:\\Data\\customers.txt' DIRECT ENFORCELENGTH"); // Determine if execution returned a count value, or a full result // set. if (result) System.out.println("Got result set"); else // Count will usually return the count of rows inserted. System.out.println("Got count"); int rowcount = stmt.getupdatecount(); System.out.println("Number of accepted rows = " + rowcount); conn.close(); catch (SQLException e) System.out.print("Error: "); System.out.println(e.toString()); The result of running this code appears below. In this case, the customers.txt file contains rows, seven of which get rejected because they contain data too wide to fit into their database columns. Got countnumber of accepted rows = 9993 HP Vertica Analytic Database (7.1.x) Page 236 of 401

237 Handling Errors When the HP Vertica JDBC driver encounters an error, it throws a SQLException or one of its subclasses. The specific subclass it throws depends on the type of error that has occurred. Most of the JDBC method calls can result in several different types of errors, in response to which the JDBC driver throws a specific SQLException subclass. Your client application can choose how to react to the error based on the specific exception that the JDBC driver threw. Note: The specific SQLException subclasses were introduced in the JDBC 4.0 standard. If your client application runs in a Java 5 JVM, it will use the older JDBC 3.0-compliant driver which lacks these subclasses. In that case, all errors throw a SQLException. The hierarchy of SQLException subclasses is arranged to help your client application determine what actions it can take in response to an error condition. For example: The JDBC driver throws SQLTransientException subclasses when the cause of the error may be a temporary condition, such as a timeout error (SQLTimeoutException) or a connection issue (SQLTransientConnectionIssue). Your client application can choose to retry the operation without making any sort of attempt to remedy the error, since it may not reoccur. The JDBC driver throws SQLNonTransientException subclasses when the client needs to take some action before it could retry the operation. For example, executing a statement with a SQL syntax error results in the JDBC driver throwing the a SQLSyntaxErrorException (a subclass of SQLNonTransientException). Often, your client application just has to report these errors back to the user and have him or her resolve them. For example, if the user supplied your application with a SQL statement that triggered a SQLSyntaxErrorException, it could prompt the user to fix the SQL error. See Vertica Analytic Database SQLState Mapping to Java Exception Classes for a list Java exceptions thrown by the JDBC driver. Vertica Analytic Database SQLState Mapping to Java Exception Classes SQLSTATE Class or Value Description Java Exception Class Class 00 Successful Completion SQLException Class 01 Warning SQLWarning Class 02 No Data SQLException Class 03 SQL Statement Not Yet Complete SQLException HP Vertica Analytic Database (7.1.x) Page 237 of 401

238 SQLSTATE Class or Value Description Java Exception Class Class 08 Class 09 Client Connection Exception Triggered Action Exception SQLNonTransientConnectionException SQLException Class 0A Feature Not Supported SQLFeatureNotSupportedException Class 0B Invalid Transaction Initiation SQLException Class 0F Locator Exception SQLException Class 0L Invalid Grantor SQLException Class 0P Invalid Role Specification SQLException Class 21 Cardinality Violation SQLException Class 22 Data Exception SQLDataException 22V21 Class 23 ERRCODE_INVALID_ EPOCH Integrity Constraint Violation SQLNonTransientException SQLIntegrityConstraintViolationException Class 24 Invalid Cursor State SQLException Class 25 Invalid Transaction State SQLTransactionRollbackException Class 26 Class 27 Class 28 Class 2B Class 2D Invalid SQL Statement Name Triggered Data Change Violation Invalid Authorization Specification Dependent Privilege Descriptors Still Exist Invalid Transaction Termination SQLException SQLException SQLInvalidAuthorizationException SQLDataException SQLException Class 2F SQL Routine Exception SQLException Class 34 Invalid Cursor Name SQLException HP Vertica Analytic Database (7.1.x) Page 238 of 401

239 SQLSTATE Class or Value Description Java Exception Class Class 38 Class 39 External Routine Exception External Routine Invocation Exception SQLException SQLException Class 3B Savepoint Exception SQLException Class 3D Invalid Catalog Name SQLException Class 3F Invalid Schema Name SQLException Class 40 Transaction Rollback SQLTransactionRollbackException Class 42 Class 44 Syntax Error or Access Rule Violation WITH CHECK OPTION Violation SQLSyntaxErrorException SQLException Class 53 Insufficient Resources SQLTransientException ERRCODE_TOO_ MANY_CONNECTIONS SQLNonTransientConnectionException Class 54 Program Limit Exceeded SQLNonTransientException Class 55 55V03 Object Not In Prerequisite State ERRCODE_LOCK_ NOT_AVAILABLE SQLNonTransientException SQLTransactionRollbackException Class 57 Operator Intervention SQLTransientException 57V01 57V02 57V03 ERRCODE_ADMIN_ SHUTDOWN ERRCODE_CRASH_ SHUTDOWN ERRCODE_CANNOT_ CONNECT_NOW SQLNonTransientConnectionException SQLNonTransientConnectionException SQLNonTransientConnectionException Class 58 System Error SQLException Class V1 Vertica-specific multinode errors class SQLException HP Vertica Analytic Database (7.1.x) Page 239 of 401

240 SQLSTATE Class or Value Description Java Exception Class Class V2 V2000 Vertica-specific miscellaneous errors class ERRCODE_AUTH_ FAILED SQLException SQLInvalidAuthorizationException Class VC Configuration File Error SQLNonTransientException Class VD DB Designer errors SQLNonTransientException Class VP User procedure errors SQLNonTransientException Class VX Internal Error SQLException Error Handling Example The following example code demonstrates catching two subclasses of SQLException. In this example, the program just prints out different error messages. Your own client application could respond to these errors in different ways. import java.sql.*; import java.util.properties; // Demonstrate catching specific SQLException subclasses. public class ExceptionClassExample public static void main(string[] args) Properties myprop = new Properties(); myprop.put("user", "myuser"); myprop.put("password", "password123"); Connection conn; try conn = DriverManager.getConnection( "jdbc:vertica://verticahost:5433/vmart", myprop); System.out.println("Connected!"); // Array of statements that we want to run. Some contain errors. String[] statements = new String[] "DROP TABLE IF EXISTS t;", "CREATE TABLE t (id INTEGER, name VARCHAR(50));", "INSERT INTO t (id, name) VALUES (1, 'Alice');", "INSERT INTO t (id, name) VALUES ('Bob', 2)", "DRUP TABLE t CASCADE;", "DROP TABLE t CASCADE;", "CREATE TABLE nonexistentschema.t (id INTEGER, name VARCHAR(50));"; Statement stmt = conn.createstatement(); // Loop through the strings, executing each. for (String statement : statements ) try System.out.println("Executing statement: '" + statement + "'"); HP Vertica Analytic Database (7.1.x) Page 240 of 401

241 stmt.execute(statement); System.out.println("Success!"); // Handle some specific types of SQL Exceptions error."); error."); // Syntax errors in statements are handled here. catch (SQLSyntaxErrorException e) System.out.println("Statement '" + statement + "' has a syntax System.out.println(" SQLSTATE = " + e.getsqlstate()); System.out.println(" Error code: " + e.geterrorcode() + " Error message: " + e.getmessage()); // SQLDataException is thrown for various data-releted errors, such // as trying to put the wrong data type in a column. catch (SQLDataException e) System.out.println("Statement '" + statement + "' caused a data System.out.println(" SQLSTATE = " + e.getsqlstate()); System.out.println(" Error code: " + e.geterrorcode() + " Error message: " + e.getmessage()); // Catch-all for other exceptions. catch (SQLException e) System.out.println("Statement '" + statement + "' caused a " + e.getclass().getcanonicalname() + " exception."); System.out.println(" SQLSTATE = " + e.getsqlstate()); System.out.println(" Error code: " + e.geterrorcode() + " Error message: " + e.getmessage()); e.getclass().getcanonicalname(); //e.printstacktrace(); conn.close(); // This catches exceptions caused by a bad connection. catch (SQLException e) e.printstacktrace(); Routing JDBC Queries Directly to a Single Node The JDBC driver has the ability to route queries directly to a single node using a special connection called a Routable Connection. This feature is ideal for high-volume "short" requests that return a small number of results that all exist on a single node. The common scenario for using this feature is to do high-volume lookups on data that is identified with a unique key. Routable queries typically provide lower latency and use less system resources than distributed queries. However, the data being queried must be segmented in such a way that the JDBC client can determine on which node the data resides. HP Vertica Typical Analytic Query Typical analytic queries require dense computation on data across all nodes in the cluster and benefit from having all nodes involved in the planning and execution of the queries. HP Vertica Analytic Database (7.1.x) Page 241 of 401

242 HP Vertica Routable Query API Query For high-volume queries that return a single or a few rows of data, it is more efficient to execute the query on the single node that contains the data. To effectively route a request to a single node, the client must determine the specific node on which the data resides. For the client to be able to determine the correct node, the table must segmented by one or more columns. For example, if you segment a table on a Primary Key (PK) column, then the client can determine on which node the data resides based on the Primary Key and directly connect to that node to quickly fulfill the request. The Routable Query API provides two classes for performing routable queries; VerticaRoutableExecutor and VGet. VerticaRoutableExecutor provides a more expressive SQLbased API while VGet provides a more structured API for programmatic access. HP Vertica Analytic Database (7.1.x) Page 242 of 401

243 The VerticaRoutableExecutor class, available starting in Release 7.1 SP1, allows you to use traditional SQL with a reduced feature set to query data on a single node. Note that the client and server must be at Release 7.1 SP1 to use the VerticaRoutableExecutor. For joins, the table must be joined on a key column that exists in each table you are joining, and the tables must be segmented on that key, except for unsegmented tables, which can always be joined (since all the data in an unsegmented table is available on all nodes). The VGet class does not use traditional SQL syntax. Instead, it uses a data structure that you build by defining predicates and predicate expressions and outputs and output expressions. This class is ideal for doing Key/Value type lookups on single tables. The data structure used for querying the table must provide a predicate for each segmented column defined in the projection for the table. You must provide, at a minimum, a predicate with a constant value for each segmented column. For example, an id with a value of if the table is segmented only on the id column. You can also specify additional predicates for the other, non-segmented, columns in the table. Predicates act like an SQL WHERE clause and multiple predicates/predicate expressions apply together with an SQL AND modifier. Predicates must be defined with a constant value. Predicate expressions can be used to refine the query and can contain any arbitrary SQL expressions (such as less than, greater than, etc.) for any of the non-segmented columns in the table. Java doc for all classes and methods in the JDBC Driver is available in the HP Vertica JDBC Java doc. Note: The JDBC Routable Query API is read-only and requires JDK 1.6 or greater. See Also Creating Tables and Projections for use with the Routable Query API Creating a Connection for Routable Queries Defining the Query for Routable Queries Using the VGet Class Defining the Query for Routable Queries using the VerticaRoutableExecutor Class Routable Query Performance and Troubleshooting Creating Tables and Projections for use with the Routable Query API For routable queries, the client needs to determine the appropriate node to get the data. The client does this by comparing all of the projections available for the table and determining the best projection to use to find the single node that contains data. You must create a projection segmented by the key column(s) on at least one table to take full advantage of the Routable Query API. Other HP Vertica Analytic Database (7.1.x) Page 243 of 401

244 tables which join to this table must either have an unsegmented projection, or a projection segmented as described below. Note: Tables must be segmented by hash for Routable Queries. See Hash-Segmentation- Clause. Other segmentation types are not supported. Creating Tables for use with Routable Queries To create a table that can be used with the Routable Query API, segment (by hash) the table on a uniformly distributed column. Typically, you segment on a primary key. For faster lookups, sort the projection on the same columns on which you segmented. For example, to create a table that is well suited to Routable Queries: CREATE TABLE users ( id INT NOT NULL PRIMARY KEY, username VARCHAR(32), VARCHAR(64), business_unit VARCHAR(16)) ORDER BY id SEGMENTED BY HASH(id) ALL NODES; This table is segmented based on the id column (and ordered by id to make lookups faster). To build a query for this table using the Routable Query API, you only need to provide a single predicate for the id column which returns a single row when queried. However, if you were to add multiple columns to the segmentation clause, such as this table: CREATE TABLE users2 ( id INT NOT NULL PRIMARY KEY, username VARCHAR(32), VARCHAR(64), business_unit VARCHAR(16)) ORDER BY id, business_unit SEGMENTED BY HASH(id, business_unit) ALL NODES; Then you would need to provide two predicates when querying the users2 table, since the segmentation clause uses both the id and the business_unit columns. However, if you know both id and business_unit when you perform the queries, then it is beneficial to segment on both columns, as it makes it easier for the client to determine that this projection is the best projection to use to determine the correct node. Designing Tables for Single-node JOINs If you plan to use the VerticaRoutableExecutor class and join tables during routable queries, then you must segment all tables being joined by the same segmentation key. Typically this key is a Primary/Foreign key on all the tables being joined. For example, the customer_key may be the primary key in a customers dimension table, and the same key is a foreign key in a sales fact table. HP Vertica Analytic Database (7.1.x) Page 244 of 401

245 Projections for a VerticaRoutableExecutor query using these tables must be segmented by hash on the customer key in each table. If you want to join with small dimension tables, such as date dimensions, then it may be appropriate to make those tables unsegmented so that the date_dimension data exists on all nodes. It is important to note that when joining unsegmented tables, you still must specify a segmented table in the createroutableexecutor() call. Verifying Existing Projections for Tables If you have existing tables that are already segmented by hash (for example, on an ID column), then you can determine what predicates are needed to query the table by using the select get_table_ projections('tablename') command to view the projections associated with the table. The example table displays the following when select get_table_projections('users') is run: Projection Name: [Segmented] [Seg Cols] [# of Buddies] [Buddy Projections] [Safe] [UptoDate] [Stats] public.users_b1 [Segmented: Yes] [Seg Cols: "public.users.id"] [K: 1] [public.users_b0] [Safe: Yes] [UptoDate: Yes] [Stats: RowCounts] public.users_b0 [Segmented: Yes] [Seg Cols: "public.users.id"] [K: 1] [public.users_b1] [Safe: Yes] [UptoDate: Yes] [Stats: RowCounts] Note that for each projection, only the "public.users.id" column is specified,meaning you need to provide a predicate for this column when you build your query. If the table was segmented on multiple columns, for example id and business_unit, then you would need to provide both columns as predicates to the routable query. Creating a Connection for Routable Queries The JDBC Routable Query API provides the VerticaRoutableConnection interface to connect to a cluster and allow for Routable Queries. This interface provides advanced routing capabilities beyond those of a normal VerticaConnection. The VerticaRoutableConnection provides access to the VerticaRoutableExecutor and VGet classes. See Defining the Query for Routable Queries using the VerticaRoutableExecutor Class and Defining the Query for Routable Queries Using the VGet Class respectively. You enable access to this class by setting the EnableRoutableQueries JDBC connection property to true. The VerticaRoutableConnection maintains an internal pool of connections and a cache of table metadata that is shared by all VerticaRoutableExecutor/VGet objects that are produced by the connection's createroutableexecutor()/prepareget() method. It is also a fully-fledged JDBC connection on its own and supports all the functionality that a VerticaConnection supports. When this connection is closed, all pooled connections managed by this VerticaRoutableConnection and all child objects are closed too. The connection pool and metadata is only used by child Routable Query operations. HP Vertica Analytic Database (7.1.x) Page 245 of 401

246 Example: You can create the connection using a JDBC data source: com.vertica.jdbc.datasource jdbcsettings = new com.vertica.jdbc.datasource(); jdbcsettings.setdatabase("exampledb"); jdbcsettings.sethost("doc1.verticacorp.com"); jdbcsettings.setuserid("dbadmin"); jdbcsettings.setpassword("password"); jdbcsettings.setenableroutablequeries(true); jdbcsettings.setport((short) 5433); VerticaRoutableConnection conn; conn = (VerticaRoutableConnection)jdbcSettings.getConnection(); You can also create the connection using a connection string and the DriverManager.getConnection() method: String connectionstring = "jdbc:vertica://doc.verticacorp.com:5433/exampledb?user=dbadmin&password=& EnableRoutableQueries=true"; VerticaRoutableConnection conn = (VerticaRoutableConnection) DriverManager.getConnection (connectionstring); Both methods result in a conn connection object that is identical. Note: Avoid opening many VerticaRoutableConnection connections because this connection maintains its own private pool of connections which are not shared with other connections. Instead, your application should use a single connection and issue multiple queries through that connection. In addition to the setenableroutablequeries property that the Routable Query API adds to the HP Vertica JDBC connection class, the API also adds additional properties. The complete list is below. EnableRoutableQueries: Enables Routable Query lookup capability. Default is false. FailOnMultiNodePlans: If the plan requires more than one node, and FailOnMultiNodePlans is true, then the query fails. If it is set to false then a warning is generated and the query continues. However, latency is greatly increased as the Routable Query must first determine the data is on multiple nodes,then a normal query is run using traditional (all node) execution and execution. Defaults to true. Note that this failure cannot occur on simple calls using only predicates and constant values. MetadataCacheLifetime: The time in seconds to keep projection metadata. The API caches metadata about the projection used for the query (such as projections). The cache is used on subsequent queries to reduce response time. The default is 300 seconds. HP Vertica Analytic Database (7.1.x) Page 246 of 401

247 MaxPooledConnections: Cluster-wide maximum number of connections to keep in the VerticaRoutableConnection s internal pool. Default 20. MaxPooledConnectionsPerNode: Per-node maximum number of connections to keep in the VerticaRoutableConnection s internal pool. Default 5. Defining the Query for Routable Queries using the VerticaRoutableExecutor Class The VerticaRoutableExecutor class is used to access table data directly from a single node. VerticaRoutableExecutor directly queries HP Vertica only the node that has all the data needed for the query, avoiding the distributed planning and execution costs associated with a normal HP Vertica execution. VerticaRoutableExecutor is used if you need to join tables or use a group by clausei, as these operations are not possible using VGet. When using the VerticaRoutableExecutor class, you must follow these rules: If joining tables, all tables being joined must be segmented (by hash) on the same set of columns referenced in the join predicate, unless the table being joined is unsegmented. When using multiple conditions in WHERE clauses, the WHERE clause must use AND between the conditions. OR's in the WHERE clause cause the query to degenerate to a multi-node plan. OR, IN list, or range conditions on columns outside of the join condition are acceptable if the data exists on the same node. You can only execute a single statement per request. "Chained" SQL statements are not permitted. Your query may be used in a driver-generated subquery to help determine if the query can be executed on a single node, Therefore, you cannot include the semi-colon at the end of the statement and you cannot include SQL comments (using -- ), as these would cause the drivergenerated query to fail. You create a VerticaRoutableExecutor by calling createroutableexecutor(schema, table); on a connection object. If schema is set to null then the search path is used to fine the table. VerticaRoutableExecutor Methods VerticaRoutableExecutor has the following methods: execute(query string, [ column, value Map ]) - Runs the query. Accepts as input the query to be executed, and either: The column and value when the lookup is being done on just a single value. For example: String column = "customer_key"; Integer value = 1; ResultSet rs = q.execute(query, column, value) HP Vertica Analytic Database (7.1.x) Page 247 of 401

248 A Java map of the column names and corresponding values if the lookup is being done on one or more columns. For example: ResultSet rs = q.execute(query, map);. The table must have at least one projection segmented by a set of columns exactly matching the columns in the map. Note that each column defined in the map must have only one value. You cannot include more than one value for the same column. For example: Map<String, Object> map = new HashMap<String, Object>(); map.put("customer_key", 1); map.put("another_key", 42); ResultSet rs = q.execute(query, map); The query being executed uses regular SQL. The SQL must meet the rules of the VerticaRoutableExecutor Class. For example, you can add limits and sorts, or use aggregate functions provided the data exists on a single node. Important: The JDBC client uses the column/value or map arguments to determine on which node to execute the query. You must make sure that the content of the query uses the same values that you provide in the column/value or map arguments. Note: The following data types cannot be used as column values. Additionally, if a table is segmented on any columns with the following data types then the table cannot be queried using the Routable Query API: interval timetz timsestamptz Note: The driver does not verify the syntax of the query before it sends it to the server. If your expression is incorrect then the query fails. close() - Closes this VerticaRoutableExecutor by releasing resources used by this VerticaRoutableExecutor. It does not close the parent JDBC connection to HP Vertica. getwarnings() - Retrieves the first warning reported by calls on this VerticaRoutableExecutor. Additional warnings are chained and can be accessed with the JDBC getnextwarning() method. Example Query using VerticaRoutableExecutor The following example details how to use VerticaRoutableExecutor to execute a query using both a JOIN clause and an aggregate function with a GROUP BY claue. The example also details how to create a customer and sales tables, and how to segment the tables so they can be joined using the VerticaRoutableExecutor class. This example also uses the date_dimension table from the VMart schema to illustrate how you can also join data on unsegmented tables. HP Vertica Analytic Database (7.1.x) Page 248 of 401

249 1. Create a table for customer details, and then create the projections which segment on the customer_key. CREATE TABLE customers (customer_key INT, customer_name VARCHAR(128), customer_ VARCHAR(128)); CREATE PROJECTION cust_proj_b0 AS (SELECT * FROM customers) SEGMENTED BY HASH (customer_key) ALL NODES; CREATE PROJECTION cust_proj_b1 AS (SELECT * FROM customers) SEGMENTED BY HASH (customer_key) ALL NODES OFFSET 1; CREATE PROJECTION cust_proj_b2 AS (SELECT * FROM customers) SEGMENTED BY HASH (customer_key) ALL NODES OFFSET 2; select start_refresh(); 2. Create a sales table, then create the projections which segment on the customer_key. Since both the customer and sales tables are segmented on the same key, they are able to be joined with the VerticaRoutableExecutor Routable Query lookup. CREATE TABLE sales (sale_key INT, customer_key INT, date_key INT, sales_amount FLOAT); CREATE PROJECTION sales_proj_b0 AS (SELECT * FROM sales) segmented BY HASH (customer_key) ALL NODES; CREATE PROJECTION sales_proj_b1 AS (SELECT * FROM sales) segmented BY HASH (customer_key) ALL NODES OFFSET 1; CREATE PROJECTION sales_proj_b2 AS (SELECT * FROM sales) segmented BY HASH (customer_key) ALL NODES OFFSET 2; select start_refresh(); 3. Add some sample data: HP Vertica Analytic Database (7.1.x) Page 249 of 401

250 INSERT INTO customers VALUES (1, 'Fred', INSERT INTO customers VALUES (2, 'Sue', INSERT INTO customers VALUES (3, 'Dave', INSERT INTO customers VALUES (4, 'Ann', INSERT INTO customers VALUES (5, 'Jamie', COMMIT; INSERT INTO sales VALUES(1, 1, 1, '100.00'); INSERT INTO sales VALUES(2, 2, 2, '200.00'); INSERT INTO sales VALUES(3, 3, 3, '300.00'); INSERT INTO sales VALUES(4, 4, 4, '400.00'); INSERT INTO sales VALUES(5, 5, 5, '400.00'); INSERT INTO sales VALUES(6, 1, 15, '500.00'); INSERT INTO sales VALUES(7, 1, 15, '400.00'); INSERT INTO sales VALUES(8, 1, 35, '300.00'); INSERT INTO sales VALUES(9, 1, 35, '200.00'); COMMIT; 4. Create an unsegmented projection of the VMart date_dimension table for use in this example. Note you must run select start_refresh(); to unsegment the existing data, CREATE PROJECTION date_dim_unsegment AS (SELECT * FROM date_dimension) UNSEGMENTED ALL NODES; select start_refresh(); Using the customer, sales, and date_dimension data, you can now create a Routable Query lookup that uses joins and a group by to query the customers table and return the total amount of purchases per day for a given customer: import java.sql.*; import java.util.hashmap; import java.util.map; import com.vertica.jdbc.kv.*; public class verticakv_doc public static void main(string[] args) com.vertica.jdbc.datasource jdbcsettings = new com.vertica.jdbc.datasource(); jdbcsettings.setdatabase("vmart"); jdbcsettings.sethost("vertica.example.com"); jdbcsettings.setuserid("dbadmin"); jdbcsettings.setpassword("password"); jdbcsettings.setenableroutablequeries(true); jdbcsettings.setfailonmultinodeplans(true); jdbcsettings.setport((short) 5433); VerticaRoutableConnection conn; Map<String, Object> map = new HashMap<String, Object>(); map.put("customer_key", 1); try HP Vertica Analytic Database (7.1.x) Page 250 of 401

251 conn = (VerticaRoutableConnection) jdbcsettings.getconnection(); String table = "customers"; VerticaRoutableExecutor q = conn.createroutableexecutor(null, table); String query = "select d.date, SUM(s.sales_amount) as Total "; query += " from customers as c"; query += " join sales as s "; query += " on s.customer_key = c.customer_key "; query += " join date_dimension as d "; query += " on d.date_key = s.date_key "; query += " where c.customer_key = " + map.get("customer_key"); query += " group by (d.date) order by Total DESC"; ResultSet rs = q.execute(query, map); while(rs.next()) System.out.print("Date: " + rs.getstring("date") + ": "); System.out.println("Amount: " + rs.getstring("total")); conn.close(); catch (SQLException e) e.printstacktrace(); The example code outputs: Date: : Amount: Date: : Amount: Date: : Amount: Note that your dates may be different, because the VMart schema randomly generates the dates in the date_dimension table. Defining the Query for Routable Queries Using the VGet Class The VGet class is used to access table data directly from a single node when you do not need to join the data or use a group by clause. Like VerticaRoutableExecutor, VGet directly queries HP Vertica nodes that have the data needed for the query, avoiding the distributed planning and execution costs associated with a normal HP Vertica execution. However, VGet does not use SQL. Instead, you define predicates and values to perform Key/Value type lookups on a single table. VGet is especially suited to doing key/value-type lookups on single tables. You create a VGet by calling prepareget(schema, table/proj) on a connection object. prepareget() takes the name of the schema and the name of a table or projection as arguments. VGet Methods VGet has the following methods: HP Vertica Analytic Database (7.1.x) Page 251 of 401

252 addpredicate(string, object) - adds a predicate column and a constant value to the query. You must include a predicate for each column on which the table is segmented. The predicate acts as the "WHERE" clause to the query. Multiple addpredicate() method calls are joined by AND modifiers. Note that the VGet retains this value after each call to execute. To remove it, use ClearPredicates(). Note: The following data types cannot be used as predicates. Additionally, if a table is segmented on any columns with the following data types then the table cannot be queried using the Routable Query API: interval timetz timsestamptz addpredicateexpression(string) - Accepts arbitrary SQL expressions that operate on the table's columns as input to the query. Predicate expressions and predicates are joined by AND modifiers. You can use segmented columns in predicate expressions, but they must also be specified as a regular predicate with addpredicate(). Note that the VGet retains this value after each call to execute. To remove it, use ClearPredicates(). Note: The driver does not verify the syntax of the expression before it sends it to the server. If your expression is incorrect then the query fails. addoutputcolumn(string) - Adds a column to be included in the output. By default the query runs as SELECT * and you do not need to define any output columns to return the data. If you add output columns then you must add all the columns you want returned. Note that the VGet retains this value after each call to execute. To remove it, use ClearOutputs(). addoutputexpression(string) - Accepts arbitrary SQL expressions that operate on the table's columns as output. Note that the VGet retains this value after each call to execute. To remove it, use ClearOutputs(). Note: The driver does not verify the syntax of the expression before it sends it to the server. If your expression is incorrect then the query fails. Note: addoutputexpression() is not supported when querying Flex Tables. If you attempt to use addoutputexpression() on a Flex Table query, then a SQLFeatureNotSupportedException is thrown. HP Vertica Analytic Database (7.1.x) Page 252 of 401

253 addsortcolumn(string, SortOrder) - Adds a sort order to an output column. The output column can be either the one returned by the default query (SELECT *) or one of the columns defined in addoutputcolumn or addoutputexpress. You can defined multiple sort columns. setlimit(int) - Sets a limit on the number of results returned. A limit of 0 is unlimited. clearpredicates() - Removes predicates that were added by addpredicate() and addpredicateexpression(). clearoutputs() - Removes outputs added by addoutput() and addoutputexpression(). clearsortcolumns() - Removes sort columns previously added by addsortcolumn(). execute() - Runs the query. Care must be taken to ensure that the predicate columns exist on the table and projection used by VGet, and that the expressions do not require multiple nodes to execute. If an expression is sufficiently complex as to require more than one node to execute, execute() throws a SQLException if the FailOnMultiNodePlans connection property is true. close() - Closes this VGet by releasing resources used by this VGet. It does not close the parent JDBC connection to HP Vertica. getwarnings() - Retrieves the first warning reported by calls on this VGet. Additional warnings are chained and can be accessed with the JDBC getnextwarning() method. You call the execute() method to run query. By default, the VGet fetches all the columns of all the rows that satisfy the logical AND of all the predicates passed via the addpredicate() method. To further customize the get operation use the addoutputcolumn(), addoutputexpression(), addpredicateexpression(), addsortcolumn() and setlimit() methods. Note: VGet operations span multiple JDBC connections (and multiple HP Vertica sessions) and do not honor the parent connection's transaction semantics. If consistency is required across multiple executions, the parent VerticaRoutableConnection's consistent read API can be used to guarantee all operations occur at the same epoch. VGet is thread safe, but all methods are synchronized, so threads that share a VGet instance are never run in parallel. For better parallelism, each thread should have its own VGet instance. Different VGet instances that operate on the same table share pooled connections and metadata in a manner that enables a high degree of parallelism. Example You can query the table defined in Creating Tables and Projections for use with the Routable Query API with the following example code. The table defines an id column that is segmented by hash. import java.sql.*; import com.vertica.jdbc.kv.*; public class verticakv2 HP Vertica Analytic Database (7.1.x) Page 253 of 401

254 public static void main(string[] args) com.vertica.jdbc.datasource jdbcsettings = new com.vertica.jdbc.datasource(); jdbcsettings.setdatabase("exampledb"); jdbcsettings.sethost("docg01.verticacorp.com"); jdbcsettings.setuserid("dbadmin"); jdbcsettings.setpassword("password"); jdbcsettings.setenableroutablequeries(true); jdbcsettings.setport((short) 5433); VerticaRoutableConnection conn; try conn = (VerticaRoutableConnection) jdbcsettings.getconnection(); System.out.println("Connected."); VGet get = conn.prepareget("public", "users"); get.addpredicate("id", 5); ResultSet rs = get.execute(); rs.next(); System.out.println("ID: " + rs.getstring("id")); System.out.println("Username: " + rs.getstring("username")); System.out.println(" " + rs.getstring(" ")); System.out.println("Closing Connection."); conn.close(); catch (SQLException e) System.out.println("Error! Stacktrace:"); e.printstacktrace(); The output: Connected. ID: 5 Username: usere [email protected] Closing Connection. Routable Query Performance and Troubleshooting This topic details performance considerations and common issues you might encounter when using the Routable Query API. Using Resource Pools with Routable Queries Individual Routable Queries are serviced quickly since they directly access a single node and return only one or a few rows of data. However, by default, HP Vertica resource pools use an AUTO HP Vertica Analytic Database (7.1.x) Page 254 of 401

255 setting for the execution parallelism parameter. When set to AUTO, the setting is determined by the number of CPU cores available and generally results in multi-threaded execution of queries in the resource pool. It is not efficient to create parallel threads on the server because Routable Query operations return data so quickly and Routable Query operations only use a single thread to find a row. To prevent the server from opening unneeded processing threads, you should create a specific resource pool for Routable Query clients. Consider the following settings for the resource pool you use for Routable Queries: Set execution parallelism to 1 to force single-threaded queries. This setting improves Routable Query performance. Use CPU affinity to limit the resource pool to a specific CPU or CPU set. The setting ensures that the Routable Queries have resources available to them, but it also prevents Routable Queries from significantly impacting performance on the system for other general queries. If you do not set a CPU affinity for the resource pool, consider setting the maximum concurrency value of the resource pool to a setting that ensures good performance for Routable Queries, but does not negatively impact the performance of general queries. Performance Considerations for Routable Query Connections Because a VerticaRoutableConnection opens an internal pool of connections, it is important to configure MaxPooledConnections and MaxPooledConnectionsPerNode appropriately for your cluster size and the amount of simultaneous client connections. It is possible to impact normal database connections if you are overloading the cluster with VerticaRoutableConnections. The initial connection to the initiator node discovers all other nodes in the cluster. The internal-pool connections are not opened until a VerticaRoutableExecutor or VGet query is sent. All VerticaRoutableExecutors/VGets in a connection object use connections from the internal pool and are limited by the MaxPooledConnections settings. Connections remain open until they are closed so a new connection can be opened elsewhere if the connection limit has been reached. Troubleshooting Routable Queries Routable Query issues generally fall into two categories: Not providing enough predicates. Queries having to span multiple nodes. Predicate Requirements You must provide the same number of predicates that correspond to the columns of the table segmented by hash. To determine the segmented columns, run select get_table_projections ('tablename'). You must provide a predicate for each column displayed in the "Seg Cols" field. For VGet, this means you must literally use addpredicate() to add each of the columns. For VerticaRoutableExecutor, this means you must provide all of the predicates and values in the map sent to execute(). Multi-node Failures HP Vertica Analytic Database (7.1.x) Page 255 of 401

256 It is possible to define the correct number of predicates, but still have a failure because multiple nodes contain the data. This failure occurs because the projection's data is not segmented in such a way that the data being queried is contained on a single node. Enable logging for the connection and view the logs to verify the projection being used. If the client is not picking the correct projection, then try to query the projection directly by specifying the projection instead of the table in the create/prepare statement, for example: Using VerticaRoutableExecutor: conn.createroutableexecutor(schema, table/projection); Using VGet: conn.prepareget('schema','table/projection'). Additionally, you can use the EXPLAIN command in vsql to help determine if your query can run in single node. EXPLAIN can help you understand why the query is being run as single or multi-node. HP Vertica Analytic Database (7.1.x) Page 256 of 401

257 Programming ADO.NET Applications The HP Vertica driver for ADO.NET allows applications written in C# to read data from, update, and load data into HP Vertica databases. It provides a data adapter (HP Vertica Data Adapter) that facilitates reading data from a database into a data set, and then writing changed data from the data set back to the database. It also provides a data reader (HP VerticaDataReader) for reading data. The driver requires the.net framework version For more information about ADO.NET, see: Overview of ADO.NET ADO.NET.NET Framework Developer's Guide Note: All of the examples provided in this section are in C#. Updating ADO.NET Client Code From Previous Driver Versions Starting in release 5.1.1, the HP Vertica client drivers have been updated to improve standards compliance, performance, and reliability. As a result, some HP Vertica-specific features and past incompatibilities have been eliminated. You must update any client code written for the prior versions of the ADO.NET driver to work with the version driver and beyond. Auto Commit Change All queries are now Auto Committed. The only exception is that queries run using a Transaction are not committed until the Commit(); method is called. Performance Improvements Prepared INSERT statements now run significantly faster than in previous driver versions. For the best performance, prepared statements should be executed as part of a transaction. Namespace Change The namespace has changed from vertica to Vertica.Data.VerticaClient Connection Properties DSN is no longer a valid connection string keyword. You cannot connect to HP Vertica using ADO.net with a DSN. The RowBufferSize connection property has been renamed to ResultBufferSize. HP Vertica Analytic Database (7.1.x) Page 257 of 401

258 Getters on the VerticaConnection to get various connection string options (CacheDirectoryPooling, MinPoolSize, MaxPoolSize, SyncNotification, Timeout, Enlist, UseExtendedTypes, Password, Pooling, MinPoolSize, MaxPoolSize) have been removed. There is no longer a locale connection string keyword and you cannot set the locale through the connection string. To change the locale, run the query "set locale to..." The connection property to enable or disable auto commit has been removed. All queries outside of transactions are auto-committed. Result Buffering The driver now buffers all results, and always uses streaming. Because of this, the following functionality has changed: VerticaCommandBehavior enum has been removed. This enum extended the ADO.NET CommandBehavior enum to add support for buffering results. Results are now buffered in HP Vertica 5.1.x. The VerticaCommand.ExecuteReader(CommandBehavior, bool) argument has been removed. CacheDirectory or PreloadReader connection string options have been removed. Logging Changes Log properties are no longer configured on the connection string. Log properties are now configured through the VerticaLogProperties class. Data Type Changes The following data types have changed: Old Datatype Name verticatype.integer verticatype.bigint verticatype.timestamp verticatype.interval New Datatype Name VerticaType.BigInt VerticaType.BigInt VerticaType.DateTime Changed to specific type of interval, for example: VerticaType.IntervalDay VerticaType.IntervalDayToHour VerticaType.IntervalDayToMinute etc. HP Vertica Analytic Database (7.1.x) Page 258 of 401

259 Old Datatype Name verticatype.real verticatype.text verticatype.smallint verticatype.varbinary New Datatype Name VerticaType.Double VerticaType.VarChar VerticaType.BigInt VerticaType.VarBinary Multiple Commands Now Supported Multiple commands in a single statement are now supported, provided that parameters are not used in any of the commands in the statement. The exception is COPY commands. You cannot issue multiple COPY commands in the same statement. Setting the Locale for ADO.NET Sessions ADO.NET applications use a UTF-16 character set encoding and are responsible for converting any non-utf-16 encoded data to UTF-16. The same cautions as for ODBC apply if this encoding is violated. The ADO.NET driver converts UTF-16 data to UTF-8 when passing to the HP Vertica server and converts data sent by HP Vertica server from UTF-8 to UTF-16 ADO.NET applications should set the correct server session locale by executing the SET LOCALE TO command in order to get expected collation and string functions behavior on the server. If there is no default session locale at the database level, ADO.NET applications need to set the correct server session locale by executing the SET LOCALE TO command in order to get expected collation and string functions behavior on the server. See the SET LOCALE command in the SQL Reference Manual Connecting to the Database This section describes: Using SSL: Installing SSL Certificates on Windows Opening and Closing the Database Connection (ADO.NET) ADO.NET Connection Properties Configuring Log Properties HP Vertica Analytic Database (7.1.x) Page 259 of 401

260 Using SSL: Installing Certificates on Windows You can optionally secure communication between your ADO.NET application and HP Vertica using SSL. The HP Vertica ADO.NET driver uses the default Windows key store when looking for SSL certificates. This is the same key store that Internet Explorer uses. Before you can use SSL on the client side, you must implement SSL on the server. See Implementing SSL in the Administrator's Guide, perform those steps, then return to this topic to install the SSL certificate on Windows. To use SSL for ADO.NET connections to HP Vertica: Import the server and client certificates into the Windows Key Store. If required by your certificates, import the public certificate of your Certifying Authority. Import the Server and Client Certificates into the Windows Key store: 1. Copy the server.crt file you generated when you enabled SSL on the server to your Windows Machine. 2. Double-click the certificate. 3. Let Windows determine the key type, and click Install. Import the Public Certificate of Your CA: You must establish a chain of trust for the certificates. You may need to import the public certificate for your Certifying Authority (CA) (especially if it is a self-signed certificate). 1. using the same certificate as above, double-click the certificate. 2. Select Place all certificates in the following store. 3. Click Browse, select Trusted Root Certification Authorities and click Next. 4. Click Install. Enable SSL in Your ADO.NET Applications In your connection string, be sure to enable SSL by setting the SSL property in VerticaConnectionStringBuilder to true, for example: //configure connection properties VerticaConnectionStringBuilder(); VerticaConnectionStringBuilder builder = new HP Vertica Analytic Database (7.1.x) Page 260 of 401

261 builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; builder.ssl = true; //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); Opening and Closing the Database Connection (ADO.NET) Before you can access data in HP Vertica through ADO.NET, you must create a connection to the database using the VerticaConnection class which is an implementation of System.Data.DbConnection. The VerticaConnection class takes a single argument that contains the connection properties as a string. You can manually create a string of property keywords to use as the argument, or you can use the VerticaConnectionStringBuilder class to build a connection string for you. This topic details the following: Manually building a connection string and connecting to HP Vertica Using VerticaConnectionStringBuilder to create the connection string and connecting to HP Vertica Closing the connection To Manually Create a Connection string: See ADO.NET Connection Properties for a list of available properties to use in your connection string. At a minimum, you need to specify the Host, Database, and User. 1. For each property, provide a value and append the properties and values one after the other, separated by a semicolon. Assign this string to a variable. For example: String connectstring = "DATABASE=VMart;HOST=node01;USER=dbadmin"; 2. Build an HP Vertica connection object that specifies your connection string. VerticaConnection _conn = new VerticaConnection(connectString) 3. Open the connection. _conn.open(); HP Vertica Analytic Database (7.1.x) Page 261 of 401

262 4. Create a command object and associate it with a connection. All VerticaCommand objects must be associated with a connection. VerticaCommand command = _conn.createcommand(); To Use the VerticaConnectionStringBuilder Class to Create a Connection String and Open a connection: 1. Create a new object of the VerticaConnectionStringBuilder class. VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder(); 2. Update your VerticaConnectionStringBuilder object with property values. See ADO.NET Connection Properties for a list of available properties to use in your connection string. At a minimum, you need to specify the Host, Database, and User. builder.host = "node01"; builder.database = "VMart"; builder.user = "dbadmin"; 3. Build an HP Vertica connection object that specifies your connection VerticaConnectionStringBuilder object as a string. VerticaConnection _conn = new VerticaConnection(builder.ToString()); 4. Open the connection. _conn.open(); 5. Create a command object and associate it with a connection. All VerticaCommand objects must be associated with a connection. VerticaCommand command = _conn.createcommand; Note: If your database is not in compliance with your HP Vertica license, the call to VerticaConnection.open() returns a warning message to the console and the log. See Managing Your License Key in the Administrator's Guide for more information. HP Vertica Analytic Database (7.1.x) Page 262 of 401

263 To Close the connection: When you're finished with the database, close the connection. Failure to close the connection can deteriorate the performance and scalability of your application. It can also prevent other clients from obtaining locks. _conn.close(); Example Usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); //Perform some operations _conn.close(); ADO.NET Connection Properties You use connection properties to configure the connection between your ADO.NET client application and your HP Vertica database. The properties provide the basic information about the connections, such as the server name and port number, needed to connect to your database. You can set a connection property in two ways: Include the property name and value as part of the connection string you pass to a VerticaConnection. Set the properties in a VerticaConnectionStringBuilder object, and then pass the object as a string to a VerticaConnection. HP Vertica Analytic Database (7.1.x) Page 263 of 401

264 Property Description Default Value Database User Port Host PreferredAddress Family Name of the HP Vertica database to which you want to connect. For example, if you installed the example VMart database, the database is "VMart". Name of the user to log into HP Vertica/. Port on which HP Vertica is running. The host name or IP address of the server on which HP Vertica is running. You can provide an IPv4 address, IPv6 address, or hostname. In mixed IPv4/IPv6 networks, the DNS server configuration determines which IP version address is sent first. Use the PreferredAddressFamily option to force the connection to use either IPv4 or IPv6. The IP version to use if the client and server have both IPv4 and IPv6 addresses and you have provided a host name. Valid values are: Ipv4 Connect to the server using IPv4. Ipv6 Connect to the server using IPv6. None Use the IP address provided by the DNS server. none none 5433 none Vertica.Data.VerticaClient.AddressFamilyPr eference.none HP Vertica Analytic Database (7.1.x) Page 264 of 401

265 Property Description Default Value Password ConnSettings IsolationLevel Label DirectBatchInser t ResultBufferSize ConnectionTimeou t The password associated with the user connecting to the server. SQL commands to run upon connection. Uses %3B for semicolons. Sets the transaction isolation level for HP Vertica. See Transactions for a description of the different transaction levels. This value is either Serializable, ReadCommitted, or Unspecified. See Setting the Transaction Isolation Level for an example of setting the isolation level using this keyword. Note: By default, this value is set to IsolationLevel.Unspecified, which means the connection uses the server's default transaction isolation level. HP Vertica's default isolation level is IsolationLevel.ReadCommit ted. A string to identify the session on the server. A Boolean value, whether to bulk insert to ROS (true) or WOS (false). The size of the buffer to use when streaming results. Number seconds to wait for a connection. A value of 0 means no timeout. string.empty string.empty System.Data. IsolationLevel.Unspecified string false HP Vertica Analytic Database (7.1.x) Page 265 of 401

266 Property Description Default Value ReadOnly Pooling MinPoolSize MaxPoolSize A Boolean value. If true, throw an exception on write attempts. A boolean value, whether to enable connection pooling. Connection pooling is useful for server applications because it allows the server to reuse connections. This saves resources and enhances the performance of executing commands on the database. It also reduces the amount of time a user must wait to establish a connection to the database An integer that defines the minimum number of connections to pool. Valid Values: Cannot be greater than the number of connections that the server is configured to allow. Otherwise, an exception results. Default: 55 An integer that defines the maximum number of connections to pool. Valid Values: Cannot be greater than the number of connections that the server is configured to allow. Otherwise, an exception results. false false 1 20 HP Vertica Analytic Database (7.1.x) Page 266 of 401

267 Property Description Default Value LoadBalanceTimeo ut SSL IntegratedSecuri ty The amount of time, expressed in seconds, to timeout or remove unused pooled connections. Disable: Set to 0 (no timeouts) If you are using a cluster environment to load-balance the work, then pool is restricted to the servers in the cluster when the pool was created. If additional servers are added to the cluster, and the pool is not removed, then the new servers are never added to the connection pool unless LoadBalanceTimeout is set and exceeded or VerticaConnection.Clear AllPools() is called manually from an application. If you are using load balancing, then set this property to a value that considers when new servers are added to the cluster. However, do not set it so low that pools are frequently removed and rebuilt, doing so makes pooling ineffective. A Boolean value, indicating whether to use SSL for the connection. Provides a Boolean value that, when set to true, uses the user s Windows credentials for authentication, instead of user/password in the connection string. 0 (no timeout) false false HP Vertica Analytic Database (7.1.x) Page 267 of 401

268 Property Description Default Value KerberosServiceN ame KerberosHostname Provides the service name portion of the HP Vertica Kerberos principal; for example: vertica Provides the instance or host name portion of the HP Vertica Kerberos principal; for example: vertica/ vertica Value specified in the servername connection string property Enabling Native Connection Load Balancing in ADO.NET Native connection load balancing helps spread the overhead caused by client connections on the hosts in the HP Vertica database. Both the server and the client must enable native connection load balancing in order for it to have an effect. If both have enabled it, then when the client initially connects to a host in the database, the host picks a host to handle the client connection from a list of the currently up hosts in the database, and informs the client which host it has chosen. If the initially-contacted host did not choose itself to handle the connection, the client disconnects, then opens a second connection to the host selected by the first host. The connection process to this second host proceeds as usual if SSL is enabled, then SSL negotiations begin, otherwise the client begins the authentication process. See About Native Connection Load Balancing in the Administrator's Guide for details. To enable native load balancing on your client, set the ConnectionLoadBalance connection parameter to true either in the connection string or using the ConnectionStringBuilder(). The following example demonstrates connecting to the database several times with native connection load balancing enabled, and fetching the name of the node handling the connection from the V_ MONITOR.CURRENT_SESSION system table. using System; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication1 class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder(); builder.host = "node01.example.com"; builder.database = "VMart"; builder.user = "dbadmin"; HP Vertica Analytic Database (7.1.x) Page 268 of 401

269 balance // Enable native client load balancing in the client, // must also be enabled on the server! builder.connectionloadbalance = true; // Connect 3 times to verify a new node is connected // for each connection. for (int i = 1; i <= 4; i++) try VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); if (i == 1) // On the first connection, check the server policy for load VerticaCommand sqlcom = _conn.createcommand(); sqlcom.commandtext = "SELECT LOAD_BALANCE_POLICY FROM V_CATALOG.DATABASES"; var returnvalue = sqlcom.executescalar(); Console.WriteLine("Status of load balancy policy on server: " + returnvalue.tostring() + "\n"); VerticaCommand command = _conn.createcommand(); command.commandtext = "SELECT node_name FROM V_MONITOR.CURRENT_SESSION"; VerticaDataReader dr = command.executereader(); while (dr.read()) Console.Write("Connect attempt #" + i + "... "); Console.WriteLine("Connected to node " + dr[0]); dr.close(); _conn.close(); Console.WriteLine("Disconnecting.\n"); catch (Exception e) Console.WriteLine(e.Message); Running the above example produces the following output: Status of load balancy policy on server: roundrobin Connect attempt #1... Connected to node v_vmart_node0001 Disconnecting. Connect attempt #2... Connected to node v_vmart_node0002 Disconnecting. Connect attempt #3... Connected to node v_vmart_node0003 HP Vertica Analytic Database (7.1.x) Page 269 of 401

270 Disconnecting. Connect attempt #4... Connected to node v_vmart_node0001 Disconnecting. ADO.NET Connection Failover If a client application attempts to connect to a host in the Vertica Analytic Database cluster that is down, the connection attempt fails when using the default connection configuration. This failure usually returns an error to the user. The user must either wait until the host recovers and retry the connection or manually edit the connection settings to choose another host. Due to Vertica Analytic Database's distributed architecture, you usually do not care which database host handles a client application's connection. You can use the client driver's connection failover feature to prevent the user from getting connection errors when the host specified in the connection settings is unreachable. It gives you two ways to let the client driver automatically attempt to connect to a different host if the one specified in the connection parameters is unreachable: Configure your DNS server to return multiple IP addresses for a host name. When you use this host name in the connection settings, the client attempts to connect to the first IP address from the DNS lookup. If the host at that IP address is unreachable, the client tries to connect to the second IP, and so on until it either manages to connect to a host or it runs out of IP addresses. Supply a list of backup hosts for the client driver to try if the primary host you specify in the connection parameters is unreachable. For both methods, the process of failover is transparent to the client application (other than specifying the list of backup hosts, if you choose to use the list method of failover). If the primary host is unreachable, the client driver automatically tries to connect to other hosts. Failover only applies to the initial establishment of the client connection. If the connection breaks, the driver does not automatically try to reconnect to another host in the database. Choosing a Failover Method You usually choose to use one of the two failover methods. However, they do work together. If your DNS server returns multiple IP addresses and you supply a list of backup hosts, the client first tries all of the IPs returned by the DNS server, then the hosts in the backup list. Note: If a host name in the backup host list resolves to multiple IP addresses, the client does not try all of them. It just tries the first IP address in the list. The DNS method of failover centralizes the configuration client failover. As you add new nodes to your Vertica Analytic Database cluster, you can choose to add them to the failover list by editing the DNS server settings. All client systems that use the DNS server to connect to Vertica Analytic Database automatically use connection failover without having to change any settings. However, HP Vertica Analytic Database (7.1.x) Page 270 of 401

271 this method does require administrative access to the DNS server that all clients use to connect to the Vertica Analytic Database cluster. This may not be possible in your organization. Using the backup server list is easier than editing the DNS server settings. However, it decentralizes the failover feature. You may need to update the application settings on each client system if you make changes to your Vertica Analytic Database cluster. Using DNS Failover To use DNS failover, you need to change your DNS server's settings to map a single host name to multiple IP addresses of hosts in your Vertica Analytic Database cluster. You then have all client applications use this host name to connect to Vertica Analytic Database. You can choose to have your DNS server return as many IP addresses for the host name as you want. In smaller clusters, you may choose to have it return the IP addresses of all of the hosts in your cluster. However, for larger clusters, you should consider choosing a subset of the hosts to return. Otherwise there can be a long delay as the client driver tries unsuccessfully to connect to each host in a database that is down. Using the Backup Host List To enable backup list-based connection failover, your client application has to specify at least one IP address or host name of a host in the BackupServerNode parameter. The host name or IP can optionally be followed by a colon and a port number. If not supplied, the driver defaults to the standard HP Vertica port number (5433). To list multiple hosts, separate them by a comma. The following example demonstrates setting the BackupServerNode connection parameter to specify additional hosts for the connection attempt. The connection string intentionally has a nonexistent node, so that the initial connection fails. The client driver has to resort to trying the backup hosts to establish a connection to HP Vertica. using System; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication1 class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder(); builder.host = "not.a.real.host:5433"; builder.database = "VMart"; builder.user = "dbadmin"; builder.backupservernode = "another.broken.node:5433,docg02.verticacorp.com:5433"; try VerticaConnection _conn = HP Vertica Analytic Database (7.1.x) Page 271 of 401

272 new VerticaConnection(builder.ToString()); _conn.open(); VerticaCommand sqlcom = _conn.createcommand(); sqlcom.commandtext = "SELECT node_name FROM current_session"; var returnvalue = sqlcom.executescalar(); Console.WriteLine("Connected to node: " + returnvalue.tostring() + "\n"); _conn.close(); Console.WriteLine("Disconnecting.\n"); catch (Exception e) Console.WriteLine(e.Message); Notes When native connection load balancing is enabled, the additional servers specified in the BackupServerNode connection parameter are only used for the initial connection to an HP Vertica host. If host redirects the client to another host in the database cluster to handle its connection request, the second connection does not use the backup node list. This is rarely an issue, since native connection load balancing is aware of which nodes are currently up in the database. See Enabling Native Connection Load Balancing in ADO.NET. Connections to a host taken from the BackupServerNode list are not pooled for ADO.NET connections. Configuring Log Properties (ADO.Net) Log properties for ADO.Net are configured differently than they are other client drivers. On the other client drivers, log properties can be configured as one of the connection properties. The ADO.Net driver user the VerticaLogProperties class to configure the properties. VerticaLogProperties VerticaLogProperties is a static class that allows you to set and get the log settings for the ADO.net driver. You can control the log level, log path, and log namespace using this class. The log is created when the first connection is opened. Once the connection is opened, you cannot change the log path. It must be set prior to opening the connection. You can change the log level and log namespace at any time. Setting Log Properties Setting the log properties is done using the three methods in the VerticaLogProperties class. The three methods are: HP Vertica Analytic Database (7.1.x) Page 272 of 401

273 SetLogPath(String path, bool persist) SetLogNamespace(String lognamespace, bool persist) SetLogLevel(VerticaLogLevel loglevel, bool persist) Each of the methods requires a boolean persist argument. When set to true, the persist argument causes the setting to be written to the client's Windows Registry, where it is used for all subsequent connections. If set to false, then the log property only applies to the current session. SetLogPath The SetLogPath method takes as its arguments a string containing the path to the log file and the persist argument. If the path string contains only a directory path, then the log file is created with the name vdp-driver-mm-dd_hh.mm.ss.log (where MM-dd_HH.mm.ss is the date and time the log was created). If the path ends in a filename, such as log.txt or log.log, then the log is created with that filename. If SetLogPath is called with an empty string for the path argument, then the client executable's current directory is used as the log path. If SetLogPath is not called and no registry entry exists for the log path, and you have called any of the other VerticaLogProperties methods, then the client executable's current directory is used as the log path. When the persist argument is set to true, the path specified is copied to the registry verbatim. If no filename was specified, then the filename is not saved to the registry. Note: Note: The path must exist on the client system prior to calling this method. The method does not create directories. Example Usage: //set the log path string path = "C:\\log"; VerticaLogProperties.SetLogPath(path, false); SetLogNamespace The SetLogNamespace method takes as its arguments a string containing the namespace to log and the persist argument. The namespace string to log can be one of the following: Vertica Vertica.Data.VerticaClient Vertica.Data.Internal.IO HP Vertica Analytic Database (7.1.x) Page 273 of 401

274 Vertica.Data.Internal.DataEngine Vertica.Data.Internal.Core Namespaces can be truncated to include multiple child namespaces. For example, you can specify "Vertica.Data.Internal" to log for all of the Vertica.Data.Internal namespaces. If a log namespace is not set, and no value is stored in the registry, then the "Vertica" namespace is used for logging. Example Usage: //set namespace to log string lognamespace = "Vertica.Data.VerticaClient"; VerticaLogProperties.SetLogNamespace(lognamespace, false); SetLogLevel The SetLogLevel method takes as its arguments a VerticaLogLevel type and the persist argument. The VerticaLogLevel argument can be one of: VerticaLogLevel.None VerticaLogLevel.Fatal VerticaLogLevel.Error VerticaLogLevel.Warning VerticaLogLevel.Info VerticaLogLevel.Debug VerticaLogLevel.Trace If a log level is not set, and no value is stored in the registry, then VerticaLogLevel.None is used. Example Usage: //set log level VerticaLogLevel level = VerticaLogLevel.Debug; VerticaLogProperties.SetLogLevel(level, false); Getting Log Properties You can get the log property values using the getters included in the VerticaLogProperties class. The properties are: HP Vertica Analytic Database (7.1.x) Page 274 of 401

275 LogPath LogNamespace LogLevel Example Usage: //get current log settings string logpath = VerticaLogProperties.LogPath; VerticaLogLevel loglevel = VerticaLogProperties.LogLevel; string logns = VerticaLogProperties.LogNamespace; Console.WriteLine("Current Log Settings:"); Console.WriteLine("Log Path: " + logpath); Console.WriteLine("Log Level: " + loglevel); Console.WriteLine("Log Namespace: " + logns); Setting and Getting Log Properties Example This complete example shows how to set and get log properties: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) //configure connection properties (); VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; //get current log settings string logpath = VerticaLogProperties.LogPath; VerticaLogLevel loglevel = VerticaLogProperties.LogLevel; string logns = VerticaLogProperties.LogNamespace; Console.WriteLine("\nOld Log Settings:"); Console.WriteLine("Log Path: " + logpath); Console.WriteLine("Log Level: " + loglevel); Console.WriteLine("Log Namespace: " + logns); HP Vertica Analytic Database (7.1.x) Page 275 of 401

276 //set the log path string path = "C:\\log"; VerticaLogProperties.SetLogPath(path, false); //set log level VerticaLogLevel level = VerticaLogLevel.Debug; VerticaLogProperties.SetLogLevel(level, false); //set namespace to log string lognamespace = "Vertica"; VerticaLogProperties.SetLogNamespace(lognamespace, false); //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); //get new log settings logpath = VerticaLogProperties.LogPath; loglevel = VerticaLogProperties.LogLevel; logns = VerticaLogProperties.LogNamespace; Console.WriteLine("\nNew Log Settings:"); Console.WriteLine("Log Path: " + logpath); Console.WriteLine("Log Level: " + loglevel); Console.WriteLine("Log Namespace: " + logns); //close the connection _conn.close(); The example produces the following output: Old Log Settings: Log Path: Log Level: None Log Namespace: New Log Settings: Log Path: C:\log Log Level: Debug Log Namespace: Vertica HP Vertica Analytic Database (7.1.x) Page 276 of 401

277 Querying the Database Using ADO.NET This section describes how to create queries to do the following: Inserting data into the database Read data from the database Load data into the database Note: The ExecuteNonQuery() method used to query the database returns an int32 with the number of rows affected by the query. The maximum size of an int32 type is a constant and is defined to be 2,147,483,547. If your query returns more results than the int32 max, then ADO.NET throws an exception because of the overflow of the int32 type. However the query is still processed by HP Vertica even when the reporting of the return value fails. This is a limitation in.net, as ExecuteNonQuery() is part of the standard ADO.NET interface. Inserting Data (ADO.NET) Inserting data can done using the VerticaCommand class. VerticaCommand is an implementation of DbCommand. It allows you to create and send an SQL statement to the database. Use the CommandText method to assign an SQL statement to the command and then execute the SQL by calling the ExecuteNonQuery method. The ExecuteNonQuery method is used for executing statements that do not return result sets. To Insert a Single Row of data: 1. Create a connection to the database. 2. Create a command object using the connection. VerticaCommand command = _conn.createcommand(); 3. Insert data using an INSERT statement. The following is an example of a simple insert. Note that is does not contain a COMMIT statement because the HP Vertica ADO.NET driver operates in autocommit mode. command.commandtext = "INSERT into test values(2, 'username', ' ', 'password')"; 4. Execute the query. The rowsadded variable contains the number of rows added by the insert statement. HP Vertica Analytic Database (7.1.x) Page 277 of 401

278 Int32 rowsadded = command.executenonquery(); The ExecuteNonQuery() method returns the number of rows affected by the command for UPDATE, INSERT, and DELETE statements. For all other types of statements it returns -1. If a rollback occurs then it is also set to -1. Example Usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); VerticaCommand command = _conn.createcommand(); command.commandtext = "INSERT into test values(2, 'username', ' ', 'password')"; Int32 rowsadded = command.executenonquery(); Console.WriteLine( rowsadded + " rows added!"); _conn.close(); Using Parameters You can use parameters to execute similar SQL statements repeatedly and efficiently. Using Parameters VerticaParameters are an extension of the System.Data.DbParameter base class in ADO.NET and are used to set parameters in commands sent to the server. Use Parameters in all queries (SELECT/INSERT/UPDATE/DELETE) for which the values in the WHERE clause are not static; that is for all queries that have a known set of columns, but whose filter criteria is set dynamically by an application or end user. Using parameters in this way greatly decreases the chances of an SQL injection issue that can occur when simply creating a SQL query from a number of variables. HP Vertica Analytic Database (7.1.x) Page 278 of 401

279 Parameters require that a valid DbType, VerticaDbType, or System type be assigned to the parameter. See SQL Data Types and ADO.NET Data Types for a mapping of System, Vertica, and DbTypes. To create a parameter placeholder, place either the at sign (@) or a colon (:) character in front of the parameter name in the actual query string. Do not insert any spaces between the placeholder indicator (@ or :) and the placeholder. Note: character is the preferred way to identify parameters. The colon (:) character is supported for backward compatibility. For example, the following typical query uses the string 'MA' as a filter. SELECT customer_name, customer_address, customer_city, customer_state FROM customer_dimension WHERE customer_state = 'MA'; Instead, the query can be written to use a parameter. In the following example, the string MA is replaced by the parameter SELECT customer_name, customer_address, customer_city, customer_state FROM customer_dimension WHERE customer_state For example, the ADO.net code for the prior example would be written as: VerticaCommand command = _conn.createcommand(); command.commandtext = SELECT customer_name, customer_address, customer_city, customer_ state FROM customer_dimension WHERE customer_state ; command.parameters.add(new VerticaParameter( STATE, VerticaType.VarChar)); command.parameters["state"].value = "MA"; Note: Although the VerticaCommand class supports a Prepare() method, you do not need to call the Prepare() method for parameterized statements because HP Vertica automatically prepares the statement for you. Creating and Rolling Back Transactions Creating Transactions Transactions in HP Vertica are atomic, consistent, isolated, and durable. When you connect to a database using the Vertica ADO.NET Driver, the connection is in autocommit mode and each individual query is committed upon execution. You can collect multiple statements into a single transaction and commit them at the same time by using a transaction. You can also choose to rollback a transaction before it is committed if your code determines that a transaction should not commit. Transactions use the VerticaTransaction object, which is an implementation of DbTransaction. You must associate the transaction with the VerticaCommand object. HP Vertica Analytic Database (7.1.x) Page 279 of 401

280 The following code uses an explicit transaction to insert one row each into to tables of the VMart schema. To Create a Transaction in HP Vertica Using the ADO.NET driver: 1. Create a connection to the database. 2. Create a command object using the connection. VerticaCommand command = _conn.createcommand(); 3. Start an explicit transaction, and associate the command with it. VerticaTransaction txn = _conn.begintransaction(); command.connection = _conn; command.transaction = txn; 4. Execute the individual SQL statements to add rows. command.commandtext = "insert into product_dimension values(... )"; command.executenonquery(); command.commandtext = "insert into store_orders_fact values(... )"; 5. Commit the transaction. txn.commit(); Rolling Back Transactions If your code checks for errors, then you can catch the error and rollback the entire transaction. VerticaTransaction txn = _conn.begintransaction(); VerticaCommand command = new VerticaCommand("insert into product_dimension values( , 5, 'New item 5' )", _conn); // execute the insert command.executenonquery(); command.commandtext = "insert into product_dimension values( , 6, 'New item 6' )"; // try insert and catch any errors bool error = false; try command.executenonquery(); catch (Exception e) HP Vertica Analytic Database (7.1.x) Page 280 of 401

281 Console.WriteLine(e.Message); error = true; if (error) txn.rollback(); Console.WriteLine("Errors. Rolling Back."); else txn.commit(); Console.WriteLine("Queries Successful. Committing."); Commit and Rollback Example This example details how you can commit or rollback queries during a transaction. using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); bool error = false; VerticaCommand command = _conn.createcommand(); VerticaCommand command2 = _conn.createcommand(); VerticaTransaction txn = _conn.begintransaction(); command.connection = _conn; command.transaction = txn; command.commandtext = "insert into test values(1, 'test', 'test', 'test' )"; Console.WriteLine(command.CommandText); try command.executenonquery(); catch (Exception e) Console.WriteLine(e.Message); error = true; HP Vertica Analytic Database (7.1.x) Page 281 of 401

282 command.commandtext = "insert into test values(2, 'ear', 'eye', 'nose', 'extra' )"; Console.WriteLine(command.CommandText); try command.executenonquery(); catch (Exception e) Console.WriteLine(e.Message); error = true; if (error) txn.rollback(); Console.WriteLine("Errors. Rolling Back."); else txn.commit(); Console.WriteLine("Queries Successful. Committing."); _conn.close(); The example displays the following output on the console: insert into test values(1, 'test', 'test', 'test' ) insert into test values(2, 'ear', 'eye', 'nose', 'extra' ) [42601]ERROR: INSERT has more expressions than target columns Errors. Rolling Back. See Also Setting the Transaction Isolation Level Setting the Transaction Isolation Level You can set the transaction isolation level on a per-connection and per-transaction basis. See Transaction for an overview of the transaction isolation levels supported in HP Vertica. To set the default transaction isolation level for a connection, use the IsolationLevel keyword in the VerticaConnectionStringBuilder string (see Connection String Keywords for details). To set the isolation level for an individual transaction, pass the isolation level to the VerticaConnection.BeginTransaction() method call to start the transaction. HP Vertica Analytic Database (7.1.x) Page 282 of 401

283 To set the Isolation Level on a connection-basis: 1. Use the VerticaConnectionStringBuilder to build the connection string. 2. Provide a value for the IsolationLevel builder string. It can take one of two values: IsolationLevel.ReadCommited (default) or IsolationLevel.Serializeable. For example: VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder(); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; builder.isolationlevel = System.Data.IsolationLevel.Serializeable VerticaConnection _conn1 = new VerticaConnection(builder.ToString()); _conn1.open(); To set the Isolation Level on a Transaction basis: 1. Set the IsolationLevel on the BeginTransaction method, for example VerticaTransaction txn = _conn.begintransaction(isolationlevel.serializable); Example usage: The following example demonstrates: getting the connection's transaction isolation level. setting the connection's isolation level using connection property. setting the transaction isolation level for a new transaction. using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; HP Vertica Analytic Database (7.1.x) Page 283 of 401

284 builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn1 = new VerticaConnection(builder.ToString()); _conn1.open(); VerticaTransaction txn1 = _conn1.begintransaction(); Console.WriteLine("\n Transaction 1 Transaction Isolation Level: " + txn1.isolationlevel.tostring()); txn1.rollback(); VerticaTransaction txn2 = _conn1.begintransaction (IsolationLevel.Serializable); Console.WriteLine("\n Transaction 2 Transaction Isolation Level: " + txn2.isolationlevel.tostring()); txn2.rollback(); VerticaTransaction txn3 = _conn1.begintransaction (IsolationLevel.ReadCommitted); Console.WriteLine("\n Transaction 3 Transaction Isolation Level: " + txn3.isolationlevel.tostring()); _conn1.close(); When run, the example code prints the following to the system console: Transaction 1 Transaction Isolation Level: ReadCommitted Transaction 2 Transaction Isolation Level: Serializable Transaction 3 Transaction Isolation Level: ReadCommitted Reading Data (ADO.Net) To read data from the database use VerticaDataReader, an implementation of DbDataReader. This implementation is useful for moving large volumes of data quickly off the server where it can be run through analytic applications. Note: that the VerticaDataReader.HasRows property returns true if the result generated any rows. In versions of HP Vertica prior to 5.1, HasRows returned rows if there were more rows to be read. Note: A VerticaCommand cannot execute anything else while it has an open VerticaDataReader associated with it. To execute something else, close the data reader or use a different VerticaCommand object. To Read Data From the Database Using VerticaDataReader: 1. Create a connection to the database. 2. Create a command object using the connection. HP Vertica Analytic Database (7.1.x) Page 284 of 401

285 VerticaCommand command = _conn.createcommand(); 3. Create a query. This query works with the example VMart database. command.commandtext = "SELECT fat_content, product_description " + "FROM (SELECT DISTINCT fat_content, product_description" + " FROM product_dimension " + " WHERE department_description " + " IN ('Dairy') " + " ORDER BY fat_content) AS food " + "LIMIT 10;"; 4. Execute the reader to return the results from the query. The following command calls the ExecuteReader method of the VerticaCommand object to obtain the VerticaDataReader object. VerticaDataReader dr = command.executereader(); 5. Read the data. The data reader returns results in a sequential stream. Therefore, you must read data from tables row-by-row. The following example uses a while loop to accomplish this: Console.WriteLine("\n\n Fat Content\t Product Description"); Console.WriteLine(" \t "); int rows = 0; while (dr.read()) Console.WriteLine(" " + dr[0] + " \t " + dr[1]); ++rows; Console.WriteLine(" \n (" + rows + " rows)\n"); 6. When you're finished, close the data reader to free up resources. dr.close(); Example Usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication HP Vertica Analytic Database (7.1.x) Page 285 of 401

286 (); class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); VerticaCommand command = _conn.createcommand(); command.commandtext = "SELECT fat_content, product_description " + "FROM (SELECT DISTINCT fat_content, product_description" + " FROM product_dimension " + " WHERE department_description " + " IN ('Dairy') " + " ORDER BY fat_content) AS food " + "LIMIT 10;"; VerticaDataReader dr = command.executereader(); Console.WriteLine("\n\n Fat Content\t Product Description"); Console.WriteLine(" \t "); int rows = 0; while (dr.read()) Console.WriteLine(" " + dr[0] + " \t " + dr[1]); ++rows; Console.WriteLine(" \n (" + rows + " rows)\n"); dr.close(); _conn.close(); Loading Data Through ADO.Net This section details the different ways that you can load data in HP Vertica using the ADO.NET client driver: Using the HP Vertica Data Adapter Using Batch Inserts and Prepared Statements Streaming Data Via ADO.NET Using the HP Vertica Data Adapter The HP Vertica data adapter (VerticaDataAdapter) enables a client to exchange data between a data set and an HP Vertica database. It is an implementation of DbDataAdapter. You can use HP Vertica Analytic Database (7.1.x) Page 286 of 401

287 VerticaDataAdapter to simply read data, or, for example, read data from a database into a data set, and then write changed data from the data set back to the database. Batching Updates When using the Update() method to update a dataset, you can optionally use the UpdateBatchSize () method prior to calling Update() to reduce the number of times the client communicates with the server to perform the update. The default value of UpdateBatchSize is 1. If you have multiple rows.add() commands for a data set, then you can change the batch size to an optimal size to speed up the operations your client must perform to complete the update. Reading Data From HP Vertica Using the Data adapter: The following example details how to perform a select query on the VMart schema and load the result into a DataTable, then output the contents of the DataTable to the console. using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using System.Data.SqlClient; Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); // Try/Catch any exceptions try using (_conn) // Create the command VerticaCommand command = _conn.createcommand(); command.commandtext = "select product_key, product_description " + "from product_dimension where product_key < 10"; // Associate the command with the connection HP Vertica Analytic Database (7.1.x) Page 287 of 401

288 command.connection = _conn; // Create the DataAdapter VerticaDataAdapter adapter = new VerticaDataAdapter(); adapter.selectcommand = command; // Fill the DataTable DataTable table = new DataTable(); adapter.fill(table); // Display each row and column value. int i = 1; foreach (DataRow row in table.rows) foreach (DataColumn column in table.columns) Console.Write(row[column] + "\t"); Console.WriteLine(); i++; Console.WriteLine(i + " rows returned."); catch (Exception e) Console.WriteLine(e.Message); _conn.close(); Reading Data From HP Vertica into a Data set and Changing data: The following example shows how to use a data adapter to read from and insert into a dimension table of the VMart schema. using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using System.Data.SqlClient; using Vertica.Data.VerticaClient namespace ConsoleApplication class Program HP Vertica Analytic Database (7.1.x) Page 288 of 401

289 (); static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); // Try/Catch any exceptions try using (_conn) //Create a data adapter object using the connection VerticaDataAdapter da = new VerticaDataAdapter(); //Create a select statement that retrieves data from the table < 10", da.selectcommand = new VerticaCommand("select * from product_dimension where product_key _conn); //Set up the insert command for the data adapter, and bind variables for some of the columns da.insertcommand = new VerticaCommand("insert into product_dimension values( :key, :version, :desc )", _conn); da.insertcommand.parameters.add(new VerticaParameter("key", VerticaType.BigInt)); da.insertcommand.parameters.add(new VerticaParameter("version", VerticaType.BigInt)); da.insertcommand.parameters.add(new VerticaParameter("desc", VerticaType.VarChar)); da.insertcommand.parameters[0].sourcecolumn = "product_key"; da.insertcommand.parameters[1].sourcecolumn = "product_version"; da.insertcommand.parameters[2].sourcecolumn = "product_description"; da.tablemappings.add("product_key", "product_key"); da.tablemappings.add("product_version", "product_version"); da.tablemappings.add("product_description", "product_description"); //Create and fill a Data set for this dimension table, and get the resulting DataTable. DataSet ds = new DataSet(); HP Vertica Analytic Database (7.1.x) Page 289 of 401

290 da.fill(ds, 0, 0, "product_dimension"); DataTable dt = ds.tables[0]; //Bind parameters and add two rows to the table. DataRow dr = dt.newrow(); dr["product_key"] = ; dr["product_version"] = 5; dr["product_description"] = "New item 5"; dt.rows.add(dr); dr = dt.newrow(); dr["product_key"] = ; dr["product_version"] = 6; dr["product_description"] = "New item 6"; dt.rows.add(dr); //Extract the changes for the added rows. DataSet ds2 = ds.getchanges(); //Send the modifications to the server. int updatecount = da.update(ds2, "product_dimension"); //Merge the changes into the original Data set, and mark it up to date. ds.merge(ds2); ds.acceptchanges(); Console.WriteLine(updateCount + " updates made!"); catch (Exception e) Console.WriteLine(e.Message); _conn.close(); Using Batch Inserts and Prepared Statements You can load data in batches using a prepared statement with parameters. You can also use transactions to rollback the batch load if any errors are encountered. If you are loading large batches of data (more than 100MB), then consider using a direct batch insert. The following example details using data contained in arrays, parameters, and a transaction to batch load data. HP Vertica Analytic Database (7.1.x) Page 290 of 401

291 The test table used in the example is created with the command: create table test (id INT, username VARCHAR(24), VARCHAR(64), password VARCHAR(8)); Example Batch Insert Using Parameters and Transactions using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); // create arrays for column data int[] ids = 1, 2, 3, 4; string[] usernames = "user1", "user2", "user3", "user4"; string[] s = "[email protected]", "[email protected]","[email protected]","[email protected]" ; string[] passwords = "pass1", "pass2", "pass3", "pass4" ; // create counters for accepted and rejected rows int rows = 0; int rejrows = 0; bool error = false; // create the transaction VerticaTransaction txn = _conn.begintransaction(); // create the parametrized query and assign parameter types VerticaCommand command = _conn.createcommand(); command.commandtext = "insert into TEST @password)"; command.parameters.add(new VerticaParameter("id", VerticaType.BigInt)); command.parameters.add(new VerticaParameter("username", VerticaType.VarChar)); command.parameters.add(new VerticaParameter(" ", VerticaType.VarChar)); HP Vertica Analytic Database (7.1.x) Page 291 of 401

292 command.parameters.add(new VerticaParameter("password", VerticaType.VarChar)); // prepare the statement command.prepare(); // loop through the column arrays and insert the data for (int i = 0; i < ids.length; i++) command.parameters["id"].value = ids[i]; command.parameters["username"].value = usernames[i]; command.parameters[" "].value = s[i]; command.parameters["password"].value = passwords[i]; try rows += command.executenonquery(); catch (Exception e) Console.WriteLine("\nInsert failed - \n " + e.message + "\n"); ++rejrows; error = true; if (error) //roll back if errors Console.WriteLine("Errors. Rolling Back Transaction."); Console.WriteLine(rejRows + " rows rejected."); txn.rollback(); else //commit if no errors Console.WriteLine("No Errors. Committing Transaction."); txn.commit(); Console.WriteLine("Inserted " + rows + " rows. "); _conn.close(); HP Vertica Analytic Database (7.1.x) Page 292 of 401

293 Loading Batches Directly into ROS When loading large batches of data (more than 100MB or so), you should load the data directly into ROS containers. Inserting directly into ROS is more efficient for large loads than AUTO mode, since it avoids overflowing the WOS and spilling the remainder of the batch to ROS. Otherwise, the Tuple Mover has to perform a moveout on the data in the WOS, while subsequent data is directly written into ROS containers. This results in the data from your batch being segmented across containers. When you load data using AUTO mode, HP Vertica inserts the data first into the WOS. If the WOS is full, then HP Vertica inserts the data directly into ROS. See the COPY statement for more details. To directly load batches into ROS, set the DirectBatchInsert connection property to true. See Opening and Closing the Database Connection for details on all of the connection properties. When the DirectBatchInsert property is set to true, all batch inserts bypass the WOS and load directly into a ROS container. Example usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; builder.directbatchinsert = true; VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); //Perform some operations _conn.close(); Streaming Data Via ADO.NET There are two options to stream data from a file on the client to your HP Vertica database through ADO.NET: HP Vertica Analytic Database (7.1.x) Page 293 of 401

294 Use the VerticaCopyStream ADO.NET class to stream data in an object-oriented manner Execute a COPY SQL statement to stream the data The topics in this section explain how to use these options. Streaming From the Client Via VerticaCopyStream The VerticaCopyStream class lets you stream data from the client system to an HP Vertica database. It lets you use the SQL COPY statement directly without having to copy the data to a host in the database cluster first by substituting one or more data stream(s) for STDIN. Notes: Use Transactions and disable auto commit on the copy command for better performance. Disable auto commit using the copy command with the 'no commit' modifier. You must explicitly disable commits. Enabling transactions does not disable autocommit when using VerticaCopyStream. The copy command used with VerticaCopyStream uses copy syntax. VerticaCopyStream.rejects is zeroed every time execute is called. If you want to capture the number of rejects, assign the value of VerticaCopyStream.rejects to another variable before calling execute again. You can add multiple streams using multiple AddStream() calls. Example usage: The following example demonstrates using VerticaCopyStream to copy a file stream into HP Vertica. using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using System.IO; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) //configure connection properties HP Vertica Analytic Database (7.1.x) Page 294 of 401

295 VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder (); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); try using (_conn) //start a transaction VerticaTransaction txn = _conn.begintransaction(); //create a table for this example VerticaCommand command = new VerticaCommand("DROP TABLE IF EXISTS copy_table", _conn); command.executenonquery(); command.commandtext = "CREATE TABLE copy_table (Last_Name char(50), " + "First_Name char(50), char(50), " + "Phone_Number char(15))"; command.executenonquery(); //create a new filestream from the data file string filename = "C:/customers.txt"; Console.WriteLine("\n\nLoading File: " + filename); FileStream inputfile = File.OpenRead(filename); //define the copy command string copy = "copy copy_table from stdin record terminator E'\n' delimiter ' '" + " enforcelength " + " no commit"; //create a new copy stream instance with the connection and copy statement VerticaCopyStream vcs = new VerticaCopyStream(_conn, copy); //start the VerticaCopyStream process vcs.start(); //add the file stream vcs.addstream(inputfile, false); //execute the copy HP Vertica Analytic Database (7.1.x) Page 295 of 401

296 vcs.execute(); //finish stream and write out the list of inserted and rejected rows long rowsinserted = vcs.finish(); IList<long> rowsrejected = vcs.rejects; // does not work when rejected or exceptions defined Console.WriteLine("Number of Rows inserted: " + rowsinserted); Console.WriteLine("Number of Rows rejected: " + rowsrejected.count); if (rowsrejected.count > 0) for (int i = 0; i < rowsrejected.count; i++) Console.WriteLine("Rejected row #0 is row 1", i, rowsrejected[i]); //commit the changes txn.commit(); catch (Exception e) Console.WriteLine(e.Message); //close the connection _conn.close(); Using Copy with ADO.NET To use COPY with ADO.NET, just execute a COPY statement and the path to the source file on the client system. This method is simpler than using the VerticaCopyStream class. However, you may prefer using VerticaCopyStream if you have many files to copy to the database or if your data comes from a source other than a local file (streamed over a network connection, for example). The following example code demonstrates using COPY to copy a file from the client to the database. It is the same as the code shown in Bulk Loading Using the COPY Statement and the path to the data file is on the client system, rather than on the server. To load data that is stored on a database node, use a VerticaCommand object to create a COPY command: 1. Create a connection to the database through the node on which the data file is stored. 2. Create a command object using the connection. HP Vertica Analytic Database (7.1.x) Page 296 of 401

297 VerticaCommand command = _conn.createcommand(); 3. Copy data. The following is an example of using the COPY command to load data. It uses the LOCAL modifier to copy a file local to the client issuing the command. command.commandtext = "copy lcopy_table from '/home/dbadmin/customers.txt'" + " record terminator E'\n' delimiter ' '" + " enforcelength "; Int32 insertedrows = command.executenonquery(); Console.WriteLine(insertedRows + " inserted."); Example Usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using System.IO; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) //configure connection properties VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder(); builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); try using (_conn) //start a transaction VerticaTransaction txn = _conn.begintransaction(); HP Vertica Analytic Database (7.1.x) Page 297 of 401

298 //create a table for this example VerticaCommand command = new VerticaCommand("DROP TABLE IF EXISTS lcopy_table", _conn); command.executenonquery(); command.commandtext = "CREATE TABLE IF NOT EXISTS lcopy_table (Last_ Name char(50), " + "First_Name char(50), char(50), " + "Phone_Number char(15))"; command.executenonquery(); //define the copy command command.commandtext = "copy lcopy_table from '/home/dbadmin/customers.txt'" + " record terminator E'\n' delimiter ' '" + " enforcelength " + " no commit"; //execute the copy Int32 insertedrows = command.executenonquery(); Console.WriteLine(insertedRows + " inserted."); //commit the changes txn.commit(); catch (Exception e) Console.WriteLine("Exception: " + e.message); //close the connection _conn.close(); Handling Messages (ADO.NET) You can capture info and warning messages that HP Vertica provides to the ADO.NET driver by using the InfoMessage event on the VerticaConnection delegate class. This class captures messages that are not severe enough to force an exception to be triggered, but might still provide information that can benefit your application. HP Vertica Analytic Database (7.1.x) Page 298 of 401

299 To Use the VerticaInfoMessageEventHander class: 1. Create a method to handle the message sent from the even handler: static void conn_infomessage(object sender, VerticaInfoMessageEventArgs e) Console.WriteLine(e.SqlState + ": " + e.message); 2. Create a connection and register a new VerticaInfoMessageHandler delegate for the InfoMessage event: _conn.infomessage += new VerticaInfoMessageEventHandler(conn_InfoMessage); 3. Execute your queries. If a message is generated, then the event handle function is run. 4. You can unsubscribe from the event with the following command: _conn.infomessage -= new VerticaInfoMessageEventHandler(conn_InfoMessage); Example usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program // define message handler to deal with messages static void conn_infomessage(object sender, VerticaInfoMessageEventArgs e) Console.WriteLine(e.SqlState + ": " + e.message); static void Main(string[] args) //configure connection properties (); VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder HP Vertica Analytic Database (7.1.x) Page 299 of 401

300 builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); //create message handler instance by subscribing it to the InfoMessage event of the connection _conn.infomessage += new VerticaInfoMessageEventHandler(conn_InfoMessage); //create and execute the command VerticaCommand cmd = _conn.createcommand(); cmd.commandtext = "drop table if exists faketable"; cmd.executenonquery(); //close the connection _conn.close(); This examples displays the following when run: 00000: Nothing was dropped Getting Table Metadata (ADO.Net) You can get the table metadata by using the GetSchema() method on a connection and loading the metadata into a DataTable: DataTable table = _conn.getschema("tables", new string[] database_name, schema_name, table_name, table_type ); For example: DataTable table = _conn.getschema("tables", new string[] null, null, null, "SYSTEM TABLE" ); database_name, schema_name, table_name can be set to null, be a specific name, or use a LIKE pattern. table_type can be one of: HP Vertica Analytic Database (7.1.x) Page 300 of 401

301 "SYSTEM TABLE" "TABLE" "GLOBAL TEMPORARY" "LOCAL TEMPORARY" "VIEW" null If table_type is set to null, then the metadata for all metadata tables is returned. Example Usage: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Data; using Vertica.Data.VerticaClient; namespace ConsoleApplication class Program static void Main(string[] args) //configure connection properties (); VerticaConnectionStringBuilder builder = new VerticaConnectionStringBuilder builder.host = " "; builder.database = "VMart"; builder.user = "dbadmin"; //open the connection VerticaConnection _conn = new VerticaConnection(builder.ToString()); _conn.open(); //create a new data table containing the schema //the last argument can be "SYSTEM TABLE", "TABLE", "GLOBAL TEMPORARY", // "LOCAL TEMPORARY", "VIEW", or null for all types DataTable table = _conn.getschema("tables", new string[] null, null, null, "SYSTEM TABLE" ); //print out the schema HP Vertica Analytic Database (7.1.x) Page 301 of 401

302 foreach (DataRow row in table.rows) foreach (DataColumn col in table.columns) Console.WriteLine("0 = 1", col.columnname, row[col]); Console.WriteLine("============================"); //close the connection _conn.close(); ADO.NET Data Types his table details the mapping between HP Vertica data type's and.net and ADO.NET data types..net Framework Type ADO.NET DbType VerticaType HP Vertica Data Type VerticaDataReader getter Boolean Boolean Bit Boolean GetBoolean() byte[] Binary Binary VarBinary LongVarBinary Binary VarBinary LongVarBinary GetBytes() Note: The limit for LongVarBinary is 32 Million bytes. If you attempt to insert more than the limit during a batch transfer for any one row, then they entire batch fails. Verify the size of the data before attempting to insert a LongVarBinary during a batch. HP Vertica Analytic Database (7.1.x) Page 302 of 401

303 .NET Framework Type ADO.NET DbType VerticaType HP Vertica Data Type VerticaDataReader getter Datetime DateTime Date Time TimeStamp Date Time TimeStamp GetDateTime() Note: The Time portion of the DateTime object for vertica dates is set to DateTime.MinValu e. Previously, VerticaType.DateT ime was used for all date/time types. VerticaType.DateT ime still exists for backwards compatibility, but now there are more specific VerticaTypes for each type. DateTimeOffset DateTimeOffset TimestampTZ TimeTZ TimestampTZ TimeTZ GetDateTimeOffset() Note: The Date portion of the DateTime is set to DateTime.MinValu e Decimal Decimal Numeric Numeric GetDecimal() Double Double Double Double Precision GetDouble() Note: HP Vertica Double type uses a default precision of 53. Int64 Int64 BigInt Integer GetInt64() HP Vertica Analytic Database (7.1.x) Page 303 of 401

304 .NET Framework Type ADO.NET DbType VerticaType HP Vertica Data Type VerticaDataReader getter TimeSpan Object 13 Interval Types 13 Interval Types GetInterval() Note: There are 13 VerticaType values for the 13 types of intervals. The specific VerticaType used determines the conversion rules that the driver applies. Year/Month intervals represented as 365/30 days String String Varchar LongVarChar Varchar LongVarChar GetString() String StringFixedLengt Char Char GetString() Object Object N/A N/A GetValue() HP Vertica Analytic Database (7.1.x) Page 304 of 401

305 Programming Python Client Applications HP Vertica provides an ODBC driver so applications can connect to the HP Vertica database. In order to use Python with HP Vertica, you must install the pyodbc module and an HP Vertica ODBC driver on the machine where Python is installed. See Python Prerequisites. Python on Linux Most Linux distributions come with Python preinstalled. If you want a more recent version, you can download and build it from the source code, though sometimes RPMs are also available. See the Python Web site and click an individual release for details. See also Python documentation. To determine the Python version on your Linux operating systems, type the following at a command prompt: # python -V The system returns the version; for example: Python Python on Windows Python is not required to run natively on Windows operating systems, so it is not preinstalled. The ActiveState Web site distributes a free Windows installer for Python called ActivePython. If you need installation instructions for Windows, see Using Python on Windows at python.org. Python on Windows at diveintopython.org provides installation instructions for both the ActivePython and python.org packages. HP Vertica Analytic Database (7.1.x) Page 305 of 401

306 Python and Unicode When you are using Python, be sure that all of your components are using the same unicode text encoding. By default, the DSN Parameter ColumnsAsChar causes the ODBC driver to report CHAR and VARCHAR values as SQL_WCHAR. The driver returns these values to the driver manager in the encoding expected by the driver manager, as controlled by the DriverManagerEncoding parameter in vertica.ini. Similarly, your Python application must use the encoding expected by the driver manager. If any of these components use different encodings, your output can become garbled. The Python Driver Module (pyodbc) The native python driver is not supported. Before you can connect to HP Vertica using Python, you need the pyodbc module, which communicates with iodbc/unixodbc driver on UNIX operating systems and the ODBC Driver Manager for Windows operating systems. The pyodbc module is an open source, MIT-licensed Python module, letting you use ODBC to connect to almost any database from Windows, Linux, Mac OS/X, and other operating systems. HP Vertica supports multiple versions of pyodbc. See Python Prerequisites for additional details. Download the source distribution from the pyodbc Web site, unpack it and build it. Note that you need the unixodbc development package (in addition to the regular build tools) to build pyodbc. For example, on RedHat/CentOS run: yum install unixodbc-devel, and on Ubuntu run:sudo apt-get install unixodbc-dev. See the pyodbc wiki for detailed instructions. External Resources Python Database API Specification v2.0 Python documentation Configuring the ODBC Run-Time Environment on Linux To configure the ODBC run-time environment on Linux: 1. Create the odbc.ini file if it does not already exist. 2. Add the ODBC driver directory to the LD_LIBRARY_PATH system environment variable: export LD_LIBRARY_PATH=/path-to-vertica-odbc-driver:$LD_LIBRARY_PATH Important: If you skip Step 2, the ODBC manager cannot find the driver in order to load it. HP Vertica Analytic Database (7.1.x) Page 306 of 401

307 These steps are relevant only for unixodbc and iodbc. See their respective documentation for details on odbc.ini. See Also unixodbc Web site iodbc Web site Querying the Database Using Python The example session below uses pyodbc with the HP Vertica ODBC driver to connect Python to the HP Vertica database. Note: SQLFetchScroll and SQLFetch functions cannot be mixed together in iodbc code. When using pyodbc with the iodbc driver manager, skip cannot be used with the fetchall, fetchone, and fetchmany functions. Example Script The following example script shows how to query HP Vertica using Python 3, pyodbc, and an ODBC DSN. import pyodbc cnxn = pyodbc.connect("dsn=verticadsn", ansi=true) cursor = cnxn.cursor() # create table cursor.execute("create TABLE TEST(" "C_ID INT," "C_FP FLOAT," "C_VARCHAR VARCHAR(100)," "C_DATE DATE, C_TIME TIME," "C_TS TIMESTAMP," "C_BOOL BOOL)") cursor.execute("insert INTO test VALUES(1,1.1,'abcdefg ',' ','23:12:34',' :00:09','t')") cursor.execute("insert INTO test VALUES(2,3.4,'zxcasdqwe ',' ','00:00:01',' :19:19','f')") cursor.execute("select * FROM TEST") rows = cursor.fetchall() for row in rows: print(row, end='\n') cursor.execute("drop TABLE TEST CASCADE") cursor.close() cnxn.close() The resulting output displays: (2, 3.4, 'zxcasdqwe ', datetime.date(1991, 11, 11), datetime.time(0, 0, 1), HP Vertica Analytic Database (7.1.x) Page 307 of 401

308 datetime.datetime(1981, 12, 31, 19, 19, 19), False) (1, 1.1, 'abcdefg ', datetime.date(1901, 1, 1), datetime.time(23, 12, 34), datetime.datetime(1901, 1, 1, 9, 0, 9), True) Notes SQLPrimaryKeys returns the table name in the primary (pk_name) column for unnamed primary constraints. For example: Unnamed primary key: CREATE TABLE schema.test(c INT PRIMARY KEY); SQLPrimaryKeys "TABLE_CAT", "TABLE_SCHEM", "TABLE_NAME", "COLUMN_NAME", "KEY_SEQ", "PK_NAME" <Null>, "SCHEMA", "TEST", "C", 1, "TEST" Named primary key: CREATE TABLE schema.test(c INT CONSTRAINT pk_1 PRIMARY KEY); SQLPrimaryKeys "TABLE_CAT", "TABLE_SCHEM", "TABLE_NAME", "COLUMN_NAME", "KEY_SEQ", "PK_NAME" <Null>, "SCHEMA", "TEST", "C", 1, "PK_1" HP recommends that you name your constraints. See Also Loading Data Through ODBC HP Vertica Analytic Database (7.1.x) Page 308 of 401

309 Programming Perl Client Applications The Perl programming language has a Database Interface module (DBI) that creates a standard interface for Perl scripts to interact with databases. The interface module relies on Database Driver modules (DBDs) to handle all of the database-specific communication tasks. The result is an interface that provides a consistent way for Perl scripts to interact with many different types of databases. Your Perl script can interact with HP Vertica using the Perl DBI module along with the DBD::ODBC database driver to interface to HP Vertica's ODBC driver. See the CPAN pages for Perl's DBI and DBD::ODBC modules for detailed documentation. The topics in this chapter explain how to: Configure Perl to access HP Vertica Connect to HP Vertica Query data stored in HP Vertica Insert data into HP Vertica Perl Client Prerequisites In order run a Perl client script that connects to HP Vertica, your client system must have: The HP Vertica ODBC drivers installed and configured. See Installing the HP Vertica Client Drivers for details. A Data Source Name (DSN) containing the connection parameters for your HP Vertica. See Creating an ODBC Data Source Name. (Optionally, your Perl script can connect to HP Vertica without using a DSN as described in Connecting From Perl Without a DSN). A supported version of Perl installed The DBI and DBD::ODBC Perl modules (see below) HP Vertica Analytic Database (7.1.x) Page 309 of 401

310 Supported Perl Versions HP Vertica supports Perl versions 5.8 and Versions later than 5.10 may also work. Perl on Linux Most Linux distributions come with Perl preinstalled. See your Linux distribution's documentation for details of installing and configuring its Perl package is it is not already installed. To determine the Perl version on your Linux operating systems, type the following at a command prompt: # perl -v The system returns the version; for example: This is perl, v built for x86_64-linux-thread-multi Perl on Windows Perl is not installed by default on Windows platforms. There are several different Perl packages you can download and install on your Windows system: ActivePerl by Activestate is a commercially-supported version of Perl for Windows platforms. Strawberry Perl is an open-source port of Perl for Windows. The Perl Driver Modules (DBI and DBD::ODBC) Before you can connect to HP Vertica using Perl, your Perl installation needs to have the Perl Database Interface module (DBI) and the Database Driver for ODBC (DBD::ODBC). These modules communicate with iodbc/unixodbc driver on UNIX operating systems or the ODBC Driver Manager for Windows operating systems. HP Vertica supports the following Perl modules: DBI version (DBI tar.gz) DBD::ODBC version 1.22 (DBD-ODBC-1.22.tar.gz) Later versions of DBI and DBD::ODBC may also work. DBI is installed by default with many Perl installations. You can test whether it is installed by executing the following command on the Linux or Windows command line: # perl -e "use DBI;" If the command exits without printing anything, then DBI is installed. If it prints an error, such as: HP Vertica Analytic Database (7.1.x) Page 310 of 401

311 Can't locate DBI.pm contains: /usr/local/lib64/perl5/usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5.) at -e line 1. BEGIN failed--compilation aborted at -e line 1. then DBI is not installed. Similarly, you can see if DBD::ODBC is installed by executing the command: # perl -e "use DBD::ODBC;" You can also run the following Perl script to determine if DBI and DBD::ODBC are installed. If they are, the script lists any available DSNs. #!/usr/bin/perl use strict; # Attempt to load the DBI module in an eval using require. Prevents # script from erroring out if DBI is not installed. eval require DBI; DBI->import(); ; if ($@) # The eval failed, so DBI must not be installed print "DBI module is not installed\n"; else # Eval was successful, so DBI is installed print "DBI Module is installed\n"; # List the drivers that DBI knows about. = DBI->available_drivers; print "Available Drivers: \n"; foreach my $driver (@drivers) print "\t$driver\n"; # See if DBD::ODBC is installed by searching driver array. if (grep print "\ndbd::odbc is installed.\n"; # List the ODBC data sources (DSNs) defined on the system print "Defined ODBC Data Sources:\n"; = DBI->data_sources('ODBC'); foreach my $dsn (@dsns) print "\t$dsn\n"; else print "DBD::ODBC is not installed\n"; The exact output of the above code will depend on the configuration of your system. The following is an example of running the code on a Windows computer: DBI Module is installed HP Vertica Analytic Database (7.1.x) Page 311 of 401

312 Available Drivers: ADO DBM ExampleP File Gofer ODBC Pg Proxy SQLite Sponge mysql DBD::ODBC is installed. Defined ODBC Data Sources: dbi:odbc:dbase Files dbi:odbc:excel Files dbi:odbc:ms Access Database dbi:odbc:verticadsn Installing Missing Perl Modules If Perl's DBI or DBD::ODBC modules are not installed on your client system, you must install them before your Perl scripts can connect to HP Vertica. How you install modules depends on your Perl configuration: For most Perl installations, you use the cpan command to install modules. If the cpan command alias isn't installed on your system, you can try to start CPAN by using the command: perl -MCPAN -e shell Some Linux distributions provide Perl modules as packages that can be installed with the system package manager (such as yum or apt). See your Linux distribution's documentation for details. On ActiveState Perl for Windows, you use the Perl Package Manager (PPM) program to install Perl modules. See the Activestate's PPM documentation for details. Note: Installing Perl modules usually requires administrator or root privileges. If you do not have these permissions on your client system, you need to ask your system administrator to install these modules for you. Connecting to Using Perl You use the Perl DBI module's connect function to connect to HP Vertica. This function takes a required data source string argument and optional arguments for the username, password, and connection attributes. HP Vertica Analytic Database (7.1.x) Page 312 of 401

313 The data source string must start with "dbi:odbc:", which tells the DBI module to use the DBD::ODBC driver to connect to HP Vertica. The remainder of the string is interpreted by the DBD::ODBC driver. It usually contains the name of a DSN that contains the connection information needed to connect to your HP Vertica database. For example, to tell the DBD::ODBC driver to use the DSN named VerticaDSN, you use the data source string: "dbi:odbc:verticadsn" The username and password parameters are optional. However, if you do not supply them (or just the username for a passwordless account) and they are not set in the DSN, attempting to connect always fails. The connect function returns a database handle if it connects to HP Vertica. If it does not, it returns undef. In that case, you can access the DBI module's error string property ($DBI::errstr) to get the error message. Note: By default, the DBI module prints an error message to STDERR whenever it encounters an error. If you prefer to display your own error messages or handle errors in some other manner, you may want to disable these automatic messages by setting DBI's PrintError connection attribute to false. See Setting Perl DBI Connection Attributes for details. Otherwise, users may see two error messages: the one that DBI prints automatically, and the one that your script prints on its own. The following example demonstrates connecting to HP Vertica using a DSN named VerticaDSN. The call to connect supplies a username and password. After connecting, it calls the database handle's disconnect function, which closes the connection. #!/usr/bin/perl -w use strict; use DBI; # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123"); unless (defined $dbh) # Conection failed. die "Failed to connect: $DBI::errstr"; print "Connected!\n"; $dbh->disconnect(); Setting ODBC Connection Parameters in Perl To set ODBC connection parameters, replace the DSN name with a semicolon delimited list of parameter name and value pairs in the source data string. Use the DSN parameter to tell DBD::ODBC which DSN to use, then add in other the other ODBC parameters you want to set. For example, the following code connects using a DSN named VerticaDSN and sets the connection's locale to en_gb. #!/usr/bin/perl -w use strict; HP Vertica Analytic Database (7.1.x) Page 313 of 401

314 use DBI; # Instead of just using the DSN name, use name and value pairs. my $dbh = DBI->connect("dbi:ODBC:DSN=VerticaDSN;Locale=en_ GB","ExampleUser","password123"); unless (defined $dbh) # Conection failed. die "Failed to connect: $DBI::errstr"; print "Connected!\n"; $dbh->disconnect(); See Data Source Name (DSN) Connection Parameters for a list of the connection parameters you can set in the source data string. Setting Perl DBI Connection Attributes The Perl DBI module has attributes that you can use to control the behavior of its database connection. These attributes are similar to the ODBC connection parameters (in several cases, they duplicate each other's functionality). The DBI connection attributes are a cross-platform way of controlling the behavior of the database connection. You can set the DBI connection attributes when establishing a connection by passing the DBI connect function a hash containing attribute and value pairs. For example, to set the DBI connection attribute AutoCommit to false, you would use: # Create a hash that holds attributes for the connection my $attr = AutoCommit => 0; # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); See the DBI documentation's Database Handle Attributes section for a full description of the attributes you can set on the database connection. After your script has connected, it can access and modify the connection attributes through the database handle by using it as a hash reference. For example: print "The AutoCommit attribute is: ". $dbh->autocommit. "\n"; The following example demonstrates setting two connection attributes: RaiseError controls whether the DBI driver generates a Perl error if it encounters a database error. Usually, you set this to true (1) if you want your Perl script to exit if there is a database error. AutoCommit controls whether statements automatically commit their transactions when they complete. DBI defaults to HP Vertica's default AutoCommit value of true. Always set AutoCommit to false (0) when bulk loading data to increase database efficiency. #!/usr/bin/perl HP Vertica Analytic Database (7.1.x) Page 314 of 401

315 use strict; use DBI; # Create a hash that holds attributes for the connection my $attr = RaiseError => 1, # Make database errors fatal to script AutoCommit => 0, # Prevent statements from committing # their transactions. ; # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); if (defined $dbh->err) # Connection failed. die "Failed to connect: $DBI::errstr"; print "Connected!\n"; # The database handle lets you access the connection attributes directly: print "The AutoCommit attribute is: ". $dbh->autocommit. "\n"; print "The RaiseError attribute is: ". $dbh->raiseerror. "\n"; # And you can change values, too... $dbh->autocommit = 1; print "The AutoCommit attribute is now: ". $dbh->autocommit. "\n"; $dbh->disconnect(); The example outputs the following when run: Connected!The AutoCommit attribute is: 0 The RaiseError attribute is: 1 The AutoCommit attribute is now: 1 Connecting From Perl Without a DSN If you do not want to set up a Data Source Name (DSN) for your database, you can supply all of the information Perl's DBD::ODBC driver requires to connect to your HP Vertica database in the data source string. This source string must the DRIVER= parameter that tells DBD::ODBC which driver library to use in order to connect. The value for this parameter is the name assigned to the driver by the client system's driver manager: On Windows, the name assigned to the HP Vertica ODBC driver by the driver manager is Vertica. On Linux and other UNIX-like operating systems, the HP Vertica ODBC driver's name is assigned in the system's odbcinst.ini file. For example, if your /etc/odbcint.ini contains the following: [HPVertica] Description = HP Vertica ODBC Driver Driver = /opt/vertica/lib64/libverticaodbc.so HP Vertica Analytic Database (7.1.x) Page 315 of 401

316 you would use the name HPVertica. See Creating an ODBC DSN for Linux, Solaris, AIX, and HP-UX for more information about the odbcinst.ini file. You can take advantage of Perl's variable expansion within strings to use variables for most of the connection properties as the following example demonstrates. #!/usr/bin/perl use strict; use DBI; my $server='verticahost'; my $port = '5433'; my $database = 'VMart'; my $user = 'ExampleUser'; my $password = 'password123'; # Connect without a DSN by supplying all of the information for the connection. # The DRIVER value on UNIX platforms depends on the entry in the odbcinst.ini # file. my $dbh = DBI->connect("dbi:ODBC:DRIVER=Vertica;Server=$server;". "Port=$port;Database=$database;UID=$user;PWD=$password") or die "Could not connect to database: ". DBI::errstr; print "Connected!\n"; $dbh->disconnect(); Note: Surrounding the driver name with braces ( and ) in the source string is optional. Executing Statements Using Perl Once your Perl script has connected to HP Vertica (see Connecting to Using Perl), it can execute simple statements that return a value rather than a result set by using the Perl DBI module's do function. You usually use this function to execute DDL statements or data loading statements such as COPY (see Using COPY LOCAL to Load Data in Perl). #!/usr/bin/perl use strict; use DBI; # Disable autocommit my $attr = AutoCommit => 0; # Open a connection using a DSN. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); unless (defined $dbh) # Conection failed. die "Failed to connect: $DBI::errstr"; # You can use the do function to perform DDL commands. # Drop any existing table. $dbh->do("drop TABLE IF EXISTS TEST CASCADE;"); # Create a table to hold data. $dbh->do("create TABLE TEST( \ C_ID INT, \ C_FP FLOAT,\ HP Vertica Analytic Database (7.1.x) Page 316 of 401

317 C_VARCHAR VARCHAR(100),\ C_DATE DATE, C_TIME TIME,\ C_TS TIMESTAMP,\ C_BOOL BOOL)"); # Commit changes and exit. $dbh->commit(); $dbh->disconnect(); Note: The do function returns the number of rows that were affected by the statement (or -1 if the count of rows doesn't apply or is unavailable). Usually, the only time you need to consult this value is after you deleted a number of rows or if you used a bulk load command such as COPY. You use other DBI functions instead of do to perform batch inserts and selects (see Batch Loading Data Using Perl and Querying Using Perl for details). Batch Loading Data Using Perl To load large batches of data into HP Vertica using Perl: 1. Set DBI's AutoCommit connection attribute to false to improve the batch load speed. See Setting Perl DBI Connection Attributes for an example of disabling AutoCommit. 2. Call the database handle's prepare function to prepare a SQL INSERT statement that contains placeholders for the data values you want to insert. For example: # Prepare an INSERT statement for the test table $sth = $dbh->prepare("insert into test values(?,?,?,?,?,?,?)"); The prepare function returns a statement handle that you will use to insert the data. 3. Assign data to the placeholders. There are several ways to do this. The easiest is to populate an array with a value for each placeholder in your INSERT statement. 4. Call the statement handle's execute function to insert a row of data into HP Vertica. The return value of this function call lets you know whether HP Vertica accepted or rejected the row. 5. Repeat steps 3 and 4 until you have loaded all of the data you need to load. 6. Call the database handle's commit function to commit the data you inserted. The following example demonstrates inserting a small batch of data by populating an array of arrays with data, then looping through it and inserting each row. #!/usr/bin/perl use strict; use DBI; # Create a hash reference that holds a hash of parameters for the # connection. my $attr = AutoCommit => 0, # Turn off autocommit HP Vertica Analytic Database (7.1.x) Page 317 of 401

318 PrintError => 0 # Turn off automatic error printing. # This is handled manually. ; # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); if (defined DBI::err) # Conection failed. die "Failed to connect: $DBI::errstr"; print "Connection AutoCommit state is: ". $dbh->autocommit. "\n"; # Create table to hold inserted data $dbh->do("drop TABLE IF EXISTS TEST CASCADE;") or die "Could not drop table"; $dbh->do("create TABLE TEST( \ C_ID INT, \ C_FP FLOAT,\ C_VARCHAR VARCHAR(100),\ C_DATE DATE, C_TIME TIME,\ C_TS TIMESTAMP,\ C_BOOL BOOL)") or die "Could not create table"; # Populate an array of arrays with values. One of these rows contains # data that will not be sucessfully inserted. Another contains an # undef value, which gets inserted into the database as a NULL. = ( [1,1.111,'Hello World!',' ','01:01:01',' :01:01','t'], [2, ,'How are you?',' ','02:02:02',' :02:02','f'], ['bad value', ,'how are you?',' ','02:02:02',' :02:02','f'], [4, ,undef,' ','02:02:02',' :02:02','f'], ); # Create a prepared statement to use parameters for inserting values. my $sth = $dbh->prepare_cached("insert into test values(?,?,?,?,?,?,?)"); my $rowcount = 0; # Count # of rows # Loop through the arrays to insert values foreach my $tuple (@data) $rowcount++; # Insert the row my $retval = $sth->execute(@$tuple); # See if the row was successfully inserted. if ($retval == 1) # Value of 1 means the row was inserted (1 row was affected by insert) print "Row $rowcount successfully inserted\n"; else print "Inserting row $rowcount failed"; # Error message is not set on some platforms/versions of DBUI. Check to # ensure a message exists to avoid getting an unitialized var warning. if ($sth->err()) print ": ". $sth->errstr(); print "\n"; # Commit changes. With AutoCommit off, you need to use commit for batched # data to actually be committed into the database. If your Perl script exits HP Vertica Analytic Database (7.1.x) Page 318 of 401

319 # without committing its data, HP Vertica rolls back the transaction and the # data is not committed. $dbh->commit(); $dbh->disconnect(); The previous example displays the following when successfully run: Connection AutoCommit state is: 0 Row 1 successfully inserted Row 2 successfully inserted Inserting row 3 failed with error [Vertica][VerticaDSII] (20) An error occurred during query execution: Row rejected by server; see server log for details (SQL-01000) Row 4 successfully inserted Note that one of the rows was not inserted because it contained a string value that could not be stored in an integer column. See Conversions Between Perl and Data Types for details of data type handling in Perl scripts that communicate with HP Vertica. Using COPY LOCAL to Load Data in Perl If you have delimited files (for example, a file with comma-separated values) on your client system that you want to load into HP Vertica, you can use the COPY LOCAL statement to directly load the file's contents into HP Vertica instead of using Perl to read, parse, and then batch insert the data. You execute a COPY LOCAL statement to load the file from the local filesystem. The result of executing the statement is the number of rows that were successfully inserted. The following example code demonstrates loading a file named data.txt and located in the same directory as the Perl file into HP Vertica using a COPY LOCAL statement. #!/usr/bin/perl use strict; use DBI; # Filesystem path handling module use File::Spec; # Create a hash reference that holds a hash of parameters for the # connection. my $attr = AutoCommit => 0; # Turn off AutoCommit # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr) or die "Failed to connect: $DBI::errstr"; print "Connected!\n"; # Drop any existing table. $dbh->do("drop TABLE IF EXISTS Customers CASCADE;"); # Create a table to hold data. $dbh->do("create TABLE Customers( \ ID INT, \ FirstName VARCHAR(100),\ LastName VARCHAR(100),\ VARCHAR(100),\ Birthday DATE)"); # Find the absolute path to the data file located in the current working HP Vertica Analytic Database (7.1.x) Page 319 of 401

320 # directory and named data.txt my $currdir = File::Spec->rel2abs(File::Spec->curdir()); my $datafile = File::Spec->catfile($currDir, 'data.txt'); print "Loading file $datafile\n"; # Load local file using copy local. Return value is the # of rows affected # which equates to the number of rows inserted. my $rows = $dbh->do("copy Customers FROM LOCAL '$datafile' DIRECT") or die $dbh->errstr; print "Copied $rows rows into database.\n"; $dbh->commit(); # Prepare a query to get the first 15 rows of the results my $sth = $dbh->prepare("select * FROM Customers WHERE ID < 15 \ ORDER BY ID"); $sth->execute() or die "Error querying table: ". $dbh->errstr; # Pre-declare variable to hold result row used in format statement. # Use Perl formats to pretty print the output. Declare the heading for the # form. format STDOUT_TOP = ID First Last Birthday == ===== ==== ===== ========. # The Perl write statement will output a formatted line with values from the array. See for details. format # Loop through result rows while we have them while (@row = $sth->fetchrow_array()) write; # Format command does the work of extracting the columns from # array and writing them out to STDOUT. # Call commit to prevent Perl from complaining about uncommitted transactions # when disconnecting $dbh->commit(); $dbh->disconnect(); The data.txt file is a text file containing a row of data on each line. The columns are delimited by pipe ( ) characters. This is the default format that the COPY command accepts, which makes the COPY LOCAL statement in the example code simple. See the COPY statement entry in the SQL Reference Manual for handling data files that are in different formats. Here is an example of the content in this file: 1 Georgia Gomez [email protected] Abdul Alexander [email protected] Nigel Contreras [email protected] Gray Holt [email protected] Candace Bullock [email protected] Matthew Dotson [email protected] Haviva Hopper [email protected] Stewart Sweeney [email protected] Allen Rogers [email protected] Trevor Dillon [email protected] Leroy Ashley [email protected] HP Vertica Analytic Database (7.1.x) Page 320 of 401

321 12 Elmo Malone Laurel Ball Zeus Phillips Alexis Mclean The example code produces the following output when run on a large sample file: Connected! Loading file /home/dbadmin/perl/data.txt Copied rows into database. ID First Last Birthday == ===== ==== ===== ======== 1 Georgia Gomez [email protected] Abdul Alexander [email protected] Nigel Contreras [email protected] Gray Holt [email protected] Candace Bullock [email protected] Matthew Dotson [email protected] Haviva Hopper [email protected] Stewart Sweeney [email protected] Allen Rogers [email protected] Trevor Dillon [email protected] Leroy Ashley [email protected] Elmo Malone [email protected] Laurel Ball [email protected] Zeus Phillips [email protected] Note: Loading a single, large data file into HP Vertica through a single data connection is less efficient than loading a number of smaller files onto multiple nodes in parallel. Loading onto multiple nodes prevents any one node from becoming a bottleneck. Querying Using Perl To query HP Vertica using Perl: 1. Prepare a query statement using the Perl DBI module's prepare function. This function returns a statement handle that you use to execute the query and get the result set. 2. Execute the prepared statement by calling the execute function on the statement handle. 3. Retrieve the results of the query from the statement handle using one of several methods, such as calling the statement handle's fetchrow_array function to retrieve a row of data, or fetchall_array to get an array of arrays containing the entire result set (not a good idea if your result set may be very large!). The following example demonstrates querying the table created by the example shown in Batch Loading Data Using Perl. It executes a query to retrieve all of the content of the table, then repeatedly calls the statement handle's fetchrow_array function to get rows of data in an array. It repeats this process until fetchrow_array returns undef, which means that there are no more rows to be read. HP Vertica Analytic Database (7.1.x) Page 321 of 401

322 #!/usr/bin/perl use strict; use DBI; my $attr = RaiseError => 1 ; # Make errors fatal to the Perl script. # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); # Prepare a query to get the content of the table my $sth = $dbh->prepare("select * FROM TEST ORDER BY C_ID ASC"); # Execute the query by calling execute on the statement handle $sth->execute(); # Loop through result rows while we have them, getting each row as an array while = $sth->fetchrow_array()) # array contains the column values for this row of data # Loop through the column values foreach my $column (@row) if (!defined $column) # NULLs are signaled by undefs. Set to NULL for clarity $column = "NULL"; print "$column\t"; # Output the column separated by a tab print "\n"; $dbh->disconnect(); The example prints the following when run: Hello World! :01: :01: How are you? :02: :02: NULL :02: :02:02 0 Binding Variables to Column Values Another method of retrieving the query results is to bind variables to columns in the result set using the statement handle's bind_columns function. You may find this method convenient if you need to perform extensive processing on the returned data, since your code can use variables rather than array references to access the data. The following example demonstrates binding variables to the result set, rather than looping through the row and column values. #!/usr/bin/perl use strict; use DBI; my $attr = RaiseError => 1 ; # Make SQL errors fatal to the Perl script. # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN32","ExampleUser","password123", $attr); # Prepare a query to get the content of the table my $sth = $dbh->prepare("select * FROM TEST ORDER BY C_ID ASC"); $sth->execute(); # Create a set of variables to bind to the column values. my ($C_ID, $C_FP, $C_VARCHAR, $C_DATE, $C_TIME, $C_TS, $C_BOOL); # Bind the variable references to the columns in the result set. HP Vertica Analytic Database (7.1.x) Page 322 of 401

323 $sth->bind_columns(\$c_id, \$C_FP, \$C_VARCHAR, \$C_DATE, \$C_TIME, \$C_TS, \$C_BOOL); # Now, calling fetch() to get a row of data updates the values of the bound # variables. Continue calling fetch until it returns undefined. while ($sth->fetch()) # Note, you should always check that values are defined before using them, # since NULL values are translated into Perl as undefined. For this # example, just check the VARCHAR column for undefined values. if (!defined $C_VARCHAR) $C_VARCHAR = "NULL"; # Just print values separated by tabs. print "$C_ID\t$C_FP\t$C_VARCHAR\t$C_DATE\t$C_TIME\t$C_TS\t$C_BOOL\n"; $dbh->disconnect(); The output of this example is identical to the output of the previous example. Preparing, Querying, and Returning a Single Row If you expect a single row as the result of a query (for example, when you execute a COUNT (*) query), you can use the DBI module's selectrow_array function to combine executing a statement and retrieving an array as a result. The following example shows using selectrow_array to execute and get the results of the SHOW LOCALE statement. It also demonstrates changing the locale using the do function. #!/usr/bin/perl use strict; use DBI; my $attr = RaiseError => 1 ; # Make SQL errors fatal to the Perl script. # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); # Demonstrate setting/getting locale. # Use selectrow_array to combine preparing a statement, executing it, and # getting an array as a result. = $dbh->selectrow_array("show LOCALE;"); # The locale name is the 2nd column (array index 1) in the result set. print "Locale: $localerv[1]\n"; # Use do() to execute a SQL statement to set the locale. $dbh->do("set LOCALE TO en_gb"); # Get the locale = $dbh->selectrow_array("show LOCALE;"); print "Locale is now: $localerv[1]\n"; $dbh->disconnect(); The result of running the example is: Locale: en_us@collation=binary (LEN_KBINARY) Locale is now: en_gb (LEN) HP Vertica Analytic Database (7.1.x) Page 323 of 401

324 Conversions Between Perl and Data Types Perl is a loosely-typed programming language that does not assign specific data types to values. It converts between string and numeric values based on the operations being performed on the values. For this reason, Perl has little problem extracting most string and numeric data types from HP Vertica. All interval data types (DATE, TIMESTAMP, etc.) are converted to strings. You can use several different date and time handling Perl modules to manipulate these values in your scripts. HP Vertica NULL values translate to Perl's undefined (undef) value. When reading data from columns that can contain NULL values, you should always test whether a value is defined before using it. When inserting data into HP Vertica, Perl's DBI module attempts to coerce the data into the correct format. By default, it assumes column values are VARCHAR unless it can determine that they are some other data type. If given a string value to insert into a column that has an integer or numeric data type, DBI attempts to convert the string's contents to the correct data type. If the entire string can be converted to a value of the appropriate data type, it inserts the value into the column. If not, inserting the row of data fails. DBI transparently converts integer values into numeric or float values when inserting into column of FLOAT, NUMERIC, or similar data types. It converts numeric or floating values to integers only when there would be no loss of precision (the value to the right of the decimal point is 0). For example, it can insert the value 3.0 into an INTEGER column since there is no loss of precision when converting the value to an integer. It cannot insert 3.1 into an INTEGER column, since that would result in a loss of precision. It returns an error instead of truncating the value to 3. The following example demonstrates some of the conversions that the DBI module performs when inserting data into HP Vertica. #!/usr/bin/perl use strict; use DBI; # Create a hash reference that holds a hash of parameters for the # connection. my $attr = AutoCommit => 0, # Turn off autocommit PrintError => 0 # Turn off print error. Manually handled ; # Open a connection using a DSN. Supply the username and password. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123", $attr); if (defined DBI::err) # Conection failed. die "Failed to connect: $DBI::errstr"; print "Connection AutoCommit state is: ". $dbh->autocommit. "\n"; # Create table to hold inserted data $dbh->do("drop TABLE IF EXISTS TEST CASCADE;"); $dbh->do("create TABLE TEST( \ C_ID INT, \ C_FP FLOAT,\ C_VARCHAR VARCHAR(100),\ HP Vertica Analytic Database (7.1.x) Page 324 of 401

325 C_DATE DATE, C_TIME TIME,\ C_TS TIMESTAMP,\ C_BOOL BOOL)"); # Populate an array of arrays with values. = ( # Start with matching data types [1,1.111,'Matching datatypes',' ','01:01:01',' :01:01','t'], # Force floats -> int and int -> float. [2.0,2,"Ints <-> floats",' ','02:02:02',' :02:02',1], # Float -> int *only* works when there is no loss of precision. # this row will fail to insert: [3.1,3,"float -> int with trunc?",' ','03:03:03',' :03:03',1], # String values are converted into numbers ["4","4.4","Strings -> numbers", ' ','04:04:04',,' :04:04',0], # String -> numbers only works if the entire string can be # converted into a number ["5 and a half","5.5","strings -> numbers", ' ', '05:05:05',,' :05:05',0], # Number are converted into string values automatically, # assuming they fit into the column width. [6,6.6, , ' ','06:06:06',,' :06:06',0], # There are some variations in the accepted date strings [7,7.7,'Date/time formats', '07/07/2007','07:07:07',,' :07:07',1], ); # Create a prepared statement to use parameters for inserting values. my $sth = $dbh->prepare_cached("insert into test values(?,?,?,?,?,?,?)"); my $rowcount = 0; # Count # of rows # Loop through the arrays to insert values foreach my $tuple (@data) $rowcount++; # Insert the row my $retval = $sth->execute(@$tuple); # See if the row was successfully inserted. if ($retval == 1) # Value of 1 means the row was inserted (1 row was affected by insert) print "Row $rowcount successfully inserted\n"; else print "Inserting row $rowcount failed with error ". $sth->state. " ". $sth->errstr. "\n"; # Commit the data $dbh->commit(); # Prepare a query to get the content of the table $sth = $dbh->prepare("select * FROM TEST ORDER BY C_ID ASC"); $sth->execute() or die "Error: ". $dbh->errstr; # Need to pre-declare to use in the format statement. # Use Perl formats to pretty print the output. format STDOUT_TOP = Int Float VarChar Date Time Timestamp Bool === ===== ================== ========== ======== ================ ==== HP Vertica Analytic Database (7.1.x) Page 325 of 401

326 . format # Loop through result rows while we have them while (@row = $sth->fetchrow_array()) write; # Format command does the work of extracting the columsn from # the array. # Commit to stop Perl complaining about in-progress transactions. $dbh->commit(); $dbh->disconnect(); The example produces the following output when run: Connection AutoCommit state is: 0 Row 1 successfully inserted Row 2 successfully inserted Inserting row 3 failed with error [Vertica][VerticaDSII] (20) An error occurred during query execution: Row rejected by server; see server log for details (SQL-01000) Row 4 successfully inserted Inserting row 5 failed with error [Vertica][VerticaDSII] (20) An error occurred during query execution: Row rejected by server; see server log for details (SQL-01000) Row 6 successfully inserted Row 7 successfully inserted Int Float VarChar Date Time Timestamp Bool === ===== ================== ========== ======== ================ ==== Matching datatypes :01: : Ints <-> floats :02: : Strings -> numbers :04: : :06: : Date/time formats :07: :07 1 Perl Unicode Support Perl supports Unicode data with some caveats. See the perlunicode and the perlunitut (Perl Unicode tutorial) manual pages for details. (Be sure to see the copies of these manual pages included with the version of Perl installed on your client system, as the support for Unicode has changed in recent versions of Perl.) Perl DBI and DBD::ODBC also support Unicode, however DBD::ODBC must be compiled with Unicode support. See the DBD::ODBC documentation for details. You can check the DBD::ODBC-specific connection attribute named odbc_has_unicode to see if Unicode support is enabled in the driver. The following example Perl script demonstrates directly inserting UTF-8 strings into HP Vertica and then reading them back. The example writes a text file with the output, since there are may problems displaying Unicode characters in terminal windows or consoles. #!/usr/bin/perl use strict; HP Vertica Analytic Database (7.1.x) Page 326 of 401

327 use DBI; # Open a connection using a DSN. my $dbh = DBI->connect("dbi:ODBC:VerticaDSN","ExampleUser","password123"); unless (defined $dbh) # Conection failed. die "Failed to connect: $DBI::errstr"; # Output to a file. Displaying Unicode characters to a console or terminal # window has many problems. This outputs a UTF-8 text file that can # be handled by many Unicode-aware text editors: open OUTFILE, '>:utf8', "unicodeout.txt"; # See if the DBD::ODBC driver was compiled with Unicode support. If this returns # 1, your Perl script will get get strings from the driver with the UTF-8 # flag set on them, ensuring that Perl handles them correctly. print OUTFILE "Was DBD::ODBC compiled with Unicode support? ". $dbh->odbc_has_unicode. "\n"; # Create a table to hold VARCHARs $dbh->do("drop TABLE IF EXISTS TEST CASCADE;"); # Create a table to hold data. Remember that the width of the VARCHAR column # is the number of bytes set aside to store strings, which often does not equal # the number of characters it can hold when it comes to Unicode! $dbh->do("create TABLE test( C_VARCHAR VARCHAR(100) )"); print OUTFILE "Inserting data...\n"; # Use Do to perform simple inserts $dbh->do("insert INTO test VALUES('Hello')"); # This string contains several non-latin accented characters and symbols, encoded # with Unicode escape notation. They are converted by Perl into UTF-8 characters $dbh->do("insert INTO test VALUES('My favorite band is ". "\NU+00DCml\NU+00E4\NU+00FCt \NU+00D6v\NU+00EBrk\NU+00EFll". " \NU+263A')"); # Some Chinese (Simplified) characters. This again uses escape sequence # that Perl translates into UTF-8 characters. $dbh->do("insert INTO test VALUES('\x4F60\x597D')"); print OUTFILE "Getting data...\n"; # Prepare a query to get the content of the table my $sth = $dbh->prepare_cached("select * FROM test"); # Execute the query by calling execute on the statement handle $sth->execute(); # Loop through result rows while we have them while = $sth->fetchrow_array()) # Loop through the column values foreach my $column (@row) print OUTFILE "$column\t"; print OUTFILE "\n"; close OUTFILE; $dbh->disconnect(); Viewing the unicodeout.txt file in a UTF-8-capable text editor or viewer displays: Was DBD::ODBC compiled with Unicode support? 1 Inserting data... Getting data... HP Vertica Analytic Database (7.1.x) Page 327 of 401

328 My favorite band is Ümläüt Övërkïll 你 好 Hello Note: Terminal windows and consoles often have problems properly displaying Unicode characters. That is why the example writes the output to a text file. With some text editors, you may need to manually set the encoding of the text file to UTF-8 in order for the characters to properly appear (and the font used to display text must have a full Unicode character set). If the character still do not show up, it may be that your version of DBD::ODBC was not compiled with UTF-8 support. See Also Unicode Character Encoding Additional Linux ODBC Driver Configuration Settings HP Vertica Analytic Database (7.1.x) Page 328 of 401

329 Programming PHP Client Applications You can connect to HP Vertica through PHP-ODBC using the Unix ODBC or iodbc library. In order to use PHP with HP Vertica, you must install the following packages (and their dependencies): php php-odbc php-pdo UnixODBC (if you are using the Unix ODBC driver) libiodbc (if you are using the iodbc driver) PHP on Linux PHP is available with most Linux operating systems as a module for the Apache web server. Check your particular Linux repository for PHP RPMs or Debian packages. You can also build PHP from source. See the PHP web site for documentation and source downloads. PHP on Windows PHP is available for windows for both the Apache and IIS web servers. You can download PHP for Windows and view installation instructions at the PHP web site. The PHP ODBC Drivers PHP supports both the UnixODBC drivers and iodbc drivers. Both drivers use PHP's ODBC database abstraction layer. Setup You must read Programming ODBC Client Applications before connecting to HP Vertica through PHP. The following example ODBC configuration entries detail the typical settings required for PHP ODBC connections. The driver location assumes you have copied the HP Vertica drivers to /usr/lib64. Example odbc.ini [ODBC Data Sources] VerticaDSNunixodbc = exampledb VerticaDNSiodbc = exampledb2 HP Vertica Analytic Database (7.1.x) Page 329 of 401

330 [VerticaDSNunixodbc] Description = VerticaDSN Unix ODBC driver Driver = /usr/lib64/libverticaodbc.so Database = Telecom Servername = localhost UserName = dbadmin Password = Port = 5433 [VerticaDSNiodbc] Description = VerticaDSN iodbc driver Driver = /usr/lib64/libverticaodbc.so Database = Telecom Servername = localhost UserName = dbadmin Password = Port = 5433 Example odbcinst.ini # Vertica [VerticaDSNunixodbc] Description = VerticaDSN Unix ODBC driver Driver = /usr/lib64/libverticaodbc.so [VerticaDNSiodbc] Description = VerticaDSN iodbc driver Driver = /usr/lib64/libverticaodbc.so [ODBC] Threading = 1 Verify the HP Vertica UnixODBC or iodbc Library Verify the HP Vertica UnixODBC library can load all dependant libraries with the following command (assuming you have copies the libraries to /usr/lib64): For example: ldd /usr/lib64/libverticaodbc.so You must resolve any "not found" libraries before continuing. Test Your ODBC Connection Test your ODBC connection with the following. isql -v VerticaDSN HP Vertica Analytic Database (7.1.x) Page 330 of 401

331 PHP Unicode Support PHP does not offer native Unicode support. PHP only supports a 256-character set. However, PHP provides the UTF-8 functions utf8_encode() and utf8_decode() to provide some basic Unicode functionality. See the PHP manual for strings for more details about PHP and Unicode. Querying the Database Using PHP The example script below details the use of PHP ODBC functions to connect to the HP Vertica Analytics Platform. <?php # Turn on error reporting error_reporting(e_error E_WARNING E_PARSE E_NOTICE); # A simple function to trap errors from queries function errortrap_odbc($conn, $sql) if(!$rs = odbc_exec($conn,$sql)) echo "<br/>failed to execute SQL: $sql<br/>". odbc_errormsg($conn); else echo "<br/>success: ". $sql; return $rs; # Connect to the Database $dsn = "VerticaDSNunixodbc"; $conn = odbc_connect($dsn,'','') or die ("<br/>connection ERROR"); echo "<p>connected with DSN: $dsn</p>"; # Create a table $sql = "CREATE TABLE TEST( C_ID INT, C_FP FLOAT, C_VARCHAR VARCHAR(100), C_DATE DATE, C_TIME TIME, C_TS TIMESTAMP, C_BOOL BOOL)"; $result = errortrap_odbc($conn, $sql); # Insert data into the table with a standard SQL statement $sql = "INSERT into test values(1,1.1,'abcdefg ',' ','23:12:34 ',' :00:09','t')"; $result = errortrap_odbc($conn, $sql); # Insert data into the table with odbc_prepare and odbc_execute $values = array(2,2.28,'abcdefg ',' ','23:12:34',' :00:09','t'); $statement = odbc_prepare($conn,"insert into test values(?,?,?,?,?,?,?)"); if(!$result = odbc_execute($statement, $values)) echo "<br/>odbc_execute Failed!"; else echo "<br/>success: odbc_execute."; # Get the data from the table and display it $sql = "SELECT * FROM TEST"; if($result = errortrap_odbc($conn, $sql)) HP Vertica Analytic Database (7.1.x) Page 331 of 401

332 echo "<pre>"; while($row = odbc_fetch_array($result) ) print_r($row); echo "</pre>"; # Drop the table and projection $sql = "DROP TABLE TEST CASCADE"; $result = errortrap_odbc($conn, $sql); # Close the ODBC connection odbc_close($conn);?> Example Output The following is the example output from the script. Success: CREATE TABLE TEST( C_ID INT, C_FP FLOAT, C_VARCHAR VARCHAR(100), C_DATE DATE, C_ TIME TIME, C_TS TIMESTAMP, C_BOOL BOOL) Success: INSERT into test values(1,1.1,'abcdefg ',' ','23:12:34 ',' :00:09','t') Success: odbc_execute. Success: SELECT * FROM TEST Array ( [C_ID] => 1 [C_FP] => 1.1 [C_VARCHAR] => abcdefg [C_DATE] => [C_TIME] => 23:12:34 [C_TS] => :00:09 [C_BOOL] => 1 ) Array ( [C_ID] => 2 [C_FP] => 2.28 [C_VARCHAR] => abcdefg [C_DATE] => [C_TIME] => 23:12:34 [C_TS] => :12:34 [C_BOOL] => 1 ) Success: DROP TABLE TEST CASCADE HP Vertica Analytic Database (7.1.x) Page 332 of 401

333 Management API Management API The Management API is a REST API that you can use to view and manage HP Vertica databases with scripts or applications that understand REST and JSON. The response format for all requests is JSON. General API Information GET / GET api Returns the agent-specific information useful for version checking and service discovery. Returns a list of api objects and properties. Backup and Restore GET backups POST backups/:config_script_base GET backups/:config_script_base/:archive_id POST restore/:archive_id Returns all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the /opt/vertica/config directory. Creates a new backup as defined by the given vbr configuration script base (filename without the.ini extension). Returns details for a specific backup archive. Restores a backup. Databases GETdatabases POST databases GET databases/:database_name PUT databases/:database_name DELETE databases/:database_name GET databases/:database_name/configuration Returns a list of databases, their properties, and current status. Creates a new database by supplying a valid set of parameters. Returns details about a specific database. Starts, stops, rebalances, or runs Workload Analyzer on a database. Deletes an existing database. Returns the current configuration parameters from the database. HP Vertica Analytic Database (7.1.x) Page 333 of 401

334 Management API PUT databases/:database_name/configuration GET databases/:database_name/hosts POST databases/:database_name/hosts DELETE databases/:database_ name/hosts/:host_id POST databases/:database_name/hosts/:host_ id/process DELETE databases/:database_ name/hosts/:host_id/process POST databases/:database_name/hosts/:host_ id/replace_with/:host_id_new GET databases/:database_name/license PUT databases/:database_name/license GET databases/:database_name/licenses GET databases/:database_name/nodes GET databases/:database_name/nodes/:node_id POST databases/:database_name/process GET databases/:database_name/process DELETE databases/:database_name/process POST databases/:database_ name/rebalance/process POST databases/:database_name/wla/process Sets one or more configuration parameters in the database. Returns hosts details for a specific database. Adds a new host to the database. Removes a host from the database. Starts the database process on a specific host. Stops the database on a specific host. Replaces a host with a standby host in the database. Returns the HP Vertica license that the specified database is using. Upgrades the license in the database. Returns all the feature licenses that the specified database is using. Returns a list of nodes for the specified database. Returns details on a specific node for the specified database. Starts the specified database. Returns the state of the database as either UP or DOWN. Stops the specified database on all hosts. Rebalances the specified database. This option can have a long run time. Runs the analyze workload action against the specified database.this option can have a long run time. Hosts GET hosts Returns a list of hosts in this cluster. HP Vertica Analytic Database (7.1.x) Page 334 of 401

335 Management API GET hosts/:hostid Returns details for a specific host in this cluster. Jobs GET jobs GET jobs/:id Returns a list of jobs the agent is tracking, along with their current status and exit codes. Returns the details (the saved output) for a specific job. Licenses POST licenses GET licenses Uploads and applies a new license to this cluster. Returns the license field that databases created on this cluster use. Nodes GET nodes GET nodes/:nodeid Returns a list of nodes in this cluster. Returns details for a specific node in this cluster. Webhooks GET webhooks POST webhooks/subscribe DELETE webhooks/:subscriber_id Returns a list of active webhooks. Creates a new webhook. Deletes an existing webhook. curl curl is a command-line tool and application library used to transfer data to or from a server. It uses URL syntax, such as HTTP and HTTPS. All API requests sent to an HP Vertica server must be made using HTTPS. A request made using HTTP will fail. There are four HTTP requests that can be passed using curl to call API methods: Request Description HP Vertica Analytic Database (7.1.x) Page 335 of 401

336 Management API GET PUT POST DELETE Retrieves data. Updates data. Creates new data. Deletes data. Syntax curl Options -h --help Lists all available command-line options. -H --header Allows you to use custom headers in your command. This is useful for sending a request that requires a VerticaAPIKEY. curl -H "VerticaApiKey: ValidAPIKey" -k --insecure Allows SSL connections without certificate validation. curl -k -X --request Specifies the custom request used when communicating with a server. curl -X REQUEST Can be one of the following values: GET PUT POST DELETE Note: If no request is specified, curl automatically defaults to the GET request. There are many more options available to add to your curl query. For a comprehensive list with descriptions, visit the curl Documentation Website. HP Vertica Analytic Database (7.1.x) Page 336 of 401

337 Management API VerticaAPIKey The Management API requires an authentication key, named VerticaAPIKEY, to access some API resources. You can manage API keys by using the apikeymgr command-line tool. usage: apikeymgr [-h] [--user REQUESTOR] [--app APPLICATION] [--delete] [--create] [--update] [--migrate] [--secure restricted,normal,admin] [--list] API key management tool optional arguments: -h, --help show this help message and exit --user REQUESTOR The name of the person requesting the key --app APPLICATION The name of the application that will use the key --delete Delete the key for the given R & A --create Create a key for the given R & A --update Update a key for the given R & A --migrate migrate the keyset to the latest format --secure restricted,normal,admin Set the keys security level --list List all the keys known Example Request To create a new VerticaAPIKEY for the dbadmin user with admin access, enter the following: $ apikeymgr --user dbadmin --app vertica --create --secure admin Response: Requestor : dbadmin Application: vertica API Key : ValidAPIKey Synchronizing cluster... HP Vertica Analytic Database (7.1.x) Page 337 of 401

338 Management API GET / Returns API version information and a list of links to child resources for the Management API. Resource URL Authentication Not required. Parameters None. Example Request GET Response: "body": "mime-types": [ "default", "application/vertica.database.configuration.json-v2", "application/json", "application/vertica.nodes.json-v2", "default", "application/json", "default", "application/json", "application/vertica.jobs.json-v2", "default", "application/vertica.hosts.json-v2", "application/json", "default", "application/vertica.hosts.json-v2", "application/json", "default", "application/json", "application/vertica.host.json-v2", "default", "application/vertica.hosts.json-v2", "application/json", HP Vertica Analytic Database (7.1.x) Page 338 of 401

339 Management API "application/vertica.nodes.json-v2", "default", "application/json", "default", "application/json", "application/vertica.database.json-v2", "default", "application/vertica.hosts.json-v2", "application/json", "default", "application/vertica.hosts.json-v2", "application/json", "default", "application/json", "application/vertica.databases.json-v2", "application/vertica.nodes.json-v2", "default", "application/json", "application/vertica.agent.json-v2", "default", "application/json", "default", "application/vertica.users.json-v2", "application/json" ], "version": "7.1.0", "href": "/", "links": [ "/databases", "/hosts", "/nodes", "/licenses", "/webhooks", "/backups", "/restore", "/jobs" ], "mime-type": "application/vertica.agent.json-v2" HP Vertica Analytic Database (7.1.x) Page 339 of 401

340 Management API GET api Displays a list of all Management API commands and a brief description for each command. You can also access an HTML version of this information at Replace <NODE> with the URL of a cluster node. Resource URL Authentication Not required. Parameters None. Example Request GET Response: [ "accepts":, "description": " Returns the agent specific information useful for version checking and service discovery ", "method": "GET", "params": [], "route": "/", "accepts":, "description": " build the list of cluster objects and properties and return it as a JSON formatted array ", "method": "GET", "params": [], "route": "/api", "accepts":, "description": " list all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the /opt/vertica/config directory. ", HP Vertica Analytic Database (7.1.x) Page 340 of 401

341 Management API "method": "GET", "params": [], "route": "/backups", "accepts":, "description": " create a new backup as defined by the given vbr configuration script base (filename minus the.ini extenstion) ", "method": "POST", "params": [], "route": "/backups/:config_script_base", "accepts":, "description": " get the detail for a specific backup archive ", "method": "GET", "params": [], "route": "/backups/:config_script_base/:archive_id", "accepts":, "description": " delete a backup based on the config ini file script", "method": "DELETE", "params": [], "route": "/backups/:config_script_base/:backup_id", "accepts":, "description": " build the list of databases, their properties, and current status ( from cache ) and return it as a JSON formatted array ", "method": "GET", "params": [], "route": "/databases", "accepts":, "description": " Create a new database by supplying a valid set of parameters ", "method": "POST", "params": [ "name : name of the database to create", "passwd : password used by the database administrative user", "only : optional list of hostnames to include in database", "exclude : optional list of hostnames to exclude from the database", "catalog : directory used for the vertica catalog", "data : directory used for the initial vertica storage location", "port : port the database will listen on (default 5433)" ], "route": "/databases", "accepts":, "description": " Retrieve the database properties structure ", "method": "GET", "params": [], "route": "/databases/:database_name", "accepts":, HP Vertica Analytic Database (7.1.x) Page 341 of 401

342 Management API "description": " Control / alter a database values using the PUT http method ", "method": "PUT", "params": [ "action : value one of start stop rebalance wla" ], "route": "/databases/:database_name", "accepts":, "description": " Delete an existing database ", "method": "DELETE", "params": [], "route": "/databases/:database_name", "accepts":, "description": " retrieve the current parameters from the database. if its running return 503 Service Unavailable ", "method": "GET", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/configuration", "accepts":, "description": " set a list of parameters in the database. if its not running return 503 Service Unavailable ", "method": "PUT", "params": [ "user_id : vertica database username", "passwd : vertica database password", "parameter : value vertica parameter/key combo" ], "route": "/databases/:database_name/configuration", "accepts":, "description": " list the hosts that are current used by this database", "method": "GET", "params": [], "route": "/databases/:database_name/hosts", "accepts":, "description": " add a host to the database ", "method": "POST", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/hosts", "accepts":, "description": " remove a host from the database", "method": "DELETE", HP Vertica Analytic Database (7.1.x) Page 342 of 401

343 Management API "params": [], "route": "/databases/:database_name/hosts/:host_id", "accepts":, "description": " start the database process on a specific host participating in this database.", "method": "POST", "params": [], "route": "/databases/:database_name/hosts/:host_id/process", "accepts":, "description": " run the stop action against the given database for a specific host", "method": "DELETE", "params": [], "route": "/databases/:database_name/hosts/:host_id/process", "accepts":, "description": " replace a host with a standby host in the database ", "method": "POST", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/hosts/:host_id/replace_with/:host_id_new", "accepts":, "description": " return the vertica license that this database is using ", "method": "GET", "params": [ "user_id : vertica database user", "passwd : vertica databse password" ], "route": "/databases/:database_name/license", "accepts":, "description": " this method upgrades the license in the database by using the license in /opt/vertica/config/share ", "method": "PUT", "params": [ "user_id : vertica database user", "passwd : vertica databse password" ], "route": "/databases/:database_name/license", "accepts":, "description": " return all the feature licenses that this database is using ", "method": "GET", "params": [ "user_id : vertica database user", "passwd : vertica databse password" ], HP Vertica Analytic Database (7.1.x) Page 343 of 401

344 Management API "route": "/databases/:database_name/licenses", "accepts":, "description": " build the list of nodes for a given database, their properties, and current status ( from cache ) and return it as a JSON formatted array ", "method": "GET", "params": [], "route": "/databases/:database_name/nodes", "accepts":, "description": " build the list of nodes for a given database, their properties, and current status and return it as a JSON formatted array ", "method": "GET", "params": [], "route": "/databases/:database_name/nodes/:node_id", "accepts":, "description": " run the start action against the given database ", "method": "POST", "params": [ "epoch : start the database from this epoch", "include : start the database on these hosts only" ], "route": "/databases/:database_name/process", "accepts":, "description": " easy way to see if a database is running -- returns state of UP or DOWN", "method": "GET", "params": [], "route": "/databases/:database_name/process", "accepts":, "description": " run the stop action against the given database ", "method": "DELETE", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/process", "accepts":, "description": " run the rebalance data action against the given database - could be very long running! ", "method": "POST", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/rebalance/process", HP Vertica Analytic Database (7.1.x) Page 344 of 401

345 Management API "accepts":, "description": " Retrieve the database properties structure ", "method": "GET", "params": [], "route": "/databases/:database_name/status", "accepts":, "description": " run the analyze workload action against the given database - could be very long running! ", "method": "POST", "params": [ "user_id : vertica database username", "passwd : vertica database password" ], "route": "/databases/:database_name/wla/process", "accepts":, "description": " build a list of nodes in the cluster independent of their database associations ", "method": "GET", "params": [], "route": "/hosts", "accepts":, "description": " lists the properties of a given host in the cluster by calling the RESTful service on that agent. ", "method": "GET", "params": [], "route": "/hosts/:hostid", "accepts":, "description": " Returns a list of jobs the agent is tracking along with their current status and exit codes ", "method": "GET", "params": [], "route": "/jobs", "accepts":, "description": " Deletes a specific job by canceling any outstanding activity associated with it. ", "method": "DELETE", "params": [], "route": "/jobs/:id", "accepts":, "description": " Returns the details (the saved output) for a specific job ", "method": "GET", "params": [], "route": "/jobs/:id", "accepts":, HP Vertica Analytic Database (7.1.x) Page 345 of 401

346 Management API "description": " POST your vertica license to this url using HTTP file upload format. ", "method": "POST", "params": [ "license : the file to upload (use html form post format)" ], "route": "/licenses", "accepts":, "description": " list the license fiel that will be used by databases created on this cluster found in /opt/vertica/config/share/license.key ", "method": "GET", "params": [], "route": "/licenses", "accepts":, "description": " build a list of nodes in the topology independent of their database associations ", "method": "GET", "params": [], "route": "/nodes", "accepts":, "description": " build a list of nodes in the topology independent of their database associations ", "method": "GET", "params": [], "route": "/nodes/:nodeid", "accepts":, "description": " restore a backup given then archive id as defined via the 'GET' method ", "method": "POST", "params": [], "route": "/restore/:archive_id", "accepts":, "description": " delete a subscription from this agent. ", "method": "DELETE", "params": [], "route": "/webhooks/:subscriber_id", "accepts":, "description": " post a request with a callback url to subscribe to events from this agent. Returns a subscription_id that can be used to unsubscribe from the subscription_id ", "method": "POST", "params": [ "url : full url to the callback resource" ], "route": "/webhooks/subscribe" HP Vertica Analytic Database (7.1.x) Page 346 of 401

347 Management API ] HP Vertica Analytic Database (7.1.x) Page 347 of 401

348 Management API GET backups Returns a list of all backups created for vbr configuration (*.ini) files that reside in /opt/vertica/config and provides details about each backup. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: [, "backups": [ "backup": "backup3_ _114852", "epoch": "61", "hosts": "v_vmart_node0001( )", "objects": "" ], "config_file": "/opt/vertica/config/backup3.ini", "num_backups": 1 "backups": [ "backup": "backup_ _113737", "epoch": "61", "hosts": "v_vmart_node0001( )", "objects": "", HP Vertica Analytic Database (7.1.x) Page 348 of 401

349 Management API ] "backup": "backup_archive _113645", "epoch": "60", "hosts": "v_vmart_node0001( )", "objects": "" ], "config_file": "/opt/vertica/config/backup.ini", "num_backups": 2 HP Vertica Analytic Database (7.1.x) Page 349 of 401

350 Management API POST backups/:config_script_base Creates a new backup job for the backup defined in the vbr.py configuration script :config_ script_base. The vbr.py configuration script must reside in /opt/vertica/configuration. The :config_script_base value does not include the.ini filename extention. To determine valid :config_script_base values, see GET backups. Returns a job ID that you can use to determine the status of the job. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request POST Response: "id": "CreateBackup-VMart ", "url": "/jobs/createbackup-vmart " HP Vertica Analytic Database (7.1.x) Page 350 of 401

351 Management API GET backups/:config_script_base/:archive_id Returns details on a specific backup. You must provide the :config_script_base. This value is the name of a vbr.py config file (without the.ini filename extension) that resides in /opt/vertica/config. The :archive_id is the value of the backup field that the GET backups command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "backup": "backup3_ _123254", "config_file": "/opt/vertica/config/backup3.ini", "epoch": "62", "hosts": "v_vmart_node0001( )", "objects": "" HP Vertica Analytic Database (7.1.x) Page 351 of 401

352 Management API POST restore/:archive_id Creates a new restore job to restore the database from the backup archive identified by :archive_ id. The :archive_id is the value of a backup field that the GET backups command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request POST Response: "id": "RestoreBackup-VMart ", "url": "/jobs/restorebackup-vmart " HP Vertica Analytic Database (7.1.x) Page 352 of 401

353 Management API GETdatabases Returns a list of databases, their current status, and database properties. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET An example of the full request using curl: curl -H "VerticaApiKey: ValidAPIKey" Response: "body": [ "href": "/databases/vmart", "mime-type": [ "application/vertica.database.json-v2" ], "name": "VMart", "port": "5433", "status": "UP", "href": "/databases/testdb", "mime-type": [ "application/vertica.database.json-v2" ], "name": "testdb", HP Vertica Analytic Database (7.1.x) Page 353 of 401

354 Management API "port": "5433", "status": "DOWN" ], "href": "/databases", "links": [ "/:database_name" ], "mime-type": "application/vertica.databases.json-v2" HP Vertica Analytic Database (7.1.x) Page 354 of 401

355 Management API POST databases Creates a job to create a new database with the provided parameters. Important: You must stop any running databases on the nodes on which you want to create the new database. If you do not, database creation fails. Returns a job ID that can be used to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters name passwd only exclude catalog data Name of the database to create. Password for the new database. Optional list of hostnames to include in the database. By default, all nodes in the cluster are added to the database. Optional list of hostnames to exclude from the database. Path of the catalog directory. Path of the data directory. port Port where the database listens for client connections. Default is Example Request POST &catalog=%2fhome%2fdbadmin%2ftestdb &data=%2fhome%2fdbadmin%2ftestdb Response: HP Vertica Analytic Database (7.1.x) Page 355 of 401

356 Management API "jobid": "CreateDatabase-testDB :49: ", "resource": "/jobs/createdatabase-testdb :49: ", "userid": "dbadmin" HP Vertica Analytic Database (7.1.x) Page 356 of 401

357 Management API GET databases/:database_name Returns details about a specific database. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": "database_id": "VMart", "id": "VMart", "nodes": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003", "nodes_new": [ "catalog_base": "/home/dbadmin", "data_base": "/home/dbadmin", "host": " ", "id": "v_vmart_node0001", "catalog_base": "/home/dbadmin", "data_base": "/home/dbadmin", "host": " ", "id": "v_vmart_node0002", "catalog_base": "/home/dbadmin", "data_base": "/home/dbadmin", HP Vertica Analytic Database (7.1.x) Page 357 of 401

358 Management API "host": " ", "id": "v_vmart_node0003" ], "path": "/home/dbadmin/vmart", "port": "5433", "restartpolicy": "ksafe", "status": "UP", "href": "/databases/vmart", "links": [ "/configuration", "/hosts", "/license", "/nodes", "/process", "/rebalance/process", "/status", "/wla/process" ], "mime-type": "application/vertica.database.json-v2" HP Vertica Analytic Database (7.1.x) Page 358 of 401

359 Management API PUT databases/:database_name Creates a job to run the action specified by the action parameter against the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have normal level security or higher. Parameters user_id passwd action A database username. A password for the username. Can be one of the following values: start Start the database. stop Stop the database. rebalance Rebalance the database. wla Run Work Load Analyzer against the database. Example Request PUT id=dbadmin"&"passwd=vertica"&"action=stop Response: "id": "StopDatabase-testDB :28: ", HP Vertica Analytic Database (7.1.x) Page 359 of 401

360 Management API "url": "/jobs/stopdatabase-testdb :28: " HP Vertica Analytic Database (7.1.x) Page 360 of 401

361 Management API DELETE databases/:database_name Creates a job to delete (drop) an existing database on the cluster. To perform this operation, you must first stop the database. The :database_name is the value of the name field that the GETdatabases command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters None. Example Request DELETE Response: "id": "DropDatabase-TestDB :50: ", "url": "/jobs/dropdatabase-testdb :50: " HP Vertica Analytic Database (7.1.x) Page 361 of 401

362 Management API GET databases/:database_name/configuration Returns a list of configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. The password for the username. Example Request GET Response: This API call returns over100 configuration parameters.. The followin response is a small subset of the total amount returned. [ "catalog_value": "1", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "1", "database_value": "1", "default_value": "1", "description": "No of active partitions", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "ActivePartitionCount", "source": "DEFAULT" HP Vertica Analytic Database (7.1.x) Page 362 of 401

363 Management API,,,,, "catalog_value": "180", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "180", "database_value": "180", "default_value": "180", "description": "Interval between advancing the AHM (seconds)", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "AdvanceAHMInterval", "source": "DEFAULT" "catalog_value": "3", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "3", "database_value": "3", "default_value": "3", "description": "HDFS replication factor for Vertica data", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "HadoopFSReplication", "source": "DEFAULT" "catalog_value": "", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "", "database_value": "", "default_value": "", "description": "Path to the java binary for executing UDx written in Java", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "JavaBinaryForUDx", "source": "DEFAULT" "catalog_value": "80", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "80", "database_value": "80", "default_value": "80", "description": "The max amount of memory TopK(Heap) can use in MB", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "TopKHeapMaxMem", "source": "DEFAULT" HP Vertica Analytic Database (7.1.x) Page 363 of 401

364 Management API "catalog_value": "READ COMMITTED", "change_requires_restart": "f", "change_under_support_guidance": "f", "current_value": "READ COMMITTED", "database_value": "READ COMMITTED", "default_value": "READ COMMITTED", "description": "READ COMMITTED (Default) - Last epoch for reads and current epoch for writes. SERIALIZABLE - Current epoch for reads and writes", "groups": "", "is_mismatch": "f", "node_name": "ALL", "parameter_name": "TransactionIsolationLevel", "source": "DEFAULT" ] HP Vertica Analytic Database (7.1.x) Page 364 of 401

365 Management API PUT databases/:database_name/configuration Sets one or more configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Returns the parameter name, the requested value, and the result of the attempted change (Success or Failed). Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters user_id passwd parameter_name A database username. The password for the username. A parameter name and value combination for the parameter to be changed. Values must be URL encoded. You can include multiple name/value pairs to set multiple parameters with a single API call. Example Request PUT id=dbadmin"&"passwd=vertica "&"JavaBinaryForUDx=%2Fusr%2Fbin%2Fjava"&"TransactionIsolationLevel=SERIALIZABL E Response: [, "key": "JavaBinaryForUDx", "result": "Success", "value": "/usr/bin/java" HP Vertica Analytic Database (7.1.x) Page 365 of 401

366 Management API ] "key": "TransactionIsolationLevel", "result": "Success", "value": "SERIALIZABLE" HP Vertica Analytic Database (7.1.x) Page 366 of 401

367 Management API GET databases/:database_name/hosts Returns the hostname/ip address, node name, and UP/DOWN status of each host associated with the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "hostname": " ", "nodename": "v_vmart_node0001", "status": "UP", "ts": " T13:12: ", "hostname": " ", "nodename": "v_vmart_node0002", "status": "UP", "ts": " T13:12: ", "hostname": " ", "nodename": "v_vmart_node0003", "status": "UP", "ts": " T13:12: " HP Vertica Analytic Database (7.1.x) Page 367 of 401

368 Management API ], "href": "/databases/vmart/hosts", "links": [], "mime-type": "application/vertica.hosts.json-v2" HP Vertica Analytic Database (7.1.x) Page 368 of 401

369 Management API POST databases/:database_name/hosts Creates a job to add a host to the database identified by :database_name. This host must already be part of the cluster. The :database_name is the value of the name field that the GETdatabases command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters user_id passwd hostname A database username. The password for the username. The hostname to add to the database. Thishost must already be part of the cluster. Example Request POS T id=dbadmin"&"passwd=vertica Response: "id": "AddHostToDatabase-testDB :24: ", "url": "/jobs/addhosttodatabase-testdb :24: " HP Vertica Analytic Database (7.1.x) Page 369 of 401

370 Management API DELETE databases/:database_name/hosts/:host_ id Creates a job to remove the host identified by :host_id from the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. The :host_id is the value of the host field returned by GET databases/:database_name. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters user_id passwd A database username. A password for the username. Example Request DELET E id=dbadmin"&"passwd=vertica Response: "id": "RemoveHostFromDatabase-testDB :41: ", "url": "/jobs/removehostfromdatabase-testdb :41: " HP Vertica Analytic Database (7.1.x) Page 370 of 401

371 Management API POST databases/:database_name/hosts/:host_ id/process Creates a job to start the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GETdatabases command returns. The :host_id is the value of the host field returned by GET databases/:database_name. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request POST Response: "id": "StartDatabase-testDB :14: ", "url": "/jobs/startdatabase-testdb :14: " HP Vertica Analytic Database (7.1.x) Page 371 of 401

372 Management API DELETE databases/:database_name/hosts/:host_ id/process Creates a job to stop the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GETdatabases command returns. The :host_id is the value of the host field returned by GET databases/:database_name. Returns a job ID that can be used to determine the status of the job. See GET jobs. Note: If stopping the database on the hosts causes the database to no longer be k-safe, then the all database nodes may shut down. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request DELETE Response: "id": "StopDatabase-testDB :02: ", "url": "/jobs/stopdatabase-testdb :02: " HP Vertica Analytic Database (7.1.x) Page 372 of 401

373 Management API POST databases/:database_name/hosts/:host_ id/replace_with/:host_id_new Creates a job to replace the host identified by hosts/:host_id with the host identified by replace_with/:host_id. HP Vertica performs these operations for the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. The :host_id is the value of the host field as returned by GET databases/:database_name. You can find valid replacement hosts using GET hosts. The replacement host cannot already be part of the database. You must stop the vertica process on the host being replaced. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters user_id passwd A database username. A password for the username. Example Request PO ST with/ ?user_id=dbadmin"&"passwd=vertica Response: "id": "ReplaceNode-testDB :50: ", "url": "/jobs/replacenode-testdb :50: " HP Vertica Analytic Database (7.1.x) Page 373 of 401

374 Management API GET databases/:database_name/license Returns details about the database license being used by the database identified by :database_ name. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. The password for the username. Example Request GET Response: "body": "details": "assigned_to": "Vertica Systems, Inc.", "grace_period": 0, "is_ce": false, "is_unlimited": false, "name": "vertica", "not_after": "Perpetual", "not_before": " ", "last_audit": "audit_date": " :49: ", "database_size_bytes": " ", "license_size_bytes": " ", "usage_percent": " " HP Vertica Analytic Database (7.1.x) Page 374 of 401

375 Management API, "href": "/databases/vmart/license", "links": [], "mime-type": "application/vertica.license.json-v2" HP Vertica Analytic Database (7.1.x) Page 375 of 401

376 Management API GET databases/:database_name/licenses Returns details about all license being used by the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. The password for the username. Example Request GET Response: "body": [ "details": "assigned_to": "Vertica Systems, Inc.", "audit_date": " :35: ", "is_ce": "False", "name": "vertica", "node_restriction": "", "not_after": "Perpetual", "not_before": " ", "size": "500GB", "last_audit": "audit_date": " :35: ", "database_size_bytes": " ", "license_size_bytes": " ", "usage_percent": " " HP Vertica Analytic Database (7.1.x) Page 376 of 401

377 Management API, "details": "assigned_to": "Vertica Systems, Inc., FlexTable", "audit_date": " :35: ", "is_ce": "False", "name": "com.vertica.flextable", "node_restriction": "", "not_after": "Perpetual", "not_before": " ", "size": "500GB", "last_audit": "audit_date": " :35: ", "database_size_bytes": 0, "license_size_bytes": , "usage_percent": 0 ], "href": "/databases/vmart/licenses", "links": [], "mime-type": "application/vertica.features.json-v2" HP Vertica Analytic Database (7.1.x) Page 377 of 401

378 Management API GET databases/:database_name/nodes Returns a comma-separated list of node IDs for the database identified by :database_name. The :database_name is the value of the name field that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: [ ] "database_id": "VMart", "node_id": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003", "status": "Unknown" HP Vertica Analytic Database (7.1.x) Page 378 of 401

379 Management API GET databases/:database_name/nodes/:node_id Returns details about the node identified by :node_id. The :node_id is one of the node IDs returned by GET databases/:database_name/nodes. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "db": "VMart", "host": " ", "name": "v_vmart_node0001", "state": "UP" HP Vertica Analytic Database (7.1.x) Page 379 of 401

380 Management API POST databases/:database_name/process Creates a job to start the database identified by :database_name. The :database_name is the value of the namefield that the GETdatabases command returns. Returns a job ID that can be used to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters epoch include Start the database from this epoch. Include only these hosts when starting the database. Use a commaseparated list of hostnames. Example Request POST An example of the full request using curl: curl -X POST -H "VerticaApiKey: ValidAPIKey" Response: "id": "StartDatabase-testDB :41: ", "url": "/jobs/startdatabase-testdb :41: " HP Vertica Analytic Database (7.1.x) Page 380 of 401

381 Management API GET databases/:database_name/process Returns a state of UP or DOWN for the database identified by :database_name. The :database_ name is the value of the namefield that the GETdatabases command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "state": "UP" HP Vertica Analytic Database (7.1.x) Page 381 of 401

382 Management API DELETE databases/:database_name/process Creates a job to stop the database identified by :database_name. The :database_name is the value of the namefield that the GETdatabases command returns. Returns a job ID that you can useto determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. The password for the username. Example Request DELETE id=dbadmin"&"passwd=vertica An example of the full request using curl: curl -X DELETE -H "VerticaApiKey: ValidAPIKey" id=dbadmin"&"passwd=vertica Response: "id": "StopDatabase-testDB :46: ", "url": "/jobs/stopdatabase-testdb :46: " HP Vertica Analytic Database (7.1.x) Page 382 of 401

383 Management API POST databases/:database_ name/rebalance/process Creates a job to run a rebalance on the database identified by host identified by :database_name. The :database_name is the value of the namefield that the GETdatabases command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. A password for the username. Example Request POST Response: "id": "RebalanceData-testDB :42: ", "url": "/jobs/rebalancedata-testdb :42: " HP Vertica Analytic Database (7.1.x) Page 383 of 401

384 Management API POST databases/:database_name/wla/process Creates a job to run Workload Analyzer on the database identified by host identified by :database_ name. The :database_name is the value of the name field that the GETdatabases command returns. Returns a job ID that you can use to determine the status of the job. See GET jobs. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters user_id passwd A database username. A password for the username. Example Request POST Response: "id": "AnalyzeWorkLoad-testDB :48: ", "url": "/jobs/analyzeworkload-testdb :48: " HP Vertica Analytic Database (7.1.x) Page 384 of 401

385 Management API GET hosts Returns a list of the hosts in the cluster and the hardware, software, and network details about each host. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "cpu_info": "cpu_type": " Intel(R) Xeon(R) CPU E GHz", "number_of_cpus": 2, "host_id": " ", "hostname": "doch01.verticacorp.com", "max_user_proc": "3833", "nics": [ "broadcast": " ", "ipaddr": " ", "name": "eth0", "netmask": " ", "speed": "unknown", "broadcast": " ", "ipaddr": " ", HP Vertica Analytic Database (7.1.x) Page 385 of 401

386 Management API,, "name": "lo", "netmask": " ", "speed": "locallink" ], "total_memory": 3833, "vertica": "arch": "x86_64", "brand": "vertica", "release": " ", "version": "7.1.0" "cpu_info": "cpu_type": " Intel(R) Xeon(R) CPU E GHz", "number_of_cpus": 2, "host_id": " ", "hostname": "doch02.verticacorp.com", "max_user_proc": "3833", "nics": [ "broadcast": " ", "ipaddr": " ", "name": "eth0", "netmask": " ", "speed": "unknown", "broadcast": " ", "ipaddr": " ", "name": "lo", "netmask": " ", "speed": "locallink" ], "total_memory": 3833, "vertica": "arch": "x86_64", "brand": "vertica", "release": " ", "version": "7.1.0" "cpu_info": "cpu_type": " Intel(R) Xeon(R) CPU E GHz", "number_of_cpus": 2, "host_id": " ", "hostname": "doch03.verticacorp.com", "max_user_proc": "3833", "nics": [ "broadcast": " ", "ipaddr": " ", "name": "eth0", HP Vertica Analytic Database (7.1.x) Page 386 of 401

387 Management API "netmask": " ", "speed": "unknown", "broadcast": " ", "ipaddr": " ", "name": "lo", "netmask": " ", "speed": "locallink" ], "total_memory": 3833, "vertica": "arch": "x86_64", "brand": "vertica", "release": " ", "version": "7.1.0" ], "href": "/hosts", "links": [ "/:hostid" ], "mime-type": "application/vertica.hosts.json-v2" HP Vertica Analytic Database (7.1.x) Page 387 of 401

388 Management API GET hosts/:hostid Returns hardware, software, and network details about the host identified by :host_id. You can find :host_id for each host using GET hosts. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": "cpu_info": "cpu_type": " Intel(R) Xeon(R) CPU E GHz", "number_of_cpus": 2, "hostname": "doch01.verticacorp.com", "max_user_proc": "3833", "nics": [ "broadcast": " ", "ipaddr": " ", "name": "eth0", "netmask": " ", "speed": "unknown", "broadcast": " ", "ipaddr": " ", "name": "lo", "netmask": " ", HP Vertica Analytic Database (7.1.x) Page 388 of 401

389 Management API "speed": "locallink" ], "total_memory": 3833, "vertica": "arch": "x86_64", "brand": "vertica", "release": " ", "version": "7.1.0", "href": "/hosts/ ", "links": [], "mime-type": "application/vertica.host.json-v2" HP Vertica Analytic Database (7.1.x) Page 389 of 401

390 Management API GET jobs Returns a list of jobs being tracked by the agent and job details. Jobs always start immediately. The is_running field is a Boolean value. If is_running is false, then the job is complete. The exit_code details the status of the job. The exit_code is different for certain types of jobs: For Backup jobs: 0 indicates success. Any other number indicates a failure. For all other jobs: -9 indicates success. Any other number indicates a failure. You can see details about failures in /opt/vertica/log/agentstdmsg.log. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: HP Vertica Analytic Database (7.1.x) Page 390 of 401

391 Management API "body": [ "exit_code": 0, "id": "CreateBackup-VMart ", "is_running": false, "status": "unused", "ts": " ", "exit_code": 1, "id": "CreateBackup-VMart ", "is_running": false, "status": "unused", "ts": " " ], "href": "/jobs", "links": [ "/:jobid" ], "mime-type": "application/vertica.jobs.json-v2" HP Vertica Analytic Database (7.1.x) Page 391 of 401

392 Management API GET jobs/:id Gets the details for a specific job with the provided :id. You can determine the list of job :ids usingget jobs. Details for a specific job are the same as the details provided for all jobs byget jobs. Note: You must URL encode the :id as some IDs may contain spaces or other special characters. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET HP Vertica Analytic Database (7.1.x) Page 392 of 401

393 Management API POST licenses Uploads and applies a license file to this cluster. You must provide the license file as an HTTP POST form upload, identified by the name license. For example, you can use curl: curl -k --request POST -H "VerticaApiKey:ValidAPIKey" \ --form "[email protected]" Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have admin level security. Parameters None. Example Request POST Response: There is no HTTP body response for successful uploads. A successful upload returns an HTTP 200/OK header. HP Vertica Analytic Database (7.1.x) Page 393 of 401

394 Management API GET licenses Returns any license files that are used by this cluster when creating databases. License files must reside in /opt/vertica/config/share. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "comment": "Vertica license is valid", "end": "Perpetual", "grace": "0", "size": "1TB CE Nodes 3", "start": " ", "status": true, "vendor": "Vertica Community Edition" ], "href": "/license", "links": [], "mime-type": "application/vertica.license.json-v2" HP Vertica Analytic Database (7.1.x) Page 394 of 401

395 Management API GET nodes Returns a list of nodes associated with this cluster. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "node0001", "node0002", "node0003", "v_testdb_node0001", "v_testdb_node0002", "v_testdb_node0003", "v_vmart_node0001", "v_vmart_node0002", "v_vmart_node0003" ], "href": "/nodes", "links": [ "/:nodeid" ], "mime-type": "application/vertica.nodes.json-v2" HP Vertica Analytic Database (7.1.x) Page 395 of 401

396 Management API GET nodes/:nodeid Returns details about the node identified by :node_id. You can find the :node_id for each node using GET nodes. In the body field, the following information is detailed in comma-separated format: Node Name Host Address Catalog Directory Data Directory Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "v_vmart_node0001", " ,/home/dbadmin,/home/dbadmin" ], "href": "/nodes/v_vmart_node0001", "links": [], "mime-type": "application/vertica.node.json-v2" HP Vertica Analytic Database (7.1.x) Page 396 of 401

397 Management API GET webhooks Returns a list of active webhooks for this cluster. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request GET Response: "body": [ "host": " ", "id": "79c1c8a18be02804b3d2f48ea ", "port": 80, "timestamp": " :54: ", "url": "/gettest.htm", "host": " ", "id": "9c32cb0f3d2f9a7cb10835f1732fd4a7", "port": 80, "timestamp": " :54: ", "url": "/getwebhook.php" ], "href": "/webhooks", "links": [ "/subscribe", "/:subscriber_id" ], HP Vertica Analytic Database (7.1.x) Page 397 of 401

398 Management API "mime-type": "application/vertica.webhooks.json-v2" HP Vertica Analytic Database (7.1.x) Page 398 of 401

399 Management API POST webhooks/subscribe Creates a subscription for a webhook. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters url A URL to an application that accepts JSON messages from this cluster. Example Request POS T ok.php Response: The response is not JSON encoded. The only text response is the ID of the webhook subscription. Additionally, an HTTP 200/OK header indicates success. 79c1c8a18be02804b3d2f48ea HP Vertica Analytic Database (7.1.x) Page 399 of 401

400 Management API DELETE webhooks/:subscriber_id Deletes the webhook identified by :subscriber_id. The :subscriber_id is the value of the id field that the GET webhooks command returns. Resource URL Authentication Requires a VerticaAPIKey in the request header. The API key must have restricted level security or higher. Parameters None. Example Request DELETE Response: There is no HTTP body response for successful deletes. A successful delete returns an HTTP 200/OK header. HP Vertica Analytic Database (7.1.x) Page 400 of 401

401 We appreciate your feedback! If you have comments about this document, you can contact the documentation team by . If an client is configured on this system, click the link above and an window opens with the following information in the subject line: Feedback on Connecting to HP Vertica (Vertica Analytic Database 7.1.x) Just add your feedback to the and click send. If no client is available, copy the information above to a new message in a web mail client, and send your feedback to [email protected]. HP Vertica Analytic Database Page 401 of 401