dbConnect-NativeDriver-method | Teradata Package for R - dbConnect-NativeDriver-method - Teradata Package for R

Teradata® Package for R User Guide

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Teradata Package for R
Release Number
17.20
Published
March 2024
Language
English (United States)
Last Update
2024-04-09
dita:mapPath
efv1707506846369.ditamap
dita:ditavalPath
ayr1485454803741.ditaval
dita:id
nqx1518630623256
Product Category
Teradata Vantage

Use the dbConnect(tdplyr::NativeDriver(), ...) function to establish a connection to Vantage using the Teradata SQL Driver for R (also called the native driver for R) and initialize a context.

  • If there is no previous context, then a new context is initialized.
  • If the context already exists:
    • If the connection parameters "host", "uid" and "database" (that is, the default schema) of the new connection object are different from those of the connection object from the previous context, then the previous context is overwritten and all non-persistent work tables are removed.
    • If the connection parameters are the same for both the new connection object and the connection object from the previous context, then the previous context is not overwritten and all non-persistent work tables remain in the session.
Arguments:
  • drv: Specifies a NativeDriver object obtained from tdplyr::NativeDriver().
  • host: Specifies the fully qualified domain name or IP address of the Vantage system.
  • uid: Specifies the username to connect with Vantage.
  • pwd: Specifies the password for the connecting user.
  • temp.database: Specifies the database name in which temporary database object (table or view) is created for processing data. Such objects are garbage collected at the end of the session.

    If this argument is not supplied, default database of the connection is used for temporary objects. To get the temporary database name, use the function td_get_context.

    Make sure the user has privilege to create objects in this database, otherwise the functions that create temporary objects fail.
  • database: Specifies the database name to which connection is needed.
  • log: Specifies the controls for debug logging.
    The 1-bit governs function and method tracing, the 2-bit governs debug logging, the 4-bit governs transmit and receive message hex dumps, and the 8-bit governs timing.
    Examples:
    • If the user wants only debug logging, 2 (in bit representation: 0010) should be used as the argument value.
    • If the user wants timing and debug logging, 10 (in bit representation: 1010) should be used as an argument value.
  • ...: Optional argument specifies the additional connection parameters that are passed to Teradata SQL Driver for R. See the Connection Parameters section of https://github.com/Teradata/r-driver for details of connection parameters of the driver.
    When the type of a connection parameter is integer or boolean (for example: log, lob_support, and so on), pass integer or boolean value, instead of quoted integer or quoted boolean as suggested in the documentation.
tdplyr requires that the user has certain permissions on the user's default database or the initial default database specified using database, or the temporary database specified using temp.database.

These permissions allow the user to:

  • Create tables to save results of Vantage Analytic Functions;
  • Create views in the background for objects of class "tbl_teradata" based on query.

It is expected that the user has the required permissions to create these objects in the database to be used.

For views based on Vantage Analytic Functions, additional permissions may be required, which can be granted using:
GRANT EXECUTE FUNCTION ON VAL ... WITH GRANT OPTION

The access to the views created may also require issuing additional permission depending on which database is used and which object the view being created is based on, which can be granted using:

GRANT SELECT ... WITH GRANT OPTION
The temp.database and database arguments help determine which database is used by default to lookup for tables and views while creating objects of class "tbl_teradata" and which database is used to create all internal temporary objects, as shown in the following table.
Scenario tdplyr behaviors
temp.database provided? database provided? Internal temporary objects are created in Database object (table or view) lookup is done from
Yes Yes temp.database database
No Yes database database
Yes No temp.database User's default database
No No User's default database User's default database

Example 1: Establish a connection using the dbConnect API and NativeDriver object

This example establishes a connection to Vantage using the dbConnect API and NativeDriver object.

This will initialize the context based on the connection parameters, if the context does not exist.

con <- DBI::dbConnect(tdplyr::NativeDriver(), host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>")

Example 2: Establish a connection using the dbConnect API and teradatasql TeradataDriver object

This example establishes a connection to Vantage using the dbConnect API and teradatasql TeradataDriver object.

This will not initialize the context. Running the td_get_context() function returns NULL if there is no previous context. Users need to use td_set_context function to initialize the context on the TeradataDriver object.

con <- DBI::dbConnect(teradatasql::TeradataDriver(),'{"host":"<dbcname>","user":"<tduser>","password":"<tdpwd>"}')