OpenText Analytics Database 26.2.x – Using vsql

Connecting-To: Installing the vsql client

Mon, 01 Jan 0001 00:00:00 +0000

This page covers a non-FIPS installation. To install on a FIPS-compliant system, see Installing the FIPS client driver for ODBC and vsql.

Linux and macOS

Note

For Linux: The vsql client is automatically installed as part of the OpenText™ Analytics Database server .rpm.

To install vsql manually on another system:

Download vsql.
Extract or install vsql:
- If you downloaded the .tar, create the /opt/vertica/ directory if it does not already exist, copy the .tar to it, navigate to it, and extract the .tar:
```
$ mkdir -p /opt/vertica/
$ cp driver_name.tar.gz /opt/vertica/
$ tar vzxf driver_name.tar.gz
```
- If you downloaded the .rpm, install it with:
```
$ rpm -Uvh driver_name.rpm
```
Optionally add the vsql directory to your PATH. For example:
```
$ export PATH=$PATH:\opt\vertica\bin
```
Make the vsql client executable. For example, to allow all users to run vsql:
```
$ chmod ugo+x /path/to/vsql
```
Set your shell locale to a locale supported by vsql (which ones?). For example, in your .profile, add:
```
export LANG=end_US.UTF-8
```

Windows

To install the vsql client:

Download the Windows client driver installer. For details on the drivers included in this installer, see Windows client driver installer.
Run the installer and follow the prompts to install the drivers.
Reboot your system.

After installing the driver, you can optionally add the vsql directory to your PATH. For example, to append the vsql directory to your PATH with Windows PowerShell for the current session:

PS C:\> $Env:PATH += ";C:\Program Files\Vertica Systems\VSQL64\"

You can verify that the vsql directory is in your PATH by running vsql -?:

PS C:\> vsql -?
This is vsql, the OpenText&trade; Analytics Database interactive terminal.

Usage:
  vsql [OPTIONS]... [DBNAME [USERNAME]]

For usage details, see vsql usage on Windows

Connecting-To: vsql usage on Windows

Mon, 01 Jan 0001 00:00:00 +0000

Font

The default raster font does not work well with the ANSI code page. Set the console font to "Lucida Console."

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, set the code page by entering cmd.exe /c chcp 1252.

Note

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

To verify, enter:

set CYGWIN=binmode tty ntsec

To remove the "tty" flag, enter:

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. You can also press F8 after typing a few letters of a command to cycle through commands in the history buffer which begin with the same letters.

Connecting-To: Connecting from the administration tools

Mon, 01 Jan 0001 00:00:00 +0000

You can use the Administration tools to connect to a database using vsql on any node in the cluster.

Log in as the database administrator user; for example, dbadmin.

Note
OpenText™ Analytics Database does not allow users with root privileges to connect to a database for security reasons.
Run the Administration Tools.
```
$ /opt/vertica/bin/admintools
```
On the Main Menu, select Connect to Database.
If prompted, enter the database password:
```
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.

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.

Connecting-To: Connecting from the command line

Mon, 01 Jan 0001 00:00:00 +0000

You can connect to a database using vsql from the command line on multiple client platforms.

If the connection cannot be made for any reason—for example, you have insufficient privileges, or the server is not running on the targeted host—vsql returns an error and terminates.

Syntax

/opt/vertica/bin/vsql [-h host] [ -p port ] [ -O TOTP ] [ option...] [ dbname [ username ] ]

Parameters

host: Optional if you connect to a local server. You can provide an IPv4 or IPv6 IP address or a host name.
For OpenText™ Analytics Database 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. If you are using IPv6 and provide an IP address, you must append the address with an %interface name.
port: The database server port.
Default: 5433
TOTP: Specify the current Time-based One-time Password (Totp) value. The Totp is sent to the server in the connection string for validation. If MFA is enforced and you do not provide a Totp, a dialog is displayed. You need to enter the Totp before proceeding with authentication.
option: One or more vsql command-line options.
If the database is password protected, you must specify the -w or --password command line option.
dbname: The name of the target database. If unspecified, vsql automatically connects to the database on the specified host and port.
username: A database username, by default your system username.

Exit codes

vsql returns 0 to the shell when it terminates normally. Otherwise, it returns one of the following:

1: A fatal error occurred—for example, out of memory or file not found.
2: The connection to the server went bad and the session was not interactive
3: 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 to capture error messages by redirecting vsql output to the output file retail_queries.out:

$ vsql --echo-all < retail_queries.sql > retail_queries.out 2>&1

Connecting-To: Meta-commands

Mon, 01 Jan 0001 00:00:00 +0000

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.

Connecting-To: Variables

Mon, 01 Jan 0001 00:00:00 +0000

vsql provides variable substitution features similar to common Linux command shells. Variables are name/value pairs, where the value can be a string of any length. To set variables, use the vsql meta-command \set. For example, the following statement sets the variable fact to the value dim:

=> \set fact dim

If you call \set on a variable and supply no value, the variable is set to an empty string.

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.

Getting variables

To retrieve the content of a given variable, precede the name with a colon and use it as the argument of any slash command. For example:

=> \echo :fact
dim

An unqualified \set command returns all current variables and their values:

dbadmin=> \set
VERSION = 'vsql'
AUTOCOMMIT = 'off'
VERBOSITY = 'default'
PROMPT1 = '%/%R%# '
PROMPT2 = '%/%R%# '
PROMPT3 = '>> '
ROWS_AT_A_TIME = '1000'
DBNAME = 'dbadmin'
USER = 'dbadmin'
PORT = '5433'
LOCALE = 'en_US@collation=binary'
HISTSIZE = '500'

Deleting variables

To unset (or delete) a variable, use the vsql meta-command \unset.

Variable naming conventions

vsql internal variable names can contain letters, numbers, and underscores in any order and any number. Some 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

You can substitute ("interpolate") vsql variables into regular SQL statements. You do so by prepending the variable name with a colon (:). For example, the following statements query the table my_table:

=> \set fact 'my_table'
=> SELECT * FROM :fact;

The value of the variable is copied literally, 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. One exception applies: the contents of backquoted strings (````) are passed to a system shell, and replaced with the shell's output. See Using Backquotes to Read System Variables below.

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 hard-code values.

For example, to set an internal variable to the full path for a file in your UNIX user directory, you can 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.

Connecting-To: Prompting

Mon, 01 Jan 0001 00:00:00 +0000

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

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.

%:name:

The value of the vsql variable name. See the section Variables for details.

%`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 non-printing 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 gnome-terminal and xterm).

Connecting-To: Command line editing

Mon, 01 Jan 0001 00:00:00 +0000

vsql supports the tecla library for line editing and retrieval. You can define a tecla configuration with the following files:

~/.vsqlrc (user)
/opt/vertica/config/vsqlrc (global)

For details, see the tecla documentation.

Command history is automatically saved in ~/.vsql_history when vsql exits and is reloaded when vsql starts.

Disabling tab completion

To disable tab completion, add the following to .vsqlrc:

\bind ^I

Key bindings

Key bindings are read from a global configuration at /opt/vertica/config/vsqlrc, if present. To override key bindings, add definitions to ~/.vsqlrc.

Key bindings must be prefixed with a backslash (\). For example, the following definition binds the "backward-word" action to Ctrl+B:

\bind ^B backward-word

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.

Implementation differences

The vsql implementation of the tecla library deviates from the tecla documentation in the following ways:

Unlike the standard tecla library, which saves all executed lines in the command history, vsql only saves unique non-empty lines.
vsql standardizes the name and location of the history file (~/.vsql_history).
vsql does not support 8-bit meta characters. This can affect international character sets, meta keys, and locales. You can verify that a meta character sends an escape by setting the EightBitInput X resource to False. You can do this in the following ways:
- Add the following to ~/.Xdefaults:
```
XTerm*EightBitInput: False
```
- Start an xterm session with the -xrm '*EightBitInput: False'.

Connecting-To: vsql environment variables

Mon, 01 Jan 0001 00:00:00 +0000

Set one or more of the following environment variables to be used by the defined properties automatically, 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. Use the \pset command to enable/disable the pager.
VSQL_CLIENT_LABEL: The label to identify the vsql client in various system tables like SESSIONS. This is an alternative to setting the client label with the --label option or SET_CLIENT_LABEL, but if either of these is used, they take precedence over VSQL_CLIENT_LABEL.
VSQL_DATABASE: The database to which you are connecting. For example, VMart.
TMPDIR: Directory for storing temporary files. The default is platform-dependent. On Unix-like systems the default is /tmp.
VSQL_EDITOR EDITOR VISUAL: Editor used by the \e command. The variables are examined in the order listed; the first that is set is used.
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.
VSQL_HOST: Host name or IP address of the OpenText™ Analytics Database node.
VSQL_OAUTH_ACCESS_TOKEN: Holds the OAuth access token and enables users to sign in to the OpenText™ Analytics Database using VSQL client through OAuth authentication.
VSQL_PASSWORD: The database password. Using this environment variable increases site security by precluding the need to enter the database password on the command line.
VSQL_PORT: Port to use for the connection.
VSQL_SSLMODE: Specifies whether and how clients such as admintools use SSL when connecting to servers.
VSQL_USER: User name to use for the connection.
VSQL_WORKLOAD: The workload to use for the connection.

Connecting-To: Locales

Mon, 01 Jan 0001 00:00:00 +0000

The default terminal emulator under Linux is gnome-terminal, although xterm can also be used.

OpenText recommends that you use gnome-terminal with vsql in UTF-8 mode, which is its default.

To change settings on Linux

From the tabs at the top of the vsql screen, select Terminal.
Click Set Character Encoding.
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

Right click the vsql screen title bar and select Change Settings.
Click Window and click Translation.
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.

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

Connecting-To: Entering data with vsql

Mon, 01 Jan 0001 00:00:00 +0000

You often need to insert literal data when using vsql. For example:

Adding a row of data to a table using an INSERT statement.
Adding multiple rows of data through a COPY FROM STDIN statement.

The following table lists the data types that OpenText™ Analytics Database supports and the format you use to enter that data in queries when using vsql.

Data Type	Inserting to vsql using	Example Use in INSERT INTO table...	For More Information See...
Binary types, such as BINARY and VARBINARY	Helper functions such as HEX_TO_BINARY, octal strings, specified data format in COPY statements, casting string values to binary.	`VALUES(HEX_TO_BINARY('0x3D'), '\\141\\337\\');`	Binary data types (BINARY and VARBINARY) Binary (native) data
BOOLEAN	Literal values `TRUE` and `FALSE` or strings such as `'y'`, `'t'`, `'true'`, or `'false'`.	`VALUES(TRUE, 'f');`	Boolean data type
Character data types such as CHAR or LONG VARCHAR	Strings enclosed in single quotes.	`VALUES('my string');`	Character data types (CHAR and VARCHAR)
Date and time data types, such as TIMESTAMPTZ	Formatted text string	`VALUES('16:43:00', '2016-09-15 04:55:00 PDT');`	Date/time data types Date/time expressions
Numeric Data Types	Literal numeric values, including scientific notation, hexadecimal, and BINARY scaling.	`VALUES(3.1415, 42, 6.0221409e23);`	Numeric data types
UUID	Formatted text string	`VALUES('12345678-1234-1234-1234-123456789012');`	UUID data type

Connecting-To: Files

Mon, 01 Jan 0001 00:00:00 +0000

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.

Connecting-To: Exporting data using vsql

Mon, 01 Jan 0001 00:00:00 +0000

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	Meta-command	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.
=> \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 OpenText™ Analytics 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;"
A|1|2|3
B|4|5|6

$ vsql -F $'\t' -At -c "SELECT * FROM testtable;"
A       1       2       3
B       4       5       6

$ vsql -F $'\v' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6
$ vsql -F $'\013' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6

Connecting-To: Copying data using vsql

Mon, 01 Jan 0001 00:00:00 +0000

You can use vsql to copy data between two OpenText™ Analytics 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 the database to another cluster.

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

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 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 command, so you will need to download and install it yourself. See the Pipe Viewer page for download packages and instructions. The database 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

Connecting-To: Output formatting examples

Mon, 01 Jan 0001 00:00:00 +0000

By default, OpenText™ Analytics Database formats query output as follows:

=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
       category_description
----------------------------------
 Food
 Medical
 Misc
 Non-food
(4 rows)

You can control the format of query output in various ways with the \pset command—for example, change the border:

=> \pset border 2
Border style is 2.
=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
+----------------------------------+
|       category_description       |
+----------------------------------+
| Food                             |
| Medical                          |
| Misc                             |
| Non-food                         |
+----------------------------------+
(4 rows)
=> \pset border 0
Border style is 0.
=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
      category_description
--------------------------------
Food
Medical
Misc
Non-food
(4 rows)

The following sequence of pset commands change query output in several ways:

Set border style to 1.
Remove column alignment.
Change the field separator to a comma.
Remove column headings

=> \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 product_key, product_description, category_description FROM product_dimension LIMIT 10;
1,Brand #2 bagels,Food
1,Brand #1 butter,Food
2,Brand #6 chicken noodle soup,Food
3,Brand #11 vanilla ice cream,Food
4,Brand #14 chocolate chip cookies,Food
4,Brand #12 rash ointment,Medical
6,Brand #18 bananas,Food
7,Brand #25 basketball,Misc
8,Brand #27 french bread,Food
9,Brand #32 clams,Food

The following example uses meta-commands to toggle output format—in this case, \a (alignment), \t (tuples only), and -x (extended display):

=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is off.
=> SELECT product_key, product_description, category_description FROM product_dimension LIMIT 10;
 product_key |       product_description        |       category_description
-------------+----------------------------------+----------------------------------
           1 | Brand #2 bagels                  | Food
           1 | Brand #1 butter                  | Food
           2 | Brand #6 chicken noodle soup     | Food
           3 | Brand #11 vanilla ice cream      | Food
           4 | Brand #14 chocolate chip cookies | Food
           4 | Brand #12 rash ointment          | Medical
           6 | Brand #18 bananas                | Food
           7 | Brand #25 basketball             | Misc
           8 | Brand #27 french bread           | Food
           9 | Brand #32 clams                  | Food
(10 rows)

The following example sets output format to HTML, so the database renders query results in HTML markup as a table:


=> \pset format html
Output format is html.
=> \pset tableattr 'border="2" cellpadding="3"'
Table attribute is "border="2" cellpadding="3"".
=> SELECT product_key, product_description, category_description FROM product_dimension LIMIT 2;
<table border="1" border="2" cellpadding="3">
  <tr>
    <th align="center">product_key</th>
    <th align="center">product_description</th>
    <th align="center">category_description</th>
  </tr>
  <tr valign="top">
    <td align="right">1</td>
    <td align="left">Brand #2 bagels</td>
    <td align="left">Food                            </td>
  </tr>
  <tr valign="top">
    <td align="right">1</td>
    <td align="left">Brand #1 butter</td>
    <td align="left">Food                            </td>
  </tr>
</table>
<p>(2 rows)<br />
</p>