Use the td_create_context() function to establish a connection to Vantage. The established connection will be set as the current context for all subsequent analytic functions.
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 (that is, the default schema) are the same for both the new connection object and the connection object from the previous context.
Optional arguments:
- dsn: 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. Only applicable when the argument dType is 'ODBC'.
- host: Specifies the fully qualified domain name or IP address of the Teradata Vantage System.Required when the argument dType is 'NATIVE'.
- uid: Specifies the username for logging onto Vantage.
- pwd: Specifies the password. If not specified, the password present in DSN is used.Encrypted passwords can also be passed to this argument, using Stored Password Protection feature. Examples 3 section 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 in the "Stored Password Protection" section at https://github.com/Teradata/r-driver
- tdWalletString: Specifies the tdwallet reference string for the password required for the connection. If this is specified, the argument pwd is ignored. Only applicable when the argument dType is 'ODBC'.
- database: Specifies the database name to which connection is needed. If not supplied and if
- dType is 'ODBC', the database name present in the DSN is used.
- dType is 'native', then the database name associated with the user-specified in the argument "uid" is used.
- temp.database: Some of the functions need to create temporary database objects (table or view) to process 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 the function td_get_context.
- dtype: Specifies the driver type: 'ODBC' or 'NATIVE'.
- logmech: Specifies the type of logon mechanism to establish a connection to Vantage.
- Only applicable when dType is 'NATIVE'. Ignored when used with 'ODBC'.
- If the value is NULL, it takes the default value used by the Teradata SQL driver.
See the Logon Mechanisms section for details about possible logmech values and usage examples.
- logdata: Specifies additional data for the chosen logon authentication method.
- Only applicable when dType is 'NATIVE'. Ignored when used with 'ODBC'.
- If logmech is 'JWT', then JWT token should be provided with the key 'jwt.token' in the named list of this argument.
- 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.
- ...: 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.
temp.database and database arguments
In case you do not have permissions to create tables or views in your own database, but are allowed to create the required objects in other common database, you must use the argument temp.database to pass the name of the other database where you are allowed to create the database objects such as tables and views. If this argument is not provided, intermediate database objects are created in your default database.
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 Behavior | ||
|---|---|---|---|
| temp.database is provided | database is 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 |
Logon Mechanisms
There are five logon mechanisms available to connect to Vantage.
- TD2: The Teradata 2 (TD2) mechanism provides authentication using a database username and password. This is the default logon mechanism.
td_create_context(host = <host-name>, uid=<username>, pwd=<password>, dType = "native", logmech = "TD2")
- 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 = <host-name>, uid=<username>, pwd=<password>, dType = "native", logmech = "TDNEGO")
- LDAP: LDAP is a directory-based mechanism. User logs on to a database with a directory username and password and is authenticated by the directory.
td_create_context(host = <host-name>, uid=<username>, pwd=<password>, dType = "native", logmech = "LDAP")
- KRB5: KRB5 is a directory-based mechanism. User logs on to a database with a domain username and password and is authenticated by Kerberos (KRB5 or SPNEGO mechanism).
td_create_context(host = <host-name>, uid=<username>, pwd=<password>, dType = "native", logmech = "KRB5")
- JWT : Using JWT token to connect to Vantage. The connection will be active till the expiry of JWT token.
td_create_context(host = <host-name>, dType = "native", logmech = "JWT", logdata = list(jwt.token=<token_value>))
In addition to these five logon mechanisms listed, connection to Vantage can be established using Stored Password Protection feature. See the td_create_context() function in Teradata Package for R Function Reference for more information.
To use non-default logon mechanisms (TDNEGO, LDAP, KRB5 and JWT), you must set up the clients with appropriate security mechanisms.
Example 1: Establish a connection to the database with additional connection parameters
con <- td_create_context(host = <host-name>, uid=<username>, pwd=<password>, dType = "native", log = 1, tmode = 'ansi', lob_support = FALSE)
Example 2: Create context with the 'database' parameter
con <- td_create_context(host = <host-name>, uid=<username>, pwd=<password>, database=<databasename>, dType = "native", log = 1, tmode = 'ansi', lob_support = FALSE)
Example 3: Create context using encrypted password and key passed to the 'pwd' parameter
Specify the password in the following format:
ENCRYPTED_PASSWORD(file:<PasswordEncryptionKeyFileName>, file:<EncryptedPasswordFileName>)
- PasswordEncryptionKeyFileName specifies the name of a file that contains the password encryption key and associated information.
- EncryptedPasswordFileName specifies the name of a file that contains the encrypted password and associated information.
- Each filename must be preceded by the 'file:' prefix.
- PasswordEncryptionKeyFileName and EncryptedPasswordFileName must be separated by a single comma.
td_create_context(host = "<dbcname>", uid = "<tduser>", pwd = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)", dType = "NATIVE")