Teradata QueryGrid: Teradata Database-to-Teradata Aster Data Integration User Guide

PDF

Dokument

Reklama

What would you do if you knew?™

Teradata QueryGrid

Teradata Database-to-Teradata Aster

User Guide

Release 15.00.00

B035-1187-015K

February 2016

The product or products described in this book are licensed products of Teradata Corporation or its affiliates.

Teradata, Active Data Warehousing, Active Enterprise Intelligence, Applications-Within, Aprimo Marketing Studio, Aster, BYNET, Claraview,

DecisionCast, Gridscale, MyCommerce, QueryGrid, SQL-MapReduce, Teradata Decision Experts, "Teradata Labs" logo, Teradata

ServiceConnect, Teradata Source Experts, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries.

Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.

AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.

Apache, Apache Avro, Apache Hadoop, Apache Hive, Hadoop, and the yellow elephant logo are either registered trademarks or trademarks of the

Apache Software Foundation in the United States and/or other countries.

Apple, Mac, and OS X all are registered trademarks of Apple Inc.

Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda

Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and

Maximum Support are servicemarks of Axeda Corporation.

Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.

GoldenGate is a trademark of Oracle.

Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.

Hortonworks, the Hortonworks logo and other Hortonworks trademarks are trademarks of Hortonworks Inc. in the United States and other countries.

Intel, Pentium, and XEON are registered trademarks of Intel Corporation.

IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.

Linux is a registered trademark of Linus Torvalds.

LSI is a registered trademark of LSI Corporation.

Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United

States and other countries.

NetVault is a trademark or registered trademark of Dell Inc. in the United States and/or other countries.

Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.

Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates.

QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.

Quantum and the Quantum logo are trademarks of Quantum Corporation, registered in the U.S.A. and other countries.

Red Hat is a trademark of Red Hat, Inc., registered in the U.S. and other countries. Used under license.

SAP is the trademark or registered trademark of SAP AG in Germany and in several other countries.

SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.

Simba, the Simba logo, SimbaEngine, SimbaEngine C/S, SimbaExpress and SimbaLib are registered trademarks of Simba Technologies Inc.

SPARC is a registered trademark of SPARC International, Inc.

Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries.

Unicode is a registered trademark of Unicode, Inc. in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.

The information contained in this document is provided on an "as-is" basis, without warranty of any kind, either express or implied, including the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you. In no event will Teradata Corporation be liable for any indirect, direct, special, incidental, or consequential damages, including lost profits or lost savings, even if expressly advised of the possibility of such damages.

The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country.

Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice.

To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please e-mail: [email protected]

Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata

Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata

Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback.

Copyright

Preface

Purpose

This book describes the Teradata

QueryGrid

™

: Teradata Database-to-Teradata Aster

Database SQL interface for transferring data between Teradata Database and remote

Teradata Aster Database hosts.

Use this book with the other books in the SQL book set.

Audience

This book is intended for database administrators and other technical personnel who use

Teradata Database.

Supported Releases

For Teradata QueryGrid supported releases information, see KAP314E23E .

Prerequisites

You should be familiar with basic relational database management theory and technology.

To become familiar with concepts specific to Teradata Database, read Introduction to

Teradata and SQL Fundamentals.

Changes to This Book

Release

Teradata Teradata

QueryGrid: Teradata

Aster Database-to-

Teradata Database

15.00.00

February 2016

Description

Initial publication.

Teradata Database-to-Teradata Aster 3

Preface

Additional Information

URL

www.info.teradata.com

www.teradata.com

www.teradata.com/TEN/ https://tays.teradata.com

Teradata Developer

Exchange

Description

Use the Teradata Information Products Publishing Library site to:

• View or download a manual:

• Under Online Publications, select General Search.

• Enter your search criteria and click Search.

• Download a documentation CD-ROM:

• Under Online Publications, select General Search.

• In the Title or Keyword field, enter CD-ROM, and click Search.

The Teradata home page provides links to numerous sources of information about Teradata. Links include:

• Executive reports, white papers, case studies of customer experiences with Teradata, and thought leadership

• Technical information, solutions, and expert advice

• Press releases, mentions and media resources

Teradata Customer Education delivers training that builds skills and capabilities for our customers, enabling them to maximize their

Teradata investment.

Use Teradata @ Your Service to access Orange Books, technical alerts, and knowledge repositories, view and join forums, and download software patches.

Teradata Developer Exchange provides articles on using Teradata products, technical discussion forums, and code downloads.

To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please email [email protected]

Product Safety Information

This document may contain information addressing product safety practices related to data or property damage, identified by the word Notice. A notice indicates a situation which, if not avoided, could result in damage to property, such as equipment or data, but not related to personal injury.

Example

Notice:

Improper use of the Reconfiguration utility can result in data loss.

Teradata Database-to-Teradata Aster

CHAPTER 1

Introduction to Teradata QueryGrid: Teradata

Database-to-Teradata Aster Database

Overview of the Teradata-to-Aster Connector

Teradata QueryGrid: Teradata Database-to-Teradata Aster Database (also referred to as the

Teradata-to-Aster connector) provides an SQL interface for transferring data between

Teradata Database and remote Teradata Aster Database hosts. It allows you to do the following:

• Create a remote server object that consists of a server name and the name/value pairs that Teradata Database needs to connect to the remote Teradata Aster Database server.

• Associate an import operator and an export operator with the foreign server.

• Execute a variety of remote Aster analytical functions from Teradata on remote Aster data or data exported from a local Teradata Database system.

• Import Teradata Aster Database data into a temporary or permanent Teradata Database table.

• Export data from temporary or permanent Teradata Database tables into existing

Teradata Aster Database tables.

• Reference tables on the remote Teradata Aster Database hosts in SELECT and INSERT statements.

• Limit the number of columns and rows that you import or export to control the amount of data and enhance performance.

Considerations

You may not use this feature without the appropriate license. The fact that this feature may be included in product media or downloads, or described in documentation that you receive does not authorize you to use it without the appropriate license. Contact your Teradata sales representative to purchase and enable this feature.

For Teradata QueryGrid supported releases information, see KAP314E23E .

The port on the Teradata system must be accessible. The default port for the Teradata-to-

Aster connector is 5001. If you run any other application that listens on port 5001, you must specify a different port number in the CREATE or ALTER FOREIGN SERVER statement.

All Teradata nodes must be connected on a network that is connected to all Queen and

Worker Bee nodes on the Teradata Aster system.

You must have a proxy user configured on the Teradata Aster Database.

Teradata Database-to-Teradata Aster 5

Chapter 1 Introduction to Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Overview of the Teradata-to-Aster Connector

Limitations

• ORDER BY clauses are not supported when you use SELECT with a FOREIGN TABLE.

To work around this limitation, you can order the results after they are returned to the local system.

• Not all of the Teradata Aster analytic functions are supported.

For a list of the Teradata Aster analytic functions that the Teradata-to-Aster connector supports, see

Supported Aster Functions .

• Transaction semantics are not supported between the Teradata system and the Teradata

Aster system.

For example, suppose that the following statements are executed in this order:

1. BEGIN Transaction ;

2. INSERT INTO t1@remote SELECT * FROM local

3. INSERT INTO local values (1,2)

4. END Transaction ;

If the second statement fails, then the data that is being inserted into table t1 is rolled back if it has not been committed by the local system. Once it is committed by the local system, a late arriving abort does not roll back the data.

If an error occurs on the third statement, the data in the remote system is not rolled back.

It is already committed from the remote system’s perspective.

6 Teradata Database-to-Teradata Aster

CHAPTER 2

Getting Started with Teradata QueryGrid:

Teradata Database-to-Teradata Aster Database

Setup Tasks Needed to Use the Teradata-to-Aster

Connector

To prepare to use the Teradata-to-Aster connector, you need to become familiar with the software. You then need to perform several tasks on the Teradata system and on the remote

Teradata Aster system.

Routines Used in the Teradata-to-Aster Connector

You should be familiar with the functions and procedures that the Teradata-to-Aster connector uses, as you need to grant privileges on them to users so that they can create foreign server objects or query a foreign server.

The Teradata-to-Aster connector provides the following routines:

Operator

LOAD_FROM_ASTER

LOAD_TO_ASTER

ASTEREXECUTE

ExecuteForeignSQL

EFSSPOP_TDSQLA

Description

A table operator that is used to import data from a remote

Teradata Aster Database.

A table operator that is used to export data to a remote Teradata

Aster Database.

A table operator that is used to export data from a Teradata

Database system to a Teradata Aster server, execute a remote function, and return the results.

For information about ASTEREXECUTE, see

AsterExecute .

A stored procedure that is used to execute basic SQL queries, such as CREATE, DROP, DELETE, and GRANT on a foreign server.

For information about ExecuteForeignSQL, see

ExecuteForeignSQL .

A table operator that is used when you create a foreign server object so that you can use the ExecuteForeignSQL syntax to run

SQL queries on the remote Teradata Aster server.

Teradata Database-to-Teradata Aster 7

Chapter 2 Getting Started with Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Setup Tasks Needed to Use the Teradata-to-Aster Connector

Operator

LOAD_FROM_REMOTE_TD

LOAD_TO_REMOTE_TD

Description

An internal routine that is installed on the Teradata Aster server to import the data that is exported from the Teradata Database system. You do not call the LOAD_FROM_REMOTE_TD operator directly.

An internal routine that is installed on the Teradata Aster server to export data back to the Teradata Database system. You do not call the LOAD_TO_REMOTE_TD operator directly.

Tasks To Be Performed On the Teradata System

• A Teradata DBA with the appropriate privileges needs to grant the following privileges to the DBAs and users who are going to create foreign server objects:

• CREATE SERVER and DROP SERVER privileges on TD_SERVER_DB

• EXECUTE FUNCTION and SELECT privileges on LOAD_FROM_ASTER or on the

SYSLIB database

• EXECUTE FUNCTION and SELECT privileges on LOAD_TO_ASTER or on the

SYSLIB database

• EXECUTE FUNCTION and SELECT privileges on EFSSPOP_TDSQLA

For an example of granting the privileges needed to create foreign servers, see Examples of

Granting the Necessary Privileges to Use the Teradata-to-Aster Connector .

• You should become familiar with the CREATE FOREIGN SERVER and CREATE

REPLACE AUTHORIZATION syntax before you try to create a foreign server.

For information about this syntax, see

CREATE FOREIGN SERVER

and

CREATE

AUTHORIZATION and REPLACE AUTHORIZATION .

• You can create an authorization object that stores the encrypted credentials for a user as a database object. If you use an authorization object, then the trusted user credentials do not need to be used when a DBA or a user creates a foreign server.

You can use the DEFINER keyword to make the authorization global for all users who need to query the foreign server.

For information about creating an authorization object, see Creating an Authorization

Object for the Server

and

CREATE AUTHORIZATION and REPLACE

AUTHORIZATION .

• Create one or more foreign server objects on the Teradata Database system.

• The creators of the foreign server objects need to grant SELECT and INSERT privileges on the foreign server objects to each Teradata user who needs to submit queries to each foreign server.

For an example of granting the privileges needed to run queries using foreign servers, see

Examples of Granting the Necessary Privileges to Use the Teradata-to-Aster Connector .

• A Teradata DBA with the appropriate privileges needs to grant the EXECUTE

PROCEDURE privilege on ExecuteForeignSQL to users who need to run

ExecuteForeignSQL.

For an example of granting the privileges, see

Examples of Granting the Necessary

Privileges to Use the Teradata-to-Aster Connector

• A Teradata DBA with the appropriate privileges needs to grant the EXECUTE

FUNCTION privilege and SELECT privilege on ASTEREXECUTE to users who need to run ASTEREXECUTE.

8 Teradata Database-to-Teradata Aster

Chapter 2 Getting Started with Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Setup Tasks Needed to Use the Teradata-to-Aster Connector

For an example of granting the privileges, see Examples of Granting the Necessary

Privileges to Use the Teradata-to-Aster Connector .

For additional information about granting privileges, see SQL Data Control Language,

B035-1149, and Security Administration, B035-1100.

It is considered a best practice to limit the grant of all privileges only to those DBAs and users who need the privileges to perform their designated tasks.

Tasks To Be Performed On the Teradata Aster System

A Teradata Aster DBA with the appropriate privileges must perform the following tasks:

• Create a trusted user who acts as a proxy on the Teradata Aster system. The trusted user must be a permanent user who has already been defined in the Teradata Aster database.

• For each Teradata end user who needs to query the foreign Aster servers, the DBA needs to use CREATE USER to define an identical user on the Teradata Aster system.

• Set up trusted sessions for every Teradata user who queries foreign server objects, by using GRANT teradata_username TO aster_trusted_username.

• Grant EXECUTE FUNCTION privilege to each Teradata end user (or to public) on the following functions:

• LOAD_TO_REMOTE_TD

• LOAD_FROM_REMOTE_TD

For information about performing tasks on a Teradata Aster system, see your Teradata Aster documentation.

Examples of Granting the Necessary Privileges to Use the Teradata-to-

Aster Connector

Granting the Privileges Needed to Create Foreign Servers

The following example shows how to grant a DBA or user named anne_m the privilege to create foreign servers and to associate an import operator and an export operator with them.

GRANT CREATE SERVER, DROP SERVER

ON TD_SERVER_DB

TO anne_m ;

GRANT EXECUTE FUNCTION, SELECT

ON SYSLIB.LOAD_FROM_ASTER

TO anne_m ;

GRANT EXECUTE FUNCTION, SELECT

ON SYSLIB.LOAD_TO_ASTER

TO anne_m;

Granting the Privileges Needed to Associate SYSLIB.EFSSPOP_TDSQLA

With a Foreign Server

The following example shows how to grant a DBA the privileges needed to create a foreign server on which DBAs or users can run ExecuteForeignSQL. The foreign server creator must have privileges on SYSLIB.EfsspOp and must associate this operator with a foreign server to make it possible to run ExecuteForeignSQL on a foreign server. ExecuteForeignSQL allows

Teradata Database-to-Teradata Aster 9

Chapter 2 Getting Started with Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Setup Tasks Needed to Use the Teradata-to-Aster Connector you to run basic SQL queries, such as CREATE, DROP, DELETE, and GRANT on the remote

Teradata Aster server.

GRANT EXECUTE FUNCTION, SELECT

ON SYSLIB.EFSSPOP_TDSQLA

TO anne_m;

Granting the Privileges Needed to Query Foreign Servers

The following example shows how the creator of a foreign server would grant a user named kris_w the privileges needed to submit queries to a foreign server named aster_server_02.

GRANT SELECT, INSERT

ON aster_server_02

TO kris_w;

Granting the Privileges Needed to Run ASTEREXECUTE

The following example shows how you would grant a user named kris_w the privileges needed to use ASTEREXECUTE syntax to export data to a Teradata Aster server and execute a remote function on it.

GRANT EXECUTE FUNCTION, SELECT

ON SYSLIB.ASTEREXECUTE

TO kris_w;

Granting the Privileges Needed to Run ExecuteForeignSQL

The following example shows how you would grant a user named kris_w the privileges needed to use the ExecuteForeignSQL syntax to run basic SQL queries, such as CREATE,

DROP, DELETE, and GRANT on the remote Teradata Aster server.

GRANT EXECUTE PROCEDURE

ON SYSLIB.ExecuteForeignSQL

TO kris_w;

Privileges Usage Notes

• You can specify the CREATE SERVER privilege only on the database TD_SERVER_DB.

• You can specify the DROP SERVER privilege only on the database TD_SERVER_DB.

• Only SELECT, INSERT, and SHOW privileges are allowed on foreign server objects. You must grant SELECT, INSERT, and SHOW privileges on foreign server objects to users who need to query foreign server objects.

• The creator of a foreign server object automatically receives DROP SERVER, SELECT, and SHOW privileges WITH GRANT OPTION on the foreign server object.

• The creator of a foreign server object automatically receives INSERT privilege WITH

GRANT OPTION on the foreign server object if an EXPORT operator is associated with the foreign server object.

• You cannot grant INSERT privilege on a foreign server object if the foreign server object does not have an export operator associated with it.

• When you GRANT ALL privileges on the TD_SERVER_DB database, CREATE SERVER and DROP SERVER privileges are included in the privileges granted.

10 Teradata Database-to-Teradata Aster

Chapter 2 Getting Started with Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Teradata System Security

GRANT ALL ON and REVOKE ALL ON a foreign server object have different meanings, depending on the table operators that are associated with the specified foreign server:

• Granting or revoking the ALL privilege also grants or revokes SHOW, DROP, and

SELECT privilege on a foreign server.

• The ALL privilege on the TD_SERVER_DB database includes the INSERT privilege for foreign servers that reference export operators.

For information about the syntax of GRANT (SQL Form) and REVOKE (SQL Form), see

SQL Data Control Language, B035-1149.

Creating an Authorization Object for the Server

Optionally, you can create an authorization object for the server that stores the encrypted credentials. You must be a database administrator to create an authorization object.

This object stores the proxy credentials for the remote logon and is typically defined as a single global value. To make it global for all users who are granted INSERT or SELECT privileges on the server object, you should create the object in the TD_SERVER_DB database and use the DEFINER attribute when you create it.

For additional information about creating authorization objects, see Security Administration,

B035-1100.

For example, you could type the following SQL:

CREATE AUTHORIZATION td_server_db.server_name_proxy AS DEFINER

TRUSTED USER 'proxyuser' PASSWORD 'myproxy_pswrd';

The proxy is then authorized and stored in the TD_SERVER_DB database.

Teradata System Security

The Teradata-to-Aster connector does not support encryption over the wire.

The port that you use when you create a foreign server (the listening port) is protected by a unique security key that is generated for each query by the local contract and passed as a

USING clause to the remote system. The remote system uses this key as part of its connection information to protect against unauthorized attempts to listen on the listening port.

One method to control system security is to limit CREATE FOREIGN SERVER privileges to the DBA. The DBA can then grant SELECT and INSERT privileges for the foreign server object to users to access the remote database. The user's SQL statement runs as the user name of the session and that user name is used for security in the remote database. You can maintain system security if you use one-to-one mapping for users on both systems.

Note that if you grant a user access to TD_SERVER_DB, the database that stores server objects, you have also granted that user the ability to create server objects.

Teradata Database-to-Teradata Aster 11

Chapter 2 Getting Started with Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

Teradata System Security

12 Teradata Database-to-Teradata Aster

CHAPTER 3

Syntax for Teradata QueryGrid: Teradata

Database-to-Teradata Aster Database

Introduction

This chapter describes the SQL syntax and options for using the Teradata QueryGrid connector. It includes examples that demonstrate the proper statement usage and connectorspecific grammar.

ALTER FOREIGN SERVER

Purpose

Modifies the parameters of an existing server object.

Syntax

Teradata Database-to-Teradata Aster 13

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER

Syntax Elements

server_name

The name given to the foreign server object.

EXTERNAL SECURITY

Associates an authorization object with the foreign server. The authorization stores the encrypted credentials for a user as a database object. The Teradata QueryGrid connector passes the credentials in the authorization to the remote platform identified by the foreign server when the foreign server is accessed.

INVOKER

DEFINER

You can specify either a DEFINER or an INVOKER, but not both. If neither INVOKER nor DEFINER are specified then INVOKER is used by default.

INVOKER is a keyword that indicates that the associated authorization must be present in the user database at the time that the foreign server is accessed.

Note: The user database is the database that was created for the user in the Teradata system when the user account was created.

DEFINER is a keyword that indicates that the associated authorization must be present in the database that contains the foreign server when the foreign server is accessed.

Note: The DEFAULT keyword that can be used with DEFINER in CREATE

AUTHORIZATION and REPLACE AUTHORIZATION statements is not needed in association with a foreign server.

If you use the DEFINER keyword, the authorization is global for all users who need to query the foreign server.

14 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER

TRUSTED

A keyword that indicates the associated authorization object was created as TRUSTED.

authorization_name

Specifies the name of the authorization object to be used when the foreign server is accessed.

Modify options

ADD

You can use to the ADD option to make the following changes:

• add or replace a global name value pair that is used to define the server object

• add an IMPORT or EXPORT table operator. If you want to replace a table operator that is already associated with the foreign server you must first drop the table operator before adding the new one.

name('value')

The name value pair or pairs that you want to add or modify.

IMPORT

Indicates that you are going to act on the operator that is used to import data into

Teradata Database.

EXPORT

Indicates that you are going to act on the operator that is used to export data out of

Teradata Database.

Drop options

DROP

You can use the DROP option to make the following changes:

• drop a global name value pair that was used to define a server object. You need only specify the name to drop the pair.

• drop an IMPORT or EXPORT table operator that was associated with a server definition.

When you drop a table operator, all related name value pairs are also dropped.

name

When used alone, name is the name of the name value pair that you want to drop.

IMPORT

Indicates that you are going to act on the operator that is used to import data into

Teradata Database.

EXPORT

Indicates that you are going to act on the operator that is used to export data out of

Teradata Database

Required Name Value Pairs

These name value pairs are required to create a functioning foreign server object. You can create a foreign server without a USING clause, but it will be nonfunctional.

Note that for sending queries and obtaining results, you also need to associate an import operator and an export operator with a foreign server.

Teradata Database-to-Teradata Aster 15

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER

hosttype

The type of host to connect to. For the Teradata-to-Aster connector, this value must be aster.

local_ips or ip_device

The IP addresses of the local Teradata nodes. You can use the IP address or the DNS name. ip_device supports a common node device name, but the device name found by using ifconfig must be on the same network for all nodes of the system.

remotehost

The DNS host name or IP address of the remote Teradata Aster queen node.

Note: The default port for the Teradata-to-Aster connector is 5001. If you run any other application that listens on port 5001, you must also specify a different port number in the

CREATE or ALTER FOREIGN SERVER statement. For more information see the port NVP in

Optional Name Value Pairs

Optional Name Value Pairs bytecountreportfreq

The frequency with which progress is updated in Viewpoint. The default is 50MB, which corresponds to each block. You can adjust this to a larger value if the update frequency of once per block is too resource-intensive.

Users can override this value at the query level by using a session QUERY_BAND name value pair. For example:

SET QUERY_BAND = 'bytecountreportfreq=256;' FOR SESSION;

concurrentstreams

The parallel efficiency to use. This value determines the number of parallel socket connections that are established between a local Teradata node and a remote Teradata

Aster vworker.

The valid range is 1 to 5. The default value is 1. With a value of 1, a node on the foreign server reads the requested data and uses the established socket connection to send the data in 64KB blocks to a node on the local system

If your network bandwidth setup can support higher values, users may want to override this server value at the query level by using a session QUERY_BAND name value pair.

For example:

SET QUERY_BAND = 'concurrentstreams=2;' FOR SESSION;

dbname

The database to connect to. You can use the dbname name value pair in the server object to limit access to specific databases. The default is beehive. This parameter is required if you use schemaname. The database name in the server object overrides users' selections.

disable_pushdown

When set to true, disables the pushdown of all query conditions to the remote system.

Valid values are true and false. By default, this NVP is set to false.

Certain system level, session level, and column level query attributes (such as casespecific) can affect character string comparison results. These attributes can cause some queries to return incorrect results due to incorrect row filtering on the remote system.

To avoid incorrect results caused by condition pushdown in situations where the

16 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER settings on the local system do not match the settings on the remote system, you can disable the pushdown of all conditions to the remote system.

For example, consider the following query and its EXPLAIN: explain SELECT * from UPTT48.table1@MyforeignServer where x2 <

'012';

The following EXPLAIN illustrates the processing of the query when disable_pushdown

is set to true

, and therefore no condition pushdown takes place during processing.

Explanation

-----------------------------------------------------------------------

1) First, we do an all-AMPs RETRIEVE step executing table operator

syslib.load_from_td with a condition of ("table1.X2 < '012 '").

< BEGIN EXPLAIN FOR REMOTE QUERY -->

We get external query:'SELECT x1 ,x2 FROM UPTT48.table1 WHERE X2 <

'012 '' for target system:server1.mycompany.com. 1) First, we

lock a distinct UPTT48."pseudo table" for read on a RowHash to

prevent global deadlock for UPTT48.table1. 2) Next, we lock

UPTT48.table1 for read. 3) We do an all-AMPs RETRIEVE step from

UPTT48.table1 by way of an all-rows scan with a condition of

("UPTT48.table1.x2 < '012 '") executing table operator

SYSLIB.load_to_tdRemote with a condition of ("(1=1)") into Spool 2

(used to materialize view, derived table, table function or table

operator d) (all_amps), which is built locally on the AMPs.

The size of Spool 2 is estimated with no confidence to be 3 rows

(64,068 bytes). The estimated time for this step is 0.16 seconds.

4) We do an all-AMPs RETRIEVE step from Spool 2 (Last Use) by way

of an all-rows scan into Spool 3 (group_amps), which is built

locally on the AMPs. The size of Spool 3 is estimated with no

confidence to be 3 rows (64,068 bytes). The estimated time for

this step is 0.16 seconds. 5) Finally, we send out an END

TRANSACTION step to all AMPs involved in processing the request.

-> The contents of Spool 3 are sent back to the user as the result

of statement 1. The total estimated time is 0.32 seconds.

<-- END EXPLAIN FOR REMOTE QUERY >

The size of Spool 1 is estimated with low confidence to be 80,000

rows (2,800,000 bytes). The estimated time for this step is 0.13

seconds.

2) Next, we do an all-AMPs RETRIEVE step from Spool 1 (Last Use) by

way of an all-rows scan with a condition of ("table1.X2 < '012 '")

into Spool 2 (group_amps), which is built locally on the AMPs.

The size of Spool 2 is estimated with no confidence to be 80,000

rows (3,360,000 bytes). The estimated time for this step is 0.54

seconds.

3) Finally, we send out an END TRANSACTION step to all AMPs involved

in processing the request.

-> The contents of Spool 2 are sent back to the user as the result of

statement 1. The total estimated time is 0.67 seconds.

The following EXPLAIN illustrates the processing of the query when disable_pushdown is set to false

, and processing is pushed down onto the remote system.

Teradata Database-to-Teradata Aster 17

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER

Explanation

-----------------------------------------------------------------------

1) First, we do an all-AMPs RETRIEVE step executing table operator

syslib.load_from_td with a condition of ("table1.X2 < '012 '").

< BEGIN EXPLAIN FOR REMOTE QUERY -->

We get external query:'SELECT x1 ,x2 FROM UPTT48.table1 ' for

target system:server1.mycompany.com. 1) First, we lock a distinct

UPTT48."pseudo table" for read on a RowHash to prevent global

deadlock for UPTT48.table1. 2) Next, we lock UPTT48.table1 for

3) We do an all-AMPs RETRIEVE step from UPTT48.table1 by way of an

read. all-rows scan with no residual conditions executing table

operator SYSLIB.load_to_tdRemote with a condition of ("(1=1)")

into Spool 2 (used to materialize view, derived table, table

function or table operator d) (all_amps), which is built locally

on the AMPs. The size of Spool 2 is estimated with low confidence

to be 8 rows (170,848 bytes). The estimated time for this step

is 0.16 seconds.

4) We do an all-AMPs RETRIEVE step from Spool 2 (Last Use) by way

of an all-rows scan into Spool 3 (group_amps), which is built

locally on the AMPs. The size of Spool 3 is estimated with low

confidence to be 8 rows (170,848 bytes). The estimated time for

this step is 0.16 seconds. 5) Finally, we send out an END

TRANSACTION step to all AMPs involved in processing the request.

-> The contents of Spool 3 are sent back to the user as the result

of statement 1. The total estimated time is 0.32 seconds.

<-- END EXPLAIN FOR REMOTE QUERY >

The size of Spool 1 is estimated with low confidence to be 80,000

rows (2,800,000 bytes). The estimated time for this step is 0.13

seconds.

2) Next, we do an all-AMPs RETRIEVE step from Spool 1 (Last Use) by

way of an all-rows scan with a condition of ("table1.X2 < '012 '")

into Spool 2 (group_amps), which is built locally on the AMPs.

The size of Spool 2 is estimated with no confidence to be 80,000

rows (3,360,000 bytes). The estimated time for this step is 0.54

seconds.

3) Finally, we send out an END TRANSACTION step to all AMPs involved

in processing the request.

-> The contents of Spool 2 are sent back to the user as the result of

statement 1. The total estimated time is 0.67 seconds.

listen_timeout

The number of seconds to wait for one connection while listening. The default is 60 seconds. This value represents the time period in which the query is parsed, runs on the foreign server, and returns results to the local system. If you are accessing large tables on the foreign server, you may want to increase this value to avoid having queries time out.

Users can override this server value at the query level by using a session QUERY_BAND name value pair. For example:

SET QUERY_BAND = 'listen_timeout=180;' FOR SESSION;

port

The local port number to which the foreign server can connect. This port must remain open. The default is 5001. If you run any other application that listens on port 5001, you

18 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

ALTER FOREIGN SERVER must specify a different port number in the CREATE or ALTER FOREIGN SERVER statement.

Note: This NVP is an exception to the rule that you do not use surrounding apostrophes

(single quotation marks) for name value pairs that are composed entirely of integers.

You must delimit the port value with apostrophes.

For example, following is the correct syntax for a port number: port ('6001')

read_timeout

The number of seconds to wait on the socket. The default value is 30.

Users can override this server value at the query level by using a session QUERY_BAND name value pair. For example:

SET QUERY_BAND = 'read_timeout=60;' FOR SESSION;

schemaname

The name of the schema to use when you import or export queries.

The Teradata-to-Aster connector supports and passes the following server name value pairs to the Teradata Aster system:

• local_ips

• read_timeout

• port

If a user uses SET QUERY_BAND to set any of these values for a session, then the

QUERY_BAND values take precedence over the values that were set when a foreign server object was created or last altered.

Required Privileges

You must have DROP SERVER privilege on the TD_SERVER_DB database or on the specified foreign server to modify the foreign server object. If you are modifying the table operators that are associated with the server, or adding a table operator, you must also have

EXECUTE FUNCTION and SELECT privileges on the specified table operators.

Usage Notes

You cannot use the following names in the name value pairs in ALTER SERVER statements:

• Columns

• hExplain

• IsNested

• Servermode

Note: External security options and ADD or DROP clauses must be specified in the syntax.

Teradata Database-to-Teradata Aster 19

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Example of Using ALTER FOREIGN SERVER Syntax

This example demonstrates altering a foreign server in Teradata Database by changing the number of parallel socket connections between the Teradata Database node and the Teradata

Aster vworker.

ALTER FOREIGN SERVER remote_system

ADD concurrentstreams(2) ;

AsterExecute

Purpose

The AsterExecute table operator exports data from a Teradata Database system to a Teradata

Aster server (the foreign server), executes a remote function, and returns the results.

20 Teradata Database-to-Teradata Aster

Syntax

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Syntax Elements

select_options

You can use any valid Teradata Database select options for the SELECT clause, such as an asterisk (*) for all data or standard column selection criteria, such as a partial column list.

Teradata Database-to-Teradata Aster 21

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Introduces the object or expression that you want to act on. You can specify up to 16 ON clauses, but the number of ON clauses in this SELECT must match the number of %s placeholders for temporary table names that you have in the ON clauses in the remote query.

table_name

The name of a table on the Teradata server to use in the query.

table_name@foreign_server_name

The name of a table on a foreign server to use in the query. The table can be on a

Teradata Aster server, or, if you are also using the appropriate Teradata QueryGrid connector, the table can be on an Oracle server or on a remote Teradata server. If the table is on a Teradata Aster server, you can optionally qualify it with the schema name.

The foreign server where the table is located does not have to be the same foreign server as the foreign server on which the Aster analytical function is run

(aster_foreign_svr_name, which appears just before the USING clause).

query_expression

A query expression that is input to the table operator. You can use any valid Teradata

Database query that generates a data set.

correlation_name

An alias for the table that is referenced in the ON clause.

HASH BY

An optional set of column names on which to hash order globally the columns input to a table function or table operator.

When you use a multiple input table operator that has multiple hash by clauses, the following restrictions apply:

• All of them must have the same number of partitioning parameters.

• The corresponding parameters must be the same type or matched using an implicit cast.

If you specify a LOCAL ORDER BY clause along with a HASH BY clause, the following restrictions apply:

• All the clauses must have the same number of LOCAL ORDER BY columns.

• The data types of the columns must be the same type or matched using an implicit cast.

For more information about HASH BY, see SQL Data Manipulation Language.

PARTITION BY

To partition for a table specified as input to a table operator.

You cannot specify a row-level security constraint column as a partitioning column. You can specify a column by name or position, or use an expression that resolves to a column.

If you have multiple PARTITION BY clauses, the following restrictions apply:

• All of them must have the same number of partitioning parameters.

• The corresponding parameters must be the same type or matched using an implicit cast.

22 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

If you specify an ORDER BY clause with a PARTITION BY clause, the following restrictions apply:

• All the clauses must have the same number of ORDER BY columns.

• The data types of the columns must be the same type or matched using an implicit cast.

PARTITION BY ANY

Specifies a table with no partitioning or order by parameters.

PARTITION BY ANY preserves the existing distribution of the rows on the AMPs. A

PARTITION BY ANY clause followed by ORDER BY clause means that all the rows are ordered by the ORDER BY clause on that partition, and it is functionally equivalent to using LOCAL ORDER BY without using a HASH BY clause.

The following restrictions apply:

• You cannot specify a PARTITION BY ANY clause and a LOCAL ORDER BY clause in the same ON clause.

• If you specify multiple ON clauses with a table operator, you can only specify one

PARTITION BY ANY clause. All other clauses must be DIMENSION

For more information about PARTITION BY and PARTITION BY ANY, see SQL Data

Manipulation Language.

DIMENSION

Specifies that a duplicate copy of the dimension table is created for every partition on which the table operator operates. You can specify zero or more DIMENSION clauses for each ON clause.

The following restrictions apply:

• You cannot use a LOCAL ORDER BY clause and a DIMENSION clause in the same ON clause.

• If you have only one ON clause as input to a table operator, you cannot use DIMENSION in it. You must have at least one PARTITION BY or HASH BY clause in a second ON clause to use DIMENSION.

• If you use multiple ON clauses and you specify only LOCAL ORDER BY in one of them, then all other ON clauses can only specify DIMENSION.

For more information about DIMENSION, see SQL Data Manipulation Language.

ORDER BY

LOCAL ORDER BY

Specifies that qualified rows are ordered on each AMP in preparation to be input to a table function.

You cannot use a LOCAL ORDER BY clause in addition to a DIMENSION clause in the same ON clause.

If you use multiple ON clauses, you cannot specify a LOCAL ORDER BY clause in addition to a PARTITION BY ANY clause in the same ON clause.

If you use multiple ON clauses and you specify only LOCAL ORDER BY in one of them, then all other ON clauses can only specify a DIMENSION clause.

If you specify multiple HASH BY clauses with LOCAL ORDER BY clauses, the following restrictions apply:

• All of the clauses must have the same number of LOCAL ORDER BY columns.

Teradata Database-to-Teradata Aster 23

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

• The data types of the columns must be the same type or matched using an implicit cast.

ORDER BY

How result sets are sorted. If you do not use this clause, result rows are returned unsorted.

You cannot specify ORDER BY as the only option in an ON clause. You must combine it with a PARTITION BY, PARTITION BY ANY, HASH BY, or DIMENSION clause.

If you specify an ORDER BY clause with a PARTITION BY clause, the following restrictions apply:

• All of the clauses must have the same number of ORDER BY columns.

• The data types of the columns must be the same type or matched using an implicit cast.

• When NORMALIZE and ORDER BY are specified in a query, the rows are normalized first and the result is ordered on the normalized result.

For more information about LOCAL ORDER BY and ORDER BY, see SQL Data

Manipulation Language.

aster_foreign_svr_name

The name of the Teradata Aster foreign server where the query is to run.

select_options

Any valid select options, such as an asterisk (*) to select all data, or a partial column list from the list of columns returned for the specified Aster analytical function.

aster_analytical_function

The Teradata Aster analytical function to execute on the Teradata Aster server.

To see a list of the Aster analytical functions that the Teradata-to-Aster connector supports, see

Supported Aster Functions .

For more information about the Teradata Aster analytical functions, see the Teradata Aster documentation available at www.info.teradata.com

Introduces one or more tables that contain the data to be analyzed by the specified Aster analytical function. The number of ON clauses allowed here depends on the Aster analytical function that you use.

A string that is automatically replaced with a Teradata Aster table identifier used for the data that is sent in the first set of ON clauses. Each %s corresponds positionally to one

ON statement in the outer SELECT. You must have one ON %s clause in the remote query for every ON clause in the outer SELECT.

aster_table_name

The name of a table on the foreign server for the Teradata Aster analytical function to act on.

aster_partition_and_order_options

Any valid Teradata Aster options for an ON clause, such as PARTITION BY ANY,

ORDER BY, and DIMENSION.

24 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

For information about Teradata Aster partition and order options, see the Teradata

Aster Database User Guide located at www.info.teradata.com

aster_analytical_function_options

Any valid options for the specified Teradata Aster analytical function.

For information about Teradata Aster analytical function options, see the Teradata Aster

Analytics Foundation User Guide located at www.info.teradata.com

SUBSTITUTE

Introduces one or more strings to replace and the replacement strings for the remote query that you are running on the Teradata Aster server. You can make any number of substitutions, and spaces in this expression are ignored.

The SUBSTITUTE clause is useful, for example, to avoid having to escape apostrophes

(single quotation marks) in the remote query. For an example that uses apostrophes and double quotation marks in a SUBSTITUTE clause, see

Usage Notes

string1

The string that you want to be replaced in the remote query.

The dash (-) and greater than (>) literal symbols.

string2

The string that you want to be used in the remote query that executes on the Teradata

Aster server.

Introduces the alias name for the derived table or the alias name with a comma-separated, filtered column list.

correlation_name

The name that you want to use for the table that is created by the execution of the remote query. This derived table name can be used in the query later, and it can contain a filtered column list, as in correlation_name(col1, col2).

column_name

A column, or list of columns separated by commas, to use from the derived table, for example, tv_spots(col1, col2).

Required Privileges

You must have EXECUTE FUNCTION and SELECT privileges on AsterExecute to use this function.

Usage Notes

• The AsterExecute table operator is located in the SYSLIB database.

• You do not need to know the names of the columns that will be returned if all columns are being retrieved from the function execution.

• Teradata Aster expects an apostrophe (single quotation mark) around certain types of expressions where Teradata Database expects a double quotation mark ("). For example, if you use the Teradata Aster PATTERN analytical function in your query, you need to

Teradata Database-to-Teradata Aster 25

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute either escape each apostrophe with a second apostrophe, or you can use the

SUBSTITUTE clause to ensure that the double quotation marks needed to satisfy

Teradata syntax requirements are translated to apostrophes when the remote query runs on the Teradata Aster server.

For example, in the following query, each apostrophe is escaped by a second apostrophe to satisfy Teradata Database syntax, as follows:

SELECT * FROM ASTEREXECUTE

(

ON (SELECT * FROM tab1) @astersrv1 USING

REMOTEQUERY('select * from sessionize (on %s partition by(''c1'') order by (''c1'') timecolumn (''c1'') timeout (''3000'') )')

) AS tv_spots;

If you use the SUBSTITUTE clause instead, you can use the double quotation marks and your query would look as follows:

SELECT * FROM ASTEREXECUTE

(

ON (SELECT * FROM tab1) @astersrv1 USING

REMOTEQUERY('select * from sessionize (on %s partition by("c1") order by ("c1") timecolumn ("c1") timeout ("3000") )')

SUBSTITUTE(' " -> '' ')

) AS tv_spots;

For examples of using AsterExecute, see

Using the Teradata-to-Aster Connector with

SELECT Statements .

Supported Aster Functions

The following table shows the supported Aster Time Series, Path and Attribution Analysis functions:

Aster Function Notes

Attribution

CMAVG Cumulative Moving AVG

DTW

Path_Generator

Path_Start

Path_Summarizer

SAX

Sessionize

Dynamic Time Warping

Symbolic aggregate approximation

The following table shows the supported Aster Pattern Matching functions:

Aster Function

nPath

Notes

The following table shows the supported Aster Statistical Analysis functions:

26 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Aster Function

ApproxDCountReduce/ApproxDCountMap

ApproxPercentileReduce/ApproxPercentileMap

Notes

Approximate Distinct Count

ConfusionMatrix

ConfusionMatrixPlot

Corr_Reduce distnmatch

Correlation

Distribution Matching

EMAVG

Hist_map

Hist_reduce

FMeasure

Histogram_map

LARSPredict

LinReg

Exponential Moving Average

Histogram

Least Angle Regression

Linear regression

Principal Component Analysis

Pca_Reduce

Pca_Map

Percentile

SMAVG

Sample

SparseSVMPredictor

SVMModelPrinter

VWAP

WMAVG

Simple Moving Average

Support Vector Machines

Volume-Weighted Average Price

Weighted Moving Average

The following table shows the supported Aster Text Analysis functions:

Aster Function

EvaluateNamedEntityFinderRow /

EvaluateNamedEntityFinderPartition

EvaluateSentimentExtractor

ExtractSentiment

FindNamedEntity

LDATopicPrinter ldist

NaiveBayesText

Notes

Named Entity Recognition (NER)

Sentiment Extraction Functions

Named Entity Recognition (NER)

Levenshtein distance

Teradata Database-to-Teradata Aster 27

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Aster Function

NaiveBayesTextPredict nGram

PosTagger

Sentenizer

TF_IDF

TextChunker

TextClassifier

TextClassifierEvaluator

Text_Parser

TextMorph

TextTagging

TextTokenizer

Notes

Parts-Of-Speech Tagger

Term Frequency-Inverse Document Frequency

The following table shows the supported Aster Cluster Analysis functions:

Aster Function

KmeansPlot

Notes

The following table shows the supported Aster Naive Bayes functions:

Aster Function

naiveBayesMap naiveBayesReduce

Notes

The following table shows the supported Aster Decision Trees functions:

Aster Function

Forest_Analyze single_tree_predict

Notes

Random Forest Function

Single Decision Tree Function

The following table shows the supported Aster Association Analysis functions:

Aster Function

Basket_Generator

WSRecommender

Notes

Weighted-sum recommendations

The following table shows the supported Aster Graph Analysis functions:

Aster Function

AllPairsShortestPath

Notes

28 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

AsterExecute

Aster Function

Betweenness

Closeness

EigenvectorCentrality

LocalClusteringCoefficient

LoopyBeliefPropagation nTree

PageRank

Notes

The following table shows the supported Aster Data Transformation functions:

Aster Function

Antiselect apache_log_parser

IdentityMatch

IpGeo

JSONParser

Multi_case

MurmurHash

PSTParserAFS

Pack

Pivot

Unpack

Unpivot

XMLParser

XMLRelation

Notes

Personal Storage Table

The following table shows the supported Aster Data Visualization functions:

Aster Function

CfilterViz

NpathViz

Notes

Teradata Database-to-Teradata Aster 29

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

BEGIN LOGGING

Purpose

Starts the auditing of SQL requests that attempt to access data.

This topic describes only the portions of the BEGIN LOGGING syntax diagram that are specific to this Teradata QueryGrid connector. For information about the other syntax that you can use with BEGIN LOGGING, see SQL Data Definition Language - Syntax and

Examples, B035-1144.

Syntax

BEGIN LOGGING ON

DENIALS

FOR CONSTRAINT

WITH TEXT

constraint_name

FIRST

LAST

FIRST AND LAST

EACH

ALL

operation

GRANT

database_name user_name

AUTHORIZATION authorization_name

DATABASE database_name

USER database_name

TABLE

VIEW

database_name.

user_name.

MACRO

PROCEDURE

FUNCTION

TYPE

FOREIGN SERVER

object_name

;

Syntax Element

ON FOREIGN SERVER object_name

Indicates that the database object for which access is to be logged is a foreign server.

You must specify an object name, which is the name of the foreign server. You can optionally specify the name of the containing database, which must be

TD_SERVER_DB. You cannot use a user_name with FOREIGN SERVER.

30 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

COMMENT (Comment Placing Form)

Purpose

Creates a user-defined description of a user-defined database object or definition in the data dictionary.

This topic describes only the portions of the COMMENT syntax diagram that are specific to

Teradata QueryGrid. For information about the other syntax elements in COMMENT

(Comment Placing Form), see SQL Data Definition Language - Syntax and Examples,

B035-1144.

Syntax

COMMENT

object_kind_1 object_kind_2 database_name.

user_name.

object_name

'comment'

;

Syntax Element

object_kind_2

An optional database object kind specification.

You can specify the following database object kinds to retrieve a comment for the kind of object they represent, but they are optional.

• DATABASE

• FOREIGN SERVER

• TABLE

• USER

If you specify an optional database_name with FOREIGN SERVER, the name must be

TD_SERVER_DB. You cannot use a user_name with FOREIGN SERVER.

All existing rules for COMMENT apply for use with a FOREIGN SERVER object.

The optional comment string is recorded in DBC.TVM.

For more information about using COMMENT (Comment Placing Form), see SQL Data

Definition Language - Syntax and Examples, B035-1144.

CREATE AUTHORIZATION and REPLACE

AUTHORIZATION

Purpose

Creates or replaces an authorization object in Teradata Database. The authorization stores credentials for a user account that exists on a remote platform. The credentials need only be

Teradata Database-to-Teradata Aster 31

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE AUTHORIZATION and REPLACE AUTHORIZATION valid on the platform specified in the foreign server object; they do not need to be valid on the Teradata Database or on its underlying operating system. When you specify TRUSTED in the CREATE or REPLACE AUTHORIZATION statement, Teradata Database does not validate the credentials.

For Teradata QueryGrid, an authorization object is used by a foreign server object to log into a remote platform using credentials that are valid on the remote platform. When a Teradata user makes a request that uses the foreign server, the foreign server object provides the credentials from the authorization object to the target platform for authentication. This allows any part of the request that runs on the remote platform to use the context, privileges, and access control granted to the remote platform user account.

For example, if the foreign server connects to a Teradata Aster Database that authenticates users using the OS platform, then the associated authorization object must contain credentials for the OS platform user account.

The syntax table describes only the portions of the CREATE AUTHORIZATION and

REPLACE AUTHORIZATION syntax diagram that are specific to Teradata QueryGrid. For information about the other syntax that you can use with CREATE AUTHORIZATION and

REPLACE AUTHORIZATION, see SQL Data Definition Language - Syntax and Examples,

B035-1144.

Syntax

Syntax Elements

database_name.

user_dbname.

Optional name of the location where the authorization is to be stored.

The default location that is used changes based on whether DEFINER or INVOKER is specified. The following rules apply to specifying DEFINER or INVOKER:

• If you specify DEFINER, the database or user you specify must be the containing database or user for the foreign server, UDF, table UDF, method, or external SQL procedure. If no location is specified, the authorization is created in the database that contains the foreign server objects (TD_SERVER_DB).

• If you specify INVOKER, the database_name or user_dbname you specify must be associated with the session user who will be sending requests to the foreign server. If no location is specified, the authorization is placed in the user database of the creator of the authorization.

authorization_name

Name for the authorization object. This name must be unique within the database in which it is stored.

Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE AUTHORIZATION and REPLACE AUTHORIZATION

INVOKER

DEFINER

• If you specify INVOKER TRUSTED, or if you specify TRUSTED alone, Teradata creates the authorization object in the database of the user who creates the object.

This syntax makes the authorization available only to those with privilege to the user database.

• If you specify DEFINER TRUSTED or DEFINER DEFAULT TRUSTED, then

Teradata creates the authorization object in the database that contains the object that is using the authorization; for a foreign server this is the TD_SERVER_DB database.

This syntax makes the authorization globally available.

TRUSTED

A keyword used to specify that the credentials are to be encrypted and stored as database objects.

You cannot use TRUSTED authorizations in CREATE or REPLACE UDF or XSP statements.

'fs_user_name'

The name of the credential on the remote platform to be used by the foreign server.

'fs_password'

The password for the credential on the remote platform to be used by the foreign server.

All existing rules for CREATE AUTHORIZATION and REPLACE AUTHORIZATION apply.

For more information about using CREATE AUTHORIZATION and REPLACE

AUTHORIZATION, see SQL Data Definition Language - Syntax and Examples,

B035-1144.

Usage Notes

• A proxy user can be used by one or more trusted authorization objects. To drop the proxy, you need to drop the authorization on the proxy. For example:

DROP FOREIGN SERVER TD_SERVER_DB.remote_system ;

DROP AUTHORIZATION TD_SERVER_DB.remote_proxy ;

You do not have to drop the foreign server objects that are used by the proxy, but it is a best practice to do so, because you must have an authorization associated with a foreign server object in order to reference the object. If you drop an authorization but do not drop a foreign server object that uses it, then the next time that you try to reference the foreign server object, you get an error message.

• The proxy users who are configured to use the Teradata-to-Aster connector are users who are defined on the remote Teradata Aster database. A DBA on the remote Teradata Aster system can drop these individual Teradata Aster users on the Teradata Aster system without any constraints.

However, before a DBA on the remote Teradata Aster system drops a remote proxy user, a

DBA on the Teradata system should drop the authorization and foreign server objects as well. If the authorization and foreign server objects on the Teradata system are not dropped first, users see errors during query execution.

• If the credentials change on the foreign server's target platform, you must remember to replace the credentials in the authorization object. If you fail to update the invalid

Teradata Database-to-Teradata Aster 33

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE FOREIGN SERVER information, the next time that you try to reference the foreign server object, you get an error message.

• If you drop an authorization object, keep in mind that it may be used by multiple foreign server objects. You should either drop the foreign server objects or alter them so that they specify a valid authorization object. If you fail to update the invalid information, the next time that you try to reference the foreign server object, you get an error message.

Examples of Creating and Replacing the Authorization

If you want to make the authorization available globally, create the authorization on

TD_SERVER_DB using the DEFINER TRUSTED type.

CREATE AUTHORIZATION TD_SERVER_DB.remote_system1

AS DEFINER TRUSTED USER 'proxy_1'

PASSWORD 'Global' ;

If you use DEFINER TRUSTED, as in this example, then the credentials for sales must be created in the TD_SERVER_DB database.

CREATE AUTHORIZATION TD_SERVER_DB.sales AS DEFINER TRUSTED

USER 'johnson'

PASSWORD 'Secret';

The following two examples establish authorization for the user who invokes the object. The credentials are encrypted and stored in the user database as an object.

CREATE AUTHORIZATION sales AS TRUSTED

USER 'johnson'

PASSWORD 'Secret' ;

REPLACE AUTHORIZATION sales AS INVOKER TRUSTED

USER 'williams'

PASSWORD 'topsecret' ;

CREATE FOREIGN SERVER

Purpose

Creates a foreign server object and associates table operators with it.

When you create a server object, you can customize it based on its purpose. You can define multiple server objects for the same remote database, each with different characteristics needed by different users.

You can use name value pairs to define the characteristics of the foreign server.

34 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE FOREIGN SERVER

Syntax

CREATE FOREIGN SERVER

server_name

EXTERNAL SECURITY

INVOKER

DEFINER

TRUSTED

authorization_name

using option

DO IMPORT WITH

operator option

;

, DO EXPORT WITH

operator option operator option

table_operator

using option

database_name.

Syntax Elements

server_name

The name given to the foreign server object.

EXTERNAL SECURITY

INVOKER

DEFINER

You can specify either a DEFINER or an INVOKER, but not both. If neither INVOKER nor DEFINER are specified then INVOKER is used by default.

INVOKER is a keyword that indicates that the associated authorization must be present in the user database at the time that the foreign server is accessed.

Note: The user database is the database that was created for the user in the Teradata system when the user account was created.

DEFINER is a keyword that indicates that the associated authorization must be present in the database that contains the foreign server when the foreign server is accessed.

Note: The DEFAULT keyword that can be used with DEFINER in CREATE

AUTHORIZATION and REPLACE AUTHORIZATION statements is not needed in association with a foreign server.

Teradata Database-to-Teradata Aster 35

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE FOREIGN SERVER

If you use the DEFINER keyword, the authorization is global for all users who need to query the foreign server.

TRUSTED

A keyword that indicates the associated authorization object was created as TRUSTED.

authorization_name

Specifies the name of the authorization object to be used when the foreign server is accessed.

Using option

USING

USING introduces the global name value pairs (NVPs) that provide the server definition information. USING must be followed by at least one name value pair of the form

name('value'), but an empty value of ' ' is supported. You can create a foreign server without a

USING clause, but users cannot query a foreign server until you complete the server definition with an import operator and an export operator.

Note: With the exception of the port NVP, do not use surrounding apostrophes (single quotation marks) for name value pairs that are composed entirely of integers. NVPs that contain only integers are handled differently from those that contain alphabetic strings, alphanumeric strings, or characters and integers, such as an IP address. If you delimit an integer value with apostrophes, then the value is silently ignored and the default value is used instead.

Required Name Value Pairs

These name value pairs are required to create a functioning foreign server object. You can create a foreign server without a USING clause, but it will be nonfunctional.

Note that for sending queries and obtaining results, you also need to associate an import operator and an export operator with a foreign server.

hosttype

The type of host to connect to. For the Teradata-to-Aster connector, this value must be aster.

local_ips or ip_device

remotehost

The DNS host name or IP address of the remote Teradata Aster queen node.

Note: The default port for the Teradata-to-Aster connector is 5001. If you run any other application that listens on port 5001, you must also specify a different port number in the

CREATE or ALTER FOREIGN SERVER statement. For more information see the port NVP in

Optional Name Value Pairs

36 Teradata Database-to-Teradata Aster

Chapter 3 Syntax for Teradata QueryGrid: Teradata Database-to-Teradata Aster Database

CREATE FOREIGN SERVER

Optional Name Value Pairs bytecountreportfreq

Users can override this value at the query level by using a session QUERY_BAND name value pair. For example:

SET QUERY_BAND = 'bytecountreportfreq=256;' FOR SESSION;

concurrentstreams

The parallel efficiency to use. This value determines the number of parallel socket connections that are established between a local Teradata node and a remote Teradata

Aster vworker.

If your network bandwidth setup can support higher values, users may want to override this server value at the query level by using a session QUERY_BAND name value pair.

For example:

SET QUERY_BAND = 'concurrentstreams=2;' FOR SESSION;

dbname

disable_pushdown

When set to true, disables the pushdown of all query conditions to the remote system.

Valid values are true and false. By default, this NVP is set to false.

To avoid incorrect results caused by condition pushdown in situations where the settings on the local system do not match the settings on the remote system, you can disable the pushdown of all conditions to the remote system.

For example, consider the following query and its EXPLAIN: explain SELECT * from UPTT48.table1@MyforeignServer where x2 <

'012';

The following EXPLAIN illustrates the processing of the query when disable_pushdown

is set to true

, and therefore no condition pushdown takes place during processing.

Explanation

-----------------------------------------------------------------------

1) First, we do an all-AMPs RETRIEVE step executing table operator

syslib.load_from_td with a condition of ("table1.X2 < '012 '").

< BEGIN EXPLAIN FOR REMOTE QUERY -->

We get external query:'SELECT x1 ,x2 FROM UPTT48.table1 WHERE X2 <

'012 '' for target system:server1.mycompany.com. 1) First, we

Teradata Database-to-Teradata Aster 37