OpenText Analytics Database 26.2.x – Statements

Sql-Reference: ACTIVATE DIRECTED QUERY

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

Activates a directed query and makes it available to the query optimizer across all sessions.

Syntax

ACTIVATE DIRECTED QUERY { query-name | where-clause }

Arguments

query-name

Name of the directed query to activate, as stored in the DIRECTED_QUERIES column query_name. You can also use GET DIRECTED QUERY to obtain names of all directed queries that map to an input query.

where-clause

Resolves to one or more directed queries that are filtered from system table DIRECTED_QUERIES. For example, the following statement activates all directed queries with the same save_plans_version identifier:

=> ACTIVATE DIRECTED QUERY WHERE save_plans_version = 21;

Privileges

Superuser

Activation life cycle

After you activate a directed query, it remains active until it is explicitly deactivated by DEACTIVATE DIRECTED QUERY or removed from storage by DROP DIRECTED QUERY. If a directed query is active at the time of database shutdown, OpenText™ Analytics Database automatically reactivates it when you restart the database.

Examples

See Managing directed queries.

Sql-Reference: ALTER statements

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

ALTER statements let you change existing database objects.

Sql-Reference: BEGIN

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

Starts a transaction block.

Note

BEGIN is a synonym for START TRANSACTION.

Syntax

BEGIN [ WORK | TRANSACTION ] [ isolation-level ] [ READ [ONLY] | WRITE ]

Parameters

WORK | TRANSACTION

Optional keywords for readability only.

isolation-level

Specifies the transaction's isolation level, which determines what data the transaction can access when other transactions are running concurrently, one of the following:

READ COMMITTED (default)
SERIALIZABLE
REPEATABLE READ (automatically converted to SERIALIZABLE)
READ UNCOMMITTED (automatically converted to READ COMMITTED)

For details, see Transactions.

READ [ONLY] | WRITE

Specifies the transaction mode, one of the following:

READ WRITE (default): Transaction is read/write.
READ ONLY: Transaction is read-only.

Setting the transaction session mode to read-only disallows the following SQL statements, but does not prevent all disk write operations:

INSERT, UPDATE, DELETE, and COPY if the target table is not a temporary table
All CREATE, ALTER, and DROP commands
GRANT, REVOKE, and EXPLAIN if the SQL to run is one of the statements cited above.

Privileges

None

Examples

Create a transaction with the isolation level set to READ COMMITTED and the transaction mode to READ WRITE:

=> BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED READ WRITE;
BEGIN
=> CREATE TABLE sample_table (a INT);
CREATE TABLE
=> INSERT INTO sample_table (a) VALUES (1);
OUTPUT
--------
1
(1 row)

=> END;
COMMIT

Sql-Reference: CALL

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

Invokes a stored procedure created with CREATE PROCEDURE (stored).

Syntax

CALL [[database.]schema.]procedure( [ argument-list] );

Parameters

[database.]schema: Database and schema. The default schema is public. If you specify a database, it must be the current database.
procedure: The name of the stored procedure, where procedure conforms to conventions described in Identifiers.
argument-list: A comma-delimited list of arguments to pass to the stored procedure, whose types correspond to the types of the argument's IN parameters.

Privileges

Non-superuser: EXECUTE on the procedure

Examples

See Executing stored procedures and Stored procedures: use cases and examples.

Sql-Reference: COMMENT ON statements

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

COMMENT ON statements let you create comments on database objects, such as schemas, tables, and libraries. Each object can have one comment. Comments are stored in the system table COMMENTS.

Sql-Reference: COMMIT

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

Ends the current transaction and makes all changes that occurred during the transaction permanent and visible to other users.

COMMIT is a synonym for END

Syntax

COMMIT [ WORK | TRANSACTION ]

Parameters

WORK TRANSACTION: Optional keywords for readability only.

Privileges

None

Examples

This example shows how to commit an insert.

=> CREATE TABLE sample_table (a INT);
=> INSERT INTO sample_table (a) VALUES (1);
OUTPUT
--------
1
=> COMMIT;

Sql-Reference: CONNECT TO VERTICA

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

Connects to another OpenText™ Analytics Database to enable importing and exporting data across databases, with COPY FROM VERTICA and EXPORT TO VERTICA, respectively.

After you establish a connection to another database, the connection remains open in the current session until you explicitly close it with DISCONNECT. You can have only one connection to another database at a time. However, you can establish successive connections to different databases in the same session.

By default, invoking CONNECT TO VERTICA uses the OpenText™ Analytics Database's private network. For information about creating a connection over a public network, see Using public and private IP networks.

Important

Copy and export operations can fail if either side of the connection is a single-node cluster installed on localhost.

Syntax

CONNECT TO VERTICA db-spec
    [ USER username ]
    [ PASSWORD 'password' ] ON 'host', port
    [ TLS CONFIGURATION tls_configuration ]
    [ TLSMODE PREFER ]

Parameters

db-spec

The target database, either the database name or DEFAULT.

username

The username to use when connecting to the other database. If omitted, the current user's username is used.

password

The password of the user on the target database. If omitted, you can use credential forwarding or mutual TLS to authenticate to the target database. For details, see Passwordless authentication

host

The host name of one of the nodes in the other database.

port

The port number of the other database.

tls_configuration

The TLS Configuration to use for TLS. The TLS Configuration is ignored if ImportExportTLSMode is set to any of the following:

REQUIRE_FORCE
VERIFY_CA_FORCE
VERIFY_FULL_FORCE

The effective TLS mode of CONNECT TO VERTICA changes depending on the TLSMODE of the TLS Configuration and the value of ImportExportTLSMode (for non-FORCE values). For details, see Effective TLSMode.

If the target database is configured for mutual TLS and the user on the target database can authenticate with TLS, you can use tls_configuration to authenticate instead of password.

TLSMODE PREFER

Deprecated

This parameter has been superseded by the TLS CONFIGURATION parameter. TLSMODE PREFER only takes effect if TLS CONFIGURATION is not set.

Overrides the value of configuration parameter ImportExportTLSMode for this connection to PREFER. If TLS CONFIGURATION is set or ImportExportTLSMode is set to REQUIRE_FORCE, VERIFY_CA_FORCE, or VERIFY_FULL_FORCE, then TLSMODE PREFER has no effect.

If TLSMODE PREFER and ImportExportTLSMode are both not set, CONNECT TO VERTICA uses ENABLE.

Effective TLS mode

The effective TLS mode of CONNECT TO VERTICA is determined by the TLSMODE of the TLS Configuration and the value of ImportExportTLSMode. The following table summarizes this interaction for non-FORCE values of ImportExportTLSMode:

TLS Configuration	ImportExportTLSMode	Effective TLS mode
ENABLE	PREFER	PREFER
ENABLE	Anything except PREFER	REQUIRE
TRY_VERIFY, VERIFY_CA	Anything	VERIFY_CA
VERIFY_FULL	Anything	VERIFY_FULL

Privileges

None

Security requirements

When importing from or exporting to a database, you can connect only to a database that uses trusted (username only) or password-based authentication, as described in Security and authentication. OAuth and Kerberos authentication methods are not supported.

If configured with a certificate, the database encrypts data during transmission using TLS and attempts to encrypt plan metadata. You can set configuration parameter ImportExportTLSMode to require encryption for plan metadata.

Passwordless authentication

If you omit the password in the call to CONNECT TO VERTICA, you can authenticate to the target database in the following ways:

Credential forwarding
TLS authentication

For brevity, in this and later sections, "caller" refers to the user that runs CONNECT TO VERTICA from the source database to connect to the target database.

Credential forwarding

Credential forwarding lets you authenticate as the current user on the target database by forwarding your hash or password, depending on the caller's authentication method on the target database. To do this, the following requirements must be met:

The caller exists in both databases.
In the target database, the caller has been granted a hash or ldap authentication record.

For an example, see Examples.

TLS authentication

TLS authentication lets you use the certificates and keys in the specified tls_configuration parameter to authenticate instead of a password. To do this, the following requirements must be met:

The caller exists in both databases.
In the source database:
- A custom TLS configurations contains a CA certificate, a client certificate, and client key that can be used to authenticate to the target database with TLS authentication.
- The caller has USAGE privileges on the TLS Configuration.
In the target database:
- The caller has been granted a TLS authentication record.
- The caller can authenticate with TLS using the certificates of TLS Configuration from the source database. This requires a CA certificate that signs the client certificate from the source database.

For an example, see Examples.

Examples

Password authentication

The following example authenticates as the dbadmin to ExampleDB on the host VerticaHost01 on port 5433:

=> CONNECT TO VERTICA ExampleDB USER dbadmin PASSWORD 'Password123' ON 'VerticaHost01',5433;
CONNECT

Credential forwarding

In the following example, Penny wants to run CONNECT TO VERTICA from db_1 to connect to db_2:

Note

In general, the LDAP link service should be used instead to synchronize users between databases. For demonstration purposes, the example below manually configures the user penny on both databases. You can skip these steps if you use LDAP Link.

On db_1, create the user penny:

=> CREATE USER penny IDENTIFIED BY 'my_password';

On db_2, create the user penny with the same hash, salt, and security (hashing) algorithm:

On db_1, retrieve the hash (from the password column) and salt from PASSWORDS:

=> SELECT user_name, password, salt FROM passwords WHERE user_name='penny';
-[ RECORD 1 ]-------------------------------------------------------------------------------------------------------------------------------------
user_name | penny
password  | sha512b2e0911954a79d9d419b7b42774d36d17dd8a663c966bf0dd8f4cd6aad00d3c7ee7ba74b9bf0e56071cd995ae04aeaae537b35903e97255ed5fe286b6ff0d00a
salt      | eac4ad840264e8c590120b31b815318f

On db_1, retrieve the effective security algorithm from PASSWORD_AUDITOR:

=> SELECT user_name, effective_security_algorithm FROM password_auditor WHERE user_name='penny';
 user_name | effective_security_algorithm
-----------+------------------------------
 penny     | SHA512
(1 row)

On db_2, create the user penny:
```
=> CREATE USER penny;
```
On db_2, use ALTER USER to set the security algorithm to the value in db_1. For details, see Password hashing algorithm:
```
=> ALTER USER penny SECURITY_ALGORITHM 'SHA512';
```

On db_2, set penny's password using the hash and salt from db_1:

=> ALTER USER penny IDENTIFIED BY 
'sha512b2e0911954a79d9d419b7b42774d36d17dd8a663c966bf0dd8f4cd6aad00d3c7ee7ba74b9bf0e56071cd995ae04aeaae537b35903e97255ed5fe286b6ff0d00a'
SALT 'eac4ad840264e8c590120b31b815318f';

On db_1, enable credential forwarding for penny by setting EnableConnectCredentialForwarding (disabled by default):
```
=> ALTER USER penny SET EnableConnectCredentialForwarding=1;
```
On db_2, create an authentication record with the hash method:
Note

This example authentication record lets users authenticate to the database without TLS. In general, you should also configure client-server TLS and then specify HOST TLS so the hashed password is forwarded to the target database over a secure connection. For example:
```
      
=> CREATE AUTHENTICATION v_hash_auth METHOD 'hash' HOST TLS '0.0.0.0/0';
```
```
=> CREATE AUTHENTICATION v_hash_auth METHOD 'hash' HOST '0.0.0.0/0';
```

Grant the authentication record to penny:

=> GRANT AUTHENTICATION v_hash_auth TO penny;

On db_1, run CONNECT TO VERTICA to connect to db_2, omitting the password. This example uses the default port:
```
=> CONNECT TO VERTICA db_2 ON 'example.com', 5433;
```

TLS authentication

In the following example, Penny wants to run CONNECT TO VERTICA from db_1 to connect to db_2 without specifying her password:

Create the user penny on both databases.

=> CREATE USER penny IDENTIFIED BY 'my_password';

On db_1, create or import a CA certificate, server certificate, and client certificate.

-- Create a CA certificate
=> CREATE KEY root_key TYPE 'RSA' LENGTH 2048;

=>  CREATE CA CERTIFICATE mtls_root_cert
SUBJECT '/C=US/ST=Massachusetts/L=Burlington/O=OpenText/OU=Vertica/CN=Vertica Root CA'
VALID FOR 3650
EXTENSIONS 'authorityKeyIdentifier' = 'keyid:always,issuer', 'nsComment' = 'Vertica generated root CA cert'
KEY mtls_root_key;

-- Create a client certificate, signing it with the CA certificate
=> CREATE KEY client_key TYPE 'RSA' LENGTH 2048;

=> CREATE CERTIFICATE mtls_client_cert
SUBJECT '/C=US/ST=Massachusetts/L=Burlington/O=OpenText/OU=Vertica/CN=penny'
SIGNED BY mtls_root_cert
EXTENSIONS 'nsComment' = 'Vertica client cert', 'extendedKeyUsage' = 'clientAuth'
KEY mtls_client_key;

-- Create a server certificate, signing it with the CA certificate
CREATE KEY mtls_server_key TYPE 'RSA' LENGTH 2048;

CREATE CERTIFICATE mtls_server_cert
SUBJECT '/C=US/ST=Massachusetts/L=Burlington/O=OpenText/OU=Vertica/CN=*.example.com'
SIGNED BY mtls_root_cert
EXTENSIONS 'extendedKeyUsage' = 'serverAuth'
KEY mtls_server_key;

On db_1, create a custom TLS configuration to use with CONNECT TO VERTICA, adding the mtls_client_cert and mtls_root_cert as the certificates and setting TLSMODE to ENABLE or higher:
```
=> CREATE TLS CONFIGURATION mtls;
=> ALTER TLS CONFIGURATION mtls CERTIFICATE mtls_client_cert ADD CA CERTIFICATES mtls_root_cert TLSMODE 'ENABLE';
```

On db_2, import the CA certificate, server certificate, and server key from db_1. You can retrieve the contents of a certificate and key from the CERTIFICATES and CRYPTOGRAPHIC_KEYS system tables:

      
=> CREATE CA CERTIFICATE mtls_root_cert AS '-----BEGIN CERTIFICATE-----certificate_text-----END CERTIFICATE-----';
=> CREATE CERTIFICATE mtls_server_key AS '-----BEGIN PRIVATE KEY-----key-----END PRIVATE KEY-----'
=> CREATE CERTIFICATE mtls_server_cert AS '-----BEGIN CERTIFICATE-----certificate_text-----END CERTIFICATE-----';

On db_2, configure mutual mode client-server TLS using mtls_root_cert and mtls_server_cert and setting the TLSMODE to TRY_VERIFY or higher:

=> ALTER TLS CONFIGURATION server CERTIFICATE mtls_server_cert ADD CA CERTIFICATES mtls_root_cert TLSMODE 'TRY_VERIFY';

On db_2, create an authentication record for TLS authentication.

=> CREATE AUTHENTICATION mtls_auth METHOD 'tls' HOST TLS '0.0.0.0/0';

On db_2, grant mtls_auth to penny:

=> GRANT AUTHENTICATION mtls_auth TO penny;

On db_1, run CONNECT TO VERTICA to connect to db_2, specifying the mtls TLS Configuration. This example uses the default port:
```
=> CONNECT TO VERTICA vmart USER penny ON 'example.com', 5433 TLS CONFIGURATION mtls;
```

Sql-Reference: COPY

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

COPY bulk-loads data into an OpenText™ Analytics Database. By default, COPY automatically commits itself and any current transaction except when loading temporary tables. If COPY is terminated or interrupted, the database rolls it back.

COPY reads data as UTF-8 encoding.

For information on loading one or more files or pipes on a cluster host or on a client system, see COPY LOCAL.

To define a data pipeline to automatically load new files, see Automatic load.

Syntax

COPY [ /*+ LABEL (label-string)*/ ] [[{namespace. | database. }]schema.]target-table
   [ ( { column-as-expression | column }
       [ DELIMITER [ AS ] 'char' ]
       [ ENCLOSED [ BY ] 'char' ]
       [ ENFORCELENGTH ]
       [ ESCAPE [ AS ] 'char' | NO ESCAPE ]
       [ FILLER datatype]
       [ FORMAT 'format' ]
       [ NULL [ AS ] 'string' ]
       [ TRIM 'byte' ]
       [,...] ) ]
   [ COLUMN OPTION (column
       [ DELIMITER [ AS ] 'char' ]
       [ ENCLOSED [ BY ] 'char' ]
       [ ENFORCELENGTH ]
       [ ESCAPE [ AS ] 'char' | NO ESCAPE ]
       [ FORMAT 'format' ]
       [ NULL [ AS ] 'string' ]
       [ TRIM 'byte' ]
     [,...] ) ]
FROM {
   [ LOCAL ] STDIN [ compression ]
   | { 'path-to-data'
       [ ON { nodename | (nodeset) | ANY NODE | EACH NODE } ] [ compression ] }[,...]
     [ PARTITION COLUMNS column[,...] ]
   | LOCAL 'path-to-data' [ compression ] [,...]
   | VERTICA {source-namespace. | source-database. }[source-schema.]source-table[( source-column[,...] ) ]
  }
  [ NATIVE
    | FIXEDWIDTH COLSIZES {( integer )[,...]}
    | NATIVE VARCHAR
    | ORC
    | PARQUET
  ]
  | [ WITH ] UDL-clause[...]
}
   [ ABORT ON ERROR ]
   [ DELIMITER [ AS ] 'char' ]
   [ ENCLOSED [ BY ] 'char'
   [ ENFORCELENGTH ]
   [ ERROR TOLERANCE ]
   [ ESCAPE [ AS ] 'char' | NO ESCAPE ]
   [ EXCEPTIONS 'path' [ ON nodename] [,...]
   [ NULL [ AS ] 'string' ]
   [ RECORD TERMINATOR 'string' ]
   [ REJECTED DATA {'path' [ ON nodename] [,...] | AS TABLE reject-table} ]
   [ REJECTMAX integer ]
   [ SKIP integer ]
   [ SKIP BYTES integer ]
   [ STREAM NAME  'streamName']
   [ TRAILING NULLCOLS ]
   [ TRIM 'byte' ]
   [ [ WITH ] PARSER parser ([ arg=value[,...] ]) ] ]
   [ NO COMMIT ]

Parameters

See Parameters.

Restrictions

See Restrictions.

Privileges

Superusers have full COPY privileges. The following requirements apply to non-superusers:

INSERT privilege on table
USAGE privilege on schema
USER-accessible storage location
Applicable READ or WRITE privileges granted to the storage location where files are read or written

COPY can specify a path to store rejected data and exceptions. If the path resolves to a storage location, the following privileges apply to non-superusers:

The storage location was created with the USER option (see CREATE LOCATION).
The user must has READ access to the storage location, as described in GRANT (storage location)

Sql-Reference: COPY FROM VERTICA

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

Imports data from another OpenText™ Analytics Database. COPY FROM VERTICA is similar to COPY, but supports only a subset of its parameters.

Important

The source database must be no more than one major release behind the target database.

Syntax

COPY [[{database | namespace }.]target-schema.]target-table
    [( target-columns )]
    FROM VERTICA {source-database | source-namespace }.[source-schema.]source-table
    [( source-columns )]
    [STREAM NAME 'stream name']
    [NO COMMIT]

Arguments

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

target-table: The target table for the imported data. The database loads the data into all projections that include columns from the schema table.
target-columns: A comma-delimited list of columns in target-table to store the copied data.See Mapping Between Target and Source Columns below.
You cannot use FILLER columns or columns of complex types, except native arrays, as part of the column definition.
{ source-database | source-namespace }: The source of the data to import. Namespaces are available only in Eon Mode.
A connection to the source database must already exist in the current session before starting the copy operation; otherwise the database returns an error. For details, see CONNECT TO VERTICA.
[source-schema.]source-table: The table that is the source of the imported data. If schema is any schema other than public or if you specified a source-namespace, you must supply the schema name.
source-columns: A comma-delimited list of the columns in the source table to import. If omitted, all columns are exported.Columns cannot be of complex types. See Mapping Between Target and Source Columns below.
STREAM NAME: A COPY load stream identifier. Using a stream name helps to quickly identify a particular load. The STREAM NAME value that you specify in the load statement appears in the stream column of the LOAD_STREAMS system table.
NO COMMIT: Prevents COPY from committing its transaction automatically when it finishes copying data. For details, see Using transactions to stage a load.

Privileges

Source table: SELECT
Source table schema: USAGE
Target table: INSERT
Target table schema: USAGE

Mapping between target and source columns

If you copy all table data from one database to another, COPY FROM VERTICA can omit specifying column lists if column definitions in both tables comply with the following conditions:

Same number of columns
Identical column names
Same sequence of columns
Matching or compatible column data types
No complex data types (ARRAY, SET, or ROW), except for native arrays

If any of these conditions is not true, the COPY FROM VERTICA statement must include column lists that explicitly map target and source columns to each other, as follows:

Contain the same number of columns.
List source and target columns in the same order.
Pair columns with the same (or compatible) data types.

Node failure during COPY

See Handling node failure during copy/export.

Examples

The following example copies the contents of an entire table from the vmart database to an identically-defined table in the current database:

=> CONNECT TO VERTICA vmart USER dbadmin PASSWORD 'myPassword' ON 'VertTest01',5433;
CONNECT
=> COPY customer_dimension FROM  VERTICA vmart.customer_dimension;
 Rows Loaded
-------------
      500000
(1 row)
=> DISCONNECT vmart;
DISCONNECT

For more examples, see Copying data from another OpenText Analytics Database.

Sql-Reference: COPY LOCAL

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

Using the COPY statement with its LOCAL option lets you load data files (up to 4,294,967,295 files) on a client system, rather than on a cluster host. COPY LOCAL supports the STDIN and 'pathToData' parameters, but not the [ON nodename] clause. COPY LOCAL does not support multiple file batches in NATIVE or NATIVE VARCHAR formats. COPY LOCAL does not support reading ORC or Parquet files; use ON NODE instead. COPY LOCAL does not support CURRENT_LOAD_SOURCE().

The COPY LOCAL option is platform-independent. The statement works in the same way across all supported OpenText™ Analytics Database platforms and drivers. For more details about supported drivers, see Client drivers.

COPY LOCAL does not automatically create files detailing exceptions and rejections, even if exceptions occur.

COPY LOCAL is subject to the following restrictions when used with vsql and the client libraries:

COPY LOCAL must be the first statement in any multi-statement query.
COPY LOCAL cannot be used multiple times in the same query.

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.

Privileges

User must have INSERT privilege on the table and USAGE privilege on the schema.

How COPY LOCAL works

COPY LOCAL loads data in a platform-neutral way. The COPY LOCAL statement loads all files from a local client system to the database host, where the server processes the files. You can copy files in various formats: uncompressed, compressed, fixed-width format, in bzip or gzip format, or specified as a bash glob. Files of a single format (such as all bzip, or gzip) can be comma-separated in the list of input files. You can also use any of the applicable COPY statement options (as long as the data format supports the option). For instance, you can define a specific delimiter character, or how to handle NULLs, and so forth.

Note

The Linux glob command returns files that match the pattern you enter, as specified in the Linux Manual Page for Glob (7). For ADO.net platforms, specify patterns and wildcards as described in the .NET Directory.getFiles Method.

For more information about using the COPY LOCAL option to load data, see COPY for syntactical descriptions, and Specifying where to load data from for detailed examples.

The database host uncompresses and processes the files as necessary, regardless of file format or the client platform from which you load the files. Once the server has the copied files, the database maintains performance by distributing file parsing tasks, such as encoding, compressing, uncompressing, across nodes.

Viewing copy local operations in a query plan

When you use the COPY LOCAL option, the GraphViz query plan includes a label for Load-Client-File, rather than Load-File. Following is a section from a sample query plan:

-----------------------------------------------
  PLAN:  BASE BULKLOAD PLAN  (GraphViz Format)
-----------------------------------------------
 digraph G {
 graph [rankdir=BT, label = " BASE BULKLOAD PLAN \nAll Nodes Vector:
 \n\n  node[0]=initiator (initiator) Up\n", labelloc=t, labeljust=l ordering=out]
.
.
.
10[label = "Load-Client-File(/tmp/diff) \nOutBlk=[UncTuple]",
color = "green", shape = "ellipse"];

Examples

The following example shows a load from a local file.

$ cat > t.dat
12
17
9
^C

=> CREATE TABLE numbers (value INT);
CREATE TABLE

=> COPY numbers FROM LOCAL 't.dat';
 Rows Loaded
-------------
           3
(1 row)

=> SELECT * FROM numbers;
 value
-------
    12
    17
     9
(3 rows)

Sql-Reference: CREATE statements

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

CREATE statements let you create new database objects such as tables and users.

Sql-Reference: DEACTIVATE DIRECTED QUERY

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

Deactivates one or more directed queries previously activated by ACTIVATE DIRECTED QUERY.

Syntax

DEACTIVATE DIRECTED QUERY { query-name | input-query | where-clause }

Arguments

query-name

Name of the directed query to deactivate, as stored in the DIRECTED_QUERIES column query_name.

input-query

The input query of the directed queries to deactivate. Use this argument to deactivate multiple direct queries that map to the same input query.

where-clause

Resolves to one or more directed queries that are filtered from system table DIRECTED_QUERIES. For example, the following statement specifies to deactivate all directed queries with the same save_plans_version identifier:

=> DEACTIVATE DIRECTED QUERY WHERE save_plans_version = 21;

Privileges

Superuser

Examples

See Managing directed queries.

Sql-Reference: DELETE

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

Removes the specified rows from a table and returns a count of the deleted rows. A count of 0 is not an error, but indicates that no rows matched the condition. An unqualified DELETE statement (one that omits a WHERE clause) removes all rows but leaves intact table columns, projections, and constraints.

DELETE supports subqueries and joins, so you can delete values in a table based on values in other tables.

Important

OpenText™ Analytics Database implementation of DELETE differs from traditional databases; it does not delete data from disk storage, but instead marks rows as deleted so they are available for historical queries. Deleted data remains on disk and counts against disk quota, until purged.

Syntax

DELETE [ /*+LABEL (label-string)*/ ] 
  FROM [[{database | namespace }.]schema.]table [ where-clause ]

Arguments

LABEL: Assigns a label to a statement to identify it for profiling and debugging.

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

table: Any table, including temporary tables.
where-clause: Which rows to mark for deletion. If you omit this clause, DELETE behavior varies depending on whether the table is persistent or temporary. See below for details.

Privileges

Table owner or user with GRANT OPTION is grantor.

DELETE privilege on table
USAGE privilege on the schema of the target table
SELECT privilege on a table when the DELETE statement includes a WHERE or SET clause that specifies columns from that table.

Restrictions

You cannot execute DELETE on an immutable table.

Committing successive table changes

OpenText™ Analytics Database follows the SQL-92 transaction model, so successive INSERT, UPDATE, and DELETE statements are included in the same transaction. You do not need to explicitly start this transaction; however, you must explicitly end it with COMMIT, or implicitly end it with COPY. Otherwise, the database discards all changes that were made within the transaction.

Persistent and temporary tables

When deleting from a persistent table, DELETE removes data directly from the ROS.

DELETE execution on temporary tables varies, depending on whether the table was created with ON COMMIT DELETE ROWS (default) or ON COMMIT PRESERVE ROWS:

If DELETE contains a WHERE clause that specifies which rows to remove, behavior is identical: DELETE marks the rows for deletion. In both cases, you cannot roll back to an earlier savepoint.
If DELETE omits a WHERE clause and the table was created with ON COMMIT PRESERVE ROWS, the database marks all table rows for deletion. If the table was created with ON COMMIT DELETE ROWS, DELETE behaves like TRUNCATE TABLE and removes all rows from storage.

Note
If you issue an unqualified DELETE statement on a temporary table created with ON COMMIT DELETE ROWS, the database removes all rows from storage but does not end the transaction.

Examples

The following statement removes all rows from a temporary table:

=> DELETE FROM temp1;

The following statement deletes all records from a schema-qualified table where a condition is satisfied:

=> DELETE FROM retail.customer WHERE state IN ('MA', 'NH');

For examples that show how to nest a subquery within a DELETE statement, see Subqueries in UPDATE and DELETE.

Sql-Reference: DISCONNECT

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

Closes a connection to another OpenText™ Analytics Database that was opened in the same session with CONNECT TO VERTICA.

Note

Closing your session also closes the database connection. However, it is a good practice to explicitly close the connection to the other database, both to free up resources and to prevent issues with other SQL scripts that might be running in your session. Always closing the connection prevents potential errors if you run a script in the same session that attempts to open a connection to the same database, since each session can only have one connection to a given database at a time.

Syntax

DISCONNECT db-spec

Parameters

db-spec: Specifies the target database, either the database name or DEFAULT.

Privileges

None

Examples

=> DISCONNECT DEFAULT;
DISCONNECT

Sql-Reference: DO

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

Executes an anonymous (unnamed) stored procedure without saving it.

Syntax

DO [ LANGUAGE 'language-name' ] $$
    source
$$;

Parameters

language-name

Specifies the language of the procedure source, one of the following (both options refer to PLvSQL; PLpgSQL is included to maintain compatibility with existing scripts):

PLvSQL
PLpgSQL

Default: PLvSQL

source

The source code of the procedure.

Privileges

None

Examples

For more complex examples, see Stored procedures: use cases and examples

This procedure prints the variables in the DECLARE block:

DO LANGUAGE PLvSQL $$
DECLARE
    x int := 3;
    y varchar := 'some string';
BEGIN
    RAISE NOTICE 'x = %', x;
    RAISE NOTICE 'y = %', y;
END;
$$;

NOTICE 2005:  x = 3
NOTICE 2005:  y = some string

For more information on RAISE NOTICE, see Errors and diagnostics.

Sql-Reference: DROP statements

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

DROP statements let you delete database objects such as schemas, tables, and users.

Sql-Reference: END

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

Ends the current transaction and makes all changes that occurred during the transaction permanent and visible to other users.

Note

COMMIT is a synonym for END.

Syntax

END [ WORK | TRANSACTION ]

Parameters

WORK | TRANSACTION: Optional keywords that have no effect, for readability only.

Privileges

None

Examples

=> BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED READ WRITE;
BEGIN
=> CREATE TABLE sample_table (a INT);
CREATE TABLE
=> INSERT INTO sample_table (a) VALUES (1);
OUTPUT
--------
1
(1 row)

=> END;
COMMIT

Sql-Reference: EXECUTE DATA LOADER

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

EXECUTE DATA LOADER executes a data loader created with CREATE DATA LOADER. It attempts to load all files in the specifed location that have not already been loaded and that have not reached the retry limit. By default, executing the loader commits the transaction.

Data loaders are excuted with COPY ABORT ON ERROR.

EXECUTE DATA LOADER records events in the DATA_LOADER_EVENTS system table.

EXECUTE DATA LOADER runs the data loader once. To execute it periodically, you can use a scheduled stored procedure. To suspend execution, call ALTER DATA LOADER with the DISABLE option.

Syntax

EXECUTE DATA LOADER [schema.]name
   [ WITH FILES { file [ON { nodename | (nodeset) | ANY NODE | EACH NODE }] [compression] [{ EXACT_PATH | EXPAND_GLOB }] }[,...] ]
   [ FORCE RETRY ]
   [ BATCH_SIZE { 'size{K|M|G|T}' | '0' | 'UNLIMITED' } ]
   [ NO COMMIT ]

Arguments

schema: Schema containing the data loader. The default schema is public.
name: Name of the data loader.
WITH FILES file: Load only the specified files from the data loader's COPY path. Files that do not also match the COPY path are ignored. Files that have already been loaded are not reloaded. Both of these events are recorded in the loader's associated monitoring table.

Note

If a file includes node assignments or compression settings, these will override the corresponding settings in the original COPY statement for the specified file.
If a file does not include node assignments or compression settings, they will be inherited from the original COPY statement for the specified file.
If a file uses EXPAND_GLOB, the settings will not be inherited and you must explicitly specify them after the file if required.

For more information about COPY parameters (node assignment and compression), see Parameters.

EXACT_PATH | EXPAND_GLOB

How to match the named file:

EXACT_PATH (default): file names must match exactly. Any special characters in the file name are treated as literal parts of the name. For example, sales*.parquet specifies a single file whose name includes the * character.
EXPAND_GLOB: glob characters in file names are interpreted as globs. For example, sales*.parquet specifies one or more Parquet files begainning with sales.

FORCE RETRY

Ignore the retry limit.

BATCH_SIZE { 'size{K|M|G|T}' | '0' | 'UNLIMITED' }

When dividing a load for parallel execution, override the OpenText™ Analytics Database default and set the target total size of files to include in one batch. This value is a hint and batches could be larger, depending on the sizes of individual files.

If this option is omitted, the database chooses a size based on the total data volume and the number of executor nodes. The maximum batch size that the database automatically chooses is 10GB on each node, but you can specify a larger value with this option.

To set a target size, specify an integer with a unit of measure, such as '100M' or '2G'. To disable batch loads and load files one at a time, specify '0'. To load all files in a single batch, specify 'UNLIMITED'.

NO COMMIT

Do not commit the transaction after execution. Use when execution is part of an operation that must be atomic. SQS triggers use this option so that execution and queue management are part of the same transaction.

Privileges

Read privileges to the source location.

Non-superuser:

Owner or EXECUTE privilege on the data loader.
Write privilege on the table.

Examples

Execute a data loader once:

=> EXECUTE DATA LOADER sales_dl;
 Rows Loaded 
-------------
           5
(1 row)

Schedule a recurring execution:

=> CREATE SCHEDULE daily_load USING CRON '0 13 * * *';

--- statement must be quoted:
=> CREATE PROCEDURE dl_runner() as $$ begin EXECUTE 'EXECUTE DATA LOADER sales_dl'; end; $$;

=> CREATE TRIGGER t_load ON SCHEDULE daily_load EXECUTE PROCEDURE dl_runner() AS DEFINER;

Load specific files with globbing:

--- no file named '09*.dat' so nothing loaded by default:
=> EXECUTE DATA LOADER sales_dl 
   WITH FILES 's3://MyBucket/sales/2023/09*.dat';
 Rows Loaded 
-------------
           0
(1 row)

--- loads '09-01.dat', '09-02.dat', etc:
=> EXECUTE DATA LOADER sales_dl 
   WITH FILES 's3://MyBucket/sales/2023/09*.dat' EXPAND_GLOB;
 Rows Loaded 
-------------
          20
(1 row)

--- loads one glob and one specific file:
=> EXECUTE DATA LOADER sales_dl 
   WITH FILES 's3://MyBucket/sales/2023/09*.dat' EXPAND_GLOB, 
              's3://MyBucket/sales/2023/specials.dat' EXACT_PATH;
 Rows Loaded 
-------------
          32
(1 row)

See Automatic load for an extended example.

Sql-Reference: EXPLAIN

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

Returns a formatted description of the OpenText™ Analytics Database optimizer's plan for executing the specified statement.

Syntax

EXPLAIN [/*+ ALLNODES */] [explain-options] sql-statement

Parameters

/*+ALLNODES*/

Specifies to create a query plan that assumes all nodes are active, not valid with LOCAL option.

explain-options

One or more EXPLAIN options, specified in the order shown:

[ LOCAL ] [ VERBOSE ] [ JSON ] [ ANNOTATED ]

LOCAL: On a multi-node database, shows the local query plans assigned to each node, which together comprise the total (global) query plan. If you omit this option, the database shows only the global query plan. Local query plans are shown only in DOT language source, which can be rendered in Graphviz.

This option is incompatible with the hint /*+ALLNODES*/. If you specify both, EXPLAIN returns with an error.
VERBOSE: Increases the level of detail in the rendered query plan.
JSON: Renders the query plan in JSON format. This option is compatible only with VERBOSE.
ANNOTATED: Embeds optimizer hints that encapsulate the query plan for this query. This option is compatible with LOCAL and VERBOSE.

sql-statement

A query or DML statement—for example, SELECT, INSERT, UPDATE, COPY, and MERGE.

Privileges

The same privileges required by the specified statement.

Requirements

The following requirements apply to EXPLAIN's ability to produce useful information:

Reasonably representative statistics of your data must be available. See Collecting Statistics for details.
EXPLAIN produces useful output only if projections are available for the queried tables.
Qualifier options must be specified in the order shown earlier, otherwise EXPLAIN returns with an error. If an option is incompatible with any preceding options, EXPLAIN ignores them.

Examples

See Viewing query plans.

Sql-Reference: EXPORT TO DELIMITED

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

Exports a table, columns from a table, or query results to delimited files. The files can be read back in using DELIMITED. Several exporter parameters have corresponding parser parameters, allowing you to change delimiters, null indicators, and other formatting.

There are some limitations on the queries you can use in an export statement. See Query Restrictions.

You can export ROS‑format data and data from external tables in the OpenText™ Analytics Database, and you can also export data to Iceberg tables. The supported catalog types are filesystem, glue, and hms. For more information, see EXPORT TO ICEBERG.

File exporters are UDxs that cannot be run in fenced mode. If the ForceUDxFencedMode configuration parameter is set to true to support other UDxs, you can set it to false at the session level before performing the export.

This statement returns the number of rows written and logs information about exported files in a system table. See Monitoring exports.

During an export to HDFS or an NFS mount point, the database writes files to a temporary directory in the same location as the destination and renames the directory when the export is complete. Do not attempt to use the files in the temporary directory. During an export to S3, GCS, or Azure, the database writes files directly to the destination path, so you must wait for the export to finish before reading the files. For more information, see Exporting to object stores.

Syntax

EXPORT [ /*+LABEL (label-string)*/ ] TO DELIMITED 
   ( directory='path'[, param=value[,...] ] )
   [ OVER (over-clause ) ] AS SELECT query-expression

Arguments

LABEL

Assigns a label to a statement to identify it for profiling and debugging.

over-clause

Specifies how to partition table data using PARTITION BY. Within partitions you can sort using ORDER BY. See SQL analytics. This clause may contain column references but not expressions.

If you partition data, the database creates a partition directory structure, transforming column names to lowercase. See Partitioned data for a description of the directory structure. If you use the fileName parameter, you cannot use partitioning.

If you omit this clause, the database optimizes for maximum parallelism.

query-expression

Specifies the data to export. See Query Restrictions for important limitations.

Parameters

directory

The destination directory for the output files. The current user must have permission to write it. The destination can be on any of the following file systems:

HDFS file system
S3 object store
Google Cloud Storage (GCS) object store
Azure Blob Storage object store
Linux file system, either an NFS mount or local storage on each node

See also: ifDirExists.

ifDirExists

What to do if directory already exists, one of:

fail (default)
overwrite: replace the entire directory
append: export new files into the existing directory with a prepended hash that identifies all files in the exported batch
appendNoHash: export new files into the existing directory without a prepended hash; with this option, the database cannot clean up partial exports

If you specify overwrite for an export to an object store, the existing directory is deleted recursively at the beginning of the operation and is not restored if the operation fails. Be careful not to export to a directory containing data you want to keep. For an export to a Linux file system or HDFS, the directory is only overwritten if the export succeeds.

Do not do concurrent exports to the same directory. In particular, if you do so with a value of overwrite, all operations appear to succeed, but the results are incorrect.

When using append, be careful to use the same table schema. Otherwise, queries of external tables using this data path could fail.

filename

If specified, all output is written to a single file of this name in the location specified by directory. While the query can be processed by multiple nodes, only a single node generates the output data. The fileSizeMB parameter is ignored, and the query cannot use partitioning in the OVER() clause.

filePrefix

Prefix to use for exported files instead of the default hash. If used with ifDirExists=appendNoHash, choose a unique prefix to avoid overwriting existing files.

addHeader

If true, add a header row to the beginning of each file.

Default: false

delimiter

Column delimiter character. To produce CSV in accordance with RFC 4180, set the delimiter character to , (comma).

Default: | (vertical bar)

escapeDelimitersInsideEnclosures

If true, delimiter characters are escaped within values that are enclosed by enclosedBy. This parameter is most relevant when enclosedBy and escapeAs have the same value. A value of false only applies when enclosedBy has a value (is not an empty string).

Default: true

recordTerminator

Character that marks the record end.

Default: \n

enclosedBy

Character to use to enclose string and date/time data. If you omit this parameter, no character encloses these data types.

Default: '' (empty string, no enclosing character)

escapeAs

Character to use to escape values in exported data that must be escaped, including the enclosedBy value.

Default: \ (backslash)

nullAs

String to represent null values in the data. If this parameter is included, the exporter exports all null values as this value. Otherwise, the exporter exports null values as zero-length strings.

binaryTypesFormat

Format for exported binary data type (BINARY, VARBINARY, and LONG VARBINARY) values, one of the following:

Default: Printable ASCII characters where possible and escaped octal representations of the non-printable bytes. The DELIMITED parser reads this format.
Hex: Base 16 (hexadecimal) representation; value is preceded by '0x' and bytes are not escaped.
Octal: Base 8 (octal) representation, without escaping.
Bitstring: Binary representation, without escaping.

For example, the value a\000b\001c can be exported as follows:

Default (assuming an escape character of \): a\\000b\\001c
Hex: 0x6100620163
Octal: 141000142001143
Bitstring: 0110000100000000011000100000000101100011

compression

Compression type, one of:

Uncompressed
BZip
GZip

Default: Uncompressed

fileExtension

Output file extension. If using compression, a compression-specific extension such as .bz2 is appended.

Default: csv

fileSizeMB

The maximum file size of a single output file. This value is a hint, not a hard limit. A value of 0 specifies no limit. If filename is also specified, fileSizeMB is ignored.

This value affects the size of individual output files, not the total output size. For smaller values, the database divides the output into more files; all data is still exported.

Default: 10GB

fileMode

For writes to HDFS only, permission to apply to all exported files. You can specify the value in Unix octal format (such as 665) or user-group-other format—for example, rwxr-xr-x. The value must be formatted as a string even if using the octal format.

Valid octal values range between 0 and 1777, inclusive. See HDFS Permissions in the Apache Hadoop documentation.

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 660, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

dirMode

For writes to HDFS only, permission to apply to all exported directories. Values follow the same rules as those for fileMode. Further, you must give the HDFS user full permission, at least rwx------ or 700.

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 755, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

Privileges

Non-superusers:

Source table: SELECT
Source table schema: USAGE
Destination directory: Write

Query restrictions

You must provide an alias column label for selected column targets that are expressions.

If you partition the output, you cannot specify schema and table names in the SELECT statement. Specify only the column name.

The query can contain only a single outer SELECT statement. For example, you cannot use UNION:

=> EXPORT TO DELIMITED(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT 1 as account_id, '{}' as json, 0 hash
   UNION ALL
   SELECT 2 as account_id, '{}' as json, 1 hash;
ERROR 8975:  Only a single outer SELECT statement is supported
HINT:  Please use a subquery for multiple outer SELECT statements

Instead, rewrite the query to use a subquery:

=> EXPORT TO DELIMITED(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT
    account_id,
    json
   FROM
   (
     SELECT 1 as account_id, '{}' as json, 0 hash
     UNION ALL
     SELECT 2 as account_id, '{}' as json, 1 hash
   ) a;
 Rows Exported
---------------
             2
(1 row)

To use composite statements such as UNION, INTERSECT, and EXCEPT, rewrite them as subqueries.

Data types

EXPORT TO DELIMITED does not support ARRAY, ROW, and SET types.

This operation exports raw Flex columns as binary data.

Output

The export operation always creates (or appends to) an output directory, even if all output is written to a single file or the query produces zero rows.

By default, output file names follow the pattern: prefix-nodename-threadId[-sequenceNumber].extension. prefix is typically an 8-character hash, but can be longer if the export appended to an existing directory. A sequence number is added if an export needs to be broken into pieces to satisfy fileSizeMB. You can change the prefix using the filePrefix parameter or, for appends, by setting ifDirExists=appendNoHash. You can write all output to a single named file using the filename parameter.

Column names in partition directories are lowercase.

Files exported to a local file system by any OpenText™ Analytics Database user are owned by the database superuser. Files exported to HDFS or object stores are owned by the database user who exported the data.

Making concurrent exports to the same output destination is an error and can produce incorrect results.

Exports to the local file system can be to an NFS mount (shared) or to the Linux file system on each node (non-shared). For details, see Exporting to the Linux file system. Exports to non-shared local file systems have the following restrictions:

The output directory must not exist on any node.
You must have a USER storage location or superuser privileges.
You cannot override the permissions mode of 700 for directories and 600 for files.

Exports to object-store file systems are not atomic. Be careful to wait for the export to finish before using the data. For details, see Exporting to object stores.

Examples

The following example exports uncompressed comma-separated values (CSV) with a header row in each file:

=> EXPORT TO DELIMITED(directory='webhdfs:///user1/data', delimiter=',', addHeader='true')
  AS SELECT * FROM public.sales;

Sql-Reference: EXPORT TO ICEBERG

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

Exports data from OpenText™ Analytics Database tables into Apache Iceberg format, an open table format for large-scale analytics with ACID transaction support. Iceberg tables store data in Parquet format, a columnar storage format optimized for such workloads. This integration allows database users to use data lake architectures and interoperate with query engines such as Apache Spark, Trino, and Flink.

Benefits

Interoperability: Share data across multiple query engines.
Open format: Avoid vendor lock-in by using Iceberg’s open standard.
Flexible storage: Supports cloud storage (AWS S3, Azure Blob, GCS) and on-premises storage (HDFS, NFS, S3-compatible, local storage).
Scalability: Manage large datasets efficiently with Iceberg’s metadata layer.

Use cases

Moving cold data from OpenText™ Analytics Database to a lower-cost data lake architecture.
Sharing database data with Spark or Trino to accomodate for existing data pipelines.
Building a multi-engine query environment using Iceberg tables.

Prerequisites

OpenText™ Analytics Database 25.4 or later.
Permissions on the target storage location.

Usage

Exporting to Iceberg is currently performed using the EXPORT TO PARQUET command along with the icebergCatalog parameter. For more information about the syntax, see EXPORT TO PARQUET.

Examples

Filesystem catalog

Export data from a table named large_t  to an Iceberg table on the file system, using /mnt/shared_nfs/accounts as the directory for the Iceberg table.

=> EXPORT TO PARQUET(icebergCatalog='filesystem', directory='/mnt/shared_nfs/accounts')
  AS SELECT * FROM large_t;

AWS Glue catalog

Export data from a table named sales_orders  to an Iceberg table on AWS Glue, using s3://data-lake/iceberg/customer_orders as the directory for the Iceberg table.

=> EXPORT TO PARQUET(icebergCatalog='glue', glueDB='analytics', glueTable='customer_orders', directory='s3://data-lake/iceberg/customer_orders') AS SELECT * FROM sales_orders;

Hive Metastore catalog

Export data from a table named users_connection to an HDFS location webhdfs://hive-metastore-host:9870/iceberg/users managed under the Hive Metastore Iceberg catalog.

=> EXPORT TO PARQUET(icebergCatalog='hms', hmsDB='testdb', hmsTable='users', hmsUri='thrift://hive-metastore-host:9083', directory='webhdfs://hive-metastore-host:9870/iceberg/users', ifDirExists='overwrite') 
AS SELECT * FROM users_connection;

Export data from a table named users_connection to an S3 location s3://data-lake/iceberg/users managed under the Hive Metastore Iceberg catalog.

=> EXPORT TO PARQUET(icebergCatalog='hms', hmsDB='testdb', hmsTable='users', hmsUri='thrift://hive-metastore-host:9083', directory='s3://data-lake/iceberg/users', ifDirExists='overwrite') 
AS SELECT * FROM users_connection;

Output directory structure

After a successful run, the directory specified in the examples contains the following structure:

├── data 

│   ├── *.parquet 

└── metadata 

    ├── *.manifest.avro 

    ├── manifest-list.avro 

    └── v1.metadata.json

All Parquet data files will be written to the data/subdirectory.
All Iceberg metadata files will be written to the metadata/subdirectory.

Not supported

The following items are not supported in this release; OpenText plans to address them in the upcoming release:

No partition support: The export process does not partition data for Iceberg tables. All data is written as a single, flat structure without partitioned directories.
No complex data types: Only primitive data types (such as integers, strings, and dates) are supported. Complex types like arrays, maps, and structs cannot be exported.
No append or modify operations: You cannot append data to an existing Iceberg table or modify its contents. The export process supports only creating new tables or overwriting existing data completely.

Sql-Reference: EXPORT TO JSON

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

Exports a table, columns from a table, or query results to JSON files. The files can be read back into OpenText™ Analytics Database using FJSONPARSER.

There are some limitations on the queries you can use in an export statement. See Query Restrictions.

This statement returns the number of rows written and logs information about exported files in a system table. See Monitoring exports.

Syntax

EXPORT [ /*+LABEL (label)*/ ] TO JSON 
   ( directory='path'[, param=value[,...] ] )
   [ OVER (over-clause ) ] AS SELECT query-expression

Arguments

LABEL

Assigns a label to a statement to identify it for profiling and debugging.

over-clause

Specifies how to partition table data using PARTITION BY. Within partitions you can sort using ORDER BY. See SQL analytics. This clause may contain column references but not expressions.

If you omit this clause, the database optimizes for maximum parallelism.

query-expression

Specifies the data to export. See Query Restrictions for important limitations.

Parameters

directory

The destination directory for the output files. The current user must have permission to write it. The destination can be on any of the following file systems:

HDFS file system
S3 object store
Google Cloud Storage (GCS) object store
Azure Blob Storage object store
Linux file system, either an NFS mount or local storage on each node

See also: ifDirExists.

ifDirExists

What to do if directory already exists, one of:

fail (default)
overwrite: replace the entire directory
append: export new files into the existing directory with a prepended hash that identifies all files in the exported batch
appendNoHash: export new files into the existing directory without a prepended hash; with this option, the database cannot clean up partial exports

Do not do concurrent exports to the same directory. In particular, if you do so with a value of overwrite, all operations appear to succeed, but the results are incorrect.

When using append, be careful to use the same table schema. Otherwise, queries of external tables using this data path could fail.

filename

filePrefix

Prefix to use for exported files instead of the default hash. If used with ifDirExists=appendNoHash, choose a unique prefix to avoid overwriting existing files.

omitNullFields

Boolean, whether to omit ROW fields with null values.

Default: false

compression

Compression type, one of:

Uncompressed
BZip
GZip

Default: Uncompressed

fileSizeMB

The maximum file size of a single output file. This value is a hint, not a hard limit. A value of 0 specifies no limit. If filename is also specified, fileSizeMB is ignored.

This value affects the size of individual output files, not the total output size. For smaller values, the database divides the output into more files; all data is still exported.

Default: 10GB

fileMode

Valid octal values range between 0 and 1777, inclusive. See HDFS Permissions in the Apache Hadoop documentation.

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 660, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

dirMode

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 755, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

Privileges

Non-superusers:

Source table: SELECT
Source table schema: USAGE
Destination directory: Write

Query restrictions

You must provide an alias column label for selected column targets that are expressions.

If you partition the output, you cannot specify schema and table names in the SELECT statement. Specify only the column name.

The query can contain only a single outer SELECT statement. For example, you cannot use UNION:

=> EXPORT TO JSON(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT 1 as account_id, '{}' as json, 0 hash
   UNION ALL
   SELECT 2 as account_id, '{}' as json, 1 hash;
ERROR 8975:  Only a single outer SELECT statement is supported
HINT:  Please use a subquery for multiple outer SELECT statements

Instead, rewrite the query to use a subquery:

=> EXPORT TO JSON(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT
    account_id,
    json
   FROM
   (
     SELECT 1 as account_id, '{}' as json, 0 hash
     UNION ALL
     SELECT 2 as account_id, '{}' as json, 1 hash
   ) a;
 Rows Exported
---------------
             2
(1 row)

To use composite statements such as UNION, INTERSECT, and EXCEPT, rewrite them as subqueries.

Data types

EXPORT TO JSON can export ARRAY and ROW types in any combination.

EXPORT TO JSON does not support binary output (VARBINARY).

Output

The export operation always creates (or appends to) an output directory, even if all output is written to a single file or the query produces zero rows.

Column names in partition directories are lowercase.

Making concurrent exports to the same output destination is an error and can produce incorrect results.

The output directory must not exist on any node.
You must have a USER storage location or superuser privileges.
You cannot override the permissions mode of 700 for directories and 600 for files.

Exports to object-store file systems are not atomic. Be careful to wait for the export to finish before using the data. For details, see Exporting to object stores.

Examples

In the following example, one of the ROW elements has a null value, which is omitted in the output. EXPORT TO JSON writes each JSON record on one line; line breaks have been inserted into the following output for readability:

=> SELECT name, menu FROM restaurants;
       name        |                                     menu
-------------------+------------------------------------------------------------------------------
 Bob's pizzeria    | [{"item":"cheese pizza","price":null},{"item":"spinach pizza","price":10.5}]
 Bakersfield Tacos | [{"item":"veggie taco","price":9.95},{"item":"steak taco","price":10.95}]
(2 rows)

=> EXPORT TO JSON (directory='/output/json', omitNullFields=true)
   AS SELECT * FROM restaurants;
 Rows Exported
---------------
             2
(1 row)

=> \! cat /output/json/*.json
{"name":"Bob's pizzeria","cuisine":"Italian","location_city":["Cambridge","Pittsburgh"],
 "menu":[{"item":"cheese pizza"},{"item":"spinach pizza","price":10.5}]}
{"name":"Bakersfield Tacos","cuisine":"Mexican","location_city":["Pittsburgh"],
 "menu":[{"item":"veggie taco","price":9.95},{"item":"steak taco","price":10.95}]}

Sql-Reference: EXPORT TO ORC

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

Exports a table, columns from a table, or query results to files in the ORC format.

You can use an OVER() clause to partition the data before export. You can partition data instead of or in addition to exporting the column data. Partitioning data can improve query performance by enabling partition pruning. See Partitioned data.

There are some limitations on the queries you can use in an export statement. See Query Restrictions.

This statement returns the number of rows written and logs information about exported files in a system table. See Monitoring exports.

Syntax

EXPORT [ /*+LABEL (label-string)*/ ] TO ORC 
   ( directory='path'[, param=value[,...] ] )
   [ OVER (over-clause ) ] AS SELECT query-expression

Arguments

LABEL

Assigns a label to a statement to identify it for profiling and debugging.

over-clause

Specifies how to partition table data using PARTITION BY. Within partitions you can sort using ORDER BY. See SQL analytics. This clause may contain column references but not expressions.

If you omit this clause, the database optimizes for maximum parallelism.

query-expression

Specifies the data to export. See Query Restrictions for important limitations.

Parameters

directory

The destination directory for the output files. The current user must have permission to write it. The destination can be on any of the following file systems:

HDFS file system
S3 object store
Google Cloud Storage (GCS) object store
Azure Blob Storage object store
Linux file system, either an NFS mount or local storage on each node

See also: ifDirExists.

ifDirExists

What to do if directory already exists, one of:

fail (default)
overwrite: replace the entire directory
append: export new files into the existing directory with a prepended hash that identifies all files in the exported batch
appendNoHash: export new files into the existing directory without a prepended hash; with this option, the database cannot clean up partial exports

Do not do concurrent exports to the same directory. In particular, if you do so with a value of overwrite, all operations appear to succeed, but the results are incorrect.

When using append, be careful to use the same table schema. Otherwise, queries of external tables using this data path could fail.

filename

filePrefix

Prefix to use for exported files instead of the default hash. If used with ifDirExists=appendNoHash, choose a unique prefix to avoid overwriting existing files.

compression

Column compression type, one of:

Zlib
Uncompressed

Default: Zlib

stripeSizeMB

The uncompressed size of exported stripes in MB, an integer value between 1 and 1024, inclusive.

Default: 250

rowIndexStride

Integer that specifies how frequently the exporter builds indexing statistics in the output, between 1 and 1000000 (1 million), inclusive. A value of 0 disables indexing. The exporter builds statistics after every rowIndexStride rows in each stripe, or once for stripes < rowIndexStride.

Default: 1000

fileSizeMB

The maximum file size of a single output file. This value is a hint, not a hard limit. A value of 0 specifies no limit. If filename is also specified, fileSizeMB is ignored.

This value affects the size of individual output files, not the total output size. For smaller values, the database divides the output into more files; all data is still exported.

Default: 10GB

fileMode

Valid octal values range between 0 and 1777, inclusive. See HDFS Permissions in the Apache Hadoop documentation.

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 660, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

dirMode

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 755, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

Privileges

Non-superusers:

Source table: SELECT
Source table schema: USAGE
Destination directory: Write

Query restrictions

You must provide an alias column label for selected column targets that are expressions.

If you partition the output, you cannot specify schema and table names in the SELECT statement. Specify only the column name.

The query can contain only a single outer SELECT statement. For example, you cannot use UNION:

=> EXPORT TO ORC(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT 1 as account_id, '{}' as json, 0 hash
   UNION ALL
   SELECT 2 as account_id, '{}' as json, 1 hash;
ERROR 8975:  Only a single outer SELECT statement is supported
HINT:  Please use a subquery for multiple outer SELECT statements

Instead, rewrite the query to use a subquery:

=> EXPORT TO ORC(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT
    account_id,
    json
   FROM
   (
     SELECT 1 as account_id, '{}' as json, 0 hash
     UNION ALL
     SELECT 2 as account_id, '{}' as json, 1 hash
   ) a;
 Rows Exported
---------------
             2
(1 row)

To use composite statements such as UNION, INTERSECT, and EXCEPT, rewrite them as subqueries.

Data types

EXPORT TO ORC converts OpenText™ Analytics Database data types to Hive data types as shown in the following table.

OpenText™ Analytics Database Data Type	Hive Data Type
INTEGER, BIGINT	BIGINT
FLOAT, DECIMAL, SMALLINT, TINYINT, CHAR, BOOLEAN	Corresponding Hive type
VARCHAR, LONG VARCHAR	VARCHAR (max 64KB) or STRING (can be read as either)
BINARY, VARBINARY, LONG VARBINARY	BINARY
DATE	DATE if supported by your version of Hive, otherwise INT96 (can be read as TIMESTAMP)
TIMESTAMP, TIMESTAMPTZ	TIMESTAMP. The database does not convert TIMESTAMP values to UTC. To avoid problems arising from time zones, use TIMESTAMPTZ instead of TIMESTAMP.
TIME, TIMEZ, INTERVAL, UUID	Not supported
ARRAY, SET	Not supported
ROW	Not supported

Decimal precision must be <= 38.

The exported Hive types might not be identical to the database types. For example, a database INT is exported as a Hive BIGINT. When defining Hive external tables to read exported data, you might have to adjust column definitions.

This operation exports raw Flex columns as binary data.

Output

The export operation always creates (or appends to) an output directory, even if all output is written to a single file or the query produces zero rows.

Column names in partition directories are lowercase.

Making concurrent exports to the same output destination is an error and can produce incorrect results.

The output directory must not exist on any node.
You must have a USER storage location or superuser privileges.
You cannot override the permissions mode of 700 for directories and 600 for files.

Exports to object-store file systems are not atomic. Be careful to wait for the export to finish before using the data. For details, see Exporting to object stores.

Examples

The following example demonstrates partitioning and exporting data. EXPORT TO ORC first partitions the data on region and then, within each partition, sorts by store.

=> EXPORT TO ORC(directory='gs://DataLake/user2/data')
  OVER(PARTITION BY store.region ORDER BY store.ID)
  AS SELECT sale.price, sale.date, store.ID
  FROM public.sales sale
  JOIN public.vendor store ON sale.distribID = store.ID;

For more examples, see EXPORT TO PARQUET, which (aside from a few parameters) behaves the same as EXPORT TO ORC.

Sql-Reference: EXPORT TO PARQUET

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

Exports a table, columns from a table, or query results to files in the Parquet format.

There are some limitations on the queries you can use in an export statement. See Query Restrictions.

This statement returns the number of rows written and logs information about exported files in a system table. See Monitoring exports.

After you export data, you can use the GET_METADATA function to inspect the results.

Syntax

EXPORT [ /*+LABEL (label-string)*/ ] TO PARQUET 
   (directory='path'[, param=value[,...] ] )
   [ OVER (over-clause ) ] AS SELECT query-expression

Arguments

LABEL

Assigns a label to a statement to identify it for profiling and debugging.

over-clause

Specifies how to partition table data using PARTITION BY. Within partitions you can sort using ORDER BY. See SQL analytics. This clause may contain column references but not expressions.

If you omit this clause, the database optimizes for maximum parallelism.

query-expression

Specifies the data to export. See Query Restrictions for important limitations.

Parameters

icebergCatalog

Specifies the catalog that manages the Iceberg table and stores its metadata.

filesystem: Stores Iceberg metadata in a local or distributed filesystem.
glue: Stores Iceberg metadata in AWS Glue. Requires the glueDB and glueTable parameters.

glueDB

Name of the AWS Glue database. The glueTable parameter must also be specified.

glueTable

Name of the AWS Glue table. The glueDB parameter must also be specified.
hms: Stores Iceberg table metadata to the exported HMS directory and automatically registers the table in HMS using the connection information you provide.

hmsDB

Name of the Hive database. The hmsTable parameter must also be specified.

hmsTable

Name of the Hive table. The hmsDB parameter must also be specified.

hmsUri

URI of the Hive metastore in the format 'thrift://host:port'. This provides the address of the Hive Metastore service hosting the specified HMS database (hmsDB).

For more information, see EXPORT TO ICEBERG.

directory

The destination directory for the output files. The current user must have permission to write it. The destination can be on any of the following file systems:

HDFS file system
S3 object store
Google Cloud Storage (GCS) object store
Azure Blob Storage object store
Linux file system, either an NFS mount or local storage on each node

See also: ifDirExists.

ifDirExists

What to do if directory already exists, one of:

fail (default)
overwrite: replace the entire directory
append: export new files into the existing directory with a prepended hash that identifies all files in the exported batch
appendNoHash: export new files into the existing directory without a prepended hash; with this option, the database cannot clean up partial exports

Do not do concurrent exports to the same directory. In particular, if you do so with a value of overwrite, all operations appear to succeed, but the results are incorrect.

When using append, be careful to use the same table schema. Otherwise, queries of external tables using this data path could fail.

filename

filePrefix

Prefix to use for exported files instead of the default hash. If used with ifDirExists=appendNoHash, choose a unique prefix to avoid overwriting existing files.

compression

Column compression type, one of:

Snappy
GZIP
Brotli
ZSTD
Uncompressed

Default: Snappy

rowGroupSizeMB

The uncompressed size of exported row groups, in MB, an integer value between 1 and fileSizeMB , inclusive, or unlimited if fileSizeMB is 0.

The row groups in the exported files are smaller than this value because Parquet files are compressed on write. For best performance when exporting to HDFS, set size to be smaller than the HDFS block size.

Row-group size affects memory consumption during export. An export thread consumes at least double the row-group size. The default value of 512MB is a compromise between writing larger row groups and allowing enough free memory for other OpenText™ Analytics Database operations. If you perform exports when the database is not otherwise under heavy load, you can improve read performance on the exported data by increasing row-group size on export. However, row groups that span multiple blocks on HDFS decrease read performance by requiring more I/O, so do not set the row-group size to be larger than your HDFS block size.

Default: 512

fileSizeMB

The maximum file size of a single output file. This value is a hint, not a hard limit. A value of 0 specifies no limit. If filename is also specified, fileSizeMB is ignored.

This value affects the size of individual output files, not the total output size. For smaller values, the database divides the output into more files; all data is still exported.

Default: 10GB

fileMode

Valid octal values range between 0 and 1777, inclusive. See HDFS Permissions in the Apache Hadoop documentation.

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 660, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

dirMode

When writing files to any destination other than HDFS, this parameter has no effect.

Default: 755, regardless of the value of fs.permissions.umask-mode in hdfs-site.xml.

int96AsTimestamp

Boolean, specifies whether to export timestamps as int96 physical type (true) or int64 physical type (false).

Default: true

Privileges

Non-superusers:

Source table: SELECT
Source table schema: USAGE
Destination directory: Write

Query restrictions

You must provide an alias column label for selected column targets that are expressions.

If you partition the output, you cannot specify schema and table names in the SELECT statement. Specify only the column name.

The query can contain only a single outer SELECT statement. For example, you cannot use UNION:

=> EXPORT TO PARQUET(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT 1 as account_id, '{}' as json, 0 hash
   UNION ALL
   SELECT 2 as account_id, '{}' as json, 1 hash;
ERROR 8975:  Only a single outer SELECT statement is supported
HINT:  Please use a subquery for multiple outer SELECT statements

Instead, rewrite the query to use a subquery:

=> EXPORT TO PARQUET(directory = '/mnt/shared_nfs/accounts/rm')
   OVER(PARTITION BY hash)
   AS
   SELECT
    account_id,
    json
   FROM
   (
     SELECT 1 as account_id, '{}' as json, 0 hash
     UNION ALL
     SELECT 2 as account_id, '{}' as json, 1 hash
   ) a;
 Rows Exported
---------------
             2
(1 row)

To use composite statements such as UNION, INTERSECT, and EXCEPT, rewrite them as subqueries.

Data types

EXPORT TO PARQUET converts database data types to Hive data types as shown in the following table.

Database Data Type	Hive Data Type
INTEGER, BIGINT	BIGINT
FLOAT, DECIMAL, SMALLINT, TINYINT, CHAR, BOOLEAN	Corresponding Hive type
VARCHAR, LONG VARCHAR	VARCHAR (max 64KB) or STRING (can be read as either)
BINARY, VARBINARY, LONG VARBINARY	BINARY
DATE	DATE if supported by your version of Hive, otherwise INT96 (can be read as TIMESTAMP)
TIMESTAMP, TIMESTAMPTZ	TIMESTAMP. The database does not convert TIMESTAMP values to UTC. To avoid problems arising from time zones, use TIMESTAMPTZ instead of TIMESTAMP.
INTERVAL	INT64
TIME	INT64
TIMETZ	Not supported
ARRAY	ARRAY
SET	Not supported
ROW	STRUCT

Decimal precision must be <= 153.

This operation exports raw Flex columns as binary data.

Output

The export operation always creates (or appends to) an output directory, even if all output is written to a single file or the query produces zero rows.

Column names in partition directories are lowercase.

Making concurrent exports to the same output destination is an error and can produce incorrect results.

The output directory must not exist on any node.
You must have a USER storage location or superuser privileges.
You cannot override the permissions mode of 700 for directories and 600 for files.

Exports to object-store file systems are not atomic. Be careful to wait for the export to finish before using the data. For details, see Exporting to object stores.

Examples

The following example demonstrates exporting all columns from theT1 table in the public schema, using GZIP compression.

=> EXPORT TO PARQUET(directory='webhdfs:///user1/data', compression='gzip')
  AS SELECT * FROM public.T1;

The following example demonstrates exporting the results of a query using more than one table.

=> EXPORT TO PARQUET(directory='s3://DataLake/sales_by_region')
   AS SELECT sale.price, sale.date, store.region
   FROM public.sales sale
   JOIN public.vendor store ON sale.distribID = store.ID;

The following example demonstrates partitioning and exporting data. EXPORT TO PARQUET first partitions the data on region and then, within each partition, sorts by store.

=> EXPORT TO PARQUET(directory='gs://DataLake/user2/data')
  OVER(PARTITION BY store.region ORDER BY store.ID)
  AS SELECT sale.price, sale.date, store.ID
  FROM public.sales sale
  JOIN public.vendor store ON sale.distribID = store.ID;

The following example uses an alias column label for a selected column target that is an expression.

=> EXPORT TO PARQUET(directory='webhdfs:///user3/data')
  OVER(ORDER BY col1) AS SELECT col1 + col1 AS A, col2
  FROM public.T3;

The following example sets permissions for the output.

=> EXPORT TO PARQUET(directory='webhdfs:///user1/data',
     fileMode='432', dirMode='rwxrw-r-x')
  AS SELECT * FROM public.T1;

The following example demonstrates exporting data to an Iceberg table and then registering it in Hive Metastore (HMS).

=> EXPORT TO PARQUET(
     icebergCatalog='hms', 
     hmsDB='analytics', 
     hmsTable='sales_by_district',
     hmsUri='thrift://172.17.0.101:9083', 
     directory='webhdfs://172.17.0.99:9870/data/sales_by_region',
     ifDirExists='overwrite')
  AS SELECT * FROM public_sales_connection;

Sql-Reference: EXPORT TO VERTICA

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

Exports table data from one OpenText™ Analytics Database to another. A connection to the target database must exist in the current session before starting the copy operation. Otherwise, the database returns an error. For details, see CONNECT TO VERTICA.

Important

The source database must be no more than one major release behind the target database.

Syntax

EXPORT [ /*+LABEL (label-string)*/ ] TO VERTICA
   [[ { target-db | target-ns }.]target-schema.]target-table [ ( target-columns ) ]
   { AS SELECT query-expression | FROM [[namespace.]schema.]source-table[ ( source-columns ) ] }

Arguments

LABEL: Assigns a label to a statement to identify it for profiling and debugging.
target-db: The target database to which data is exported. A connection to this database must already exist in the current session before starting the copy operation; otherwise the database returns an error. For details, see CONNECT TO VERTICA.
target-ns: For Eon Mode databases, namespace in the target database to which data is exported. If unspecified, the target namespace is default_namespace.
target-schema: The target schema to which data is exported, or public if not specified.
target-table: The table in the target database to store the exported data. The table cannot have columns of complex data types other than native arrays.
target-columns: A comma-delimited list of columns in target-table in which to store the exported data.See Mapping Between Source and Target Columns, below.
query-expression: The data to export.
[[namespace.]schema.]source-table: The table in the source database that contains the data to export. The namespace option only applies to Eon Mode databases and defaults to default_namespace.
source-columns: A comma-delimited list of the columns in the source table to export. The table cannot have columns of complex data types.See Mapping Between Source and Target Columns, below.

Privileges

Non-superusers:

Source table: SELECT
Source table schema: USAGE
Target table: INSERT
Target table schema: USAGE

Mapping between source and target columns

If you export all table data from one database to another, EXPORT TO VERTICA can omit specifying column lists if column definitions in both tables comply with the following conditions:

Same number of columns
Identical column names
Same sequence of columns
Matching or compatible column data types
No complex data types (ARRAY, SET, or ROW), except for native arrays

If any of these conditions is not true, the EXPORT TO VERTICA statement must include column lists that explicitly map source and target columns to each other, as follows:

Contain the same number of columns.
List source and target columns in the same order.
Pair columns with the same (or compatible) data types.

Examples

See Exporting data to another database.

Sql-Reference: GET DIRECTED QUERY

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

Queries the DIRECTED_QUERIES system table on the specified input query, and returns details of all directed queries that map to the input query. For details about output, see Managing directed queries.

Syntax

GET DIRECTED QUERY input-query

Arguments

input-query: An input query that is associated with one or more directed queries.

Privileges

None

Examples

See Managing directed queries.

Sql-Reference: GRANT statements

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

GRANT statements grant privileges on database objects to users and roles.

Important

In a database with trust authentication, GRANT statements appear to work as expected but have no real effect on database security.

Sql-Reference: INSERT

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

Inserts values into all projections of the specified table. You must insert one complete tuple at a time. If no projections are associated with the target table, OpenText™ Analytics Database creates a superprojection to store the inserted values.

INSERT works for flex tables as well as regular native tables. If the table has real columns, inserted data of scalar types and native arrays of scalar types is added to both the real column and the __raw__ column. For data of complex types, the values are not added to the __raw__ column.

Syntax

INSERT [ /*+LABEL (label-string)*/ ] 
  INTO [[{ database | namespace }.]schema.]table-name 
  [ ( column-list ) ]
  { DEFAULT VALUES | VALUES ( values-list )[,...] | SELECT query-expression }

Arguments

LABEL: Assigns a label to a statement to identify it for profiling and debugging.

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

table-name

The target table. You cannot invoke INSERT on a projection.

column-list

A comma-delimited list of one or more target columns in this table, listed in any order. VALUES clause values are mapped to columns in the same order. If you omit this list, the database maps VALUES clause values to columns according to column order in the table definition.

A list of target columns is invalid with DEFAULT VALUES.

DEFAULT VALUES

Fills all columns with their default values as specified in the table definition. If no default value is specified for a column, the database inserts a NULL value.

You cannot specify a list of target columns with this option.

VALUES (values-list)

A comma-delimited list of one or more values to insert in the target columns, where each value is one of the following:

expression resolves to a value to insert in the target column. The expression must not nest other expressions, include database meta-functions, or use mixed complex types. Values may include native array or ROW types if the database can coerce the element or field types.
DEFAULT inserts the default value as specified in the table definition.

If no value is supplied for a column, the database implicitly adds a DEFAULT value, if defined. Otherwise the database inserts a NULL value. If the column is defined as NOT NULL, INSERT returns an error.

You can use INSERT to insert multiple rows in the target table, by specifying multiple comma-delimited VALUES lists:

INSERT INTO table-name
   VALUES ( values-list ), ( values-list )[,...]

For details, see Multi-Row INSERT below.

SELECT query-expression

A query that returns the rows to insert. Isolation level applies only to the SELECT clauses and works like any query. Restrictions on use of complex types apply as in other queries.

Privileges

Table owner or user with GRANT OPTION is grantor
INSERT privilege on table
USAGE privilege on schema that contains the table

Committing successive table changes

Multi-row INSERT

You can use INSERT to insert multiple rows in the target table, by specifying multiple comma-delimited VALUES lists. For example:

=> CREATE TABLE public.t1(a int, b int, c varchar(16));
CREATE TABLE
=> INSERT INTO t1 VALUES (1,2, 'un, deux'), (3,4, 'trois, quatre');
 OUTPUT
--------
      2
(1 row)

=> COMMIT;
COMMIT
=> SELECT * FROM t1;
 a | b |       c
---+---+---------------
 1 | 2 | un, deux
 3 | 4 | trois, quatre
(4 rows)

Restrictions

The database does not support subqueries as the target of an INSERT statement.
Restrictions on the use of complex types in SELECT statements apply equally to INSERT. Using complex values that cannot be coerced to the column type results in an error.
If primary key, unique key, or check constraints are enabled for automatic enforcement in the target table, the database enforces those constraints when you load new data. If a violation occurs, the database rolls back the operation and returns an error.
If an insert would violate a table or schema disk quota, the operation fails. For more information, see Disk quotas.

Examples

=> INSERT INTO t1 VALUES (101, 102, 103, 104);
=> INSERT INTO customer VALUES (10, 'male', 'DPR', 'MA', 35);
=> INSERT INTO start_time VALUES (12, 'film','05:10:00:01');
=> INSERT INTO retail.t1 (C0, C1) VALUES (1, 1001);
=> INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < '2004-05-07';

The database does not support subqueries or nested expressions as the target of an INSERT statement. For example, the following query returns an error message:

=> INSERT INTO t1 (col1, col2) VALUES ('abc', (SELECT mycolumn FROM mytable));
ERROR 4821:  Subqueries not allowed in target of insert

You can rewrite the above query as follows:

=> INSERT INTO t1 (col1, col2) (SELECT 'abc', mycolumn FROM mytable);
 OUTPUT
--------
      0
(1 row)

The following example shows how to use INSERT...VALUES with flex tables:

=> CREATE FLEX TABLE flex1();
 CREATE TABLE
=> INSERT INTO flex1(a,b) VALUES (1, 'x');
 OUTPUT
--------
      1
(1 row)

=> SELECT MapToString(__raw__) FROM flex1;
           MapToString
---------------------------------
{
"a" : "1",
"b" : "x"
}
(1 row)

The following example shows how to use INSERT...SELECT with flex tables:

=> CREATE FLEX TABLE flex2();
 CREATE TABLE
=> INSERT INTO flex2(a, b) SELECT a, b, '2016-08-10 11:10' c, 'Hello' d, 3.1415 e, f from flex1;
 OUTPUT
--------
      1
(1 row)

=> SELECT MapToString(__raw__) FROM flex2;
           MapToString
---------------------------------
{
"a" : "1",
"b" : "x",
"c" : "2016-08-10",
"d" : "Hello",
"e" : 3.1415,
"f" : null
}
(1 row)

The following examples use complex types:

=> CREATE TABLE inventory(storeID INT, product ROW(name VARCHAR, code VARCHAR));
CREATE TABLE

--- LookUpProducts() returns a row(varchar, int), which is cast to row(varchar, varchar):
=> INSERT INTO inventory(product) SELECT LookUpProducts();
 OUTPUT
--------
      5
(1 row)

--- Cannot use with select...values:
=> INSERT INTO inventory(product) VALUES(LookUpProducts());
ERROR 2631:  Column "product" is of type "row(varchar,varchar)" but expression is of type "row(varchar,int)"

--- Literal values are supported:
=> INSERT INTO inventory(product) VALUES(ROW('xbox',165));
 OUTPUT
--------
      1
(1 row)

=> SELECT product FROM inventory;
          product
------------------------------
 {"name":"xbox","code":"125"}
(1 row)

Sql-Reference: LOCK TABLE

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

Locks a table, giving the caller's session exclusive access to certain operations. Tables are automatically unlocked after the current transaction ends—that is, after COMMIT or ROLLBACK. LOCK TABLE can be useful for preventing deadlocks.

To view existing locks, see LOCKS.

Note

READ COMMITTED isolation (default) and SERIALIZABLE isolation automatically handle locks for you, and the vast majority of users can rely on them exclusively; LOCK TABLE is only for advanced users who need granular control over locks for more complex workloads.

To implement pessimistic concurrency without manually locking tables, you can use SELECT...FOR UPDATE to acquire an EXCLUSIVE (X) lock on the table.

Syntax

LOCK [ TABLE ] [[{database | namespace }.]schema.]table [,...]
    IN { lock_type } MODE
    [ NOWAIT ]

Arguments

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

table

The table to lock.

lock-type

The type of lock, one of the following:

SHARE
INSERT
INSERT VALIDATE
SHARE INSERT
EXCLUSIVE
NOT DELETE
USAGE
OWNER

Note

LOCK TABLE does not currently support D (drop partition) locks.

NOWAIT

If specified, LOCK TABLE returns and reports an error immediately if it cannot acquire the lock. Otherwise, LOCK TABLE waits for incompatible locks to be released by their respective sessions, returning an error if the lock is not released after a certain amount of time, as defined by LockTimeout.

Privileges

Required privileges depend on the type of lock requested:

Lock	Privileges
SHARED (S)	SELECT
INSERT (I)	INSERT
SHARE INSERT	SELECT, INSERT
INSERT VALIDATE (IV)	SELECT, INSERT
EXCLUSIVE (X)	UPDATE, DELETE
NOT DELETE (T)	SELECT
USAGE	All privileges
Owner	All privileges

Examples

See Lock examples.

Sql-Reference: MERGE

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

Performs update and insert operations on a target table based on the results of a join with another data set, such as a table or view. The join can match a source row with only one target row; otherwise, OpenText™ Analytics Database returns an error.

If a merge would violate a table or schema disk quota, the operation fails. For more information, see Disk quotas.

The target table cannot have columns of complex data types. The source table can, so long as those columns are not included in the merge operation.

Syntax

MERGE [ /*+LABEL (label-string)*/ ]
    INTO [[ { database | namespace }.]schema.]target-table [ [AS] alias ]
    USING source-dataset
    ON join-condition matching-clause[ matching-clause ]

Returns

Number of target table rows updated or inserted

Arguments

LABEL: Assigns a label to a statement to identify it for profiling and debugging.

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

target-table

The table on which to perform update and insert operations. MERGE takes an X (exclusive) lock on the target table during the operation. The table must not contain columns of complex types.

Important

The total number of target table columns cannot exceed 831.

source-dataset

The data to join to target-table, one of the following:

[[database.]schema.]table[ [AS]alias ]
[[database.]schema.]view[ [AS]alias ]
(subquery) sq-alias

The specified data set typically supplies the data used to update the target table and populate new rows. You can specify an external table.

ON join-condition

The conditions on which to join the target table and source data set.

Tip

The database query optimizer can create an optimized query plan for a MERGE statement only if the target table join column has a unique or primary key constraint. For details, see MERGE optimization.

matching-clause

One of the following clauses:

MERGE supports one instance of each clause, and must include at least one.

WHEN MATCHED THEN UPDATE

For each target-table row that is joined (matched) to source-dataset, specifies to update one or more columns:

WHEN MATCHED [ AND update-filter ] THEN UPDATE
  SET { column = expression }[,...]

update-filter optionally filters the set of matching rows. The update filter can specify any number of conditions. the database evaluates each matching row against this filter, and updates only the rows that evaluate to true. For details, see Update and insert filters.

Note

The database also supports Oracle syntax for specifying update filters:

WHEN MATCHED THEN UPDATE
SET { column = expression }[,...]
[ WHERE update-filter ]

The following requirements apply:

A MERGE statement can contain only one WHEN MATCHED clause.
target-column can only specify a column name in the target table. It cannot be qualified with a table name.

For details, see Merging table data.

WHEN NOT MATCHED THEN INSERT

For each source-dataset row that is not joined (not matched) to target-table, specifies to:

Insert a new row into target-table.
Populate each new row with the values specified in values-list.

WHEN NOT MATCHED [ AND insert-filter ] THEN INSERT
  [ ( column-list ) ] VALUES ( values-list )

column-list is a comma-delimited list of one or more target columns in the target table, listed in any order. MERGE maps column-list columns to values-list values in the same order, and each column-value pair must be compatible. If you omit column-list, the database maps values-list values to columns according to column order in the table definition.

insert-filter optionally filters the set of non-matching rows. The insert filter can specify any number of conditions. The database evaluates each non-matching source row against this filter. For each row that evaluates to true, the database inserts a new row in the target table. For details, see Update and insert filters.

Note

The database also supports Oracle syntax for specifying insert filters:

WHEN NOT MATCHED THEN INSERT
[ ( column-list ) ] VALUES ( values-list )
[ WHERE insert-filter ]

The following requirements apply:

A MERGE statement can contain only one WHEN NOT MATCHED clause.
*column-list* can only specify column names in the target table. It cannot be qualified with a table name.
Insert filter conditions can only reference the source data. If any condition references the target table, the database returns an error.

For details, see Merging table data.

Privileges

MERGE requires the following privileges:

SELECT permissions on the source data and INSERT, UPDATE, and DELETE permissions on the target table.
Automatic constraint enforcement requires SELECT permissions on the table containing the constraint.
SELECT permissions on the target table if the condition in the syntax reads data from the target table.

For example, the following GRANT statement grants user1 access to the t2 table. This allows user1 to run the MERGE statement that follows:

=> GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE t2 to user1;
GRANT PRIVILEGE

=>\c - user1
You are now connected as user "user1".

=> MERGE INTO t2 USING t1 ON t1.a = t2.a
WHEN MATCHED THEN UPDATE SET b = t1.b
WHEN NOT MATCHED THEN INSERT (a, b) VALUES (t1.a, t1.b);

Improving MERGE performance

You can improve MERGE performance in several ways:

Design projections for optimal MERGE performance.
Facilitate creation of optimized query plans.
Use a source data set that is smaller than the target table.

For details, see MERGE optimization.

Constraint enforcement

If primary key, unique key, or check constraints are enabled for automatic enforcement in the target table, the database enforces those constraints when you load new data. If a violation occurs, the database rolls back the operation and returns an error.

Caution

If you run MERGE multiple times using the same target and source table, each iteration is liable to introduce duplicate values into the target columns and return with an error.

Columns prohibited from merge

The following columns cannot be specified in a merge operation; attempts to do so return with an error:

IDENTITY columns, or columns whose default value is set to a named sequence.
Vmap columns such as __raw__ in flex tables.
Columns of complex types ARRAY, SET, or ROW.

Examples

See:

Sql-Reference: PROFILE

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

Profiles a single SQL statement.

Syntax

PROFILE { sql-statement }

Parameters

sql-statement: A query (SELECT) statement or DML statement--for example, you can profile INSERT, UPDATE, COPY, and MERGE.

Output

Writes profile summary to stderr, saves details to system catalog V_MONITOR.EXECUTION_ENGINE_PROFILES.

Privileges

The same privileges required to run the profiled statement

Description

PROFILE generates detailed information about how the target statement executes, and saves that information in the system catalog V_MONITOR.EXECUTION_ENGINE_PROFILES. Query output is preceded by a profile summary: profile identifiers transaction_id and statement_id, initiator memory for the query, and total memory required. For example:

=> PROFILE SELECT customer_name, annual_income FROM public.customer_dimension WHERE (customer_gender, annual_income) IN (SELECT customer_gender, MAX(annual_income) FROM public.customer_dimension GROUP BY customer_gender);
NOTICE 4788:  Statement is being profiled
HINT:  Select * from v_monitor.execution_engine_profiles where transaction_id=45035996274683334 and statement_id=7;
NOTICE 3557:  Initiator memory for query: [on pool general: 708421 KB, minimum: 554324 KB]
NOTICE 5077:  Total memory required by query: [708421 KB]
  customer_name   | annual_income
------------------+---------------
 Emily G. Vogel   |        999998
 James M. McNulty |        999979
(2 rows)

Use profile identifiers to query the table for profile information on a given query.

Sql-Reference: RELEASE SAVEPOINT

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

Destroys a savepoint without undoing the effects of commands executed after the savepoint was established.

Syntax

RELEASE [ SAVEPOINT ] savepoint_name

Parameters

savepoint_name: Specifies the name of the savepoint to destroy.

Privileges

None

Notes

Once destroyed, the savepoint is unavailable as a rollback point.

Examples

The following example establishes and then destroys a savepoint called my_savepoint. The values 101 and 102 are both inserted at commit.

=> INSERT INTO product_key VALUES (101);
=> SAVEPOINT my_savepoint;
=> INSERT INTO product_key VALUES (102);
=> RELEASE SAVEPOINT my_savepoint;
=> COMMIT;

Sql-Reference: REMOVE RESTORE POINT FROM ARCHIVE

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

Eon Mode only

Removes a in-database restore point from an archive.

To remove a specific restore point, you must specify either its index in the archive or its unique object ID. You can find both of these identifiers by querying the ARCHIVE_RESTORE_POINTS system table. If neither of these identifiers are provided, the oldest restore point in the archive is removed.

Syntax

REMOVE RESTORE POINT FROM ARCHIVE archive-name { INDEX restore-point-index | ID restore-point-id }

Arguments

archive-name: Name of the archive from which to remove the restore point.
restore-point-index: Index of the restore point to remove, where index 1 specifies the most recently saved restore point.
restore-point-id: Unique object ID of the restore point to remove.

Privileges

Superuser or archive owner

Examples

To view all restore points, including unique object IDs and indexes, query the ARCHIVE_RESTORE_POINTS system table:

=> SELECT * FROM ARCHIVE_RESTORE_POINTS;
                  id                  |         save_time          | index |  archive  |  state 
--------------------------------------+----------------------------+-------+-----------+----------
 2616f6cd-e98c-472c-8d5c-a7f459dff82b | 2021-12-10 10:19:58.565311 |     1 | verticadb | COMPLETE
 116066cc-29cb-4ce5-9a27-170538ba95cf | 2021-12-06 11:02:48.059941 |     2 | verticadb | COMPLETE
(2 rows)

The following statement removes the most recently saved restore point in the verticadb archive:

=> REMOVE RESTORE POINT FROM ARCHIVE verticadb index 1;
REMOVE RESTORE POINT

If you again query the ARCHIVE_RESTORE_POINTS table, the restore point will either appear with a status of REMOVING or, if the removal process has completed, is not listed:

=> SELECT * FROM ARCHIVE_RESTORE_POINTS;
                  id                  |         save_time          | index |  archive  |  state 
--------------------------------------+----------------------------+-------+-----------+----------
 2616f6cd-e98c-472c-8d5c-a7f459dff82b | 2021-12-10 10:19:58.565311 |       | verticadb | REMOVING
 116066cc-29cb-4ce5-9a27-170538ba95cf | 2021-12-06 11:02:48.059941 |     1 | verticadb | COMPLETE
(2 rows)

Sql-Reference: REPLICATE

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

Eon Mode only

Copies table or schema data directly from one Eon Mode database's communal storage to another. REPLICATE copies all table data and metadata. Each REPLICATE call can only replicate tables and schemas to a single namespace in the target database. When called multiple times, this statement only copies data that has changed in the source database since the last call. The tables do not have to exist in the target database before replication. If the table does exist in the target, it is overwritten.

Caution

Replication overwrites any data in the target table. You do not receive any notification that the data in the target database will be overwritten, even if the target table's design does not match the source table. Verify that the tables you want to replicate either do not exist in the target database or do not contain data that you need. Be especially cautious when replicating entire schemas to prevent overwriting data in the target database.

Similarly, changes to a replicated table in the target database are overwritten each time you replicate the table. When performing scheduled replications, only grant read access to replicated tables in the target database. Limiting these tables to read-only access will help prevent confusion if a user makes changes to a replicated table.

Syntax

REPLICATE { table | schema | "[.namespace.]schema.table" 
          |  INCLUDE "inc_pattern" [ EXCLUDE "ex_pattern" ] }
          { FROM | TO } database_name
          [ TARGET_NAMESPACE namespace-name ]

Arguments

table | schema | "[.namespace.]schema.table"

The name of a single table or schema to replicate. If specified, the namespace name must be front-qualified with a period. For example, to specify table t in schema s in namespace n, you would write ".n.s.t". If you do not specify a namespace, the object is assumed to be in the default_namespace.

inc_pattern

A string containing a wildcard pattern of the schemas and/or tables to include in the replication. Namespace names must be front-qualified with a period.

ex_pattern

A string containing a wildcard pattern of the schemas and/or tables to exclude from the set of tables matched by the include pattern. Namespace names must be front-qualified with a period.

Note

When using wildcard patterns, be sure to anchor the patterns with a period to indicate the separation between the schema and the table name and between the namespace and schema. For example, suppose you wanted to replicate all tables in the public schema in the n1 namespace that started with the letter t, except the table public.t3. This pattern statement does not work because the exclude wildcard only applies to schemas:

=>  REPLICATE INCLUDE ".n1.public.t*" EXCLUDE "*3" FROM verticadb;

The following statement does work because the periods in the EXCLUDE wildcard force the wildcard to apply to the table:

=>  REPLICATE INCLUDE ".n1.public.t*" EXCLUDE ".n1.*.*3" FROM verticadb;

database_name

The name of the database from or to which data is replicated. The replication steps depend on whether the call is initiated from the source or target database:

Target-inititated replication: use the CONNECT TO VERTICA statement to create a connection to the source database, and specify the source database in the REPLICATE statement using a FROM source_db clause.
Source-inititated replication: use the CONNECT TO VERTICA statement to connect to the target database, and specify the target database in the REPLICATE statement using a TO target_db clause.

Both of these methods copy the shard data directly from the source communal storage location to the target communal storage location.

TARGET_NAMESPACE namespace-name

Namespace in the target cluster to which objects are replicated. The target namespace must have the same shard count as the source namespace in the source cluster.

If you do not specify a target namespace, objects are replicated to a namespace with the same name as the source namespace. If no such namespace exists in the target cluster, it is created with the same name and shard count as the source namespace. You can only replicate tables in the public schema to the default_namespace in the target cluster.

Privileges

Superuser

Examples

Connect to the source database from the target database and then replicate the source database's customers table to the target database:

=> CONNECT TO VERTICA source_db USER dbadmin 
           PASSWORD 'mypassword' ON 'vertica_node01', 5433;
 CONNECT

=> REPLICATE customers FROM source_db;
REPLICATE

The following example performs the same data replication as the previous example, but the following replication is initiated from the source database instead of the target database:

=> CONNECT TO VERTICA target_db USER dbadmin 
           PASSWORD 'mypassword' ON 'vertica_node01', 5433;
 CONNECT

=> REPLICATE customers TO target_db;
REPLICATE

Replicate all tables in the public schema that start with the letter t:

=> REPLICATE INCLUDE "public.t*" FROM source_db;

Replicate all tables in the public schema except those that start with the string customer_:

=> REPLICATE INCLUDE "public.*" EXCLUDE '*.customer_*' FROM source_db;

Replicate the flights table in the airline schema of the airport namespace to the airport2 namespace in the target cluster:

=> REPLICATE ".airport.airline.flights" FROM source_db TARGET_NAMESPACE airport2;

Replicate all schemas and tables in the default_namespace of the source database to the default_namespace in the target database:

=> REPLICATE INCLUDE ".default_namespace.*.*" FROM source_db;

Sql-Reference: REVOKE statements

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

REVOKE statements let you revoke privileges on database objects from users and roles.

Important

In a database with trust authentication, REVOKE statements appear to work as expected but have no real effect on database security.

Sql-Reference: ROLLBACK

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

Ends the current transaction and discards all changes that occurred during the transaction.

Syntax

ROLLBACK [ WORK | TRANSACTION ]

Parameters

WORK | TRANSACTION: Have no effect; they are optional keywords for readability.

Privileges

None

Notes

When an operation is rolled back, any locks that are acquired by the operation are also rolled back.

ABORT is a synonym for ROLLBACK.

Examples

This example shows how to roll back from a DELETE transaction.

=> SELECT * FROM sample_table;
a
---
1
(1 row)

=> DELETE FROM sample_table WHERE a = 1;

=> SELECT * FROM sample_table;
a
---
(0 rows)
=> ROLLBACK;
=> SELECT * FROM sample_table;
a
---
1
(1 row)

This example shows how to roll back the changes you made since the BEGIN statement.

=> BEGIN TRANSACTION ISOLATION LEVEL READ COMMITTED READ ONLY;
BEGIN
=> ROLLBACK TRANSACTION;
ROLLBACK

Sql-Reference: ROLLBACK TO SAVEPOINT

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

Rolls back all commands that have been entered within the transaction since the given savepoint was established.

Syntax

ROLLBACK TO [SAVEPOINT] savepoint_name

Parameters

savepoint_name: Specifies the name of the savepoint to roll back to.

Privileges

None

Notes

The savepoint remains valid and can be rolled back to again later if needed.
When an operation is rolled back, any locks that are acquired by the operation are also rolled back.
ROLLBACK TO SAVEPOINT implicitly destroys all savepoints that were established after the named savepoint.

Examples

The following example rolls back the values 102 and 103 that were entered after the savepoint, my_savepoint, was established. Only the values 101 and 104 are inserted at commit.

=> INSERT INTO product_key VALUES (101);
=> SAVEPOINT my_savepoint;
=> INSERT INTO product_key VALUES (102);
=> INSERT INTO product_key VALUES (103);
=> ROLLBACK TO SAVEPOINT my_savepoint;
=> INSERT INTO product_key VALUES (104);
=> COMMIT;

Sql-Reference: SAVE QUERY

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

Saves an input query to associate with a custom directed query.

Syntax

SAVE QUERY input-query

Arguments

input-query: The input query to associate with a custom directed query. The input query supports only one optimizer hint, :v.

Privileges

Superuser

Usage

SAVE QUERY saves the specified input query for use by the next invocation of CREATE DIRECTED QUERY CUSTOM. CREATE DIRECTED QUERY CUSTOM pairs the saved query with its annotated query argument to create a directed query. Both statements must be issued in the same user session.

The saved query remains available until the one of the following events occurs:

The next invocation of CREATE DIRECTED QUERY, whether invoked with CUSTOM or OPTIMIZER.
Another invocation of SAVE QUERY.
The session ends.

Caution

OpenText™ Analytics Database associates a saved query with a directed query without checking whether the input and annotated queries are compatible. Be careful to sequence SAVE QUERY and CREATE DIRECTED QUERY CUSTOM so the saved and directed queries are correctly matched.

Examples

See Custom directed queries.

Sql-Reference: SAVE RESTORE POINT TO ARCHIVE

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

Eon Mode only

Saves an in-database restore point to an archive. After the restore point is saved, you can revive the database to the state at which the restore point was saved. For details on reviving your database from a restore point, see Revive from a restore point.

Syntax

SAVE RESTORE POINT TO ARCHIVE archive-name

Arguments

archive-name: Name of the archive to which the restore point is saved.

Privileges

Superuser or archive owner

Examples

The following statement saves a restore point to the verticadb archive:

=> SAVE RESTORE POINT TO ARCHIVE verticadb;
SAVE RESTORE POINT

To view all restore points in the database, query the ARCHIVE_RESTORE_POINTS system table:

=> SELECT * FROM ARCHIVE_RESTORE_POINTS;

                  id                  |         save_time          | index |  archive  |  state 
--------------------------------------+----------------------------+-------+-----------+----------
 2616f6cd-e98c-472c-8d5c-a7f459dff82b | 2021-12-10 10:19:58.565311 |     1 | verticadb | COMPLETE
 116066cc-29cb-4ce5-9a27-170538ba95cf | 2021-12-06 11:02:48.059941 |     2 | verticadb | COMPLETE
(2 rows)

Sql-Reference: SAVEPOINT

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

Creates a special mark, called a savepoint, inside a transaction. A savepoint allows all commands that are executed after it was established to be rolled back, restoring the transaction to the state it was in at the point in which the savepoint was established.

Tip

Savepoints are useful when creating nested transactions. For example, a savepoint could be created at the beginning of a subroutine. That way, the result of the subroutine could be rolled back if necessary.

Syntax

SAVEPOINT savepoint_name

Parameters

savepoint_name: Specifies the name of the savepoint to create.

Privileges

None

Notes

Savepoints are local to a transaction and can only be established when inside a transaction block.
Multiple savepoints can be defined within a transaction.
If a savepoint with the same name already exists, it is replaced with the new savepoint.

Examples

The following example illustrates how a savepoint determines which values within a transaction can be rolled back. The values 102 and 103 that were entered after the savepoint, my_savepoint, was established are rolled back. Only the values 101 and 104 are inserted at commit.

=> INSERT INTO T1 (product_key) VALUES (101);
=> SAVEPOINT my_savepoint;
=> INSERT INTO T1 (product_key) VALUES (102);
=> INSERT INTO T1 (product_key) VALUES (103);
=> ROLLBACK TO SAVEPOINT my_savepoint;
=> INSERT INTO T1 (product_key) VALUES (104);
=> COMMIT;
=> SELECT product_key FROM T1;
.
.
.
101
104
(2 rows)

Sql-Reference: SELECT

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

Returns a result set from one or more data sources—tables, views, joined tables, and named subqueries.

Syntax

[ AT epoch ] [ WITH-clause ] SELECT [ ALL | DISTINCT ]
    { * | { MATCH_COLUMNS('pattern') | expression [ [AS] alias ] }[,...] }
    [ into-table-clause ]
    [ from-clause ]
    [ where-clause ]
    [ time-series-clause ]
    [ group-by-clause[,...] ]
    [ having-clause[,...] ]
    [ match-clause ]
    [ union-clause ]
    [ intersect-clause ]
    [ except-clause ]
    [ order-by-clause [ offset-clause ]]
    [ limit-clause ]
    [ FOR UPDATE [ OF table-name[,...] ] ]

Note

SELECT statements can also embed various directives, or hints, that let you control how a given query is handled—for example, join hints such as JTYPE, which enforces the join type (merge or hash join).

For details on using OpenText™ Analytics Database hints, see Hints.

Parameters

AT epoch

Returns data from the specified epoch, where epoch is one of the following:

EPOCH LATEST: Return data up to but not including the current epoch. The result set includes data from the latest committed DML transaction.
EPOCH integer: Return data up to and including the specified epoch.
TIME 'timestamp': Return data from the epoch at the specified timestamp.

These options are ignored if used to query temporary or external tables.

See Epochs for additional information about how OpenText™ Analytics Database uses epochs.

For details, see Historical queries.

ALL | DISTINCT

ALL (default): Retains duplicate rows in result set or group.
DISTINCT: Removes duplicate rows from the result set or group.

The ALL or DISTINCT qualifier must immediately follow the SELECT keyword. Only one instance of this keyword can appear in the select list.

*

Lists all columns in the queried tables.

Caution

Selecting all columns from the queried tables can produce a very large wide set, which can adversely affect performance.

MATCH_COLUMNS('pattern')

Returns all columns in the queried tables that match pattern.

expression [[AS] alias]

An expression that typically resolves to column data from the queried tables—for example, names of columns that are specified in the FROM clause; also:

Literals (constants)
Aggregate expressions
CASE expressions
SQL functions
Subqueries in the SELECT list

You can optionally assign a temporary alias to each column expression and reference that alias elsewhere in the SELECT statement—for example, in the query predicate or ORDER BY clause. The database uses the alias as the column heading in query output.

FOR UPDATE

Specifies to obtain an X lock on all tables specified in the query, most often used from READ COMMITTED isolation.

FOR UPDATE requires update/delete permissions on the queried tables and cannot be issued from a read-only transaction.

Privileges

Non-superusers:

USAGE on the schema
SELECT on the table or view

Note

As view owner, you can grant other users SELECT privilege on the view only if one of the following is true:

You own the view's base table.
You have SELECT...WITH GRANT OPTION privilege on the view's base table.

Examples

When multiple clients run transactions as in the following example query, deadlocks can occur if FOR UPDATE is not used. Two transactions acquire an S lock, and when both attempt to upgrade to an X lock, they encounter deadlocks:

=> SELECT balance FROM accounts WHERE account_id=3476 FOR UPDATE;
    ...
=> UPDATE accounts SET balance = balance+10 WHERE account_id=3476;
=> COMMIT;

Sql-Reference: SET statements

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

SET statements let you change how the database operates, such as changing the autocommit settings or the resource pool your session uses.

Sql-Reference: SHOW

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

Shows run-time parameters for the current session.

Syntax

SHOW { parameter | ALL }

Parameters

ALL

Shows all run-time settings.

AUTOCOMMIT

Returns on/off to indicate whether statements automatically commit their transactions when they complete.

AVAILABLE ROLES

Lists all roles available to the user.

AVAILABLE WORKLOADS

Returns the workloads available to the user and their enabled roles.

DATESTYLE

Shows the current style of date values. See SET DATESTYLE.

ENABLED ROLES

Shows the roles enabled for the current session. See SET ROLE.

ESCAPE_STRING_WARNING

Returns on/off to indicate whether warnings are issued when backslash escapes are found in strings. See SET ESCAPE_STRING_WARNING.

GRACEPERIOD

Shows the session GRACEPERIOD set by SET SESSION GRACEPERIOD.

IDLESESSIONTIMEOUT

Shows how long the session can remain idle before it times out.

INTERVALSTYLE

Shows whether units are output when printing intervals. See SET INTERVALSTYLE.

LOCALE

Shows the current locale. See SET LOCALE.

MEMORYCAP

Shows the maximum amount of memory that any request use. See SET MEMORYCAP.

MULTIPLEACTIVERESULTSETS

Returns on/off to indicate whether multiple active result sets on one connection are allowed. See SET SESSION MULTIPLEACTIVERESULTSETS.

RESOURCE POOL

Shows the resource pool that the session is using. See SET RESOURCE POOL.

RUNTIMECAP

Shows the maximum amount of time that queries can run in the session. See SET RUNTIMECAP.

SEARCH_PATH

Shows the order in which OpenText™ Analytics Database searches schemas. See SET SEARCH_PATH. For example:

=> SHOW SEARCH_PATH;
    name     |                      setting
-------------+---------------------------------------------------
 search_path | "$user", public, v_catalog, v_monitor, v_internal
(1 row)

STANDARD_CONFORMING_STRINGS

Shows whether backslash escapes are enabled for the session. See SET STANDARD_CONFORMING_STRINGS.

TEMPSPACECAP

Shows the maximum amount of temporary file space that queries can use in the session. See SET TEMPSPACECAP.

TIMEZONE

Shows the timezone set in the current session. See SET TIMEZONE.

TRANSACTION_ISOLATION

Shows the current transaction isolation setting, as described in SET SESSION CHARACTERISTICS AS TRANSACTION. For example:

=> SHOW TRANSACTION_ISOLATION;
         name          |    setting
-----------------------+----------------
 transaction_isolation | READ COMMITTED
(1 row)

TRANSACTION_READ_ONLY

Returns true/false to indicate the current read-only setting, as described in SET SESSION CHARACTERISTICS AS TRANSACTION. For example:

=> SHOW TRANSACTION_READ_ONLY;
         name          | setting
-----------------------+---------
 transaction_read_only | false
(1 row)

WORKLOAD

Shows the workloads associated with the current session.

Privileges

None

Examples

Display all current runtime parameter settings:

=> SHOW ALL;
            name             |                          setting
-----------------------------+-----------------------------------------------------------
 locale                      | en_US@collation=binary (LEN_KBINARY)
 autocommit                  | off
 standard_conforming_strings | on
 escape_string_warning       | on
 multipleactiveresultsets    | off
 datestyle                   | ISO, MDY
 intervalstyle               | plain
 timezone                    | America/New_York
 search_path                 | "$user", public, v_catalog, v_monitor, v_internal, v_func
 transaction_isolation       | READ COMMITTED
 transaction_read_only       | false
 resource_pool               | general
 memorycap                   | UNLIMITED
 tempspacecap                | UNLIMITED
 runtimecap                  | UNLIMITED
 idlesessiontimeout          | UNLIMITED
 graceperiod                 | UNLIMITED
 enabled roles               | dbduser*, dbadmin*, pseudosuperuser*
 available roles             | dbduser*, dbadmin*, pseudosuperuser*
 tcp_keepalive               | idle_time: [7200], probe_interval: [75], probe_count: [9]
 workload                    | analytics
(21 rows)

Sql-Reference: SHOW CURRENT

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

Displays active configuration parameter values that are set at all levels. OpenText™ Analytics Database first checks values set at the session level. If a value is not set for a configuration parameter at the session level, the database next checks if the value is set for the node where you are logged in, and then checks the database level. If no values are set, SHOW CURRENT shows the default value for the configuration parameter. If the configuration parameter requires a restart to take effect, the active values shown might differ from the set values.

Syntax

SHOW CURRENT { parameter-name[,...] | ALL }

Parameters

parameter-name: Names of configuration parameters to show.
ALL: Shows all configuration parameters set at all levels.

Privileges

Non-superuser: SHOW CURRENT ALL returns masked parameter settings. Attempts to view specific parameter settings return an error.

Examples

Show configuration parameters and their settings at all levels.

=> SHOW CURRENT ALL;
level    |    name                   |setting
---------+---------------------------+---------
DEFAULT  | ActivePartitionCount      | 1
DEFAULT  | AdvanceAHMInterval        | 180
DEFAULT  | AHMBackupManagement       | 0
DATABASE | AnalyzeRowCountInterval   | 3600
SESSION  | ForceUDxFencedMode        | 1
NODE     | MaxClientSessions         | 0
...

Sql-Reference: SHOW DATABASE

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

Displays configuration parameter values that are set for the database.

Important

You can also get detailed information on configuration parameters, including their current and default values, by querying system table CONFIGURATION_PARAMETERS.

Note

If the configuration parameter is set but requires a database restart to take effect, the value shown might differ from the active value.

Syntax

SHOW DATABASE db-spec { parameter-name[,...] | ALL }

Parameters

db-spec

Specifies the current database, set to the database name or DEFAULT.

parameter-name

Names of one or more configuration parameters to show.Non-superusers can only specify parameters whose settings are not masked by SHOW DATABASE...ALL, otherwise OpenText™ Analytics Database returns an error.

If you specify a single parameter that is not set, SHOW DATABASE returns an empty row for that parameter.

To obtain the names of database-level parameters, query system table CONFIGURATION_PARAMETERS.

ALL

Shows all configuration parameters set at the database level. For non-superusers, the database masks settings of security parameters, which only superusers can access.

Privileges

Superuser: Shows all database parameter settings.
Non-superuser: Masks all security parameter settings, which only superusers can access. To determine which parameters require superuser privileges, query system table CONFIGURATION_PARAMETERS.

Examples

Show to a non-superuser all configuration parameters that are set on the database:

=> SHOW DATABASE DEFAULT ALL;
              name              | setting
--------------------------------+----------
 AllowNumericOverflow           | 1
 CopyFaultTolerantExpressions   | 1
 GlobalHeirUsername             | ********
 MaxClientSessions              | 50
 NumericSumExtraPrecisionDigits | 0
(6 rows)

Show settings for two configuration parameters:

=> SHOW DATABASE DEFAULT AllowNumericOverflow, NumericSumExtraPrecisionDigits;
              name              | setting
--------------------------------+---------
 AllowNumericOverflow           | 1
 NumericSumExtraPrecisionDigits | 0
(2 rows)

Sql-Reference: SHOW NODE

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

Displays configuration parameter values that are set for a node. If you specify a parameter that is not set, SHOW NODE returns an empty row for that parameter.

Note

If the configuration parameter is set but requires a database restart to take effect, the value shown might differ from the active value.

Syntax

SHOW NODE node-name { parameter-name [,...] | ALL }

Parameters

node-name: Name of the target node.
parameter-name: Names of one or more node-level configuration parameters. To obtain the names of node-level parameters, query system table CONFIGURATION_PARAMETERS.
ALL: Shows all configuration parameters set at the node level.

Privileges

None

Examples

View all configuration parameters and their settings for node v_vmart_node0001:

=> SHOW NODE v_vmart_node0001 ALL;
           name            | setting
---------------------------+---------
 DefaultIdleSessionTimeout | 5 hour
 MaxClientSessions         | 20

Sql-Reference: SHOW SESSION

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

Displays configuration parameter values that are set for the current session. If you specify a parameter that is not set, SHOW SESSION returns an empty row for that parameter.

Note

If the configuration parameter is set but requires a database restart to take effect, the value shown might differ from the active value.

Syntax

SHOW SESSION { ALL | UDPARAMETER ALL }

Parameters

ALL: Shows all OpenText™ Analytics Database configuration parameters set at the session level.
UDPARAMETER ALL: Shows all parameters defined by user-defined extensions. These parameters are not shown in the CONFIGURATION_PARAMETERS table.

Privileges

None

Examples

View all database configuration parameters and their settings for the current session. User-defined parameters are not included:

=> SHOW SESSION ALL;
name                        |                      setting
----------------------------+---------------------------------------------------
locale                      | en_US@collation=binary (LEN_KBINARY)
autocommit                  | off
standard_conforming_strings | on
escape_string_warning       | on
datestyle                   | ISO, MDY
intervalstyle               | plain
timezone                    | America/New_York
search_path                 | "$user", public, v_catalog, v_monitor, v_internal
transaction_isolation       | READ COMMITTED
transaction_read_only       | false
resource_pool               | general
memorycap                   | UNLIMITED
tempspacecap                | UNLIMITED
runtimecap                  | UNLIMITED
enabled roles               | dbduser*, dbadmin*, pseudosuperuser*
available roles             | dbduser*, dbadmin*, pseudosuperuser*
ForceUDxFencedMode          | 1
(17 rows)

Sql-Reference: SHOW USER

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

Displays configuration parameter settings for database users. To get the names of user-level parameters, query system table CONFIGURATION_PARAMETERS:

SELECT parameter_name, allowed_levels FROM configuration_parameters
      WHERE allowed_levels ilike '%USER%' AND parameter_name ilike '%depot%';
     parameter_name      |     allowed_levels
-------------------------+-------------------------
 UseDepotForWrites       | SESSION, USER, DATABASE
 DepotOperationsForQuery | SESSION, USER, DATABASE
 UseDepotForReads        | SESSION, USER, DATABASE
(3 rows)

Syntax

SHOW USER { user-name | ALL } [PARAMETER] { cfg-parameter [,...] | ALL }

Parameters

user-name | ALL: Show parameter settings for the specified user, or for all users.
[PARAMETER] parameter-list: A comma-delimited list of user-level configuration parameters.
PARAMETER ALL: Show all configuration parameters that are set for the specified users.

Privileges

Non-superusers: Can view only their own configuration parameter settings.

Examples

The following example shows configuration parameter settings for two users, Yvonne and Ahmed:

=> SELECT user_name FROM v_catalog.users WHERE user_name != 'dbadmin';
 user_name
-----------
 Ahmed
 Yvonne
(2 rows)

=> SHOW USER Yvonne PARAMETER ALL;
  user  |        parameter        | setting
--------+-------------------------+---------
 Yvonne | DepotOperationsForQuery | Fetches
(1 row)

=> ALTER USER Yvonne SET PARAMETER UseDepotForWrites = 0;
ALTER USER
=> SHOW USER Yvonne PARAMETER ALL;
  user  |        parameter        | setting
--------+-------------------------+---------
 Yvonne | DepotOperationsForQuery | Fetches
 Yvonne | UseDepotForWrites       | 0
(2 rows)

=> ALTER USER Ahmed SET PARAMETER DepotOperationsForQuery = 'Fetches';
ALTER USER
=> SHOW USER ALL PARAMETER ALL;
  user  |        parameter        | setting
--------+-------------------------+---------
 Ahmed  | DepotOperationsForQuery | Fetches
 Yvonne | DepotOperationsForQuery | Fetches
 Yvonne | UseDepotForWrites       | 0
(3 rows)

Sql-Reference: START TRANSACTION

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

Starts a transaction block.

Syntax

START TRANSACTION [ isolation_level ]

where isolation_level is one of:

ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }READ { ONLY | WRITE }

Parameters

Isolation level, described in the following table, determines what data the transaction can access when other transactions are running concurrently. The isolation level cannot be changed after the first query (SELECT) or DML statement (INSERT, DELETE, UPDATE) has run. A transaction retains its isolation level until it completes, even if the session's isolation level changes during the transaction. OpenText™ Analytics Database internal processes (such as the Tuple Mover and refresh operations) and DDL operations always run at the SERIALIZABLE isolation level to ensure consistency.

WORK | TRANSACTION

Have no effect; they are optional keywords for readability.

ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED }

SERIALIZABLE: Sets the strictest level of SQL transaction isolation. This level emulates transactions serially, rather than concurrently. It holds locks and blocks write operations until the transaction completes. Not recommended for normal query operations.
REPEATABLE READ: Automatically converted to SERIALIZABLE by OpenText™ Analytics Database.
READ COMMITTED (Default): Allows concurrent transactions. Use READ COMMITTED isolation for normal query operations, but be aware that there is a subtle difference between them. SeeTransactionsfor more information.
READ UNCOMMITTED: Automatically converted to READ COMMITTED by the database.

READ {WRITE | ONLY}

Determines whether the transaction is read/write or read-only. Read/write is the default.

Setting the transaction session mode to read-only disallows the following SQL commands, but does not prevent all disk write operations:

INSERT, UPDATE, DELETE, and COPY if the table they would write to is not a temporary table
All CREATE, ALTER, and DROP commands
GRANT, REVOKE, and EXPLAIN if the command it would run is among those listed.

Privileges

None

Notes

BEGIN performs the same function as START TRANSACTION.

Examples

This example shows how to start a transaction.

= > START TRANSACTION ISOLATION LEVEL READ COMMITTED READ WRITE;
START TRANSACTION
=> CREATE TABLE sample_table (a INT);
CREATE TABLE
=> INSERT INTO sample_table (a) VALUES (1);
OUTPUT
--------
1
(1 row)

Sql-Reference: TRUNCATE TABLE

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

Removes all storage associated with a table, while leaving the table definition intact. TRUNCATE TABLE auto-commits the current transaction after statement execution and cannot be rolled back.

TRUNCATE TABLE also performs the following actions:

Removes all table history preceding the current epoch. After TRUNCATE TABLE returns, AT EPOCH queries on the truncated table return nothing.
Drops all table- and partition-level statistics.

Syntax

TRUNCATE TABLE [[{database | namespace }.]schema.]table-name

Arguments

{ database | namespace }

Name of the database or namespace that contains table:

Database name: If specified, it must be the current database.
Namespace name (Eon Mode only): You must specify the namespace of objects in non-default namespaces. If no namespace is provided, it is assumed the object is in the default namespace.

schema

Name of the schema, by default public. If you specify the namespace or database name, you must provide the schema name, even if the schema is public.

If you specify a schema name that contains a period, the part before the period cannot be the same as the name of an existing namespace.

table-name: The name of the anchor table or temporary table to truncate. You cannot truncate an external table.

Privileges

Non-superuser:

Table owner
USAGE privileges on table schema

Examples

See Truncating tables.