heavysql
heavysql is the client-side SQL console that displays query results for SQL statements you submit to the HeavyDB Server.
Syntax
<database> is the name of the database to connect to. The default database name is heavyai.
Options
Option
Description
-a [ --echo-all ]
When input is read from a file, print all executed commands and queries.
--ca-cert arg
Path to trusted server certificate. Initiates an encrypted connection.
-d [ --delimiter ] arg (=|)
Field delimiter in row output.
--db arg
Database name (default is heavyai).
-h [ --help ]
Print help messages.
--history arg
History filename.
--http
Use HTTP transport.
--https
Use HTTPS transport.
-n [ --no-header ]
Do not print query result header.
-p [ --passwd ] arg
Password.
--port arg
Port number. Default is 6274.
-q [ --quiet ]
Do not print result headers or connection strings.
-s [ --server ] arg (=localhost)
Server hostname.
--skip-verify
Do not verify SSL certificate validity.
-t [ --timing ]
Print timing information.
-u [ --user ] arg (=admin)
Username.
-v [ --version ]
Print heavysql version number.
Running heavysql
After starting heavysql, you can enter SQL queries or backslash commands from the command line.
The HEAVY.AI server has a default one hour timeout on individual HTTP requests, including those made from heavysql, when using Thrift HTTP transport. If your queries are expected to exceed the timeout, use either the default heavysql TCP transport or increase the timeout using the heavy_web_server --timeout option.
If the connection to the server is lost, heavysql automatically attempts to reconnect.
Commands
You can use the backslash commands listed in the table below for a variety of tasks beyond SQL queries.
Command
Description
\c <database> <user> <password>
Connect to a database.
\clear_cpu
Clear the CPU memory. Generally, the server takes care of memory management and you would not need to use this command. If you are having unexpected memory issues, you can try clearing the CPU memory to see if performance improves.
\clear_gpu
Clear the GPU memory. Generally, the server takes care of memory management and you would not need to use this command. If you are having unexpected memory issues, you can try clearing the GPU memory to see if performance improves.
\copy <file path> <table>
Copy or append data from client-side file to table. The file is assumed to be in CSV format unless the file name ends with .tsv. HEAVY.AI supports Latin-1 ASCII format and UTF-8. If you want to load data with another encoding (for example, UTF-16), convert the data to UTF-8 before loading it to HEAVY.AI.
\cpu
Switch to CPU mode in the current session.
\d <table>
Describe table columns using a SQL CREATE TABLE statement.
\d <view>
Describe the results of a view SELECT statement.
\dash
List all dashboards accessible by the current user.
\detect [geo | parquet | raster] <filename> {<filePath> | <s3Link>}
Displays the inferred schema for CSV/TSV files, or the actual schema for geo, Parquet, or raster files.
\detect does not support custom parameters. It uses default values, such as commas as the delimiter (tabs in .tsv files). This is not applicable for geo, Parquet, or raster files.
\export_dashboard <dashboard name> <filename>
Exports a dashboard to a filepath. Files with spaces in their names should be quoted. If there is a quote within a quoted string, it should be escaped with a backslash.
\gpu
Switch to GPU mode in the current session.
\h
Help. List available backslash commands.
\historylen <number>
Set the history buffer size (default is 100).
\import_dashboard <dashboard name> <filename>
Imports a dashboard from a filepath. Files with spaces in their names should be quoted. If there is a quote within a quoted string, it should be escaped with a backslash.
\l
List databases.
\memory_summary
Print memory usage summary.
\multiline
Set multi-line command mode.
\notiming
Do not print timing information.
\o <table>
Return the optimal CREATE TABLE statement for a table, based on the size of the actual data stored.
\object_privileges {database|table} <object_name>
Reports all privileges granted to an object for all roles and users.
\privileges {<rolename>|<userName>}
Reports all database object privileges granted to role or user.
\q
Quit omnisql.
\role_list <username>
Reports all roles granted to user.
\roles
Reports all roles.
\set_license <licensekey>
Applies license key to the HEAVY.AI instance. Does not require the services to be restarted to apply the license change.
\singleline
Set single-line command mode.
\status
Get the status of the server and its leaf nodes.
\t [<regex>]
List tables, with optional regular expression.
\timing
Print timing information.
\u [<regex>]
List users, with optional regular expression.
\v [<regex>]
List views, with optional regular expression.
\version
Print HeavyDB server version.
Unlike SQL statements, backslash commands do not require a terminating semicolon character.
Runtime Examples
The \t, \u, and \v commands might return a long list of values. You can use a regular expression match pattern to filter the results. For example, you could use the following command to return only tables that start with the word flight.
SQL query example:
Backslash command example that describes a table:
If you frequently perform the same tasks, you can create a script and pipe it to heavysql. You can use both SQL commands and heavysql commands in your script.
For example, if you periodically upload data to the movies table, you can append rows from files named movies.csv using the following script, and display the results.
When you pipe the script to heavysql, you get results similar to the following.