Teradata R Package Function Reference | 17.00 - 17.00 - td_create_context - Teradata R Package

Teradata® R Package Function Reference

prodname
Teradata R Package
vrm_release
17.00
created_date
September 2020
category
Programming Reference
featnum
B700-4007-090K

Description

Use the td_create_context function to establish a connection to Teradata Vantage. The established connection will be set as the current context for all subsequent analytic functions.
Note: If a context already exists, this overwrites the previous context and removes all nonpersistent work tables created by the analytic functions, even though the connection parameters host, uid and database (i.e. default schema) are same for both the new connection object and the connection object from the previous context.

Usage

td_create_context(
  dsn = NULL,
  host = NULL,
  uid = NULL,
  pwd = NULL,
  tdWalletString = NULL,
  database = NULL,
  temp.database = NULL,
  dType = "odbc",
  logmech = NULL,
  logdata = NULL,
  ...
)

Arguments

dsn

Optional argument.
Specifies the Data Source Name (DSN) for the ODBC connection. If this argument is not specified, relevant optional arguments are used to form the connection string.
Note : Only applicable when the argument "dType" is 'ODBC'
Default Value: NULL
Types: character

host

Optional argument. Required when "dType" is 'NATIVE'.
Specifies the fully qualified domain name or IP address of the Teradata Vantage System.
Default Value: NULL
Types: character

uid

Optional argument.
Specifies the userId for connection. If not supplied, the userId present in DSN is used.
Default Value: NULL
Types: character

pwd

Optional argument.
Specifies the password. If not supplied, the password present in DSN is used.
Default Value: NULL
Types: character
Note: Encrypted passwords can also be passed to this argument, using Stored Password Protection feature. Examples section below demonstrates passing encrypted password to "td_create_context". More details on Stored Password Protection and how to generate key and encrypted password file can be found at StoredPasswordProtection

tdWalletString

Optional argument.
Specifies the tdwallet reference string for the password required for the connection. If this is specified, the argument 'pwd' is ignored.
Note : Only applicable when the argument "dType" is 'ODBC'
Default Value: NULL
Types: character

database

Optional argument.
Specifies the database name to which connection is needed. If not supplied, the database name present in the DSN is used.
Note : Only applicable when the argument "dType" is 'ODBC'
Default Value: NULL
Types: character

temp.database

Optional argument.
Some of the functions need to create temporary database objects(table/view) for processing data. Such objects are garbage collected at the end of the session. If a user wants to specifically use a known database for temporary objects, the database name can be specified using this argument. Make sure the user has privilege to create objects in this database, otherwise the functions that create temporary objects will fail.
If this argument is not supplied, default database of the connection is used for temporary objects. To get the temporary database name, use function td_get_context().
Default Value: NULL
Types: character

dType

Required argument.
Specifies the driver type.
Permitted Values: ODBC, NATIVE
Default Value: ODBC
Types: character

logmech

Optional argument.
Specifies the logon authentication method. Only applicable when "dType" is 'NATIVE'. Ignored when used with 'ODBC'.
If the value is NULL, it takes default value used by the Teradata SQL driver.
Permitted Values: TD2, LDAP, TDNEGO, KRB5 (for Kerberos) and JWT
Default Value: NULL
Types: character

logdata

Optional argument.
Specifies additional data for the chosen logon authentication method. Only applicable when 'dType' is "NATIVE". Ignored when used with "ODBC".
Note: If "logmech" is "JWT", then JWT token should be provided with the key 'jwt.token' in the named list of this argument.
Default Value: NULL
Types: Named list of characters

...

Optional arguments as applicable to the corresponding driver.

Details

You should make sure that Teradata driver is properly installed and configured on the system where this function is being invoked.
When logmech argument (other than TD2 which is the current default logon mechanism) is used, you should setup the client with relevant security mechanisms.

Note:

  1. tdplyr requires that the user has certain permissions on the user's default database or the initial default database specified using the "database" argument, or the temporary database when specified using "temp.database".
    These permissions allow the user to:

    1. Create tables to save results of Vantage analytic functions.

    2. 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 that will be used.
    For views based on Vantage Analytic Functions, additional permissions may be required, which can be granted using:
    GRANT EXECUTE FUNCTION ON SYSLIB ... WITH GRANT OPTION.
    The access to the views created may also require issuing additional permissions 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.

  2. The "temp.database" and "database" parameters help determine which database is used by default to lookup for tables/views while creating objects of class "tbl_teradata" and which database is used to create all internal temporary objects, as shown in the table below.

    Scenario tdplyr behaviour
    1. Both "database" and Internal temporary objects are created in
    "temp.database" are provided "temp.database", and database table/view lookup
    is done from "database".
    2. "database" is provided Database table/view lookup and internal
    but "temp.database" is not temporary objects are created in "database".
    3. "temp.database" is provided Internal temporary objects are created in
    but "database" is not "temp.database", database table/view lookup
    from the users default database.
    4. Neither "database" nor Database table/view lookup and internal
    "temp.database" are provided temporary objects are created in users
    default database.

Value

Invisibly returns an object of class: DBIConnection.

See Also

td_remove_context, td_set_context, td_get_context, dbConnect

Examples

# Note: The default database in the connection is used as the temporary
# database. For retrieving and removing context, check td_get_context
# and td_remove_context respectively.

# Create a context (ODBC connection) specifying a dsn name.
con <- td_create_context(dsn = "TeradataDSN")

# Example 1: Create a context (ODBC connection) with a different temporary database.
td_create_context(dsn = "TeradataDSN", temp.database = "database_for_transient_objects")

# Example 2: Create a context (ODBC connection) using TdWallet.
td_create_context(dsn = "TeradataDSN", tdWalletString = "password_tduser")

# Example 3: Create a context using the Teradata SQL Driver. Note that the argument 'logmech' is
# not specified. Connection is established with default logon mechanism.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE")

# Example 4: Create a context using the Teradata SQL Driver with various logon mechanisms.

# Connection using TD2: The Teradata 2(TD2) mechanism provides authentication using a Vantage
# database username and password.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE",
                  logmech = "TD2")

# Connection using TDNEGO: TDNEGO is a security mechanism that automatically determines the
# actual mechanism required, based on policy, without user's involvement. The actual mechanism
# is determined by the TDGSS server configuration and the security policy's mechanism
# restrictions.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE",
                  logmech = "TDNEGO")

# Connection using LDAP: LDAP is a directory-based mechanism. User logs on to a Vantage database
# with a directory username and password and is authenticated by the directory.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "<tdpwd>", dType = "NATIVE",
                  logmech = "LDAP")

# Connection using KRB5: KRB5 is a directory-based mechanism. User logs on to a Vantage database
# with a domain username and password and is authenticated by Kerberos (KRB5 or SPNEGO
# mechanism).
td_create_context(host = "<dbcname>", uid = "<tduser>", dType = "NATIVE", logmech = "KRB5")

# Connection using JWT: Using JWT token to connect to Vantage.
td_create_context(host = "<dbcname>", dType = "NATIVE", logmech = "JWT",
                  logdata = list(jwt.token="<token_value>"))

# Example 5: Create context using encrypted password and key passed to "pwd" parameter.
# The password should be specified in the format mentioned below:
# ENCRYPTED_PASSWORD(file:<PasswordEncryptionKeyFileName>, file:<EncryptedPasswordFileName>)
# The PasswordEncryptionKeyFileName specifies the name of a file that contains the password
# encryption key and associated information.
# The EncryptedPasswordFileName specifies the name of a file that contains the encrypted password
# and associated information.
# Each filename must be preceded by the 'file:' prefix. The PasswordEncryptionKeyFileName must be
# separated from the EncryptedPasswordFileName by a single comma.
td_create_context(host = "<dbcname>", uid = "<tduser>",
                  pwd = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)",
                  dType = "NATIVE")

# Example 6: Create context using encrypted password in LDAP logon mechanism.
td_create_context(host = "<dbcname>", uid = "<tduser>",
                  pwd = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)",
                  dType = "NATIVE", logmech = "LDAP")