QueryGrid Installation

Teradata® QueryGrid™
Installation and User Guide
Release 2.07
February 2019
B035-5991-118K
DOCS.TERADATA.COM
Copyright and Trademarks
Copyright © 2016 - 2019 by Teradata. All Rights Reserved.
All copyrights and trademarks used in Teradata documentation are the property of their respective owners. For more information, see
Trademark Information.
Product Safety
Safety type Description
Indicates a situation which, if not avoided, could result in damage to property, such as to equipment
NOTICE or data, but not related to personal injury.
Indicates a hazardous situation which, if not avoided, could result in minor or moderate personal
CAUTION injury.
Indicates a hazardous situation which, if not avoided, could result in death or serious personal injury.
WARNING
Warranty Disclaimer
Except as may be provided in a separate written agreement with Teradata or required by applicable law, the information available
from the Teradata Documentation website or contained in Teradata information products 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 noninfringement.
The information available from the Teradata Documentation website or contained in Teradata information products 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.
The information available from the Teradata Documentation website or contained in Teradata information products may be changed or
updated by Teradata at any time without notice. Teradata may also make changes in the products or services described in this information
at any time without notice.
Feedback
To maintain the quality of our products and services, e-mail your comments on the accuracy, clarity, organization, and value of this document
to: teradata-books@lists.teradata.com
Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed nonconfidential. Without
any payment or other obligation of any kind and without any restriction of any kind, Teradata and its affiliates are hereby free to (1) reproduce,
distribute, provide access to, publish, transmit, publicly display, publicly perform, and create derivative works of, the Feedback, (2) use any
ideas, concepts, know-how, and techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing,
and marketing products and services incorporating the Feedback, and (3) authorize others to do any or all of the above.
Contents
Chapter 1: Teradata QueryGrid Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Teradata QueryGrid Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Teradata QueryGrid Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Active, Pending, and Previous Teradata QueryGrid Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Teradata QueryGrid Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Teradata QueryGrid 1.0x and 2.0x Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Teradata QueryGrid in the Teradata Public Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Part I: Preparing for Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 2: Preparing for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
QueryGrid Installation Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Obtaining a Change Control Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Downloading Required Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Part II: Installing and Configuring Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 3: Installing and Configuring Teradata QueryGrid Manager . . . . . . . . . . . . . . . . . . . . . 26

Installing Teradata QueryGrid Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Creating a Join Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Clustering Deployed QueryGrid Manager Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Default publicAddress, bindAddress, and clusterAddress Overview . . . . . . . . . . . . . . . . . . . . . . 28
Adding Aliases for Other Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Chapter 4: Setting Up Teradata QueryGrid in the Viewpoint Administration Portlets . . . . . . . . 31

Installing a QueryGrid Root Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding a Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 5: Configuring Teradata QueryGrid in the QueryGrid Portlet . . . . . . . . . . . . . . . . . . . . . 33

Adding the QueryGrid Portlet to the Viewpoint Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Changing a Service Account Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Updating the Teradata QueryGrid Manager Password in the Monitored Systems Portlet . . . . . . 33
Uploading Connector Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Uploading Fabric Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Uploading Node Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Adding a Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Adding a Data Source System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Teradata® QueryGrid™ Installation and User Guide, Release 2.07 3

Contents
Add Data Source Nodes to a System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Adding a Dedicated Bridge System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Add Non-Data Source Nodes to a Dedicated Bridge System . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Adding a Bridge System Using Data Source Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Adding a Fabric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Adding a Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Adding a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adding a Communication Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Adding a User Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Adding a Role Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Adding a Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Running a Connector Diagnostic Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Running a Link Diagnostic Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Running a Link Bandwidth Test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Part III: Configuring and Using Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 6: Using the Teradata Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . 53

Completing the Teradata Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Using the Teradata Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Migrating 1.0x Teradata Foreign Server Definitions to 2.0x Teradata Connectors . . . . . . . . . . . 122
Chapter 7: Using the Presto Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . . 124

Completing the Presto Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Using the Presto Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Chapter 8: Using the Hive Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . 146

Completing the Hive Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Using the Hive Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Chapter 9: Using the Spark SQL Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . 171
Completing the Spark SQL Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Using the Spark SQL Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Chapter 10: Using the Oracle Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . 194
Completing the Oracle Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Using the Oracle Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Part IV: Managing QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Chapter 11: Modifying an Existing QueryGrid Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Working with Active, Pending, or Previous Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Editing a Fabric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Editing a Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Editing a Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Contents
Editing a Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Editing a System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Editing a Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Editing a Communication Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Editing a User Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Chapter 12: Teradata QueryGrid Monitoring, Logging, and Error Handling . . . . . . . . . . . . . . . 218
Fabric Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Monitoring User Queries Between Local and Remote Servers . . . . . . . . . . . . . . . . . . . . . . . . . 221
Logging and Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Chapter 13: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Solutions for Job Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Chapter 14: Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Teradata QueryGrid Manager Settings and Account Management . . . . . . . . . . . . . . . . . . . . . . 227
Restarting a Fabric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Resetting Teradata QueryGrid Manager to Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Removing Teradata QueryGrid Manager from a Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Backup and Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Migrating QueryGrid Manager to a New Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
QueryGrid Manager RESTful APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Part V: Upgrading Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Chapter 15: Upgrading QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Teradata QueryGrid Upgrade Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Upgrading Teradata QueryGrid Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Upgrading Teradata QueryGrid Node Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Upgrading Teradata QueryGrid Connectors and Fabrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Removing Old Software Versions from Teradata QueryGrid Manager . . . . . . . . . . . . . . . . . . . 237
Appendix A: QueryGrid Portlet Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Appendix B: QueryGrid Portlet Table and Row Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Appendix C: Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Appendix D: Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

1
Teradata QueryGrid Overview
Teradata QueryGrid Description

Teradata® QueryGrid™ 2.0x is a data analytics fabric that provides seamless, high-performing data access,
processing, and movement across one or more data sources. The data sources can be the same type,
such as Teradata Database and Teradata Database, or different types, such as Teradata Database and
Presto.
Teradata QueryGrid connectors join data sources in a fabric. Each connector can initiate SQL queries and
be the target of SQL queries within the fabric. Links specify which connectors can communicate with each
other.
Teradata QueryGrid supports the following connectors:
• Teradata Database
• Presto
• Hive (for Cloudera Distribution of Hadoop and Hortonworks Data Platform)
• Spark SQL
• Oracle (only as a target connector)
Note:
As of Teradata QueryGrid 2.07, only links that involve the Teradata Connector are supported. For
example, links where neither the initiator or target connector are a Teradata connector, such as Hive
to Oracle, are not supported.
Teradata QueryGrid Components

Teradata QueryGrid includes the following components.
Component Description
Teradata Software installed on a dedicated physical machine (TMS or server) or VM that enables
QueryGrid definition, administration, and monitoring of Teradata QueryGrid.
Manager After installing Teradata QueryGrid Manager, configure it in Viewpoint, and then use
the QueryGrid portlet to install and configure the remaining Teradata QueryGrid
components.
Data Center Logical name that represents the physical location of systems (data sources) in
Teradata QueryGrid.
System (Data One or more data source nodes that share the same software platform, such as
Source) Teradata Database nodes, nodes in a Hadoop cluster (CDH or HDP), or nodes in a
Presto cluster.

1: Teradata QueryGrid Overview
System (Bridge) A subset of data source nodes or non-data source nodes used to perform CPU-
intensive operations such as compression and encryption, and to transfer data.
Fabric One or more data source nodes, in different systems, that run a compatible version of
Teradata QueryGrid software over the same port.
Connector Adapter software for a data source that enables data type mapping, conversion, and
communication with other connectors in the same Teradata QueryGrid fabric.
Link Named configuration that specifies which connectors can communicate with each other
and defines rules of data transfer.
Teradata QueryGrid Manager

Teradata QueryGrid Manager performs the following functions in Teradata QueryGrid:
• Administers and monitors Teradata QueryGrid
• Allows installation, configuration, and upgrade of Teradata QueryGrid
• Initiates connectivity and bandwidth diagnostics checks
• Captures and summarizes query performance metrics
• Manages keys for secure access to Teradata QueryGrid
• Captures logs generated from Teradata QueryGrid components
The number of Teradata QueryGrid Manager instances required depends on the QueryGrid Managers
hardware specifications, the number of data source nodes in the fabric, and the volume of QueryGrid
queries. At least two QueryGrid Managers are recommended for high availability.
When more than one Teradata QueryGrid Manager instance is installed, cluster the Teradata QueryGrid
Manager instances for high availability and scalability. Clustering makes sure that all Teradata QueryGrid
Manager instances have the same configuration so they can each administer and monitor Teradata
QueryGrid. Teradata recommends creating only one QueryGrid Manager cluster in your enterprise system
to prevent silos where systems are not able to join the same QueryGrid fabric.
When a cluster is present, failover and recovery of a QueryGrid Manager instance in a cluster is automatic.
If one instance goes offline, the other instances in the cluster take over the workload of the failed instance.
Once the failed QueryGrid Manager comes back online, it automatically recovers any new configuration
updates made while offline and resumes its workload as it was before the failure.
Data Center
A Data Center performs the following functions in Teradata QueryGrid:
• Allows Teradata QueryGrid Manager to determine whether communication between two data sources
(systems) is across a LAN or WAN
• Makes sure communication with Teradata QueryGrid Manager remains LAN-local if a Teradata
QueryGrid Manager is available locally

When you install Teradata QueryGrid Manager software on a physical machine, a default Data Center is
created using the hostname of the TMS, VM, or server. The default Data Center name is displayed in the
QueryGrid portlet.
The default Data Center cannot be deleted. It can be renamed, or you can do one of the following:
• Create a new Data Center in the QueryGrid portlet
• Create a new Data Center during clustering if you have two or more Teradata QueryGrid Manager
instances.
System (Data Source)

During Teradata QueryGrid configuration, Teradata QueryGrid is added as a monitored system.
The following data source systems can be added to Teradata QueryGrid. Each system must have its own
connector.
• Hive (CDH and HDP)
• Presto
• Spark SQL
• Oracle
Data source nodes added to systems in Teradata QueryGrid can be associated with only one system. During
Teradata QueryGrid configuration, the node and fabric software is installed on every node in a system. The
node software manages the fabrics and connectors on the node.
System (Bridge)
Bridge systems represent a subset of data source nodes or a separate set of non-data source nodes that
allow:
• All network traffic to flow through the nodes in the bridge system instead of through all the nodes in
data source systems
• Offloading CPU-intensive operations such as data encryption or compression to the nodes in the bridge
system instead of using all the nodes in data source systems
• Using nodes connected to a public network for data transfer
One or two bridge systems can be included in the data transfer path between data source nodes in initiator
and target systems. The nodes in a bridge system can be:
• A subset of data source nodes running QueryGrid node software. The data source nodes can be in
the initiator system, or target system, or both.
• A set of non-data source nodes running QueryGrid node software. The non-data source nodes do not
need connector software because they do not have local data to process. An example of a non-data
source node is an edge node in a Hadoop system.
A link is used to define the data transfer path. One or two bridges can be included in the data transfer path.
A link can contain one or more hops. The number of hops is based on the number of bridges.

• If there are no bridges, there is one hop.

• If there is one bridge, there are two hops.
• If there are two bridges, there are three hops.
The hop defines the network and communication policy to be used for data movement between connection
points in the data transfer path.
Fabric
A fabric performs the following functions in Teradata QueryGrid:
• Enables communication between paired data source nodes of the same type, such as Teradata
Database and Teradata Database, or a different type, such as Teradata Database and Presto
• Allows a user to initiate a single SQL query that joins data from two or more systems (data sources)
within the fabric
There is no restriction on the size of the data that is transported between data source nodes in a fabric.
Fabric software is installed on data source nodes and does the following:
• Allows the Teradata QueryGrid connectors to:
◦ Communicate with each other in parallel
◦ Run, process, and transport data efficiently
• Monitors fabric usage per query and reports metrics to the Teradata QueryGrid Manager
Connectors and links are associated with a fabric.
Connectors
A connector performs the following functions in Teradata QueryGrid:
• Provides for query processing across data sources (systems)
• Translates query request SQL from one source query format to another
• Transforms data, converting the data from one data type or format to another so that the data can be
exchanged between different systems (data sources).
• Enables data sources to participate in queries. Any connector that joins the fabric can participate in
the queries.
• Enables data sources to initiate queries.
• Enables sending and receiving data to and from the fabric
• Communicates with other connectors in the fabric
• Controls the running of queries on target systems. All connectors can act as a target of queries and
control the queries that are run on a target system (data source) on behalf of the initiator system (data
source)
• Return query results to initiating systems
Connectors are specific to the system type (Teradata Database, Hive, or Presto-configured Hadoop), and
there can be only one connector for each system type. A Teradata Database system hosts a Teradata
connector, but a single Hadoop system can host multiple connectors (Hive and Presto).

Optional connector properties allow you to refine a connector type configuration, or override connector
properties set during configuration.
Connector software connects data sources with the Teradata QueryGrid fabric. The software is installed on
all data source nodes in a system. Fabric software is also installed on all data source nodes in a system.
Fabric software includes a driver. A driver runs on one or more data source nodes called driver nodes. As
part of query processing, a driver node receives requests from the initiator connector and submits the
requests to the target system. The driver loads the connector, reads messages, invokes methods to process
requests, and sends responses.
When you configure a connector, you must specify which nodes in a system (data source) are driver nodes.
Only a subset of the nodes on a large system need to be driver nodes. Use multiple driver nodes for
redundancy and to share the workload required for query initiation.
After a target driver node submits a query, connection caching forms a connection pool that does the
following:
• Reuses physical connections
• Reduces overhead for QueryGrid queries
• Minimizes creating and closing sessions
The connection pool uses the same JDBC connection for all phases of a single query or for subsequent
queries with the same session and user credentials. For more information on configuring tunable connector
pool properties, see the connector and link properties information in the relevant connector topics.
Links
A connector can be both an initiator or a target of a query. A link is a named configuration that defines the
initiator connector and target connector pair.
• Initiating connector: Point from which a QueryGrid query originates. For example, in a Teradata-to-
Presto query, the Teradata connector initiates the query.
• Target connector: Destination point of a QueryGrid query. For example, in a Teradata-to-Presto query,
a Presto connector is the target connector that the initiating connector accesses to either import or
export data.
You can create initiating connector and target connector link pairings only for connector types you have
defined.
• If you have defined only Teradata Database connectors, you can create links only between Teradata
Database systems.
• If you have defined both Teradata and Presto connectors, you can create links between Teradata
Database systems and Presto systems.
• If you have defined Teradata, Presto and Hive connectors, you can create links for all combinations of
these connector types.
Links simplify configuration of foreign server definitions in preparation for running QueryGrid queries.
In a Teradata QueryGrid fabric, each link:
• Specifies an initiating connector and a target connector link pairing to use for querying

• Specifies whether bridges are used:

◦ If no bridges are used, only one hop is defined (the hop between the initiator and target)
◦ If one bridge is used, two hops are defined (the hop between the initiator and bridge, and the hop
between the bridge and target)
◦ If two bridges are used, three hops are defined (the hop between the initiator and the first bridge,
the hop between the first bridge and second bridge, and the hop between the second bridge and
target)
• Defines the properties of initiating and target connectors
When you create links and associated properties, you are creating Configuration Name Value Pairs
(NVP). NVP does the following:
◦ Specifies the behavior of the target connector component
◦ Configures how data is transformed
◦ Configures the underlying link data transportation layer
◦ Affects how the initiator connector performs
Optional properties allow for configuration refinement of the initiating or target connector. These link
properties override connector properties.
• Defines initiating and target networks for hops
Links refer to networks to determine which interfaces to use for data transfer. A query originates in a
certain server or network and is sent to a target server or network. If no network is specified, the link
uses any working route.
Networks are defined by rules that map physical network interfaces to logical network definitions, either
by interface name or by CIDR notation. The rules are checked in the order in which they appear in a
matching rules list.
• Specifies a communications policy that defines rules for transferring data between target and initiating
connectors and bridges (if used)
Communication policies define how systems communicate with one another and allow you to configure
the transfer concurrency and security options, and to enable or disable ZStandard data compression
on row data blocks during data transfer.
Teradata QueryGrid is preconfigured with a policy appropriate to use over LANs (LAN Policy) and a
policy appropriate for use with WANs (WAN Policy).
Communication policies are not necessarily specific to the systems involved, so you can reuse them.
• Specifies user mappings (optional)
User mappings allow a user logged on to the initiating system to submit queries as a specific user on
the target system. You can map multiple users on the initiating system to a single user on the target
system, if applicable, but cannot map multiple users on the target system to a single user on the
initiating system.
In the QueryGrid portlet, you can construct a table mapping a username on one data source to a
username on another data source.

When using the Hive, Presto, or Spark target connector without security, user mapping is typically
required. For example, if a query is initiated using a Teradata-to-Hadoop link by user Joe, Teradata
automatically changes the username to all uppercase and sends the query as user JOE by default to
the target system. The following are possible outcomes for this use-case when no security is used with
a Hive target connector:
◦ The user Joe does not exist on the target system. In this scenario, the query must be run with an
existing user on the target system such as hive. In this scenario, user mapping is required where
JOE on the Teradata system is mapped to the user hive on the target Hive system.
◦ The user Joe does exist on the target system, but as joe (all lowercase). In this scenario, user
mapping is required where JOE on the Teradata system is mapped to joe on the target Hive
system.
◦ The user Joe does exist on the target as JOE (all uppercase). This scenario does not require user
mapping.
When a security platform such as Kerberos is used, user mapping is not required when using a Hive,
Presto, or Spark target connector.
Active, Pending, and Previous Teradata QueryGrid

Configurations
Making changes to a Teradata QueryGrid configuration can potentially impact production workloads.
Configuration changes include changes to the following:
• Fabric, connector, and node software package versions
• Fabric configuration
• Connector configuration
• Links and link pairings
• Networks, communication policies, and user mappings associated with a link
The fabric, connector, and software packages have versions, and each of the components listed above has
a version in a Teradata QueryGrid configuration. Each component in a Teradata QueryGrid configuration
can have one of the following states. These states allow you to manage changes to your Teradata QueryGrid
configuration.
Item Description
Active The configuration actively processing production workloads in the production environment. The
configuration has been tested and verified.
If you replace an active version, the formerly active version becomes the previous version and
the former previous version is deleted.
Pending A new or modified configuration that has been pushed to the production environment for testing
(without affecting production workloads).
If you activate a pending version, the formerly active version that you replaced becomes the
previous version.
Previous A previous configuration in the production environment.

Item Description
If you activate a previous version, the active version becomes the previous version, and any
pending version remains the pending version.
For more information, see Working with Active, Pending, or Previous Versions.
Teradata QueryGrid Security

Root Certificate Authority
A QueryGrid Manager instance can be installed on one or more TMSs, VMs, or servers. When the first
QueryGrid Manager instance is installed, QueryGrid Manager generates a root certificate authority (CA). If
additional QueryGrid Manager instances are installed and all instances are clustered, the root CA generated
by the first QueryGrid Manager instance is used throughout the cluster.
Note:
The root CA must be registered in Viewpoint during Teradata QueryGrid installation.
The root CA signs SSL certificates for each QueryGrid Manager instance.
SSL Certificates
Each QueryGrid Manager instance generates an SSL certificate for secured communication between itself
and all other clients. Clients include:
• Additional QueryGrid Manager instances in the same cluster
• Data source nodes in a system
• Viewpoint
When a data source node is added to a system (data source) in QueryGrid, a QueryGrid Manager instance
gives the node an SSL certificate during node software installation. The SSL certificate, which is signed by
the root CA, allows the data source node to verify that it is communicating with a trusted QueryGrid Manager
instance.
All communication between the Teradata QueryGrid Manager instances and data source nodes within the
fabric use HTTPS over port 9444.
QueryGrid Manager Service Accounts

Service accounts named viewpoint and support are automatically created using default passwords when
QueryGrid Manager is initially started. Teradata strongly recommends changing the default password for
these accounts. For more information on changing passwords, see Changing a Service Account Password.

Authentication and Registration of Data Source Nodes

When a data source node is added to a system (data source) in QueryGrid, node software is installed on
the node, and a node service registers the node with a QueryGrid Manager instance. The node service
provides the following:
Item Description
UUID Acts as the node username when the node authenticates itself to a QueryGrid
Manager instance.
Time-limited access Authenticates the node before the node can be added to a system (data source)
token for the first time.
Generated password for Allows the node to authenticate itself to a QueryGrid Manager instance after the
authentication node joins a system (data source) for the first time.
IP Addresses and Hostname Verification

When the first Teradata QueryGrid Manager instance starts, the generated SSL certificate contains the IP
address for the QueryGrid Manager TMS, VM, or server, and the hostnames known to Teradata QueryGrid
Manager so that clients can perform host verification.
If the Teradata QueryGrid Manager is accessed by hostnames or IP addresses unknown to it, you can add
them to the SSL certificate by setting an aliases property, which can contain a comma-separated list of
hostnames or IP addresses. Procedures for adding aliases are included in the installation procedures in
this guide.
Communication Policies for Data Transfer within a Fabric

Connectors enable sending and receiving data to and from the data source nodes in a fabric. When
configuring Teradata QueryGrid, a communication policy can be set for the link pair associated with the
initiating connector (the connector starting the query) and the target connector (the connector receiving the
query). You can define different combinations of authentication, integrity, and encryption checks to use for
data transfer and specify which one to use for each link.
A communication policy can have one of the following security levels.
Security Level Usage
IP-based authentication, no integrity Default that specifies a minimum level of security. It is

check, no encryption recommended for use only in highly trusted environments.
IP-based authentication, checksum Provides more security than the previous level, but is still
integrity check, no encryption recommended for use only in a trusted environment.
Key-based authentication, secure Provides more security than the previous level and is
integrity check, encryption credentials recommended in non-trusted environments.
Key-based authentication, secure Provides the highest level of security and is recommended in non-
integrity check, encrypt all data trusted environments. The following encryption and integrity

Security Level Usage
algorithms are available: AES-CRC32, AES-GCM (default), AES-

SHA256, or AES-SHA512.
OS Users
Security also depends on the OS user the connector software runs as. You can specify the OS user for
each connector. The user is typically the same user under which the data source runs.
Data Source User
Teradata Database teradata user
Presto presto user
Hive user executing the query (which may be hive), yarn user, and Kerberos principal or
other authorized user
Spark SQL user executing the query (which may be hive), yarn user, and Kerberos principal or
other authorized user
LDAP and Kerberos

Supported security mechanisms for a target connector (connector for the data source being queried), are
different for Teradata Database, Presto, and Hive connectors. For information about security mechanisms
specific to a data source, see the appropriate connector security sections.
General Security Guidelines for Teradata QueryGrid

The following guidelines represent best practices for maintaining security for Teradata QueryGrid.
• Change Teradata QueryGrid Manager service account default passwords during installation.
Procedures are provided in this guide.
• Set appropriate permissions in Viewpoint to limit the users who can edit the Teradata QueryGrid
configuration.
• Create links using only initiator data sources running in secure environments.
• Use the security option appropriate to the environment when specifying communication policies for
links.
Teradata QueryGrid 1.0x and 2.0x Connectors

Teradata QueryGrid 2.0x connectors are installed, configured, and monitored using the QueryGrid portlet
in Viewpoint.
• QueryGrid 1.0x connectors and QueryGrid 2.0x connectors can coexist on the same system (data
source). Queries with 1.0x connectors and 2.0x connectors can run in parallel.
• In a QueryGrid 2.0x fabric, 1.0x connectors cannot be used.

Note:
For information about migrating Teradata Database 1.0x foreign server definitions for use with 2.0x
Teradata connectors, see Migrating 1.0x Teradata Foreign Server Definitions to 2.0x Teradata
Connectors.
Teradata QueryGrid in the Teradata Public Cloud

Teradata QueryGrid can be deployed in the Teradata public cloud.
For Teradata QueryGrid Manager deployment procedures, see the following:
• Teradata® Software for AWS Installation and Administration Guide, B035-2800

• Teradata® Software for Azure Installation and Administration Guide, B035-2810
For Teradata QueryGrid installation and configuration procedures, use this guide.

I
Preparing for Software
Installation
2
Preparing for Installation
Prerequisites
The following minimum requirements must exist before installing Teradata QueryGrid and one or more of
the following licensed connectors:
• Teradata connector for Teradata Database
• Hive connector for CDH and HDP
• Presto connector for Presto, CDH, or HDP
• Spark SQL connector for CDH and HDP
• Oracle connector for Oracle Database
Note:
For more information, log in to https://access.teradata.com and search for KCS001621.
Requirements
Component Requirements
System (Data For supported database and operating system versions, refer to the compatibility matrix.
Source) For more information, log in to https://access.teradata.com and search for KCS001621.
Note:
For the Hive connector, Hive Client must be installed on all driver nodes in the system.
Note:
For QueryGrid versions 2.06 and later, /var/opt/teradata/tdqg/tmp must be
mounted with exec privileges.
Note:
For the Oracle target connector requirements, see Completing the Oracle Connector
Configuration.
Teradata Viewpoint 16.10, 16.20 and later. The QueryGrid portlet package must be installed on
Viewpoint the Viewpoint server.
The Viewpoint 16.10 edition must support multiple-system monitoring. QueryGrid 2.0x
cannot be configured on Viewpoint editions that support only single-system monitoring.
Kerberos For environments secured with Kerberos, the most current version of Kerberos available.
Java The latest version of Java 8 on the driver node or nodes in an initiating system (data
source). A driver node invokes the connector method (for example, Teradata Database)
used for a query on a target system (data source).
To locate Java, the following environment variables are checked (in order): TDWDOG_
JAVA_HOME, OPENJDK_JDK8_64_HOME, OPENJDK_JRE8_64_HOME, JDK8_64_
HOME, JRE8_64_HOME.

2: Preparing for Installation
Component Requirements
If all of the variables are empty, then the which java command is used to find the Java
path. If Java is not part of the path, you can specify it by using the system property
driverJavaPath and the system-properties.sh script in the QueryGrid Manager bin
directory /opt/teradata/tdqgm/bin. You must run the script as root or as the tdqgm
user. This path includes the Java executable. For example, if Java is located in /usr/
currentJava/bin/ then the path is driverJavaPath=/usr/currentJava/bin/java.
TMS, Server, One or more (separate server for each QueryGrid Manager instance).
or VM for
Important:
QueryGrid
Manager Do not install QueryGrid Manager on existing TMS servers hosting Viewpoint, Data
Mover, Ecosystem Manager, and so forth, unless those products are uninstalled and the
server is re-purposed to be a QueryGrid Manager server.
• Hardware requirements (minimum):
◦ 2 CPUs
◦ 16 GB RAM
◦ 250 GB hard disk space available at /var/opt/teradata/tdqgm
• Operating system:
◦ SLES 11 or 12
◦ Red Hat 6 or 7
• The latest version of Java 8 on any TMS, server, or VM on which Teradata QueryGrid
Manager is being installed.
See QueryGrid Manager planning section below.
Network Network connectivity between the Teradata nodes and Hadoop master node, and all
Hadoop data nodes, through customer LAN, BYNET, or InfiniBand.
Number of QueryGrid Manager Instances

For each Data Center, determine the number of QueryGrid Managers needed. One instance of QueryGrid
Manager is installed on one TMS or customer-supplied server, or VM.
Use the following guidelines. The guidelines are based on the minimum hardware requirements for the
TMS, server, or VM.
Per Data Center Description
Minimum number of QueryGrid One instance for approximately every 200 Teradata QueryGrid-
Manager instances connected nodes
• This approximation is based on moderate query volume on minimum
supported hardware requirements.
• Actual required number varies depending on server specs and query
volume.
• New QueryGrid managers can be added if load is high on existing
instances to reduce overall load.
Minimum number of QueryGrid Two instances

Manager instances for high • More than two instances can be deployed.
availability (HA)

Per Data Center Description
• Multiple instances can be clustered for high availability and

scalability.
• Each instance in a cluster is fully active and maintains a full copy of
the QueryGrid configuration.
Number of QueryGrid Manager At least one per Data Center, more if the number of nodes in the Data
instances to keep Center exceed the resource requirements of the single QueryGrid
communication, heartbeats, Manager instance
query metrics, and log data local
to a Data Center
Port Availability
Make sure that network ports are open between QueryGrid-attached systems (data sources) and
QueryGrid Manager. Systems include the Teradata Database nodes, Hadoop master node, all Hadoop
data nodes, and Presto nodes.
The following illustration shows the port numbers used between QueryGrid-attached systems and
QueryGrid Manager in a fabric.
Port Description
22 • One-way connection from Teradata QueryGrid Manager to all QueryGrid-attached nodes;

used if performing automatic installation of packages.
• One-way connection from Teradata QueryGrid Manager to another Teradata QueryGrid
Manager; used during cluster creation when using the SSH method.

Port Description
1025 One-way connection from the target Teradata connector (driver) to the target Teradata
Database systems (JDBC connection).
5000-5001 Two-way connections between all QueryGrid-attached nodes; other available ports can be
used, but ports 5000-5001 are recommended.
7000-7001 Two-way connections between clustered Teradata QueryGrid Managers.
8080 One-way connection from the target Presto connector (driver) to the target Presto coordinator.
8443 One-way connection from the target Hive connector (driver) to the Apache Knox Gateway if
Apache Knox Gateway is enabled on Hadoop nodes.
9300-9303 Two-way connections between clustered Teradata QueryGrid Managers.
9443 • One-way HTTPS connection from Viewpoint or a browser to Teradata QueryGrid Manager.
• One-way connection from Teradata QueryGrid Manager to another Teradata QueryGrid
Manager; used during cluster creation when using the join token method.
9444 One-way HTTPS connection from QueryGrid-attached nodes to Teradata QueryGrid

Manager.
9445 Two-way HTTPS connection between clustered Teradata QueryGrid Managers in a fabric.
10000 One-way connection between the target Hive connector (driver) to target Hiveserver 2.
10016 One-way connection from the target Spark SQL connector (driver) to the target Spark Thrift
Server.
QueryGrid Installation Workflow

Pre-Installation
Task Required Information
Perform required software upgrades See Prerequisites.
Open a Change Control See Obtaining a Change Control Number.
Download QueryGrid packages See Downloading Required Packages.
QueryGrid Manager Installation and Configuration

The following table shows the workflow for installing and configuring QueryGrid Manager. The procedures
are covered in this guide.
For the Data Center, identify the number of QueryGrid –

Manager instances needed

Install the QueryGrid Manager instances, one instance QueryGrid Manager TMS or server login (either
per TMS, server, or VM root or user with sudo privileges)
Cluster the QueryGrid Manager instances, if applicable –
In Viewpoint, configure QueryGrid Manager From the customer, obtain Viewpoint logon
credentials of a user in the Administrator role.
QueryGrid Installation and Configuration Using the QueryGrid Portlet

The following table shows the basic workflow for installing and configuring QueryGrid in the QueryGrid
portlet. Additional configuration is available for networks, communication policies, and user mappings. The
procedures are covered in this guide.
Upload QueryGrid –-
node, fabric, and
connector software
Add a Data Center to Use a logical name for the Data Center where systems (data sources) are located.
QueryGrid
Add a data source Use a logical name for the system

system Specify the max memory per node resource limit (how much memory you should
reserve on each node in the system for QueryGrid operations).
Add data source You must have root or sudo privileges for all data source nodes in the system.
nodes to the system You must manually enter the IP addresses or hostnames of the following nodes:
• Teradata Database system
• Presto system
For a Hadoop system, you can do one of the following:
• Manually enter the IP addresses or hostnames of the nodes
• Automatically auto-populate the node list if the system is monitored by
Viewpoint
Note:
Before adding data source nodes to the system, Hive Client must be installed
on all the driver nodes in the Hadoop cluster.
Add a bridge system You must have root or sudo privileges for all nodes to be added to the system.
[optional] You can use existing data source nodes in a bridge system, or non-data source
nodes. If using non-data source nodes, you will need the IP addresses or
hostnames of the nodes.
Add a fabric Use a logical name for the fabric.
Add a connector Use a logical name for the connector.
Add a link Use a logical name for the link.

Obtaining a Change Control Number

1. Open an incident through Teradata Support at https://access.teradata.com to obtain a Teradata
Change Control Number.
Change Control Numbers must be obtained at least 28 days prior to the installation or upgrade date.
2. Record the Change Control Number for future use.
Downloading Required Packages

Major and minor version numbers of all packages must match, with the exception of Teradata QueryGrid
Manager. Run the latest version of Teradata QueryGrid Manager, which is backwards compatible with prior
releases of QueryGrid and Viewpoint. Packages of different major and minor version numbers are
incompatible.
1. Log on to https://access.teradata.com.
2. Navigate to TaYS.
3. Click Software Downloads.
4. Click Database and Applications tab and do the following:
a. Click Enterprise Applications tab.
b. From Sub Category list, select QueryGrid 2.0.
c. From Release list, select the applicable release.
d. Select Site ID.
e. Select Change Control Number.
f. Click Submit.
g. Select the packages to be downloaded.
5. At the top of the page, in Teradata FTP/SFTP, enter the FTP directory Name.
6. Click Download Selected or Download All.
7. In the Download window, follow the instructions for accessing the software from the FTP/SFTP
location.
Software Packages
Component Package
Manager tdqg-manager-version.rpm
Note:
Download the Manager package to the server on which you are operating the
Teradata QueryGrid Manager.
Download the remaining packages to a location with browser access to
Viewpoint, which is where you perform the distribution and installation of these
packages using the QueryGrid Portlet.

Component Package
Node tdqg-node-version.tar.gz
Fabric tdqg-fabric-version.tar.gz
Teradata Database tdqg-teradata-connector-version.tar.gz

connector
Presto connector tdqg-presto-connector-version.tar.gz
Hive connector tdqg-hive-connector-version.tar.gz

II
Installing and
Configuring Software
3
Installing and Configuring Teradata
QueryGrid Manager
Installing Teradata QueryGrid Manager
Install Teradata QueryGrid Manager software on one or more dedicated physical or virtual machines other
than the data source nodes of your Teradata QueryGrid environment. For system requirements, see
Prerequisites.
Note:
When you install Teradata QueryGrid Manager software on more than one machine, you can cluster
the Teradata QueryGrid Manager instances.
1. Install the latest version of Java 8 on each dedicated physical or virtual machines.
Note:
If the correct version of Java is not automatically detected, you can set the path to the Java home
directory in /etc/opt/teradata/tdqgm/setenv.sh.
For example:
export TDQGM_JAVA_HOME=/usr/java/jdk1.8.0_101
For more information, log in to https://access.teradata.com and search for KAP314E23E.
2. Download the latest Teradata QueryGrid Manager package (file name tdqg-manager-version.rpm).
3. Log on to the TMS, VM, or server.
4. From a console window, install Teradata QueryGrid Manager by typing the following:
rpm -ivh tdqg-manager-version.rpm
Installation takes approximately one minute.
5. Verify the installation.
a. Open a browser.
b. Access the Teradata QueryGrid Manager instance by typing the following:
https://<hostname>:9443
6. If you are unable to access Teradata QueryGrid Manager, do the following:
a. Review the following logs.
/var/opt/teradata/tdqgm/logs/tdqgm-boot.log
/var/opt/teradata/tdqgm/logs/tdqgm-main.log
/var/opt/teradata/tdqgm/logs/init.log
b. Fix all identified problems.

3: Installing and Configuring Teradata QueryGrid Manager
c. From the console window, restart the Teradata QueryGrid Manager by typing the following:
service tdqgm restart
7. If this is the first Teradata QueryGrid Manager instance installed, confirm that the default value for the
publicAddress is appropriate for your environment.
a. Open the /etc/opt/teradata/tdqgm/server.properties file.
b. If the default value is not appropriate, see Modifying the publicAddress, bindAddress, and
clusterAddress for a QueryGrid Manager Instance.
Note:
You can also edit the bindAddress and clusterAddress.
8. If the publicAddress is a hostname (not an IP Address) and cannot be resolved from the data source
nodes using DNS, add the QueryGrid Manager server or servers to the /etc/hosts file of each node
in the data source system.
Creating a Join Token

Generate a join token on an existing QueryGrid Manager cluster to add a new QueryGrid Manager to the
cluster instead of requiring SSH credentials. A join token is necessary to create clusters in environments
where standard SSH connectivity is disabled or not available.
1. Log on to one of the existing Teradata QueryGrid Manager TMS, VM, or server instances in the cluster.
2. From the console window, run the following script as root or the tdqgm user:
/opt/teradata/tdqgm/bin/create-join-cluster-token.sh
[root@qgm1 ~]# /opt/teradata/tdqgm/bin/create-join-cluster-token.sh
Starting create-join-cluster-token command, just a moment...
Join cluster token created, it expires in 24 hours. Token:
knyQebO0W+PI1LGVrEZAUzSMi58aRZ5oFDuMhB9uaZqD/
5IochpacvY1Pl9A3xkEHWrtb7hjSqSjARI0CfQdUQ==
3. Copy the token output and use it as input to the join-cluster command that is run from the QueryGrid
Manager instance being added to the cluster.
The generated token is only good for 24 hours.
Clustering Deployed QueryGrid Manager Instances

If applicable in your environment, you can cluster Teradata QueryGrid Manager instances.
1. Log on to the Teradata QueryGrid Manager TMS, VM, or server to include in a cluster.
2. From a console window, run the join-cluster script as root or the tdqgm user:
/opt/teradata/tdqgm/bin/join-cluster.sh
3. Select a join method.

Join Method
-----------
1. SSH - Provide SSH credentials to access cluster seed files
2. Token - Provide token to access cluster seed files using QGM web service
Select join method [1-2]:

4. Enter the hostname of an existing QueryGrid Manager instance to join; if using the token join method,
specify the hostname of the QueryGrid Manger instance where the create-join-cluster-token
script was run.
5. Depending on the join method selected, enter one of the following:
Option Description
SSH Specify the login credentials for a user granted read permission to /etc/opt/teradata/
tdqgm on that instance.
Token Enter the token generated by the create-join-cluster-token script on one of the other
QueryGrid Manager instances.
6. Enter the Data Center for this instance.
Note:
By default, data source nodes communicate with QueryGrid Managers in the same datacenter.
7. Enter y at the prompt to continue with the clustering process.

All the data on the instance that the cluster command is run from is replaced with the data from the
first Teradata QueryGrid Manager instance, or the existing cluster, being joined.
Default publicAddress, bindAddress, and

clusterAddress Overview
Each Teradata QueryGrid Manager instance has a default publicAddress, bindAddress, and
clusterAddress. Data source nodes, other Teradata QueryGrid Manager instances (if installed), and the
fabric use these addresses to access a specific Teradata QueryGrid Manager instance.
When the first Teradata QueryGrid Manager instance starts up, it:
• Looks up the fully qualified domain name (FQDN) or hostname for the TMS, VM, or server to use as
the default publicAddress.
The publicAddress is the address that all data source (QueryGrid-attached) nodes use to access
• Resolves the publicAddress to an IP address used as its clusterAddress and bindAddress.
◦ The clusterAddress is the IP address that other Teradata QueryGrid Managers in the cluster
use to access a specific QueryGrid Manager.

◦ The bindAddress is a locally bound IP address to which Teradata QueryGrid Manager internal
services bind.
Modifying the publicAddress, bindAddress, and clusterAddress

for a QueryGrid Manager Instance
Changing the publicAddress, clusterAddress, and bindAddress defaults is optional. You can change
the default clusterAddress before or after clustering.
You can set or modify each of these values independently in /etc/opt/teradata/tdqgm/
server.properties.
1. Log on to the Teradata QueryGrid Manager TMS, VM, or server.
2. Open the /etc/opt/teradata/tdqgm/server.properties file.
Note:
You must have write permission to the files in /etc/opt/teradata/tdqgm.
3. Edit the publicAddress, bindAddress, and clusterAddress properties and save the file.
4. At the command line, restart Teradata QueryGrid Manager by typing the following.
Note:
If there are problems, review the /opt/teradata/tdqgm/logs/tdqgm-boot.log log file, fix
all identified problems, and restart Teradata QueryGrid Manager.
Adding Aliases for Other Servers

If you want Teradata QueryGrid Manager to be accessed by hostnames or IP addresses unknown to it
(hostnames and IP address not in the SSL certificate generated when the first QueryGrid Manager starts
up), you can add them to the SSL certificate so host verification can be performed.
1. Log on to the Teradata QueryGrid Manager TMS, VM, or server.
2. Open the /etc/opt/teradata/tdqgm/server.properties file.
Note:
You must have write permission to the files in /etc/opt/teradata/tdqgm.
3. Set an aliases property.

a. Add the aliases property.
b. Add a hostname or IP address.
The aliases property can contain a comma separated list of hostnames or IP addresses. For
example:

aliases=qgm1.teradata.com,qgm2.teradata.com
4. Save the file.
5. At the command line, restart Teradata QueryGrid Manager by typing the following:

4
Setting Up Teradata QueryGrid in the
Viewpoint Administration Portlets
Installing a QueryGrid Root Certificate
1. From the Teradata Viewpoint portal page, click .
2. Open the Certificates portlet.
3. From the Setup list, click Certificate Authority.
4. Click Install Certificate.
5. Type an alias for the certificate, up to 30 characters.
6. Select the A trusted SSL-enabled service option and do the following:
a. Type the hostname of a Teradata QueryGrid Manager instance. If clustered, pick any hostname.
b. Type 9443 as the port number.
7. Click Install.
The alias, expiration date, and authority of the new certificate appears under Trusted Certificate
Authorities in the Certificate Authority view.
Adding QueryGrid
Viewpoint provides a user interface to configure and monitor QueryGrid. When adding QueryGrid to
Viewpoint, only one QueryGrid Manager from a QueryGrid Manager cluster needs to be specified.
Viewpoint automatically discovers and performs failover to the other QueryGrid Managers in the cluster,
if the host manager goes offline. Teradata recommends to enter the QueryGrid Manager host that is
geographically the closest to the active Viewpoint server.
2. Open the Monitored Systems portlet.
3. Click next to Systems and select Add QueryGrid.
4. Under General System Details, enter a system nickname, up to 8 characters.
5. [Optional] Select the Enable system check box.
After it is enabled, the system starts collecting data.
6. Enter the host ID of the Teradata QueryGrid Manager closest to the Viewpoint server.
The host ID is the IP address of Teradata QueryGrid.
7. Under Login, do the following:
a. In Name, type viewpoint.
b. In Password, type teradata.
8. [Optional] Click Test to verify that the login settings are correct.
If the operation is successful, appears. If the operation fails, appears. If you receive an error,
verify that the login credentials are valid and the host can be reached.

4: Setting Up Teradata QueryGrid in the Viewpoint Administration Portlets
9. [Optional] Under Collectors, select the check box to activate QueryGrid data collectors so they can
collect data.
The data collectors can be enabled and configured individually in Data Collectors.
10. Click Apply.
If the operation is successful, appears. If the operation fails, appears. If you receive an error,
verify that the settings are correct and try again.
Adding a Role
You can add a role and configure the settings for users assigned to the role.
2. Open the Roles Manager portlet.
3. From the Roles Manager view, click Add Role.
4. Enter a name for the role, up to 25 characters.
You can use spaces, alphanumeric characters, and underscores (_).
5. [Optional] Select Enable role to activate the role for use in Teradata Viewpoint.
6. Enter a description, up to 255 characters.
7. Click Apply.
8. Specify additional role settings on each of the tabs.
Tabs Description
Systems Enable or disable the systems available to the role and select the metrics to display for
each system
Portlets Enable or disable portlets for a role, select permissions, and configure default settings
for each portlet.
Control whether users in this role can modify their own settings and share customized
versions of the portlet with other users, and configure which portlet features the role
can access.
Note:
Portlets must also be enabled in Portlet Library.
Web Enable or disable access to each web service for this role and select permissions.
Services
Users Specify users that are assigned to the role.
9. Click Apply.

5
Configuring Teradata QueryGrid in the
QueryGrid Portlet
Adding the QueryGrid Portlet to the Viewpoint Portal
1. In the portal, click Add Content.
2. Locate and click the QueryGrid portlet.
3. Click Add.
The portlet is added to the current page.
Changing a Service Account Password

The support and viewpoint accounts are automatically created when you add Teradata QueryGrid as a
monitored system:
• The support account is a user account used by customer support personnel.
• The viewpoint account is a service account used by Viewpoint to access Teradata QueryGrid.
Note:
Teradata strongly recommends changing the default passwords for these accounts.
1. Under Fabric Components, select Managers.

2. Click the Service Accounts tab and do the following for the support and viewpoint accounts:
a. Click next to each account and click Edit.
b. In Password, type a new password.
c. In Confirm Password, type the new password again.
d. Click Save.
Updating the Teradata QueryGrid Manager Password in

the Monitored Systems Portlet
The viewpoint account password set on the Service Account tab in the QueryGrid portlet must match
the viewpoint password set for the Teradata QueryGrid Manager in the Monitored Systems portlet.
2. Open the Monitored Systems portlet.
3. From the Systems list, click the name of the system you want to update.
4. From the Setup list, click General.
5. Under Login, type the Viewpoint password associated with the Viewpoint account in the QueryGrid
portlet.

5: Configuring Teradata QueryGrid in the QueryGrid Portlet
6. Click Apply.
Uploading Connector Software

Upload connector software when installing QueryGrid or when a new version of the connector software
becomes available.
1. Under Fabric Components, select Software and click the Connector Software tab.
2. Click next to Connector Software.
3. Browse to select the connector software.
4. Click Upload.
5. Click OK after the software has been successfully uploaded.
Uploading Fabric Software

Upload fabric software when installing QueryGrid or when a new version of the fabric software becomes
available.
1. Under Fabric Components, select Software and click the Fabric Software tab.
2. Click next to Fabric Software.
3. Browse to select a fabric software.
4. Click Upload.
Uploading Node Software

Upload node software when installing QueryGrid or when a new version of the node software becomes
available.
1. Under Fabric Components, select Software and click the Node Software tab.
2. Click next to Node Software.
3. Browse to select the node software.
4. Click Upload.
Adding a Data Center

When you install the Teradata QueryGrid Manager, a default data center is created based on the hostname
TMS, server, or VM. You can rename the default or create a new one.
1. Under Fabric Components, select Data Centers.
2. Click next to Data Centers.
3. Type a name, up to 256 characters.
4. Type a description, up to 1,000 characters.

5. Click Save.
Adding a Data Source System

1. Under Fabric Components, select Systems.
2. Click next to Systems.
Note:
Do not select Bridge only system.

5. From the Data center list, do one of the following:
• Select the data center where this system is located.
• If the data center where this system is located is not in the list, click to add the data center.
6. From the Node software list, do one of the following:
• Select the version of the node software that runs on this system.
• If the version of the node software that runs on this system is not in the list, click to upload the
software version file.
7. Under Resource Allocation, to set the maximum amount of memory needed to support applicable
concurrent queries, do one of the following:
Option Description
Max a. In the box, add the maximum amount of memory needed.

memory
Note:
per node
Depending on the available memory on the nodes certain settings might need to be
tuned (for example, FSG Cache) to make sure memory is available for QueryGrid.
Estimate Use the Estimate tool to help you estimate the amount of memory you need.
a. Click Estimate.
b. In Max query concurrency, enter the maximum number of QueryGrid queries
expected to run concurrently for all connectors on the system.
c. In Max link buffer size, do the following:
• Enter the size of the buffers for the communication channels.
• Select the unit of measurement.
Valid values range from 1 to 999. The default is 1 MB.
d. In Max link buffer count, enter the maximum number of buffers that any link or
connector is configured to use per communication channel.
Valid values range from 1 to 999. The default value is 4.
e. In Max workers per node, enter the number of threads that participate in a query on
a given node.
For example, enter the number of AMPs per node on the Teradata Database system.
For more information, refer to KCS008587.
f. Click Set Value.

Option Description
The value that appears in the Max memory per node box is calculated from the values
you entered in the tool.
8. Click Save.
Add Data Source Nodes to a System

When you add the following data source nodes to a system in QueryGrid, you must manually enter their
IP addresses or host names in QueryGrid:
Note:
Data source nodes include TPA, PE, and HSN nodes.
• Presto
When you add Hadoop data source nodes to a system in QueryGrid for the Hive Client connector or Spark
SQL connector, you can do one of the following:
• Manually enter the IP addresses or host names of the nodes in QueryGrid
• Automatically auto-populate the node list if the system is monitored by Viewpoint
Note:
Hive Client is required for running diagnostics and QueryGrid queries. Before adding data source
nodes to the system, install Hive Client on all driver nodes in the Hadoop cluster.
If the QueryGrid Manager publicAddress is not an IP address, or if its host name cannot be resolved
through DNS, before adding data source nodes, verify that the host name or IP address of the QueryGrid
Manager server or servers (if using clustering) have been added to the host files of the nodes in the data
source system.
Adding Nodes Automatically

2. Select the system you want to add nodes to.
3. On the Nodes tab, click next to Nodes.
4. Click Auto Install: Perform the install of the tdqg-node package and the auto-generated
configuration file across all nodes using SSH.
5. Do one of the following to select the nodes on which to install the tdqg-node software:

Option Description
Associated a. Select a system from the list.

Viewpoint system The Nodes box is auto-populated with the names of the nodes that are
available in the system you selected.
Nodes box a. Enter the IP addresses or host names of the nodes.
6. In the Install concurrency box, type an integer to set the number of nodes that can install
simultaneously.
7. In the SSH user box, type the name of the SSH user.
The SSH user should have sudo privilege to install the rpm file.
8. Under Authentication Mechanism, select the authentication mechanism you normally use to log
onto the nodes when using SSH and enter the corresponding value:
• Password
• SSH Key
9. Click Save.
10. [Optional] You can click Abort in Node Installation Status.
Adding Nodes Manually

4. Click Manual Install: Download the auto-generated configuration file that needs to be saved
on each node to complete the install.
5. Select the number of days from the Access token will expire after before the access token (in the
generated file) expires.
The access token is the number of days that registration with the system remains open. Any installs
completed after that time are not added to the system. The default is 7 days.
6. Click Generate File.
A link to the configuration file appears.
7. Click .
8. Save the file to a location.
9. Click Close.
10. For each node in the system, do the following:
a. Install the tdqg-node-release.rpm software package.
b. Copy the generated configuration file to /etc/opt/teradata/tdqg/node/tdqg-node.json.

Configuring Virtual IP Addresses

If your system is configured with Network Address Translation (NAT), each node has one or more unique
virtual IP addresses associated with it. You can use the virtual IP addresses of a node to communicate
with Teradata QueryGrid target systems that are on a public network.
To use virtual IP addresses, each NAT-configured node that runs Teradata QueryGrid node software must
have a text file containing its virtual IP addresses.
Note:
You can use virtual IP addresses on data source nodes, bridge nodes, or both. However, to reduce
the number of virtual IP addresses that need to be configured, Teradata recommends using virtual
IP addresses only on bridge nodes.
1. On each node in your system, log on and go to the following directory:

/etc/opt/teradata/tdqg/node
2. In the directory, create a text file called virtual_ips.
3. Using one virtual IP address per line, populate the text file with the virtual IP addresses of the node.
The virtual IP addresses must be valid IPV4 or IPV6 addresses. The file should look similar to the
following:
fe80::250:56ff:fea5:67d9
10.20.255.100
10.20.255.101
10.20.255.102
4. Save the file.
5. Restart the node by typing the following:
service tdqg-node restart
During QueryGrid operations, the IP addresses in each line of the file are read, validated, and used
as virtual IP addresses. If the file does not exist in the /etc/opt/teradata/tdqg/node directory, a
file not present message is logged in /var/opt/teradata/tdqg/node/<version>/logs/
tdqgnode-boot-<version>.log.
Adding a Dedicated Bridge System

A dedicated bridge system contains a set of nodes that act as routers for data movement and can perform
CPU-intensive operations such as compression or encryption. A dedicated bridge system does not contain
data source nodes.
2. Click next to Systems.
4. Select the Bridge only system check box.


6. From the Data center list, do one of the following:
• Select the data center where this system is located.
• If the data center where this system is located is not in the list, click to add the data center.
7. From the Node software list, do one of the following:
• Select the version of the node software that runs on this system.
• If the version of the node software that runs on this system is not in the list, click to upload the
software version file.
8. Under Resource Allocation, to set the maximum amount of memory needed to support applicable
concurrent queries, do one of the following:
Option Description
Max a. In the box, add the maximum amount of memory needed.

memory
Note:
per node
Depending on the available memory on the nodes, certain settings might need to be
tuned (for example, FSG Cache) to make sure memory is available for QueryGrid.
Estimate Use the Estimate tool to help you estimate the amount of memory you need.
a. Click Estimate.
b. In Max query concurrency, enter the maximum number of QueryGrid queries
expected to run concurrently for all connectors on the system.
c. In Max link buffer size, do the following:
• Enter the size of the buffers for the communication channels.
• Select the unit of measurement.
Valid values range from 1 to 999. The default is 1 MB.
d. In Max link buffer count, enter the maximum number of buffers that any link or
connector is configured to use per communication channel.
e. In Max workers per node, enter the number of threads that participate in a query on
a given node.
For example, enter the number of AMPs per node on the Teradata Database system.
For more information, refer to KCS008587.
f. Click Set Value.
The value that appears in the Max memory per node box is calculated from the values
you entered in the tool.
9. Click Save.
The dedicated bridge system is listed under Fabric Components, in Bridges, but you must add non-
data-source nodes to it.
Add Non-Data Source Nodes to a Dedicated Bridge

System
A dedicated bridge system contains non-data-source nodes, such as edge nodes.

Adding Nodes Automatically

4. Click Auto Install: Perform the install of the tdqg-node package and the auto-generated
configuration file across all nodes using SSH.
5. Do one of the following to select the nodes on which to install the tdqg-node software:
Option Description
Associated a. Select a system from the list.

Viewpoint system The Nodes box is auto-populated with the names of the nodes that are
available in the system you selected.
Nodes box a. Enter the IP addresses or host names of the nodes.
6. In the Install concurrency box, type an integer to set the number of nodes that can install
simultaneously.
7. In the SSH user box, type the name of the SSH user.
The SSH user should have sudo privilege to install the rpm file.
8. Under Authentication Mechanism, select the authentication mechanism you normally use to log
onto the nodes when using SSH and enter the corresponding value:
• Password
• SSH Key
9. Click Save.
10. [Optional] You can click Abort in Node Installation Status.
Adding Nodes Manually

4. Click Manual Install: Download the auto-generated configuration file that needs to be saved
on each node to complete the install.
5. Select the number of days from the Access token will expire after before the access token (in the
generated file) expires.
The access token is the number of days that registration with the system remains open. Any installs
completed after that time are not added to the system. The default is 7 days.
6. Click Generate File.
A link to the configuration file appears.

7. Click .
8. Save the file to a location.
9. Click Close.
10. For each node in the system, do the following:
a. Install the tdqg-node-release.rpm software package.
b. Copy the generated configuration file to /etc/opt/teradata/tdqg/node/tdqg-node.json.
Configuring Virtual IP Addresses

If your system is configured with Network Address Translation (NAT), each node has one or more unique
virtual IP addresses associated with it. You can use the virtual IP addresses of a node to communicate
with Teradata QueryGrid target systems that are on a public network.
To use virtual IP addresses, each NAT-configured node that runs Teradata QueryGrid node software must
have a text file containing its virtual IP addresses.
Note:
You can use virtual IP addresses on data source nodes, bridge nodes, or both. However, to reduce
the number of virtual IP addresses that need to be configured, Teradata recommends using virtual
IP addresses only on bridge nodes.
1. On each node in your system, log on and go to the following directory:

/etc/opt/teradata/tdqg/node
2. In the directory, create a text file called virtual_ips.
3. Using one virtual IP address per line, populate the text file with the virtual IP addresses of the node.
The virtual IP addresses must be valid IPV4 or IPV6 addresses. The file should look similar to the
following:
fe80::250:56ff:fea5:67d9
10.20.255.100
10.20.255.101
10.20.255.102
4. Save the file.
5. Restart the node by typing the following:
service tdqg-node restart
During QueryGrid operations, the IP addresses in each line of the file are read, validated, and used
as virtual IP addresses. If the file does not exist in the /etc/opt/teradata/tdqg/node directory, a
file not present message is logged in /var/opt/teradata/tdqg/node/<version>/logs/
tdqgnode-boot-<version>.log.
Adding a Bridge System Using Data Source Nodes

1. Under Fabric Configuration, select Bridges.

2. Click next to Bridges.

5. From the System list, select a system that contains data source nodes.
6. Under Bridge Nodes, do one of the following to designate which data source nodes are bridge nodes:
Option Description
Use all nodes a. Click Use all nodes.
Use selected a. Click Use selected nodes.

nodes b. Click Select Nodes.
c. In the Available nodes filter box, type some text and one or more wildcards to
get a subset of the available nodes to display in the Available nodes list.
d. Click to move the nodes you want from the Available nodes list to the Selected
nodes list.
e. Click Save.
Configuring QueryGrid for a Teradata FICON Node

In some Teradata systems, FICON nodes are used as PE-only nodes with no network connectivity. To
run QueryGrid using this configuration, the following is recommended.
Note:
In this scenario, Hop 1 uses a bynet network interface as the initiating and target network; Hop 2
uses the customer LAN network.
1. Add a new QueryGrid Manager server in the Teradata network (such as bynet) that is accessible by
all TPA and HSN nodes.
2. Cluster the new server with the target QueryGrid Manager using a customer LAN network.
3. To route PE requests from the Teradata FICON node to a target system, do the following:
a. Set up a QueryGrid link as a single bridge.
b. Make sure the bridge includes all the TPA nodes that have connectivity to all target nodes.
Adding a Fabric
1. Under Fabric Configuration, select Fabrics.
2. Click next to Fabrics.
5. Type the port number in the Port box.
Valid values range from 1024 to 65535. Select a value that is not currently in use by the systems you
plan to add to the fabric.

6. Do one of the following:
Option Description
Select an existing version a. From the Fabric software list, select a version.
b. Click Save.
Upload a version a. Next to the Fabric software list, click .

b. Browse to the file and click Upload.
c. From the Fabric software list, select the uploaded version.
d. Click Save.
Adding a Connector
1. Under Fabric Configuration, select Fabrics and click a fabric to which you want to add a connector.
2. Click the Connectors tab.
3. Click the next to Connectors.
6. In the System list, select a system you want to add this connector to.
7. Next to Allowed OS users, click to add the allowed OS user that this software runs as.
This user is typically the same user under which the database runs:
• For a Teradata Database connector it is the teradata user.
• For a Presto connector it is the presto user.
• For a Hive connector, you must add the user executing the query (which may be hive), yarn user,
and Kerberos principal or other authorized user.
• For a Spark SQL connector, you must add the user executing the query (which may be hive), yarn
user, and Kerberos principal or other authorized user.
Option Description
Select an existing a. From the Software Name list, select an existing software version.
connector software The list contains the Teradata, Presto, or Hive connector software
version packages you uploaded earlier.
Upload a new a. Next to the Software Name list, click .

connector software b. Browse to the file and click Upload.
version
c. From the Software name list, select the uploaded version.
d. Click Save.
9. In the Server box, enter the hostname of the server.

10. Click next to Connector Software.

11. In Select Connector Properties, do one or more of the following:
Option Description
Customize a. Select the check box to customize the values for a connector property.
When the check box is cleared, it designates that QueryGrid should use the default
values for a property.
Note:
You can further customize initiator and target connector properties at the link level in
the Links tab.
Overridable a. [Optional] Select the check box to designate that the normal configured values for
the connector property can be overridden when a user executes queries during
individual processing sessions.
Note:
Once you designate a property as overridable at the connector level, it stays in effect
even if you do not designate it as overridable at the link level in the Links tab.
In order to disable the setting for an initiator or target connector, you must clear the
check box at both the link level and connector level.
For these reasons, it might be preferable to designate a property as overridable only at
link level in the Links tab, depending on the requirements specific to the link.
12. Click OK to save the configuration.

Under Connector Software, all properties you set to customize appear.
13. Modify each setting to govern how the connector operates.
For complete descriptions of all properties for each connector type, see:
• Teradata Connector and Link Properties
• Presto Connector and Link Properties
• Hive Connector and Link Properties
• Spark SQL Connector and Link Properties
14. Under Driver Nodes, do one of the following to designate where driver nodes are available:
Option Description
Make available on a. Click Make available on all nodes.

all nodes
Make available on a. Click Make available on selected nodes only.

selected nodes b. Click Select Nodes.
only
c. In the Available nodes filter box, type some text and one or more wildcards
to get a subset of the available nodes to display in the Available nodes list.
d. Click to move the nodes you want from the Available nodes list to the
Selected nodes list.
e. Click Save.

15. [Optional] From the Associated Viewpoint system list, select a Viewpoint system to associate with
this connector.
This association is used to link Viewpoint monitored systems to QueryGrid queries in portlets, such
as Query Monitor.
16. Click Save.
Adding a Network
1. Under Fabric Components, select Networks.
2. Click next to Networks.
5. In the Matching rules list, select one of the following:
Option Description
CIDR notation a. Type the Classless Inter-Domain Routing (CIDR) designation for the physical
network interface.
You can enter up to 500 characters.
Interface Name a. Type the interface name.
6. [Optional] Click next to Matching rules to add more rules.

7. You can click to remove an existing rule.
8. Click Save.
Adding a Communication Policy

1. Under Fabric Components, select Communication Policies.
2. Click next to Communication Policies.
5. Type an integer from 1 and 5 to set the number of data transfer streams that can run simultaneously.
The default value is 1.
6. [Optional] Select Enable compression for data transfer to allow ZStandard data compression on
row blocks during data transfer.
7. Select the combination of authentication, integrity and encryption checks you want to use.
Option Description
IP-based authentication, no integrity

check, no encryption
IP-based authentication, checksum a. Select the extent of the integrity checks to be run.
integrity check, no encryption

Option Description
Key-based authentication, secure a. Select the extent of the integrity checks to be run.
integrity check, encrypt credentials b. Select the size of the authentication key.
By default, QueryGrid uses a 2048-bit authentication key.
c. Select the size of the encryption key.
By default, QueryGrid uses a 2048-bit encryption key.
d. Select the encryption/integrity algorithm.
By default, QueryGrid uses AES-GCM.
Key-based authentication, secure a. Select the extent of the integrity checks to be run.
integrity check, encrypt all data b. Select the size of the authentication key.
By default, QueryGrid uses a 2048-bit authentication key.
c. Select the size of the encryption key.
By default, QueryGrid uses a 2048-bit encryption key.
d. Select the encryption/integrity algorithm.
By default, QueryGrid uses AES-GCM.
8. Click Save.
Adding a User Mapping

1. Under Fabric Components, select User and Role Mappings.
2. Click next to User and Role Mappings.
5. Click Save.
6. In the list of user mappings, select the mapping you just added.
7. On the Users tab, click next to Users.
8. Type the name of the user on the initiating system.
You can map multiple users to single remote user; however, you can only use an initiating user once.
9. Type the name of the user on the target system you want to map to.
10. Click Save.
Adding a Role Mapping

1. Under Fabric Components, select User and Role Mappings.
2. Click next to User and Role Mapping.
5. Click Save.
6. In the list of role mappings, select the mapping you just added.

7. On the Roles tab, click next to Roles.

8. Type the name of the role on the initiating system.
You can map multiple roles to single remote role; however, you can only use an initiating role once.
9. Type the name of the role on the target system you want to map to.
10. Click Save.
Adding a Link
1. Under Fabric Configuration, select Fabrics and click a fabric to which you want to add a link.
2. Click the Links tab.
3. Click next to Links.
6. From Bridge configuration, select one of the following:
Option Description
No bridges A bridge is not used for this link. The hop is between the initiator and target.
Single A single bridge is used for this link. A query is sent from the initiator to the bridge (Hop
bridge 1), and from the bridge to the target (Hop 2). A query is returned in the reverse order.
Dual bridge A dual bridge is used for this link. A query is sent from the initiator to bridge 1 (Hop 1),
from bridge 1 to bridge 2 (Hop 2), and from bridge 2 to the target (Hop 3). The query is
returned in the reverse order.
7. From Initiating Connector, do the following:

a. In the Connector name list, select an initiating connector that sends the queries.
b. In the Threads per query box, type a number for the number of query tasks to be used during
data transfer at the initiating system.
The default is 1. Supported values are 1 to 5.
8. Click next to Initiating Connector.
9. In Select Initiating Connector Properties, do one or more of the following:
Option Description
Customize a. Select the check box to customize the values for an initiating connector property.
When the check box is cleared, it designates that QueryGrid should use the default
values for a property
Overridable a. [Optional] Select the check box to designate that the normal configured values for
the initiator connector property can be overridden when a user executes queries
during individual processing sessions.
Once you select the check box, it cannot be cleared.

Option Description
Note:
Once you designate a property as overridable at the connector level (on the
Connectors tab), it stays in effect even if you do not designate it as overridable at
the link level.
In order to disable the setting for an initiator or target connector, you must clear the
check box at both the link level and connector level.
For these reasons, it might be preferable to designate a property as overridable only
at link level, depending on the requirements specific to the link.

Under Initiating Connector, all properties you set to customize appear.
Each property is required until you clear the check box.
11. Modify each setting to govern how the initiator connector operates in this link pairing.
For complete descriptions of all properties for each connector type, see:
• Presto Connector and Link Properties
• Hive Connector and Link Properties
• Spark SQL Connector and Link Properties
12. If you selected a Single bridge or Dual bridge configuration, do the following for each bridge:
a. In the Bridge name list, select the bridge system.
data transfer at each bridge system.
13. For each hop, add an Initiating network:
Option Description
Select an a. Select an existing network from the list.

initiating
network
Add a new a. Click next to Initiating network to add the network you want this link to send
initiating queries over.
network and b. Type a name, up to 256 characters.
select it
c. Type a description, up to 1,000 characters.
d. In the Matching rules list, select one of the following:
• CIDR notation
• Interface name
e. [Optional] Click next to Matching rules to add more rules.
f. [Optional] You can click to remove an existing rule.
g. Click Save.
h. Select the network from the list you just added.

14. For each hop, add a Target network. Do similar steps performed to add an initiating network.
15. For each hop, do one of the following to add a Communication policy:
Option Description
Select a a. Select a policy from the list.

communication
policy
Add a a. Click next to Communication Policy.

communication b. Type a name, up to 256 characters.
policy and select it
c. Type a description, up to 1,000 characters.
d. Type an integer from 1 and 5 to set the number of data transfer streams that
can run simultaneously.
The default value is 1.
e. Select the combination of authentication, integrity and encryption checks
you want to use. The choices appear in order of increasing security level,
with the choice that provides the greatest level of security listed last. Fill in
values, if requested. For more information, see Adding a Communication
Policy.
f. Click Save.
g. Select the policy you just added for Communication policy.
16. From Target Connector, do the following:

a. In the Connector name list, select a target connector to receive queries from.
data transfer at the target system.
17. Click next to Target Connector.
18. In Select Target Connector Properties, follow the same process as noted for the Initiating
Connector.
Under Target Connector, all properties you selected to customize appear.
20. Modify each setting to govern how the target connector operates in this link pairing.
21. [Optional] Select a User mapping to use over this link.
User mapping enables a specific user on an initiating system to submit queries as a specific user on
a target system.
22. [Optional] Select Enable debug logging for initiating user if you have a query or set of queries that
are failing or not performing correctly for a particular database user for an unknown reason.
If you enable this option and have the user run the query again, detailed logging is captured by the
Use Info for debugging performance issues and Debug for debugging incorrect or failing behavior. A
Teradata Technical Support Specialist can then use this information to troubleshoot the issue.
23. Click Save.

Running a Connector Diagnostic Check

Run a diagnostic check on a connector to determine whether a target connector is available and can
access the target system using the specified connector properties.
2. On the Connectors tab, click next to the applicable connector and select Diagnostic Check.
3. To test the connector and the associated fabric, click one of the following:
• Active
• Pending
Any properties that are required and need to be configured appear.
4. If applicable, set the values for the connector properties.
5. Click Run.
The test results display in the Connector Diagnostic Check window.
For more information see Connector Diagnostic Check Metrics.
Running a Link Diagnostic Check

Run a link diagnostic check to test the connectivity between all the nodes of initiating and target systems,
based on the communication policy that is associated with the link. The check reports either pass or fail.
If it fails, it reports why it failed.
2. On the Links tab, click next to the applicable link and select Diagnostic Check.
3. To test the link, click one of the following:
• Active
• Pending
4. Click Run.
The test results display in the Link Diagnostic Check window.
Running a Link Bandwidth Test

Run a link bandwidth test to test the bandwidth between all the nodes of initiating and target systems,
based on the communication policy that is associated with the link. This test reports an average byte rate
between systems and helps to identify bottlenecks.
Note:
The minimum required properties for running a link bandwidth test are the port number and hostname
of the target connector.

2. On the Links tab, click next to the applicable link and select Bandwidth Test.
3. To test the link, click one of the following:

• Active
• Pending
4. Depending on the direction of the link data flow you want to test, click one of the following:
• Initiating to target
• Target to initiating
5. Set the bandwidth to use to transfer data between nodes.
The default is 100 MB.
6. Click Run.
The test results display in the Link Bandwidth Test window.
For more information, see Link Bandwidth Test Metrics.

III
Configuring and Using
Connectors
6
Using the Teradata Connector with Teradata
QueryGrid
Completing the Teradata Connector Configuration
After you add and configure a Teradata connector and link pairings in a QueryGrid fabric, you must do the
following to complete the configuration:
• Configure Teradata connectors used as initiators in link pairings
• Configure Teradata connectors used as targets in link pairings
• Test installed Teradata connectors and links that use a Teradata connector as an initiator or target
• Define security settings
Teradata Connector and Link Properties

When you create links and associated properties in the QueryGrid portlet, you are creating Configuration
Name Value Pairs (NVP). NVP does the following:
• Specifies the behavior of the target connector component
• Configures how data is transformed
• Configures the underlying link data transportation layer
• Affects how the initiator connector performs
Links are named configurations that include an initiating connector and a target connector. If the same
property is set for a link and a connector, the link setting overrides the connector setting.
Note:
Properties may be available for initiating connectors only, target connectors only, or both.
Overridable? Connector
Name Default Description
Property Name Type
Authentication Trusted Indicates the authentication mechanism used Target

Mechanism on the target data source.
Values are Trusted, TD2, Kerberos, and LDAP.
This is a required setting.
Byte Count 640K Frequency with which byte count is updated in ● Initiator,
Report DBQL. You can adjust this to a larger value if byteCountReportFrequency Target
Frequency the update frequency is too resource intensive.
Connection 30 minutes Frequency of eviction checks. Connection Target
Evict objects from the pool are checked, closed, and
Frequency removed if the idle time (current time - last time
of use) of a connection object is greater than the
Connection Max Idle Time setting.

6: Using the Teradata Connector with Teradata QueryGrid
Property Name Type
Reduce the time between checks if there are

multiple concurrent users running queries to
clear the connections more frequently.
Valid values are 1–1440 minutes.
Connection 86400 seconds The maximum idle time for the connection cache Target
Max Idle Time object, after which the object is closed and
removed from the cache. Use this property when
there are multiple concurrent users and queries
running on the system that might lead to
starvation of connection objects.
Valid values are 1–86400 seconds.
Connection 100 Maximum number of connection objects that can Target

Pool Size be stored in a connection pool. When acquiring
a new connection, the connector checks for an
available space in the pool. If no space is
available in the connection pool, the connection
fails after 5 minutes. Only one connection pool
and username per connector configuration is
allowed.
Valid values are 1–10000.
Custom Push None Teradata, Presto, or Hive custom push profile ● Initiator
Profile used with the Remote Table Optimization customPushProfile
(RTO) feature
This custom push profile overrides a default
push profile.
Default Push None Teradata, Presto, or Hive default push profile Initiator
Profile used with the Remote Table Optimization
(RTO) feature
This push profile is used if there is no custom
push profile.
Disable False When set to true, disables the pushdown of all ● Initiator
Pushdown query conditions to the target system. disablePushdown
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 target system.
To avoid incorrect results caused by condition
pushdown in situations where the settings on the
initiating system do not match the settings on the
target system, you can disable the pushdown of
all conditions to the target system.
If set to Overridable, this property can only be
overridden at the session level from false to true
(indicating you are disabling pushdown), but
cannot be changed from true to false.
Enable Async False Indicates if PDE asynchronous abort should be Initiator,

Abort enabled. Target
Enable Info Logging level for the connector or link Initiator,
Logging properties. User level log settings can be Target
explicitly set through the add or edit link page
in the QueryGrid portlet.
This setting applies to both the initiating and
target connector; however, the logging level for

Property Name Type
the initiating connector in the link takes

precedence if they are set differently.
Valid values are NONE, WARN, INFO, and
DEBUG.
Link Buffer 4 Maximum number of write buffers available on ● Initiator,

Count a single channel at one time. linkBufferCount Target
Note:
Link Buffer Count overrides the default internal
fabric property
shmDefaultNumMemoryBuffers.
Link Buffer Size 1048576 Maximum size of the write buffers to allocate for ● Initiator
row handling and message exchange. linkBufferSize
Valid values are 73728– 10485760 bytes.
Link 30000 Handshake timeout in milliseconds for the link Initiator,

Handshake channel setup. Target
Timeout Valid values are 60000–86400000.
Link Heartbeat 3600000 Maximum interval in milliseconds for the Initiator,

Interval heartbeat signal on a channel between the Target
connector and the fabric instance, used for
health check status.
Note:
This interval should be greater than Link
Handshake Timeout.
Password None User password. Target

Maximum length is 255 characters.
Port 1025 Default value for a Teradata connector is 1025. Target

Valid values are 1025–65535. The default value
can be overridden.
Read Timeout 3600000 Number of seconds to wait to read between ● Initiator,

data packets when importing data messages. readTimeout Target
Realm None Kerberos realm. Target

Replace False Replaces unsupported Unicode characters with Initiator,
Unsupported U+FFFD, when importing data by a Teradata Target
Unicode connector.
Character Note:
If you are using Unicode Pass Through
characters, do not set this property to true.
See Validate Unsupported Unicode Characters.
Response 86400000 Number of milliseconds to wait for the final data ● Initiator,
Timeout exec response when all the data has been responseTimeout Target
transferred.
Role Support False Enable user role support for the target system. ● Target
When set to true, the user role from the initiator roleSupport
or target based on role mapping is applied to

Property Name Type
the target system and any errors are returned

back to the user. When set to false, roles are
not applied to the target system.
Server None Used to connect to the target database as part Target
of the JDBC connection string. This is the IP
address or DNS name of the target host.
Temporary None Specified database name for creating ● Target
Database temporary tables/views. tempDbName
Name If you do not provide a database name in this
property, QueryGrid creates the temporary view
in the default database assigned to the user.
Teradata GSS /usr/tdbms Specifies the absolute path (gssJar) to the

JAR Path /bin/ Teradata GSS JAR file (tdgssconfig.jar) to
tdgssconfig. use for the JDBC connection of a target
jar connector.
Teradata JDBC /usr/tdbms Specifies the absolute path (jdbcJar) to the
JAR Path /bin/ Teradata JDBC JAR file (terajdbc4.jar) to
terajdbc4. use for the JDBC connection of a target
jar connector.
Username DBC Name of the user. Target
This NVP is saved in the Teradata QueryGrid
Manager configuration and is required when the
initiator does not support a mechanism to
provide user credentials. The username is also
used for connectivity diagnostic checks.
Validate False Validate unsupported Unicode character when Initiator,

Unsupported importing data by a Teradata connector. Target
Unicode Note:
Characters
If you are using Unicode Pass Through
characters, do not set this property to true.
See Replace Unsupported Unicode Character.
Write Timeout 3600000 Number of milliseconds to wait to write between ● Initiator,

data packets when exporting data messages. writeTimeout Target
Teradata Initiator Connector Tasks

If you designated a Teradata connector as an initiator connector in any link pairing (for example, a
Teradata-to-Hive link), perform the following tasks:
1. Configure the foreign server and grant privileges.
2. Install the ExecuteForeignSQL stored procedure.

Confirming the QueryGrid Functions
Before continuing with the configuration of the Teradata Initiator connector, you must confirm the
QueryGrid initiator and target functions.
1. Check for the existence of the qginitiator and qgremote functions by running the following query on
both the initiator and target (if applicable) systems.
help user td_sysfnlib;
Help information returned. 531 rows.
Total elapsed time was 1 second.
Table/View/Macro name Kind Comment
--------------------- ---- --------
...
QGEXECUTEFOREIGNQUERY L ?
QGEXECUTEFOREIGNQUERYCONTRACT C ?
QGINITIATOREXPORT L ?
QGINITIATOREXPORTCONTRACT C ?
QGINITIATORIMPORT L ?
QGINITIATORIMPORTCONTRACT C ?
QGREMOTEEXPORT L ?
QGREMOTEEXPORTCONTRACT C ?
QGREMOTEIMPORT L ?
QGREMOTEIMPORTCONTRACT C ?
...
2. If the functions do not exist, run the DIP script systems functions using the DIP utility to add these
to the database.
DIPSYSFNC - System Functions
Configuring a Foreign Server and Granting Privileges for a Teradata-to-

TargetConnector
Note:
Before you begin, the following procedure for a Teradata-to-Teradata connector whose
Authentication Mechanism is set to Trusted, verify that a proxy user exists on the target Teradata
Database system. The proxy user is the one that will be used for authentication on the target
system. See Setting Up the Proxy User for a Teradata-to-Teradata Connector when Authentication
Mechanism is Set to Trusted.
Complete the following steps on the initiator system. These apply after initial deployment and when
creating remote servers or access, but not after upgrading versions.

For Teradata connectors, External Name Value Pairs (NVP) are set in the Foreign Server definition.
• The External NVP must be set up so the QueryGrid connector can identify itself with the Teradata
QueryGrid Manager to obtain the configuration NVP.
• External NVP may be set up on Teradata to access specific features like name and role mapping,
but should be used with care to not conflict with values supplied by Teradata QueryGrid Manager.
• The External NVP are called LINK and VERSION. These are configured using SQL commands:
ALTER FOREIGN SERVER or CREATE FOREIGN SERVER. For more information, see Teradata
Connector and Link Properties.
1. Log on as an Administrator, such as dbc, to the initiating Teradata Database system, and create an
authorization object for the target server:
CREATE AUTHORIZATION td_server_db.target_server_auth AS DEFINER TRUSTED USER
'proxyuser' PASSWORD 'password';
An authorization object is created in the td_server_db database. Using the DEFINER clause makes
the authorization available globally to all users.
2. Grant the CREATE SERVER and EXECUTE FUNCTION privileges on the td_server_db database
to the Administrator user, for example:
GRANT CREATE SERVER ON td_server_db TO dbc;
GRANT EXECUTE FUNCTION ON TD_SYSFNLIB TO dbc;

3. Create the foreign server:
CREATE FOREIGN SERVER target_server_name
EXTERNAL SECURITY DEFINER TRUSTED target_server_auth
USING
LINK('linkname')
VERSION ('version')
DO IMPORT WITH TD_SYSFNLIB.QGInitiatorImport,
DO EXPORT WITH TD_SYSFNLIB.QGInitiatorExport;
For example, where sdll7100 is the initiating Teradata Database system, and sdll7151 is the target
Teradata Database system:
CREATE FOREIGN SERVER sdll7151_fs

USING
LINK('sdll7100_sdll7151')
VERSION('active')
4. From database td_server_db, grant SELECT and INSERT privileges on the target server to initiating
end users.

GRANT SELECT ON td_server_db.target_server_name to initiating_end_user;

GRANT INSERT ON td_server_db.target_server_name to initiating_end_user;
For example:
GRANT SELECT ON td_server_db.sdll7151_fs to sdll7100_user2;

GRANT INSERT ON td_server_db.sdll7151_fs to sdll7100_user2;
Completing the Teradata Initiator Connector Installation on Teradata

Database Nodes (Viewpoint 16.10)
Note:
On systems with Viewpoint 16.10, use the following procedure to complete the installation of the
Teradata connector components.
When you add a connector to a fabric, QueryGrid performs the following tasks on the Teradata Database
initiating nodes in the system:
• Creates the directories required for completing the installation
• Installs the Teradata connector package. The Teradata connector package includes a stored
procedure that provides a simple interface for executing basic SQL queries
The procedure includes the following:
• Running an installation script to unpack and distribute the Teradata connector package components
• Additional setup steps
1. Log on to a Teradata QueryGrid Manager TMS, VM, or server.
The QueryGrid Manager TMS, VM, or server can be part of a cluster.
2. Run the following script at the prompt as root or the tdqgm user:
/opt/teradata/tdqgm/bin/tdqg.sh install-connector
3. From Connectors, enter the number for the Teradata connector.
4. From Connector Version, enter the number for the Active or Pending version.
5. From Driver Nodes, enter the number of the driver node you want to use to perform the installation.
6. In Connector Properties, provide the administrator credentials, such as dbc and the password, for
the initiating Teradata Database system.
7. Enter the appropriate number for the mode the Teradata Database system is running in (TERA or
ANSI).
Note:
The mode determines how a stored procedure can be run.
The Teradata connector components are installed.

8. [Optional] Verify that the stored procedure is installed on the Teradata Database nodes.

a. Log on as an Administrator, such as DBC, of the initiating Teradata Database system.

b. Create the related foreign server.
For example:
CREATE FOREIGN SERVER target_server_name_efssp

USING
LINK('linkname')
VERSION ('version’)
DO IMPORT WITH TD_SYSFNLIB.QGExecuteForeignQuery;
c. From database td_server_db, grant the SELECT privilege on the target server to initiating end
users.
For example:
GRANT SELECT on td_server_db.target_server_name_efssp to initiating_end_user;

d. Submit the DDL or DCL query on the target system.
For example:
.logon initiating_end_user, initiating_end_user
CALL SYSLIB.ExecuteForeignSQL(‘DDL’, ‘target_server_name_efssp’);
Completing the Teradata Initiator Connector Installation on Teradata

Database Nodes (Viewpoint 16.20)
Note:
On systems with Viewpoint 16.20, use the following procedure to complete the installation of the
Teradata connector components.
When you add a connector to a fabric, QueryGrid performs the following tasks on the Teradata Database
initiating nodes in the system:
• Creates the directories required for completing the installation
• Installs the Teradata connector package. The Teradata connector package includes the following:
◦ A stored procedure that provides a simple interface for executing basic SQL queries
◦ Push profile code, associated functions, and macros that allow you to use Teradata Database
Remote Table Optimization (RTO) with QueryGrid
This procedure includes the following:
• Running an installation script to unpack and distribute the Teradata connector package components
• Additional setup steps

1. Make sure the connector package has been downloaded from Teradata's software download site
and uploaded to the QueryGrid portlet, and that the connector has been added to the fabric.
3. Click the fabric containing the Teradata Database initiating nodes.
4. Select Connectors tab.
5. Click next to the Teradata initiating connector for the Teradata Database nodes and select Install.
6. From Connector Installation, select one of the following:
• Active
• Pending
7. In the Select driver node list, select the driver node you want to use to run the installation script.
8. To allow the installation script to run, provide the Username and Password log on for an
Administrator, such as DBC, of the initiating Teradata Database system.
9. In the Transaction Mode list, select one of the following:
Note:
The mode determines how a stored procedure can be executed.
Option Description
For systems running in Teradata mode: Select TERA.
For systems running in ANSI mode: Select ANSI.
10. Click Run.

The stored procedure and RTO components are installed on all the Teradata Database nodes.
11. Verify successful installation by checking that the driver node specified in the Select driver node
list is represented in the Success field.
12. [Optional] Verify that the stored procedure is installed on the Teradata Database nodes.
a. Log on as an Administrator, such as DBC, of the initiating Teradata Database system.
b. Create the related foreign server.
For example:
CREATE FOREIGN SERVER target_server_name_efssp

USING
LINK('linkname')
VERSION ('version’)
c. From database td_server_db, grant the SELECT privilege on the target server to initiating end
users.
For example:

GRANT SELECT on td_server_db.target_server_name_efssp to initiating_end_user;

d. Submit the DDL or DCL query on the target system.
For example:
.logon initiating_end_user, initiating_end_user
CALL SYSLIB.ExecuteForeignSQL(‘DDL’, ‘target_server_name_efssp’);
Teradata Target Connector Tasks

If you designated a Teradata connector as a target connector in any link pairing (for example, a Hive-to-
Teradata link), perform the following tasks:
1. Configure the proxy user.
2. If the initiator connector is one other than Teradata (for example, Presto-to-Teradata, or Hive-to-
Teradata), set up user mapping.
Setting Up the Proxy User for a Teradata-to-Teradata Connector when

Authentication Mechanism is Set to Trusted
The proxy user:

• Usually has no perm space or permissions beyond acting as proxy
• Might require SPOOL and TEMPORARY space based the specific query workload of all users of
the target server
1. Confirm the remote proxy user exists.
2. On the remote Teradata Database system, log on as Administrator.
For example, log on as user dbc.
3. Create a unique proxy user name for each system:
CREATE USER proxyuser AS PERM = 0 PASSWORD = password;
4. Grant proxy user CONNECT privileges for all users to be impersonated:
GRANT CONNECT THROUGH proxyuser TO PERMANENT target_end_user without role;
The target_end_user is the user who has access to objects from the local system. The
target_end_user should be created with PERM > 0.
Setting Up User Mapping
1. Add a user mapping where a Presto or a Hive user is the initiating user and a Teradata user is the
target user.

For more information, see Adding a User Mapping.

2. Edit the following Presto-to-Teradata or Hive-to-Teradata link settings.
Settings Description
Target properties Configure the following Teradata user credentials:

• Username
• Password
User mapping Select the user mapping previously created.
Testing Teradata Connectors and Links

After completing the tasks required to configure Teradata initiator connectors, target connectors, and links
that use a Teradata connector as an initiator or target, do the following to test connectivity:
1. Run a connector diagnostic check to validate Teradata connectivity with a data source.
2. Run a link diagnostic check for all links that use a Teradata connector as an initiator or target.
3. Run a link bandwidth test for all links that use a Teradata connector as an initiator or target.
4. Validate the connections between data sources for all Teradata-to-TargetConnector links.
Validating a Teradata-to-TargetConnector Link
Complete these steps to verify a Teradata-to-TargetConnector link (where TargetConnector is any type
of target connector).
1. Log on to the initiating Teradata Database system as a local user.
2. Validate the foreign server configuration by running the HELP FOREIGN SERVER query:
HELP FOREIGN SERVER foreign_server_name;
For example, where tdh9151_fs is the Presto foreign server:

HELP FOREIGN SERVER tdh9151_fs;
Teradata Connector Privileges and Security
Required Teradata Initiator Connector Privileges
To maintain security for Teradata connectors used in QueryGrid.

1. Set appropriate privileges to those who create and manage foreign servers.
2. Set appropriate privileges to authorization objects, if used.
An authorization object stores a mapping of the local user and password for the remote server.

3. Set up foreign server objects that match the appropriate access to database and tables needed by
Teradata Database users.
4. Set appropriate privileges to foreign server objects to Teradata Database users.
Privileges for Administrators

CREATE SERVER and DROP SERVER are object-level privileges that restrict who can use the
CREATE FOREIGN SERVER and DROP FOREIGN SERVER SQL statements with a Teradata initiator
connector.
• CREATE SERVER can only be granted on the TD_SERVER_DB database as a whole.
• DROP SERVER can be granted on the TD_SERVER_DB database or on individual foreign server
objects.
• The CREATE SERVER and DROP SERVER privileges are included if you grant ALL privileges on
the TD_SERVER_DB database.
In addition to the CREATE SERVER and DROP SERVER privileges, administrators need the EXECUTE
FUNCTION and SELECT privileges on the import and export table operators or on the TD_SYSFNLIB
database that contains the table operators in order to create, drop, and modify foreign server objects.
The creator of a foreign server object implicitly receives the following privileges on the object:
• SHOW privilege WITH GRANT OPTION
• DROP SERVER privilege WITH GRANT OPTION
• SELECT privilege WITH GRANT OPTION
• If the foreign server object is capable of exporting data (that is, the CREATE FOREIGN SERVER
statement includes the DO EXPORT WITH clause), the creator automatically receives the INSERT
privilege WITH GRANT OPTION
CREATE AUTHORIZATION and DROP AUTHORIZATION privileges are required to work with
authorization objects referenced by foreign server objects. DROP AUTHORIZATION is automatically
granted to the creator of an authorization object.
Privileges for Users of the Foreign Server Object

You must grant SELECT, INSERT, and SHOW privileges on the foreign server object to users who query
the remote database using a Teradata initiator connector.
Granting the ALL privilege on a foreign server object implicitly grants other privileges that depend on
the nature of the foreign server:
• If the foreign server object can import data from the remote database (that is, the CREATE
FOREIGN SERVER statement included a DO IMPORT WITH clause), granting the ALL privilege
on the foreign server implicitly includes the SELECT, SHOW, and DROP privileges.
• If the foreign server object can export data to the remote database (that is, the CREATE FOREIGN
SERVER statement included a DO EXPORT WITH clause), granting the ALL privilege on the foreign
server implicitly includes the INSERT, SHOW, and DROP privileges.

Teradata Initiator Connector Security and User Sessions
The Teradata initiator connector has a mechanism in the foreign server definition called an authorization
object, which contains the authenticating username and password for the remote system. This works
for either a one-to-one user mapping or a many-to-one user mapping (used for trusted users or service
accounts).
For more information, see Teradata® Database SQL Data Definition Language - Detailed Topics.
QueryGrid also provides a user mapping mechanism associated with the foreign server definition that
permits the mapping of user names. This permits users to be mapped for data centers that do not use
a common user identification across all systems. You can configure the user mapping table in the
QueryGrid portlet.
User mapping allows users logged on to the initiating system to be mapped to another user on the
remote system.
For user mapping, set up the Teradata initiator connector with DEFINER authorization.
Teradata provides a user configurable mechanism for authenticating to Kerberos. The user and
password is used to obtain a ticket from the KDC when attempting to connect to a remote Kerberized
Teradata or Presto.
Session Settings
Session settings are passed from the initiating Teradata Database system to the target Teradata
Database system.
• ANSI and TERA mode affect transaction semantics.
• QueryBand can be used for workload management to map TASM rules from the local to the target
system or to help associate child queries with the initiating Teradata query for monitoring purposes.
QueryGrid appends the following name-value pairs (NVPs) to the initiating Teradata Database
QueryBand when connecting to the target system. If a query traverses through more than one
Teradata-Teradata link, each system appends its session attributes to these NVPs delimited by a
colon.
◦ QG_UUID
◦ TD_HOSTID
◦ TD_QUERYID
◦ TD_REQUEST
◦ TD_SESSION
The following example shows three systems, A, B, and C, with the query initiated on System A.
Select * from foreign table(select * from tab@systemC)@systemB as dt
[QueryBand] System A session = ‘name1=value;’
[QueryBand] System B session =
‘name1=value;QG_UUID=<uuid1>;TD_HOSTID=<hostA>;TD_QUERYID=<queryidA>;TD_REQU

EST=<requestA>;TD_SESSION=<sessionA>;’
[QueryBand] System C session =
'name1=value;QG_UUID=<uuid1>:<uuid2>;TD_HOSTID=<hostA>:<hostB>;TD_QUERYID=<q
ueryidA>:<queryidB>;TD_REQUEST=<requestA>:<requestB>;TD_SESSION=<sessionA>:<
sessionB>;’
Authorization Objects
You can create an authorization object, which stores the credentials for a user in encrypted form for
Teradata connectors. Authorization object stores the user's credentials and used in foreign servers to
carry these credentials to the remote system for authentication.
If you need one-to-one mapping between a Teradata Database user and a remote user, then you must
have corresponding accounts in Teradata Database and the security system.
• When that user creates the authorization using AS INVOKER TRUSTED, the authorization is
stored by default on the user database.
• The credentials for the security system do not need to be revealed to another person and the
authorization object is accessible only to users with privilege to that database.
You can use many-to-one mapping between multiple Teradata Database users and one user on the
remote system to simplify administration. Only the creator of the authorization need know the
credentials for the user on the remote security system. When the authorization is created using AS
DEFINER TRUSTED, the authorization is stored by default in the TD_SERVER_DB database, which
makes the authorization available globally.
For a Teradata-to-Presto connection, create an authorization object and use it in the USING clause of
the foreign server. Teradata passes the credentials in an authorization object to the Presto connector,
then the Presto connector authenticates the user before sending the query to the data source.
Where the Foreign Server Looks for the Authorization Object

When using INVOKER, the authorization is stored in user's database; each user can use their own
credentials to log on to the remote system. When a foreign server is configured with the INVOKER
keyword and no value is specified for the database name (dbname), Presto or Hive connectors
automatically look for the authorization in the user database of the session user.
Using INVOKER
This example creates the remote_presto1 authorization object in the user database of the creator. If
the creator is td_user then td_user.remote_presto1 is the fully qualified object name.
create authorization remote_presto1 as invoker trusted

user 'active_user' password 'active_pass';
This example creates a foreign server object that uses the remote_presto1 authorization object.

create foreign server Presto_1

external security invoker trusted remote_presto1
using
link('td1_presto1')
version('active')
The link value of td1_presto1 was created in the QueryGrid portlet. The link defines initiating and
target networks, specifies a communications policy that defines rules for transferring data between
connectors, and other properties.
When a foreign server is configured with the DEFINER keyword and no value is specified for the
database name (dbname), the Teradata connector automatically looks for the authorization in the
TD_SERVER_DB database.
Using DEFINER
This example creates the remote_presto1 authorization object.
create authorization td_server_db.remote_presto1 as definer trusted

user 'active_proxy_user' password 'active_proxy_pass';
This example creates a foreign server object that uses the remote_presto1 authorization object.
create foreign server Presto_1

external security definer trusted remote_presto1
using
link('td1_presto1')
version('active')
The link value of td1_presto1 was created in the QueryGrid portlet. The link defines initiating and
target networks, specifies a communications policy that defines rules for transferring data between
connectors, and other properties.
For more information, see CREATE AUTHORIZATION and REPLACE AUTHORIZATION.
Teradata Target Connector Security Guidelines
Teradata connectors support Trusted, TD2, LDAP, and Kerberos security mechanisms when acting as
target connectors. The following considerations apply to each of the security mechanisms:
• The username and password assigned and communicated from the initiator connector takes
precedence over the one defined for the Teradata target connector properties.

For example, if the Teradata initiator provides an authorization object, it takes precedence over
security-related connector property settings. Defining these connector properties is optional. If,
however, credentials are not provided by the initiator connector, a username and password must
exist in its connector property settings.
• An Administrator can define user mappings in the QueryGrid portlet if the initiator end user differs
from the remote system end user. This is the user to which you have granted CONNECT THROUGH
on the remote system.
• For user mapping, the local user submitting the query is mapped to the remote user that submits
the query. User mapping applies as follows:
◦ For a Teradata initiator connector, user mapping can be used when it is set up with DEFINER
authorization such that the local user submitting the query is the not the same as the
authenticating user.
◦ For a target connector, user mapping is applicable when it is set up with the TRUSTED
authentication mechanism and the remote user is not the same as the authenticating user.
Trusted
Trusted User or Service Accounts are a proxy user that act on behalf of the local user. You configure
trusted sessions by granting CONNECT THROUGH privileges to proxy user or permanent end user. To
do this perform the following steps on the remote system:
CREATE USER proxyuser AS PERM = 0 PASSWORD = password;
GRANT CONNECT THROUGH proxyuser TO PERMANENT target_end_user without role;
>> this target_end_user is the user that has access to objects that we will
access from local system
The following property settings are required for Teradata target connectors using the Trusted security
model.
Setting Description
Authentication Mechanism Set to Trusted.
Username Set to the proxy user name.
Password Set to the password for proxy user.
TD2
The following property settings are required for Teradata target connectors using the TD2 security model.
Setting Description
Authentication Mechanism Set to TD2.
Username Set to the authorization user name.
Password Set to the password for the authorized user.

LDAP
You can configure Teradata target connectors to use LDAP authentication involving a username and
password. This means that queries with a Teradata target can be submitted using the LDAP security
mechanism to authenticate; for example, the Presto-to-Teradata connection supports LDAP. The
following properties must be configured to use LDAP with Teradata target connectors.
Setting Description
Authentication Mechanism Set to LDAP.
Username Set to the LDAP directory user name.
Password Set to the password for the user.
For detailed information about how to configure Teradata target connectors to use LDAP authentication,
refer to the Orange Book: User Authentication and Directory Integration.
Kerberos
Teradata Kerberos set up must be completed before configuring QueryGrid. The following property
settings are required for Teradata target connectors using the Kerberos security model.
Setting Description
Authentication Mechanism Set to Kerberos.
Username Set to the Kerberos principal name.
Password Set to the password for the Kerberos principal name.

QueryGrid authenticates a principal using a password.
Realm Set to the Kerberos realm.
For more information, see Teradata Connector and Link Properties.
Teradata Gateway Encryption
Teradata gateway encryption is supported.
Using the Teradata Connector
Data Dictionary Views for Teradata QueryGrid

The following Data Dictionary views are available for QueryGrid:
• DBC.QryLogV (TotalServerByteCount column only)
• DBC.QryLogStepsV (ServerByteCount column only)

• DBC.ServerV[X]
• DBC.ServerInfoV[X]
• DBC.TblSrvV[X]
• DBC.TblSrvInfoV[X]
For more information, see Teradata® Database Data Dictionary, B035-1092.
SQL Syntax for the Teradata Connector

The following describes the SQL syntax and options specific to the Teradata QueryGrid connector, and
provides examples of their use.
If you are a DBA, or a DBA has already granted you the privileges needed to create foreign servers, we
recommend that you start by reading CREATE FOREIGN SERVER.
SQL Command Reference for the Teradata Connector
ALTER FOREIGN SERVER
Purpose
Modifies the parameters of an existing server object.
Syntax
ALTER FOREIGN SERVER server_name A
EXTERNAL SECURITY INVOKER TRUSTED authorization_name

DEFINER
A
,
ADD modify options ;
DROP drop options

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 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.
You must use either INVOKER TRUSTED or DEFINER TRUSTED if the remote platform uses
an external security system (such as Kerberos, for example) for authentication.

TRUSTED
A keyword that indicates the associated authorization object was created as TRUSTED.
You must use the TRUSTED security type for the Teradata connector.
authorization_name
Specifies the name of the authorization object to be used when the foreign server is accessed.
Modify Options
ADD
Use to:
• 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 External Name Value pair or pairs (LINK and VERSION) you want to add or modify.
The name value pair or pairs define the properties of the foreign server. The name value
pairs are defined in the QueryGrid portlet. You can create separate named link
configurations for unique sets of properties and you can create different versions (active,
pending, previous) of the links. For more information, see Teradata Connector and Link
Properties.
You can change the External Name Value pairs in ALTER FOREIGN SERVER. If you want
to modify the properties of the named link, use the QueryGrid portlet.
In the description of the name value pairs:
• The label "Server only" indicates that the name value pair must follow the syntax ADD
name('value').
• The label "Import only" indicates that the name value pair must be specified after the
IMPORT keyword.
• The label "Export only" indicates that the name value pair must be specified after the
EXPORT keyword.
• Unlabeled name value pairs may be specified in any part of the ADD syntax. If
specified as ADD name('value'), the name value pair will be applied to the server as
a whole.
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.

operator_name
The name of the table operator that you want to use.
For more information about the table operators used with the server object, see CREATE
FOREIGN SERVER.
Drop Options
DROP
• 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.
• Drop a local name value pair that was used with an IMPORT or EXPORT table operator. You
need only specify the name to drop the pair.
name
When used alone, name is the name of the name value pair you want to drop.
IMPORT
Indicates you are going to act on the operator that is used to import data into Teradata
Database.
EXPORT
Indicates you are going to act on the operator that is used to export data out of Teradata
Database.
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.
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 Teradata® Database SQL Data Definition Language - Syntax and Examples,
B035-1144.

Syntax
BEGIN LOGGING ON A
DENIALS WITH TEXT FIRST
LAST
FIRST AND LAST
EACH
A ALL B
, ,
FOR CONSTRAINT constraint_name
operation BY database_name
GRANT user_name
B
, 20 ;
ON AUTHORIZATION authorization_name
DATABASE database_name
USER database_name
TABLE object_name
VIEW database_name.
MACRO user_name.
PROCEDURE
FUNCTION
TYPE
FOREIGN SERVER
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.
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 Teradata® Database SQL Data Definition Language - Syntax and Examples, B035-1144.

Syntax
COMMENT object_kind_1 object_name

ON object_kind_2 database_name. 'comment' ;
user_name.
AS
IS
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 Teradata® Database 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 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 server protected by Kerberos, then the associated
authorization object must contain credentials for the user account on that server.
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,
seeTeradata® Database 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.
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.
When using an authorization object, you must use the TRUSTED security type for the
Teradata QueryGrid Teradata connector.
You cannot use TRUSTED authorizations in CREATE or REPLACE UDF or XSP statements.
'fs_user_name'
'fs_user_name@realm_name'
The name of the credential on the remote platform to be used by the foreign server.
The user name for the authorization object can consist of a user name alone or a user name
and the name of the Kerberos realm. When only the user name is specified, the default realm
specified in the krb5.conf file is used for kinit.
If you include the Kerberos realm name, then the default realm is ignored and the realm that
you specify in the authorization object is used for kinit. You should include a Kerberos realm
name if you have one of the following situations:
• You want users to be able to connect to multiple Kerberized clusters, each from a different
realm, from the same Teradata system.
• You want users to be able to connect to a Kerberized cluster where the authentication
realm is different from the service realm.
Note:
If used with the name of the Kerberos realm, the user_name portion cannot also contain
an @ sign.
'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 Teradata® Database SQL Data Definition Language - Syntax and
Examples, B035-1144.
Usage Notes
• An authorization is required only if you are using an external security system such as Kerberos
for authentication on the foreign server's target platform.

• You must use either INVOKER TRUSTED or DEFINER TRUSTED when authentication on
Hadoop is performed by an external security system such as Kerberos.
• Use INVOKER TRUSTED when you want to create a one-to-one mapping between the Teradata
user and the user on the foreign server's target platform. For example, using the same user name
for Teradata and Kerberos.
• Use DEFINER TRUSTED when you want to create a many-to-one mapping between Teradata
users and a user on the target platform of the foreign server. For example, when you want multiple
Teradata users who are making requests to the foreign server to use one Kerberos account on
the target platform.
• Username and Password connector properties can be set in the QueryGrid portlet. They are used
for connector diagnostic checks and for end-to-end queries if they were not provided by the initiator
in the authorization object.
• When you create an authorization for another user using INVOKER TRUSTED, user_dbname
must be specified. Specify the username associated with the session user who will be sending
requests to the foreign server. If you fail to specify user_dbname, the authorization will be stored
in your user database.
• The authorization takes up no space in the database used to store it.
• If your credentials change on the target platform of the foreign server, you must remember to
replace the credentials in your 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.
• 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 plan to use the authorization to authenticate to Kerberos on a foreign server then you must use
either INVOKER TRUSTED or DEFINER TRUSTED.
The following two examples establish authorization for the user who invokes the object. The credentials
are encrypted and stored as a database object in the user database.
CREATE AUTHORIZATION sales AS INVOKER TRUSTED

USER 'johnson'
PASSWORD 'Secret' ;
REPLACE AUTHORIZATION sales AS TRUSTED

USER 'williams'
PASSWORD 'topsecret' ;
If you want to make the authorization available globally, create the authorization on TD_SERVER_DB
using the DEFINER TRUSTED type. If you use DEFINER TRUSTED, as in this example, then the

credentials for proxy_1 are stored in the remote_system1 authorization that is created in the
TD_SERVER_DB database.
CREATE AUTHORIZATION TD_SERVER_DB.remote_system1

AS DEFINER TRUSTED USER 'proxy_1'
PASSWORD 'Global' ;
CREATE FOREIGN SERVER
Purpose
Creates a foreign server object and associates an import table operator and an export table operator
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.
Syntax
CREATE FOREIGN SERVER server_name A
EXTERNAL SECURITY TRUSTED authorization_name

INVOKER
DEFINER
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
Associates an authorization object with the foreign server. The authorization stores the
encrypted credentials for a user as a database object. The Teradata 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.
You must use either INVOKER TRUSTED or DEFINER TRUSTED if the remote platform uses
an external security system (such as Kerberos, for example) for authentication.
TRUSTED
A keyword that indicates the associated authorization object was created as TRUSTED.
You must use the TRUSTED security type for the Teradata connector.
authorization_name
Specifies the name of the authorization object to be used when the foreign server is accessed.

USING
USING introduces the name value pair that provides server definition information. 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.
name('value')
The name value pair or pairs define the properties of the foreign server. The name value pairs are
defined in the QueryGrid portlet. You can create separate named link configurations for unique sets
of properties and you can create different versions of the links. For more information, see Teradata
After defining the properties in the QueryGrid portlet, use the External Name Value pairs (LINK and
VERSION) with the USING clause of CREATE FOREIGN SERVER to associate the name value pair
with the foreign server.
The link name value pair is required to create a functioning foreign server object. Version is optional.
Additional optional name value pairs may be required to create a foreign server for a specific
implementation.
link
A named configuration that references an initiating connector, a target connector, a
communication policy, and defines the connector properties to use.
version
The version of the link to use.
You can specify the version of the configuration to use (active or pending) in a Teradata
foreign server definition. When pending is specified, then any pending versions of the link,
the initiating connector, the target connector, the communication policy, and the fabric are
used.
name(scalar_subquery)
You can also specify a subquery that returns a single row. Only one subquery is allowed for each
name. The subquery must return only one row and the WHERE clause of the subquery must reference
a unique primary index or unique secondary index. System variables and Using parameters are
allowed in the WHERE clause of the subquery. The row can have multiple values (columns) but all
values must be the same data type.
name(system_variable)
You can specify a system variable as a value.
name(using_parameter)
You can specify a using parameter as a value.

DO IMPORT WITH
Associates an IMPORT function with a foreign server.
DO EXPORT WITH
Associates an EXPORT function with a foreign server.
Required Privileges
You must have CREATE SERVER privilege on the TD_SERVER_DB database to define a foreign
server object. If you are associating the server with table operators, you must also have EXECUTE
FUNCTION and SELECT privileges on the specified table operators.
Usage Notes
• The target platform of the foreign server object must be running and reachable when creating the
foreign server object for it in Teradata Database.
• You can create multiple named foreign server objects that reference the same server using the
same link.
• Foreign server object names that are stored in TD_SERVER_DB must be unique.
• Name value pairs in the server area of the syntax apply to the connection to the remote platform
and to both of the table operators specified in the IMPORT WITH and EXPORT WITH clauses.
• Server options, names, and name value pairs can appear only once in the CREATE FOREIGN
SERVER syntax.
• The order of the DO IMPORT WITH and DO EXPORT WITH clauses in the CREATE SERVER
syntax does not matter.
• You must grant SELECT, INSERT, and SHOW privileges on foreign server objects to users who
need to query foreign server objects.
Examples: Using CREATE FOREIGN SERVER
The example creates a foreign server using the LINK name value pair. The link and its properties are
defined in the QueryGrid portlet.
CREATE FOREIGN SERVER Presto_1

USING
LINK(‘td1_presto1’)

The example creates a foreign server using the LINK and VERSION name value pairs. The link and
its properties are defined in the QueryGrid portlet. The state of the link (active, pending, or previous)
is also set in the QueryGrid portlet and referenced in the VERSION clause in the example:

EXTERNAL SECURITY DEFINER TRUSTED Auth_1
USING
LINK(‘td1_presto1’)
VERSION('active')
For more information about connector and link properties, see Teradata Connector and Link Properties.
For more information about versions, see Replacing Active Fabrics, Connectors, and Links Versions
with Pending or Previous Versions.
DROP FOREIGN SERVER
Purpose
Drops a foreign server object from the TD_SERVER_DB database.
In addition to deleting the server object and its associated information from the dictionary tables, all
dependent entries on the associated table operators are deleted.
You must have the DROP SERVER privilege on the TD_SERVER_DB database or on the specified
foreign server to DROP the foreign server.
Syntax
DROP FOREIGN SERVER server_name
TD_SERVER_DB. ;
Syntax Elements
server_name
The name of the foreign server object.

You can also use the following formats for the server name:
• the Unicode Delimited Identifier, such as U&"foreign#005fsv" UESCAPE'#'
• the double-quoted object name, such as "foreign srv1"

TD_SERVER_DB.
The name of the database that stores server objects and their attributes.
Example: Using DROP FOREIGN SERVER
The example shows how to drop a foreign server object.
DROP FOREIGN SERVER TD_SERVER_DB.Presto1;
END LOGGING
Purpose
Ends the auditing of SQL requests that started with a BEGIN LOGGING request.
This topic describes only the portions of the END LOGGING syntax diagram that are specific to Teradata
QueryGrid. For information about the other syntax that you can use with END LOGGING, see Teradata®
Database SQL Data Definition Language - Syntax and Examples, B035-1144.
Syntax
END LOGGING ON ALL A

,
DENIALS WITH TEXT
operation
GRANT
A B
FOR CONSTRAINT constraint_name ,
BY database_name
user_name
B
, 20 ;
ON AUTHORIZATION authorization_name
DATABASE database_name
USER database_name
TABLE object_name
VIEW database_name.
MACRO user_name.
PROCEDURE
FUNCTION
TYPE
FOREIGN SERVER

Syntax Elements
ON operation
Indicates the operation for which log entries should no longer be made.
ON FOREIGN SERVER object_name
Indicates that the operation for which log entries should no longer be made is access to 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.
For information about using END LOGGING, see Teradata® Database SQL Data Definition Language
- Syntax and Examples, B035-1144.
EXPLAIN
You can use the Teradata QueryGrid connector to query a remote system to request an EXPLAIN plan
from the remote system.
For a Presto target system specify the kind of EXPLAIN you want, either LOGICAL or DISTRIBUTED.
• A LOGICAL plan executes the EXPLAIN command on a single node.
• A DISTRIBUTED plan executes the EXPLAIN command in fragments on single or multiple nodes.
To specify the kind, use the QueryGrid portlet to configure the target connector with the ExplainKind
connector property. See Teradata Connector and Link Properties.
Example: Session Override Introduction

The example generates an EXPLAIN plan for a session override introduction.
< BEGIN EXPLAIN FOR REMOTE QUERY -->

----- BEGIN SESSION OVERRIDDEN PROPERTIES -----
'linkBufferSize' = '1048576'
'schemaName' = 'default'
----- END SESSION OVERRIDDEN PROPERTIES -----
Remote Queries:
1. CREATE TABLE
qgremote.DEFAULT.TEMP_38b505c0_9fb4_4a3d_bdc8_000000000017_EXEC
...

Example: Using Teradata to Presto EXPLAIN SELECT

The example generates an EXPLAIN plan from the remote SELECT query and embeds the result into
the query plan on the local Teradata system.
EXPLAIN SELECT * FROM p100@tdh111 WHERE c1 > 10;
Result:
Explanation
---------------------------------------------------------------------------
1) First, we do an all-AMPs RETRIEVE step executing table operator
TD_SYSFNLIB.QGINITIATORIMPORT with a condition of ("p100.C1 >= 11").
Remote Queries:
1. EXPLAIN CREATE TABLE
qgremote.DEFAULT.TEMP_a1cd2570_d4ef_4b38_b3ed_00000000014e_EXEC AS
SELECT c1 ,c2 ,c3 ,c4 ,c5 FROM "default"."p100" WHERE C1 >= 11
[- Output[rows] => [rows:bigint]
-
TableCommit[qgremote:QGRemoteTransactionHandle{uuid=280273f9-403c-4cc7
-b0b5-dc148b36285f}:com.teradata.querygrid.qgc.presto.QGRemoteInsertTa
bleHandle@e32e808] => [rows:bigint]
- Exchange[GATHER] => partialrows:bigint, fragment:varbinary
- TableWriter => [partialrows:bigint, fragment:varbinary]
c1 := c1
c2 := c2
c3 := c3
c4 := c4
c5 := c5
- Exchange[REPARTITION] => c1:bigint, c2:varchar, c3:double,
c4:boolean, c5:varbinary
- ScanFilterAndProject[table = hive:hive:default:p100,
originalConstraint = ("c1" >= 11), filterPredicate = ("c1" >= 11)]
=> [c1:bigint, c2:varchar, c3:double, c4:boolean, c5:varbinary]
LAYOUT: hive
c1 := HiveColumnHandle{clientId=hive, name=c1, hiveType=bigint,
hiveColumnIndex=0, partitionKey=false}
c2 := HiveColumnHandle{clientId=hive, name=c2, hiveType=string,
c3 := HiveColumnHandle{clientId=hive, name=c3, hiveType=double,
c4 := HiveColumnHandle{clientId=hive, name=c4, hiveType=boolean,
c5 := HiveColumnHandle{clientId=hive, name=c5, hiveType=binary,

]
<-- END EXPLAIN FOR REMOTE QUERY >
The size of Spool 1 is estimated with low confidence to be 8 rows
(33,096 bytes). The estimated time for this step is 0.15 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 ("p100.C1 >= 11") into
Spool 2 (group_amps), which is built locally on the AMPs. The
size of Spool 2 is estimated with low confidence to be 8 rows (
98,840 bytes). The estimated time for this step is 0.16 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.31 seconds.
Example: Using Teradata to Presto EXPLAIN INSERT

The example generates an EXPLAIN plan for the remote INSERT query and embeds the result into the
query plan on the local Teradata system.
EXPLAIN INSERT INTO p100@tdh111 values(1,'abc',11.1, 1, 1);
Result:
Explanation
---------------------------------------------------------------------------
1) First, we do an INSERT into Spool 4.
2) Next, we do an all-AMPs RETRIEVE step from Spool 4 (Last Use) by
way of an all-rows scan executing table operator
TD_SYSFNLIB.QGINITIATOREXPORT with a condition of ("(1=1)") into
Spool 2 (used to materialize view, derived table, table function
or table operator p100) (all_amps), which is built locally on the
AMPs.
Remote Queries:
1. CREATE TABLE
qgremote.DEFAULT.TEMP_a1cd2570_d4ef_4b38_b3ed_00000000014f_EXEC AS
SELECT * FROM "p100" WITH NO DATA
2. EXPLAIN INSERT INTO "p100" SELECT * FROM
qgremote.DEFAULT.TEMP_a1cd2570_d4ef_4b38_b3ed_00000000014f_EXEC
3. DROP TABLE IF EXISTS
qgremote.DEFAULT.TEMP_a1cd2570_d4ef_4b38_b3ed_00000000014f_EXEC
[- Output[rows] => [rows:bigint]
- TableCommit[hive:LegacyTransactionHandle{connectorId=hive,
uuid=f15a3b4c-89a8-427d-8dcd-c147334ff2ca}:hive:default.p100] =>

[rows:bigint]
- Exchange[GATHER] => partialrows:bigint, fragment:varbinary
- TableWriter => [partialrows:bigint, fragment:varbinary]
c1 := c1
c2 := c2
c3 := c3
c4 := c4
c5 := c5
- Exchange[REPARTITION] => c1:bigint, c2:varchar, c3:double,
c4:boolean, c5:varbinary
-
TableScan[qgremote:default:temp_a1cd2570_d4ef_4b38_b3ed_00000000014f_e
xec, originalConstraint = true] => [c1:bigint, c2:varchar,
c3:double, c4:boolean, c5:varbinary]
LAYOUT:
com.teradata.querygrid.qgc.presto.QGRemoteTableLayoutHandle@6029ca45
c1 := {name = c1, type = bigint}
c2 := {name = c2, type = varchar}
c3 := {name = c3, type = double}
c4 := {name = c4, type = boolean}
c5 := {name = c5, type = varbinary}
]
The size of Spool 2 is estimated with high confidence to be 1 row
(29 bytes). The estimated time for this step is 0.03 seconds.
3) We do an all-AMPs RETRIEVE step from Spool 2 (Last Use) by way of
an all-rows scan into Spool 3 (Last Use), which is built locally
on the AMPs. The size of Spool 3 (Last Use) is estimated with
high confidence to be 1 row (41 bytes). The estimated time for
this step is 0.16 seconds.
-> No rows are returned to the user as the result of statement 1.
GRANT and REVOKE
GRANT grants one or more explicit privileges on a database, foreign server, user, proxy logon user,
table, hash index, join index, view, stored procedure, User-Defined Function (UDF), User-Defined
Method (UDM), User-Defined Type (UDT), or macro to a role, group of roles, user, or group of users or
databases. REVOKE revokes privileges on the same objects.
There are no changes to existing syntax for Teradata QueryGrid, except that CREATE SERVER and
DROP SERVER privileges have been added. These privileges should be granted only to a user, not to
a database.

Note:
You are not allowed to GRANT CONNECT THROUGH privilege on the DBC user.
For a syntax diagram and description of the syntax elements that you can use in GRANT and
REVOKE, see Teradata® Database SQL Data Control Language, B035-1149.
HELP FOREIGN
Purpose
Returns the details of the foreign object that you specify.
• A foreign server object name returns the list of databases accessible on the server.
• The name of a database on a foreign server returns the list of tables in the remote database on the
server.
• The name of a table in a remote database on a foreign server returns the list of columns in the
remote table on the server.
• The name of a function in a remote database on a foreign server.
Syntax
Syntax Elements
SERVER server_name
The name of the foreign server. Displays the databases in the foreign server.
DATABASE db_name@server_name
The name of the remote database, qualified with the name of the foreign server. Displays the tables in
the database.
TABLE db_name.table_name@server_name
The name of the remote table, qualified with the name of the foreign server. Displays the column names,
data type, and other attributes.

HELP FOREIGN TABLE can be executed with or without the database or schema name (db_name)
specified. When the database name is not provided in the query, the currently logged on database or
the connector default is used.
FUNCTION db_name.ForeignFunction@server_name
The name of the function on the remote database, qualified with the name of the remote server.
Displays the details of the foreign function available on the remote server. For example, the statement
may return the function parameters, their types, and other attributes.
Examples of Using HELP FOREIGN
Example: Teradata to Presto HELP FOREIGN SERVER

The example fetches the schema (databases) from the catalog associated with the server.
help foreign server QG_Presto1;
Result:
Databases
--------------------
default
information_schema
finance
marketing
Example: Teradata to Presto HELP FOREIGN DATABASE

The example fetches the tables from the specified database.
help foreign database "default"@QG_Presto1;
Result:
Tables
---------------------
buses
ca120453
jing_part_tab1
prama_part_tab1
tbig_1row
web_sales_part1_orc
Example: Teradata to Presto HELP FOREIGN TABLE

The example fetches the column information of the specified table.

Note:
HELP FOREIGN TABLE can be run with or without the database or schema name specified.
When the database name is not provided in the query, the currently logged on database or the
connector default is used.
help foreign table tbig_1row@QG_Presto1;
Result:
Column | Type | Comment

————-——-----+—————-----+————-
id | bigint |
firstname | varchar |
lastname | varchar |
gender | varchar |
age | bigint |
Example: Teradata to Teradata HELP FOREIGN FUNCTION

The example fetches information about the specified foreign function.
help foreign function syslib.MonitorQueryBand@td1 ;
Result:
Parameter Name HostId

Type I2
Comment ?
Nullable Y
Format -(5)9
Max Length 2
Decimal Total Digits ?
Decimal Fractional Digits ?
Table/View? F
Char Type ?
Parameter Type I
UDT Name ?
Parameter Dictionary Name HostId
Parameter SQL Name HostId
Parameter Name UEscape ?
UDT Dictionary Name ?
UDT SQL Name ?
UDT Name UEscape ?
Inline Length ?
Parameter Name SessionNo

Type I
Comment ?
Nullable Y
Format -(10)9
Max Length 4
Table/View? F
Char Type ?
Parameter Type I
UDT Name ?
Parameter Dictionary Name SessionNo
Parameter SQL Name SessionNo
UDT SQL Name ?
UDT Name UEscape ?
Inline Length ?
Parameter Name RunVProcNo
Type I2
Comment ?
Nullable Y
Format -(5)9
Max Length 2
Table/View? F
Char Type ?
Parameter Type I
UDT Name ?
Parameter Dictionary Name RunVProcNo
Parameter SQL Name RunVProcNo
UDT SQL Name ?
UDT Name UEscape ?
Inline Length ?
Parameter Name RETURN0
Type CV
Comment ?
Nullable Y
Format X(12304)
Max Length 24,608


Table/View? F
Char Type 2
Parameter Type O
UDT Name ?
Parameter Dictionary Name RETURN0
Parameter SQL Name RETURN0
UDT SQL Name ?
UDT Name UEscape ?
Inline Length ?
Required Privileges
You must have ANY privilege granted on the server object to display the output from HELP FOREIGN.
The ANY privilege is used for a HELP or SHOW statement for which at least one privilege, but no
specific privilege, is required. For more information, see Privilege Dictionary in Teradata® Database
SQL Data Control Language, B035-1149.
INSERT Syntax and the Teradata Connector
You can export data to a remote system by using an INSERT statement to place data into an existing
table. The table can be empty or it can contain data. If the table already contains data, the exported data
is appended to the data in the existing table.
If no database is specified for the remote database, the current session database or the connector
default database is used, depending on the remote connector type and user mapping.
Example: Teradata to Presto INSERT

The example shows an export request initiated on Teradata using the foreign server object
(new_cardata@QG_Presto1) to insert data from a Teradata table into a table on a remote Presto system.
INSERT INTO new_cardata@QG_Presto1 SELECT * FROM td_cardata;
SELECT Syntax and the Teradata Connector
You can use the foreign server grammar in the form of database_name.table_name@server_name in
the SELECT statements of your queries. If you do not specify a database, it defaults to the current
database for Teradata-to-Teradata and is used as the default or overridden database provided in the
connector or link properties for Teradata-to-Presto. You can use this foreign server grammar in joins and
any other place that you reference a normal table, including views, macros, and stored procedures.

Logical expressions such as AND, OR, NOT, >, <, and so on, are supported. Standard Teradata limits,
such as returning up to 2048 columns, apply. Row size must be less than 64K.
For a list of the supported data types, see Data Type Mapping for Teradata QueryGrid Connectors.
Query processing is pushed down to the target system, based on the capabilities of the target system,
and the optimization of the local system. For example, if you query a target Presto system from a
Teradata system, the Teradata optimizer decides the pushdown predicates, which are then evaluated
for final target query pushdown based on what is supported by the target system.
Example: Teradata to Presto SELECT

The example initiates a request from Teradata to select data from a table on the target Presto system,
using the foreign server object (presto1) and the target Presto table (cardata):
SELECT CAST(Price AS DECIMAL (8,2))

, mileage
, CAST(make AS VARCHAR(20))
, CAST(model AS VARCHAR(20))
FROM cardata@presto1 WHERE make=’Buick’;
Result:
price mileage make model

-------- ------- ------ --------------------
17314.10 8221 Buick Century
17542.04 9135 Buick Enclave
Example: Teradata to Presto SELECT from Foreign Table

The example initiates a request on Teradata using the foreign table push down query to fetch data from
a target Presto system. This is a pass through query and will not be parsed on the Teradata end, but
might need to be regenerated on the target server, for example, to qualify table name with catalog name:
SELECT * FROM FOREIGN TABLE (SELECT make, model FROM default.cardata

where make = 'Buick')@QG_presto1 AS dt;
Result:
make model
------ --------------------
Buick Century
Buick Enclave
Note:
A select from foreign table request can only be initiated by Teradata.

Example: Teradata to Presto SELECT from Foreign Table with an EXPORT

Clause
The example shows a foreign table query with an additional export clause that combines the export
operation and subsequent join and import operation in a single operator. This example first creates a
temporary table (temp) in the target database, exports the data from the local ut2.datatypes2 table to
the temporary table, then runs the query on the foreign table to join the temporary table and the target
datatypes1.bigint1 table, and then the result set is brought back Teradata.
SELECT * FROM FOREIGN TABLE

(SELECT datatypes1.bigint1, temp.double1 FROM datatypes1, temp
WHERE datatypes1.bigint1 > 1)@test EXPORT((select * from ut2.datatypes2) as
temp)
AS ft;
Note:
A select from foreign table request with an export clause can only be initiated by Teradata.
Example: Teradata to Presto SELECT from Foreign Table with an EXPORT

Clause (Multiple Input Streams)
Multiple tables can be exported to the target system. A maximum of 16 input streams are supported.
An error is displayed when the limit is exceeded.
SELECT * FROM
FOREIGN TABLE(SELECT types_numeric.bigint1,temp1.integer1 , temp2.byteint2
FROM types_numeric, temp1,temp2
WHERE types_numeric.bigint1 > 1
AND temp2.bigint2 = types_numeric.bigint1)@td1
EXPORT(
(SELECT 127 as byteint1, 32767 as smallint1, 2147483647 as integer1,
9223372036854775807 as bigint1) as temp1,
localdb.table1 as temp2)
AS ft;
Note:
A select from foreign table request with an export clause can only be initiated by Teradata.
Example: SELECT with a RETURNS Clause

SELECT supports the use of a RETURNS clause to define expected output. The RETURNS clause
supports column lists or table definitions, and is typically used to return a column with a specific type,
character set length, and string format. Arrays used in the RETURNS clause bring the column back,
based on the Teradata array type. When fetching an unbounded or bounded string type, a RETURNS

clause helps map these types to CHAR, VARCHAR, or CLOB with a specific length or character set.
BYTE and VARBYTE can also be mapped to a specific length.
When bringing the array type from Hive or Presto target connectors, any JSON-based Hadoop array
format is implicitly converted to the Teradata VARCHAR array format.
CREATE TYPE SUSUDTLIB.STRARRAY AS VARCHAR(2) CHARACTER SET UNICODE ARRACY [3];
SELECT * FROM datatypes1@fs1 RETRUNS (varchar1 STRARRAY)
SELECT * FROM datatypes1@fs1 RETURNS (varchar1 VARCHAR(5) CHARACTER SET LATIN)
WHERE bigint1 >10000 AND double1 < 10000;
Example: SELECT Foreign Function

During Foreign Function execution, tables are exported from the initiating system to the target system,
the function is run on the target system, and the result is imported into the initiating system.
SELECT clicktime, custname(char(10)), productname, pagetype, productprice, sessionid

FROM SESSIONIZE@remoteTD
(
ON ( sess_data )
PARTITION BY partition_id
ORDER BY clicktime
USING
TIMECOLUMN('clicktime')
TIMEOUT(60)
RAPIDFIRE(0.2)
) AS S, cust_data where S.userid = custid ORDER BY S.partition_id, S.clicktime;
*** Query completed. 19 rows found. 6 columns returned.
*** Total elapsed time was 3 seconds.
CLICKTIME custname PRODUCTNAME PAGETYPE PRODUCTPRICE SESSIONID
-------------------------- -------- ------------ --------- ------------ ---------
2013-12-03 22:03:02.540000 Sri ? Home ? 0
2013-12-03 22:03:32.190000 Sri mytablet checkout 45000.00 0
2013-12-03 22:03:46.210000 Sri myphone 3 checkout 46000.00 0
2013-12-03 22:04:13.820000 Sri B LED TV checkout 86000.00 0
2013-12-03 22:04:25.520000 Sri Z LED TV checkout 91000.00 0
2013-12-18 22:08:07.800000 Walkar ? Home ? 1
2013-12-18 22:08:38.890000 Walkar A Laptop checkout 58500.00 1
2013-12-19 22:09:26.930000 Walkar ? Home ? 2
2013-12-19 22:10:09.180000 Walkar XYZ Laptop checkout 56500.00 2
2013-12-19 22:10:41.860000 Walkar Solar A4 checkout 36500.00 2
2013-12-19 22:11:00.040000 Walkar ABC Tru checkout 41500.00 2
2013-12-24 22:15:13.600000 Pam ? Home ? 3
2013-12-24 22:15:42.170000 Pam home theater checkout 800.00 3
2013-12-24 22:16:03.520000 Pam TV 52inch checkout 700.00 3
2013-12-25 22:12:20.890000 Julia ? Home ? 4
2013-12-25 22:12:52.820000 Julia ABC Tru checkout 41000.00 4
2013-12-25 22:13:11.720000 Julia myphone 3 checkout 47000.00 4
2013-12-26 22:13:54.150000 Doug ? Home ? 5
2013-12-26 22:14:13.000000 Doug myphone 3 checkout 250.00 5
SHOW FOREIGN SERVER
Purpose
Displays the SQL text most recently used to create, drop, or modify the server object.

A SHOW FOREIGN SERVER statement allows you to see a server object definition that contains the
name value pairs that the associated table operators use to connect to the foreign server.
Syntax
Syntax Elements
IN XML
To return the report in XML format.

The XML schema for the output produced by this option is maintained in:
http://schemas.teradata.com/dbobject/DBobject.xsd
TD_SERVER_DB.
The name of the database that stores foreign server objects and their parameters.
server_name
The name of the foreign server object.

For the full syntax diagram and information about the other objects that can be used with SHOW, see
Teradata® Database SQL Data Definition Language - Syntax and Examples, B035-1144.
Required Privileges
SHOW FOREIGN SERVER requires SHOW privilege or ANY privilege on the server object to display
the output.
Example of Using SHOW FOREIGN SERVER
This example demonstrates the SHOW FOREIGN SERVER that returns XML output.
SHOW IN XML FOREIGN SERVER TD_SERVER_DB.presto1;

Overriding Session Properties

Designating a Teradata connector property as overridable in the QueryGrid portlet allows users to
override configured Teradata connector properties when starting queries during an individual processing
session.
When you override a Teradata connector property, the servername in the syntax statement indicates the
foreign server to which the listed, overridable Teradata connector properties apply. The designated foreign
server uses the value of the properties listed in the syntax statement until the occurrence (if any) of
another servername.
2. Select the fabric.
Option Description
To override a Teradata a. Click the Connectors tab.

connector property in b. Click next to the connector that has a property you want to override.
the Connectors tab
c. Select Edit.
d. Click next to Connector Software.
e. Find the Teradata connector property you want to override and click the
Overridable check box.
f. Click OK.
g. Click Save.
To override a Teradata a. Click the Links tab.

connector property in b. Click next to the link that has a property you want to override.
the Links tab
c. Select Edit.
d. Click next to Initiating Connector or Target Connector.
e. Find the Teradata link property you want to override and click the
f. Click OK.
g. Click Save.
4. Use the following syntax when running Teradata Database 16.00 and later to override the Teradata
connector property during a session:
set foreign server attr = ‘servername=<fs1>;<prop1>=<overrideVal1>;
…;servername=<fs2>
<prop1>=<overrideVal1>;…;’ for session volatile;
For example:
Set foreign server attr =
‘servername=fs1;readtimeout=500000;writetimeout=200000;servername=fs2;
responsetimeout=250000;’ for session volatile;

5. [Optional] To clear Teradata connector property overrides without closing a session, use the following
syntax.
Set foreign server attr = NONE for session volatile;
Remote Table Optimization (RTO)

QueryGrid 2.03 and later Teradata connectors support the Teradata Database Remote Table Optimization
(RTO) feature introduced in Teradata Database 16.10. RTO provides a way to use the remote data source,
rather than the Teradata Database, to process queries involving remote tables.
Note:
Make sure that the RTO feature is enabled in the Teradata Database.
RTO can do the following:

• Limit the data transfer from the remote data source to the Teradata Database
• Help the Teradata optimizer to generate better plans when a remote query is involved
• Reduce query execution time for the Teradata Database
• Lower CPU and IO resource use for the Teradata Database
RTO has the following limitations:
• Multiple remote tables that are joined as a cluster are limited to being inner-joined and must have
equality binding predicates connecting them.
• Aggregations performed on multiple remote tables are not pushed to the remote, even if all the
multiple tables are clustered.
The Teradata connector and Teradata Database optimizer use a push profile to identify an operation that
is executed on the remote. Operations include pushdown, aggregate, and join operations.
When you run the Teradata connector installation script, RTO is available. The script performs the
following actions:
• Inserts default push profile JSON code into the Teradata Database table
• Creates the push profile table, associated functions, and macros under TD_SERVER_DB in the
Teradata Database
The following connector types have default push profiles:
• Hive
• Presto
• Spark
When you configure a Teradata connector for use with RTO, you must select one of the following push
profile properties for the Teradata initiating connector:

• Default Push Profile. The default is recommended for queries with a specific target connector or link.
Query performance depends on how the remote system executes the pushed operation and is based
on the network interfaces and bandwidth. If the remote system performance is slow and causes
undesirable impacts, the default push profile can be replaced with a custom push profile.
• Custom Push Profile. Custom push profiles can be created for site-specific queries that need to be
configured based on data transfer thresholds and transfer speeds. Custom push profiles override
default push profiles.
Note:
Using a push profile does not require changes to the foreign server.
RTO Process
When a query is sent from the Teradata Database to a remote data source, and a push profile is used,
the following occurs:
1. The operation is sent to the remote data source.
Note:
Statistics are collected. The statistics and push profile settings determine whether the
operation is performed on the remote data source.
2. A temporary table is created on the remote data source and the following scenarios apply:
• If delayed fetch is enabled and chosen based on static statistics, dynamic statistics are collected
for the temporary table. The statistics determine whether a remote join or local join is performed
on the temporary table.
• If a remote join is chosen (with or without delayed fetch), the temporary table is exported for a
local join.
3. Statistics about the row count and byte count of the temporary table are collected and sent to the
Teradata Database optimizer for analysis.
4. If the counts are at or below the delayed fetch threshold specified in the push profile, the query result
(the temporary table) is sent to the Teradata Database.
5. If the byte count is greater than the delayed fetch threshold, the dynamic statistics that were collected
are sent to the optimizer. The optimizer then decides whether a local join or remote join is performed.
• If a local join is chosen, the temporary table is brought back in a separate execution phase.
• If a remote join is chosen, the local table is exported, joined with the temporary table on the
remote system, then brought back to the local system.

Default Push Profiles
Teradata Default Push Profile

EXECUTE TD_SERVER_DB.TD_CONN_REGISTER_PUSHPROFILE('TERADATA_V1', 'dummy',
'dummy', 'teradata', 1, new JSON('{
"ColOp": [
{
"default": true,
"array": false,
"CompareOp": {
"default": true
},
"ArithOp": {
"default": true
},
"LogicalOp": {
"default": true
}
}
],
"JoinOp": {
"default": true
},
"AggrOp": {
"default": true
},
"ServerSettings": {
"importCostAdj": 1.00,
"exportCostAdj": 1.50,
"delayedFetchThresh": 0,
"doCluster": true,
"doRemoteJoin": true,
"remJoinTransAdj": 0,
"doMultiTblClustering": true,
"doSingleTblDelayedFetch": false
}
}
'));
Presto Default Push Profile

EXECUTE TD_SERVER_DB.TD_CONN_REGISTER_PUSHPROFILE('PRESTO_V1', 'dummy',
'dummy', 'presto', 1, new JSON('{

"ColOp": [
{
"default":true,
"array":false,
"CompareOp": {
"default": true,
"overlap":false
},
"ArithOp": {
"default": true,
"mod":false
},
"LogicalOp": {
"default": true
}
}
],
"JoinOp": {
"inner": true
},
"AggrOp": {
"count":true,
"sum":true
},
"ServerSettings":{
"doCluster": true,
}
}
'));
Hive Default Push Profile

EXECUTE TD_SERVER_DB.TD_CONN_REGISTER_PUSHPROFILE('HIVE_V1', 'dummy', 'dummy',
'hive', 1, new JSON('{
"ColOp":[
{
"date":true,

"char":true,
"varchar":true,
"byteint":true,
"smallint":true,
"int":true,
"bigint":true,
"decimal":true,
"real":true,
"varbyte":true,
"timestamp":true,
"CompareOp": {
"default":true,
"overlap":false
},
"ArithOp": {
"default": true,
"mod":false
},
"LogicalOp": {
"default":true
}
}
],
"JoinOp": {
"inner":true
},
"AggrOp": {
"count":true,
"sum":true
},
"ServerSettings": {
"doCluster": true,
}
}
'));

Spark Default Push Profile

EXECUTE TD_SERVER_DB.TD_CONN_REGISTER_PUSHPROFILE('SPARK_V1', 'dummy', 'dummy',
'spark', 1, new JSON('{
"ColOp": [
{
"date": true,
"byteint": true,
"smallint": true,
"int": true,
"bigint": true,
"decimal": true,
"real": true,
"varbyte": true,
"timestamp": true,
"CompareOp": {
"default": true,
"overlap": false
},
"ArithOp": {
"default":true,
"mod": false
},
"LogicalOp": {
"default": true
}
}
],
"JoinOp": {
"inner": true
},
"AggrOp": {
"count": true,
"sum": true
},
"ServerSettings": {
"doCluster": true,

}
}
'));
Push Profile Attributes
The attributes of a push profile are described in the following sections. Except where noted, the attributes
are used in default push profiles and custom push profiles. Create custom push profiles and overrides
with the help of a Teradata Customer Support Representative.
<SourceProfile: SourceProfileName,>
<SourceProfile: SourceProfileName,> is the PushProfileID of the default push profile. A default
push profile does not contain this attribute. A custom push profile always points to the PushProfileID
of the default push profile used to create the custom profile.
ColOp
Note:
Changing ColOp is not recommended. Always use the default data type lists provided for Teradata
Database, Presto, Hive, and Spark.
ColOp is an array of data types and the operations that can be pushed to the remote database for a
specified data type. For a disabled data type, none of the expressions/operations are pushed. When a
default is used in ColOp, the expressions/operations are pushed to the remote system for all supported
data types.
The data types and operations that are supported by a corresponding Teradata Database version are
listed using true/false. True means an operation on a data type can be pushed to a remote database.
You can override the default for a data type if a data type is specified.
In the following example, operations/conditions on all data types that can be pushed to the target
connector are supported, except array.
"default":true,
"array":false,
In the following example, only operations/conditions on the following data types are pushed. No other
data types are supported for the link.
"date":true,
"char":true,
"varchar":true,

Attribute Setting
Data type TRUE: When a data type has a true flag, the operation on the data type is pushed to the
remote system.
FALSE: No operation on this data type is pushed to the remote system.
Operation TRUE: When an operation on any data type has a true flag, the operation is pushed to the
remote system.
FALSE: The operation on any data type is not pushed to the remote system for any data
type.
Example operations are:
• CompareOp operations (EQ, NE, LT, and so forth)
• LogicalOp operations (AND, OR, NOT, and so forth)
Note:
All ColOp attributes are subject to the limitations of the target connector. If a target connector does
not support the operation, the operation is not pushed to the remote system.
Example of ColOp attribute and settings:

"ColOp" : [
"default" : true,
"date" : false,
"CompareOp" : { "default" : true },
"LogicalOp" : { "default" : true, "OR" : false },
"ArithOp" : { "default" : true }
],
GroupOp
Note:
Changing GroupOp from the default provided for the target connector is not recommended. For
example, if the default custom push profile states that an inner join is true and an outer join is false,
do not change it.

GroupOp is the name of a group that contains similar operations. When a default is used, it implies that
the default applies to all operations in the group. The value is either TRUE or FALSE.
When a group of similar operations like JoinOp or AggrOp are listed under GroupOp, and the value is
set to TRUE or FALSE:
TRUE: The operation will be pushed to the remote system.
FALSE: The operation will not be pushed to the remote system.
Example of GroupOp operations and settings:
"JoinOp" : { "inner" : true, "outer" : false },
"AggrOp" : { "count" : true, "sum" : true }

Within a group, if the default push profile supports the operation, you can override the default by
specifying a specific operation (Op).
ServerSettings
Server-level settings impact the performance of the query. The cost factors for import and export can
be set for a specific link. In addition, flags can be set to turn on the cluster phase and remote joins for
an operation.
Attribute Setting
doSingleTblDelayedFetch Enables and disables delayed fetch processing for single remote table
clustered query. The default value is FALSE.
FALSE: Delayed fetch is disabled for single table clustering and only
static planning applies.
TRUE: Delayed fetch is enabled for single table clustered query.
Changing the default is not recommended.
doCluster Controls whether to push or not to push aggregation and predicates to

the remote system. The default value is TRUE.
TRUE: Push aggregation and predicates to the remote system.
FALSE: Do not push aggregations and predicates to the remote system.
If the processing power of the remote system is not optimal, the
recommendation is to set this to FALSE. Custom push profiles and
overrides should be done only with the help of a Teradata Customer
Support Representative.
doMultiTblClustering Controls whether multiple remote tables should be joined at the remote
system or if they should be imported to the local system and joined at
the local system. The default value is TRUE.
TRUE: Enable remote join for clustered remote tables.
FALSE: Disable remote join for clustered remote tables. This implies
that tables are imported to the local system and joined at the local
system.
If the processing power of the remote system is not optimal, the
recommendation is to set this to FALSE. Custom push profiles and

Attribute Setting
overrides should be done only with the help of a Teradata Customer

Support Representative.
doRemoteJoin Controls whether remote join is enabled or not; i.e., exporting of a local
table and join with remote table on the target system is allowed or not.
Default value is TRUE.
TRUE: Enables exporting a table from a local system and performing a
join with a table on the remote system.
FALSE: Disables remote join. A table will not be exported to a remote
system for a remote join. Joins are performed on the local system.
If the processing power of the remote system is not optimal, and the cost
of an export to the remote system and a join on the remote system is
higher, it is recommended to update the cost adjustments of import and
export.
Note:
The following attributes are applicable only when doRemoteJoin is set
to TRUE:
• importCostAdj
• exportCostAdj
• remJoinTransAdj
• delayedFetchThresh
importCostAdj Cost of importing one remote table of size ONE unit.

Note:
This attribute applies only when doRemoteJoin is set to TRUE: The
importCostAdj and exportCostAdj factors are relative to each other.
exportCostAdj Cost of exporting one local table of size ONE unit.

Note:
This attribute applies only when doRemoteJoin is set to TRUE: The
importCostAdj and exportCostAdj factors are relative to each other.
remJoinTransAdj Specifies the cost of performing a remote join and importing the result.
The default is 0 and should not be changed. This factor is accounted for
in exportCostAdj.
delayedFetchThresh Specifies the minimum size of a remote table in order to perform a

delayed fetch. In a delayed fetch:
• The remote join is performed on the remote system and the resulting
table is temporarily held at the remote system.
• If the table is at or below the minimum size of the
delayedFetchThresh, the temporary table is exported to the local
system to perform the join.
• If the table is above the minimum size of the delayedFetchThresh,
a remote join is performed on the temporary table on the remote
system, and the joined table is exported to the local system.

Attribute Setting
Note:
If the value is set to zero, delayed fetch is disabled and the temporary
(result) table is exported to the local system to perform the remote join.
TableProfile
TableProfile allows you to override a custom push profile at the table level. It is useful when a set of
operations for a few tables on a remote system are not performing according to expectations. Custom
push profiles and overrides should be done with the help of a Teradata Customer Support
Representative.
Push Profile Defaults
The following defaults are supported for RTO data types and operations for Teradata Database 16.20
and later.
ColOp Data Types

ARRAY
BIGINT
CLOB
BLOB
BYTE
BYTEINT
CHAR
DATE
DECIMAL
INT
INTERVAL
NUMBER
REAL
SMALLINT
TIME
TIME_ZONE
TIMESTAMP
TIMESTAMP_ZONE
VARBYTE
VARCHAR
CompareOP
BETWEEN

EQ
GE
GT
IN
LE
LIKE
LT
NE
NOTIN
OVERLAP
LogicalOP
AND
OR
NOT
ISNULL
ArithOp
ABS
ADD
DIV
LOG10
LOGE
MOD
MUL
SQRT
SUB
AggrOp
AVG
COUNT
MAXIMUM
MINIMUM
SUM
MiscOp
CASE
CAST
CONCAT
DTI
EXTRACT
LOWER
OCTET

SUBSTR
TRIM
UPPER
Server Setting
delayedFetchThresh
doCluster
doMultiTblClustering
doRemoteJoin
doSingleTblDelayedFetch
exportCostAdj
importCostAdj
remJoinTransAdj
Push Profile Macros
The following macros are found in TD_SERVER_DB and are available to display, modify, and drop push
profiles recorded in the table.
• TD_CONN_REGISTER_PUSHPROFILE
• TD_SHOW_PUSHPROFILE
• TD_SHOW_EXPANDED_PUSHPROFILE
• TD_OVERWRITE_PUSHPROFILE
• TD_DROP_PUSHPROFILE
• TD_COPY_PUSHPROFILE
Information on the macros is found at HELP DATABASE TD_SERVER_DB.
Custom Push Profiles
The macros installed with the RTO dip script allow you to create and name custom push profiles for use
with Teradata QueryGrid. A custom push profile can be used to:
• Enable or disable any operation available in the default push profile
• Tune (calibrate) the server settings available in a default push profile
Custom push profiles override default push profiles.
NOTICE
The settings in custom push profiles should be based on workload and the recommendations of
your Teradata Customer Support Representative.

Creating a Custom Push Profile
NOTICE
Base the settings in custom push profiles on workload and the recommendations of your Teradata
Customer Support Representative.
This procedure shows how to use the following macros to create custom push profiles.
• Copy macro (TD_COPY_PUSHPROFILE).
• Overwrite macro (TD_OVERWRITE_PUSHPROFILE).
Hive is used as an example. Use the same steps to create custom push profiles for Teradata and
Presto.
1. Create a custom push profile.
Option Steps
Copy and a. Copy the default push profile and rename it.
Overwrite In the example below, the default push profile HIVE_V1 is copied and renamed
the push Hive_Custom1.
profile EXECUTE TD_COPY_PUSHPROFILE(‘HIVE_V1’, ‘Hive_Custom1’);
b. Update the push profile.
The following example uses the overwrite macro to overwrite an entire existing
custom push profile (Hive_Custom1) with a new JSON specification.
EXECUTE TD_OVERWRITE_PUSHPROFILE('Hive_Custom1', new
JSON(‘{"SourceProfile":"Hive_V1",
"ColOp":[{"timestamp":false,"varbyte":false,"byte":false,
"CompareOp":{"default":true,"GT":false,"LT":false}
"CastOp":{"default":false}}],
"AggrOp":{"count":false}}’))
Query Concurrency on Teradata Database

The Workload Designer portlet does not contain a default Teradata Dynamic Workload Manager
(TDWM) rule to limit query concurrency for the import and export QueryGrid table operators (such as
QGInitiatorImport, QGInitiatorExport, QGRemoteImport, and QGRemoteExport).
It is considered a best practice to create a custom rule in TDWM to set the concurrency limit for these
operators. Teradata recommends that you use a range of 6 to 8 concurrent queries under typical
circumstances. You can increase this limit to 50 or more queries, but you should keep in mind that when
you increase concurrency, there is a cost in terms of query latency. If a rule contains multiple objects of
the same type, then the objects are logically tied together with an OR. It is considered a best practice to
not include objects other than functions when you create throttle rules for the connector table operators.

For information about TASM throttle rules, see Teradata® Database Workload Management User
Guide, B035-1197.
For more detailed information about using Viewpoint Workload Designer, see Teradata® Viewpoint User
Guide, B035-2206.
Tuning Query Concurrency on Teradata Database
1. From the Workload Designer view, click to create a new ruleset.

2. Enter the name of the ruleset and optionally, a description, for the ruleset.
3. Click Save.
4. Click Throttles.
5. Next to System Throttles, click the .
6. On the General tab, enter a name and optionally, a description, for the throttle.
7. Click Save.
8. Click the Classification tab.
9. Select Target from the list and click Add.
10. Select Function from the Target Type list and select TD_SYSFNLIB from the database list.
11. Enter the name of the function and click Include.
The name can be exact or you can use an asterisk (*) as a wildcard to indicate any number of
characters. For example, you can use QGInitiator* to create a single throttle that matches both
QGInitiatorImport and QGInitiatorExport.
12. Click OK.
13. Click Save.
14. Click the State Specific Settings tab.
15. Under Default Settings, click the box and enter the number of queries you want to permit
simultaneously.
• Select Delay to place queries exceeding the limit in a delay queue.
• Select Reject.
17. Click Save.
18. Do the following to activate the ruleset:
a. From the Workload Designer view, click next to the ruleset that you want and select Make
Active.
Using APIs to Monitor Queries Between Teradata and a

Foreign Server
To monitor the data transfer between Teradata and a foreign server per a user request, you can use the
following APIs:

• PM/API MONITOR SESSION
Note:
If you are using the MONITOR SESSION request, set the mon_ver_id to 11, where mon_ver_id
is the monitor software version ID field for the current release.
• Open API MonitorMySessions

• Open API MonitorSession
The APIs return the following values.
Field Name/Column
Description
Name
ReqTblOpBytesIn Total number of bytes transferred into Teradata Database from a foreign
server for the current request through one or more table operators.
Note:
The request may involve one or multiple table operator executions. The
ReqTblOpBytesIn output parameter shows bytes transferred across all
invocations within the request.
ReqTblOpBytesOut Total number of bytes transferred out of Teradata Database and into a foreign
server for the current request through one or more table operators.
Note:
The request may involve one or multiple table operator executions. The
ReqTblOpBytesOut output parameter shows bytes transferred across all
invocations within the request.
Teradata QueryGrid Stored Procedures, Functions, and Table

Operators
Teradata supplies several table operators to import and export data to and from remote systems:
• QGRemoteImport
• QGRemoteExport
• QGInitiatorImport
• QGInitiatorExport
Teradata also provides the QGExecuteForeignQuery table operator to enable DDL and DCL actions on
a remote system, such as CREATE, ALTER, DROP, GRANT, REVOKE, and so on.
QGExecuteForeignQuery is invoked by ExecuteForeignSQL when the user runs a query using
ExecuteForeignSQL.
These table operators are activated from DIP.

ExecuteForeignSQL is a stored procedure that provides a simple interface for the users to execute basic
SQL queries. ExecuteForeignSQL and an install script are provided as part of the Teradata QueryGrid
connector package.
ExecuteForeignSQL
Purpose
The ExecuteForeignSQL stored procedure provides an interface for executing basic SQL queries on
the foreign server. For example, you can use ExecuteForeignSQL to create or drop a table in a database
on the foreign server.
ExecuteForeignSQL passes all SQL queries through, but it does not return results sets, so if you use it
to execute a SELECT or HELP statement, you do not see any results.
ExecuteForeignSQL and an install script are provided as part of the Teradata QueryGrid connector
package. The DBA manually executes the script to install ExecuteForeignSQL and then grants the
appropriate privileges. Before you use ExecuteForeignSQL you create a foreign server using the
QGExecuteForeignQuery table operator in the DO IMPORT WITH clause.
Syntax
CALL ExecuteForeignSQL ( ‘query_expression’ , ‘server_name’ )

;
SYSLIB.
Syntax Elements
SYSLIB.
The name of the database where the stored procedure is located.
query_expression
A valid Teradata SQL expression.
The query is passed through unparsed to the foreign server.
server_name
The name of the foreign server.
Usage Notes
ExecuteForeignSQL provides secure execution by using an embedded table operator along with Trusted
Sessions to handle logon credential verification.
A DBA can selectively GRANT the privilege to use ExecuteForeignSQL.
To call ExecuteForeignSQL, you must first create a foreign server object that specifies the use of the
TD_SYSFNLIB.QGExecuteForeignQuery table operator:

You can only associate one import and one export operator at a time with a foreign server, so to run
ExecuteForeignSQL on an existing foreign server that is being used for queries, you can create a
separate foreign server object with a different name to use for running ExecuteForeignSQL. You must
have EXECUTE FUNCTION and SELECT privileges on this operator.
If you reference a table name, you must prepend it with the schema name.
SQL queries that return result sets, such as SELECT or HELP, are executed on the remote system, but
the resultant rows are not displayed. The query may continue to use CPU, memory and I/O resources
ExecuteForeignSQL uses a proxyuser, so the execution of commands on behalf of DBC is not
supported.
ExecuteForeignSQL can be used with Kerberized clusters.
Example: Using ExecuteForeignSQL

Before you call ExecuteForeignSQL, you must create the foreign server object and specify DO IMPORT
WITH TD_SYSFNLIB.QGExecuteForeignQuery, as shown in the example below.
CREATE FOREIGN SERVER <fs_name>

EXTERNAL SECURITY DEFINER TRUSTED TD_SERVER_DB.<auth_name>
USING
LINK('<linkName>')
version('active')
The example creates a table on the foreign server:
CALL SYSLIB.ExecuteForeignSQL(
'create table tab1(c1 int, c2 string)',
'QG_Presto1');
);
Where QG_Presto1 is the name of the foreign server.
Note:
This example works similarly for remote Teradata, Presto, or Hive. Simply create a foreign server
object (for example, TD_SERVER_DB.HIVE_EFSSP) and call SYSLIB.ExecuteForeignSQL.

Table Operators and Function
QGInitiatorImport
QGInitiatorImport is the initiator import function that is invoked when the query is initiated from Teradata
and needs to access metadata and fetch data from a remote host. This initiator import connector function
is used to import data from any remote host.
QGInitiatorExport
QGInitiatorExport is the initiator export function that is invoked when the query is initiated from Teradata
to access metadata and export data to a remote host. This initiator export connector function is used to
export data to any remote host.
Example: Using QGInitiatorImport and QGInitiatorExport

USING
LINK(‘QG_presto1’)
QGRemoteImport
QGRemoteImport is the remote import function that is invoked when the query is initiated by a remote
host to transfer data to the local Teradata system. This remote import function is used for data transfer
from any remote data source.
QGRemoteExport
QGRemoteExport is the remote export function that is invoked when the query is initiated by a remote
host to access data from the local Teradata system. This remote import function is used to export data
to any remote host.
QGExecuteForeignQuery
QGExecuteForeignQuery is the function that is invoked when a stored procedure is invoked to execute
a DDL or DML request on the remote system. This allows you to execute CREATE TABLE, DROP
TABLE, GRANTs, and so on, from a local Teradata system on the remote host.
Example: Using QGExecuteForeignQuery

CREATE FOREIGN SERVER presto_efssp
USING
LINK(‘QG_presto1’)

QueryGrid Data Transformation
Data Type Mapping for Teradata QueryGrid Connectors
When you query a remote system that runs a target connector that is a different platform from the local
system (initiator) connector, data is converted to satisfy the target database requirements. Even when
the initiator and target connectors are the same, the data is still transformed because the host formats
might be different from each other.
It is important to note the following information about data types:
• The mapping for some data types may not preserve the data in all cases, so be aware that with
some queries, data loss can occur.
As an example, the import of data from Presto with an unlimited VARCHAR size into a limited
Teradata VARCHAR column requires truncation and thus, data loss.
As another example, if you export a Teradata byteint data type as a Boolean and then import it
again, the data may not be the same. This can occur because the Boolean zero or one is imported
while the byteint may have contained other values beyond zero or one.
• If a data type is unsupported on the remote system, and the metadata information retrieved contains
a global type that is not supported on the initiator system, an error is returned from the initiator. For
SELECT * queries with a column containing an unsupported data type, the unsupported column
causes the entire query to return an error. In this case the query must include only the supported
columns in the select list.
• All time-related data types are in UTC.
Teradata Data Type Mapping
Global Types to Teradata Data Types

The initiator connector maps global data types to Teradata data types.
Note:
Teradata data types denoted with an asterisk (*) are only available with Teradata Database 16.20
Feature Update 1 and later.
Global Data Type Teradata Data Type
G_Array Varchar (Character Set Unicode)
G_Array_VC_UTF16 / G_Array_VC_Latin Array *
G_Bigint Bigint

G_Blob Blob
G_Boolean Byteint
G_Byte Byte
G_ByteInt Byteint
G_Char_Kanji1 Char (Character Set Kanji1)
G_Char_KanjiSJIS Char (Character Set KanjiSJIS)
G_Char_Latin Char (Character Set Latin)
G_Char_UTF8 Char (Character Set Unicode)
G_Char_UTF16 Char (Character Set Unicode)
G_Clob_UTF16 / G_Clob_Latin Clob
G_DatasetAvro Dataset storage format Avro *
G_Date Date
G_Decimal Decimal
G_Double Double precision
G_Float Float
G_Integer Integer
G_IntervalDay Interval day
G_IntervalDayToHour Interval day to hour
G_IntervalDayToMinute Interval day to minute
G_IntervalDayToSecond Interval day to second
G_IntervalHour Interval hour
G_IntervalHourToMinute Interval hour to minute
G_IntervalHourToSecond Interval hour to second
G_IntervalMinute Interval minute
G_IntervalMinuteToSecond Interval minute to second
G_IntervalMonth Interval month
G_IntervalSecond Interval second
G_IntervalYear Interval year
G_IntervalYearToMonth Interval year to month

G_JSON_UTF16 / G_JSON_Latin JSON *
G_Map Varchar (Character Set Unicode)
G_MBB MBB *
G_MBR MBR *
G_Number Number
G_Period Period *
G_Row Varchar (Character Set Unicode)
G_SmallInt Smallint
G_STGeometry ST_Geometry *
G_Time Time
G_TimeWithTimeZone Time with time zone
G_Timestamp Timestamp
G_TimestampWithTimeZone Timestamp with time zone
G_UDT_UTF16 / G_UDT_Latin Distinct UDT / Structured UDT *
G_Varbyte Varbyte
G_Varchar_Kanji1 Varchar (Character Set Kanji1)
G_Varchar_KanjiSJIS Varchar (Character Set KanjiSJIS)
G_Varchar_Latin Varchar (Character Set Latin)
G_Varchar_UTF8 Varchar (Character Set Unicode)
G_Varchar_UTF16 Varchar (Character Set Unicode)
G_XML XML *
Others Currently not supported
Teradata Data Types to Global Types

The target connector maps Teradata data types to global data types.
Note:
Teradata data types denoted with an asterisk (*) are only available with Teradata Database 16.20

Teradata Data Type Global Data Type
Array * G_Array_VC_UTF16 / G_Array_VC_Latin
Bigint G_BigInt
Blob G_Blob
Byte G_Byte
Byteint G_Byteint
Char G_Char_UTF16 / G_Char_Latin / G_Char_Kanji1 / G_Char_KanjiSJIS
Clob G_Clob_UTF16/Latin
Dataset storage format Avro * G_DatasetAvro
Date G_Date
Decimal G_Decimal
Distinct UDT/Structured UDT * G_UDT / G_UDT_UTF16 / G_UDT_Latin
Double precision G_Double
Float G_Float
Integer G_Integer
Interval day G_IntervalDay
Interval day to hour G_IntervalDayToHour
Interval day to minute G_IntervalDayToMinute
Interval day to second G_IntervalDayToSecond
Interval hour G_IntervalHour
Interval hour to minute G_IntervalHourToMinute
Interval hour to second G_IntervalHourToSecond
Interval minute G_IntervalMinute
Interval minute to second G_IntervalMinuteToSecond
Interval month G_IntervalMonth
Interval second G_IntervalSecond
JSON * G_JSON_UTF16 / G_JSON_Latin
MBB * G_MBB
MBR * G_MBR
Number G_Number

Teradata Data Type Global Data Type
Period (all period types) * G_Period
Smallint G_SmallInt
ST_Geometry * G_STGeometry
Timestamp G_TimeStamp
Timestamp with time zone G_TimestampWithTimeZone
Varbyte G_Varbyte
Varchar G_Varchar_UTF16 / G_Varchar_Latin / G_Varchar_Kanji1 / G_

Varchar_KanjiSJIS
XML * G_XML
Teradata Connector Limitations

The following limitations affect use of Teradata connectors with Teradata QueryGrid:
• Dataset CSV storage is not supported.
• Transaction semantics between systems is not supported.
After data has been exported and committed to a remote system, any subsequent errors or aborts
on the local system do not roll back the remote request.
• Use of the Returns clause is not supported for Teradata-to-Teradata links.
• Teradata QueryGrid does not collect query metrics (such as CPU usage) for remote Teradata
queries. The remote server sends the SessionID/QueryID through a data execution channel but is
not available for Metadata/Help/Explain queries.
• User mapping with remote user authentication works only for the INVOKER security model.
• When using EXPORT clause queries, the LOB UDT data type cannot be exported if no LOB/LOB
UDTs are imported in the FOREIGN TABLE query.
• The EXPORT clause does not support char/varchar with the Kanji1 character set.
• The maximum size supported for BLOB and CLOB is less than 2GB (2,097,088,000).
• The maximum size of VARCHAR is 64k.
Migrating 1.0x Teradata Foreign Server Definitions to 2.0x

Teradata Connectors
QueryGrid 2.0x Teradata connectors are compatible with the SQL data manipulation language used for
QueryGrid 1.0x Teradata-to-X connectors. In 2.0x, if you want to use the same SQL you use with your
1.0x connectors, you can migrate your 1.0x foreign server definitions for use with 2.0x connectors.

The following procedure preserves the FOREIGN SERVER grants and access rights for users.
1. Stop all queries running on the QueryGrid 1.0x foreign server.
2. For the FOREIGN SERVER used on QueryGrid 1.0x, type the following to display the FOREIGN
SERVER description, the list of custom clauses, and the import and export functions used for the
FOREIGN SERVER:
SHOW FOREIGN SERVER bock_classic2;
CREATE FOREIGN SERVER TD_SERVER_DB.bock_classic2
EXTERNAL SECURITY INVOKER TRUSTED UT1PROXY3 USING
Hosttype ('Teradata')
remotehost ('bock1.labs.teradata.com')
ip_device ('byn1')
port ('5000')
read_timeout (200 )
listen_timeout (60 )
concurrentstreams (1 )
DO IMPORT WITH SYSLIB.LOAD_FROM_TD ,
DO EXPORT WITH SYSLIB.LOAD_TO_TD ;
3. Drop all old NVPs from the QueryGrid 1.0x foreign server.
ALTER FOREIGN SERVER TD_SERVER_DB.bock_classic2 DROP hosttype, drop remotehost,
drop ip_device, drop port, drop read_timeout, drop listen_timeout, drop
concurrentstreams, drop IMPORT, drop EXPORT;
4. Add the new NVPs to the QueryGrid 1.0x foreign server.
AALTER FOREIGN SERVER TD_SERVER_DB.bock_classic2 ADD link(‘bock_ng’), add
IMPORT WITH TD_SYSFNLIB.QGINITIATORIMPORT, add export with
TD_SYSFNLIB.QGINITIATOREXPORT;
5. Show the new 2.0x FOREIGN SERVER.
SHOW FOREIGN SERVER bock_classic2;
CREATE FOREIGN SERVER TD_SERVER_DB.bock_classic2
EXTERNAL SECURITY INVOKER TRUSTED UT1PROXY3 USING
LINK(‘bock_ng’)
DO IMPORT WITH TD_SYSFNLIB.QGINITIATORIMPORT,
DO EXPORT WITH TD_SYSFNLIB.QGINITIATOREXPORT;
For more information about configuring the 2.0x foreign server with QueryGrid 2.0x name value pairs,
see:
• Configuring a Foreign Server and Granting Privileges for a Teradata-to-TargetConnector

7
Using the Presto Connector with Teradata
QueryGrid
Completing the Presto Connector Configuration
After you add and configure a Presto connector and link pairings in a QueryGrid fabric, you must do the
• Configure Presto connectors used as initiators in link pairings
• Configure Presto connectors used as targets in link pairings
• Test installed Presto connectors and links that use a Presto connector as an initiator or target
Presto Connector and Link Properties

Name Value Pairs (NVP). NVPs do the following:
Note:
Property Name Type
16.20+ LOB True On Teradata Databases version 16.20 and later, ● Target
Support the STRING and BINARY columns on Presto are lobSupport
mapped to CLOB and BLOB by default. Unselect
this option to map the STRING and BINARY
columns to VARCHAR and VARBYTE,
respectively.
Authentication None Indicates the authentication mechanism used on Target
Mechanism the target data source.
Valid values are None, Kerberos, and LDAP.
Catalog Name hive Name of the catalog for the Presto connector. ● Target
catalogName

7: Using the Presto Connector with Teradata QueryGrid
Property Name Type
Connection 30 minutes Frequency of eviction checks. Connection objects Target

Evict from the pool are checked, closed, and removed
Frequency if the idle time (current time - last time of use) of a
connection object is greater than the Connection
Max Idle Time setting.
multiple concurrent users running queries to clear
the connections more frequently.
Connection 86400 The maximum idle time for the connection cache Target
Max Idle Time seconds object, after which the object is closed and
running on the system that might lead to starvation
of connection objects.
Connection 100 Maximum number of connection objects that can Target

Pool Size be stored in a connection pool. When acquiring a
new connection, the connector checks for an
available space in the pool. If no space is available
in the connection pool, the connection fails after 5
minutes. Only one connection pool and username
per connector configuration is allowed.
Default Binary 64000 The default truncation size for the VARBINARY ● Target
Size bytes types. defaultBinarySize
Valid values are 1–2097088000 bytes.
This is for a Teradata-to-Presto link and is used by
the target Presto connector and is applicable
when the initiating Teradata Database does not
support BLOB data types with QueryGrid. With
BLOB support, the default binary size is not used.
Default String 32000 The VARCHAR truncation size. ● Target

Size characters This is the size at which data imported from or defaultStringSize
exported to string columns is truncated. The value
represents the maximum number of Unicode
characters to import, and defaults to 32000
characters. Teradata QueryGrid truncates the
string columns at the default value set in
defaultStringSize if less than the actual column
size.
Valid values are 1–1048544000 characters.
This is for a Teradata-to-Presto link and is used by
the target Presto connector and is applicable
when the initiating Teradata Database does not
support the CLOB data type with QueryGrid. With
CLOB support, the default string size is not used.
Disable False When set to true, disables the pushdown of all ● Initiator
Pushdown query conditions to the target system. disablePushdown
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 target system.
To avoid incorrect results caused by condition
pushdown in situations where the settings on the

Property Name Type
initiating system do not match the settings on the

target system, you can disable the pushdown of
all conditions to the target system.
If designated as Overridable, this property can
only be overridden at the session level from false
to true (indicating you are disabling pushdown),
but cannot be changed from true to false.
Enable INFO Logging level for the connector or link properties. Initiator,
Logging User level log settings can be explicitly set Target
through the add or edit link page in the
QueryGrid portlet.
This setting applies to both the initiating and target
connector. The logging level for the initiator
connector in the link, however, takes precedence
if set differently.
DEBUG.
Explain Kind None Defines the flavor of the explain for the EXPLAIN ● Target
SQL statement for a remote Presto query. explainKind
Valid values are logical or distributed.
Keytab None Absolute path to the Kerberos keytab file. Target

QueryGrid only uses the keytab file for
authentication if the user does not provide a
username and password.
Link Buffer 4 Maximum number of write buffers available on a ● Initiator,
Count single channel at one time. linkBufferCount Target
Note:
fabric property shmDefaultNumMemoryBuffers.
Link Buffer Size 1048576 Maximum size of the write buffers to allocate for ● Initiator
row handling and message exchange. linkBufferSize
Link 30000 Handshake timeout in milliseconds for the link Initiator,

Handshake channel setup. Target

Note:
Handshake Timeout.

Port 8090 Sometimes set to 8080. Target

Valid values are 1026–65535. The default value
can be overridden.

Property Name Type
Presto Reader 8 Number of parallel concurrent readers in Presto ● Target

Task per worker per query. prestoReaderTaskConcurrency
Concurrency
Presto Writer 8 Number of parallel writers in Presto or concurrent ● Target
Count writer threads per worker per query. prestoWriterCount
Read Timeout 3600000 Number of milliseconds to wait to read between ● Initiator,

data packets when importing data messages. readTimeout Target
Realm None Kerberos realm. Target

Response 86400000 Number of milliseconds to wait for the final data ● Initiator,
Timeout exec response when all the data has been responseTimeout Target
transferred.
Role Support False Enable user role support for the target system. ● Target
This feature is only available when Presto with roleSupport
Sentry is being used.
When set to true, the user role from the initiator or
target is applied to the target system based on role
mapping, if any. If the cluster is configured to
support roles, errors are returned back to the user.
If the cluster is not configured to support roles,
the user role is not applied.
When set to false, roles are not applied to the
target system.
Schema Name default Name of the schema used for the Presto ● Target
connector. schemaName
Server None Used to connect to the target database as part of Target

the JDBC connection string. This is the IP
address or DNS name of the target host.
SSL Trust or None SSL truststore or keystore password for LDAP or Target
Key Store Kerberos authentication on Presto.
Password
SSL Trust or None SSL truststore or keystore path for LDAP or Target
Key Store Path Kerberos authentication on Presto.
Temporary None Specified database name for creating temporary ● Target
Database tables/views. tempDbName
Name If you do not provide a database name in this
property, QueryGrid creates the temporary view in
the default database assigned to the user.
Username Default Name of the user. Target

username Maximum length is 255 characters.
for the This NVP is saved in the Teradata QueryGrid
connector. Manager configuration and is required when the
initiator does not support a mechanism to provide
user credentials. The username is also used for
connectivity diagnostic checks.
Write Timeout 3600000 Number of milliseconds to wait to write between ● Initiator,
data packets when exporting data messages. writeTimeout Target

Presto Initiator Connector Tasks

If you designated a Presto connector as an initiator connector in any link pairing (for example, a Presto-
to-Teradata link), perform the following tasks:
1. Deploy the Presto connector .jar files using the appropriate installation step:
• Completing the Presto Connector Installation by Running the Installation Script Manually
(Viewpoint 16.10)
• Completing the Presto Connector Installation with the QueryGrid Portlet (Viewpoint 16.20)
• Completing the Presto Connector Installation by Running the Installation Script Manually
(Viewpoint 16.20)
2. Set up the Presto catalog properties file.
Completing the Presto Connector Installation by Running the Installation

Script Manually (Viewpoint 16.10)
If you are upgrading QueryGrid and are using Viewpoint 16.10, use the following procedure to complete
the Presto connector installation.
• Run an installation script that uses presto-admin to unpack and distribute the loader-factory-
version.jar file to the worker nodes
Note:
After the JAR file is successfully installed, Presto restarts.
• Verify the installation

1. Log on to a Teradata QueryGrid Manager TMS, VM, or server.
The QueryGrid Manager TMS, VM, or server can be part of a cluster.
2. From the prompt, run the following script as root or as the tdqgm user.
/opt/teradata/tdqgm/bin/tdqg.sh install-connector
3. From Connectors, enter the number for the Presto connector.
4. From Connector Version, enter the number for the Active or Pending version.
5. From Driver Nodes, enter the number of the driver node you want to use to perform the installation.
6. For the host name listed in Connector Properties, enter the following.
Properties
SSH User root
Password Password for root user
Location of presto-admin /opt/prestoadmin

Properties
Location of Presto installation /opt/presto
The Presto connector components are installed.

7. Verify successful execution of the install.sh script as indicated by lack of displayed errors.
8. [Optional] Verify that the loader-factory-version.jar file is installed to applicable directories:
tdh234m1:~ # ls /usr/lib/presto/lib/plugin/qgplugin/loader-factory-version.jar
Completing the Presto Connector Installation with the QueryGrid Portlet

(Viewpoint 16.20)
When you add a connector to a fabric, QueryGrid performs the following tasks on the initiating node
where Presto (presto-admin) is installed:
• Creates the directories required for completing the installation.
• Installs the Presto connector package. The Presto connector package includes a loader-factory
JAR file.
Use the following procedure to complete the installation and configuration of the Presto connector on
systems with Viewpoint 16.20. During the procedure, you must provide SSH credentials.
Note:
The SSH credentials are not stored in the QueryGrid portlet and are used only to complete the
installation and configuration of the Presto connector.
The procedure includes the following:

• Running an installation script that uses presto-admin to unpack and distribute the JAR files to the
worker nodes
Note:
After the JAR files are successfully installed, Presto restarts.
• Verifying the installation

1. Make sure the connector package has been downloaded from Teradata's software download site
and uploaded to the QueryGrid portlet, and that the connector has been added to the fabric.
3. Click the fabric containing the initiating node where Presto (presto-admin) is installed.
4. Select Connectors tab.
5. Click next to the Presto initiating connector for the initiating node and select Install.
6. From Connector Installation, select one of the following:

• Active
• Pending
7. In the Select driver node list, select the driver node you want to use to run the installation script.
8. To allow the installation script to run, provide the following information:
Option Description
Host: Type the host name of the master node where Presto is installed (the initiator
master node where you want to install the JAR files).
Note:
Do not use the IP address.
SSH User: Type root.
Password Type the password for the root user.
Presto Admin Type the name of the directory where Presto (presto-admin) is installed on the
Location Master Node. The default installation directory is:
/opt/prestoadmin/
Presto Install Type the name of the directory to install the JAR files. The default is:
Location /usr/lib/presto/
9. Click Run.
10. Verify successful installation by checking that the driver node specified in the Select driver node
list is represented in the Success field.
If the installation is successful, the JAR files are distributed to the worker nodes. When installation
is complete, Presto restarts.
Note:
If an error halts the installation, Presto does not restart.
11. [Optional] Log on as an Administrator on the worker nodes and verify that the loader-factory-
version.jar file is installed to applicable directories:
Completing the Presto Connector Installation by Running the Installation

Script Manually (Viewpoint 16.20)
When completing the Presto connector installation on systems with Viewpoint 16.20, if you do not want
to provide SSH credentials in the QueryGrid portlet, use the following procedure to:
• Run an installation script that uses presto-admin to unpack and distribute the loader-factor-
version.jar file to the worker nodes.

Note:
After the JAR files are successfully installed, Presto restarts.
Note:
As of QueryGrid 2.06, the presto qgremote and qginitiator JAR files are combined in the
loaderfactory JAR file.
• Verify the installation.

1. Log on as an Administrator on the node where Presto (presto-admin) is installed.
2. Change the directory:
cd /opt/teradata/tdqg/connector/tdqg-presto-connector/presto-connector-software-
version/bin
For example:
tdh234m1:~ # cd /opt/teradata/tdqg/connector/tdqg-presto-connector/
02.07.00.00/bin
3. Run ./install.sh.
The script deploys the .jar files to the /usr/lib/presto/lib/plugin directory and invokes the
presto-admin utility to restart Presto.
4. Verify successful execution of the install.sh script as indicated by lack of displayed errors.
5. [Optional] Verify that the loader-factory-version.jar file is installed to applicable directories:
Setting Up the Presto Initiator Catalog Properties File
You define catalog properties for the Presto connector in a properties file that is manually created and
edited. This is different than the Teradata connector properties, which are defined using the QueryGrid
portlet.
The Presto catalog properties file references a data source and maintains the set of properties
associated with that data source connector. You can have one or more catalogs per connector. The
Presto connector can have multiple initiator catalogs, one for each link and version pair. The catalog
properties file is analogous to the CREATE FOREIGN SERVER statement for the Teradata connector.
After manually editing the file, you must restart the Presto server for the new configuration to take effect.
Do the following to configure the Presto catalog properties file:
1. Log on as an Administrator to the master node of the Hadoop cluster where Presto is installed.
2. Create and edit an initiator catalog properties file: ~/.prestoadmin/catalog/name.properties.

For example, create and edit a file named tdh234m1sdld0461_active.properties. Add the
following content to the file:
connector.name=qginitiator
qginitiator.linkName=tdh234m1sdld0461
qginitiator.version=active
3. Run presto-admin catalog add name to deploy the properties file on all nodes.
For example:
presto-admin catalog add tdh234m1sdld0461_active
4. Restart the Presto cluster.
Run:
presto-admin server restart
5. From Presto CLI use the SHOW CATALOGS command to verify the newly created properties file
exists.
Run:
tdh234m1:~ # presto-cli --server localhost:8090
presto:testuser> show catalogs;
Result:
Catalog
-------------------------
hive
qginitiator
qgremote
system
tdh234m1sdld0461_active
tpch
Presto Target Connector Tasks

If you designated a Presto connector as a target connector in any link pairing (for example, a Teradata-
to-Presto link), use one of the following procedures to deploy the Presto loader-factory-version.jar
files:
• Completing the Presto Connector Installation with the QueryGrid Portlet (Viewpoint 16.20)
• Completing the Presto Connector Installation by Running the Installation Script Manually (Viewpoint
16.20)
Testing Presto Connectors and Links

After completing the tasks required to configure Presto initiator connectors, target connectors, and links
that use a Presto connector as initiator or target, do the following to test connectivity:

1. Run a connector diagnostic check to validate connectivity with a data source.

2. Run a link diagnostic check for all links that use a Presto connector as an initiator or target.
3. Run a link bandwidth test for all links that use a Presto connector as an initiator or target.
4. Validate the connections between data sources for all Presto-to-TargetConnector links.
Validating a Presto-to-TargetConnector Link
Complete these steps to verify a Presto-to-TargetConnector link (where TargetConnector is any type of
target connector). For example, for a Presto-to-Teradata link:
1. Log on as the Presto user to the Hadoop master node on which the Presto connector is installed.
2. Confirm setup of the Presto-to-TargetConnector link properties file by invoking the Presto CLI,
then running SHOW CATALOGS. For example, for a Presto-to-Teradata connector link:
tdh234m1:~ # presto-cli --server localhost:8090
presto> use hive.testuser;
presto:testuser> show catalogs;
The following output indicates that the Presto-to-Teradata link properties file
tdh234m1sdld0461_active is set up and recognized as a catalog by Presto:
Catalog
-------------------------
hive
qginitiator
qgremote
system
tdh234m1sdld0461_active
tpch
3. Retrieve all databases on a Teradata system by running SHOW SCHEMAS FROM <catalog_name>.
For example:
presto:testuser> show schemas from tdh234m1sdld0461_active;
The following output indicates retrieval of all databases including system databases that reside on
the target Teradata system:
Schema
-------------------------
PUBLIC
SQLJ
SYSBAR
…
testuser
…

4. Retrieve all tables in a Teradata database by running SHOW TABLES FROM

<catalog_name>.<schema_name>. For example:
presto:testuser> show tables from tdh234m1sdld0461_active.testuser;
The following output indicates retrieval of all tables in the testuser database that reside on the target
Teradata system:
Schema
-------------------------
testtable1
testtable2
…
Presto Connector Privileges and Security
Presto Initiator Connector Security and User Sessions
Each type of Teradata QueryGrid connector uses different mechanisms for authenticating the local user
Presto supports Kerberos authentication and LDAP. Presto user credentials are stored in the Username
and Password properties in the connector or link settings in Teradata QueryGrid. For information about
setting Username and Password in the QueryGrid portlet, see Presto Connector and Link Properties
and Adding a Connector.
Apache Sentry support has been added starting with Presto 208t. For information on setting up Presto
with Sentry, see https://docs.starburstdata.com/latest/security/sentry.html.
Presto Target Connector Security Guidelines
LDAP
A Presto target connector can be configured to use LDAP authentication.
For more information about setting up the Presto LDAP configuration, see Teradata Presto
Documentation available from http://www.info.teradata.com: Teradata for Hadoop > Teradata
Distribution of Presto > Teradata Distribution of Presto.
Currently, QueryGrid only supports simple LDAP authentication mechanism involving username and
password. The Presto target connector sends a username and password to the internal coordinator
code, and it validates these credentials using an external LDAP service. Both Active Directory and Open
LDAP are supported. Presto requires Secure LDAP (LDAPS), so make sure you have TLS enabled on
your LDAP server. Presto documentation on how to configure Presto to enable LDAP authentication
over HTTPs can be found at http://teradata.github.io/presto/docs/current/security/ldap.html.
The following property settings are required for Presto target connectors using the LDAP security model.

Setting Description
Port Set to the HTTPS server port, or to the value of the http-server.https.
port value in the presto config.properties file.
Authentication Mechanism Set to LDAP.
Username Set to the LDAP user name.
Password Set to the LDAP user password.
SSL Trust or Key Store Set to the Java trust store or Key Store absolute path.
Path
SSL Trust or Key Store Set to the password for the Java trust store or Key Store file you entered
Password into the SSL Trust or Key Store Path property.
For more information, see Presto Connector and Link Properties.
Kerberos
You can set up QueryGrid to use Kerberos authentication with the Presto target connector; it uses two
forms of authentication with Kerberos:
Username/Password
The Presto target connector authenticates the username and password against Kerberos
before sending the query to the data source.
Kerberos Keytab
Presto can be configured to enable Kerberos Keytab authentication.
Kerberos Authentication Setup
When using Kerberos authentication, a principal can be authenticated using a username and password
or a Keytab file. Presto Kerberos setup instructions can be found at http://teradata.github.io/presto/
docs/current/security/server.html. The driver node on the remote server establishes Kerberos
authentication; the Presto connector is configured with the location of the needed file.
The following property settings are required for Presto target connectors using the Kerberos security
model.
Setting Description
Port Set to the HTTPS server port, or to the value of the http-server.https.
port value in the presto config.properties file.
Authentication Set to Kerberos.

Mechanism
Username Set to the Kerberos principal name.
Password Set only if the Kerberos principal should be authenticated using a password.

Setting Description
Realm Set to the Kerberos realm if the Kerberos principal in the username property
does not already contain the realm.
Keytab Set to absolute path of Keytab file only if the Kerberos principal should be
authenticated using Keytab.
Note:
If both the Password and Keytab connector properties contain values,
then the Password setting takes precedence.
SSL Trust or Key Set to the Java trust store or Key Store absolute path.
Store Path
SSL Trust or Key Set to the password for the Java trust store or Key Store file you entered
Store Password into the SSL Trust or Key Store Path property.
For more information about setting up the Presto Kerberos configuration, see Teradata Presto
Documentation available from http://www.info.teradata.com: Teradata for Hadoop > Teradata
HTTPs must be configured for LDAP or Kerberos enabled Presto clusters. See https://
teradata.github.io/presto/docs/current/security/tls.html.
Kerberos Maintenance
You must update the configuration of Teradata QueryGrid if the name or location of the default Kerberos
realm or the location of the host for your KDC (Key Distribution Center) or administration server
changes.
Presto Target Connector Privileges
For Presto queries, QueryGrid creates tables with no data under the temporary database. Users require
CREATE TABLE and DROP TABLE access to the temporary database when running Teradata initiator
FOREIGN TABLE or EXPLAIN queries.
Using the Presto Connector

You can install and configure the Presto connector on independent nodes to access Hadoop data remotely
from the HDFS or you can install and configure it on Hadoop nodes.
Ambari is used for the administrative monitoring of Hive.
Presto has its own monitoring system. You can also use the Viewpoint Query Monitor portlet to monitor
the queries that pass through the Presto connector. For more information, see Teradata® Viewpoint User
Guide, B035-2206.

For detailed information about configuring the Teradata Distribution of Presto, see the related
documentation available from http://www.info.teradata.com: Select Teradata for Hadoop > Teradata
SQL Syntax for the Presto Connector

Teradata QueryGrid supports the following SQL statements from a Presto connector node:
• SELECT
• INSERT
• SHOW SCHEMAS, SHOW TABLES, SHOW COLUMNS, SHOW CATALOGS
• DESCRIBE
SQL syntax used with the Presto connector differs from Teradata SQL syntax. One notable change is
that you must qualify a table with its catalog, for example: QGNG.salesdb.sales. QGNG is the catalog
name, salesdb is the schema name, and sales is the table name.
The names of catalogs, schema, tables, and columns are not modified by Teradata QueryGrid unless
either the local system or the remote system is unable to support the name in its native format. This
includes uppercase, lowercase, and mixed case, as well as multi-byte names in language character sets.
SQL Command Reference for the Presto Connector
SELECT Syntax for the Presto Connector
You can use catalog_name.schema_name.table_name in the SELECT statements of your queries. If

you do not specify a database, it defaults to the database that is configured for the connector properties
in the QueryGrid portlet.
You can use this foreign server grammar in joins and any other place that you reference a normal table,
including views, macros, and stored procedures.
Logical expressions such as AND, OR, GT, LT, LE, GE, EQ, ISNULL, IS NOT NULL, IN, and NOT IN
are supported pushdown predicates.
For data type mappings from Teradata to Presto and Presto to Teradata, see QueryGrid Data
Transformation.
Example: Presto to Teradata SELECT

The example shows an import initiated on Presto to fetch data from a remote Teradata system. The
query predicates to be pushed are provided to the connector in the Constraint class by the Presto server
and used for pushdown to the remote Teradata system.
SELECT MAKE, MODEL FROM QG_TD1.DB1.TD_CARDATA WHERE MAKE = 'BUICK';

make model
------ --------------------
Buick Century
Buick Enclave
Where QG_TD1 is the catalog used to reference the Presto-to-Teradata link. DB1 is the database or
schema name on the remote system, and TD_CARDATA is the table on the remote system.
Example: Teradata-to-Presto SELECT From Foreign Table with EXPORT

The example initiates a SELECT From Foreign Table with EXPORT request from Teradata to Presto.
The Presto target connector creates a temporary table on the target Presto system, exports the data
from the local Teradata Database, and imports the result of the join or aggregation query into the
Teradata Database. In the example the remote table that is created is named pricetemp.
SELECT * FROM FOREIGN TABLE(SELECT p.make, SUM(quantity * price)

FROM pricetemp p, store.inventory q
WHERE p.itemid = q.itemid GROUP BY p.partno)@presto1
EXPORT((select * from monthlyprice) as pricetemp) as dt;
INSERT Syntax for the Presto Connector
You can use Presto to export data to a remote system by using an INSERT statement to place data into
an existing table. The remote table can be empty or it can contain data. If the remote table already
contains data, the exported data is appended to the existing table.
Example: Presto to Teradata INSERT

The example shows an export request initiated on Presto to insert data into a remote Teradata Database
table.
INSERT INTO QG_TD1.DB1.TD_CARDATA SELECT * from hive.default.cardata;
QG_TD1 is the catalog used to reference the Presto-to-Teradata link, DB1 is the Teradata Database, and
TD_CARDATA is the table to insert to on Teradata Database.
SHOW Syntax for the Presto Connector
The Presto SHOW statement provides the details of schemas/databases, tables, and table columns on
local or remote systems. The SHOW CATALOGS statement lists the contents of the Presto catalog. The
following statements are available:
• SHOW SCHEMAS FROM <catalog_name>;
• SHOW TABLES FROM <catalog_name>.<schemaname>;
• SHOW COLUMNS FROM <catalog_name>.<schemaname>.<tablename>;

• SHOW CATALOGS;
• DESCRIBE <catalog_name>.<schema_name>.<tablename>;
The Presto DESCRIBE statement is an alias for the Presto SHOW COLUMNS statement and returns
the same information.
The Presto SHOW statement is equivalent to the HELP FOREIGN statement used when Teradata is
the initiator. For more information, see Examples of Using HELP FOREIGN.
Example: Presto to Teradata SHOW SCHEMAS

The example fetches the schema (databases) from the remote Teradata system. QD_TD1 is the catalog
used to reference the Presto-to-Teradata link.
presto:default> SHOW SCHEMAS FROM QG_TD1;
Example: Presto to Teradata SHOW TABLES

The example fetches the list of tables from the specified database (<schemaname>) on the remote
Teradata system.
presto:default> SHOW TABLES FROM QG_TD1.<schemaname>;
Example: Presto to Teradata SHOW COLUMNS

The example fetches the column information from the specified table (<schemaname>.<tablename>)
on the remote Teradata system.
presto:default> SHOW COLUMNS FROM QG_TD1.<schemaname>.<tablename>;
Note:
The Presto DESCRIBE <catalog_name>.<schema_name>.<tablename> statement can be used
instead of SHOW COLUMNS.
Example: Presto SHOW CATALOGS

The example lists the registered catalogs. It does not invoke a Teradata QueryGrid query.
presto:default> SHOW CATALOGS;
Result:
Catalog
----------------
hive
qginitiator
qgremote
system

QG_TD1
tpch
Note:
The Presto-to-Teradata catalog called QG_TD1 is listed as well as the rest of the registered
catalogs.

Designating a Presto connector property as overridable in the QueryGrid portlet allows users to override
configured Presto connector properties when starting queries during an individual processing session.
Presto catalogs can define their own properties. You can view these properties using the show session
command. This example shows the Presto session property called override in the Presto QueryGrid
catalog p2p_active.
presto:default> show session;

Name |Value|Default| Type |
-------------------+---------------------------------------------------------
p2p_active.override| | | varchar| Properties to p2p_active.override
-----------------------------------------------------------+
for QG connector. Of form [name]=[value];[name]=[value];...
Option Description
To override a Presto a. Click the Connectors tab.

the Connectors tab
c. Select Edit.
e. Find the Presto connector property you want to override and click the
f. Click OK.
g. Click Save.
To override a Presto a. Click the Links tab.

the Links tab
c. Select Edit.
e. Find the Presto link property you want to override and click the
f. Click OK.
g. Click Save.

4. To override the Presto connector property during a Presto session, use the syntax in the following
example.
set session p2p_active.override =
‘<prop1>=<overrideVal1>;<prop2>=<overrideVal2>;…’;
For example:
SET SESSION p2p_active.override='responsetimeout =
3000000;linkBufferCount=3;';
presto:default> show session;
Name | Value |Default
--------------------+---------------------------------------------+-------
p2p_active.override| responsetimeout = 3000000;linkBufferCount=3; |
| Type |
+-----------------------------------------------------------------------
|varchar|Properties to override for QG connector. Of form [name]=[value];
---------------
[name]=[value];
5. [Optional] To clear Presto connector property overrides without closing a Presto session, use the
syntax in the following example.
reset session p2p_active.override;
When you query a remote system that runs a target connector that is a different platform from the local
system (initiator) connector, data is converted to satisfy the target database requirements. Even when
the initiator and target connectors are the same, the data is still transformed because the host formats
might be different from each other.
As another example, if you export a Teradata byteint data type as a Boolean and then import it
again, the data may not be the same. This can occur because the Boolean zero or one is imported
while the byteint may have contained other values beyond zero or one.

Presto Data Type Mapping
Global Types to Presto Data Types

The initiator connector maps global data types to Presto data types.
Note:
Global Data Types denoted with an asterisk (*) are only available with Teradata Database 16.20
Global Data Type Presto Data Type
G_Array Array
G_Array_VC_UTF16 / G_Array_VC_Latin * Array
G_Bigint Bigint
G_Blob Varbinary
G_Boolean Boolean
G_Byte Varbinary
G_ByteInt Tinyint
G_Char_UTF8 Char(n)
G_Char_UTF16 Char(n)
G_Clob_UTF16/Latin Varchar
G_Date Date
G_Decimal Decimal
G_Double Double
G_Float Real
G_Integer Integer
G_JSON_UTF16 / G_JSON_Latin * Varchar
G_Longvargraphic Varchar(n)
G_Map Varchar (Character Set Unicode)
G_Number Decimal

Global Data Type Presto Data Type
G_Row Row
G_SmallInt Smallint
G_STGeometry * Varchar
G_Time Time
G_TimestampWithTimeZone Time with time zone
G_Varchar_Latin Varchar(n)
G_Varchar_UTF8 Varchar(n)
G_Varchar_UTF16 Varchar(n)
G_Varchargraphic Varchar(n)
G_XML * Varchar
Presto Data Types to Global Types

The target connector maps Presto data types to global data types.
Presto Data Type Global Data Type
Array G_Array
Bigint G_BigInt
Boolean Boolean
Char(n) G_Char_UTF16
Date G_Date
Decimal G_Decimal
Double G_Double
Integer G_Integer
Interval day to second G_IntervalDayToSecond
Interval hour G_IntervalHour
Interval year to month G_IntervalYearToMonth
Json G_Json

Presto Data Type Global Data Type
Map G_Map
Row G_Row
Smallint G_SmallInt
Time G_Time
Times with time zone G_TimeWithTimeZone
Timestamp with time zone G_TimeStampWithTimeZone
Tinyint G_Tinyint
Varbinary G_Blob
Varchar G_Clob_UTF16/Latin
Varchar(n) G_Varchar_UTF16
Presto String and Binary Types Considerations

Presto connector has a restricted maximum size for the following column types:
• BLOB – 2GB
• CLOB – 2GB-1
• VARCHAR – 64k
Due to the in-memory nature of these types, a large amount of resources are required on the Presto
side when their sizes near 1.7GB. Therefore, caution is advised when inserting large Teradata CLOB
or BLOB columns into the Presto string or binary columns when using QueryGrid.
Note:
Teradata testing has found that Presto contains the exchange.http-client.max-content-length
property which needs to be set high enough for Presto to transfer a large data page. There is a
known limit in current Presto release which limit CLOB and BLOB data to 1.7GB.
Presto Connector Limitations

The following limitations affect the use of Presto connectors with Teradata QueryGrid:
• Use of Presto is limited to queries that can be performed in memory, so some queries may not be
able to run in Presto that would run in Hive.

• Presto does not support roles and access control unless Sentry is enabled.
• Teradata QueryGrid does not support TimeWithTimeZone and TimestampWithTimeZone data types
with Presto connectors.
• When using the Explain command with a Presto initiator connector, remote query and execution plan
data is not returned.
• The default for Timestamp precision is three (3); Teradata QueryGrid truncates data with more than
three decimal places.
• When using Predicate pushdowns, Array, Time, TimeWithTimeZone, Timestamp, and
TimestampWithTimeZone data types are not pushed down.

8
Using the Hive Connector with Teradata
QueryGrid
Completing the Hive Connector Configuration
After you add and configure a Hive connector and link pairings in a QueryGrid fabric, you must do the
• Configure Hive connectors used as initiators in link pairings
• Configure Hive connectors used as targets in link pairings
• Test installed Hive connectors and links that use a Hive connector as an initiator or target
Hive Connector and Link Properties

Note:
Property Name Type
16.20+ LOB True On Teradata Databases version 16.20 and ● Target

Support later, the STRING and BINARY columns on lobSupport
Hive are mapped to CLOB and BLOB by
default. Unselect this option to map the
STRING and BINARY columns to
VARCHAR and VARBYTE, respectively.
Authentication None Authentication mechanism used on the Target

Mechanism target data source.
Valid values are None, Kerberos, and
HS2Only.

8: Using the Hive Connector with Teradata QueryGrid
Property Name Type
Collect False Displays the approximate number of rows ● Target

Approximate exported to the target data source. collectActivityCount
Activity Count When set to false, the activity count displays
a 1. When set to true, an approximate activity
count is returned. The default is false.
Compression System Compression type to use when exporting to ● Target

Codec Default a Hive table. Valid values are System compressionCodec
Default, Deflate, BZip2, Gzip, LZ4, and
Snappy.
Conf File Paths /etc/ Paths to core-site.xml , hdfs-site. Target

hadoop/ xml , and hive-site.xml in a comma-
conf/, separated list.
/etc/hive This is a required setting.
/conf
Connection 30 minutes Frequency of eviction checks. Connection Target

Evict objects from the pool are checked, closed,
Frequency and removed if the idle time (current time -
last time of use) of a connection object is
greater than the Connection Max Idle Time
setting.
multiple concurrent users running queries to
clear the connections more frequently.
Connection 86400 The maximum idle time for the connection Target
Max Idle Time seconds cache object, after which the object is closed
and removed from the cache. Use this
property when there are multiple concurrent
users and queries running on the system
that might lead to starvation of connection
objects.
Connection 100 Maximum number of connection objects that Target

Pool Size can be stored in a connection pool. When
acquiring a new connection, the connector
checks for an available space in the pool. If
no space is available in the connection pool,
the connection fails after 5 minutes. Only
one connection pool and username per
connector configuration is allowed.
Custom JAR None Specifies the path or paths to use for .jar Target
Path files not listed in Hadoop JAR Files. Enter
paths in a comma-separated list. See
Configuring the Hive Connector for Use with
a Custom Hadoop Library Path or Custom
JAR Path.
Database Default Name of the database for the connector, if ● Target

Name not provided in the user query. databaseName

Property Name Type
Maximum name length is 255 characters.
Default Binary 64000 The default truncation size for the ● Target
Size bytes VARBINARY types. defaultBinarySize
This is for a Teradata-to-Hive link and is used
by the target Hive connector and is
applicable when the initiating Teradata
Database does not support BLOB data types
with QueryGrid. With BLOB support, the
default binary size is not used.
Default String 32000 The VARCHAR truncation size. ● Target

Size characters This is the size at which data imported from defaultStringSize
or exported to string columns is truncated.
The value represents the maximum number
of Unicode characters to import, and
defaults to 32000 characters. Teradata
QueryGrid truncates the string columns at
the default value set in defaultStringSize if
less than the actual column size.
This is for a Teradata-to-Hive link and is used
by the target Hive connector and is
applicable when the initiating Teradata
Database does not support CLOB data
types with QueryGrid. With CLOB support,
the default string size is not used.
Disable False When set to true, disables the pushdown of ● Initiator

Pushdown all query conditions to the target system. disablePushdown
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
target system.
To avoid incorrect results caused by
condition pushdown in situations where the
settings on the initiating system do not match
the settings on the target system, you can
disable the pushdown of all conditions to the
target system.
If designated as Overridable, this property
can only be overridden at the session level
from false to true (indicating you are
disabling pushdown), but cannot be
changed from true to false.
Enable INFO Logging level for the connector or link Initiator,

Logging properties. User level log settings can be Target
explicitly set through the add or edit link
page in the QueryGrid portlet.
This setting applies to both the initiating and
target connector; however, the logging level

Property Name Type
for the initiating connector in the link takes

precedence if they are set differently.
DEBUG.
Hadoop Default Required if Hadoop uses a custom Target

Library Path Hadoop installation path instead of the default
library path Hadoop path or if any Hadoop .jar files are
saved outside of the default Hadoop library.
Enter paths in a comma-separated list. See
Configuring the Hive Connector for Use with
a Custom Hadoop Library Path or Custom
JAR Path.
If no custom information is available, the
default Hadoop library path is used.
Hadoop None Specifies Hadoop environment properties ● Target

Properties for a user session. Properties are provided hadoopProperties
in a list. Use = between each property and
its value (name=value, name=value,
name=value), and a comma as a separator
between properties, with or without a space
after the comma.
For example:
mapred.job.queue.name=abcdef,
mapreduce.task.timeout=3600000,
mapreduce.map.speculative=false
If Hadoop Properties is not selected, the
default Hadoop environment properties are
used.
Hive mr Hive execution engine to use. ● Initiator,

Execution Valid values are mr, tez (HDP only), or spark hiveEngine Target
Engine (CDH only).
Hive Kerberos None Overrides the principal name in hive-site. Target

Principal xml.
HiveServer2 False Indicates whether HS2 High Availability is Target

HA Enabled enabled.
Keytab None Absolute path to the Kerberos keytab file. Target

QueryGrid only uses the keytab file for
authentication if the user does not provide
a username and password.
Knox None Password for the Knox connection. Target

Connection
Password
Knox None Username for the Knox connection. Target

Connection
Username
Knox Context None Knox context path for HS2, for example, Target
Path gateway/mycluster/hive
Required only if Knox is used.

Property Name Type
Knox Gateway None Knox gateway host. The use of this property Target
Host indicates that Knox is enabled.
Knox Gateway 8443 Knox gateway port number. Target

Port Valid values are 1024–65535.
Knox Trust None Knox gateway trust store path. Target

Store Path Required only if Knox is used.
Knox Trust None Knox gateway trust store password. Target

Store Required only if Knox is used.
Password
Link Buffer 4 Maximum number of write buffers available ● Initiator,

Count on a single channel at one time. linkBufferCount Target
Note:
Link Buffer Count overrides the default
internal fabric property
shmDefaultNumMemoryBuffers.
Link Buffer 1048576 Maximum size of the write buffers to ● Initiator

Size allocate for row handling and message linkBufferSize
exchange.
Link 30000 Handshake timeout in milliseconds for the Initiator,

Handshake link channel setup. Target

Note:
Handshake Timeout.
Number of None For Hive-on-Spark only. Controls the ● Initiator,

Cores per number of concurrent tasks an Executor numExecutorCores Target
Executor can run. If a value is not specified, the
system default is used.
Number of None Units of parallelism to use when data is ● Initiator,

Mappers exported or imported to Hive. This is the numMappers Target
number of mappers (equivalent to
containers) on the cluster. It defines
maximum parallelism per cluster per query.
This is applicable when data is being
exported or imported to Hive using a
TargetConnector-to-Hive export or Hive-to-

Property Name Type
TargetConnector import (where

TargetConnector is any type of connector).
The following are intended to be
conservative starting values:
• Hive as either initiator or target: 3 multiplied
by the number of data nodes in the
Hadoop cluster
Consider increasing these numbers
significantly based on the available
resources on the Hadoop cluster, as well as
the nature of the queries you are performing.
For Hive-on-Spark, system default is used
if a value is not specified.

Used only if Kerberos or HS2-only security
is used.
Port 10000 Valid values for Hiveserver 2 are 1026– Target

65535.
Queue Name None Name of the queue that submits the MR, ● Initiator,
Tez (HDP only), or Spark (CDH only) job. queueName Target
Read Timeout 3600000 Number of milliseconds to wait to read ● Initiator,

between data packets when importing data readTimeout Target
messages.
Response 86400000 Number of milliseconds to wait for the final ● Initiator,

Timeout data exec response when all the data has responseTimeout Target
been transferred.
Role Support False Enable user role support for the target ● Target
system. roleSupport
When set to true, the user role from the
initiator or target is applied to the target
system based on role mapping, if any. If the
cluster is configured to support roles, errors
are returned back to the user. If the cluster
is not configured to support roles, the user
role is not applied.
When set to false, roles are not applied to
the target system.
Server None Used to connect to the target database as Target

part of the JDBC connection string. This is
the IP address or DNS name of the target
host.
Spool File Path /var/opt/ Local path to use for spool files if the fabric Both
teradata/ is enabled to support Hive Task Retries.
tdqg/fabric
/data/

Property Name Type
Note:
When a custom path is specified, the
specified directory must be present on all
Hadoop data nodes configured in a
QueryGrid cluster. The directory must have
read, write, and execute permissions to
create, read, and write files and sub
directories for the querygrid OS group and
the tdqg OS user.
SSL Key Store None Specifies the SSL password when SSL is Target
Password enabled for hiveserver2.
• For CDH, you must provide the SSL
password.
• For HDP, the Hive connector loads the SSL
password from hive-site.xml. You can
use this property to specify a different
password.
SSL Key Store None Used to specify the key store path where Target
Path the SSL username and password are
stored when SSL is enabled for
hiveserver2.
• For CDH, you must provide the SSL path.
• For HDP, the Hive connector loads the SSL
path from hive-site.xml. You can use
this property to specify a different path.
Support Hive False When set to true, the fabric is enabled to Both
Task Retries support Hive Task Retries. When enabled,
the fabric does not fail on the query when
Hive tasks are retried. Instead, it discards
the data received from a failed task attempt
and continues to process task data from the
retried attempt.
Note:
This feature is only supported when Hive is
the data source, where Hive is importing
data as a target or exporting data as an
initiator, and the execution engine is mr or
tez.
Temporary Default Temporary database name for storing ● Target

Database temporary tables and views. tempDbName
Name
Username Hive Name of the user. A username added for a Target

connector or target connector link must be
included in Allowed OS users.
This NVP is saved in the Teradata QueryGrid
Manager configuration and is required when
the initiator does not support a mechanism
to provide user credentials. The username is
also used for connectivity diagnostic checks.

Property Name Type
Write Timeout 3600000 Number of milliseconds to wait to write ● Initiator,

between data packets when exporting data writeTimeout Target
messages.
Hive Initiator Connector Tasks

If you designated a Hive connector as an initiator connector in any link pairing (for example, a Hive-to-
Teradata link), perform the following tasks:
1. Configure primary group for Hive users (CDH only).
2. Configure non-native table.
Configuring the Primary Group for Hive Users (CDH Only)
If you are using a Hive connector on a Cloudera implementation of Hadoop and want to enable logging,
you must change the primary group for Hive users to make sure QueryGrid infrastructure logging
functions work properly on CDH clusters.
If you are using a Hive connector on any Kerberized Hadoop cluster and want to enable logging, each
user corresponding to a Kerberos principal must also have the primary group of ‘hadoop’.
Note:
This task is only required if you want to enable logging.
1. Run the following command in Linux:

cmdall usermod -g hadoop hive
Configuring a Non-Native Table for a Hive-to-Target Connector
The Hive Storage Handlers framework is used for the Teradata QueryGrid Hive initiator connector.
Storage handlers allow Hive to access data stored on other systems. A Hive table created using a
storage handler is referred to as a non-native table.
Hive storage handlers operate at the table level, so one non-native table must be created for each remote
table, unlike Teradata Foreign Servers and Presto Catalogs that operate at the database level.
The following steps provide an example of configuring a non-native table in order to use it with a Hive-
to-TargetConnector (where TargetConnector is any type of target connector).
1. Set the link properties for the Hive-to-Teradata link in the QueryGrid portlet.
See Hive Connector and Link Properties.
2. Log on to a Hive client such as Beeline and add hive-loaderfactory JAR to the class path:

add jar /opt/teradata/tdqg/connector/tdqg-hive-connector/version/lib/hive-

loaderfactory-version.jar;
There are others ways to add JARs to Hive class path, one of which is by setting
HIVE_AUX_JARS_PATH.
Note:
The last approach typically requires a Hive restart. If you are using a Cloudera implementation
of Hadoop and Sentry is enabled, this may be the only option available for use because Sentry
does not allow use of ADD JAR commands.
3. Use a Hive storage handler to create the non-native table. For example:
CREATE EXTERNAL TABLE cardata_remote
ROW FORMAT SERDE 'com.teradata.querygrid.qgc.hive.QGSerDe'
STORED BY'com.teradata.querygrid.qgc.hive.QGStorageHandler'
TBLPROPERTIES (
"link"="hive_to_td_link",
"version"="active",
"table"="ut1.cardata");
There is no column definition in the CREATE TABLE statement because the column definition is
inferred dynamically by the Serializer and Deserializer (SerDe).
The table property clause contains the fully-qualified name of the remote table; for example,
database.schema.table, schema.table, and table. If any part is omitted, default values (specified in
connector properties) are used.
Hive Target Connector Tasks

If you designated a Hive connector as a target connector in any link pairing (for example, a Teradata-to-
Hive link), perform the following tasks:
1. Configure the Hive class path (CDH only).
2. Configure the target Hive connector.
Note:
There is no connector installation option as of QueryGrid 2.05.
Configuring the Hive Class Path (CDH Only)
If you are using a Hive connector on a Cloudera Distribution for Hadoop (CDH) implementation, there
is a reported bug on CDH 5.7.

Note:
If you are using any CDH implementation with Sentry enabled, you must also perform this task
because Sentry does not allow use of ADD JAR commands.
1. To resolve the bug, add the following to the class path for the Hive connector:
/opt/teradata/tdqg/connector/tdqg-hive-connector/version/lib/hive-
loaderfactory-version.jar
You can add the syntax in multiple ways, such as modifying HIVE_AUX_JARS_PATH.
2. If required, restart Hive.
Configuring the Hive Connector for Use with a Custom Hadoop Library
Path or Custom JAR Path
If you installed Hadoop with a custom library path or stored any Hadoop .jar files listed in Hadoop JAR
Files outside of the default Hadoop library, you must manually configure the Hive connector with the
custom path for any files that do not reside in the default Hadoop library path.
If you need to add .jar files not listed in Hadoop JAR Files, you can manually configure the Hive
connector to specify which path to use to find the .jar files.
Note:
This only affects the target Hive connector configuration and any files outside the default Hadoop
path.
1. Use the procedures in Editing a Connector or Editing a Link to enable either the Hadoop Library
Path property or Custom JAR Path property, or both properties.
2. Do one or both of the following:
• In the Hadoop Library Path NVP, use comma-separated values to enter the custom library
path or paths for all required .jar files not in the default Hadoop library path. If a custom path
is provided, the default path is not used.
/usr/hdp/2.6.5.0-292/hive-hcatalog/share/hcatalog/,/usr/hdp/2.6.5.0-292/
hadoop-hdfs/,/usr/hdp/2.6.5.0-292/hadoop-mapreduce
• In the Custom JAR Path NVP, use comma-separated values to enter the paths for additional,
custom JARs not listed in Hadoop JAR Files reside.
/lib, /user/lib

Hadoop JAR Files
Name
commons-cli.jar
commons-collections.jar
commons-configuration.jar
commons-io.jar
commons-logging.jar
curator-client.jar
curator-framework.jar
gson.jar
hadoop-auth.jar
hadoop-common.jar
hadoop-mapreduce-client-common.jar
hadoop-mapreduce-client-core.jar
hive-exec.jar
hive-jdbc-.*-standalone.jar
log4j.jar
slf4j-api.jar
xerceslmpl.jar
zookeeper.jar
Enabling the Operation Log
To access the application ID of a Hadoop job in the Hive connector log or exception message, you
must enable operation log in your Hadoop cluster. This is not a required Hive target connector task.
1. Set hive.server2.logging.operation.enabled = true in the Hive configuration.
2. Confirm the operation log path provided in hive.server2.logging.operation.log.location
exists on all nodes where hiveserver2 is running.

Testing Hive Connectors and Links

After completing the tasks required to install Hive initiator connectors, target connectors, and links that
use a Hive connector as an initiator or target, do the following to test connectivity:
2. Run a link diagnostic check for all links that use a Hive connector as an initiator or target.
3. Run a link bandwidth test for all links that use a Hive connector as an initiator or target.
4. Validate the connections between data sources for all Hive-to-TargetConnector links.
Validating a Hive-to-TargetConnector Link
Complete these steps to verify a Hive-to-TargetConnector link (where TargetConnector is any type of
target connector).
1. Make sure you have completed all steps described in Configuring a Non-Native Table for a Hive-to-
Target Connector.
2. Run DESCRIBE <table>, where <table> is the non-native table you created and configured.
3. Verify the result.
For example:
0: jdbc:hive2://localhost:10000/> describe table1;
col_name data_type comment
c1 int from deserializer
c2 varchar(100) from deserializer
Hive Connector Privileges and Security
Required Hive Initiator Connector Privileges
To maintain security for Teradata connectors used in QueryGrid.

1. Set appropriate privileges to those who create and manage foreign servers.
2. Set appropriate privileges to authorization objects, if used.
An authorization object stores a mapping of the local user and password for the remote server.
3. Set up foreign server objects that match the appropriate access to database and tables needed by
Teradata Database users.
4. Set appropriate privileges to foreign server objects to Teradata Database users.

Hive Target Connector Security Guidelines
General
When setting parameters for Hive target connectors in NVP link pairings, make sure the setting of the
Conf File Paths property has the correct pathname correct value. QueryGrid heavily depends on this
setting when processing data transfers. See Hive Connector and Link Properties.
Kerberos
You can set up QueryGrid to use Kerberos authentication with a Hive target connector. It uses two forms
of authentication with Kerberos:
Username/Password
The Hive target connector authenticates the username and password against Kerberos before
sending the query to the data source.
Username/Keytab
Hive can be configured to enable Kerberos Keytab authentication.
If you are using a Hive target connector in an NVP link pairing to access a Kerberized Hadoop cluster:
• Select Kerberos for the Authentication Mechanism property.
• Set it to HS2 Only if only the HiveServer2 is secured (for example, LDAP/CUSTOM/PAM). This is
not a common setup.
• Verify that the Teradata QueryGrid (tdqg) user has permission to run kinit. See Verifying
Permission to Run kinit.
Knox (HDP Only)

The Hive target connector supports most security mechanisms and protocols for Hadoop and
HiveServer2. Knox is served as a gateway service between Hive and HiveServer2. The Hive connector
connects to the Knox service if Knox is configured in the Hive connector properties. Requests from the
Hive connector are sent to the Knox service and Knox then redirects the request to HiveServer2. You
must configure the connection between Knox and HiveServer2.
There is a limitation with Knox when SSL is enabled and Knox is connecting to HiveServer2 using
SPNEGO authorization. In this scenario, Knox does not work with Hive.
If using Knox on a Hortonworks Hadoop (HDP) implementation, make sure the following NVP link
properties contain the correct values:
Setting Description
Authentication Mechanism Required setting.
Username Set only if using Kerberos or HS2-only security.

For example, LDAP, CUSTOM, or PAMs
Password Set only if using Kerberos or HS2-only security.

Setting Description
Conf File Paths Required setting.
Keytab Set only if Kerberos is used and password is not provided.
Knox Gateway Host Set only if using Knox authentication.
Knox Gateway Port Set only if using Knox authentication.
Knox Trust Store Path Set only if using Knox authentication.
Knox Context Path Set only if using Knox authentication.
Knox Trust Store Password Set only if using Knox authentication.
Knox Connection Username Set only if using Knox authentication.
Knox Connection Password Set only if using Knox authentication.
For more information, see Hive Connector and Link Properties.
Hive Target Connector Privileges
To retrieve metadata from the Hive metastore during a session, a temporary view must be created in
the default or temporary database specified in the Hive connector property Temporary Database Name
(tempdb). Temporary views are created with limit 0 so no one can use the temporary views to access
data during the short period of time the temporary view exists. Users require CREATE VIEW and DROP
VIEW access to the default or temporary database.
Verifying Permission to Run kinit
If you are using a Hive target connector to access a Kerberized Hadoop cluster, verify that the Teradata
QueryGrid user has permission to run kinit.
1. Log in to a master node.
2. Type the following:
su tdqg
kinit <username>
4. Log in to beeline with the same Hive principal.
Updating Hive Classpath after Upgrading the Hive Connector

When the Hive connector .jar files are located on the Hive classpath, the old .jar files on the Hive classpath
must be removed and replaced by new ones when upgrading the Hive connector. In particular, the
following files must be replaced:

• hive-qginitiator-version.jar (for 02.04 and earlier)

• hive-qgremote-version.jar (for 02.04 and earlier)
• hive-loaderfactory-version.jar (for 02.05 and later)
Note:
Failure to replace the old .jar files can render the upgraded Hive connector unusable.
Using the Hive Connector

The following discusses the Hive initiator connector (Hive-to-X, where X is a remote data source) and the
available SQL commands for this connector.
SQL Syntax for the Hive Initiator Connector

Teradata QueryGrid supports the following SQL statements from a Hive connector node when Hive is
the initiator:
• SELECT
• INSERT
• SHOW
• DESCRIBE
• EXPLAIN
SQL syntax used with the Hive connector differs from Teradata SQL syntax.
The Hive connector supports predicate pushdown by default. Hive initiator connectors support the
following logical expressions as pushdown predicates: And, Or, Not, Eq, NEq, LT, GT, LE, GE, Like,
IsNULL, Between, In, and NOT IN.
SQL Syntax for the Hive Target Connector

Teradata QueryGrid supports the following SQL statements when Hive is the target connector:
• SELECT
• INSERT
• HELP, SHOW, or DESCRIBE (depending on the syntax of the initiator connector; for example, HELP
FOREIGN is used when Teradata is the initiator connector)
• EXPLAIN INSERT and EXPLAIN SELECT
The Hive connector supports predicate pushdown by default. Hive target connectors support the following
logical expressions as pushdown predicates: And, Or, Not, Gt, Lt, Le, Ge, Ne, Eq, Case, IsNULL,
Between, Abs, Concat, Lower, Upper, Like, Plus, Minus, Mult, Div, In, and NOT IN.
Predicate pushdown can be disabled by setting the disablePushdown property to TRUE. See Hive

SQL Command Reference for the Hive Connector
DESCRIBE Syntax for the Hive Initiator Connector
The example shows the Hive initiator connector using the DESCRIBE statement to fetch and display
metadata from a non-native remote table.
jdbc:hive2://localhost:10000> DESCRIBE cardata_remote;
Result:
+-----------+----------------+--------------------+--+
| col_name | data_type | comment |
+-----------+----------------+--------------------+--+
| price | double | from deserializer |
| mileage | bigint | from deserializer |
| make | varchar(2048) | from deserializer |
| model | varchar(2048) | from deserializer |
| trim1 | varchar(2048) | from deserializer |
| type1 | varchar(2048) | from deserializer |
| cylinder | int | from deserializer |
| liter | double | from deserializer |
| doors | int | from deserializer |
| cruise | tinyint | from deserializer |
| sound | tinyint | from deserializer |
| leather | tinyint | from deserializer |
| dt | varchar(2048) | from deserializer |
| country | varchar(2048) | from deserializer |
+-----------+----------------+--------------------+--+
14 rows selected (0.877 seconds)
EXPLAIN Syntax for the Hive Initiator Connector
The example shows Hive initiating an EXPLAIN request to a Teradata target connector.
jdbc:hive2://localhost:10000> EXPLAIN SELECT * FROM cardata_remote;
Result:
+--------------------------------------------------------------------------------
------+--+
| STAGE DEPENDENCIES:
| Stage-1 is a root stage
| Stage-0 depends on stages: Stage-1
|

| STAGE PLANS:
| Stage: Stage-1
| Map Reduce
| Map Operator Tree:
| TableScan
| alias: cardata_remote
| Statistics: Num rows: 1 Data size: 0 Basic stats: PARTIAL Column
stats: NONE
| Select Operator
| expressions: price (type: double), mileage (type: bigint),
| make (type: varchar(2048)), model (type: varchar(2048)),
| trim1 (type: varchar(2048)),
| type1 (type: varchar(2048)),
| cylinder (type: int),
| liter (type: double),
| doors (type: int),
| cruise (type: tinyint),
| sound (type: tinyint),
| leather (type: tinyint),
| dt (type: varchar(2048)),
| country (type: varchar(2048))
| outputColumnNames: _col0, _col1, _col2, _col3, _col4, _col5, _col6,
| _col7, _col8, _col9, _col10, _col11, _col12, _col13
stats: NONE
| File Output Operator
| compressed: false
stats: NONE
| table:
| input format: org.apache.hadoop.mapred.TextInputFormat
| output format:
org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat
| serde: org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe
|
| Stage: Stage-0
| Fetch Operator
| limit: -1
| Processor Tree:
| ListSink
|
+--------------------------------------------------------------------------------
------+--+
INSERT Syntax for the Hive Initiator Connector
table. The table can be empty or it can contain data. If the table already contains data, the exported data
is appended to the existing table.
Example: Using INSERT with Hive as the Initiator Connector

The example shows an INSERT using the Beeline command line shell. Hive is the initiator and the target
connector can be any other Teradata QueryGrid connector; for example, Teradata, Presto, or target
Hive.
jdbc:hive2://localhost:10000> insert into cardata_remote select * from

cardata_local;

Result:
INFO : Number of reduce tasks is set to 0 since there's no reduce operator

INFO : number of splits:1
INFO : Submitting tokens for job: job_1472862876236_0011
INFO : The url to track the job: http://tdh127m2.labs.teradata.com:8088/proxy/
application_1472862876236_0011/
INFO : Starting Job = job_1472862876236_0011, Tracking URL = http://
tdh127m2.labs.teradata.com:8088/proxy/application_1472862876236_0011/
INFO : Kill Command = /usr/hdp/2.6.5.0-292/hadoop/bin/hadoop job -kill
job_1472862876236_0011
INFO : Hadoop job information for Stage-0: number of mappers: 1; number of
reducers: 0
INFO : 2016-09-09 14:42:21,870 Stage-0 map = 0%, reduce = 0%
INFO : 2016-09-09 14:42:31,473 Stage-0 map = 100%, reduce = 0%, Cumulative CPU
4.54 sec
INFO : MapReduce Total cumulative CPU time: 4 seconds 540 msec
INFO : Ended Job = job_1472862876236_0011
No rows affected (22.979 seconds)
SELECT Syntax for the Hive Initiator Connector
Hive SELECT queries with Hive as the initiator are used to import data from a target data source into
Hive. Teradata QueryGrid supports Beeline to use for Hive initiator queries.
The Hive connector supports predicate pushdown by default. Predicate pushdown can be disabled by
setting the disablePushdown property to TRUE.
Example: Using SELECT with Hive as the Initiator Connector

The example shows a SELECT using the Beeline command line shell. Hive is the initiator and the target
connector can be any other Teradata QueryGrid connector; for example, Teradata, Presto, or target
Hive.
jdbc:hive2://localhost:10000> SELECT
cardata_target.price,cardata_target.mileage,
cardata_target.make, cardata_target.model FROM cardata_target WHERE price <
10000;
Result:
+----------------------+------------------------+---------------------
+--------------+
|cardata_target.price|cardata_target.mileage|cardata_target.make|
cardata_target.model|
+----------------------+------------------------+---------------------
+--------------+
| 8638.930895 | 25216 | Chevrolet | AVEO |
| 9482.219404 | 24842 | Chevrolet | AVEO |
| 8768.998585 | 35299 | Chevrolet | AVEO |
| 9665.84886 | 19565 | Chevrolet | AVEO |
| 9563.789309 | 19273 | Chevrolet | AVEO |
| 9720.97889 | 20836 | Chevrolet | AVEO |
| 9954.054174 | 37345 | Chevrolet | AVEO |
| 9654.060142 | 19183 | Chevrolet | AVEO |
| 9919.048185 | 34621 | Chevrolet | AVEO |

| 9041.906254 | 26191 | Chevrolet | AVEO |

| 9928.188175 | 29680 | Chevrolet | AVEO |
| 9220.829677 | 29992 | Chevrolet | AVEO |
| 9789.037676 | 22986 | Chevrolet | AVEO |
| 9506.047937 | 22169 | Chevrolet | AVEO |
+--------------------+----------------------+-------------------
+--------------------+
SHOW Syntax for the Hive Initiator Connector
The following SHOW statements are available when Hive is the initiating connector:
• SHOW CREATE TABLE <table>; Display the complete CREATE TABLE statement of the
specified table.
• SHOW COLUMNS FROM|IN <table>; Describes the column information for the specified remote
table.
The Hive SHOW statement is equivalent to the HELP FOREIGN statement that is used when Teradata
is the initiator. See Examples of Using HELP FOREIGN.
Example: Using Hive-to-Teradata SHOW CREATE TABLE

The example fetches the details of the CREATE TABLE statement for the specified table from the remote
Teradata system. Hive is the initiator connector.
jdbc:hive2://localhost:10000> SHOW CREATE TABLE cardata_remote;
Result:
+----------------------------------------------------------+--+
| createtab_stmt |
+----------------------------------------------------------+--+
| CREATE EXTERNAL TABLE `cardata_remote`( |
| `price` double COMMENT 'from deserializer', |
| `mileage` bigint COMMENT 'from deserializer', |
| `make` varchar(2048) COMMENT 'from deserializer', |
| `model` varchar(2048) COMMENT 'from deserializer', |
| `trim1` varchar(2048) COMMENT 'from deserializer', |
| `type1` varchar(2048) COMMENT 'from deserializer', |
| `cylinder` int COMMENT 'from deserializer', |
| `liter` double COMMENT 'from deserializer', |
| `doors` int COMMENT 'from deserializer', |
| `cruise` tinyint COMMENT 'from deserializer', |
| `sound` tinyint COMMENT 'from deserializer', |
| `leather` tinyint COMMENT 'from deserializer', |
| `dt` varchar(2048) COMMENT 'from deserializer', |
| `country` varchar(2048) COMMENT 'from deserializer') |

| ROW FORMAT SERDE |

| 'com.teradata.querygrid.qgc.hive.QGNGSerDe' |
| STORED BY |
| 'com.teradata.querygrid.qgc.hive.QGNGStorageHandler' |
| WITH SERDEPROPERTIES ( |
| 'serialization.format'='1') |
| LOCATION |
| 'hdfs://TDINT/apps/hive/warehouse/cardata_remote' |
| TBLPROPERTIES ( |
| 'database'='ut1', |
| 'link'='hive_to_td_link', |
| 'version'='active', |
| 'table'='cardata', |
| 'transient_lastDdlTime'='1469578619') |
+----------------------------------------------------------+--+

Hive has an available global session configuration that allows users to override any property. This allows
users to override Hive connector properties when starting queries during an individual processing
session.
When overriding Hive connector properties for a Hive session, you must specify the non-native table
whose Hive connector properties you want to override. Use commas as delimiters.
Option Description
To override a Hive a. Click the Connectors tab.

the Connectors tab
c. Select Edit.
e. Find the Hive connector property you want to override and click the
f. Click OK.
g. Click Save.
To override a Hive a. Click the Links tab.

the Links tab
c. Select Edit.

Option Description
e. Find the Hive link property you want to override and click the
f. Click OK.
g. Click Save.
4. To override the Hive connector property during a Hive session, use the syntax in the following
example.
SET <databaseName>.<nonNativeTableName>.override = responsetimeout = 3000000,
linkBufferCount=3;
5. [Optional] To override hadoopProperties when using the Hive connector and it is designated as
overridable in the QueryGrid portlet, use the pipe (|) symbol to split Hadoop properties and a colon
(:) to split name value pairs.
The following example is used to override hadoopProperties during either a Hive or Presto session
targeting a Hive connector:
SET <databaseName>.<nonNativeTableName>.override = linkbuffersize=100000,
DEFAULTSTRINGSIZE=32000, hadoopProperties=name1:value1 | name2:value2 ;
The following example is used to override hadoopProperties during a Teradata Session targeting a
Hive connector:
SET FOREIGN SERVER ATTR = 'servername= hiveserver1;
hadoopproperties=name1:value1|name2:value2;' FOR SESSION VOLATILE
6. [Optional] To clear Hive connector property overrides without closing a Hive session, use the syntax
in the following example.
SET <databaseName>.<nonNativeTableName>.override = ;
When you query a remote system that runs a connector that is a different platform from the local system
connector, data is converted to satisfy the target database requirements. Even when the initiator and
target connectors are the same, the data is still transformed because the host formats might be different
from each other.

As another example, if you export a Teradata byteint data type as a Boolean on Hive and then
import it again, the data may not be the same. This can occur because the Boolean zero or one is
imported while the byteint may have contained other values beyond zero or one.
Hive Data Type Mapping
Global Types to Hive Data Types

The target connector maps Hive data types to global data types.
Note:
Global Data Type Hive Data Type
G_Array Array
G_Array_VC_UTF16 / G_Array_VC_Latin * Array
G_BigInt Bigint
G_Blob Binary
G_Boolean Boolean
G_Byte Binary
G_ByteInt Tinyint
G_Char_Latin Char
Note:
Latin data type mapping is only for data types using ISO_8859_1 or US_
ASCII encoding.
G_Char_UTF16 Char
G_Clob_Latin String
Note:
ASCII encoding.

Global Data Type Hive Data Type
G_Clob_UTF16 String
G_Date Date
G_Decimal Decimal
G_Double Double
G_Float Float
G_Integer Integer
G_JSON_UTF16 / G_JSON_Latin * String/Varchar
G_Map Map
G_Number Decimal
G_Row Struct
G_STGeometry * String/Varchar
G_SmallInt Smallint
G_TimeStamp Timestamp
G_Varbyte Binary
G_Varchar_Latin Varchar
Note:
ASCII encoding.
G_Varchar_UTF16 Varchar
G_XML * String/Varchar
Hive Data Types to Global Types

The remote connector maps Hive data types to global data types.
Hive Data Type Global Data Type
array G_Array
bigint G_BigInt
binary G_Blob
boolean G_Boolean
char G_Char_Latin

Hive Data Type Global Data Type
Note:
Latin data type mapping is only for data types using ISO_8859_1 or US_ASCII
encoding.
char G_Char_UTF16
date G_Date
decimal G_Decimal
double G_Double
float G_Float
integer G_Integer
map G_Map
smallint G_SmallInt
string G_Clob_Latin
Note:
encoding.
string G_Clob_UTF16
struct G_Row
timestamp G_TimeStamp
tinyint G_ByteInt
varchar G_Varchar_Latin
Note:
encoding.
varchar G_Varchar_UTF16
Hive String and Binary Types Considerations

Hive String and Binary columns are restricted to a maximum 1GB in size. However, due to the in-memory
nature of these types, a large amount of resources are required on the Hive side when their size nears
the 1GB restriction. Therefore, caution is advised when inserting large Teradata CLOB or BLOB columns
into the Hive String or Binary columns when using QueryGrid.

Hive Connector Limitations

The following limitations affect use of Hive connectors with Teradata QueryGrid:
• The default for Timestamp precision is nine (9); Teradata QueryGrid truncates data with more than
six decimal places when using Hive-to-Teradata links.
• The following Hive speculative properties are not supported and are disabled by default, unless the
Support Hive Task Retries parameter is set to True:
◦ mapreduce.map.speculative=false
◦ mapreduce.reduce.speculative=false
◦ tez.am.speculation.enabled=false
• When using the Hive initiator:
◦ Export is supported for Hive-on-Tez (Hive Execution Engine property = Tez) on HDP 3.0.1 or
later only.
◦ Export is not supported for Hive-on-Spark (Hive Execution Engine property = Spark).
◦ The target server returns all columns and the initiator server processes any column projection.
◦ The target server does not return query and plan data when using the Explain command.
◦ The target server returns all columns when using the Count command; these then aggregate
on the initiator server.
◦ Sub-queries such as insert into 1st-non-native-table select from 2nd-non-native-table cannot be
used.
• By default, the Hive target connector returns a 1 as the number of rows exported regardless of how
many rows were actually exported during a successful export query. Setting the Collect
Approximate Activity Count connector property to true returns the number of rows exported with
the following limitations:
◦ If the Hive table statistics are inaccurate (this is uncommon – Hive table statistics are usually
accurate), enabling this property can result in a performance overhead on the insert query.
◦ If there are concurrent inserts on the Hive table, an inaccurate number of rows may be displayed,
resulting in an approximate result rather than a precise number.

9
Using the Spark SQL Connector with Teradata
QueryGrid
Completing the Spark SQL Connector Configuration
After you add and configure a Spark connector and link pairings in a QueryGrid fabric, you must do the
• Configure Spark SQL connectors used as initiators used in link pairings
• Configure Spark SQL connectors used as targets in link pairings
• Test installed Spark SQL connectors and links that use a Spark connector as an initiator or target
Spark SQL Connector and Link Properties

Note:

9: Using the Spark SQL Connector with Teradata QueryGrid
Property Name Type
16.20+ LOB Support True On Teradata Databases version 16.20 and later, the STRING and BINARY columns on Spark SQL are mapped to CLOB and BLOB ● Target
by default. Unselect this option to map the STRING and BINARY columns to VARCHAR and VARBYTE, respectively. lobSupport
Authentication None Overall security mechanism for the cluster. Target

Mechanism
Collect Approximate False Displays the approximate number of rows exported to the target data source. ● Target
Activity Count When set to false, the activity count displays a 1. When set to true, an approximate activity count is returned. The default is false. collectActivityCount
Compression Codec System Default Compression type to use when exporting to a Spark target table. Valid values are System Default, Deflate, BZip2, GZip, LZ4, and ● Target
Snappy. compressionCodec
Conf File Paths /etc/hadoop/ Paths to core-site.xml , hdfs-site.xml , and hive-site.xml (if available) in a comma-separated list. Target
conf/,
/etc/spark2/
conf
Connection Evict 30 minutes Frequency of eviction checks. Connection objects from the pool are checked, closed, and removed if the idle time (current time - last time of Target
Frequency use) of a connection object is greater than the Connection Max Idle Time setting.
Reduce the time between checks if there are multiple concurrent users running queries to clear the connections more frequently.
Connection Max Idle 86400 seconds The maximum idle time for the connection cache object, after which the object is closed and removed from the cache. Use this property when Target
Time there are multiple concurrent users and queries running on the system that might lead to starvation of connection objects.
Connection Pool Size 100 Maximum number of connection objects that can be stored in a connection pool. When acquiring a new connection, the connector checks Target
for an available space in the pool. If no space is available in the connection pool, the connection fails after 5 minutes. Only one connection
pool and username per connector configuration is allowed.
Database Name Default Name of the database for the connector, if not provided in the user query. ● Target
Maximum name length is 255 characters. databaseName
Default Binary Size 64000 bytes The default truncation size for the VARBINARY types. ● Target
Valid values are 1–2097088000 bytes. defaultBinarySize
This is for a Teradata-to-Spark link and is used by the target Spark connector and is applicable when the initiating Teradata Database does
not support BLOB data types with QueryGrid. With BLOB support, the default binary size is not used.
Default String Size 32000 The VARCHAR truncation size. This is the size at which data imported from or exported to string columns is truncated. The value ● Target
characters represents the maximum number of Unicode characters to import, and defaults to 32000 characters. Teradata QueryGrid truncates defaultStringSize
the string columns at the default value set in defaultStringSize.
This is for a Teradata-to-Spark link and is used by the target Spark connector and is applicable when the initiating Teradata Database does
not support CLOB data types with QueryGrid. With CLOB support, the default string size is not used.
Disable Pushdown False When set to true, disables the pushdown of all query conditions to the target system. ● Initiator
disablePushdown

Property Name Type
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 target system.
To avoid incorrect results caused by condition pushdown in situations where the settings on the initiating system do not match the settings
on the target system, you can disable the pushdown of all conditions to the target system.
If designated as Overridable, this property can only be overridden at the session level from false to true (indicating you are disabling
pushdown), but cannot be changed from true to false.
Enable Logging INFO Runs queries with debugging mode enabled. Initiator, Target
Valid values are NONE, WARN, INFO, and DEBUG.
Hadoop Properties None Specifies Hadoop environment properties for a user session. Properties are provided in a list. Use = between each property and its ● Target
value (name=value, name=value, name=value), and a comma as a separator between properties, with or without a space after the hadoopProperties
comma.
For example:
mapred.job.queue.name=abcdef,mapreduce.task.timeout=3600000,mapreduce.map.speculative=false
If Hadoop Properties is not selected, the default Hadoop environment properties are used.
Keytab None Absolute path to the Kerberos keytab file. QueryGrid only uses the keytab file for authentication if a username and password is not Target
provided.
Link Buffer Count 4 Maximum number of write buffers available on a single channel at one time. ● Initiator, Target
Note: linkBufferCount
Link Buffer Count overrides the default internal fabric property shmDefaultNumMemoryBuffers.
Link Buffer Size 1048576 Maximum size of the write buffers to allocate for row handling and message exchange. ● Initiator, Target
Valid values are 73728–10485760 bytes. linkBufferSize
Link Handshake 30000 Handshake and ACK timeout in milliseconds for the shared memory channel setup. Initiator, Target
Link Heartbeat 3600000 Maximum interval in milliseconds for the heartbeat signal on a channel between the connector and the fabric instance, used for health Initiator, Target
Interval check status. Tunable for diagnostic purposes only.
Note:
This interval should be greater than Link Handshake Timeout.
Number Executors None Unit of parallelism when data is exported or imported into Spark SQL. ● Initiator, Target
numExecutors
Password None Password of the user or service account. Target

Port 10016 Valid values for the Spark Connector are 1026–65535. Target
Read Timeout 3600000 Number of milliseconds to wait to read between data packets when importing data messages. ● Initiator, Target
Valid values are 300000–86400000. readTimeout

Property Name Type
Response Timeout 86400000 Number of milliseconds to wait for the final data exec response when all the data has been transferred. ● Initiator, Target
Valid values are 1800000–172800000. responseTimeout
Server None Used to connect to the target database as part of the JDBC connection string. This is the IP address or DNS name of the target host. Target
Spark Resource YARN Resource Manager used by the Spark platform. Possible values are YARN and standalone. Both
Manager
Spark Monitoring localhost:8080 One or more Host/IP:Port combinations for the Spark Monitoring REST Servers. Initiator
REST Servers
Spark Home Path /usr/hdp/current/ Filepath to the Spark home directory where the /jars sub-directory resides containing all the Spark library .jar files. Target
spark2-client/
Spark Execution Spark Thrift Mechanism used by the target connector to submit queries to Spark. Possible values are Spark Thrift Server and Spark Application. Target
Mechanism Server
Temporary Database Default Temporary database name for storing temporary tables and views. ● Target
Name tempDbName
Username Hive Name of the user. A username added for a connector or target connector link must be included in Allowed OS users. Target
This NVP is saved in the Teradata QueryGrid Manager configuration and is required when the initiator does not support a mechanism to
provide user credentials. The username is also used for connectivity diagnostic checks.
Write Timeout 3600000 Number of milliseconds to wait to write between data packets when exporting data messages. ● Initiator, Target
Valid values are 300000–86400000. writeTimeout

Creating an HDFS Directory for the Spark SQL Connector

Before using the Spark SQL Connector (initiator or target), the Hadoop administrator must create the
hdfs:///tdqg-spark/ directory. This directory serves the following purpose:
• It stores a dummy text file created by the Spark SQL connector when used for the first time and is
required for the Spark SQL connector to work.
• It stores the cache files for user-defined foreign server objects that are used by the Spark SQL
initiator.
• It stores temporary files when running the target connector using the Spark Application Execution
Mechanism.
All users accessing the Spark SQL connector (initiator or target) must have WRITE access permission
in the directory.
1. Log on to any Hadoop node.
2. Create the directory using command:
hdfs dfs -mkdir /tdqg-spark/
3. Enter the permissions as in the example below:
hdfs dfs -chmod 777 /tdqg-spark/
Note:
The permission 777 is an example, actual permissions are determined by the Hadoop
administrator if the requirements to create the directory are met.
Spark SQL Initiator Connector Tasks

If you designated a Spark SQL connector as an initiator connector in any link pairing (for example, a
Spark SQL-to-Teradata link), perform the following tasks:
1. Create an HDFS directory.
2. Configure primary group for Spark users.
3. Configure a foreign server.
Starting Scala REPL
The supported client for interacting with the Spark SQL initiator is the Scala Read-Eval-Print-Loop
(REPL), referred to as the spark-shell. In order to use the Spark SQL initiator, spark-shell must be started
using the following JAR file:
• spark-loaderfactory
1. Log on to the node you want to start spark-shell.

2. Locate the connector path at /opt/teradata/tdqg/connector/tdqg-spark-connector/

<version>/lib/)
3. Add the JAR file.
4. Start the spark-shell.
The following is an example path for starting spark-shell:
spark-shell --jars /opt/teradata/tdqg/connector/tdqg-spark-connector/
version/lib/spark-loaderfactory-version.jar --master yarn
Note:
On CDH clusters, only Spark 2.1 and later are supported. When using CDH clusters, use the
spark2-shell command name instead of spark-shell.
Configuring a Group for Spark Connector Users for Logging Purposes
To enable logging for Spark SQL connector (initiator or target) users, the users must belong to the
'hadoop' group. In the case of a Kerberized Hadoop cluster, the same requirement applies to users
corresponding to Kerberos principals.
Note:
This task is only required if you want to enable logging.
1. Run the modify user command in Linux.

The following example adds user1 to the Hadoop group.
cmdall usermod -g hadoop user1
Configuring a Foreign Server for a Spark SQL-to-TargetConnector
The Data Sources API framework is used for the Teradata QueryGrid Spark SQL initiator connector.
Data Sources API allows Spark SQL to access data stored on other systems. A Spark SQL table created
using a Data Source API framework is referred to as a non-native table.
The Data Sources API operates at the table level by default, so one non-native table must be created
for each remote table, unlike Teradata Foreign Servers and Presto Catalogs that operate at the database
level. However, a Foreign Server Library has been included as part of the Spark SQL connector, which
addresses some of the limitations and inconveniences when working with non-native tables. Teradata
recommends that the Foreign Server Library be used to interact with the Spark SQL initiator and all
Spark SQL initiator examples in this section are based on the Foreign Server Library. For complete
details on the foreign server library, see Foreign Server Library API Reference for the Spark SQL Initiator
Connector.
The following steps provide an example of configuring a foreign server in order to use it with a Spark
SQL-to-TargetConnector (where TargetConnector is any type of target connector):

1. Set the link properties for the Spark SQL-to-Teradata link in the QueryGrid portlet.
See Spark SQL Connector and Link Properties.
2. Log on to Scala REPL, see Starting Scala REPL for more information.
3. Import the Foreign Server Library and create a foreign server object, for example:
scala> import tdqg.ForeignServer
import tdqg.ForeignServer
scala> val s1 = new ForeignServer('spark_to_teradata_link',"active","fs1")

s1: tdqg.ForeignServer = tdqg.ForeignServer@4eb73cc8
4. Use the foreign server to show remote schemas and verify the results, for example:
scala> s1.showSchemas
+---------------+
|DATABASE_NAME |
+---------------+
|default |
|user1 |
+---------------+
Spark SQL Target Connector Tasks

If you designated a Spark SQL connector as a target connector in any link pairing (for example, a
Teradata-to-Spark SQL link), perform the following tasks:
1. Create an HDFS directory.
2. Configure users for the Spark SQL target connector.
Configuring Users for the Spark SQL Target Connector
1. Do the following based on your configuration:
Spark Target
Description
Configuration
YARN using the Spark To enable user impersonation, the tdqg user must be able to impersonate
application other users. Add the following entry in core-site.xml to enable
impersonation:
<property>
<name>hadoop.proxyuser.tdqg.hosts</name>
<value>*</value>
</property>
<property>
<name>hadoop.proxyuser.tdqg.groups</name>
<value>*</value>
</property>

Spark Target
Description
Configuration
Standalone using the The target user, specified by user mapping, must be the same user who
Spark Thrift Server started the Spark Thrift Server.
Testing Spark SQL Connectors and Links

After completing the tasks required to install the Spark SQL initiator connectors, target connectors, and
links that use a Spark SQL connector as an initiator or target, do the following to test connectivity:
2. Run a link diagnostic check for all links that use a Spark SQL connector as an initiator or target.
3. Run a link bandwidth test for all links that use a Spark SQL connector as an initiator or target.
4. Validate the connections between data sources for all Spark SQL-to-TargetConnector links.
Validating a Spark SQL-to-TargetConnector Link
Complete these steps to verify a Spark SQL-to-TargetConnector link (where TargetConnector is any
type of target connector).
1. Make sure you have completed all steps described in Configuring a Foreign Server for a Spark SQL-
to-TargetConnector.
2. Load the previously created foreign server if the spark-shell session is no longer active.
For example:
scala> val s1 = new ForeignServer("fs1")

Loading existing Foreign Server...
Foreign Server ready to use
s1: tdqg.ForeignServer = tdqg.ForeignServer@5feff876
3. Create a non-native table that refers to an existing remote table.
For example:
scala> s1.create("test_nn_table", "user1.players")

4. Describe the non-native table created and verify the result.
For example:
scala> s1.describe("test_nn_table")
+--------+---------+-------+
|col_name|data_type|comment|
+--------+---------+-------+
|number |int |null |

|name |string |null |

+--------+---------+-------+
Note:
When a non-native table is created without specifying a database name (as in the above
example), the table is assumed to be temporary and automatically disappears once the current
session ends. In order to create a permanent non-native table, you must specify a database
name.
Spark SQL Connector Privileges and Security
Spark SQL Target Connector Security Guidelines
General
When setting parameters for Spark SQL target connectors in NVP link pairings, make sure the setting
of the Conf File Paths property has the correct pathname correct value. QueryGrid heavily depends
on this setting when processing data transfers. See Spark SQL Connector and Link Properties.
Kerberos
You can set up QueryGrid to use Kerberos authentication with a Spark SQL target connector. It uses
two forms of authentication with Kerberos:
Username/Password
The Spark SQL target connector authenticates the username and password against Kerberos
before sending the query to the data source.
Kerberos Keytab
Spark SQL can be configured to enable Kerberos Keytab authentication.
If you are using a Spark SQL target connector in an NVP link pairing to access a Kerberized Hadoop
cluster:
• Select Kerberos for the Authentication Mechanism property.
• Verify that the Teradata QueryGrid user has permission to run kinit. See Verifying Permission to
Run kinit.
Verifying Permission to Run kinit
If you are using a Spark SQL target connector to access a Kerberized Hadoop cluster, verify that the
Teradata QueryGrid user has permission to run kinit.
1. Log in to a master node.

su tdqg
kinit <username>
4. Log in to beeline with the same Hive principal.
Restarting the Spark Thrift Server after Upgrading the Spark

Connector
When the Spark Thrift server is being used for the Spark connector, the Spark Thrift Server must be
restarted after upgrading the Spark connector.
Note:
Failure to restart the Spark Thrift Server can render the upgraded Spark connector unusable.
Using the Spark SQL Connector

The following discusses the Spark SQL initiator connector (Spark SQL-to-TargetConnector) and the
available SQL commands for this connector.
Syntax for the Spark SQL Initiator Connector

Teradata recommends that the Foreign Server Library is used to interact with the Spark SQL initiator.
See Foreign Server Library API Reference for the Spark SQL Initiator Connector for details on Foreign
Server Libraries.
SQL Syntax for the Spark SQL Target Connector

Teradata QueryGrid supports the following SQL statements when Spark SQL is the target connector:
• SELECT
• INSERT
• SHOW or DESCRIBE (depending on the syntax of the initiator connector; for example, HELP
FOREIGN is used when Teradata is the initiator connector)
• EXPLAIN INSERT and EXPLAIN SELECT
The Spark SQL connector supports predicate pushdown by default. Spark SQL target connectors support
the following logical expressions as pushdown predicates: And, Or, Between, EqualTo, GreaterThan,
GreaterThanOrEqual, In, IsNULL, LessThan, LessThanOrEqual, Like, Not, NotEqualTo, and NotIn.

Foreign Server Library API Reference for the Spark SQL

Initiator Connector
The Spark SQL initiator connector provides an easy-to-use, Java-based Foreign Server library. The
library defines a "wrapper" Foreign Server class. The class contains a Foreign Server constructor to
create one or more unique Foreign Server objects. Each Foreign Server object contains a catalog of
permanent non-native tables that are backed up by a cache file on HDFS after a session ends. The Spark
SQL initiator connector also contains static and instance methods to interact with the temporary and
permanent non-native tables in each Foreign Server object and to retrieve metadata from remote tables.
The Spark SQL engine does not have objects similar to Foreign Servers (Teradata Database) or Catalogs
(Presto). Therefore, the Spark SQL initiator connector operates at the table level by default.
The primary functionalities provided by the Foreign Server Library are metadata discovery and
management. It does not change the SQL syntax for import, export, and explain queries. The
ForeignServer.sql() and ForeignServer.getDataSetFromSql() are used to run SELECT, INSERT,
and EXPLAIN statements. All syntax parameters are required when using the foreign server library,
invalid or null parameters result in an error.
Note:
Before any part of the Foreign Server Library can be used, you must run the import
tdqg.ForeignServer statement.
Name Parameter Description
Constructors
ForeignServer String Link Construct a new Foreign Server object using a QueryGrid link.
String
Version
String Name
ForeignServer String Name Restore an existing Foreign Server.
Static Methods
showForeignServers – List all Foreign Server names.
dropForeignServer String Name Drop a specified Foreign Server as well as all its non-native
tables.
sql String SQL Run a SQL statement (SELECT/INSERT/EXPLAIN only) and

display all rows in result.
getDatasetFromSql String SQL Run a SQL statement (SELECT/INSERT/EXPLAIN only) and

return the Dataset<Row> object.
Instance Methods
showSchemas – List all target schemas.

Name Parameter Description
showTables String List all tables under a target schema.

Schema
showColumns String Table Display the schema of a target table specified by a fully-qualified
name (such as, schema.table or catalog.schema.table).
show – List each non-native table (temporary or permanent) under this

Foreign Server and which target table it represents.
show String Name Display the CREATE TABLE statement of a non-native table
under this Foreign Server.
Note:
This only works for permanent non-native tables, and the
database must be part of the name.
create String Table Create a non-native table representing a target table (fully-
String Name qualified name) under this Foreign Server.
Note:
In order to create a permanent non-native table, the database
must be part of the name.
drop String Name Drop a non-native table under this Foreign Server.
Note:
For permanent non-native tables, the database must be part of
the name.
describe String Name Display the details of a non-native table under this Foreign Server.
Note:
For permanent non-native tables, the database must be part of
the name.
setSessionOverride String Set the connector properties to be overridden for the session.
Values Properties are case-insensitive and non-overridable properties
are ignored.
Example: setSessionOverride("linkbuffersize=100000,
numMappers=4")
Constructor
Creating a New Foreign Server Object
1. Create a new Foreign Server object with a unique name, such as:

scala> val s1 = new ForeignServer("s2h","active","fs1")

sq:tdqg.ForeignServer = tdqg.ForeignServer@4eb73cc8
Restoring an Existing Foreign Server Object
1. Restore an existing Foreign Server object, such as:

scala> val s1 = new ForeignServer("fs1")
Loading existing Foreign Server...
Validating default.nn1... OK
Foreign Server ready to use
s1: tdqg.ForeignServer = tdqg.ForeignServer@45775a15
Static Methods
Use the static methods to view or drop Foreign Servers as well as run SQL (SELECT/INSERT/EXPLAIN)
statements.
dropForeignServer
Drop a specified foreign server and its non-native tables.

The following is an example of dropping a foreign server using the static method:
scala> ForeignServer.dropForeignServer("fs1")
Deleting Foreign Server...
Foreign Server deleted
getDatasetFromSql
Use the getDataSetFromSql() method to perform a lazy execution of a SELECT query involving non-
native tables. For example:
scala> ForeignServer.getDatasetFromSql("select * from default.nn1")

res0: org.apache.spark.sql.Dataset[org.apache.spark.sql.Row] = [number: int,
name: string]
The query result DataSet (res0 in the above example) is used like any other Spark SQL DataSet object
and is only evaluated when an action is called.
showForeignServers
List all foreign server names.

The following example shows how to list all the foreign servers using the static method:

scala> ForeignServer.showForeignServers
Listing all Foreign Servers
fs1
sql
Use the sql method to run SELECT, INSERT, and EXPLAIN SQL statements involving non-native
tables.
EXPLAIN Syntax for the Spark SQL Initiator Connector
The following example shows Spark SQL initiating an EXPLAIN request to a Teradata target
connector.
scala> ForeignServer.sql("explain select name from default.nn1 where number =
10")
+------------------------------------------------------------------------------
------+
|plan
+------------------------------------------------------------------------------
------+
|== Physical Plan ==
*Project [name#25]
+- *Filter (isnotnull(number#24) && (number#24 = 10))
+- *Scan com.teradata.querygrid.qgc.spark.QGRelation@4ec78008
default.nn1[name#25,number#24] PushedFilters: [IsNotNull(number),
EqualTo(number,10)], ReadSchema: struct<name:string>|
+------------------------------------------------------------------------------
------+
scala> ForeignServer.sql("explain insert into default.nn1 select * from
players2")
+------------------------------------------------------------------------------
------+
|plan
+------------------------------------------------------------------------------
------+
|== Physical Plan ==
ExecutedCommand
+- InsertIntoDataSourceCommand Relation[number#24,name#25]
com.teradata.querygrid.qgc.spark.QGRelation@4ec78008,
OverwriteOptions(false,Map())
+- MetastoreRelation default, players2
+------------------------------------------------------------------------------
------+
INSERT Syntax for the Spark SQL Initiator Connector
table. The table can be empty or can contain data. If the table already contains data, the exported
data is appended to the existing table.

Example: Using INSERT with Spark SQL as the Initiator Connector

scala> ForeignServer.sql("insert into default.nn1 values (8, 'user1')")
scala> ForeignServer.sql("insert into default.nn1 select * from players2")
SELECT Syntax for the Spark SQL Initiator Connector
Spark SQL SELECT queries with Spark SQL as the initiator are used to import data from a target data
source into Spark SQL.
The Spark SQL connector supports predicate pushdown.
Example: Using SELECT with Spark SQL as the Initiator Connector

scala> ForeignServer.sql("select * from default.nn1")
+------+------------+
|number|name |
+------+------------+
|9 |user1 |
|10 |user2 |
|11 |user3 |
+------+------------+
Instance Methods
Use the instance methods to discover remote metadata and manage non-native tables (permanent or
temporary) for a Foreign Server.
create
You can use the create method to create non-native tables (permanent or temporary) to represent
target tables. If the non-native table name is in the form of db.tb1 (default.nn1 in the example), a
permanent non-native table is created. If the database is not part of the non-native name, a temporary
non-native table is created (nn2 in the example). Temporary tables in Spark SQL only exist during the
current session and cannot be associated with a database.
The following example shows the Spark SQL initiator using the CREATE statement to create non-native
tables:
scala> s1.create("default.nn1","user1.players")
scala> s1.create("nn2","default.test")
describe
The describe method is used to display the details of a non-native table.

scala> s1.describe("nn2")
+--------+---------+-------+

|col_name|data_type|comment|
+--------+---------+-------+
|c1 |string |null |
+--------+---------+-------+
drop
The drop method is used to drop a permanent non-native table from a foreign server. Note that
temporary non-native tables are dropped automatically once the current session ends.
scala> s1.drop("default.nn2")
show
The show() method can be called to view a catalog of all non-native table (permanent or temporary)
created under the current Foreign Server object (does not require connection to remote). If a permanent
non-native table name is passed to the show() method, then the complete CREATE TABLE statement
for that non-native table is displayed.
scala> s1.show
LINK: s2h.active
+-----------+--------------+------------+
|local_table|remote_table |is_temporary|
+-----------+--------------+------------+
|nn2 |default.test |true |
|default.nn1|user1.players |false |
+-----------+--------------+------------+
scala> s1.show("default.nn1")
+----------------------------------------------------------+
|createtab_stmt |
+----------------------------------------------------------+
|CREATE TABLE `default`.`nn1` (`number` INT, `name` STRING)
USING com.teradata.querygrid.qgc.spark
OPTIONS (
`serialization.format` '1',
`version` 'active',
`link` 's2h',
`table` 'user1.players'
) |
+----------------------------------------------------------+

showColumns
The show*() methods can be used for schema and metadata discovery queries and are equivalent to
HELP FOREIGN SERVER/DATABASE/TABLE queries on the Teradata Database. The showColumns
method displays the schema of a target table specified by a fully-qualified name (For example:
schema.table or database.schema.table).
scala> s1.showColumns("user1.players")
+--------+--------+-------+
|COL_NAME|COL_TYPE|COMMENT|
+--------+--------+-------+
|number |int | |
|name |string | |
+--------+--------+-------+
showSchemas
HELP FOREIGN SERVER/DATABASE/TABLE queries on the Teradata Database. This method lists all
target schemas.
scala> s1.showSchemas
+-------------+
|DATABASE_NAME|
+-------------+
|default |
|user1 |
+-------------+
showTables
HELP FOREIGN SERVER/DATABASE/TABLE queries on the Teradata Database. This method lists all
tables under a target schema.
scala> s1.showTables("user1")
+---------+
|TAB_NAME |
+---------+
|dummy |
|players |
+---------+


Designating a Spark SQL connector property as overridable in the QueryGrid portlet allows users to
override configured Spark SQL connector properties when executing queries during an individual
processing session.
For the Spark SQL initiator session, setSessionOverride() is used at the Foreign Server level to
override configured Spark SQL connector properties. The session override applies to all non-native tables
that belong to the Foreign Server.
Option Description
To override a Spark a. Click the Connectors tab.

SQL connector b. Click next to the connector that has a property you want to override.
property in the
Connectors tab c. Select Edit.
e. Find the Spark SQL connector property you want to override and click
the Overridable check box.
f. Click OK.
g. Click Save.
To override a Spark a. Click the Links tab.

SQL connector b. Click next to the link that has a property you want to override.
property in the Links
tab c. Select Edit.
e. Find the Spark SQL link property you want to override and click the
f. Click OK.
g. Click Save.
4. [Optional] To override the Spark SQL connector property during a Spark SQL session for Foreign
Server s1, use the syntax in the following example.
s1.setSessionOverride("linkBufferSize=100000, numExecutors=4",
hadoopProperties=name1:value1 | name2:value2")
Note:
When overriding hadoopProperties, you must use the pipe (|) symbol to split Hadoop
properties and a colon (:) to split name value pairs, as shown in these examples.
The following example is used to override hadoopProperties during a Teradata Session targeting a
Hive connector:

SET FOREIGN SERVER ATTR = 'servername=sparkserver1;

hadoopproperties=name1:value1|name2:value2;' FOR SESSION VOLATILE
5. [Optional] To clear Spark SQL connector property overrides without closing a Spark SQL session for
Foreign Server S1, use the syntax in the following example.
s1.setSessionOverride("")
Data Type Mapping for Spark SQL QueryGrid Connectors
When you query a remote system that runs a connector that is a different platform from the local system
connector, data is converted to satisfy the target database requirements. Even when the initiator and
target connectors are the same, the data is still transformed because the host formats might be different
from each other.
As an example, the import of data from Spark SQL with an unlimited VARCHAR size into a limited
As another example, if you export a Teradata byteint data type as a Boolean on Spark SQL and
then import it again, the data may not be the same. This can occur because the Boolean zero or
one is imported while the byteint may have contained other values beyond zero or one.
Spark SQL Data Type Mapping
Global Types to Spark SQL Data Types
Note:

Global Data Type Spark SQL Data Type
G_Array array
G_Array_VC_UTF16 / G_Array_VC_Latin * array
G_BigInt bigint
G_Blob binary
G_Boolean boolean
G_Byte binary
G_ByteInt tinyint
G_Char_Latin string
Note:
ASCII encoding.
G_Char_UTF16 string
G_Clob_Latin string
Note:
ASCII encoding.
G_Clob_UTF16 string
G_Date date
G_Decimal decimal
G_Double double
G_Float float
G_Integer integer
G_JSON_UTF16 / G_JSON_Latin * string
G_Map map
G_Number decimal
G_Row struct
G_SmallInt smallint
G_STGeometry * string
G_TimeStamp timestamp
G_Varbyte binary

Global Data Type Spark SQL Data Type
G_Varchar_Latin string
Note:
ASCII encoding.
G_Varchar_UTF16 string
G_XML * string
Spark SQL Data Types to Global Types

Spark SQL Data Type Global Data Type
array G_Array
bigint G_BigInt
binary G_Blob
boolean G_Boolean
char G_Char_Latin
Note:
encoding.
char G_Char_UTF16
date G_Date
decimal G_Decimal
double G_Double
float G_Float
integer G_Integer
map G_Map
smallint G_SmallInt
string G_Clob_Latin
Note:
encoding.
string G_Clob_UTF16

Spark SQL Data Type Global Data Type
struct G_Row
timestamp G_TimeStamp
tinyint G_ByteInt
varchar G_Varchar_Latin
Note:
encoding.
varchar G_Varchar_UTF16
Spark SQL String and Binary Types Considerations

Spark SQL String and Binary columns are restricted to a maximum 1GB in size. However, due to the
in-memory nature of these types, a large amount of resources are required on the Spark side when their
size nears the 1GB restriction. Therefore, caution is advised when inserting large Teradata CLOB or
BLOB columns into the Spark SQL String or Binary columns when using QueryGrid.
Spark SQL Connector Limitations

The following limitations affect use of Spark connectors with Teradata QueryGrid:
• The Spark connector does not support ACID tables or transactional tables.
• When using the Explain command with a Spark initiator connector, the remote server does not return
query and execution plan data.
• The default for Timestamp precision is nine (9); Teradata QueryGrid truncates data with more than
six decimal places when using Spark-to-Teradata links.
• Only limited predicate pushdown is available.
• The Foreign Function Execution (FFE) feature is currently not supported for the Spark SQL target
connector.
• The Spark SQL connector does not support roles since roles are not supported by Spark.
• By default, the Spark SQL target connector returns a 1 as the number of rows exported regardless
of how many actual rows were exported during a successful export query. Setting the Collect
Approximate Activity Count connector property to true returns the number of rows exported with
a slight performance overhead. If there are concurrent inserts on the Spark SQL table, an inaccurate
number of rows might be displayed, resulting in an approximate result rather than a precise number.
• When starting either the Spark Thrift Server or Spark Shell to use with the Spark Connector, Teradata
recommends setting the spark.task.maxFailures property to 1.

• The following are a result of possible Apache Spark limitations:

◦ Spark 2.1 and later: When using the Spark initiator, if the schema of a target table changes after
a non-native table representing that target table has been created, that non-native table must
be recreated in order to reflect the schema change.
◦ Spark 2.2 and later: When importing data for the DATE type using the Spark target connector
or exporting data of the DATE type using the Spark initiator, the data value from Spark can be
incorrect.
◦ Spark 2.2 and later: Spark does not support Char/Varchar; therefore, when using the Spark
target connector to insert data from QueryGrid and the target table contains char/varchar
columns, the data from QueryGrid may be incorrect. To avoid possible incorrect data, use String
instead of Char/Varchar.

10
Using the Oracle Connector with Teradata
QueryGrid
Completing the Oracle Connector Configuration
After you add and configure an Oracle target connector and link pairings in a QueryGrid fabric, you must
do the following to complete the configuration:
• Configure Oracle connectors used as targets in link pairings
• Test installed Oracle connectors and links
• Oracle Connector Privileges and Security
Important:
• The Oracle connector is a target connector only and cannot be used as an initiating connector.
• All Oracle target connector nodes must be driver nodes for communication and data transfer to
the Oracle system.
• Install the Oracle target connector on an edge or additional node and not on Oracle system
nodes.
The following are the minimum requirements for an Oracle target connector node to install the QueryGrid
2.0 software:
• 2 GB RAM
• SLES 11 / Redhat 6 or 7
• Memory requirements as defined in the fabric/connector setup
• CPU and JVM configuration for large dataset processing
• JAVA 8
Oracle Connector and Link Properties

Links are named configurations that include the target connector. If the same property is set for a link
and a connector, the link setting overrides the connector setting.

10: Using the Oracle Connector with Teradata QueryGrid
Important:
The Oracle connector is only available as a target connector.
Overridable?
Property Name
Authentication DB Lists the security method used on the target

Mechanism Password system.
Valid values are DB Password, OS,
Authentication, SSL, or Kerberos.
Character Set AL32UTF8 Database character set for CHAR, VARCHAR,

and CLOB.
This property is available for users who do not
have permission to access the dictionary views
that can provide this information dynamically. The
default is UTF8 if a value is not provided.
Collect Metrics False Collect query metrics from the Oracle Resource ●
Manager for QueryGrid metadata and run collectMetrics
queries.
Connection 30 minutes Frequency of eviction checks. Connection objects

Evict from the pool are checked, closed, and removed
Frequency if the idle time (current time - last time of use) of a
connection object is greater than the Connection
Max Idle Time setting.
multiple concurrent users running queries to clear
the connections more frequently.
Connection 86400 The maximum idle time for the connection cache
Max Idle Time seconds object, after which the object is closed and
running on the system that might lead to
starvation of connection objects.
Connection 100 Maximum number of connection objects that can

Pool Size be stored in a connection pool. When acquiring a
new connection, the connector checks for an
available space in the pool. If no space is
available in the connection pool, the connection
fails after 5 minutes. Only one connection pool
and username per connector configuration is
allowed.
Database None The database version property is certified for

Version Oracle database version 12.1.0.2 and later. This

Overridable?
Property Name
is a string data type and you have the option to try

it with versions of Oracle that are not certified to
run on QueryGrid.
Use this property for internal implementations of
features such as length of temporary table name
when running an export clause.
This property is required and available for users
who do not have permission to access the
dictionary views that can provide this information
dynamically.
Default Binary 64000 The VARBINARY truncation size. ●

Size bytes Valid values are 1–2097088000 bytes. defaultBinarySize
Default String 32000 The VARCHAR truncation size. ●

Size characters The value represents the maximum number of defaultStringSize
Unicode characters to import, and defaults to
32000 characters. Teradata QueryGrid truncates
the string columns at the default value set in
defaultStringSize if less than the actual column
size.
Enable Logging INFO Logging level for the connector or link properties.
User level log settings can be explicitly set
through the add or edit link page in the QueryGrid
portlet.
DEBUG.
Encryption None Encryption mechanism.

Valid values are NONE, SSL, and NNE.
Fetch Size 1000 Number of rows JDBC can pull from a database ●
at a time. fetchSize
Keystore None The keystore password is applicable when SSL

Password authentication is on the server or both the server
and target system.
Keystore Path None The keystore path is applicable when SSL

authentication is on the server or both the server
and target system.
Keystore Type JKS The keystore type is applicable when SSL

authentication is on the server or both the server
and target system.
Valid values are JKS, PKCS12, and SSO.
Keytab None Absolute path for the Kerberos keytab file.

Overridable?
Property Name
Link Buffer 4 Maximum number of write buffers available on a ●

Count single channel at one time. linkBufferCount
Note:
fabric property shmDefaultNumMemoryBuffers.
Link 30000 Handshake and ACK timeout in milliseconds for

Handshake the shared memory channel setup.
Link Heartbeat 3600000 Maximum interval in milliseconds for the

Interval heartbeat signal on a channel between the
connector and the fabric instance, used for health
check status.
Note:
Set this value to be greater than Link Handshake
Timeout.
NNE Accepted Encryption level for NNE.

Encryption Valid values are Accepted, Rejected, Requested,
Level and Required.
NNE AES256, List of the encryption algorithms used by the

Encryption AES192, database instance.
Types AES128,
3DES168,
3DES112,
DES56C,
DES40C,
RC4_256,
RC4_128,
RC4_40,
RC4_56
NNE Integrity Accepted Checksum level for data integrity (for NNE).
Level Valid values are Accepted, Rejected, Requested,
and Required.
NNE Integrity sha1, md5, Checksum algorithm for data integrity validation
Types SHA256, (for NNE).
SHA384,
SHA512
Number of 3 The number of threads used to process data at ●

Transfer the same time during a single request. transferThreads
Threads

Overridable?
Property Name
Password None The password of the user or service account

credential.
Port 1521 The IP port of the target host and is a required

property.
Preserve Case False Preserve the case sensitivity of object names. ●

When set to true, database, table, role, and user preserveCase
names are kept in the format they are written
(upper, lower, or mixed case). When set to false,
all objects convert to upper case when sent to the
Oracle database.
Read Timeout 3600000 Number of seconds to wait to read between data ●

packets when importing data messages. readTimeout
Valid values are 300000–8640000 milliseconds.
Response 86400000 Number of milliseconds to wait for the final data ●

Timeout exec response when all the data has been responseTimeout
transferred.
Role Support False Enable user role support for the target system. ●
When set to true, the user role from the initiator or roleSupport
target based on role mapping is applied to the
target system and any errors are returned back to
the user. When set to false, roles are not applied
to the target system.
Schema Name None Schema name provided in the user query. If no ●

schema value is entered, the system adds the schemaName
username as the default.
Server None This is the IP address or DNS name of the target

host and is a required property. Cannot use
multiple hostnames.
SID or None Name of the Oracle instance. This is a required ●

ServiceName property. sid
SSL Peer None Valid values are None, Server, or Both.

Authentication
Mode
SSL Server DN None The Server Distinguished Name to match. When

SSL authentication is set to server or both , you
can optionally choose to match the distinguished
name in addition to the server authentication.

Overridable?
Property Name
Temporary None The temporary database name for table creation. ●

Schema Name tempDbName
Truststore None The Truststore Password is used when SSL

Password authentication is set to Both.
Truststore Path None The Truststore Path is used when SSL

authentication is set to Both.
Truststore Type JKS The Truststore Type is used when SSL

authentication is set to Both.
Valid values are JKS, PKCS12, and SSO.
Username None Name of the user or service account for Kerberos

authentication.
Write Timeout 3600000 Number of milliseconds to wait to write between ●

data packets when exporting data messages. writeTimeout
Valid values are 300000–86400000 ms.
Oracle Target Connector Tasks

If you designated an Oracle target connector in a link pairing with a Teradata database, perform the
following task:
1. Set up user mapping.
2. Set up role mapping.
Setting Up User Mapping
1. Add user mapping when the Oracle database is using the OS user authentication on a local system.
For more information, see Adding a User Mapping.
2. Edit the following Teradata-to-Oracle link settings.
Settings Description
Target properties Configure the following Oracle user credentials:

• Username
• Password
User mapping Select the user mapping previously created.

Setting Up Role Mapping
The Oracle connector supports role mapping with Teradata Database 16.20 Feature Update 1 and later.
Note:
The following role support features are not supported with the Teradata Oracle connector:
• Authenticating roles with passwords
• Comma-separated role lists in SET ROLE
• Except clause
1. To enable Role Support, set the connector property to TRUE.
Testing Oracle Connectors and Links

After completing the tasks required to configure the Oracle target connector and links that use a Teradata
connector as an initiator, do the following to test connectivity:
2. Run a link diagnostic check for all links that use an Oracle connector as a target.
3. Run a link bandwidth test for all links that use an Oracle connector as a target.
Oracle Connector Privileges and Security
Oracle Target Connector Security Guidelines
Oracle connectors support authentication for database (DB Password), operating system (OS Auth),
encryption (SSL or NNE), and Kerberos security mechanisms when acting as target connectors. The
following considerations apply to each of the security mechanisms:
• The username and password assigned and communicated from the initiator connector takes
precedence over the one defined for the Oracle target connector properties.
For example, if the Teradata initiator provides an authorization object, the Teradata initiator settings
take precedence over security-related Oracle connector property settings. Defining these connector
properties is optional. However, if credentials are not provided by the initiator connector, a username
and password must exist in the connector property settings.
• An Administrator can define user mappings in the QueryGrid portlet if using the OS Auth
authorization.
• For user mapping, the local user submitting the query is mapped to the target user that submits the
query. User mapping is applicable when the Oracle database is set up with the OS Auth mechanism
and the target user is not the same as the authenticating user.

Authentication
Database
Oracle stores encrypted credential information and user passwords in the data dictionary to
authenticate users attempting to connect to the database.
The following property settings are required for Oracle target connectors using the DB
Password authentication.
Setting Description
Authentication Mechanism Set to DB Password.
Username [Optional] Set to the authorized user name.
Password [Optional] Set the password for the authorized user.
Operating System
The operating system authentication option is only available with on-premises systems.
The following property settings are required for Oracle target connectors using the OS Auth
authentication. The Teradata Connector username takes precedent over the username and
password set in the Oracle connector properties.
Setting Description
Authentication Mechanism Set to OS Auth.
Username [Optional] Set to the authorized user name.
Kerberos
Teradata Kerberos set up must be completed before configuring QueryGrid. The following
property settings are required for Teradata target connectors using the Kerberos security
model. The Teradata Connector username takes precedent over the username and password
set in the Oracle connector properties. Both password and keytab can be selected for
authentication, if both are provided, password takes precedence over keytab authentication.
Setting Description
Authentication Mechanism Set to Kerberos.
Username [Optional] Set to the Kerberos principal name.
Password [Optional] Set to the password for the Kerberos principal name.
QueryGrid authenticates a principal using a password.
Keytab Set to the absolute path to the Kerberos Keytab file.
For more information, see Oracle Connector and Link Properties.

SSL
SSL can be used to authenticate any client to any oracle database server that is configured to
communicate over SSL. SSL authentication can be used in conjunction with other
authentication methods like DB Password, Kerberos, and so on. The following connector
properties must be configured when setting up SSL.
Setting Description
Encryption Set to SSL.

Mechanism
SSL Authentication Set the type of authentication to use between the active and standby
servers using one of the following options:
• Server – only the server authenticates to the client
• Server and Client – both authenticate to each other
• Neither – only encryption is used, no authentication
Port Set to the port used for encrypted communication.
Truststore Password Set the SSL truststore password.
Truststore Path Set the truststore certificate path sent by the server for verification.
Only available when SSL authentication is set to Server or Both.
Truststore Type Set the SSL truststore type.
Keystore Password Set the SSL keystore password.
Keystore Path Set the keystore certificate path sent by the client for verification. Only
available when SSL authentication is set to Server or Both.
Keystore Type Set the keystore type.
Encryption
Oracle databases can be configured to support either secure sockets layer (SSL) or native network
encryption (NNE), but not both. For more information, refer to your Oracle user manuals.
SSL
SSL encrypted communication occurs between the Oracle client and the Teradata Database
instance. The following connector properties must be configured when setting up SSL.
Setting Description
Encryption Set to SSL.

Mechanism
SSL Authentication Set the type of authentication to use between the active and standby
servers using one of the following options:
• Server – only the server authenticates to the client
• Server and Client – both authenticate to each other
• Neither – only encryption is used, no authentication

Setting Description
Port Set to the port used for encrypted communication.
SSL Server DN The Server Distinguished Name to match. When SSL authentication is
set to server or both , you can optionally choose to match the
distinguished name in addition to the server authentication.
Truststore Path Set the truststore certificate path sent by the server for verification. Only
Truststore Type Set the SSL truststore type.
Truststore Password Set the SSL truststore password.
Keystore Password Set the SSL keystore password.
Keystore Path Set the keystore certificate path sent by the client for verification. Only
Keystore Type Set the keystore type.
NNE
NNE encryption allows data to be encrypted as the data moves back and forth from a database
instance.
Setting Description
Encryption Set to NNE.

Mechanism
NNE Encryption Set to the level of encryption behavior when a client, or server acting
Level as a client, connects to the database instance.
NNE Encryption List of encryption algorithms used by the database instance. The
Types algorithms are used in the listed order for decryption until one succeeds
or the end of the list is reached.
NNE Integrity Level Set to the level of data integrity when a client, or server acting as a
client, connects to the database instance.
NNE Integrity Types Set the algorithm for checksum.
Oracle Target Connector Privileges
When running schema discovery (Teradata-initiated help foreign) queries, the target information must
be retrieved from the Oracle data dictionary views. You must have access to the views in order to
successfully receive the results. When collect metrics is enabled, you must have access to the
Oracle performance view, V$SQL, to collect resource utilization data. To access tables with Varray type,
the user must have the SELECT_CATALOG_ROLE or SELECT ANY DICTIONARY grant to run the
query if Varray is not already defined in the accessible schema.

Using the Oracle Connector
Oracle Connector Supported Operations

Teradata QueryGrid supports the following operations when Oracle is the target connector. Refer to SQL
Command Reference for the Teradata Connector for information on a specific SQL syntax listed.
• Select
• Insert
• Explain
• Show/Describe
• Pass Through
QueryGrid supports predicate pushdown by default. The Oracle target connector supports the following
logical WHERE conditions and expressions from Teradata systems: Abs, And, Or, Not, Gt, Lt, Le, Ge,
Ln, Eq, Cast, IsNULL, Is Not NULL, Between, Concat, Extract, Lower, Upper, Like, Plus, Minus, Mult, Div,
SQRT, Substring, Trim, In, and NOT IN.
Select
The following examples use different SELECT commands on the Teradata system that are supported
by the Oracle target connector.
Select
SELECT CAST(Price AS DECIMAL (8,2))
, mileage
, CAST(make AS VARCHAR(20))
, CAST(model AS VARCHAR(20))
FROM cardata@oraclefs_active WHERE make=’Buick’;
price mileage make model
-------- ------- ------ --------------------
17314.10 8221 Buick Century
17542.04 9135 Buick Enclave
Select with Foreign Table

SELECT * FROM FOREIGN TABLE (SELECT make, model FROM default.cardata where make
= 'Buick')@oraclefs_active AS dt;
make model
------ --------------------
Buick Century
Buick Enclave

Select with Export Clause

SELECT * from FOREIGN TABLE(select * from tmpabc )@oraclefs_active
EXPORT((select * from oracleTypet) AS tmpabc) as dt;
*** Query completed. One row found. 11 columns returned.

c1 c2
-------------------- ---------------------------------------- -------------
abc aaaaxxxxxx
Select with Returns Clause

SELECT * FROM datatypes1@oraclefs_active RETURNS (varchar1 VARCHAR(5) CHARACTER
SET LATIN) WHERE bigint1 > 10000 AND double1 < 10000;
Insert
The following example uses the INSERT command on the Teradata system that is supported by the
Oracle target connector.
INSERT INTO new_cardata@oraclefs_active SELECT * FROM td_cardata;
Explain
The following examples use the EXPLAIN SELECT and EXPLAIN INSERT commands on the Teradata
system that are supported by the Oracle target connector.
Explain Select
explain select * from SIMBATERADATA.T_BASIC@oraclefs_active;
*** Help information returned. 34 rows.

Explanation
---------------------------------------------------------------------------
1) First, we do an all-AMPs RETRIEVE step executing table operator
TD_SYSFNLIB.QGINITIATORIMPORT in TD_MAP1 with a condition of (
"(1=1)").
Remote Queries:
1. EXPLAIN PLAN SET STATEMENT_ID = '00000000006b' FOR SELECT id
,c1 FROM SIMBATERADATA.T_BASIC

2. [Statement_ID=00000000006b, Plan_ID=375, Timestamp=26-APR-18,

Remarks=, Operation=SELECT STATEMENT, Options=, Object_Node=,
Object_Owner=, Object_Name=, Object_Alias=, Object_Instance=,
Object_Type=, Optimizer=ALL_ROWS, Search_Columns=, ID=0,
Parent_ID=, Depth=0, Position=3, Cost=3, Cardinality=9, Bytes=117,
Other_tag=, Partition_Start=, Partition_Stop=, Partition_ID=,
Distribution=, Cpu_Cost=37137, IO_Cost=3, Temp_Space=,
Access_Predicates=, Filter_Predicates=, Projection=, Time=1,
Qblock_name=, Statement_ID=00000000006b, Plan_ID=375,
Timestamp=26-APR-18, Remarks=, Operation=TABLE ACCESS,
Options=FULL, Object_Node=, Object_Owner=SIMBATERADATA,
Object_Name=T_BASIC, Object_Alias=T_BASIC@SEL$1,
Object_Instance=1, Object_Type=TABLE, Optimizer=ANALYZED,
Search_Columns=, ID=1, Parent_ID=0, Depth=1, Position=1, Cost=3,
Cardinality=9, Bytes=117, Other_tag=, Partition_Start=,
Partition_Stop=, Partition_ID=, Distribution=, Cpu_Cost=37137,
IO_Cost=3, Temp_Space=, Access_Predicates=, Filter_Predicates=,
Projection="ID"[NUMBER,22], "C1"[VARCHAR2,100], Time=1,
Qblock_name=SEL$1]
The size of Spool 2 is estimated with no confidence to be 40,000
rows (6,440,000 bytes). The estimated time for this step is 0.07
seconds.
-> The contents of Spool 2 are sent back to the user as the result of
statement 1. The total estimated time is 0.07 seconds.
Explain Insert
EXPLAIN INSERT INTO SIMBATERADATA.T_BASIC@oraclefs_active(100, 'againthruQG');
*** Help information returned. 34 rows.

Explanation
---------------------------------------------------------------------------
1) First, we do an INSERT step into Spool 5.
2) Next, we do a single-AMP RETRIEVE step from Spool 5 (Last Use) by
way of an all-rows scan executing table operator
TD_SYSFNLIB.QGINITIATOREXPORT in TD_MAP1 with a condition of (
"(1=1)") into Spool 3 (used to materialize view, derived table,

table function or table operator T_BASIC) (all_amps), which is

built locally on that AMP.
Remote Queries:
1. EXPLAIN PLAN SET STATEMENT_ID = '00000000002c' FOR INSERT INTO
T_BASIC VALUES (?,?)
2. [Statement_ID=00000000002c, Plan_ID=401, Timestamp=14-MAY-18,
Remarks=, Operation=INSERT STATEMENT, Options=, Object_Node=,
Object_Owner=, Object_Name=, Object_Alias=, Object_Instance=,
Object_Type=, Optimizer=ALL_ROWS, Search_Columns=, ID=0,
Parent_ID=, Depth=0, Position=1, Cost=1, Cardinality=1, Bytes=13,
Other_tag=, Partition_Start=, Partition_Stop=, Partition_ID=,
Distribution=, Cpu_Cost=0, IO_Cost=1, Temp_Space=,
Access_Predicates=, Filter_Predicates=, Projection=, Time=1,
Qblock_name=,Statement_ID=00000000002c, Plan_ID=401,
Timestamp=14-MAY-18, Remarks=, Operation=LOAD TABLE CONVENTIONAL,
Options=, Object_Node=, Object_Owner=SIMBATERADATA,
Object_Name=T_BASIC, Object_Alias=, Object_Instance=,
Object_Type=, Optimizer=, Search_Columns=, ID=1, Parent_ID=0,
Depth=1, Position=1, Cost=, Cardinality=, Bytes=, Other_tag=,
Partition_Start=, Partition_Stop=, Partition_ID=, Distribution=,
Cpu_Cost=, IO_Cost=, Temp_Space=, Access_Predicates=,
Filter_Predicates=, Projection=, Time=, Qblock_name=INS$1]
The size of Spool 3 is estimated with high confidence to be 1 row
(71 bytes). The estimated time for this step is 0.03 seconds.
3) We do an all-AMPs RETRIEVE step in TD_Map1 from Spool 3 (Last Use)
by way of an all-rows scan into Spool 6 (Last Use), which is built
locally on the AMPs. The size of Spool 6 (Last Use) is estimated
with high confidence to be 1 row (64,029 bytes). The estimated
time for this step is 0.08 seconds.
-> No rows are returned to the user as the result of statement 1.
Show or Describe
The following examples use different HELP commands on the Teradata system to show or describe
queries for schema discovery requests that are supported by the Oracle target connector.
Help Foreign Server

help foreign server oraclefs_active;

USERNAME PRAMA_USR
USER_ID 597
CREATED 2018-04-05 07:54:50.000000
COMMON NO
ORACLE_MAINTAINED N
Help Foreign Database or Schema

help foreign schema SIMBATERADATA@oraclefs_active;

OWNER SIMBATERADATA
TABLE_NAME ORACLETYPET
TABLESPACE_NAME USERS
CLUSTER_NAME ?
IOT_NAME ?
STATUS VALID
PCT_FREE 10
PCT_USED ?
INI_TRANS 1
MAX_TRANS 255
INITIAL_EXTENT 65536
NEXT_EXTENT 1048576
MIN_EXTENTS 1
MAX_EXTENTS 2147483645
PCT_INCREASE ?
FREELISTS ?
FREELIST_GROUPS ?
LOGGING YES
BACKED_UP N
NUM_ROWS 1
BLOCKS 5
EMPTY_BLOCKS 0
AVG_SPACE 0
CHAIN_CNT 0
AVG_ROW_LEN 89
AVG_SPACE_FREELIST_BLOCKS 0
NUM_FREELIST_BLOCKS 0
DEGREE 1
INSTANCES 1

CACHE N
TABLE_LOCK ENABLED
SAMPLE_SIZE 1
LAST_ANALYZED 2018-02-01 03:00:22.000000
PARTITIONED NO
IOT_TYPE ?
TEMPORARY N
SECONDARY N
NESTED NO
BUFFER_POOL DEFAULT
FLASH_CACHE DEFAULT
CELL_FLASH_CACHE DEFAULT
ROW_MOVEMENT DISABLED
GLOBAL_STATS YES
USER_STATS NO
DURATION ?
SKIP_CORRUPT DISABLED
MONITORING YES
CLUSTER_OWNER ?
DEPENDENCIES DISABLED
COMPRESSION DISABLED
COMPRESS_FOR ?
DROPPED NO
READ_ONLY NO
SEGMENT_CREATED YES
RESULT_CACHE DEFAULT
CLUSTERING NO
ACTIVITY_TRACKING ?
DML_TIMESTAMP ?
HAS_IDENTITY NO
CONTAINER_DATA NO
INMEMORY DISABLED
INMEMORY_PRIORITY ?
INMEMORY_DISTRIBUTE ?
INMEMORY_COMPRESSION ?
INMEMORY_DUPLICATE ?
Help Foreign Table

help foreign table SIMBATERADATA.t1@oraclefs_active;
*** Query completed. One row found. 36 columns returned.

*** Total elapsed time was 1 second.

OWNER SIMBATERADATA
TABLE_NAME t1
COLUMN_NAME A
DATA_TYPE DATE
DATA_TYPE_MOD ?
DATA_TYPE_OWNER ?
DATA_LENGTH 7
DATA_PRECISION ?
DATA_SCALE ?
NULLABLE Y
COLUMN_ID 1
DEFAULT_LENGTH ?
DATA_DEFAULT ?
NUM_DISTINCT ?
LOW_VALUE ?
HIGH_VALUE ?
DENSITY ?
NUM_NULLS ?
NUM_BUCKETS ?
LAST_ANALYZED ?
SAMPLE_SIZE ?
CHARACTER_SET_NAME ?
CHAR_COL_DECL_LENGTH ?
GLOBAL_STATS NO
USER_STATS NO
AVG_COL_LEN ?
CHAR_LENGTH 0
CHAR_USED ?
V80_FMT_IMAGE NO
DATA_UPGRADED YES
HISTOGRAM NONE
DEFAULT_ON_NULL NO
IDENTITY_COLUMN NO
EVALUATION_EDITION ?
UNUSABLE_BEFORE ?
UNUSABLE_BEGINNING ?
Pass Through
The following example uses the PASS THROUGH operation on the Teradata system to allow DDL and
DCL queries to be run on Oracle, as supported by the Oracle target connector.
call syslib.executeforeignsql('CREATE TABLE rowid1(a rowid)','oraclefs_active');


Session override is supported from the Teradata initiator connector. For more information, see Overriding
Session Properties.
1. From Teradata, enter the following syntax to override session properties:
set foreign server attr = ‘servername=oraclefs_active;readTimeout=100000;’
for session volatile;
Oracle Data Type Mapping
Global Types to Oracle Data Types

The initiator connector maps global data types to Teradata data types.
Global Data Type Oracle Data Type
G_Array Varchar (Character Set Unicode)
G_Array_VC_UTF16 / G_Array_VC_Latin Array
G_Bigint Bigint
G_Blob Blob
G_Boolean Byteint
G_Byte Byte
G_ByteInt Byteint
G_Char_Latin / G_Char_UTF16 Char (Character Set Latin / Unicode)
G_Clob_UTF16 / G_Clob_Latin Clob
G_Date Date
G_Decimal Decimal
G_Double Double precision
G_Float Float
G_Integer Integer
G_IntervalDayToSecond Interval day to second
G_IntervalYearToMonth Interval year to month
G_JSON_UTF16 / G_JSON NVarchar2

Global Data Type Oracle Data Type
G_Number Number
G_SmallInt Smallint
G_Time Time
G_TimeWithTimeZone Time with time zone
G_Varbyte Long raw
G_Varchar_Latin Varchar (Character Set Latin)
G_Varchar_UTF16 NVarchar2 (Character Set Unicode)
G_XML NVarchar2
Others Varchar2
Oracle Data Types to Global Types

The target connector maps Teradata data types to global data types.
Oracle Data Type Global Data Type
Binary_Double G_Double
Binary_Float G_Float
Blob G_Blob
Char G_Char_UTF16 / G_Char_Latin (based on charset)
Clob G_Clob_UTF16
Date G_Date
IntervalDS G_IntervalDayToSecond
IntervalYM G_IntervalYearToMonth
Long G_Clob_UTF16
Long raw G_Blob
NChar G_Char_UTF16
NClob G_Clob_UTF16
Number G_Number
NVarchar G_Varchar_UTF16

Oracle Data Type Global Data Type
RAW G_Byte
Timestamp with local time zone G_TimeStamp
Timestamp with time zone G_TimestampWithTimeZone
Varchar2 / Varchar G_Varchar_UTF16 / G_Varchar_Latin (based on charset)
Varray G_Array
Note:
User must have access to SELECT_CATALOG_ROLE.
Oracle Varchar and Binary Types Considerations

Oracle connector BLOB columns are restricted to a maximum 2GB and CLOB columns are restricted
a maximum 1GB in size. However, due to the in-memory nature of these types, a large amount of
resources are required on the Oracle side when their sizes near 1GB. Therefore, Teradata recommends
increasing the Oracle connector driver heap size when working with CLOB or BLOB types.
Oracle Connector Limitations

The following features are not supported between Oracle target connectors and Teradata QueryGrid
connectors:
• Remote table optimization
• Foreign function execution
• Case-sensitive column names

IV
Managing QueryGrid
11
Modifying an Existing QueryGrid
Configuration
Working with Active, Pending, or Previous Versions
Making changes to the Teradata QueryGrid configuration can potentially impact production workloads, so
Teradata QueryGrid supports the ability to test configuration changes before those changes are activated.
After the configuration change is tested and verified, it can be activated so that it becomes available to
production workloads.
Changes to configuration entities (fabrics, connectors, links, communication policies, and networks) are
versioned. When a query starts, it resolves which versions of the configuration entities it will use. These
versions are passed around to all components executing on behalf of that query, so that all components
use the same version of the configuration.
When a configuration change is made, it may take some time for that change to reach all the components
of a system. If a query references a version of a configuration entity that has not been propagated
throughout the system, the query will fail. Configuration changes should be persisted and tested before
being applied to production workloads, to make sure the configuration change is distributed to all the
components of Teradata QueryGrid.
Configurations can be in one of three states: active, pending, and previous. Active is the tested and verified
actively running version of the configuration. Pending is used for testing new or modified configurations.
Active configurations are put in a previous state when another version of the configuration is activated.
If you replace an active version, the formerly active version becomes the previous version and the former
previous version is deleted. If you activate a pending version, the formerly active version that you replaced
becomes the previous version. If you activate a previous version, the active version becomes the previous
version, and any pending version remains the pending version.
Replacing Active Network Versions with Pending or Previous

Versions
1. From Fabric Components, select Networks.
2. Click next to the pending or previous version that you want to make the active version and select
Activate.
Replacing Active Communication Policies Versions with

Pending or Previous Versions
1. From Fabric Components, select Communication Policies.
2. Click next to the pending or previous version that you want to make the active version and select
Activate.

11: Modifying an Existing QueryGrid Configuration
Replacing Active Fabrics, Connectors, and Links Versions with

Pending or Previous Versions
1. From Fabric Configuration, select Fabrics.
Option Description
Fabrics a. Click next to the pending or previous version that you want to make the active
version and select Activate.
Connectors a. Click the Connectors tab.

b. Click next to the pending or previous version that you want to make the active
Links a. Click the Links tab.

b. Click next to the pending or previous version that you want to make the active
Editing a Fabric
Edit a fabric if or when you need to change the name or description of the fabric.
2. Click next to the fabric row that you want to edit and select Edit.
Only Fabric name and Description can be edited.
Editing a Connector
2. Click the Connectors tab.
3. Select a connector, click next to the connector that you want to edit, and select Edit.
4. Modify the attributes of the connector that you want to change.
5. Click Save.
Editing a Link
You can edit any of the link properties. You cannot edit a previous version of a link.
2. Click the Links tab.
3. Click next to a link and click Edit.
When selecting initiating and target connectors, only active connections are available from each list.

11: Modifying an Existing QueryGrid Configuration
Editing a Data Center

Edit a data center if or when you need to change its name or description.
1. Under Fabric Components, select Data Centers.
2. Click next to the data center that you want to edit and select Edit.
Editing a System
You can edit any of the system properties as needed.
2. Click next to a system and click Edit.
Editing a Network
Edit a network when you need to change its name, description, or its rules.
1. Under Fabric Components, select Networks.
2. Click next to a network and click Edit.
Editing a Communication Policy

Edit a communication policy when you need to change its properties. You cannot change a policy name
or description if the policy is in pending state.
You cannot edit a previous version.
1. Under Fabric Components, select Communication Policies.
2. Click next to the communication policy that you want to edit and select Edit.
Editing a User Mapping

Edit a user mapping when you need to change any of the user mapping properties.
1. Under Fabric Components, select User Mappings.
2. Click next to the user mapping that you want to edit, and select Edit.

12
Teradata QueryGrid Monitoring, Logging, and
Error Handling
Fabric Overview
The Fabric Overview displays a graphical representation of the fabrics in the QueryGrid portlet. For each
fabric, the overview shows the fabric name, fabric components, component names, and information about
the health of the components.
Item Description
Fabric Name The fabric name is displayed in the upper left corner of the overview.
Data Center and The systems, connectors, and links in the data center are bounded by a circle. The data
Data Center center name is displayed outside the circumference of the circle.
Name
Systems and Systems are displayed within the circle of the data center. The system name is displayed
System Names next to the system icon.
Icon State
System status is normal.
System has one or more issues resulting in a warning or warnings.
System has a critical issue or issues.
Connectors and Connectors are displayed as semi-circles within the circle of the data center, next to the
Connector system they are associated with. The connector name is displayed next to the connector
Names icon.
Within the semi-circle of the icon:
• The filled circle represents the initiating connector.
• The unfilled circle represents the target connector.
Icon State
Connector status is normal.
Connector has one or more issues resulting in a warning or warnings.
Connector has one or more critical issues, and may also have one or more
issues resulting in a warning or warnings.
Links Directional arrows ( ) show the data transfer path between initiating connectors and
target connectors of systems within the data center.

12: Teradata QueryGrid Monitoring, Logging, and Error Handling
Item Description
• For an initiating connector, the arrow starts at the filled circle and points to the unfilled
circle representing the target connector.
• For a target connector, the arrow starts at the unfilled circle and points to the filled
circle representing the initiating connector.
Viewing a Fabric Overview

1. In the QueryGrid portlet, select Fabric Overview.
Viewing Component Details

The Fabric Overview contains information about the systems, connectors, and links in the data center.
1. In the QueryGrid portlet, select Fabric Overview.
2. For a system, connector, or link, do one of the following:
• Hover your mouse over the component to display a balloon containing information about the
component.
• Click the component to display detailed information in a Component Details panel.
Component Details
System Hovering your mouse over a system icon displays a balloon containing the system name,
a summary of warnings (if present), and a summary of critical issues (if present). If the
system has both warnings and critical issues, summaries of both are displayed in the
balloon.
Selecting a system icon displays the Component Details panel. The information
displayed in the panel depends on the system status:
• If the system status is normal, the following details are displayed in the panel:
◦ System name
◦ System description
◦ Node software version installed
• If the system status has one or more warnings or critical issues, the following additional
details are displayed in the panel:
◦ Summary of each issue
◦ The time each issue was reported
◦ Duration of each issue
◦ Details about each issue
Connector Hovering your mouse over a connector icon displays a balloon containing the connector
name, a summary of warnings (if present), and a summary of critical issues (if present).
If the connector has both warnings and critical issues, summaries of both are displayed
in the balloon.

Selecting a connector icon displays the Component Details panel. The information
displayed in the panel depends on the connector status:
• If the connector status is normal, the following details are displayed in the panel:
◦ Connector name
◦ Connector description
◦ Connector software name
◦ Connector software version installed
• If the connector status has one or more warnings or critical issues, the following
additional details are displayed in the panel:
◦ Summary of each issue
◦ The time each issue was reported
◦ Duration of each issue
◦ Details about each issue
Link Hovering your mouse over an arrow displays a balloon containing the name of a link. If
more than one link is configured, the number of links and their names are displayed in
the balloon.
Selecting an arrow displays the following in the Component Details panel.
• Link name
• Link description
• The link properties configured for each link associated with the connector (bridges, if
any, initiating and target connector properties, hops, and so forth)
Viewing Components with the Navigation Panel

If the data center contains more components than can be displayed in the Fabric Overview, you can
use the Navigation panel to view components in a specific area.
1. In the Fabric Overview, click in the upper right corner.

2. Move the view box to the area you want to see.
Issues
Use Issues to review possible problems with QueryGrid. Some of these issues might require you to take
action. The following types of issues are reported:
• Teradata QueryGrid component has gone offline.
• Teradata QueryGrid Manager has failed.
• Teradata QueryGrid Manager backup failed.
• Teradata QueryGrid Manager is running out of disk space.
• One or more Teradata QueryGrid Managers are running different versions of the Teradata QueryGrid
Manager package.
• One or more nodes on the system are missing the connector package.
• System time is incorrect on a node or a Teradata QueryGrid Manager.

• Fabric unexpectedly restarted.

• Driver unexpectedly restarted.
• Connector is missing a link.
• Network configuration of link has failed to match network address on nodes.
Each condition has an associated severity, either critical or warning.
You can view the history of an issue. With the exception of Fabric and Driver unexpected restart issues,
issues are automatically resolved once the underlying problem is corrected. You can manually delete the
Fabric and Driver restart issues to clear them.
Viewing Issues History

1. Select Issues and click View History.
2. If you do not want to view the issues history for the last week (default), click next to the time range
and select another time range from the list.
Issues Details
Issues details consists of a read-only text box that displays the entire error message that was returned
for this issue. Select the issue to view the entire message.
Monitoring User Queries Between Local and Remote

Servers
Use the following portlets to monitor the queries running on the source and target system:
• Completed Queries
• My Queries
• Query Groups
• Query Monitor
Query performance data includes metrics about each active query:
• CPU
• CPU Skew
• Rows Transferred
• Bytes Transferred
• Data Skew
These messages include local and remote session details, query text, errors, and durations for all query
phases.
The data is captured from all nodes participating in the query for a particular query. The captured data is
periodically summarized. The default summary frequency is 30 seconds.
For more information, see Teradata® Viewpoint User Guide, B035-2206.

Logging and Error Handling

Using the QueryGrid Portlet to View Issues
The Issues view in the QueryGrid portlet allows you to review possible problems with Teradata QueryGrid.
Some of these issues might require you to take action. The following types of issues are reported:
• Teradata QueryGrid component has gone offline.
• Teradata QueryGrid Manager has failed.
• Teradata QueryGrid Manager backup failed.
• Teradata QueryGrid Manager is running out of disk space.
• One or more Teradata QueryGrid Managers are running different versions of the Teradata QueryGrid
Manager package.
• One or more nodes on the system are missing the connector package.
• System time is incorrect on a node or a Teradata QueryGrid Manager.
• Fabric unexpectedly restarted.
• Driver unexpectedly restarted.
• Connector is missing a link.
• Network configuration of link has failed to match network address on nodes.
Each condition has an associated severity, either critical or warning.
To view issues history from the QueryGrid portlet, see Viewing Issues History.
Teradata QueryGrid Portlet Logging Settings

You can set the log data retention and query data retention times in the QueryGrid portlet. See Editing
Manager Settings.
Enable Logging Connector Property

There are two ways to enable logging, globally for the entire connector or link (as described here), or for
a specific user specific to a link (as described in Adding a Link and Editing a Link). The latter option is the
preferred option to limit the number of logs generated to only a single user. Increased logging requires
increased CPU, IO, and network utilization and can affect the performance of the system and queries. So,
enabling logging for a single user when troubleshooting a problem is better than enabling it for all users.
You can enable global logging by setting the Enable Logging connector property. The property can be set
to various debug levels. The default is None for the connectors and can be overridden at the connector
or the link level. The available debug levels are None, Warn, Info, or Debug. Once set, this property is
utilized for the entire query and carried forth to the target connector. This setting applies to both the initiating
and target connector; however, the logging level for the initiator connector in the link takes precedence if
they are set differently. See the Enable Logging property in Teradata Connector and Link Properties.

13
Troubleshooting
Solutions for Job Problems

If errors occur without explanation on why queries are failing, enable logging and increase the messaging
count to have errors and messages collected in a support bundle. Send the support bundle to the
QueryGrid Manager for troubleshooting. See Logging and Error Handling for information on enabling
logging levels.
The following errors originate from the initiating Teradata system.
Problem
Error Message Solution
Description
Allowed OS user is QGInitiatorExportContract: 2689: (NO UUID YET) Update allowed OS user on
not correctly ExportMeta : Connection not allowed for OS user initiator connector. For more
configured on id 14 information, see Teradata
initiator system. QueryGrid Security.
Allowed OS user is QGInitiatorExport: 9134: (a14554a5-8a07-492a- Update allowed OS user on

not correctly be57-000000000004) InitiatorDataExportReq : target connector. For more
configured on target [Error 9134] QGRemoteImport: 2689: information, see Teradata
system. RemoteDataImportReq : Connection not allowed QueryGrid Security.
for OS user id 14
System memory not QGInitiatorExport: 10201: (7031532d-f2a4-4a7e- Increase system memory for
sufficient on initiator a983-000000000001) InitiatorDataExportReq : initiator system.
system. shm alloc failed. requested 4198400b + existing
4198400b > max 5mb, linkbuffer size:count
1048576b:4
System memory not qginitiatorimport: 9134: (4bb2afaf- Increase system memory for
sufficient on target e428-45f1-90e8-000000000001) target system.
system. initiatordataimportreq : [error 9134]
qgremoteexport: 10201: remotedataexportreq :
shm alloc failed. requested 4198400b + existing
4198400b > max 5mb, linkbuffer size:count
1048576b:4
The (link buffer size qginitiatorexportcontract: 2001: (no uuid yet) Decrease link buffer size and
* link buffer) count is exportmeta : requested segment size for reader link buffer count on initiator
higher than the 1000000000b is larger than max allowed connector.
allowed value. 16777216b
LinkHandshake QGInitiatorExportContract: 2001: (NO UUID YET) Increase LinkHandshake

timeout not ExportMeta : Handshake with Fabric hit timeout timeout in the initiator
sufficient on initiator limit of 0 ms. Increase Link Handshake Timeout connector properties.
connector. and retry query
LinkHandshake QGInitiatorExport: 9134: (9c7d074e-4529-4a54- Increase LinkHandshake

timeout not a664-000000000002) InitiatorDataExportReq : timeout in the target
[Error 9134] QGRemoteImport: 2001: connector properties.

13: Troubleshooting
Problem
Description
sufficient on target RemoteDataImportReq :Handshake with Fabric

connector. hit timeout limit of 0 ms. Increase Link Handshake
Timeout and retry query
Driver not started/ QGInitiatorExportContract: 24585: Check driver status for target
offline on target (06592ddf-84cb-460b-afcd-000000000003) connector. If driver is offline,
system or incorrect ExportMeta : Driver TDdriver unreachable by restart tdqg-node service on
java path set. fabric on node sdt11134 the node.
Incorrect server QGInitiatorExportContract: 24582: Fix the server name target

name in target (9c7d074e-4529-4a54-a664-000000000004) connector property as an IP
connector. ExportMeta : [Error 1000] Login failure for address or DBS name of the
Connection to fakehost Thu May 10 08:45:52 PDT target host.
2018
Table does not exist QGInitiatorExportContract: 3706: Confirm that the table exists
on the target (9c7d074e-4529-4a54-a664-000000000004) and the query has the correct
system. ExportMeta : [Error 3807] Object 'testuser.temp_ reference.
table_non_exist' does not exist.
Syntax error on the QGInitiatorExportContract: 3706: Check the query submitted

target system. (9c7d074e-4529-4a54-a664-000000000004) and if there is a valid syntax
ExportMeta : [Error 3706] Syntax error: SELECT * on target system.
must have a FROM clause.
Syntax error for EXECUTEFOREIGNSQL:Error: 3707 (50081586- Check the query submitted in
foreignSQL pass bd87-4516-9285-000 ExecuteForeignSQL SP and
through. 000000017) ForeignFunctionDataExec : [Error if there is a valid syntax on the
3707] Syntax error, expected some target system.
thing like ‘(’ between the word ‘xx’ and ‘;’.
QueryGrid fastpath QGInitiatorImport: 3706: (9c7d074e-4529-4a54- Run the DIP script System
function, a664-000000000004) InitiatorDataImportReq : Functions if the fastpath
QGRemoteExport, [Error 3706] Syntax error, expected something like functions do not exists under
does not exist on ';' between the word 'QGRemoteExport' TD_SYSFNLIB on the target
the target system. Teradata system.
QueryGrid fastpath QGInitiatorExport: 3706: (9c7d074e-4529-4a54- Run the DIP script System
function, a664-000000000004) InitiatorDataExportReq : Functions if the fastpath
QGRemoteImport [Error 3706] Syntax error, expected something like functions do not exists under
does not exist on ';' between the word 'QGRemoteImport' TD_SYSFNLIB on the target
the target system. Teradata system.
Read timeout QGInitiatorImportContract: 2002: Increase readTimeout in the

exceeded to get the (9c7d074e-4529-4a54-a664-000000000006) initiator connector properties.
buffer for metadata ImportMeta : Hit read timeout (100ms) getting
request on the metadata buffer
initiator system.
Read timeout QGInitiatorExport: 9134: (f942f99a-3011-413b- Increase readTimeout in the

exceeded to get the bf40-000000000008) InitiatorDataExportReq : target connector properties.
buffer for data [Error 9134] QGRemoteImport: 2002:
transfer on the ExecRemoteImport : Hit read timeout (100ms)
target system. getting read buffer

13: Troubleshooting
Problem
Description
Write timeout QGInitiatorExport: 2003: (f942f99a-3011-413b- Increase writeTimeout in the

exceeded to get the bf40-000000000009) ExecInitExport : Hit write initiator connector properties.
buffer for data timeout (100ms) getting write buffer
transfer on the
initiator system.
Write timeout QGInitiatorImport: 9134: Increase writeTimeout in the

exceeded to get the (43b11795-2f81-42dc-892c-000000000001) target connector properties.
buffer for data InitiatorDataImportReq : [Error 9134]
transfer on the QGRemoteExport: 2003: Hit timeout (50ms)
target system. getting write buffer
Out of spool space QGInitiatorExport: 2646: (a18b6bce- Increase the spool space for
on target system ce8a-4ea0-97b3-000000000008) the user on the target system
during data transfer. InitiatorDataExportReq : [Error 2646] No more or reduce data set for the
spool space in testuser. query.
Error during data QGInitiatorImport: 1018: (341cab15-7eb7-46b2- Data transformation error

conversion on b78d-000000000ef2) UDT transform to internal could be due to mismatch in
initiator system. format failed data types on the initiator and
target system.
Error during data QGInitiatorExport: 40008: (6268d8db- Data transformation error

conversion on a3c3-4b62-82bd-000000000002) Export failed. could be due to a mismatch in
target system. [Error 9134] QGRemoteImport: 1018: UDT data types on the initiator and
transform to internal format failed target system.
Incorrect initiator QGInitiatorExport: 9134: (f0744a27-19bf-4ddb- Fix initiator network interface

network interface b543-00000000000a) InitiatorDataExportReq : address in link
setup in link. [Error 9134] qgremoteimport: 24582:
remotedataimportreq : qgc import req exception:
network 'ep_false_network' does not contain any
viable address for node sdt14780.la
Incorrect target QGInitiatorExportContract: 24602: (4bb2afaf- Fix the target network

network interface e428-45f1-90e8-00000000000b) ExportMeta : interface address in link.
setup in link. Network 'ep_false_network' does not contain any
viable address for node sdt14781
Connection timed QGInitiatorExportContract: 24586: Restart the node service if the

out when (3ba09cd6-8dc9-4a37-a80a-000000000001) fabric status in Viewpoint
connecting to the ExportMeta : QGCMetaTask: connection from shows offline.
target node during sdt14780.labs.teradata.com to next hop Run the link diagnostic check
the data transfer nodes failed. Connection attempt to 10.25.206. to confirm network
phase. 129:34835 hit timeout (0ms) connectivity is available
between the initiator and
target nodes. If the check
fails, increase the
openConnectionTimeout
fabric system property for the
initiator fabric.

13: Troubleshooting
Problem
Description
Note:
Increasing the fabric system
property should be done with
the help of a Teradata
Customer Support
Representative.
Connection timed QGInitiatorExport: 9134: (e7900c74-c423-4805- Increase

out when b6f0-000000000001) InitiatorDataExportReq : openConnectionTimeout
connecting to [Error 9134] QGRemoteImport: 24582: fabric system property for
initiator node during RemoteDataImportReq : QGC Import Req target fabric.
data transfer phase. Exception:Connection from sdt14781 to initiator
Note:
fabric nodes failed:([ 10.25.205.90 ])
the help of a Teradata
Customer Support
Representative.
Socket read timeout QGInitiatorImportContract: 24583: (b1872402- Increase

error. b855-463a-b772-000000000001) ImportMeta : connectionTimeout fabric
Couldn't establish connection to target fabric. (10. system property.
25.254.15;)Create AuthClient failed Socket read Note:
timed out after-300 ms, bytes read:0, total_bytes:
56(0)
QGInitiatorImport: 24582: the help of a Teradata
(62e4aabd-253d-4d54-92c2-000000000001) Customer Support
InitiatorDataImportReq : Socket read failed with Representative.
state 4 when trying to read 532648 bytes
ExportMeta : QGLClient::DoMetaRequest Read
timeout hit

14
Administrative Tasks
Teradata QueryGrid Manager Settings and Account

Management
After installing Teradata QueryGrid, use Managers to refine settings and service accounts.
Settings
Modifiable settings include query and log data retention time frame, query summary frequency,
and session timeout.
Use the Settings tab to change Teradata QueryGrid Manager settings.
Service Accounts
Service Accounts are used by Viewpoint and Teradata Support to access Teradata QueryGrid
Manager.
Use the Service Accounts tab to add or edit service accounts.
Managers
Teradata QueryGrid Managers provide centralized management and monitoring of QueryGrid. Managers
are used to install and upgrade software on Teradata QueryGrid systems. You can configure settings for
managers, such as the length of time to retain log data and the session timeout.
Managers Tab
Use the Managers tab to view details about existing managers.

You can view the details of managers and sort on the column headers to find the details you want.
Editing Manager Settings

2. Click the Settings tab to edit the following settings for the managers:
Setting Description
Log data retention Number of days to retain log data.

Valid values range from 1 to 365.
Query data retention Number of days to retain query data.


14: Administrative Tasks
Setting Description
Query summary frequency Number of seconds to wait between query summaries.

Session timeout Number of minutes to wait before a session times out.

3. Click Apply.
Service Accounts Tab
Service Accounts are used by Viewpoint and Teradata Support to access Teradata QueryGrid Manager.
Adding a Service Account

2. Click the Service Accounts tab.
3. Click next to Service Accounts.
4. Type a name in the Username box, up to 256 characters.
5. Type a password in the Password box, up to 256 characters.
6. Type the same password in the Confirm password box.
7. [Optional] Type a description in the Description box, up to 1000 characters.
8. Click Save.
Resetting a Service Account Password
Use a command line tool reset-password.sh to reset a service account password on the Teradata
QueryGrid Manager system.
1. From the command line of the Teradata QueryGrid Manager system, run: /opt/teradata/tdqgm/
bin/reset-password.sh
You must run the command as root or the tdqgm user.
Settings Tab
Modifiable settings include query and log data retention time frame, query summary frequency, and
session timeout.
Restarting a Fabric
Use the command line utility fabric-restart.sh to restart a fabric.

1. Log on to the system where the Teradata QueryGrid Manager is running.

2. From /opt/teradata/tdqgm/bin, run: ./fabric-restart.sh and answer the prompts.
Note:
You can run this command as the root or tdqgm user.
Fabrics
-------
1. Production (ACTIVE)
2. Production (PENDING)
Select a fabric [1-2]: 2
Systems
-------
1. ALL SYSTEMS
2. HdpProd
3. TD1
Select a system [1-3]: 1
Are you sure you want to restart Production (PENDING) on ALL SYSTEMS? [y/n]: y
Resetting Teradata QueryGrid Manager to Default

Settings
Use the command line utility reset.sh to reset a Teradata QueryGrid Manager back to its default settings.
2. From /opt/teradata/tdqgm/bin, run: ./reset.sh -f and type y when prompted.
Note:
You must run this command as the root or tdqgm user.
Result: The manager is reported as offline.
Removing Teradata QueryGrid Manager from a Cluster

You can only delete managers with a status of offline.
2. Make sure you have reset the Teradata QueryGrid Manager to its default settings.
3. From the QueryGrid portlet, select Managers.

4. Click the Managers tab, and select Delete for the manager you want to delete.
Backup and Restore

Teradata QueryGrid Manager provides commands for backing up and restoring the Teradata QueryGrid
configuration. Because the manager provides a clustering capability that involves replication of
configuration to all manager instances, it is typically unnecessary to restore from backup after a failure;
provided that one manager instance is still online, the configuration is preserved. However, there are
certain circumstances that may require a restore from backup:
• Recovery from a catastrophic failure where all manager instances were lost
• Cloning an existing configuration into a new cluster
When restoring from a backup, it is important to note that the manager instance being restored becomes
a new manager cluster. To add existing managers to the new manager cluster, run /opt/teradata/
tdqgm/bin/join-cluster.sh on each manager instance, one at a time. Wait for each instance to come
online before starting the next join cluster.
Note:
You must run the command as the root or tdqgm user.
Each manager instance automatically generates a backup file once a day located in /var/opt/teradata/
tdqgm/backups. Up to 7 days of backups are maintained.
Backup
The backup command is located at /opt/teradata/tdqgm/bin/backup.sh and must be run as the root
or tdqgm user. By default , backups are placed in the /var/opt/teradata/tdqgm/backups directory
and are named tdqgm-backup-YYYY-MM-DD.zip where YYYY-MM-DD is the current date. The backup
file includes all the configuration details and software packages that were uploaded to the Teradata
QueryGrid Manager.
Usage
To get help for the backup command, use the --help option:
/opt/teradata/tdqgm/bin/backup.sh --help
Result:
usage: backup [-f <file>] [-h] [-x]

Creates a backup file that enables the QueryGrid manager configuration to
be restored in the event of a catastrophic failure.
options:
-f,--file <file> The path to the backup file to create.

-h,--help Print this message.

-x,--exclude-software Flags if software files should be excluded from the
backup.
Example: Backing Up Teradata QueryGrid

To perform the back up, run:
/opt/teradata/tdqgm/bin/backup.sh
Result:
Starting backup...
Backup completed:
/var/opt/teradata/tdqgm/backups/tdqgm-backup-2016-06-16.zip
Restore
The restore command is located at /opt/teradata/tdqgm/bin/restore.sh and must be run as the
root or tdqgm user. The name of the backup file to restore as an argument is required.
Usage
To get help for the backup command, use the --help option:
/opt/teradata/tdqgm/bin/restore.sh --help
Result:
usage: restore [options] <backup-file>
Restores the QueryGrid manager configuration from a backup file in the event of
a catastrophic failure.
options:
-a,--public-address <address> The address other managers and nodes use

to access this manager instance.
-d,--data-center <name> The name of the data center to join.
-f,--force Force the restore to start without requiring
confirmation.
-h,--help Print this message
Example: Restoring Teradata QueryGrid

To restore the system, run:

/opt/teradata/tdqgm/bin/restore.sh <backup_file>
Enter public address for this manager instance [<public_address>]:
where <backup_file> is the path name of the backup ZIP file, similar to ~/tdqgm-
backup-2016-06-16.zip and <public_address> is the hostname or IP address of the Teradata
QueryGrid Manager system; for example: test.mydomain.com or 198.51.100.20.
Result (note, enter y at the prompt):
A restore from backup removes all data previously saved on this manager instance
and
all local manager services are restarted. This manager instance becomes a
standalone cluster.
Other managers can join this instance using the join-cluster command.
Do you wish to continue? [y/n]: y
Stopping QueryGrid Manager...
Deleting previous state...
Restoring configuration data...
Data Centers
------------
1. San Diego
2. Las Vegas
3. Atlanta
4. Richmond
Select data center of local manager instance [1-4]: 3
Restoring tdqg-node-16.00.00.00.DEV-30.tar.gz...
Restoring tdqg-teradata-connector-1.0-224-SNAPSHOT.tar.gz...
Restoring tdqg-fabric-1.00.00.00.tar.gz...
Restoring tdqg-teradata-connector-1.0-12-SNAPSHOT.zip...
Starting QueryGrid Manager...

Restore completed successfully.

Migrating QueryGrid Manager to a New Server

1. Install the same version of QueryGrid Manager on the new server as the original server.
2. Run the join-cluster command on the new server to cluster it to the original server.
For more information, see Clustering Deployed QueryGrid Manager Instances.
3. Run both servers concurrently for 5 minutes to make sure all data source nodes recognize the new
QueryGrid Manager instance.
4. Shut down the original QueryGrid Manager instance.
5. Make sure QueryGrid is functioning normally by running QueryGrid queries and confirming no issues
are reported in the Issues view of the QueryGrid portlet.
6. Remove the original QueryGrid Manager from the cluster.
For more information, see Removing Teradata QueryGrid Manager from a Cluster.
7. Uninstall QueryGrid Manager software on the original server.
For example, using the rpm -e tdqg-manager command.
QueryGrid Manager RESTful APIs

Advanced users can use REST APIs to automate the configuration and administration of QueryGrid.
QueryGrid Manager provides interactive documentation on automating any QueryGrid Viewpoint portlet
function through the use of these APIs. To access the interactive API documentation, go to https://
querygrid_manager_host:9443/swagger-ui/index.html.

V
Upgrading Software
15
Upgrading QueryGrid
Teradata QueryGrid Upgrade Overview

The steps for upgrading Teradata QueryGrid Manager are similar to those for installing it, whereas the
upgrade processes for connectors, fabrics, and node software differs from the installation process.
For connectors and fabrics, the upgrade process allows you to test new versions before deploying the new
versions to production. Upgrades to these components are considered configuration changes. For each
configuration, three versions can co-exist:
• Active
• Pending
• Previous
This protocol provides for pushing changes to all systems before implementation, allowing you to test new
connectors and fabrics on production deployments without affecting production workloads.
Note:
You can also update links, networks, and communication policies. Like connector and fabric
upgrades, such updates are considered configuration changes and are subject to the same version
and deployment protocol.
The upgrade process for QueryGrid node software differs somewhat from the installation process, with
the final deployment steps being handled automatically by the pre-existing version of the software.
Upgrade Considerations
The following considerations apply when upgrading QueryGrid Manager from QueryGrid 2.04 and earlier
to QueryGrid 2.05 and later:
• Previously collected log data and query metrics are reset.
QueryGrid metrics that display in Viewpoint are maintained and not reset.
• Query summarization and system health checks are suspended during the rolling upgrade until all
Managers are upgraded to the new version. Teradata recommends you perform rolling upgrades in
quick succession to minimize the amount of time different versions are running simultaneously, while
still making sure each instance is upgraded successfully and comes online before starting the next
upgrade.
• Wait to perform diagnostic checks and node install operations until after the rolling upgrade completes
to avoid timeouts or failure.
The following considerations apply when upgrading QueryGrid connectors from QueryGrid 2.04 and earlier
to QueryGrid 2.05 and later:

15: Upgrading QueryGrid
Connector
Description
Type
Teradata • Installation step is not required when upgrading from 02.04 and earlier versions.
• Proceed to run the connector installation step if it was not run on a previous version of
QueryGrid. Refer to Teradata Initiator Connector Tasks for more information.
Presto • Installation step is not required when upgrading from 02.04 and earlier versions on
Presto 189t.
• If installing or upgrading a Presto server to 189t, 195t, 203t, or 208t, complete the
connector installation steps through the connector install (using Viewpoint 16.20) or
QueryGrid Manager connector-install command line script (using Viewpoint 16.10).
Refer to Presto Initiator Connector Tasks for more information.
Hive • Installation step and target import and export of UDFs are not required as of QueryGrid
version 02.05.
• If the ADD JAR command is not allowed on Hive (for example, CDH with Sentry), the
Hive class path must be configured. Refer to Hive Target Connector Tasks for more
information.
Spark No installation steps required when upgrading from QueryGrid 02.04.
Oracle No installation steps required.
Upgrading Teradata QueryGrid Manager

Teradata QueryGrid Manager supports rolling zero-downtime upgrades.
Upgrade Teradata QueryGrid Manager when a new version becomes available. You must upgrade
Teradata QueryGrid Managers one at a time, and wait for each manager to come online before continuing
with the next upgrade.
1. Download the latest Teradata QueryGrid Manager software package.
2. Copy the package to the target system.
3. From a console window, run the following command to upgrade the manager:
rpm -Uvh tdqg-manager-version.rpm
After approximately 1 minute, open https://<hostname>:9443.
4. For access issues, review the log at /var/opt/teradata/tdqgm/logs.
Upgrading Teradata QueryGrid Node Software

Upgrade Teradata QueryGrid node software when a new version becomes available.
1. Download the latest software package and then upload the package to Teradata QueryGrid Manager.
2. In the QueryGrid portlet, select Systems.
3. Select the system on which you want to upgrade the node software, then from the Node software list,
select the new version of the node software.

4. Repeat the previous step for each system on which the prior version of the node software is deployed.
Upgrading Teradata QueryGrid Connectors and Fabrics

Upgrade each component individually from the QueryGrid portlet.
Note:
The install script should be re-run when Presto is upgraded, unless there are no QueryGrid changes
to incorporate.
1. Download the latest software packages and then upload the packages to Teradata QueryGrid
Manager.
2. Browse to the QueryGrid portlet view or tab for the component you are upgrading:
Component Type View > Tab
Connector Fabric > Connectors
Fabric Fabrics
3. Next to the component you want to upgrade, click , select Add Pending Version, then complete the
applicable procedure for adding the component.
Component Type Procedure
Connector Adding a Connector
Fabric Adding a Fabric
The component is available for testing on production deployments without affecting production
workloads.
Note:
Recommended areas of testing include QueryGrid diagnostics, bandwidth, and SQL.
4. To deploy the upgraded component in production, do the following:

a. Click next to the component, then click Activate.
b. In the confirmation dialog box, click Activate.
The status of the upgraded component changes to Current, and the status of the previously active
component changes to Previous.

Removing Old Software Versions from Teradata

QueryGrid Manager
Use the command line utility cleanup-software.sh to remove old software versions from Teradata
QueryGrid Manager. The utility cleans up fabric, node, and connector software that is unused for the
specified period of time.
The options for cleanup-software.sh are:
./cleanup-software.sh --help
usage: cleanup-software [-d <days>] [-h] [-m <host>] [-n]
Cleanup older software that is no longer being used.
options:
-d,--days <days> The number of days old the software should be
before considering it for removal. Defaults to 7.
-h,--help Print this message
-m,--manager <host> The hostname of the QueryGrid manager to connect
to. Defaults to localhost.
-n,--no-ssl Use HTTP instead of HTTPS to connect to the manager.
2. From /opt/teradata/tdqgm/bin, run: ./cleanup-software.sh
Note:
You must run this command as the root or tdqgm user.
Removing unused software older than 2016-08-25T10:26:41.356-0700.

Deleted tdqg-fabric-02.00.00.00_SNAPSHOT.tar.gz.
Deleted tdqg-presto-connector-02.00.00.00_SNAPSHOT.tar.gz.
Deleted tdqg-node-02.00.00.00_SNAPSHOT.tar.gz.
Deleted tdqg-teradata-connector-02.00.00.00_SNAPSHOT.tar.gz.
[…]

A
QueryGrid Portlet Metrics
Communication Policies Metrics

Metric Description
Name Name given to this communication policy
Description Description of this communication policy
Last Modified Creation date or the last time this communication policy was edited
Connector Diagnostic Check Metrics

Metric Description
Host Name Host name of the connector
Status Status of the connector:

• Success
• Failed
• Waiting
Start Time Time the diagnostic check started
End Time Time the diagnostic check ended
Error Message Text of the error message that was returned, if a problem was detected
Connector Software Metrics

Metric Description
Name Name of the connector software
Version Version of the connector software
Platform Platform that the connector software runs on
Package Date Date that the connector software package was built
Package Size Size of the connector software package

A: QueryGrid Portlet Metrics
Connectors Metrics
Metric Description
Name Name of this connector
Description Description that distinguishes this connector
Software Version of software that this connector runs
Enabled Whether this connector is enabled or disabled
System System that this connector runs in
Nodes Online Number of nodes on which the connector software is installed and both the node and fabric
are available
Nodes Offline Number of nodes on which the connector software is installed and not currently active
Drivers Online Number of nodes on which the connector is installed and the driver is running
Drivers Offline Number of nodes on which the connector driver is installed and not currently active but is
supposed to be active
Fabric Fabric that this connector runs in
Last Modified Creation date or the last time this connector was edited
Data Centers Metrics

Metric Description
Name Name given to this data center
Description Description of this data center
Fabric Software Metrics

Metric Description
Name Name of the fabric software
Version Version of the fabric software
Platform Platform that the fabric software runs on
Package Date Date that the fabric software package was built
Package Size Size of the fabric software package

Fabrics Metrics
Metric Description
Name Name given to this fabric
Description Description of this fabric
Port Port on which this fabric runs
Fabric Software Version of software that this fabric runs
Nodes Online Number of nodes that are online for the fabric
Nodes Offline Number of nodes that are supposed to be online for the fabric but are not
Last Modified Creation date, or the last time this fabric was edited
Issues History Metrics

Metric Description
ID Identification number assigned to the issue
Time Time the issue was created, updated, or resolved depending on the state
Issue Name of the issue
Severity Critical or Warning
Type Manager or System
Component Name of the affected component
State Specifies if the issue was created, updated, or deleted.
Issues Metrics
Metric Description
All Total number of issues
Critical Number of issues considered to be critical
Warning Number of warning-level issues
Issue Description of the issue
Severity Critical or Warning
Type Origin of the issue, either in a manager or a system
Component Name of the manager or system from which the issue originated

Metric Description
Time Time the issue occurred
Duration Length of time the issue lasted
Link Bandwidth Test Metrics

Metric Description
Host Name Host name of the link
Status Status of the link, either Success, Failed, or Waiting
Start Time Time the link bandwidth test started
End Time Time the link bandwidth test ended
Error Message Text of the error message that was returned, if a problem was detected
Links Metrics
Metric Description
Name Name of this link
Description Description that distinguishes this link
Initiating Connector Connector that initiates and sends a query to a target system
Initiating System System on which a query originates
Target Connector Connector that receives and processes a query from the initiating system or
accepts data from the initiating system, and may return results to the initiating
system
Target System System on which a query executes
Communication Policy Communication policy that this link uses
Fabric Fabric that this link runs in
Last Modified Creation date or the last time this connector was edited
Managers Metrics
Metric Description
Host Name Name given to this manager

Metric Description
Status Online or Offline
Version Software release that runs on this manager
Data Center Data center where this manager is located
Public Address Public-facing host name or IP address that is used to communicate with this manager
Cluster Address The IP address that other Teradata QueryGrid Managers in the cluster use to access a
specific QueryGrid Manager.
Bind Address A locally bound IP address to which Teradata QueryGrid Manager internal services bind.
Last Heartbeat Last time this manager sent a heartbeat
Free Space Amount of free disk space available on the manager.
Disk Usage % Percentage of the disk used by this manager
Networks Metrics
Metric Description
Name Name given to the network
Description Description of this network
Last Modified Creation time or last time this network was edited
Node Details Metrics

Node Details
Metric Description
Node Name Name given to this node
Platform Platform that this node runs on
Node Software Version of software that this node runs
Last Heartbeat Last time this node sent a heartbeat
Status Whether this node is currently online or offline

Network Interfaces
Metric Description
Interface Name Name of a network interface that this node is a part of
Address Address of the network interface
Fabrics
Metric Description
Fabric Name Name of a fabric that this node is a part of
Fabric Software Version of software that runs on the fabric
Process ID Identification number given to the fabric process
Status Whether the fabric is currently online or offline
Drivername Name of the driver
Status Whether the driver in the fabric is currently online or offline
Process ID Identification number of the driver process in this fabric
Connectors
Metric Description
Connector Name Name of a connector that this node is a part of
Connector Software Version of software that runs on the connector
Status Whether the connector is currently online or offline
Fabric Name Name of the fabric that the connector is part of
Node Installation Status Metrics

Metric Description
All Total number of nodes
Success You can filter to see the number of nodes in the following states:
• Success: Number of node installations that have succeeded
• Failed: Number of node installations that have failed
• Installing: Number of nodes that are currently installing
• Pending: Number of nodes that are currently pending
• Aborted: Number of node installations that have aborted

Metric Description
Host Name Host name of the node
Status Status is: Success, Failed, Installing, Pending, or Aborted
Start Time Time that installation of the node started
End Time Time that installation of the node ended
Error Message Error message that resulted from installation, if any
Node Software Metrics

Metric Description
Name Name of the node software package
Version Version of the node software package
Platform Platform that the of the node software package runs on
Package Date Date when the package was built
Package Size Size of the software package
Node Status Metrics

Metric Description
All Total number of nodes in the fabric
Online Number of nodes that are currently active
Offline Number of nodes that are currently not active
Host Name Host name of the device that is the node
Status Whether the node is currently online or offline
System System in which the node runs
Roles Metrics
Metric Description
Initiating Role Name of the role on the system where the query originates
Target Role Name of the role on the system where the query is targeted

Service Account Metrics

Metric Description
User Name Name given to the service account
Description Description of the service account
System Metrics
Metric Description
Name Name of the system
Description Description of the system
Data Center Data center that the system is a part of
Node Software Version of node software that the nodes in the system run
Nodes Online Number of nodes that are currently active on the system
Nodes Offline Number of nodes that are not currently active on the system
System Nodes Metrics

Metric Description
Host Name Host name of the node
Status Whether the node is online or offline
Platform Platform on which the node runs
Node Software Version of node software that the node runs
Last Heartbeat Last time the node sent a heartbeat
User and Role Mappings Metrics

Metric Description
Group Name Name of the mapping group that the user or role belongs to
Description Description of the mapping group
Mapping Count Number of mapping relationships created for this mapping group
Last Modified Time that the mapping group was last changed

Users Metrics
Metric Description
Initiating User Name of the user on the system where the query originates
Target User Name of the user on the system where the query is targeted

B
QueryGrid Portlet Table and Row Actions
Table Actions
The following table lists the QueryGrid portlet table actions, the components from which each action is
available, and the description for each action.
Action Component Description
Clear Filters Communication Policies Remove any content in the filter boxes
Connector Software Tab
Fabrics
Issues
Networks
Systems
Configure Communication Policies Choose the columns to display and set thresholds
Columns Connector Software Tab
Data Centers
Fabric Software Tab
Fabrics
Issues
Managers Tab
Networks
Node Software Tab
Systems
User Mappings
Export Communication Policies Create a .csv file containing all available data up to one
Connector Software Tab million rows
Data Centers If more than one million rows of data are available, then use
Fabric Software Tab the filters to display the data you want before exporting it
Fabrics
Issues
Managers Tab
Networks
Node Software Tab
Systems
User Mappings

B: QueryGrid Portlet Table and Row Actions
Row Actions
The following table lists the QueryGrid portlet row actions, the components from which each action is
available, and the description for each action.
Activate Communication Policies Change a pending or previous version of a component to

Networks the current (active) version
Connectors Change a pending or previous version of a component to

the current (active) version
The previous connector, if any, is deleted, and the version
of this connector that was current becomes the previous
version of this connector
Fabrics Change a pending or previous version of a component to

the current (active) version
The previous fabric, if any, is deleted, and the version of this
fabric that was current becomes the previous version of
this fabric
Add Pending Communication Policies Create a pending version of the selected component that
Version Connectors you can edit and test
Fabrics
Links
Networks
Bandwidth Test Links Run a bandwidth check on a selected link
Delete Connector software Delete a selected component

Connectors
Data Centers
Fabric software
Fabrics
Issues
Links
Networks
Node software
Nodes
Service Accounts
Systems
User Mappings
Communication Policies Delete a selected version

Deleting a current (active) version also deletes any pending
or previous versions
Teradata QueryGrid Delete a Teradata QueryGrid Manager with a status of

Manager offline
Diagnostic Connectors Run a diagnostic check on a selected component

Check

B: QueryGrid Portlet Table and Row Actions
Links
Disable/Enable Connectors Disable or enable a connector
Edit Communication Policies Change all configuration for the current (active) version
If a pending version, you cannot change the name or
description
Connectors Modify the current (active) or pending version of the

selected connector
Data Centers Modify the name and description of a data center
Fabrics Change the name and description of a current fabric version

Note:
If you need to change the port or software version that is
used in a fabric, create a pending version and wait for all
nodes to come online in order to test and then activate.
Links Modify the current (active) or pending version of the

selected link
Networks Change all configuration for a current (active) version

If a pending version, you cannot change the name or
description
Service Accounts Edit the password and description for a service account
Systems Change the system configuration
User Mappings Modify the name and description for a user mapping
View Communication Policies View the details of a previous component version

Connectors
Fabrics
Networks
Links View the properties of a link
View Driver Connectors View the status of the drivers on the selected connector
Status
View Node Nodes View the network interfaces, fabrics, and connectors this
Details node is associated with
View Node Connectors View the status of the nodes for a selected connector
Status
Fabrics View the status of the nodes associated with a fabric

C
Notation Conventions
About Notation Conventions

This section describes the notation conventions used in this book.
Convention Description
Syntax Diagrams Describes SQL syntax form, including options.
Square braces in Represent options. The indicated parentheses are required when you specify options.
the text For example:
DECIMAL [(n[,m])] means the decimal data type can be defined
optionally:
• without specifying the precision value n or scale value m
• specifying precision (n) only
• specifying both values (n,m)
You cannot specify scale without first defining precision.
• CHARACTER [(n)] means that use of (n) is optional.
The values for n and m are integers in all cases.
Syntax Diagram Conventions

Notation Conventions
Item Definition and Comments
Letter An uppercase or lowercase alphabetic character ranging from A through Z.
Number A digit ranging from 0 through 9.

Do not use commas when typing a number with more than 3 digits.
Word Keywords and variables.

• UPPERCASE LETTERS represent a keyword.
Syntax diagrams show all keywords in uppercase, unless operating system restrictions
require them to be in lowercase.
• lowercase letters represent a keyword that you must type in lowercase, such as a Linux
command.
• Mixed Case letters represent exceptions to uppercase and lowercase rules. The exceptions
are noted in the syntax explanation.
• lowercase italic letters represent a variable such as a column or table name.
Substitute the variable with a proper value.
• lowercase bold letters represent an excerpt from the diagram.
The excerpt is defined immediately following the diagram that contains it.

C: Notation Conventions
Item Definition and Comments
• UNDERLINED LETTERS represent the default value.

This applies to both uppercase and lowercase words.
Spaces Use one space between items such as keywords or variables.
Punctuation Type all punctuation exactly as it appears in the diagram.
Paths
The main path along the syntax diagram begins at the left with a keyword, and proceeds, left to right, to the
vertical bar, which marks the end of the diagram. Paths that do not have an arrow or a vertical bar only
show portions of the syntax.
The only part of a path that reads from right to left is a loop.
Continuation Links
Paths that are too long for one line use continuation links. Continuation links are circled letters indicating
the beginning and end of a link:
When you see a circled letter in a syntax diagram, go to the corresponding circled letter and continue
reading.
Required Entries
Required entries appear on the main path:
If you can choose from more than one entry, the choices appear vertically, in a stack. The first entry appears
on the main path:
Optional Entries
You may choose to include or disregard optional entries. Optional entries appear below the main path:

If you can optionally choose from more than one entry, all the choices appear below the main path:
Some commands and statements treat one of the optional choices as a default value. This value is
UNDERLINED. It is presumed to be selected if you type the command or statement without specifying one
of the options.
Strings
String literals appear in apostrophes:
Abbreviations
If a keyword or a reserved word has a valid abbreviation, the unabbreviated form always appears on the
main path. The shortest valid abbreviation appears beneath.
In the above syntax, the following formats are valid:

SHOW CONTROLS
SHOW CONTROL
Loops
A loop is an entry or a group of entries that you can repeat one or more times. Syntax diagrams show loops
as a return path above the main path, over the item or items that you can repeat:
Read loops from right to left.

The following conventions apply to loops:

Item Description Example
maximum number The number appears in a circle on the return In the example, you may type cname
of entries allowed path. a maximum of four times.
minimum number The number appears in a square on the In the example, you must type at least
of entries allowed return path. three groups of column names.
separator The character appears on the return path. In the example, the separator
character required If the diagram does not show a separator character is a comma.
between entries character, use one blank space.
delimiter character The beginning and end characters appear In the example, the delimiter
required around outside the return path. characters are the left and right
entries Generally, a space is not needed between parentheses.
delimiter characters and entries.
Excerpts
Sometimes a piece of a syntax phrase is too large to fit into the diagram. Such a phrase is indicated by a
break in the path, marked by (|) terminators on each side of the break. The name for the excerpted piece
appears between the terminators in boldface type.
The boldface excerpt name and the excerpted phrase appears immediately after the main diagram. The
excerpted phrase starts and ends with a plain horizontal line:
Multiple Legitimate Phrases

In a syntax diagram, it is possible for any number of phrases to be legitimate:
In this example, any of the following phrases are legitimate:

dbname
DATABASE dbname
tname
TABLE tname
vname
VIEW vname
Sample Syntax Diagram

D
Additional Information
Audience
This guide is intended for technical personnel who use Teradata QueryGrid:
• System administrators
• Database administrators
• Hadoop administrators
• Users
• Teradata Customer Support
Changes and Additions

Date Release Description
February 2019 2.07.00.02 • Added HDP 3.0.1 support.

• Added non-root support for QueryGrid Manager commands using tdqgm
user.
• Updated Remote Table Optimization information.
November 2018 2.07 Initial release.
Teradata Links
Link Description
https://docs.teradata.com/ Teradata documentation (HTML)
http://www.info.teradata.com Teradata documentation (PDF)
https://access.teradata.com One stop source for Teradata community, product

information, and software downloads.
Log in for customer access to:
• Support
• Software updates
• Knowledge articles
• Orange Books
http://www.teradata.com/products-and-services Teradata education network

/TEN

D: Additional Information
Link Description
https://community.teradata.com Link to Teradata community (also available from the

customer portal)
Related Documentation
Title Publication ID
Teradata® Viewpoint Installation, Configuration, and Upgrade Guide for Customers B035-2207
Describes how to install Viewpoint software, configure settings, and upgrade a Teradata
Viewpoint server.
Teradata® Viewpoint User Guide B035-2206

Describes the Teradata Viewpoint portal, portlets, and system administration features.

QueryGrid Installation

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

QueryGrid Installation

Caricato da

Copyright:

Formati disponibili

Teradata® QueryGrid™

Installation and User Guide

Safety type Description

Chapter 1: Teradata QueryGrid Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Part I: Preparing for Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2: Preparing for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Part II: Installing and Configuring Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3: Installing and Configuring Teradata QueryGrid Manager . . . . . . . . . . . . . . . . . . . . . 26

Chapter 4: Setting Up Teradata QueryGrid in the Viewpoint Administration Portlets . . . . . . . . 31

Chapter 5: Configuring Teradata QueryGrid in the QueryGrid Portlet . . . . . . . . . . . . . . . . . . . . . 33

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 3

Add Data Source Nodes to a System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Part III: Configuring and Using Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter 6: Using the Teradata Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 7: Using the Presto Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . . 124

Chapter 8: Using the Hive Connector with Teradata QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . 146

Part IV: Managing QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Chapter 11: Modifying an Existing QueryGrid Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 4

Editing a Data Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Chapter 13: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Chapter 14: Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

Part V: Upgrading Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Chapter 15: Upgrading QueryGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Appendix A: QueryGrid Portlet Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Appendix B: QueryGrid Portlet Table and Row Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Appendix C: Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Appendix D: Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 5

Teradata QueryGrid Description

Teradata QueryGrid Components

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 6

Teradata QueryGrid Manager

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 7

System (Data Source)

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 8

• If there are no bridges, there is one hop.

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 9

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 10

• Specifies whether bridges are used:

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 11

Active, Pending, and Previous Teradata QueryGrid

Previous A previous configuration in the production environment.

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 12

Teradata QueryGrid Security

QueryGrid Manager Service Accounts

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 13

Authentication and Registration of Data Source Nodes

IP Addresses and Hostname Verification

Communication Policies for Data Transfer within a Fabric

IP-based authentication, no integrity Default that specifies a minimum level of security. It is

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 14

Security Level Usage

algorithms are available: AES-CRC32, AES-GCM (default), AES-

Data Source User

Teradata Database teradata user

Presto presto user

LDAP and Kerberos

General Security Guidelines for Teradata QueryGrid

Teradata QueryGrid 1.0x and 2.0x Connectors

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 15

Teradata QueryGrid in the Teradata Public Cloud

• Teradata® Software for AWS Installation and Administration Guide, B035-2800

Teradata® QueryGrid™ Installation and User Guide, Release 2.07 16