create_context | Teradata Package for Python - create_context - Teradata Package for Python

Use the create_context() function to create a connection to the Vantage using the teradatasql + teradatasqlalchemy DBAPI and dialect combination.

Alternatively, you can pass a SQLAlchemy engine to the tdsqlengine parameter to override the default DBAPI and dialect combination.

The information in this topic provides details to establish connection from config file or through environment variables.

Optional Arguments

host

Specifies the fully qualified domain name or IP address of the Vantage system.

Types: str

username

Specifies the username for logging on to Vantage.

Types: str

password

Specifies the password for logging on to Vantage.

Types: str

tdsqlengine

Vantage sql-alchemy engine object that should be used to establish a Vantage connection.

Types: str

temp_database_name

Specifies the temporary database name where temporary tables or views will be created.

Types: str

logmech

Specifies the type of logon mechanism to establish a Vantage connection.

Permitted Values: 'TD2', 'TDNEGO', 'LDAP', 'KRB5' & 'JWT'.

• TD2: The Teradata 2 (TD2) mechanism provides authentication using a Vantage username and password. This is the default logon mechanism using which the connection is established to Vantage.
• TDNEGO: 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 by the security policy's mechanism restrictions.
• LDAP: A directory-based user logon to Vantage with a directory username and password and is authenticated by the directory.
• KRB5 (Kerberos): A directory-based user logon to Vantage with a domain username and password and is authenticated by Kerberos (KRB5 mechanism).
• JWT: The JSON Web Token (JWT) authenticates mechanism enables Single sign-on to the Vantage after the user successfully authenticates to Teradata UDA user service.

Types: str

logdata

Specifies parameter to the LOGMECH command beyond those needed by the logon mechanism, such as user ID, password, and tokens (in case of JWT) to successfully authenticate the user.

Types: str

database

Specifies the initial database to use after logon instead of the user's default database.

Types: str

config_file

Specifies the name of the configuration file to read the connection parameters.

• If you do not specify full path of file, then file lookup is done at the current working directory.
• The content of the file must be in '.env' format.
• Use parameters of create_context() as key in the configuration file.

For more information, refer to the following topics:

• Create connection using config file
• Create a connection using environment variables
• Order of preference between config file, environment variables and arguments of create_context

Default value: td_properties.cfg

Types: str

Setting Tables or Views Permissions

If 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_name to pass the name of the other database where temporary tables and views will be created. If this argument is not provided, intermediate database objects are created in your default database.

The temp_database_name and database arguments play a crucial role in determining which database is used by default to lookup for tables and views while creating teradataml DataFrame using 'DataFrame()' and 'DataFrame.from_table()' and which database is used to create all internal temporary objects.

set_config_params() can be used to set temp_table_name and temp_view_name. See temp_table_database and temp_view_database.

When configure.temp_object_type option is set to VT, then instead of temporary views, teradataml creates volatile tables in the user’s database. Hence, temp_database_name and database arguments will be ignored.

teradataml requires that you have certain permissions on the user's default database or the initial default database specified using database, or the temporary database specified using temp_database_name.

Verify you have the correct permissions to create these objects in the database to be used.

The access to the views created may also require issuing additional GRANT SELECT ... WITH GRANT OPTION permission depending on which database is used and which object the view being created is based on.

Passwords

Passwords passed as part of either password or logdata argument can be in encrypted format using Stored Password Protection.

The following examples section demonstrates passing encrypted password to the password argument.

For more information on Stored Password Protection and how to generate key and encrypted password file used in examples, see the Stored Password Protection section under the teradatasql project, on https://pypi.org/user/teradata/.

Special characters that may be used in the password are encoded by default.

Usage Considerations

• When overwriting an existing context associated with a Vantage connection, most of the operations on any teradataml DataFrames created before will not work.
• Teradata recommends calling remove_context() to end a session, so that intermediate views and tables created by teradataml are garbage collected.
• Executing create_context() triggers garbage collection in teradataml.

  See Garbage Collection in teradataml for more details.

• teradataml expects the client environments are already set up with appropriate security mechanisms and are in working conditions.

  For more information, refer to Teradata Vantage™ - Analytics Database Security Administration.

Example 1: Create a context using hostname, username and password

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword')

Example 2: Create a context using already created sqlalchemy engine

>>> from sqlalchemy import create_engine
>>> sqlalchemy_engine  = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost

>>> from teradataml.context.context import *
>>> create_context(tdsqlengine = sqlalchemy_engine)

Example 3: Create a context with default logmech 'TD2'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TD2')

Example 4: Create a context with default logmech 'TDNEGO'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='TDNEGO')

Example 5: Create a context with default logmech 'LDAP'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP')

Example 6: Create a context with default logmech 'KRB5'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', logmech='KRB5')

Example 7: Create a context with default logmech 'JWT'

>>> from teradataml.context.context import *
>>> create_context(host = 'tdhost', logmech='JWT', logdata='token=eyJpc...h8dA')

Example 8: Create a context using encrypted password and key passed to the 'password' argument

ENCRYPTED_PASSWORD(file:PasswordEncryptionKeyFileName, file:EncryptedPasswordFileName)

>>> td_context = create_context(host = 'tdhost', username='tduser', password = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)")

Example 9: Create a context using encrypted password in LDAP logon mechanism

>>> td_context = create_context(host = 'tdhost', username='tduser', password = "ENCRYPTED_PASSWORD(file:PassKey.properties, file:EncPass.properties)", logmech='LDAP')

Example 10: Create a context to connect to a different initial database, using hostname, username and password

This example creates a context using hostname, username and password, and connect to a different initial database by setting the database argument.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', database = 'database_name')

Example 11: Creates a context to connect to a different initial database, using already created sqlalchemy engine

This example creates a context using already created sqlalchemy engine, and connect to a different initial database by setting the database argument.

>>> from sqlalchemy import create_engine
>>> sqlalchemy_engine  = create_engine('teradatasql://'+ tduser +':' + tdpassword + '@'+tdhost + '/?DATABASE=database_name')
>>> create_context(tdsqlengine = sqlalchemy_engine)

Example 12: Create a context to connect to a different initial database, using 'LDAP' logmech

This example creates a context with 'LDAP' logmech, and connect to a different initial database by setting the database argument.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', logmech='LDAP', database = 'database_name')

Example 13: Create a context using 'tera' mode

This example creates a context using 'tera' mode with log value set to 8 and lob_support disabled.

>>> td_context = create_context(host = 'tdhost', username='tduser', password = 'tdpassword', tmode = 'tera', log = 8, lob_support = False)

Example 14: Create a context when password contains special characters

This example creates a context when password has special characters, and the example password "alice@pass" is encoded by default.

>>> td_context = create_context(host = 'tdhost', username='alice_pass', password = 'alice@pass')