OpenText Analytics Database 26.2.x – Meta-commands

Connecting-To: Meta-commands quick reference

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

Syntax	Summary	Command-line Options
`\! [``cmd``]`	Executes a command in a Linux shell (passing arguments as entered) or starts an interactive shell.
`\?`	Displays help information about all meta-commands, the same as `\h`.	`?`
`\a`	Toggles output format alignment. For details, see `\pset format aligned`.	`-A` `-no-align`
`\b`	Toggles beep on command completion.
`\c[connect] [db [user-name]]`	Establishes a connection to database `db`, under the specified user `user-name`. For details, see `\connect`.
`\C ['``title-str``']`	Sets a title `title-str` that precedes query result output. For details, see `\pset title` `title-str`.
`\cd [``dir``]`	Changes the current working directory to `dir`, changes to your home directory if you omit specifying a directory.
`\d` commands	See \d meta-commands
`\e[dit] [file]`	Edits the query buffer (or specified file) with an external editor. For details, see `\edit`.
`\echo [``str``]`	Writes `str` to standard output. Tip Use `\qecho` to redirect query output to the query output stream, as set by `\o`.
`\f [``str``]`	Sets the field separator for unaligned query output. The default is the vertical bar (\|).	`-F` `--field-separator`
`\g [``file-name``\|``shell-command``]`	Sends the query in the input buffer (see `\p`) to the server. You can send query results to `file-name`, or pipe results to `shell-comand`; otherwise, `\g` sends query results to standard output.
`\H`	Renders output in HTML markup as a table. For details, see `\pset format aligned`.	`-H` `--html`
`\h[elp]`	Displays help information about the meta-commands, the same as `\?`.	`--help`
`\i` `file`	Reads and executes input from filename.	`-f` `--file`
`\l \list`	Lists available databases and owners.	`-l` `--list`
`\locale [``locale``]`	Displays the current locale setting or sets a new locale for the session. For details, see `\locale`.
`\o [``file-name``\|``shell-command``]`	Controls where vsql directs query output. You can send query results to `file-name`, or pipe results to `shell-comand`; otherwise, `\o` sends query results to standard output.	`-o` `--output`
`\p`	Prints the current query buffer to standard output.
`\password [``user-name``]`	Starts the password change process. Superusers can specify a user name to change that user's password; otherwise, users can only change their own passwords.
`\pset output-option`	Sets options that control how OpenText™ Analytics Database formats query result output. For details, see `\pset`.	`-P` `--pset`
`\q`	Quits the vsql program
`\qecho [``str``]`	Writes `str` to the query output stream, as specified by by `\o`.
`\r`	Clears (resets) the query buffer
`\s [``file``]`	Valid only if vsql is configured to use the GNU Readline library, prints or saves the command line history to `file`, or to standard output if no file name is supplied.
`\set [var [value]...]`	Sets internal variable `var` to `value`. If you specify multiple values, var is set to their concantenated values. If no values are specified, `var` is set to no value.	`--set` `-v` `--variable`
`\t`	Toggles between tuples only and full display. For details, see `\pset format tuples_only`.	`-t` `--tuples-only`
`\T` `html-attribute``[...]`	Specifies attributes to be placed inside the HTML `table` tag—for example, `cellpadding` or `bgcolor`, the same as `\pset tableattr html-attribute[...]`. For sample usage, see Output formatting examples.	`-T` `--table-attr`
`\timing`	If set to on, returns how long (in milliseconds) each SQL statement runs. For details, see `\timing`.	`-i` `-- timing`
`\unset` `var`	Deletes internal variable `var` that was set by the meta-command `\set` .
`\w` `file-name`	Outputs the current query buffer to file `file-name`.
`\x`	Toggles between regular and expanded format. For details, see `\pset format expanded`.	`-x` `--expanded`
`\z`	Returns a summary of privileges on all objects in system table `V_CATALOG.GRANTS`: grantee, grantor, privileges, schema, and object name (equivalent to `\dp`). `\z` supports the same options as `\dp` for filtering output by schema and object name patterns, . For example: `> \z .myseq* Access privileges for database "dbadmin" Grantee \| Grantor \| Privileges \| Schema \| Name ---------+---------+------------+--------+-------- dbadmin \| dbadmin \| SELECT* \| public \| mySeq dbadmin \| dbadmin \| SELECT* \| public \| mySeq2 (2 rows)`

Connecting-To: \connect

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

Establishes a connection to database db, under the specified user user-name. The previous connection is closed. If you omit specifying a database name, OpenText™ Analytics Database connects to the current database. If you omit specifying a user name argument, the database assumes the current user.

Syntax

\c[connect] [db [user-name]]

Error handling

Errors that prevent execution include specifying an unknown user and denial of access to the specified database. The database handles errors differently, depending on whether this command is executed interactively in vsql, or in a script:

VSQL handling: The current connection is maintained.
Script: Processing immediately stops with an error. This is prevents scripts from acting on the wrong database.

Connecting-To: \d meta-commands

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

OpenText™ Analytics Database supports a number of \d commands, which return information on different categories of database objects. For a full list, see \d Reference below.

Syntax

Unless otherwise noted, \d commands generally conform to the following syntax:

\dCommand [ [schema.]pattern ]

Arguments

You can supply most \d commands with a string pattern argument, which filters the results that the command returns. The pattern can optionally be qualified by a schema name.

schema

Valid for most \d commands, restricts output to only database objects in schema. For example, the following \dp command obtains privileges information for all V_MONITOR tables that contain the string resource:

=> \dp V_MONITOR.*resource*
                Access privileges for database "dbadmin"
 Grantee | Grantor | Privileges |  Schema   |            Name
---------+---------+------------+-----------+----------------------------
 public  | dbadmin | SELECT     | v_monitor | resource_rejections
 public  | dbadmin | SELECT     | v_monitor | disk_resource_rejections
 public  | dbadmin | SELECT     | v_monitor | resource_usage
 public  | dbadmin | SELECT     | v_monitor | resource_acquisitions
 public  | dbadmin | SELECT     | v_monitor | resource_rejection_details
 public  | dbadmin | SELECT     | v_monitor | resource_pool_move
 public  | dbadmin | SELECT     | v_monitor | host_resources
 public  | dbadmin | SELECT     | v_monitor | node_resources
 public  | dbadmin | SELECT     | v_monitor | resource_queues
 public  | dbadmin | SELECT     | v_monitor | resource_pool_status
(10 rows)

pattern

Returns only the database objects that match the specified string. Pattern strings can include the following wildcards:

* (asterisk): zero or more characters.
? (question mark): any single character.

For example, the following \dt command returns tables that start with the string store:

=> \dt store*
                     List of tables
 Schema |       Name        | Kind  |  Owner  | Comment
--------+-------------------+-------+---------+---------
 public | store_orders      | table | dbadmin |
 public | store_orders_2018 | table | dbadmin |
 public | store_overseas    | table | dbadmin |
 store  | store_dimension   | table | dbadmin |
 store  | store_orders_fact | table | dbadmin |
 store  | store_sales_fact  | table | dbadmin |
(6 rows)

\d reference

\d

Unqualified by a pattern argument, returns all tables with their schema names, owners, and comments. If qualified by a pattern argument, \d returns all matching tables and all columns in each table, with details about each column, such as data type, size, and default value.

\df

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.

\dj

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.

\dn

Returns the schema names and schema owner.

\dp

Returns a summary of privileges on all objects in system table V_CATALOG.GRANTS: grantee, grantor, privileges, schema, and object name (equivalent to \z).

\dS

Unqualified by a pattern argument, returns all V_CATALOG and V_MONITOR system tables. To obtain system tables for just one schema, qualify the command with the schema name, as follows:

\dS { V_CATALOG | V_MONITOR }.*

\ds

Returns sequences and their parameters.

\dT

Returns all data types that the database supports.

Note

\dT returns no results if qualified with a pattern argument.

\dt

Unqualified by a pattern argument, returns the same information as an unqualified \d command. If qualified by a pattern argument, \dt returns matching tables with the same level of detail as an unqualified \dt command.

\dtv

Returns tables and views.

\du

Returns database users and whether they are superusers.

\dv

Unqualified by a pattern argument, returns all views with their schema names, owners, and comments. If qualified by a pattern argument, \dv returns all matching views and the columns in each view, with each column's data type and size.

Connecting-To: \edit

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

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

Syntax

\e[dit] [ file ]

Connecting-To: \i

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

Reads and executes input from the specified file.

Note

To see the lines on the screen as they are read, set the variable ECHO to all.

Syntax

\i filename

Examples

The OpenText™ Analytics Database vsql client on Linux supports backquote (backtick) expansion. For example:

Set an environment variable to a path that contains scripts you want to run:
```
$ export MYSCRIPTS=/home/dbadmin/testscripts
```
Issue the vsql command.
```
$ vsql
```
Use backquote expansion to include the path for running an existing script—for example, sample.sql.
```
=> \i `echo $MYSCRIPTS/sample.sql`
```

Connecting-To: \locale

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

Displays or sets the locale setting for the current session.

Note

This command does not alter the default locale for all database sessions. To change the default for all sessions, set configuration parameter DefaultSessionLocale.

Syntax

\locale [locale-identifier]

Arguments

locale-identifier

Specifies the ICU locale identifier to use, by default set to:

en_US@collation=binary

If set to an empty string, OpenText™ Analytics Database sets locale to en_US_POSIX.

If you omit this argument, \locale returns the current locale setting.

For details on identifier options, see About locale. For a complete list of locale identifiers, see the ICU Project.

Examples

View the current locale setting:

=> \locale
en_US@collation=binary

Change the default locale for this session:

=> \locale en_GBINFO:
INFO 2567:  Canonical locale: 'en_GBINFO:'
Standard collation: 'LEN'
English (GBINFO:)

Notes

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. OpenText recommends the following best practices 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.
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.

Connecting-To: \pset

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

Sets options that control how OpenText™ Analytics Database formats query result output.

Syntax

\pset output-option

Output options

Note

Unless otherwise specified, output options are valid for all formats.

format format-option

Sets output format, where format-option is one of the following:

u[naligned] writes all column data of each row on a single line, where each field is separated only by the current separator character. Use this output for use as input to other programs—for example, comma-delimited fields for CSV input.
a[ligned] (default): Renders column-aligned output.
h[tml]: Renders output in HTML markup as a table.
l[atex]: Renders output in LaTex markup.

border int

Valid only if output format is set to html, specifies the table border, where int specifies the border type.

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 especially useful for wide tables.

fieldsep 'arg'

Valid only if output format is set to unaligned, specifies the field separator, by default | (vertical bar).

For example, to specify tab as the field separator:

\pset fieldsep '\t'

footer

Toggles display of the default footer:

(int rows)

null 'string'

Specifies to represent column null values as string. By default, the database renders null values as an empty field, which might be mistaken as an empty string.

For example:

\pset null '(null)'

pager [always]

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

If qualified with the argument always, the pager is always used.

recordsep 'char'

Valid only if output format is set to unaligned, specifies the character used to delimit table records (tuples), by default a newline character.

tableattr html-attribute[...]

Specifies attributes to be placed inside the HTML table tag—for example, cellpadding or bgcolor.

title ['title-str']

Sets a title that precedes query result output, to title-str. HTML output renders this as follows:

<caption>title-str</caption>

To remove the title, reissue the command omit the title-str argument.

trailingrecordsep

Toggles on or off the trailing record separator to use in unaligned output mode.

t[uples_only]

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.

Shortcuts

The following \pset commands have short-cuts:

\pset expanded

\x

\pset fieldsep 'arg'

\f

\pset format aligned

\a

\pset format html

\H

\pset tableattr html-attribute[...]

\T html-attribute[...]

\pset title title-str

\C ['title-str']

\pset tuples_only

\t

Examples

See Output formatting examples.

Connecting-To: \set

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

Sets an internal variable to one or more values. If multiple values are specified, they are concantenated. An unqualified \set command lists all internal variables.

To unset a variable, use vsql meta-command\unset.

Syntax

\set [var [value]...]

Arguments

var: The name of an internal variable to set. Valid variable names are case sensitive and can contain characters, digits, and underscores. vsql treats several variables as special, which are described in Variables.
value: A value to set in variable var. If no value is specified, the variable is set to no value.
If set to an empty string, the variable is set to no value. If you omit this argument, \set returns all internal variables.

If no arguments are supplied, \set returns all internal variables. For example:

=> \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'

Connecting-To: \timing

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

If set to on, returns how long (in milliseconds) each SQL statement runs. Results include:

Length of time required to fetch the first block of rows
Total time until the last block is formatted.

Unqualified, \timing toggles timing on and off. You can explicitly turn timing on and off by qualifying the command with options ON and OFF, respectively.

Note

You can also enable \timing from the command line using the vsql -i command.

Syntax

\timing [ON | OFF]

Examples

The following unqualified \timing commands toggle timing on and off:

=> \timing
Timing is on
=> \timing
Timing is off

The following example shows a SQL command with timing on:

=> \timing
Timing is on.
=> SELECT user_name, ssl_state, authentication_method, client_authentication_name,
     client_type FROM sessions WHERE session_id=(SELECT session_id FROM current_session);
 user_name | ssl_state | authentication_method | client_authentication_name | client_type
-----------+-----------+-----------------------+----------------------------+-------------
 dbadmin   | None      | ImpTrust              | default: Implicit Trust    | vsql
(1 row)

Time: First fetch (1 row): 73.684 ms. All rows formatted: 73.770 ms